Le verdict en trois phrases
Un webhook Orange Money doit être vérifié par signature, idempotent et protégé par un retry exponentiel — sinon un paiement peut être compté deux fois ou usurpé. À Cotonou en 2026, OM Bénin facture ~1,5 % à la collecte, avec un timeout USSD de 120 s et 3 relances automatiques. Le settlement se fait en T+2 à T+3, ce qui impose une réconciliation stricte côté serveur.
Les trois piliers d'un webhook fiable
En Node.js, on lit le corps brut (raw body), on recalcule la signature avec le secret partagé, puis on stocke l'identifiant de transaction pour rejeter les doublons. On répond 200 vite, et on traite en tâche de fond.
| Pilier | Mécanisme | Effet |
|---|---|---|
| Authenticité | Vérification signature sur raw body | Rejette les faux événements |
| Idempotence | Clé unique (transactionId) en base | Évite le double comptage |
| Robustesse | Retry exponentiel + file d'attente | Encaisse les relances OM |
| Traçabilité | Log horodaté de chaque événement | Facilite l'audit |
| Réponse rapide | 200 immédiat, traitement async | Évite les timeouts |
Codes d'erreur et délais de settlement
Orange Money renvoie des statuts qu'il faut mapper précisément pour ne pas valider une commande sur un paiement en attente.
| Code / statut | Signification | Action serveur |
|---|---|---|
| SUCCESS | Paiement confirmé | Fulfilment après idempotence |
| PENDING | En attente USSD | Attendre, ne rien valider |
| TIMEOUT (120 s) | Client n'a pas confirmé | Laisser les relances jouer |
| FAILED | Solde/PIN refusé | Marquer échec, notifier |
| DUPLICATE | Événement déjà reçu | Ignorer (idempotence) |
| SETTLEMENT T+2/T+3 | Fonds versés | Réconcilier avec relevé |
Ces valeurs sont un ordre de grandeur 2026 ; les libellés exacts dépendent de votre contrat OM.
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
Ibrahim tient une boutique en ligne à Cotonou et encaisse 3 000 000 FCFA par mois via Orange Money. Avant sécurisation, un bug d'idempotence lui a fait livrer 12 commandes en double en un mois, soit ~180 000 FCFA de pertes. Après ajout de la clé unique par transactionId et de la vérification de signature, les doublons tombent à zéro, pour un coût de collecte stable de ~45 000 FCFA/mois (1,5 %).
FAQ
Pourquoi lire le raw body et pas le JSON parsé ? Parce que la signature est calculée sur les octets exacts reçus. Si un middleware reformate le JSON, le hash ne correspondra plus et toutes vos vérifications échoueront.
Comment garantir l'idempotence ? Stockez le transactionId avec une contrainte d'unicité en base. À la réception, tentez l'insertion : si elle échoue pour doublon, répondez 200 sans re-traiter.
Que faire pendant le timeout de 120 s ? Rien côté commande. OM déclenche jusqu'à 3 relances ; validez uniquement sur un statut SUCCESS confirmé et vérifié.
Pourquoi le settlement en T+2/T+3 est-il important ? Parce qu'un statut SUCCESS ne signifie pas fonds disponibles. Réconciliez chaque jour vos SUCCESS avec le relevé de versement pour détecter les écarts.
Discutons de votre projet. Nous sécurisons votre webhook Orange Money en Node.js avec signature, idempotence et retry. 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.
