Afriex SDK
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",
  },
  // 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

FieldTypeRequiredDescription
amountnumberYesAmount in minor currency units. Minimum value is 100
currencystringYesUppercase 3-letter ISO 4217 currency code, for example NGN
merchantReferencestringYesUnique merchant-supplied reference for the session
redirectUrlstringYesHTTPS URL to redirect the customer to after checkout
customer.namestringYesCustomer's full name
customer.emailstringYesCustomer's email address
customer.phonestringYesPhone number in E.164 format
customer.countryCodestringYesISO 3166-1 alpha-2 country code
channelsstring[]YesChannels 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
metadataobjectNoOptional flat key/value metadata with string values. At most 50 entries; keys up to 128 characters, values up to 1024

Session Flow

  1. Create session with amount, customer details, merchantReference, and redirectUrl
  2. Redirect customer to checkoutUrl
  3. Customer completes payment on Afriex-hosted page
  4. Afriex redirects the customer back to redirectUrl
  5. Track the payment through the TRANSACTION.UPDATED webhook 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.

On this page