Sandbox et tests

Le mode test (Sandbox) reproduit toute la chaîne de paiement sans opérateur réel ni mouvement d'argent. Vous y testez l'API v2, le SDK, le widget, les liens de paiement, les terminaux, les retraits et les webhooks, avec des scénarios choisis par le numéro de téléphone.

Utiliser le mode test

1. Prenez les clés Sandbox du service dans Développeurs › Clés API, environnement Sandbox (clé publique PKSANDBOX_…, clé secrète SKSANDBOX_…). Aucune validation KYC n'est requise.
2. Utilisez-les exactement comme les clés Live : mêmes adresses, mêmes champs, mêmes erreurs. Les transactions portent "mode": "sandbox".
3. Consultez les transactions de test en basculant le portail sur l'environnement Sandbox (bouton Sandbox / Live, en haut à droite) : elles sont stockées à part, jamais mélangées aux transactions Live, et purgées périodiquement.
4. Déclarez un webhook Sandbox pour tester vos notifications sans toucher au webhook Live.

Numéros de test

Un numéro de test se compose du préfixe de l'opérateur, de zéros, puis d'un code de scénario à deux chiffres, soit 10 chiffres de numéro national au Bénin, écrits au format international, sans « + » : l'indicatif 229 devant, soit 13 chiffres en tout (2290166000000). La règle vaut pour tout opérateur : indicatif, préfixe de l'opérateur, zéros, puis le code. Les numéros à retenir :

L'ancien format béninois reste accepté avec l'indicatif : 22966000012 devient 2290166000012. Un numéro sans indicatif (0166000000) est refusé avec phone_international_required, comme en Live. Dans la page de paiement, le payeur tape seulement la partie nationale (01 66 00 00 00) à côté de l'indicatif affiché +229. Tout autre numéro valide pour l'opérateur réussit en environ 5 secondes ; un numéro dont le préfixe est inconnu est refusé à l'entrée comme en Live (invalid_phone_number).

Les montants restent libres : les plafonds, les devises, les frais et l'arrondi sont calculés comme en production. Le choix automatique de l'opérateur ("provider": "auto") fonctionne aussi avec les numéros de test.

Scénarios

Les deux derniers chiffres du numéro choisissent le scénario :

• Un code d'échec qui ne concerne pas l'opération (par exemple 12 sur un retrait) donne un succès rapide.
• Le code 09 est refusé par l'opérateur simulé dès la demande ; les autres échecs surviennent après le délai, comme un vrai refus du client.
• Pendant le délai, le statut est pending : c'est le moment de tester votre suivi (?wait=5), vos écrans d'attente et onPending du SDK.
• Le code de la raison (failure.code) est celui de l'API v2 ; le code Exxx entre parenthèses est celui des webhooks et de vos journaux d'API.

Exemple complet

# 1. Encaissement qui échouera pour solde insuffisant (code 12) après ~5 s
curl -X POST https://api.cashchap.com/v2/collections \
  -H "Authorization: Bearer VOTRE_CLE_SECRETE_SANDBOX" \
  -H "Idempotency-Key: essai-solde-insuffisant-1" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1000, "currency": "XOF", "provider": "mtn-benin", "phone": "2290166000012",
        "customer": { "name": "Test Solde", "email": "test@example.com" } }'

# 2. Lecture avec attente : la réponse revient dès le statut final (5 s au plus)
curl "https://api.cashchap.com/v2/transactions/4e1d2c3b-5a69-4b8c-9d0e-1f2a3b4c5d6e?wait=5" \
  -H "Authorization: Bearer VOTRE_CLE_SECRETE_SANDBOX"

{
  "data": {
    "id": "4e1d2c3b-5a69-4b8c-9d0e-1f2a3b4c5d6e",
    "object": "transaction",
    "status": "failed",
    "mode": "sandbox",
    "failure": { "code": "insufficient_funds", "message": "Le solde Mobile Money du client est insuffisant." },
    "...": "autres champs identiques au Live"
  },
  "meta": { "request_id": "req_…" }
}

Retraits, virements et remboursements en mode test

Les retraits Mobile Money de test suivent les mêmes scénarios (codes 20 à 29) vers un numéro autorisé de l'environnement Sandbox, avec la clé secrète Sandbox. Les virements bancaires ne sont pas simulés. Les remboursements de test sont simulés et validés automatiquement.

Factures de test

Les factures PDF des transactions de test portent le préfixe TS au lieu de CS, afin de ne jamais être confondues avec des factures réelles. Elles portent aussi le bandeau « MODE TEST (Sandbox) : aucun argent réel n'a été débité. Ce document ne prouve aucun paiement. », et le QR code de leur reçu mène à la page de vérification « Paiement de test » (voir Reçus et vérification).

Liste de recette avant la mise en production

• Paiement réussi (00), refusé (10), solde insuffisant (12), délai dépassé (02, statut expired) : votre site réagit correctement à chaque cas et affiche failure.message.
• Attente longue (01, 03) : vos écrans et votre suivi tiennent plusieurs minutes.
• Coupure réseau simulée : la même requête rejouée avec la même Idempotency-Key ne crée pas de seconde transaction.
• Même reference envoyée deux fois : 409 duplicate_reference géré.
• Webhook Sandbox reçu, signature vérifiée, charge déchiffrée, traitement sans doublon.
• Page de retour du SDK : confirmation côté serveur avant tout message de succès.
• Remplacement des clés Sandbox par les clés Live et du webhook de test par le webhook Live.