Documentation CashChap

Premiers pas en cinq étapes

1. Créez votre compte marchand sur cashchap.com et confirmez votre adresse e-mail. Voir l'inscription.
2. Testez sans argent réel avec la clé Sandbox. Chaque service a une clé publique et une clé secrète Sandbox ; les paiements y sont simulés selon le numéro saisi. Voir le mode test.
3. Activez votre compte (KYC) en trois étapes depuis le portail : promoteur, entreprise, immatriculation. Les clés Live n'encaissent qu'une fois le dossier validé. Voir l'activation.
4. Intégrez CashChap avec le moyen qui vous convient : SDK JavaScript (une balise), API v2, lien de paiement CashChap Link, terminal de paiement ou encaissement en boutique depuis le portail.
5. Confirmez chaque paiement côté serveur avec GET /v2/transactions/{id} et votre clé secrète, ou un webhook signé, puis livrez. Voir la confirmation.

Choisir son mode d'intégration

Votre premier paiement en mode test

Avec votre clé secrète Sandbox (menu Développeurs › Clés API du portail), demandez un encaissement Mobile Money de 1 000 XOF sur le numéro de test MTN Bénin 2290166000000 (format international, sans « + »), qui simule un succès en cinq secondes environ :

curl -X POST https://api.cashchap.com/v2/collections \
  -H "Authorization: Bearer VOTRE_CLE_SECRETE_SANDBOX" \
  -H "Idempotency-Key: cmd-2026-00417-essai-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "XOF",
    "provider": "mtn-benin",
    "phone": "2290166000000",
    "customer": { "name": "Afi Dossou", "email": "afi.dossou@example.com" },
    "reference": "CMD-2026-00417"
  }'

CashChap répond tout de suite 202 : la transaction existe, en attente de la validation du client sur son téléphone. Le total payé par le client (amount_charged) comprend ici les frais à sa charge et l'arrondi au 5 F supérieur.

HTTP/1.1 202 Accepted
Location: /v2/transactions/7c9e6679-7425-40de-944b-e07fc1f90ae7

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "object": "transaction",
    "type": "collection",
    "status": "pending",
    "pending_reason": "awaiting_provider",
    "mode": "sandbox",
    "channel": "api",
    "reference": "CMD-2026-00417",
    "amount": 1000,
    "currency": "XOF",
    "amount_charged": 1020,
    "charged_currency": "XOF",
    "fees": { "amount": 20, "currency": "XOF", "payer": "customer", "rule": { "kind": "percentage", "value": 1.7, "level": "platform", "channel": null, "terminal": null } },
    "net_amount": 1000,
    "net_currency": "XOF",
    "...": "autres champs de l'objet transaction"
  },
  "meta": { "request_id": "req_01JA2Q8X3T9Z0F6V4M2K7C1B5N" }
}

Lisez ensuite la transaction jusqu'à un statut final (succeeded, failed, expired ou cancelled). Le paramètre wait fait patienter la réponse quelques secondes si la transaction est encore en attente :

curl "https://api.cashchap.com/v2/transactions/7c9e6679-7425-40de-944b-e07fc1f90ae7?wait=5" \
  -H "Authorization: Bearer VOTRE_CLE_SECRETE_SANDBOX"

En mode test, remplacez les deux derniers chiffres du numéro par un code de scénario : 2290166000012 simule par exemple un solde insuffisant (insufficient_funds).

Les deux environnements

Adresses à connaître

Parcourir la documentation

• Comptes et KYCInscription, activation du compte marchand en trois étapes (KYC), services multiples, collaborateurs et rôles.
• Portail marchandLes menus du portail marchand CashChap : tableau de bord, paiements, argent, clients, boutique, développeurs, compte.
• PaiementsMobile Money (MTN, Moov), cartes, choix automatique de l'opérateur, cycle de vie et statuts d'une transaction.
• Frais et devisesCommissions, qui paie les frais, total arrondi au 5 F supérieur, frais de change de 1 %, devis, devise du service pour vos clients et pour vous, taux par terminal.
• Fonds et retraitsSoldes, mise à disposition des fonds, vérifications et gel, retraits Mobile Money et virements bancaires.
• RemboursementsRembourser un paiement : remboursement total hors frais, 30 jours, validation par CashChap, webhooks refund.*.
• Reçus et vérificationReçu détaillé, facture PDF et QR code d'authentification : la page publique cashchap.com/verifier confirme qu'un paiement est authentique.
• API v2Référence de l'API REST CashChap v2 : authentification, enveloppes, idempotence, encaissements, transactions, retraits.
• SDK JavaScriptBouton de paiement CashChap avec le SDK JavaScript 2.0 : CashChap.checkout, élément cashchap-checkout, événements.
• WidgetLe formulaire de paiement hébergé par CashChap : parcours du client, affichage, sécurité, politique de sécurité du contenu.
• CashChap LinkLiens de paiement CashChap Link : encaisser sans site web, montant fixe ou libre, API publique des liens, mode Sandbox.
• QR codesPaiements par QR code : QR de chaque CashChap Link, QR fixe de la boutique (comptoir) et QR à usage unique de la caisse, affiches à imprimer, API /v2/checkouts.
• Terminaux de paiementTerminaux de paiement (TPE) et caisses : création, code d'activation, clé de terminal, sessions de caisse, taux par terminal.
• WebhooksNotifications de paiement, de retrait et de remboursement : événements, signature HMAC, déchiffrement, relances.
• Sandbox et testsMode test CashChap : clé Sandbox, numéros de test 2290166000000 (succès) et 2290166000012 (solde insuffisant), scénarios simulés.
• Erreurs de l'API v2Tous les codes d'erreur de l'API v2 (error.code), avec leur type, leur statut HTTP et la conduite à tenir.
• Codes internes (Exxx)Les codes Exxx de CashChap (webhooks, journaux d'API) et leur équivalent dans l'API v2.
• v1 retirée : migrer à la v2L'API v1 et le SDK 1.x sont retirés (410 Gone) : équivalent v2 des routes, en-têtes, champs, statuts, erreurs et SDK.
• Spécification OpenAPILa spécification OpenAPI 3.1 de l'API CashChap v2 (openapi/v2.yaml), pour générer un client ou importer dans un outil.
• Journal des changementsLes versions publiées de l'API CashChap v2 (en-tête CashChap-Version) et du SDK JavaScript, de la plus récente à la plus ancienne.
• FAQQuestions fréquentes des marchands et des développeurs CashChap.