Le verdict en trois phrases
Lancer un paiement en production sans l'avoir éprouvé en sandbox, c'est jouer la trésorerie des clients à pile ou face. Une bonne méthodologie isole un environnement de test (staging), simule les webhooks, et couvre les cas limites: timeout, double webhook, paiement partiel, remboursement. Une matrice scénario x résultat attendu, plus une checklist go-live, élimine la grande majorité des incidents.
Les environnements et leur rôle
Ne testez jamais sur la base de production. Trois environnements séparés, trois jeux de clés.
| Environnement | Clés API | Base de données | Usage |
|---|---|---|---|
| Sandbox / dev | Test | Locale jetable | Développement, premiers webhooks |
| Staging | Test | Copie anonymisée | Recette, tests d'intégration end-to-end |
| Production | Live | Réelle | Clients réels uniquement |
Les webhooks sont le point faible: en local, un tunnel (type ngrok) expose votre endpoint pour recevoir les notifications de l'agrégateur; en staging, une URL stable et un rejeu de webhook permettent de retester sans refaire un vrai paiement.
Matrice de scénarios de test
Chaque cas limite doit avoir un résultat attendu écrit, sinon il n'est pas testé. Voici la matrice minimale avant tout go-live.
| Scénario | Déclencheur simulé | Résultat attendu |
|---|---|---|
| Paiement réussi | Webhook "success" | Commande payée, client notifié 1 fois |
| Double webhook | 2x le même event | Traité 1 seule fois (idempotence) |
| Timeout opérateur | Pas de réponse 30 s | Statut "en attente", pas de double paiement |
| Webhook hors-ordre | "success" avant "created" | Réconcilié, état cohérent |
| Paiement partiel | Montant < attendu | Commande non validée, alerte |
| Remboursement | Webhook "refund" | Commande remboursée, stock restitué |
| Signature invalide | Webhook falsifié | Rejeté (401), loggé |
| Échec solde insuffisant | Webhook "failed" | Commande non payée, relance déclenchée |
Le scénario double webhook est le plus traître: sans clé d'idempotence, une commande peut être validée ou un stock décrémenté deux fois. C'est le test à ne jamais sauter.
Checklist go-live
| Vérification | État attendu |
|---|---|
| Clés Live séparées des clés Test | Confirmé, jamais commitées |
| Endpoint webhook en HTTPS + vérif signature | Actif |
| Idempotence sur l'ID de transaction | Implémentée et testée |
| Gestion timeout + vérification de statut | En place |
| Logs de chaque webhook (succès et échec) | Activés |
| Page de retour client (succès/échec/annulation) | Testée |
| Réconciliation quotidienne | Programmée |
| Test d'un vrai paiement de 100 FCFA en prod | Effectué et remboursé |
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.
Mini cas pratique
Le dev de Khadija intègre Wave sur un site Next.js. En staging, il rejoue le même webhook "success" deux fois: sans idempotence, la commande passe à "payée x2" et le mail de confirmation part en double. Il ajoute une clé d'idempotence sur l'ID de transaction (event déjà traité = ignoré) et rejoue: une seule validation. Coût du test: 0 FCFA et 30 minutes; coût de l'incident évité en prod: des heures de support et des clients facturés à tort.
FAQ
Wave et Orange Money offrent-ils un vrai sandbox en 2026?
Des environnements et comptes de test existent selon votre statut marchand et l'agrégateur. À défaut d'un sandbox complet, on teste avec de petits montants réels (ex. 100 FCFA) immédiatement remboursés.
Comment recevoir des webhooks en local?
Un tunnel comme ngrok expose votre endpoint localhost sur une URL publique temporaire. L'agrégateur y envoie ses notifications, et vous déboguez le traitement sans déployer.
Pourquoi l'idempotence est-elle si critique?
Les opérateurs peuvent renvoyer le même webhook plusieurs fois. Sans clé d'idempotence sur l'ID de transaction, vous risquez une double validation de commande ou un double décrément de stock.
Que faire d'un paiement en timeout?
Ne jamais conclure à l'échec: interroger le statut réel via l'API avant d'agir. Le paiement peut avoir abouti côté opérateur même si la réponse HTTP n'est jamais revenue.
Discutons de votre projet. Nous intégrons Wave/OM avec sandbox, idempotence et checklist go-live testée avant la moindre mise en production. 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.
