AFafriex
Checkout Sessions

Create a checkout session

Creates a hosted checkout session for a customer and returns a checkoutUrl that the customer should be redirected to in order to complete payment. The session captures the merchant intent (amount, currency, merchant reference, customer details, and allowed payment channels).

The response carries the checkoutId and checkoutUrl directly, and no webhook is sent when a session is created. Track the payment with transaction events. Every transaction the customer's payment produces carries your merchantReference as merchantReference, and your metadata as meta, in transaction webhooks and in the transaction responses.

Available in sandbox and production. Create a session with a sandbox API key to try the full flow in test mode, and with a production API key to take real payments.

post/api/v1/checkout-session

Request

Request body

amountinteger required

The transaction amount in minor currency units (e.g. kobo for NGN, cents for USD). Minimum 100 (equivalent to 1 major currency unit).

currencystring required

3-letter ISO 4217 currency code (e.g. NGN, GHS). Must be one of the currencies enabled for checkout sessions: NGN, GHS, KES, UGX, TZS, ETB, XAF, XOF, SLE, USD.

merchantReferencestring required

Your own reference for this session, for example an order number. It is not required to be unique. It is returned as merchantReference on the transactions the customer's payment produces, so you can reconcile them with your order.

redirectUrlstring uri required

HTTPS URL the hosted checkout sends the customer to when they leave the success screen after paying. No query parameters are added to it.

namestring

Optional title of the session, at most 100 characters. Angle brackets and control characters are rejected.

descriptionstring

Optional description of what the customer is paying for.

channelsstring[] required

The payment channels you are willing to offer the customer, at least one. This is a cap, not an exact list: you do not need to vary it per country. The channels the customer is shown are decided when they open the checkout page, once their currency is known: channels it cannot collect on are dropped then, so the same list works for every country (send ["VIRTUAL_BANK_ACCOUNT", "MOBILE_MONEY", "CARD"] and a KES checkout offers mobile money while a USD one offers cards).

metadataobject

Optional flat key/value metadata to attach to the session. It is returned as meta on the transactions the customer's payment produces. Both keys and values must be strings. At most 50 entries; keys up to 128 characters, values up to 1024 characters.

Example request

{
  "amount": 500000,
  "currency": "NGN",
  "merchantReference": "order-2026-05-12-001",
  "redirectUrl": "https://merchant.example.com/checkout/return",
  "name": "Order 2026-05-12-001",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+2348192837465",
    "countryCode": "NG"
  }
}

Response

Checkout session created successfully.

Example response

{
  "data": {
    "checkoutId": "394102",
    "checkoutUrl": "https://pay.afriex.com/pay/394102",
    "channels": [
      "MOBILE_MONEY"
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.