Skip to main content
POST
/
api
/
v1
/
checkout-session
Create a checkout session
curl --request POST \
  --url https://sandbox.api.afriex.com/api/v1/checkout-session \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": 500000,
  "currency": "NGN",
  "merchantReference": "order-2026-05-12-001",
  "redirectUrl": "https://merchant.example.com/checkout/return",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+2348192837465",
    "countryCode": "NG"
  },
  "channels": [
    "VIRTUAL_BANK_ACCOUNT"
  ],
  "metadata": {}
}
'
{
  "data": {
    "checkoutUrl": "https://pay.afriex.com/pay/eyJhbGciOiJI..."
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.afriex.com/llms.txt

Use this file to discover all available pages before exploring further.

Coming soon. Hosted checkout is not yet generally available in production, but you can already try it end-to-end in the sandbox/staging environment today. Use sandbox to call this endpoint, see how it works, and validate your integration while we finish the production rollout, which we expect to ship in the coming weeks.
Create a hosted checkout session for a customer. Afriex returns a checkoutUrl that you redirect the customer to so they can complete payment on Afriex’s hosted page.

​
How it works

  1. Call this endpoint with the amount you want to collect, the customer’s details, your merchantReference, and a redirectUrl.
  2. Afriex returns a checkoutUrl.
  3. Redirect the customer to that URL.
  4. After payment, Afriex redirects the customer back to your redirectUrl and fires a CHECKOUT_SESSION.CREATED webhook to your configured callback URL.

​
Identifying the session

The merchantReference you supply is the end-to-end identifier. Use it to look up the session, match webhook deliveries, and reconcile any resulting transaction in your system. It must be unique per session.

​
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).

Authorizations

​
x-api-key
string
header
required

Static business API key from the dashboard

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: x >= 100
Example:

500000

​
currency
string
required

Uppercase 3-letter ISO 4217 currency code (e.g. NGN, GHS). Must be a currency enabled for checkout sessions on the business.

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.

Example:

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

​
customer
object
required
​
channels
enum<string>[]

Payment channels the customer is allowed to use for this session. Defaults to [VIRTUAL_BANK_ACCOUNT] if omitted.

Available options:
VIRTUAL_BANK_ACCOUNT,
MOBILE_MONEY
​
metadata
object

Optional flat key/value metadata to attach to the session. Both keys and values must be strings.

Response

Checkout session created successfully.

​
data
object