Webhooks de paiement Mobile Money : sept erreurs qui font perdre des paiements

Webhooks de paiement Mobile Money : sept erreurs qui font perdre des paiements

Un webhook de paiement n'est pas un message qui arrive toujours une seule fois, dans l'ordre, et signé comme vous le croyez : c'est un contrat qu'il faut lire.

Réponse courte. Un client paie par Mobile Money, l'agrégateur (FedaPay, Kkiapay, PayDunya, CinetPay) encaisse, puis prévient votre site par une requête HTTP : le webhook. Les paiements se perdent rarement chez l'agrégateur. Ils se perdent parce que le récepteur répond trop tard ou avec un mauvais code, traite deux fois le même message, le croit sans le recouper, vérifie une signature sur un corps modifié, mélange test et production, plante sur un événement imprévu, ou tombe en panne sans que personne le sache. Voici ces sept erreurs, d'après les documentations officielles lues le 7 novembre 2026, puis une checklist de dix points.

Transparence. BOVO Digital est une agence basée au Bénin qui construit des automatisations n8n : nous avons donc un intérêt dans le sujet. Cet article ne repose sur aucune donnée, aucun client et aucun résultat de BOVO. Il lit des documentations publiques ; ce qui relève de notre raisonnement est écrit comme tel.

Ce que disent les documentations, côte à côte

Les valeurs viennent des pages FedaPay, Kkiapay et Meta, consultées le 7 novembre 2026. Meta n'est pas un agrégateur, mais ses webhooks WhatsApp suivent le même principe et se retrouvent souvent dans le même workflow qu'un paiement.

Erreur 1 : ne pas répondre en 2xx, ou répondre trop tard

Symptôme. Le paiement est réussi chez l'agrégateur, mais votre système le traite plusieurs fois, ou plus du tout.

Cause. Chez FedaPay, seul un statut 2xx est un succès : « Toute réponse différente d'un statut 2xx est considérée comme un échec. » Chez Kkiapay, tous les codes hors de cette famille, y compris les 3xx, signalent que l'événement n'a pas été reçu. Une redirection, un 404 sur la mauvaise URL, un 500 parce que votre base est lente : tout cela déclenche des reprises. FedaPay demande de répondre « rapidement » avec un 2xx avant les traitements lourds.

Ce que valent les reprises.

• FedaPay : au maximum 9 reprises, avec une attente qui ne dépasse pas 2 minutes, puis désactivation du webhook après 10 essais sans succès. Calcul à partir de ces chiffres (le nôtre) : toute la série tient dans une vingtaine de minutes au plus.
• Kkiapay : 5 essais de suite, à intervalles de 500 ms « incrémental ». La page ne détaille pas le calendrier. Notre lecture, non confirmée par la page : si l'intervalle croît par pas de 500 ms, toute la série dure quelques secondes, et une panne d'une minute suffit à manquer la notification.
• Meta : reprise immédiate puis plusieurs fois pendant sept jours, avec une fréquence décroissante (page indiquant une mise à jour du 17 juin 2026).

Correction. Accusez réception d'abord, traitez ensuite : écrivez le message brut dans une table ou une file, répondez 200, puis faites le travail. FedaPay recommande lui-même une file d'attente asynchrone.

Dans n8n. Le nœud Webhook propose le paramètre « Respond » avec trois modes que la documentation décrit : « Immediately » (le nœud renvoie le code de réponse et le message « Workflow got started »), « When Last Node Finishes », et « Using 'Respond to Webhook' Node ». La page du nœud Respond to Webhook précise qu'un workflow qui échoue avant d'atteindre ce nœud renvoie une erreur 500. Notre lecture : « Immediately », ou un Respond to Webhook placé en premier, évite qu'un échec en aval ne provoque une reprise.

Erreur 2 : ne pas dédupliquer

Symptôme. Un client reçoit deux confirmations, un abonnement est prolongé deux fois.

Cause. Les reprises existent pour qu'aucun message ne soit perdu, donc le même message peut arriver plusieurs fois. FedaPay l'écrit : un point de terminaison peut recevoir le même événement plusieurs fois. Meta écrit que votre serveur « doit être capable de gérer la déduplication ».

