Mode test

Chaque espace possède deux jeux de clés : un de production et un de test. Même API, mêmes routes, même page de paiement. Avec une clé de test, aucun agrégateur n’est appelé et aucun argent ne bouge : vous construisez et vérifiez votre intégration avant même que votre identité soit vérifiée.

Les deux jeux de clés

Production	Test	Rôle
`af_live_pub_...`	`af_test_pub_...`	Clé publique (widget, SoftPay) : créer une session et lire son statut
`af_live_sec_...`	`af_test_sec_...`	Clé secrète (serveur) : tout le reste, et la signature des webhooks

Les clés de test se trouvent dans API et Logs, sous les clés de production, et se régénèrent séparément. Tant que votre identité n’est pas vérifiée, votre espace reste en sandbox et seules les clés de test existent : une clé de production répondrait 403 avec le code identity_unverified. Après la vérification, les clés de production apparaissent et l’interrupteur Sandbox se déverrouille.

Ce qui se passe avec une clé de test

Vous créez une session comme d’habitude. La réponse porte "livemode": false.
La page de paiement affiche un bandeau « Mode test » et, après le choix du moyen et du numéro, propose deux boutons : simuler un paiement réussi ou simuler un échec. Si l’espace n’a encore aucune passerelle, un moyen fictif « Mobile Money (test) » est proposé pour dérouler le parcours.
La transaction passe en SUCCESS ou FAILED avec provider: "sandbox", et votre webhook reçoit payment.completed ou payment.failed exactement comme en production, avec "livemode": false.

curl -X POST https://cartflox.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer af_test_sec_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5000, "currency": "XOF", "customer_email": "test@example.com" }'

{
  "id": "cmu8a1b2c0001xyz",
  "object": "checkout.session",
  "url": "https://checkout.cartflox.com/cmu8a1b2c0001xyz",
  "order_id": "CS-MU8A1B-2C0X1",
  "amount": 5000,
  "currency": "XOF",
  "status": "pending",
  "livemode": false,
  "created": "2026-09-19T08:00:00.000Z"
}

Simuler l’issue sans ouvrir la page

Pour vos tests automatisés, l’issue se déclenche aussi par l’API, sans clé : l’identifiant de session, impossible à deviner, suffit.

POST/api/checkout/sandboxDénouer un paiement de test

curl -X POST https://cartflox.com/api/checkout/sandbox \
  -H "Content-Type: application/json" \
  -d '{ "transactionId": "cmu8a1b2c0001xyz", "issue": "succes" }'

issue vaut succes ou echec. La route refuse une transaction de production (HTTP 403) et une transaction déjà dénouée (HTTP 409).

Webhooks de test

Les événements de test vont à votre adresse de production, avec livemode: false, sauf si vous enregistrez une adresse de test distincte :

curl -X PATCH https://cartflox.com/api/v1/config/webhook \
  -H "Authorization: Bearer af_test_sec_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": "https://staging.maboutique.com/webhooks/cartflox", "mode": "test" }'

La signature d’un événement de test est calculée avec votre clé secrète de test. Vérifiez donc la signature avec la clé du même monde que l’événement (livemode).

Des données isolées

Les paiements de test n’apparaissent jamais dans vos listes, statistiques, exports ni notifications de production. Une clé de test ne lit que des sessions de test, et inversement.
Pour les consulter dans le tableau de bord : interrupteur « Sandbox » en haut de page. Il ne bloque jamais vos paiements réels : ce sont les clés qui font le monde d’un paiement. Un espace dont l’identité n’est pas encore vérifiée reste en sandbox, interrupteur verrouillé.
Les transactions de test sont effacées après 90 jours.

Limites du mode test

Ce qui n’est pas disponible	Pourquoi
Transferts d’argent (`POST /v1/transfers`)	Ils font sortir de l’argent : HTTP 403, code `test_mode`.
Liens de paiement (`POST /v1/payment-links`)	Un lien vit en production. Créez une session de test à la place.
Carte bancaire réelle	Le formulaire de carte n’est pas monté en mode test : simulez l’issue.