Le verdict en trois phrases
Un environnement de recette fiable est ce qui sépare un go-live serein d'un week-end à rembourser des clients furieux. En 2026, montez un tunnel webhook (ngrok ou équivalent), simulez les callbacks, et rejouez chaque événement jusqu'à ce que succès, timeout et annulation soient tous gérés. La règle : ne mettez jamais en prod un flux paiement qui n'a pas passe une checklist d'au moins 12 cas de test.
Monter le sandbox pas a pas
Orange Money fonctionne par redirection web avec une URL de notification, tandis que d'autres opérateurs comme M-Pesa Daraja utilisent un STK push. Le principe de recette est le même : un environnement isole, des identifiants de test, un endpoint de callback joignable depuis internet.
| Élément de recette | Valeur / outil 2026 | Rôle |
|---|---|---|
| Tunnel local | ngrok, cloudflared | Exposer localhost au callback |
| URL notification | https://xxxx.ngrok.io/webhook | Recevoir le statut paiement |
| Compte test | Fourni par l'opérateur | Payer sans argent réel |
| Timeout STK (M-Pesa) | 60 secondes | Simuler l'expiration |
| Shortcode test Daraja | 174379 | Sandbox Safaricom |
| Rejeu d'événement | Log + POST manuel | Tester l'idempotence |
| Signature webhook | Header à vérifier | Rejeter les faux appels |
Le piège classique : coder uniquement le cas nominal (le client paie, tout marché). En réalité 20 à 30 % des tentatives finissent en timeout, annulation ou solde insuffisant. Chacun de ces cas doit avoir un comportement défini et testé.
La checklist des 12 cas et leurs actions
Voici les statuts à couvrir et l'action attendue de votre back-end. Ne signez pas la recette tant que les 12 ne sont pas verts.
| # | Cas testé | Statut reçu | Action attendue |
|---|---|---|---|
| 1 | Paiement réussi | success | Livrer, marquer payé |
| 2 | Solde insuffisant | failed | Ne rien livrer, message clair |
| 3 | Client annule | cancelled | Libérer le panier |
| 4 | Timeout STK 60 s | timeout | Marquer en attente, relance |
| 5 | Double callback | success x2 | Idempotence, un seul fulfillment |
| 6 | Mauvais montant | mismatch | Rejeter, alerter |
| 7 | Signature invalide | — | Ignorer, logguer |
| 8 | Référence inconnue | 404 | Logguer, pas de fulfillment |
| 9 | Callback tardif | success | Fulfillment si pas déjà fait |
| 10 | Réseau coupé client | pending | Vérification serveur au retour |
| 11 | Remboursement | refunded | Annuler la commande |
| 12 | Rejeu manuel | success | Aucun double effet |
Les cas 5 et 9 sont les plus souvent oubliés et les plus coûteux : ils testent l'idempotence, c'est-à-dire la capacité à recevoir deux fois le même événement sans livrer deux fois.
Mini cas pratique
Ibrahim, restaurateur à Abidjan avec commande en ligne, a lancé sans recette sérieuse. Le premier vendredi soir, un pic de trafic sur la 4G à génère des dizaines de timeouts. Son système, ne gérant que le cas nominal, laissait les commandes bloquées sans jamais confirmer ni annuler. Résultat : 23 commandes fantômes, cuisine paralysee, et 340 000 FCFA de tickets impossibles à rapprocher ce soir-là. Après avoir monte un sandbox et valide les 12 cas (surtout timeout et rejeu), le taux de commandes bloquées est passé sous 1 %. La recette à coûté 2 jours de travail ; le week-end rate lui en avait coûté bien plus.
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.
FAQ
Combien de temps un STK push M-Pesa reste-t-il actif en sandbox 2026 ?
Environ 60 secondes. Passé ce délai sans saisie du PIN, la requête expire et vous recevez un statut d'échec ou de timeout. Testez explicitement ce cas, c'est l'un des plus fréquents en production.
Ai-je besoin d'un tunnel comme ngrok pour tester les webhooks ?
Oui, en développement local. L'opérateur doit joindre votre callback depuis internet, or localhost n'est pas accessible. Un tunnel expose votre URL locale le temps de la recette.
Quel shortcode utiliser pour le sandbox Daraja ?
Le shortcode de test 174379 dans l'environnement sandbox Safaricom. Il permet de simuler un STK push sans mouvement d'argent réel.
Combien de cas dois-je tester avant la prod ?
Au minimum 12 : succès, échec, annulation, timeout, double callback, remboursement et rejeu manuel. Les cas d'idempotence (double callback, callback tardif) sont non négociables.
Peut-on rejouer un événement webhook pour tester ?
Oui, et c'est indispensable. Conservez le payload dans vos logs et renvoyez-le manuellement en POST : votre système doit produire exactement le même résultat qu'au premier envoi, sans double effet.
Discutons de votre projet. On monte votre sandbox mobile money et on valide chaque webhook avant le go-live. 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.
