API Reference
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",
},
channels: ["VIRTUAL_BANK_ACCOUNT"],
metadata: {
orderId: "order-456",
cartId: "cart-123",
},
});
// Redirect customer to session.checkoutUrl
console.log(session.checkoutUrl); // https://checkout.afriex.com/pay/...Response:
{
checkoutUrl: string; // Redirect customer here
}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[] | No | Allowed payment channels. Defaults to VIRTUAL_BANK_ACCOUNT |
metadata | object | No | Optional flat key/value metadata with string values |
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 - Receive webhook on your configured callback URL for session updates
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.
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.