Intégrer une API de paiement en Afrique : bonnes pratiques

Intégrer une API de paiement n'a rien de trivial — surtout en Afrique, où vous devez gérer plusieurs devises, plusieurs opérateurs Mobile Money et une connectivité parfois instable. Voici les bonnes pratiques que nous recommandons à tous les développeurs qui intègrent l'API XPay. Elles s'appliquent quelle que soit la passerelle utilisée.

1. Traitez tout comme idempotent

Un webhook peut être livré plusieurs fois. Un utilisateur peut cliquer deux fois sur "Payer". Chaque opération de paiement doit avoir un identifiant unique (order_id, transaction_id) que vous vérifiez avant d'insérer en base. Utilisez une contrainte UNIQUE côté DB — c'est votre dernière ligne de défense.

2. Signez et vérifiez vos webhooks

Ne faites jamais confiance à un webhook non signé. XPay signe chaque webhook avec HMAC-SHA256 et votre clé secrète. Vérifiez la signature avec timingSafeEqual — jamais avec ===, qui expose à des attaques par timing. Ajoutez aussi un contrôle de timestamp : rejetez tout payload dont la date de signature est supérieure à 5 minutes pour empêcher les rejeux.

3. Séparez clés publiques et clés secrètes

• Publishable key (pk_...) : côté frontend, initialise le checkout. Peut apparaître dans le code source.
• Secret key (sk_...) : côté serveur uniquement, jamais commit, jamais dans une variable VITE_* ou NEXT_PUBLIC_*.

En cas de fuite, régénérez la clé depuis votre console API — la rotation est instantanée.

4. Testez en sandbox avant la prod

XPay fournit un environnement de test complet avec des numéros Mobile Money fictifs. Testez les cas heureux ET les cas d'échec : timeout, PIN invalide, solde insuffisant, webhook rejoué, double-clic. Un paiement en production qui échoue silencieusement est mille fois pire qu'un paiement qui échoue proprement.

5. Gérez les devises côté serveur

Ne convertissez jamais USD ↔ CDF côté client. Le taux change, un attaquant peut le manipuler dans les DevTools. Chez XPay, le règlement est en USD et le wallet CDF est dérivé côté serveur au taux du jour. Un client qui envoie amount=1 et currency=USD ne peut pas prétendre avoir payé amount=1 et currency=CDF.

6. Logs et observabilité

Loggez chaque appel API avec l'ID de corrélation (X-Request-Id). En cas d'incident, vous devez pouvoir reconstruire la vie d'un paiement en quelques secondes : quelle requête, quel webhook, quelle réponse, à quelle seconde exactement. Sans corrélation, un debug prend des heures ; avec, il prend deux minutes.

7. Gérez les timeouts et les retries

Sur un réseau africain moyen, un appel API peut mettre 3 à 8 secondes. Prévoyez un timeout côté client de 30 secondes, un retry exponentiel avec jitter, et un fallback qui rassure le client au lieu de le laisser bloqué sur un spinner.

8. Traitez les webhooks de façon asynchrone

Répondez 200 OK immédiatement au webhook, puis traitez le job dans une file (Redis, Postgres LISTEN/NOTIFY). Sinon, un traitement lent peut faire retry le webhook et créer des doubles paiements.

Aller plus loin

La documentation XPay détaille chaque endpoint avec des exemples cURL, Node.js et Python. Pour un tour d'horizon complet, lisez aussi notre guide d'intégration Mobile Money RDC, et notre article 10 réflexes de sécurité.