Checkout API
Create hosted payment sessions. Afriex handles the payment UI; you redirect customers to complete the transaction.
Create Checkout Session
const session = await afriex.checkout.createSession({
amount: 500000,
currency: "NGN",
merchantReference: "order-2026-05-12-001",
redirectUrl: "https://yourapp.com/checkout/return",
customer: {
name: "John Doe",
email: "john@example.com",
phone: "+2348192837465",
countryCode: "NG",
},
// A cap, not an exact list: channels the currency cannot collect on are dropped
channels: ["VIRTUAL_BANK_ACCOUNT", "MOBILE_MONEY", "CARD"],
metadata: {
orderId: "order-456",
cartId: "cart-123",
},
});
// Redirect customer to session.checkoutUrl
console.log(session.checkoutUrl); // https://pay.afriex.com/pay/...
// The channels the payer will actually be offered
console.log(session.channels); // ["VIRTUAL_BANK_ACCOUNT", "CARD"]Response:
{
checkoutUrl: string; // Redirect customer here
channels?: ("VIRTUAL_BANK_ACCOUNT" | "MOBILE_MONEY" | "CARD")[]; // What the payer will be offered
}Parameters
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Amount in minor currency units. Minimum value is 100 |
currency | string | Yes | Uppercase 3-letter ISO 4217 currency code, for example NGN |
merchantReference | string | Yes | Unique merchant-supplied reference for the session |
redirectUrl | string | Yes | HTTPS URL to redirect the customer to after checkout |
customer.name | string | Yes | Customer's full name |
customer.email | string | Yes | Customer's email address |
customer.phone | string | Yes | Phone number in E.164 format |
customer.countryCode | string | Yes | ISO 3166-1 alpha-2 country code |
channels | string[] | Yes | Channels you are willing to offer; must be non-empty. Any of VIRTUAL_BANK_ACCOUNT, MOBILE_MONEY, CARD. Ones the currency does not support are dropped |
metadata | object | No | Optional flat key/value metadata with string values. At most 50 entries; keys up to 128 characters, values up to 1024 |
Session Flow
- Create session with amount, customer details,
merchantReference, andredirectUrl - Redirect customer to
checkoutUrl - Customer completes payment on Afriex-hosted page
- Afriex redirects the customer back to
redirectUrl - Track the payment through the
TRANSACTION.UPDATEDwebhook on the transaction the session produces
amount is denominated in minor units. For example, to charge NGN 5,000.00,
send 500000.
Use merchantReference as your end-to-end identifier for lookup,
reconciliation, and webhook matching. Reusing one that is still active returns
409 DUPLICATE_REQUEST.
CHECKOUT_SESSION.CREATED fires when the session is created. It is not a
payment signal.
Checkout is available in the sandbox only for now. Production answers 403
until Afriex enables it for your business.
Use Cases
Immediate payment collection
Customer pays now; funds settle to your balance.
Delayed payment processing
Create session in advance; send link to customer later.
Embedded checkout
Open checkoutUrl in iframe or webview for in-app payment.