Ce que dit la documentation. FedaPay conseille d'enregistrer les identifiants des événements déjà traités, ou d'utiliser l'identifiant de l'objet (champ object) avec le nom de l'événement (name). Kkiapay envoie un transactionId ; la page ne parle pas de déduplication.

Correction (notre raisonnement). Rendez l'opération idempotente : une clé unique par couple « identifiant de transaction + effet » (par exemple « marquer la commande payée »), stockée dans une table avec une contrainte d'unicité. Si la clé existe déjà, répondez 200 sans rien refaire : un code d'erreur sur un doublon provoquerait de nouvelles reprises.

Erreur 3 : livrer sur la seule foi du webhook

Cause. Une URL de webhook est une adresse publique. Même signée, la requête ne prouve pas que le montant correspond à votre commande.

Ce que dit la documentation. FedaPay permet de lire une transaction par son identifiant (GET /transactions/{id}, avec un champ status dont les valeurs données en exemple sont « pending », « approved » et « canceled »). Le SDK Node de Kkiapay décrit une fonction verify qui retrouve une transaction par son identifiant. PayDunya décrit une URL checkout-invoice/confirm qui prend le jeton de la facture.

Correction (notre recommandation). Traitez le webhook comme un signal de réveil : relisez la transaction par l'API avec votre clé secrète, vérifiez statut, montant, devise et référence de commande, et livrez seulement si tout concorde. Cela coûte un appel HTTP de plus.

Erreur 4 : vérifier la signature sur un corps modifié

Symptôme. La vérification de signature échoue sans raison apparente, et l'équipe finit par la désactiver.

Cause. Une signature est calculée sur les octets exacts du corps. Si votre framework lit le JSON puis le réécrit, le calcul ne correspond plus. L'exemple Node de la documentation FedaPay le montre : un commentaire demande de récupérer le corps brut sous forme de tampon (bodyParser.raw), et l'exemple PHP lit php://input. La signature est dans l'en-tête X-FEDAPAY-SIGNATURE et se vérifie avec Webhook.constructEvent (Node) ou \FedaPay\Webhook::constructEvent (PHP). La signature comprend aussi un horodatage, qui permet de rejeter un message trop ancien ; il est régénéré à chaque reprise.

Chez Kkiapay. La page dit que le webhook est signé et qu'un en-tête x-kkiapay-secret contient une signature calculée avec le « hash secret » que vous avez saisi dans le tableau de bord. Elle ne dit pas comment cette valeur est calculée ni comment la comparer, et son exemple de requête montre simplement x-kkiapay-secret: XXX. Nous ne pouvons donc pas dire s'il s'agit du secret lui-même ou d'un condensé. C'est une lacune : demandez au support, et appuyez-vous en attendant sur la relecture par l'API (erreur 3).

Chez Meta. La page indique l'en-tête X-Hub-Signature-256 (précédé de sha256=) : un HMAC-SHA256 calculé à partir de la charge utile et du secret de l'application. À la configuration, Meta envoie une requête GET avec hub.mode, hub.challenge et hub.verify_token : comparez le jeton, puis renvoyez 200 avec la valeur de hub.challenge.

Dans n8n. Le nœud Webhook offre l'option « Raw Body », décrite comme servant à recevoir les données dans un format brut, JSON ou XML. Ses méthodes d'authentification documentées sont Basic auth, Header auth, JWT auth et n8n User Auth (OAuth2), plus une liste blanche d'adresses IP. La page ne décrit aucune vérification de signature de type FedaPay ou Meta. Nous n'avons donc validé aucune méthode de calcul dans n8n, et nous ne la décrivons pas ici. À défaut, la relecture par l'API (erreur 3) devient votre garantie principale.

Erreur 5 : mélanger le test et la production

Ce que disent les documentations.

• FedaPay : deux adresses d'API (sandbox-api.fedapay.com et api.fedapay.com) et un secret de webhook « différent entre le mode test et le mode live », unique par point de terminaison.
• Kkiapay : en sandbox, on utilise les clés de test du tableau de bord ; au passage en production, on les remplace par celles du compte live. Le guide de test donne des numéros fictifs : pour MTN Bénin, 61000000 ou 97000000 simulent un succès, et les terminaisons 001, 002 et 003 une erreur, des fonds insuffisants et un refus.
• PayDunya : adresses sandbox-api et api distinctes, clés de test et de production distinctes.

