Skip to main content
POST
Afriex SDK
Want to see the hosted checkout end to end before you write any code? Try the sandbox demo, pick a currency and amount, and click Proceed to payment, no API key required.
Testing in sandbox? A checkout session’s underlying transaction settles automatically in about 5 minutes and triggers the same webhook and redirect behavior as a real payment (see How it works below). Pick the outcome with the payer’s last four digits (e.g. 0001 fails, 0002 triggers the mobile-money OTP page, 0003 stays pending until you call /simulate); add SIMULATE_INSTANT anywhere in merchantReference to settle in about 30 seconds. Sandbox sessions also enable in-page test-mode helpers (test-number hints, OTP hint, simulate-transfer button, pre-filled test card) so payers can drive outcomes without leaving the page. Full reference: Testing in Sandbox.

How it works

  1. Call this endpoint with the amount you want to collect, the customer’s details, your merchantReference, and a redirectUrl that starts with https://.
  2. Afriex returns a checkoutUrl and a checkoutId.
  3. Redirect the customer to that URL.
  4. When the payment succeeds or fails, Afriex redirects the customer back to your redirectUrl with status (success or failed), session_id, and merchant_reference added as query parameters.
  5. The payment itself is reported by Transaction Events on the deposit the session creates.
A checkout stays open for 24 hours by default. It closes when its payment is credited, so a paid checkout can’t be opened again. Afriex sends one checkout webhook, CHECKOUT_SESSION.CREATED, when you create the session. It says nothing about payment. Don’t treat the redirect as proof of payment either: confirm it from the transaction.

Identifying the session

The merchantReference you supply is the end-to-end identifier, and it must be unique. You can’t reuse it while an earlier checkout with that reference is still open, or after a transaction has used it. Both return 409. The checkoutId in the response is the last part of the checkoutUrl, and it is the sessionId in the CHECKOUT_SESSION.CREATED webhook, so use it to match that webhook to the checkout you created. There is no endpoint to fetch a session. To find the deposit a session created, call List Transactions with ?reference= set to your merchantReference.

Amounts are in minor units

amount is denominated in the smallest unit of the currency. For example, kobo for NGN or cents for USD. To charge ₦5,000.00, pass 500000. Minimum value is 100 (one major unit).

Choosing payment channels

channels is required and lists the deposit rails you are willing to offer the customer. Supported values are VIRTUAL_BANK_ACCOUNT, MOBILE_MONEY, and CARD; pass at least one.
Cards are hosted-checkout only. CARD is available here but not on Create Payment Method; to accept card payments, always route them through a checkout session.
Treat it as a cap, not an exact list. Afriex decides which channels the customer sees when they open the checkout page, once their currency is known. Channels the currency cannot collect on are dropped then, so you can send the same list on every corridor and let Afriex offer the right subset. For example, ["VIRTUAL_BANK_ACCOUNT", "MOBILE_MONEY", "CARD"] becomes mobile money for a KES checkout and cards for a USD one, all from one integration. The response returns channels as the list you sent. Creating a checkout does not narrow it.
Because the channels are decided when the customer opens the checkout page, creating a checkout does not fail when none of your channels suit the currency. Test each currency you support in sandbox.

Authorizations

x-api-key
string
header
required

Static business API key issued from the dashboard. A business can provision multiple API keys, each scoped to a configurable set of permissions (e.g. read transactions, create deposits, etc). Permissions are chosen per key at creation time in the dashboard and may be revoked by deleting the key. Manage your keys and their permissions under Developer → API keys in the dashboard.

A request whose key does not carry the permission the target endpoint requires is rejected with 401 Unauthorized, the same response an unrecognised, malformed, revoked or disabled key returns. The API does not distinguish the two cases on the wire.

See the Permissions reference for the permission each endpoint requires.

Headers

x-api-version
string

API version in ISO 8601 format. The only supported version is 2026-05-18, which is also the default when the header is omitted. Any other value is rejected with a 400 Bad Request.

Body

application/json
amount
integer
required

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

Required range: 100 <= x <= 9007199254740991
Example:

500000

currency
string
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.

Example:

"NGN"

merchantReference
string
required

Unique merchant-supplied reference for this session. Used end-to-end to look up the session and any resulting transaction.

Minimum string length: 1
Example:

"order-2026-05-12-001"

redirectUrl
string<uri>
required

HTTPS URL the customer is redirected to after the hosted checkout flow completes.

Pattern: ^https://
Example:

"https://merchant.example.com/checkout/return"

customer
object
required
channels
enum<string>[]
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).

Minimum array length: 1
Available options:
VIRTUAL_BANK_ACCOUNT,
MOBILE_MONEY,
CARD
metadata
object

Optional flat key/value metadata to attach to the session. Both keys and values must be strings. At most 50 entries; keys up to 128 characters, values up to 1024 characters.

Response

Checkout session created successfully.

data
object