Accepter du Mobile Money en Afrique de l'Ouest francophone, ce n'est pas brancher un SDK Stripe et attendre un webhook propre cinq secondes plus tard. Chaque opérateur (Wave, Orange Money, MTN MoMo, Moov) a son propre flux d'autorisation, son propre format de callback, ses propres délais, et aucun standard commun ne les unifie. Le vrai travail d'ingénierie n'est pas d'appeler l'API d'initiation - c'est de construire une couche de réconciliation fiable autour de flux asynchrones et parfois silencieux.

Pourquoi ce n'est pas un problème de "plug-in Stripe"

Avec une carte bancaire, l'autorisation est synchrone : le paiement est accepté ou refusé en quelques centaines de millisecondes. Avec le Mobile Money, le paiement passe presque toujours par une confirmation côté utilisateur sur son téléphone - une invite USSD, une notification push à valider, ou un code PIN à saisir dans une application tierce. Entre l'appel API d'initiation et la confirmation réelle, il peut s'écouler quelques secondes ou plusieurs minutes, et le callback qui notifie le résultat n'est jamais garanti d'arriver une seule fois, dans l'ordre, ou même d'arriver du tout. L'identité du payeur, en plus, repose sur le numéro de téléphone plutôt que sur un identifiant de compte stable, ce qui introduit ses propres pièges de normalisation.

Le flux générique à construire

Indépendamment de l'opérateur, le squelette qui fonctionne en production suit toujours la même logique :

  1. Créer en base une transaction locale à l'état pending, avec une clé d'idempotence générée côté serveur.
  2. Appeler l'API d'initiation du provider avec cette clé et le numéro de téléphone, ce qui déclenche l'invite sur le téléphone du client.
  3. Stocker la référence externe renvoyée par le provider.
  4. Attendre le callback webhook qui confirme ou rejette la transaction, en vérifiant sa signature.
  5. Mettre à jour l'état local, en traitant les doublons comme un cas normal, pas une exception.
  6. Faire tourner un job de réconciliation périodique pour les transactions qui n'ont jamais reçu de callback.
// Contrôleur webhook générique (Node/Express)
// Chaque provider a son propre schéma de signature, mais le principe est identique :
// vérifier avant de faire confiance au corps de la requête.
const crypto = require('crypto');

app.post('/webhooks/mobile-money/:provider', express.raw({ type: '*/*' }), (req, res) => {
  const signatureHeader = req.headers['x-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))) {
    return res.status(401).send('invalid signature');
  }

  const payload = JSON.parse(req.body);
  // Toujours répondre 200 vite, traiter la logique métier en file d'attente
  queueTransactionReconciliation(req.params.provider, payload);
  res.status(200).send('ok');
});

Idempotence : le vrai cœur du problème

Les providers Mobile Money renvoient parfois le même callback deux ou trois fois - timeout réseau de leur côté, retry automatique, ou double notification pour un même événement. Si le traitement du webhook crédite un compte ou débloque une commande sans contrôle, un callback dupliqué peut créditer deux fois. La protection ne doit jamais dépendre uniquement de la logique applicative : une contrainte d'unicité en base sur le couple (provider, référence externe) est la seule garantie qui survit à un bug de code.

-- La contrainte d'unicité est la vraie barrière anti-doublon,
-- pas une simple vérification applicative avant insertion
CREATE UNIQUE INDEX idx_transactions_provider_ref
  ON transactions (provider, external_reference);

-- L'insertion échoue silencieusement sur un doublon plutôt que de dupliquer l'effet
INSERT INTO transactions (provider, external_reference, status, amount)
VALUES ($1, $2, $3, $4)
ON CONFLICT (provider, external_reference) DO NOTHING;

Diagnostiquer un paiement "fantôme"

Le symptôme classique en production : un client affirme avoir payé, mais la commande reste en attente côté application. Trois pistes systématiques avant de suspecter un bug :

  • Consulter les logs bruts des webhooks reçus (toujours les stocker tels quels, avant tout traitement, pour pouvoir les rejouer).
  • Interroger l'API de statut du provider avec la référence externe stockée, plutôt que de se fier uniquement au callback.
  • Vérifier la normalisation du numéro de téléphone - un numéro stocké au format local (07XXXXXXXX) ne correspondra jamais à un numéro renvoyé au format international (+225XXXXXXXXXX) dans une jointure ou une recherche de correspondance.
