Le verdict en trois phrases
Un bon SDK de paiement mobile n'expose qu'une seule interface (pay(), getStatus(), refund()) qui masque Wave, Orange Money et MTN derriere une machine a etats propre. Les trois piliers de fiabilite en Afrique : cles d'idempotence, retry avec backoff et file offline pour survivre a la 3G faible. Sans ces trois elements, vous doublez les paiements ou en perdez la confirmation.
La machine a etats a 5 statuts
Tout paiement passe par un cycle de vie strict. Chaque transition doit etre idempotente et journalisee.
| Statut | Signification | Action suivante |
|---|---|---|
| initiated | requete creee, cle d'idempotence posee | envoyer a l'operateur |
| pending | en attente de validation client | polling / webhook |
| success | confirme cote serveur | valider la commande |
| failed | refuse (solde, timeout, PIN) | proposer un autre rail |
| refunded | rembourse via API | crediter le client |
Regle absolue : ne passez a success que sur confirmation serveur signee, jamais sur le retour navigateur. Une transition mal geree entre pending et success est la premiere cause de bugs comptables.
Reglages de fiabilite recommandes (2026)
Les parametres qui rendent le SDK robuste sur reseau instable.
| Parametre | Valeur recommandee | Pourquoi |
|---|---|---|
| Timeout paiement | 90 s | couvre OTP + validation |
| Tentatives max | 3 | evite le spam operateur |
| Backoff | 2 s, 4 s, 8 s | exponentiel |
| Intervalle polling | 200 ms -> 5 s | rapide puis espace |
| Verif signature webhook | HMAC obligatoire | anti-fraude |
| File offline | persistante (SQLite) | survit a la coupure 3G |
La cle d'idempotence (une par transaction) garantit qu'un retry ne cree jamais un second debit. C'est le point le plus critique sur reseau africain instable, ou une requete peut aboutir cote serveur sans que le client recoive la reponse.
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
Aminata developpe une app de livraison a Dakar. Sans file offline, 8 % des paiements echouaient sur coupure 3G en zone peri-urbaine, soit sur 500 transactions/mois a 5 000 XOF : 40 paiements perdus = 200 000 XOF de chiffre non encaisse. Apres ajout de la file offline persistante et du retry avec backoff, le taux d'echec tombe a 1,5 %, soit ~8 paiements perdus. Elle recupere ~160 000 XOF/mois pour un jour de developpement supplementaire.
FAQ
Pourquoi une cle d'idempotence est-elle indispensable ? Sur 3G instable, une requete peut aboutir sans que la reponse revienne. Sans cle d'idempotence, le retry cree un second debit. C'est non-negociable.
Quel timeout choisir ? 90 s couvre la saisie OTP et la validation operateur. En dessous de 60 s, vous coupez des clients legitimes sur reseau lent.
La file offline est-elle vraiment utile ? Oui : elle persiste les paiements en attente en SQLite et les rejoue a la reconnexion. Elle reduit typiquement le taux d'echec de 8 % a moins de 2 %.
Combien de tentatives de retry ? 3 maximum avec backoff exponentiel (2 s, 4 s, 8 s). Au-dela, vous risquez de saturer l'operateur et d'etre limite.
Faut-il verifier la signature du webhook ? Toujours. Une verification HMAC empeche un attaquant de forger une confirmation de paiement. Un webhook non signe ne doit jamais valider une commande.
Discutons de votre projet. Nous construisons votre SDK de paiement Flutter multi-operateurs, idempotent et resilient a la 3G. 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.
