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 derrière une machine à états propre. Les trois piliers de fiabilité en Afrique : clés d'idempotence, retry avec backoff et file offline pour survivre à la 3G faible. Sans ces trois éléments, vous doublez les paiements ou en perdez la confirmation.
La machine à états à 5 statuts
Tout paiement passe par un cycle de vie strict. Chaque transition doit être idempotente et journalisée.
| Statut | Signification | Action suivante |
|---|---|---|
| initiated | requête créée, clé d'idempotence posée | envoyer à l'opérateur |
| pending | en attente de validation client | polling / webhook |
| success | confirmé côté serveur | valider la commande |
| failed | refusé (solde, timeout, PIN) | proposer un autre rail |
| refunded | rembourse via API | créditer le client |
Règle absolue : ne passez à success que sur confirmation serveur signée, jamais sur le retour navigateur. Une transition mal gérée entre pending et success est la première cause de bugs comptables.
Réglages de fiabilité recommandés (2026)
Les paramètres qui rendent le SDK robuste sur réseau instable.
| Paramètre | Valeur recommandée | Pourquoi |
|---|---|---|
| Timeout paiement | 90 s | couvre OTP + validation |
| Tentatives max | 3 | évite le spam opérateur |
| Backoff | 2 s, 4 s, 8 s | exponentiel |
| Intervalle polling | 200 ms -> 5 s | rapide puis espace |
| Vérif signature webhook | HMAC obligatoire | anti-fraude |
| File offline | persistante (SQLite) | survit à la coupure 3G |
La clé d'idempotence (une par transaction) garantit qu'un retry ne crée jamais un second débit. C'est le point le plus critique sur réseau africain instable, ou une requête peut aboutir côté serveur sans que le client reçoive la réponse.
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 développe une app de livraison à Dakar. Sans file offline, 8 % des paiements échouaient sur coupure 3G en zone péri-urbaine, soit sur 500 transactions/mois à 5 000 XOF : 40 paiements perdus = 200 000 XOF de chiffre non encaissé. Après ajout de la file offline persistante et du retry avec backoff, le taux d'échec tombe à 1,5 %, soit ~8 paiements perdus. Elle récupère ~160 000 XOF/mois pour un jour de développement supplémentaire.
FAQ
Pourquoi une clé d'idempotence est-elle indispensable ? Sur 3G instable, une requête peut aboutir sans que la réponse revienne. Sans clé d'idempotence, le retry crée un second débit. C'est non-négociable.
Quel timeout choisir ? 90 s couvre la saisie OTP et la validation opérateur. En dessous de 60 s, vous coupez des clients légitimes sur réseau lent.
La file offline est-elle vraiment utile ? Oui : elle persiste les paiements en attente en SQLite et les rejoue à la reconnexion. Elle réduit typiquement le taux d'échec de 8 % à moins de 2 %.
Combien de tentatives de retry ? 3 maximum avec backoff exponentiel (2 s, 4 s, 8 s). Au-delà, vous risquez de saturer l'opérateur et d'être limité.
Faut-il vérifier la signature du webhook ? Toujours. Une vérification HMAC empêche un attaquant de forger une confirmation de paiement. Un webhook non signé ne doit jamais valider une commande.
Discutons de votre projet. Nous construisons votre SDK de paiement Flutter multi-opérateurs, idempotent et résilient à 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.
