Créer une session de paiement

Une session représente une intention de paiement. Vous la créez côté serveur, puis redirigez votre client vers la page de paiement hébergée par Cartflox, qui gère le choix de l’opérateur, la redirection Wave, les codes OTP Orange Money et la carte bancaire.

POST/v1/checkout/sessionsCréer une nouvelle session de paiement

Paramètres

Paramètre	Type	Requis	Description
`amount`	number	Oui	Montant, entier positif (5000 pour 5 000 XOF)
`currency`	string	Non	Code ISO 4217 : XOF (défaut), XAF, GHS, NGN, KES, TZS, UGX, RWF, ZMW, MWK, CDF, ETB, MZN, ZAR, EGP, MAD, GNF, SLE, LRD, GMD, MGA, MUR, USD, EUR, GBP. Les francs CFA, GNF, UGX, RWF, CDF et MGA n’ont pas de centimes.
`customer_name`	string	Non	Nom du client, pré-rempli sur la page de paiement
`customer_email`	string	Non	E-mail du client (reçu de paiement)
`customer_phone`	string	Non	Téléphone au format international (+225…), pré-rempli pour le Mobile Money
`description`	string	Non	Libellé affiché au client
`success_url`	string	Non	Adresse de retour après un paiement réussi
`cancel_url`	string	Non	Adresse de retour si le client abandonne
`metadata`	object	Non	Vos données libres (numéro de commande, identifiant client…), renvoyées dans les webhooks
`merchant_name`	string	Non	Nom affiché en tête de la page de paiement à la place du nom de votre espace (60 caractères au plus). Utile aux plateformes qui encaissent pour plusieurs marques.
`merchant_logo`	string	Non	Adresse `https` d’un logo affiché à la place de celui de votre espace (PNG, JPG ou SVG).

En-têtes

En-tête	Valeur
`Authorization`	`Bearer af_live_sec_...` (ou `x-api-key`) ; une clé `af_test_sec_...` crée une session de test
`Content-Type`	`application/json`
`Idempotency-Key`	Facultatif. Une chaîne unique par commande : si le même appel est rejoué, la session existante est renvoyée (HTTP 200 avec l’en-tête `Idempotent-Replayed: true`) au lieu d’en créer une deuxième.

Exemples

curl -X POST https://cartflox.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer af_live_sec_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-1042" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "customer_name": "Awa Koné",
    "customer_email": "awa@example.com",
    "customer_phone": "+2250700000000",
    "description": "Commande #1042",
    "success_url": "https://maboutique.com/merci",
    "cancel_url": "https://maboutique.com/panier",
    "metadata": { "order_id": "1042" },
    "merchant_name": "Ma Boutique",
    "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": "commande-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();
// Redirigez votre client vers la page de paiement :
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: commande-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": "commande-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"])  # redirigez votre client vers cette adresse

Réponse

{
  "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"
}

Champ	Description
`id`	Identifiant de la session, à conserver pour suivre le paiement
`url`	Page de paiement : redirigez votre client ici
`order_id`	Référence Cartflox lisible (`CS-...`)
`status`	`pending` à la création, voir les statuts
`livemode`	`true` avec une clé de production, `false` avec une clé de test (mode test)