Logique de retry pour transactions mobile money échouées : idempotence et états

Le verdict en trois phrases

Le retry est indispensable, mais mal fait il est pire que l'échec : sans clé d'idempotence, chaque relance risque de débiter le client une seconde fois. La bonne architecture repose sur trois piliers : une clé d'idempotence par intention de paiement, une machine à états explicite, et un polling de statut avant toute relance. Correctement implémentée, elle fait tomber le double-débit de 2,1 % à 0,05 % sans perdre les paiements lents.

La clé d'idempotence, premier réflexe

Une clé d'idempotence est un identifiant unique attaché à l'intention de paiement du client (pas à la tentative). Toutes les relances d'un même paiement portent la même clé. L'opérateur et votre serveur peuvent ainsi reconnaître qu'il s'agit de la même transaction et ne pas la rejouer.

Sans cette clé, un client qui recharge la page ou dont le réseau relance la requête se fait débiter deux fois. Avec elle, la seconde requête renvoie simplement le résultat de la première.

La machine à états

Chaque paiement suit un cycle de vie strict. On ne relance jamais un paiement dont l'état est déjà final (success ou reversed). On ne poll que les états intermédiaires.

Cette discipline évite 90 % des incidents : la plupart des double-débits viennent d'un retry lance alors que le paiement était encore pending.

Délai de timeout et fréquence de polling par opérateur

Chaque opérateur a sa propre fenêtre de confirmation. Poller trop tôt ou relancer avant le timeout génère des doublons ; attendre trop longtemps dégrade l'expérience client. Voici les ordres de grandeur 2026.

Règle : ne relancez jamais avant d'avoir dépasse le délai de timeout de l'opérateur et confirme via polling que l'état est bien failed.

Mini cas pratique

Aminata gère un service de livraison de repas à Abidjan, 2 500 transactions/mois via MTN MoMo et Wave. Avant, son taux de double-débit atteignait 2,1 %, soit environ 52 clients par mois débités deux fois, chacun réclamant un remboursement de 4 000 FCFA en moyenne : environ 208 000 FCFA à rembourser et un service client saturé. Après avoir ajouté la clé d'idempotence, la machine à états et le polling toutes les 5 s, le taux tombe à 0,05 %, soit 1 à 2 cas par mois. Elle économise environ 200 000 FCFA/mois et surtout sauve sa réputation, qui se jouait sur ces incidents.

FAQ

À quel niveau générer la clé d'idempotence ?

Au moment où le client valide son intention de payer, pas à chaque tentative. Toutes les relances de ce paiement réutilisent cette même clé, côté client et côté serveur.

Quand puis-je relancer un paiement en toute sécurité ?

Uniquement après avoir dépassé le délai de timeout de l'opérateur (60 à 120 s selon le cas) et confirmé via polling que l'état est failed. Jamais sur un état pending.

Toutes les 5 secondes, n'est-ce pas trop de polling ?

Non, c'est la fréquence standard et elle reste légère. L'important est d'arrêter le polling dès que l'état devient final pour ne pas surcharger inutilement.

Que faire d'un paiement bloqué en pending trop longtemps ?

Au-delà de la fenêtre de l'opérateur, on le marque failed et on propose au client un nouveau paiement avec une nouvelle clé, après avoir vérifié qu'aucun débit n'a eu lieu.

L'idempotence sert-elle aussi aux remboursements ?

Oui, exactement de la même façon : une clé unique par remboursement évite de rembourser deux fois lors d'un retry de l'opération de reversement.

Discutons de votre projet. On conçoit votre logique de retry avec idempotence et machine à états pour éliminer les double-débits. WhatsApp +221 77 596 93 33.