Tester ses paiements mobile money avant la prod : sandbox, numéros de test et checklist

Mettre un bouton "Payer" en ligne sans l'avoir testé, c'est promettre à vos clients une expérience que vous n'avez jamais vue fonctionner. Au Sénégal, où le paiement passe par Wave, Orange Money, Free Money et des agrégateurs comme PayDunya, CinetPay ou Hub2, chaque intégration a ses propres pièges. Un sandbox bien utilisé vous évite de découvrir les bugs avec de l'argent réel et des clients mécontents.

Ce guide explique comment tester un paiement mobile money de bout en bout : quels environnements existent, quels numéros de test utiliser, quels scénarios couvrir, et comment basculer en production sans tout casser.

Pourquoi tester en sandbox est non négociable

Un paiement mobile money n'est pas un simple appel API qui répond instantanément. C'est une chaîne : votre serveur appelle l'agrégateur, qui contacte l'opérateur, qui envoie un push USSD ou une notification au téléphone du client, qui valide avec son code PIN, et la confirmation revient par un webhook asynchrone parfois plusieurs secondes plus tard.

Chaque maillon peut échouer. 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 ça rate. Le sandbox vous laisse rejouer tous ces cas à volonté, sans bouger un seul franc CFA.

Ce que le sandbox reproduit vraiment

Un bon environnement de test simule les réponses de l'opérateur : succès, échec, solde insuffisant, timeout, annulation utilisateur. Il vous donne aussi des webhooks de test pour valider que votre back-end réagit correctement. Ce qu'il ne simule pas toujours bien : la latence réelle du réseau au Sénégal et le comportement exact du push USSD sur les vieux téléphones. Gardez cette limite en tête.

Les environnements de test des principaux acteurs

Au Sénégal, vos intégrations passent presque toujours par un agrégateur plutôt que directement par l'opérateur. Voici le panorama.

PayDunya

PayDunya fournit un mode test active par une simple clé d'API différente (la clé commence par "test_" au lieu de "live_"). Vous créez une transaction comme en prod, mais aucun débit réel n'a lieu. La plateforme renvoie des statuts simules que vous pouvez forcer. C'est l'un des plus simples à prendre en main pour un projet sénégalais.

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 déclencher les différents codes de retour. Pensez à bien séparer vos variables d'environnement entre test et prod, car un mélange de clés est la première cause d'incident au passage en live.

Hub2

Hub2 expose une API unifiée multi-opérateurs avec un environnement sandbox documenté. C'est utile quand vous voulez accepter Wave, Orange Money et MTN sans intégrer chaque opérateur séparément. Le sandbox renvoie des numéros et réponses de test pour chaque méthode.

Orange Money et Wave en direct

Orange Money Web Payment dispose d'un environnement de développement avec des numéros de test et un parcours de validation simulé. Wave, de son côté, privilégie une intégration via lien de paiement ou checkout ; son environnement de test est plus restreint, raison de plus pour passer par un agrégateur si vous voulez un sandbox riche.

Numéros et données de test

Chaque agrégateur publie des numéros de test dans sa documentation. Ne les inventez pas : un numéro aléatoire renverra une erreur générique qui ne vous apprend rien. Les numéros officiels déclenchent des comportements précis.

Typiquement vous trouverez :

• Un numéro qui renvoie toujours un succès.
• Un numéro qui renvoie toujours un échec (refus opérateur).
• Un numéro qui simule un solde insuffisant.
• Un numéro qui ne répond jamais, pour tester votre timeout.

Notez ces numéros dans votre documentation interne. Vos développeurs et votre QA doivent pouvoir rejouer un échec en dix secondes sans chercher.

Les scénarios à couvrir absolument

Tester uniquement le paiement réussi est l'erreur classique. Voici la matrice minimale.

1. Paiement réussi

Le cas nominal. Vérifiez que le webhook de confirmation arrive, que la commande passe au statut "payée", que le reçu part, et que le client voit une page de succès claire.

2. Paiement refusé

L'opérateur rejette. Vérifiez que la commande reste en attente ou passe en "échec", que le client voit un message compréhensible (pas un code technique), et qu'il peut réessayer.

3. Solde insuffisant

Très fréquent au Sénégal. Le message doit être explicite : "Solde insuffisant, rechargez votre compte." Surtout, ne marquez pas la commande comme payée.