Piège n8n. Le nœud Webhook a deux URL, « Test URL » et « Production URL ». La première n'est enregistrée que lorsque vous écoutez un événement de test ou exécutez le workflow ; la seconde l'est à la publication du workflow. Collez l'URL de test chez l'agrégateur, et les webhooks échoueront dès que vous cesserez d'écouter.

Correction. Une configuration par environnement, avec quatre valeurs séparées : URL d'API, clé secrète, secret de webhook, URL de webhook, et une colonne « mode » (test ou live) dans votre table de paiements.

Erreur 6 : mal gérer les événements imprévus

Cause. Par défaut, FedaPay envoie tous les événements : les transaction.* (created, approved, declined, canceled, transferred, updated) mais aussi ceux des clients (customer.created, updated, deleted). Or l'exemple PHP de la documentation FedaPay se termine, dans le cas par défaut du switch, par http_response_code(400); exit(); : un événement non géré reçoit donc un 400, que l'agrégateur compte comme un échec et réessaie. Copié tel quel, cet exemple peut mener à la désactivation du webhook.

Les exemples Node, relus dans le texte brut. Notre lecture :

• deux lignes case portent une apostrophe en trop ('transaction.approved'' et 'transaction.canceled''), ce qui est une erreur de syntaxe : l'exemple ne s'exécute pas tel quel ;
• dans le bloc catch, la réponse 400 est envoyée sans instruction d'arrêt : le code continue avec un événement non défini ;
• le cas par défaut affiche event.type alors que le switch porte sur event.name.

Ces défauts sont dans l'exemple, pas dans l'API : relisez avant de copier.

Correction. Pour un événement que vous ne gérez pas : répondez 2xx et journalisez-le. Répondez 4xx ou 5xx seulement pour une signature invalide ou une charge illisible. Côté FedaPay, ne sélectionnez que les événements utiles dans le tableau de bord, comme le conseille la documentation. Dans n8n, le nœud Webhook a une option « Only Run If » (expression évaluée sur la requête) : la page indique que les requêtes qui ne correspondent pas reçoivent une réponse 200 sans créer d'exécution. L'option dépend de la version de n8n ; vérifiez qu'elle existe chez vous.

Erreur 7 : ne pas surveiller

Cause. Un webhook désactivé ne fait pas de bruit. FedaPay désactive le point de terminaison après 10 essais sans succès ; vous pouvez l'empêcher en décochant « Désactiver le webhook lorsque l'application génère des erreurs ». Notre lecture : décocher évite la coupure, mais la panne continue en silence.

Ce que la documentation offre. FedaPay a des journaux par webhook, avec un bouton « Re-déclencher ». Chez Meta, il n'existe pas d'API pour récupérer l'historique des webhooks : il faut stocker les charges utiles à la réception.

Correction (notre recommandation).

• Comparez chaque jour le nombre de commandes « en attente de paiement » avec les paiements approuvés chez l'agrégateur : l'écart est votre alerte.
• Vérifiez régulièrement l'état de votre webhook dans le tableau de bord de l'agrégateur, et notez qui s'en charge.
• Prévoyez la procédure de rattrapage : relire les transactions de la période par l'API et rejouer les livraisons manquantes, ce que l'idempotence (erreur 2) rend sans danger.

Un schéma de workflow n8n en sept étapes

Ce schéma découle des points ci-dessus. Il ne contient aucun code et nous ne l'avons pas testé. Les noms de nœuds sont ceux de la documentation n8n.

1. Nœud Webhook (méthode POST), option Raw Body activée si vous devez vérifier une signature, URL de production dans l'agrégateur.
2. Réponse : mode « Immediately », ou nœud Respond to Webhook placé en premier. L'accusé de réception part avant tout traitement.
3. Stockage du message brut et de l'heure de réception (table de journal).
4. Contrôle d'idempotence : la clé « identifiant de transaction + effet » existe-t-elle déjà ? Si oui, fin.
5. Nœud HTTP Request : relire la transaction chez l'agrégateur avec la clé secrète. La documentation du nœud décrit l'envoi d'en-têtes, l'authentification et l'import d'une commande cURL.
6. Comparaison du statut, du montant, de la devise et de la référence de commande avec votre base.
7. Livraison (accès, e-mail, message WhatsApp), puis enregistrement de la clé d'idempotence.

