Interswitch Webpay¶

Interswitch's IPG driver supports hosted Webpay, OTP authentication, recurring card charges, subscriptions, transfers, and payment links. API authentication uses OAuth 2.0 client credentials; the driver obtains and caches its token.

Setup¶

INTERSWITCH_CLIENT_ID=your_client_id
INTERSWITCH_CLIENT_SECRET=your_client_secret
INTERSWITCH_MERCHANT_CODE=your_merchant_code
INTERSWITCH_PAYABLE_CODE=your_payable_code
INTERSWITCH_TERMINAL_ID=your_terminal_id
INTERSWITCH_PASSPORT_URL=https://passport.interswitchng.com
INTERSWITCH_BASE_URL=https://api.interswitchgroup.com
INTERSWITCH_CHECKOUT_URL=https://webpay.interswitchng.com/collections/w/pay
INTERSWITCH_CALLBACK_URL=https://example.com/payment/callback
INTERSWITCH_WEBHOOK_SECRET=your_webhook_secret

Set sandbox or production URLs and merchant credentials as provided by Interswitch. Keep the client secret on the server.

Hosted checkout¶

use Alphabalex\PaymentMadeEasy\Facades\Payment;

$driver = Payment::driver('interswitch');
$checkout = $driver->initializePayment([
    'email'        => 'customer@example.com',
    'name'         => 'Jane Doe',
    'amount'       => 5000.00,
    'currency'     => '566', // numeric ISO 4217; 566 is NGN
    'reference'    => 'ORDER_123',
    'callback_url' => 'https://example.com/payment/callback',
]);

// Redirect to the returned paymentUrl.
$payment = $driver->verifyPayment('ORDER_123');

The public package amount is major units; the driver converts the request amount to kobo. The provider currency field uses an ISO 4217 numeric code, not NGN.

OTP and recurring cards¶

pay() can coordinate a payment response that requires OTP authentication. Supply a callable that obtains the OTP from your application, for example from a user interaction; the callback should return the code or null while waiting. Inspect the result status and handle completed, otp_required, 3ds_required, and failed appropriately.

The driver also exposes authenticateOtp(), tokenizeCard(), and chargeRecurring() for supported IPG workflows. Store tokens securely and use them only with customer authorization.

Additional capabilities and limitations¶

The shared contracts are payment, subscription, disbursement, and payment link. The driver does not implement the shared customer, virtual-account, balance, settlement, dispute, or split interfaces; some activities in those areas are dashboard-only. Use runtime capability checks before calling optional methods.

Webhooks¶

Configure POST /webhooks/payment-gateways/interswitch and the signing secret if the webhook product you use provides one. Follow the merchant integration's IPG callback guidance and requery transactions server-side. See webhook handling.

See Interswitch in the API reference for detailed OTP, tokenization, transfer, and subscription examples.