WooCommerce Integration

The BINKPAY WooCommerce plugin connects your WordPress store to both the BINKPAY Global and Egypt payment environments. Accept international cards, Apple Pay, and Google Pay worldwide, or enable Vodafone Cash, InstaPay, Fawry, ValU, and MeezaPay for Egyptian customers — all from a single plugin with full Arabic and RTL support.

Hosted Checkout

Cards · Apple Pay · Google Pay

Refunds sync

No code changes

Prerequisites

Before installing the BINKPAY plugin, confirm your environment meets the following minimum requirements:

Plugin Installation

The BINKPAY plugin is distributed as a ZIP file from the BINKPAY Dashboard. It is not currently available on the WordPress.org plugin directory.

Log in to dashboard.binkpay.net, navigate to Integrations → E-commerce Platforms → WooCommerce, and click Download Plugin (.zip). The downloaded file will be named binkpay-woocommerce-x.x.x.zip.

In your WordPress Admin, go to Plugins → Add New Plugin → Upload Plugin. Click Choose File, select the ZIP you downloaded, then click Install Now. WordPress will unpack and install the plugin files.

After installation completes, click Activate Plugin. The plugin will run its activation routine, which creates the required database tables for idempotency keys and webhook delivery logs.

Navigate to WooCommerce → Settings → Payments. You will see BINKPAY listed as a payment method. Click Set up next to the BINKPAY entry to open the configuration panel.

API Key Configuration

On the BINKPAY settings page (WooCommerce → Settings → Payments → BINKPAY → Manage), you will find fields for your API keys and environment selection. Enter your credentials exactly as they appear in the BINKPAY Dashboard under Developers → API Keys.

Keep your secret key out of version control

sk_live_...

sk_test_...

wp_options

wp-config.php

If you prefer to define API keys as constants rather than storing them in the database, add the following to your wp-config.php:

<?php
// BINKPAY API Keys
// These constants override the values saved in WooCommerce settings.
// Use sk_test_... / pk_test_... for staging, sk_live_... / pk_live_... for production.

