Logique de retry pour transactions mobile money echouees : idempotence et etats

Le verdict en trois phrases

Le retry est indispensable, mais mal fait il est pire que l'echec : sans cle d'idempotence, chaque relance risque de debiter le client une seconde fois. La bonne architecture repose sur trois piliers : une cle d'idempotence par intention de paiement, une machine a etats explicite, et un polling de statut avant toute relance. Correctement implementee, elle fait tomber le double-debit de 2,1 % a 0,05 % sans perdre les paiements lents.

La cle d'idempotence, premier reflexe

Une cle d'idempotence est un identifiant unique attache a l'intention de paiement du client (pas a la tentative). Toutes les relances d'un meme paiement portent la meme cle. L'operateur et votre serveur peuvent ainsi reconnaitre qu'il s'agit de la meme transaction et ne pas la rejouer.

Sans cette cle, un client qui recharge la page ou dont le reseau relance la requete se fait debiter deux fois. Avec elle, la seconde requete renvoie simplement le resultat de la premiere.

La machine a etats

Chaque paiement suit un cycle de vie strict. On ne relance jamais un paiement dont l'etat est deja final (success ou reversed). On ne poll que les etats intermediaires.

Cette discipline evite 90 % des incidents : la plupart des double-debits viennent d'un retry lance alors que le paiement etait encore pending.

Delai de timeout et frequence de polling par operateur

Chaque operateur a sa propre fenetre de confirmation. Poller trop tot ou relancer avant le timeout genere des doublons ; attendre trop longtemps degrade l'experience client. Voici les ordres de grandeur 2026.

Regle : ne relancez jamais avant d'avoir depasse le delai de timeout de l'operateur et confirme via polling que l'etat est bien failed.

Mini cas pratique

Aminata gere un service de livraison de repas a Abidjan, 2 500 transactions/mois via MTN MoMo et Wave. Avant, son taux de double-debit atteignait 2,1 %, soit environ 52 clients par mois debites deux fois, chacun reclamant un remboursement de 4 000 FCFA en moyenne : environ 208 000 FCFA a rembourser et un service client sature. Apres avoir ajoute la cle d'idempotence, la machine a etats et le polling toutes les 5 s, le taux tombe a 0,05 %, soit 1 a 2 cas par mois. Elle economise environ 200 000 FCFA/mois et surtout sauve sa reputation, qui se jouait sur ces incidents.

FAQ

A quel niveau generer la cle d'idempotence ?

Au moment ou le client valide son intention de payer, pas a chaque tentative. Toutes les relances de ce paiement reutilisent cette meme cle, cote client et cote serveur.

Quand puis-je relancer un paiement en toute securite ?

Uniquement apres avoir depasse le delai de timeout de l'operateur (60 a 120 s selon le cas) et confirme via polling que l'etat est failed. Jamais sur un etat pending.

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

Non, c'est la frequence standard et elle reste legere. L'important est d'arreter le polling des que l'etat devient final pour ne pas surcharger inutilement.

Que faire d'un paiement bloque en pending trop longtemps ?

Au-dela de la fenetre de l'operateur, on le marque failed et on propose au client un nouveau paiement avec une nouvelle cle, apres avoir verifie qu'aucun debit n'a eu lieu.

L'idempotence sert-elle aussi aux remboursements ?

Oui, exactement de la meme facon : une cle unique par remboursement evite de rembourser deux fois lors d'un retry de l'operation de reversement.

Discutons de votre projet. On concoit votre logique de retry avec idempotence et machine a etats pour eliminer les double-debits. WhatsApp +221 77 596 93 33.