# Rejouer un webhook stocké pour déboguer en local
curl -X POST http://localhost:3000/webhooks/mobile-money/wave \
  -H "x-signature: $(cat stored_signature.txt)" \
  --data-binary @stored_payload.json

Le correctif : réconciliation comme filet de sécurité, pas comme option

Le webhook ne doit jamais être le seul mécanisme de vérité. Un job planifié qui interroge périodiquement le statut des transactions pending de plus de quelques minutes auprès de l'API du provider referme la boucle quand le callback s'est perdu. Le compromis est réel : chaque appel de réconciliation consomme un quota d'appels API, souvent limité (rate limiting) côté provider, donc la fréquence doit être calibrée - toutes les deux à cinq minutes pour les transactions récentes, en espaçant progressivement pour les plus anciennes, plutôt qu'un polling agressif constant.

Quand le webhook "simple" ne suffit pas

Chaque opérateur a ses propres aspérités qu'aucune documentation générique ne couvre entièrement :

  • Certains providers exigent une liste blanche d'IP pour accepter d'envoyer des callbacks vers un serveur donné, ce qui complique les déploiements multi-région ou les environnements de staging partagés.
  • D'autres ne garantissent pas de webhook du tout pour certains types de transaction et imposent un polling pur.
  • Le format et le nom des champs du callback (montant, devise, statut) diffèrent d'un opérateur à l'autre, ce qui impose une couche de normalisation interne plutôt que de propager les formats natifs dans le reste de l'application.
  • Un changement de numéro de téléphone côté client (réattribution de SIM, portabilité) peut invalider silencieusement un identifiant client supposé stable dans le cas de paiements récurrents.
  • En cas de panne partielle d'un opérateur, mieux vaut un circuit breaker qui bascule l'UX vers un message explicite ("Wave est temporairement indisponible, réessayez avec Orange Money") qu'une boucle de retry silencieuse qui multiplie les tentatives d'initiation côté client.

Tester sans argent réel

Les environnements de sandbox fournis par les opérateurs ne reproduisent jamais fidèlement le comportement de production. Le délai de confirmation y est souvent instantané ou constant, alors qu'il varie fortement en production selon la charge du réseau de l'opérateur et la réactivité du client à l'invite reçue sur son téléphone. Un code de traitement testé uniquement en sandbox peut donc sembler fiable alors qu'il n'a jamais été confronté à un callback qui arrive après trente secondes, ou à deux callbacks qui arrivent dans le désordre.

// Simuler des callbacks désordonnés et tardifs en local,
// plutôt que de ne tester que le chemin heureux de la sandbox
async function simulateDelayedCallback(payload, delayMs) {
  await new Promise((resolve) => setTimeout(resolve, delayMs));
  return fetch('http://localhost:3000/webhooks/mobile-money/wave', {
    method: 'POST',
    headers: { 'x-signature': signPayload(payload) },
    body: JSON.stringify(payload),
  });
}

// Deux envois volontairement dans le désordre et avec latence variable
simulateDelayedCallback(payload, 200);
simulateDelayedCallback(payload, 4000);

Un deuxième écart fréquent entre sandbox et production concerne les numéros de test : la plupart des opérateurs imposent une plage de numéros fictifs dédiés au sandbox, qui ne déclenchent jamais la validation réelle côté téléphone. Un parcours de test complet doit donc inclure, avant la mise en production, une phase de bascule progressive (feature flag par pourcentage d'utilisateurs ou par ville) avec de vrais numéros et de petits montants, pour observer le comportement réel des callbacks sans exposer l'ensemble de la base clients à un bug potentiel.

À retenir

L'intégration Mobile Money se construit comme un système distribué asynchrone, pas comme un paiement par carte : la fiabilité vient d'une clé d'idempotence de bout en bout, d'une contrainte d'unicité en base et d'un job de réconciliation qui ne dépend jamais uniquement du webhook. Les spécificités de chaque opérateur se gèrent en périphérie, jamais en laissant leurs formats natifs infuser le cœur applicatif.