Introduction
Après plus de 7 ans à concevoir des architectures backend, l'un des chantiers les plus exigeants que j'ai rencontrés est l'interopérabilité financière : faire dialoguer plusieurs providers de paiement (mobile money, banques, agrégateurs) au sein d'une même plateforme, de manière fiable et évolutive.
Cet article résume les défis concrets rencontrés et les approches qui fonctionnent en production.
1. La fragmentation des standards
Chaque opérateur de paiement mobile en Afrique (Orange Money, MTN MoMo, Moov Money, Wave...) expose une API différente : formats de requêtes, codes d'erreur, mécanismes d'authentification, et même sémantique des statuts de transaction ne sont jamais alignés.
Approche retenue : construire une couche d'abstraction (adapter pattern) où chaque provider implémente une interface commune (initiatePayment, checkStatus, refund), plutôt que de laisser la logique métier dépendre directement des spécificités de chaque API.
interface PaymentProviderInterface
{
public function initiate(PaymentRequest $request): PaymentResponse;
public function checkStatus(string $transactionId): PaymentStatus;
public function refund(string $transactionId, ?int $amount = null): RefundResponse;
}Chaque implémentation concrète (OrangeMoneyProvider, MtnMomoProvider, ...) traduit les spécificités du provider vers ce contrat commun.
2. La gestion de l'asynchronisme et des webhooks
La majorité des opérateurs confirment une transaction de façon asynchrone via webhook, avec des délais variables (de quelques secondes à plusieurs minutes) et parfois des retries multiples pour un même événement.
Points de vigilance :
- Idempotence : chaque webhook doit être traité une seule fois, même reçu plusieurs fois (stockage d'un identifiant unique d'événement avec contrainte d'unicité en base).
- Timeout et polling de secours : ne jamais dépendre uniquement du webhook — prévoir un job de vérification périodique du statut auprès du provider en cas de non-réception.
- Ordre des événements : un webhook "échec" peut arriver après un webhook "succès" mal formé côté provider ; la logique de réconciliation doit être capable de trancher.
3. La réconciliation financière
Au-delà de l'intégration technique, la vraie difficulté est de garantir que ce qui est enregistré dans le système correspond exactement à ce que le provider a réellement traité, en particulier lors d'incidents (timeout, double envoi, panne réseau).
Il est essentiel de mettre en place :
- des jobs de réconciliation automatique confrontant les transactions internes aux relevés/API du provider ;
- des tableaux de bord d'écarts, pour que l'équipe finance/support puisse investiguer rapidement les anomalies ;
- un journal d'audit immuable de chaque changement de statut de transaction.
4. La gestion des erreurs et des cas limites
Chaque provider a ses propres codes d'erreur, souvent peu documentés. Il faut construire un mapping robuste vers des statuts internes normalisés (PENDING, SUCCESS, FAILED, EXPIRED, UNKNOWN), et prévoir un état UNKNOWN explicite pour les cas où le provider ne permet pas de trancher — plutôt que de forcer un statut binaire risqué.
Ce que je retiens
Construire une plateforme d'interopérabilité financière fiable, ce n'est pas seulement "brancher des API" : c'est concevoir un système résilient à l'incertitude, où chaque composant (abstraction, idempotence, réconciliation, monitoring) protège contre les défaillances inévitables des tiers.
Dans un prochain article, je détaillerai l'architecture concrète mise en place chez MAGMASEND autour de Laravel et Filament pour gérer cette complexité.