Create a payment session

A session represents a payment intent. You create it server-side, then redirect your customer to the payment page hosted by Cartflox, which handles the operator selection, the Wave redirect, Orange Money OTP codes and card payments.

POST/v1/checkout/sessionsCreate a new payment session

Parameters

Parameter	Type	Required	Description
`amount`	number	Yes	Amount, positive integer (5000 for 5,000 XOF)
`currency`	string	No	ISO 4217 code: XOF (default), XAF, GHS, NGN, KES, TZS, UGX, RWF, ZMW, MWK, CDF, ETB, MZN, ZAR, EGP, MAD, GNF, SLE, LRD, GMD, MGA, MUR, USD, EUR, GBP. CFA francs, GNF, UGX, RWF, CDF and MGA have no minor unit.
`customer_name`	string	No	Customer name, prefilled on the payment page
`customer_email`	string	No	Customer email (payment receipt)
`customer_phone`	string	No	Phone number in international format (+225…), prefilled for Mobile Money
`description`	string	No	Label shown to the customer
`success_url`	string	No	Return address after a successful payment
`cancel_url`	string	No	Return address if the customer gives up
`metadata`	object	No	Your own data (order number, customer ID…), returned in webhooks
`merchant_name`	string	No	Name shown at the top of the payment page instead of your workspace name (60 characters max). Useful for platforms collecting payments for several brands.
`merchant_logo`	string	No	`https` address of a logo shown instead of your workspace logo (PNG, JPG or SVG).

Headers

Header	Value
`Authorization`	`Bearer af_live_sec_...` (or `x-api-key`); an `af_test_sec_...` key creates a test session
`Content-Type`	`application/json`
`Idempotency-Key`	Optional. A unique string per order: if the same call is replayed, the existing session is returned (HTTP 200 with the `Idempotent-Replayed: true` header) instead of creating a second one.

Examples

curl -X POST https://cartflox.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer af_live_sec_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "customer_name": "Awa Koné",
    "customer_email": "awa@example.com",
    "customer_phone": "+2250700000000",
    "description": "Order #1042",
    "success_url": "https://maboutique.com/merci",
    "cancel_url": "https://maboutique.com/panier",
    "metadata": { "order_id": "1042" },
    "merchant_name": "My Store",
    "merchant_logo": "https://maboutique.com/logo.png"
  }'

const res = await fetch("https://cartflox.com/api/v1/checkout/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CARTFLOX_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-1042",
  },
  body: JSON.stringify({
    amount: 5000,
    currency: "XOF",
    customer_email: "awa@example.com",
    customer_phone: "+2250700000000",
    success_url: "https://maboutique.com/merci",
    cancel_url: "https://maboutique.com/panier",
    metadata: { order_id: "1042" },
  }),
});
const session = await res.json();
// Redirect your customer to the payment page:
res.ok ? redirect(session.url) : console.error(session.error);

$ch = curl_init("https://cartflox.com/api/v1/checkout/sessions");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("CARTFLOX_SECRET_KEY"),
    "Content-Type: application/json",
    "Idempotency-Key: order-1042",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "amount" => 5000,
    "currency" => "XOF",
    "customer_email" => "awa@example.com",
    "customer_phone" => "+2250700000000",
    "success_url" => "https://maboutique.com/merci",
    "cancel_url" => "https://maboutique.com/panier",
    "metadata" => ["order_id" => "1042"],
  ]),
]);
$session = json_decode(curl_exec($ch), true);
header("Location: " . $session["url"]);
exit;

import os, requests

r = requests.post(
    "https://cartflox.com/api/v1/checkout/sessions",
    headers={
        "Authorization": f"Bearer {os.environ['CARTFLOX_SECRET_KEY']}",
        "Idempotency-Key": "order-1042",
    },
    json={
        "amount": 5000,
        "currency": "XOF",
        "customer_email": "awa@example.com",
        "customer_phone": "+2250700000000",
        "success_url": "https://maboutique.com/merci",
        "cancel_url": "https://maboutique.com/panier",
        "metadata": {"order_id": "1042"},
    },
    timeout=15,
)
session = r.json()
print(session["url"])  # redirect your customer to this address

Response

{
  "id": "cmf3k2p1x0001abcd9e8f7g6h",
  "object": "checkout.session",
  "url": "https://checkout.cartflox.com/cmf3k2p1x0001abcd9e8f7g6h",
  "order_id": "CS-MF3K2A-9X1QZ",
  "amount": 5000,
  "currency": "XOF",
  "status": "pending",
  "livemode": true,
  "created": "2026-09-02T10:15:00.000Z"
}

Field	Description
`id`	Session identifier, keep it to track the payment
`url`	Payment page: redirect your customer here
`order_id`	Human-readable Cartflox reference (`CS-...`)
`status`	`pending` at creation, see the statuses
`livemode`	`true` with a production key, `false` with a test key (test mode)