4. Timeout / pas de réponse

Le client n'a jamais valide le push. Votre système doit attendre un délai raisonnable puis marquer la transaction "expirée", sans la perdre. C'est ici que l'idempotence compte.

5. Double soumission

Le client clique deux fois sur "Payer". Vous devez générer une clé d'idempotence par tentative pour ne jamais débiter deux fois. Testez-le explicitement.

6. Webhook en double ou en retard

Les agrégateurs renvoient parfois le même webhook plusieurs fois. Votre back-end doit traiter le premier et ignorer les suivants pour la même transaction.

Mini cas client : un site de livraison à Dakar

Une boutique de plats préparés livrant à Dakar nous a contactés après un lancement rate. En production directe, sans sandbox, 18 % de leurs commandes restaient bloquées en "en attente de paiement" alors que le client avait bien payé. Le webhook arrivait, mais leur code le traitait avant que la commande soit enregistrée, et le rapprochait a un identifiant vide.

Nous avons rejoue le scénario dans le sandbox CinetPay : webhook reçu sur une commande inexistante, puis re-réception 30 secondes plus tard. Le correctif a été de stocker la transaction dès l'initiation, d'utiliser la référence de commande comme clé, et de rendre le traitement du webhook idempotent. Après déploiement, le taux de commandes bloquées est tombé sous 1 %. Tout cela a été validé en sandbox avant la moindre transaction réelle.

Passer en production sans casse

Le passage en live est le moment où tout peut déraper. Quelques règles.

Séparez strictement vos clés

Clés test et clés live ne doivent jamais cohabiter dans le même fichier sans distinction claire. Utilisez des variables d'environnement et vérifiez au démarrage que vous chargez bien le bon jeu selon l'environnement.

Faites une transaction réelle de faible montant

Avant d'ouvrir au public, passez une vraie commande à 100 FCFA avec votre propre numéro. Vérifiez le débit, le webhook, le reçu, la page de succès. Remboursez-vous ensuite. C'est votre dernier filet de sécurité.

Surveillez les premières 24 heures

Mettez en place des alertes sur les transactions qui restent "en attente" trop longtemps. Les premières heures révèlent les cas que le sandbox n'a pas couverts.

Checklist développeur

Avant de déclarer un paiement "prêt pour la prod" :

• Les clés test et live sont séparées et chargées selon l'environnement.
• Les six scénarios (succès, refus, solde insuffisant, timeout, double clic, webhook double) sont testés en sandbox.
• L'idempotence empêche tout double débit.
• Le webhook est vérifié (signature) et idempotent.
• Les messages d'erreur sont en langage clair, pas des codes techniques.
• Une transaction réelle de faible montant a été validée de bout en bout.
• Des alertes existent sur les transactions bloquées.

FAQ

Le sandbox est-il vraiment fidèle à la production ?

Il est fidèle pour la logique (statuts, webhooks, codes de retour) mais pas toujours pour la latence réseau ni le comportement du push USSD sur les vieux téléphones. C'est pourquoi une transaction réelle de faible montant reste indispensable avant l'ouverture.

Quel agrégateur offre le sandbox le plus simple au Sénégal ?

PayDunya est souvent le plus rapide à prendre en main grâce au simple changement de clé entre test et live. CinetPay et Hub2 sont plus complets si vous visez plusieurs opérateurs.

Comment tester un timeout sans attendre des minutes ?

Utilisez le numéro de test dédié de l'agrégateur qui ne répond jamais. Votre code doit alors déclencher sa logique d'expiration. Vous contrôlez ainsi le délai au lieu de subir le réseau.

Faut-il tester chaque opérateur séparément ?

Oui. Wave, Orange Money et Free Money ont des parcours et des messages différents. Un scénario qui marche sur l'un peut casser sur l'autre, notamment sur les messages d'erreur affichés au client.

Que faire si l'agrégateur n'a pas de sandbox pour une méthode ?

Passez par un agrégateur qui en fournit un, ou testez avec de vraies micro-transactions contrôlées. Ne lancez jamais une méthode de paiement jamais testée directement sur de vrais clients.

Discutons de votre projet. Vous intégrez un paiement mobile money et vous voulez le tester sérieusement avant le lancement ? Écrivez-nous sur WhatsApp +221 77 596 93 33.