Mettre un bouton "Payer" en ligne sans l avoir teste, c est promettre a vos clients une experience que vous n avez jamais vue fonctionner. Au Senegal, ou le paiement passe par Wave, Orange Money, Free Money et des agregateurs comme PayDunya, CinetPay ou Hub2, chaque integration a ses propres pieges. Un sandbox bien utilise vous evite de decouvrir les bugs avec de l argent reel et des clients mecontents.
Ce guide explique comment tester un paiement mobile money de bout en bout : quels environnements existent, quels numeros de test utiliser, quels scenarios couvrir, et comment basculer en production sans tout casser.
Pourquoi tester en sandbox est non negociable
Un paiement mobile money n est pas un simple appel API qui repond instantanement. C est une chaine : votre serveur appelle l agregateur, qui contacte l operateur, qui envoie un push USSD ou une notification au telephone du client, qui valide avec son code PIN, et la confirmation revient par un webhook asynchrone parfois plusieurs secondes plus tard.
Chaque maillon peut echouer. Le client peut refuser, ne pas avoir de solde, taper un mauvais PIN, ou simplement ne jamais voir le push. Si vous testez seulement le "cas heureux" en production, vous ne saurez pas ce que voit votre client quand ca rate. Le sandbox vous laisse rejouer tous ces cas a volonte, sans bouger un seul franc CFA.
Ce que le sandbox reproduit vraiment
Un bon environnement de test simule les reponses de l operateur : succes, echec, solde insuffisant, timeout, annulation utilisateur. Il vous donne aussi des webhooks de test pour valider que votre back-end reagit correctement. Ce qu il ne simule pas toujours bien : la latence reelle du reseau au Senegal et le comportement exact du push USSD sur les vieux telephones. Gardez cette limite en tete.
Les environnements de test des principaux acteurs
Au Senegal, vos integrations passent presque toujours par un agregateur plutot que directement par l operateur. Voici le panorama.
PayDunya
PayDunya fournit un mode test active par une simple cle d API differente (la cle commence par "test_" au lieu de "live_"). Vous creez une transaction comme en prod, mais aucun debit reel n a lieu. La plateforme renvoie des statuts simules que vous pouvez forcer. C est l un des plus simples a prendre en main pour un projet senegalais.
CinetPay
CinetPay propose un compte de test distinct du compte de production, avec ses propres identifiants (site_id et apikey). Les montants sont fictifs et vous pouvez declencher les differents codes de retour. Pensez a bien separer vos variables d environnement entre test et prod, car un melange de cles est la premiere cause d incident au passage en live.
Hub2
Hub2 expose une API unifiee multi-operateurs avec un environnement sandbox documente. C est utile quand vous voulez accepter Wave, Orange Money et MTN sans integrer chaque operateur separement. Le sandbox renvoie des numeros et reponses de test pour chaque methode.
Orange Money et Wave en direct
Orange Money Web Payment dispose d un environnement de developpement avec des numeros de test et un parcours de validation simule. Wave, de son cote, privilegie une integration via lien de paiement ou checkout ; son environnement de test est plus restreint, raison de plus pour passer par un agregateur si vous voulez un sandbox riche.
Numeros et donnees de test
Chaque agregateur publie des numeros de test dans sa documentation. Ne les inventez pas : un numero aleatoire renverra une erreur generique qui ne vous apprend rien. Les numeros officiels declenchent des comportements precis.
Typiquement vous trouverez :
- Un numero qui renvoie toujours un succes.
- Un numero qui renvoie toujours un echec (refus operateur).
- Un numero qui simule un solde insuffisant.
- Un numero qui ne repond jamais, pour tester votre timeout.
Notez ces numeros dans votre documentation interne. Vos developpeurs et votre QA doivent pouvoir rejouer un echec en dix secondes sans chercher.
Les scenarios a couvrir absolument
Tester uniquement le paiement reussi est l erreur classique. Voici la matrice minimale.
1. Paiement reussi
Le cas nominal. Verifiez que le webhook de confirmation arrive, que la commande passe au statut "payee", que le recu part, et que le client voit une page de succes claire.
2. Paiement refuse
L operateur rejette. Verifiez que la commande reste en attente ou passe en "echec", que le client voit un message comprehensible (pas un code technique), et qu il peut reessayer.
3. Solde insuffisant
Tres frequent au Senegal. Le message doit etre explicite : "Solde insuffisant, rechargez votre compte." Surtout, ne marquez pas la commande comme payee.
4. Timeout / pas de reponse
Besoin d'un site web professionnel ?
Kolonell crée des sites web qui attirent des clients, optimisés pour le marché sénégalais. Devis gratuit en 2 minutes.
Le client n a jamais valide le push. Votre systeme doit attendre un delai raisonnable puis marquer la transaction "expiree", sans la perdre. C est ici que l idempotence compte.
5. Double soumission
Le client clique deux fois sur "Payer". Vous devez generer une cle d idempotence par tentative pour ne jamais debiter deux fois. Testez-le explicitement.
6. Webhook en double ou en retard
Les agregateurs renvoient parfois le meme webhook plusieurs fois. Votre back-end doit traiter le premier et ignorer les suivants pour la meme transaction.
Mini cas client : un site de livraison a Dakar
Une boutique de plats prepares livrant a Dakar nous a contactes apres un lancement rate. En production directe, sans sandbox, 18 % de leurs commandes restaient bloquees en "en attente de paiement" alors que le client avait bien paye. Le webhook arrivait, mais leur code le traitait avant que la commande soit enregistree, et le rapprochait a un identifiant vide.
Nous avons rejoue le scenario dans le sandbox CinetPay : webhook recu sur une commande inexistante, puis re-reception 30 secondes plus tard. Le correctif a ete de stocker la transaction des l initiation, d utiliser la reference de commande comme cle, et de rendre le traitement du webhook idempotent. Apres deploiement, le taux de commandes bloquees est tombe sous 1 %. Tout cela a ete valide en sandbox avant la moindre transaction reelle.
Passer en production sans casse
Le passage en live est le moment ou tout peut deraper. Quelques regles.
Separez strictement vos cles
Cles test et cles live ne doivent jamais cohabiter dans le meme fichier sans distinction claire. Utilisez des variables d environnement et verifiez au demarrage que vous chargez bien le bon jeu selon l environnement.
Faites une transaction reelle de faible montant
Avant d ouvrir au public, passez une vraie commande a 100 FCFA avec votre propre numero. Verifiez le debit, le webhook, le recu, la page de succes. Remboursez-vous ensuite. C est votre dernier filet de securite.
Surveillez les premieres 24 heures
Mettez en place des alertes sur les transactions qui restent "en attente" trop longtemps. Les premieres heures revelent les cas que le sandbox n a pas couverts.
Checklist developpeur
Avant de declarer un paiement "pret pour la prod" :
- Les cles test et live sont separees et chargees selon l environnement.
- Les six scenarios (succes, refus, solde insuffisant, timeout, double clic, webhook double) sont testes en sandbox.
- L idempotence empeche tout double debit.
- Le webhook est verifie (signature) et idempotent.
- Les messages d erreur sont en langage clair, pas des codes techniques.
- Une transaction reelle de faible montant a ete validee de bout en bout.
- Des alertes existent sur les transactions bloquees.
FAQ
Le sandbox est-il vraiment fidele a la production ?
Il est fidele pour la logique (statuts, webhooks, codes de retour) mais pas toujours pour la latence reseau ni le comportement du push USSD sur les vieux telephones. C est pourquoi une transaction reelle de faible montant reste indispensable avant l ouverture.
Quel agregateur offre le sandbox le plus simple au Senegal ?
PayDunya est souvent le plus rapide a prendre en main grace au simple changement de cle entre test et live. CinetPay et Hub2 sont plus complets si vous visez plusieurs operateurs.
Comment tester un timeout sans attendre des minutes ?
Utilisez le numero de test dedie de l agregateur qui ne repond jamais. Votre code doit alors declencher sa logique d expiration. Vous controlez ainsi le delai au lieu de subir le reseau.
Faut-il tester chaque operateur separement ?
Oui. Wave, Orange Money et Free Money ont des parcours et des messages differents. Un scenario qui marche sur l un peut casser sur l autre, notamment sur les messages d erreur affiches au client.
Que faire si l agregateur n a pas de sandbox pour une methode ?
Passez par un agregateur qui en fournit un, ou testez avec de vraies micro-transactions controlees. Ne lancez jamais une methode de paiement jamais testee directement sur de vrais clients.
Discutons de votre projet. Vous integrez un paiement mobile money et vous voulez le tester serieusement avant le lancement ? Ecrivez-nous sur WhatsApp +221 77 596 93 33.
Mohamed Bah
Fondateur, Kolonell
Passionné par le digital et l'entrepreneuriat en Afrique, Mohamed accompagne les entreprises sénégalaises dans leur transformation digitale depuis 2020. Fondateur de Kolonell, il croit que chaque PME mérite une présence en ligne professionnelle et accessible.