Checklist de dix points

1. Le récepteur répond en 2xx, y compris sur un doublon et sur un événement non géré.
2. L'accusé de réception part avant tout traitement long.
3. Chaque message brut est stocké avant d'être traité.
4. Une clé d'idempotence unique empêche de livrer deux fois.
5. Le statut, le montant, la devise et la référence sont relus par l'API avant livraison.
6. La signature est vérifiée sur le corps brut, ou, si ce n'est pas possible, la relecture par l'API est systématique.
7. Les clés, secrets et URL de test et de production sont séparés.
8. Les événements inutiles ne sont pas envoyés, et les autres ne font jamais renvoyer d'erreur.
9. Un rapprochement quotidien compare les commandes et les paiements chez l'agrégateur.
10. Quelqu'un est alerté quand le webhook est désactivé ou silencieux, et sait rejouer les événements manqués.

Ce qui dépend de votre agrégateur

Les erreurs sont communes, les détails changent. Voici ce que nous avons lu dans les documentations officielles, et seulement cela :

• PayDunya (documentation). L'IPN (notification instantanée de paiement) est une URL de votre serveur qui reçoit en POST les informations d'un paiement confirmé, annulé ou échoué. La page dit que la réponse comprend un hash qui est le hachage SHA-512 de votre clé principale (MasterKey) et sert à vérifier que les données viennent de PayDunya. Elle distingue les statuts « pending », « cancelled », « completed » et « failed », et propose une adresse de confirmation par jeton de facture, en version test (sandbox-api) et production. Nous n'y avons pas trouvé de règle de reprise.
• CinetPay. La page de documentation consacrée à la notification (notify_url) n'a pas pu être ouverte le 7 novembre 2026 (échec de connexion). Nous n'affirmons donc rien sur ses reprises, sa signature ou son bac à sable.

Pour le contexte du marché, voir la lecture du rapport BCEAO sur le Mobile Money au Bénin. Si votre webhook déclenche un message WhatsApp, la fenêtre de 24 heures et la facturation par message fixent ce que vous pouvez envoyer. Pour brancher un chatbot WhatsApp sur n8n, voir le tutoriel complet, et pour les workflows qui doivent garder une validation humaine, les agents IA n8n en production.

Ce que nous ne savons pas

• Le calcul du secret chez Kkiapay. La page ne dit pas comment produire ou comparer la valeur de x-kkiapay-secret.
• Le calendrier exact des reprises de Kkiapay et de Meta, non chiffré dans les pages lues.
• La vérification de signature dans n8n. Aucune méthode n'est décrite dans la page du nœud Webhook, et nous n'en avons pas validé.
• Les adresses IP de FedaPay. La page dit que les webhooks partent d'une liste définie, sans la donner.
• CinetPay, dont la documentation n'a pas pu être ouverte, et Orange Money, Moov Money, Celtiis Cash, pour lesquels nous n'avons pas trouvé de documentation d'API ouverte.
• Le comportement réel. Nous avons lu des documentations, pas observé des webhooks en production ; testez en sandbox.
• Le délai de réponse maximal avant qu'un agrégateur compte un échec : aucun chiffre dans les pages FedaPay et Kkiapay lues.

Sources consultées le 7 novembre 2026

• FedaPay, Webhooks et événements (page non datée).
• FedaPay, Get a transaction et Create a transaction.
• Kkiapay, Webhook (page non datée).
• Kkiapay, guide de test du bac à sable et SDK Node.js.
• Meta, Create a webhook endpoint (mise à jour affichée : 17 juin 2026).
• PayDunya, documentation HTTP/JSON (page non datée).
• n8n, nœud Webhook, nœud Respond to Webhook, nœud HTTP Request.
• CinetPay, notification : non ouverte (échec de connexion), citée pour mémoire.

Vous voulez un branchement de paiement testé, idempotent et surveillé, sans perdre un seul paiement en silence ? Découvrez notre agence d'automatisation au Bénin.