define( 'BINKPAY_SECRET_KEY', 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' );
define( 'BINKPAY_PUBLISHABLE_KEY', 'pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' );
define( 'BINKPAY_WEBHOOK_SECRET', 'whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' );

// Set to 'egypt' to use the Egypt environment (api.binkpay.eg, EGP only)
// Set to 'global' for international payments (api.binkpay.net)
define( 'BINKPAY_ENVIRONMENT', 'global' );

// Enable test mode — overrides BINKPAY_ENVIRONMENT when true
// Set to false in production
define( 'BINKPAY_TEST_MODE', false );

Payment Methods

BINKPAY supports different payment methods depending on the environment configured in the plugin settings. Each environment maps to a different API endpoint.

Global Environment

API endpoint: https://api.binkpay.net  |   Supported currencies: USD, AED, EUR, GBP, SAR

Egypt Environment

API endpoint: https://api.binkpay.eg  |   Supported currency: EGP only

Arabic & RTL Support

The BINKPAY plugin ships with a full Arabic translation and automatically detects when WordPress is set to Arabic (ar) or any Arabic locale. When RTL is active, the payment form and all BINKPAY UI elements are mirrored to display correctly in right-to-left reading order.

If your theme does not fully support RTL or you need to fine-tune the BINKPAY payment form's RTL styles, you can inject custom CSS via the binkpay_rtl_styles filter:

<?php
/**
 * Customize BINKPAY payment form RTL styles.
 * This filter fires only when is_rtl() returns true.
 */
add_filter( 'binkpay_rtl_styles', function( string $css ): string {
 $custom = <<<CSS
 /* BINKPAY card input: align placeholder text to the right */
 .binkpay-card-element {
 direction: rtl;
 text-align: right;
 }

 /* Right-align the card number, expiry, and CVV labels */
 .binkpay-field-label {
 display: block;
 text-align: right;
 font-family: 'Cairo', 'Tajawal', sans-serif;
 font-size: 14px;
 margin-bottom: 4px;
 color: #333;}

 /* Flip the card brand icon to the left side in RTL */
 .binkpay-card-brand-icon {
 float: left;
 margin-left: 0;
 margin-right: 8px;
 }

 /* Ensure error messages align right */
 .binkpay-error-message {
 text-align: right;
 direction: rtl;
 }
 CSS; return$css . $custom;
} );

/**
 * Load Arabic font ifthe site is in RTL mode and BINKPAY is on the page.
 */
add_action( 'wp_enqueue_scripts', function (): void {
 if ( ! is_rtl() ) {
 return;
 }
 if( ! is_checkout() && ! is_cart() ) { return;
 }
 wp_enqueue_style( 'binkpay-arabic-fonts',
 'https://fonts.googleapis.com/css2?family=Cairo:wght@400;600&family=Tajawal:wght@400;500&display=swap',
 [],
 null
 );
} );

Refund Handling

BINKPAY supports both full and partial refunds, initiated either from the WordPress Admin or programmatically via WooCommerce hooks.

Refund via WordPress Admin

1. Go to WooCommerce → Orders and open the order you want to refund.
2. Scroll to the Order Items section and click Refund.
3. Enter the refund amount (or quantities per line item for a partial refund) and optionally provide a reason for your records.
4. Click Refund EGP X.XX via BINKPAY (the button label reflects the order currency). BINKPAY will process the refund immediately and update the order status to Refunded or Partially Refunded.

Programmatic Refunds

Use the WooCommerce wc_create_refund() function to trigger a BINKPAY refund from code. The plugin hooks into WooCommerce's standard refund pipeline, so no BINKPAY-specific API calls are needed from your code:

my-plugin/refund-handler.php

<?php
/**
 * Issue a partial refund on a WooCommerce order backed by BINKPAY.
 *
 * @param int $order_id The WooCommerce order ID.
 * @param float $refund_amount Amount to refund in the order 's currency.
 * @param string $reason Optional reason shown in order notes.
 */
function my_plugin_refund_order( int $order_id, float $refund_amount, string $reason = ' ' ): void {
 $order = wc_get_order( $order_id );

 if ( ! $order ) {
 throw new InvalidArgumentException( "Order {$order_id} not found." );
 }

 if ( $order->get_payment_method() !== 'binkpay ' ) {
 throw new RuntimeException( 'Order was not paid via BINKPAY. ' );
 }

 $max_refundable = (float) $order->get_remaining_refund_amount();

 if ( $refund_amount > $max_refundable ) {
 throw new RuntimeException(
 "Cannot refund {$refund_amount} — only {$max_refundable} {$order->get_currency()} remaining."
 );
 }

 $refund = wc_create_refund( [
 'amount ' => $refund_amount,
 'reason ' => $reason,
 'order_id ' => $order_id,
 'refund_payment ' => true, // This triggers the BINKPAY gateway's process_refund() method
 ] ); if( is_wp_error( $refund ) ) {
 throw newRuntimeException( $refund->get_error_message() );
 } // $refund is a WC_Order_Refund instance$binkpay_refund_id = $refund->get_meta( '_binkpay_refund_id' );
 error_log( "BINKPAY refund created: {$binkpay_refund_id} for order {$order_id}" );
}

// Example usage: refund $25.00 on order 1234my_plugin_refund_order( 1234, 25.00, 'Customer requested size exchange' );

Webhook Configuration

BINKPAY sends signed webhook events to your WordPress site to notify it of payment outcomes, refunds, and disputes. The plugin automatically registers a webhook endpoint during activation at:

https://your-store.com/?wc-api=binkpay_webhook

To find or reset your webhook secret, go to WooCommerce → Settings → Payments → BINKPAY → Manage → Webhook Settings. You can also configure the webhook URL directly in the BINKPAY Dashboard under Developers → Webhooks → Add endpoint.

The plugin handles signature verification internally. If you are building a custom integration or a headless WordPress setup, here is how to verify BINKPAY webhook signatures in Node.js (for a decoupled frontend that proxies webhooks):

import crypto from 'crypto';

interface BinkpayWebhookEvent {
 id: string;
 type: string;
 created_at: string;
 data: Record<string, unknown>;
 livemode: boolean;
}

/**
 * Verify a BINKPAY webhook signature and parse the payload.
 * Throws ifthe signature is invalid.
 */ functionverifyBinkpayWebhook(
 rawBody: string,
 signatureHeader: string,
 webhookSecret: string
): BinkpayWebhookEvent { constexpectedSig = crypto
 .createHmac( 'sha256', webhookSecret)
 .update(rawBody, 'utf8')
 .digest( 'hex');

 const sigBuffer = Buffer. from(signatureHeader, 'hex');
 constexpectedBuffer = Buffer. from(expectedSig, 'hex');

 if(
 sigBuffer.length !== expectedBuffer.length ||
 !crypto.timingSafeEqual(sigBuffer, expectedBuffer)
 ) {
 throw new Error( 'BINKPAY webhook signature verification failed');
 }

 returnJSON.parse(rawBody) as BinkpayWebhookEvent;
} // Express.js handler example
// Requires: app.use('/api/binkpay-webhook', express.raw({ type: '*/*' }))
export async functionbinkpayWebhookHandler(req: Request, res: Response): Promise<void> { constrawBody = req.body.toString( 'utf8');
 constsignature = req.headers[ 'binkpay-signature'] as string;

 letevent: BinkpayWebhookEvent;
 try {
 event = verifyBinkpayWebhook(rawBody, signature, process.env.BINKPAY_WEBHOOK_SECRET!);
 } catch (err) {
 res.status( 401).json({ error: 'Invalid signature' });
 return;
 }

 switch (event.type) {
 case 'payment.succeeded':
 console.log( `Payment succeeded: ${event.data.id}`);
 // Trigger WooCommerce order completion via REST API if needed
 break;
 case 'payment.failed':
 console.warn( `Payment failed: ${event.data.id}`, event.data.failure_reason);
 break;
 case 'refund.created':
 console.log( `Refund ${event.data.id}: ${event.data.amount} ${event.data.currency}`);
 break;
 case 'dispute.created':
 console.warn( `Dispute opened on payment ${event.data.payment_id}`);
 break;
 case 'payout.completed':
 console.log( `Payout ${event.data.id} completed`);
 break;
 default:
 console.log( `Unhandled BINKPAY event: ${event.type}`);
 }

 res.status( 200).json({ received: true });
}

Test Mode

Use the following test credentials to simulate various payment scenarios in WooCommerce checkout:

To test Egypt-specific payment methods (Vodafone Cash, Fawry, InstaPay) in sandbox mode, set the environment to Egypt (test) in the plugin settings and use the test phone number 01000000000 for wallet-based methods. Fawry test references resolve instantly in sandbox without requiring a physical payment.

Troubleshooting

BINKPAY does not appear on the WooCommerce Payments settings page

This typically means the plugin is installed but WooCommerce cannot load it due to a PHP version mismatch or a missing extension. Go to Plugins → Installed Plugins and confirm BINKPAY for WooCommerce shows as Active with no error notice. If there is a fatal error, enable WP_DEBUG in wp-config.php and check wp-content/debug.log for the root cause. The most common cause is PHP below 8.1.

Egypt payment methods (Vodafone Cash, Fawry, etc.) are not showing at checkout

Egypt payment methods only render when three conditions are all true: (1) the plugin environment is set to Egypt, (2) the WooCommerce store currency isEGP (set under WooCommerce → Settings → General → Currency), and (3) the customer's cart total is within the method's allowed range (for example, ValU requires a minimum order of EGP 500). Check all three before investigating further.

Refund button in WooCommerce Admin returns "BINKPAY refund failed: charge already refunded"

This error means a refund was already issued on the BINKPAY side — either via the BINKPAY Dashboard directly or by a previous refund attempt that did not update the WooCommerce order status correctly. Log in to the BINKPAY Dashboard, find the charge by the order's BINKPAY payment ID (visible in the order's meta under Order → BINKPAY Payment ID), and verify the refund state. If the charge is fully refunded, manually update the WooCommerce order status to Refunded.

Webhooks are not being received — orders stay in "Pending payment" after checkout

First, confirm the webhook endpoint is publicly reachable. In the BINKPAY Dashboard under Developers → Webhooks, click the endpoint URL and use theSend test event button. If BINKPAY reports a delivery failure, check that your server is not blocking POST requests from BINKPAY's IP ranges, and that WordPress permalink structure is set to anything other than Plain (plain permalinks break the wc-api query parameter routing). Go to Settings → Permalinks and save to flush rewrite rules.

Apple Pay / Google Pay express buttons do not appear on the cart or product pages

Express payment buttons require the WooCommerce Blocks plugin (bundled with WooCommerce 8.0+) and your cart/checkout pages must use the WooCommerce Cart Block and Checkout Block, not the legacy shortcode-based pages. Verify by editing your Cart page in the block editor — it should contain the Cart Block, not the [woocommerce_cart] shortcode. Additionally, Apple Pay requires Safari on an Apple device and a verified domain. See the domain verification instructions in the Shopify integration guide

— the same domain registration API applies to WooCommerce.