MTN MoMo & Orange Money : intégrer le paiement mobile dans une app React

MTN MoMo et Orange Money sont incontournables pour toute app e-commerce ou SaaS destinée au marché camerounais. Voici le guide technique qu'on aurait aimé avoir quand on a commencé — basé sur notre expérience réelle en production.

Architecture recommandée

Ne jamais appeler l'API Mobile Money directement depuis le frontend. Toujours passer par votre backend Node.js ou FastAPI. Cela protège vos clés API, vous permet de logger les transactions, et gère les cas où l'utilisateur ferme son navigateur avant la confirmation.

// Backend Node.js — initier un paiement MTN MoMo
const initPayment = async (amount, phoneNumber, externalId) => {
  const token = await getAccessToken(); // Bearer token OAuth2
  
  const response = await axios.post(
    'https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttopay',
    {
      amount: amount.toString(),
      currency: 'XAF',
      externalId,
      payer: { partyIdType: 'MSISDN', partyId: phoneNumber },
      payerMessage: 'Paiement Nova',
      payeeNote: 'Service Nova Cameroun',
    },
    {
      headers: {
        Authorization: `Bearer ${token}`,
        'X-Reference-Id': externalId,
        'X-Target-Environment': 'sandbox',
        'Ocp-Apim-Subscription-Key': process.env.MTN_SUBSCRIPTION_KEY,
      },
    }
  );
  
  return response.headers['x-reference-id'];
};

Le piège de la sandbox MTN

La sandbox MTN MoMo est instable par nature : elle simule des délais et des échecs aléatoires pour reproduire les conditions réelles. Ne testez jamais votre logique de retry uniquement en sandbox — vous risquez de conclure que votre code est défaillant alors qu'il s'agit d'un comportement intentionnel de l'environnement de test.

Gestion des webhooks

MTN MoMo envoie un webhook à votre endpoint quand la transaction change de statut. En production, ces webhooks peuvent arriver avec plusieurs minutes de délai. Ne bloquez jamais l'utilisateur en attendant le webhook — retournez immédiatement un statut "en attente" et mettez à jour l'UI via polling ou WebSocket quand la confirmation arrive.

Orange Money : différences clés

L'API Orange Money Cameroun utilise un flux d'authentification différent de MTN. Elle requiert une validation par numéro USSD côté utilisateur dans certains cas. Anticipez une UX légèrement différente selon l'opérateur : MTN confirme souvent par notification push, Orange demande parfois une confirmation USSD.