Skip to main content
POST
/
api
/
v1
/
checkout-session
Afriex SDK
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);
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"
  }
}
'
import requests

url = "https://sandbox.api.afriex.com/api/v1/checkout-session"

payload = {
    "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"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://sandbox.api.afriex.com/api/v1/checkout-session', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.api.afriex.com/api/v1/checkout-session",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.api.afriex.com/api/v1/checkout-session"

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

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://sandbox.api.afriex.com/api/v1/checkout-session")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 500000,\n  \"currency\": \"NGN\",\n  \"merchantReference\": \"order-2026-05-12-001\",\n  \"redirectUrl\": \"https://merchant.example.com/checkout/return\",\n  \"customer\": {\n    \"name\": \"John Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"phone\": \"+2348192837465\",\n    \"countryCode\": \"NG\"\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://sandbox.api.afriex.com/api/v1/checkout-session")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 500000,\n  \"currency\": \"NGN\",\n  \"merchantReference\": \"order-2026-05-12-001\",\n  \"redirectUrl\": \"https://merchant.example.com/checkout/return\",\n  \"customer\": {\n    \"name\": \"John Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"phone\": \"+2348192837465\",\n    \"countryCode\": \"NG\"\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "data": {
    "checkoutUrl": "https://checkout.afriex.com/pay/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
  }
}
{
  "code": "<string>",
  "error": "<string>",
  "details": {
    "errorMessage": "<string>",
    "friendlyMessage": "<string>",
    "data": {
      "customerId": "<string>"
    }
  }
}
{
  "code": "<string>",
  "error": "<string>",
  "details": {
    "errorMessage": "<string>",
    "friendlyMessage": "<string>",
    "data": {
      "customerId": "<string>"
    }
  }
}
{
  "code": "<string>",
  "error": "<string>",
  "details": {
    "errorMessage": "<string>",
    "friendlyMessage": "<string>",
    "data": {
      "customerId": "<string>"
    }
  }
}
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).

​
Restricting payment channels

Use channels to control which deposit rails the hosted page offers the customer. Supported values are VIRTUAL_BANK_ACCOUNT, MOBILE_MONEY, and CARD; pass at least one. For example, ["CARD", "MOBILE_MONEY"] shows only the card and mobile-money options and hides the rest. If you omit channels, the session defaults to ["VIRTUAL_BANK_ACCOUNT"].

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. Requests made with a key that does not include the permission required by the target endpoint will be rejected with a 403 Forbidden response; an unrecognised, malformed or revoked key returns 401 Unauthorized. Manage your keys and their permissions under Developer → API keys in the dashboard.

Headers

​
x-api-version
string

API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest stable.

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.

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