Intégrer le paiement mobile (mobile money) dans une application web

En Afrique de l’Ouest francophone, la vraie question n’est pas « Visa ou Mastercard ? » mais « Wave, Orange Money ou Mixx by Yas ? ». Le mobile money est devenu le moyen de paiement par défaut, et tôt ou tard, tout développeur qui construit une boutique, un SaaS ou une billetterie doit l’encaisser. L’objectif de cet article est concret : comprendre vos options d’intégration, puis encaisser un premier paiement avec un exemple de code réel.

Le paysage : Wave, Orange Money, Mixx by Yas

Trois acteurs dominent le marché sénégalais. Wave s’est imposé grâce à des transferts entre particuliers gratuits et des frais marchands réduits. Orange Money conserve une très large base d’utilisateurs. Free Money a été rebaptisé Mixx by Yas fin novembre 2024, dans le cadre du repositionnement panafricain du groupe Axian. À côté, les cartes bancaires restent minoritaires pour le grand public.

La conséquence pratique est nette : proposer uniquement la carte, c’est se couper de la majorité de vos clients. Il faut accepter le mobile money — et de préférence plusieurs opérateurs.

Agrégateur ou API directe ?

Deux stratégies s’offrent à vous, et le choix tient surtout au temps disponible et au volume visé.

• L’agrégateur (PayDunya à Dakar, CinetPay à Abidjan…) expose Wave, Orange Money, Mixx by Yas, MTN MoMo et la carte derrière une seule API, avec webhooks et souvent un plugin WooCommerce prêt à l’emploi. Vous intégrez une fois, vous encaissez partout. C’est la voie la plus rapide pour démarrer.
• L’API directe d’un opérateur — par exemple l’API Wave Checkout, ou l’API Orange Money Web Payment — supprime l’intermédiaire et sa commission, mais vous gérez alors chaque opérateur séparément, avec sa propre mise en conformité.

Règle simple : commencez par un agrégateur pour valider votre produit, passez à l’API directe quand le volume justifie d’économiser la commission. N’optimisez pas un coût que vous n’avez pas encore.

Exemple concret : encaisser avec l’API Wave Checkout

Le principe est celui de la plupart des passerelles : votre serveur crée une « session de paiement », l’utilisateur est redirigé vers une page hébergée par Wave, puis revient sur votre site. La clé d’API se gère depuis le portail Wave Business et ne quitte jamais le navigateur : elle reste strictement côté serveur.

On crée la session avec un appel POST authentifié par un jeton Bearer :

curl -X POST https://api.wave.com/v1/checkout/sessions 
  -H "Authorization: Bearer $WAVE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "amount": "5000",
    "currency": "XOF",
    "success_url": "https://mon-site.sn/paiement/succes",
    "error_url": "https://mon-site.sn/paiement/echec",
    "client_reference": "commande-1042"
  }'

La réponse contient un identifiant de session (champ id, de la forme cos-…) et, surtout, une URL hébergée — wave_launch_url — vers laquelle rediriger le client :

{
  "id": "cos-18qq25rgr100a",
  "wave_launch_url": "https://pay.wave.com/c/cos-18qq25rgr100a",
  "checkout_status": "open",
  "payment_status": "processing",
  "currency": "XOF"
}

Côté serveur (ici en PHP), il suffit alors de rediriger l’utilisateur vers cette URL :

$session = json_decode($reponse, true);
header('Location: ' . $session['wave_launch_url']);
exit;

Ne faites jamais confiance à la redirection de retour

Le piège classique consiste à marquer la commande « payée » dès que l’utilisateur revient sur l’success_url. Or cette redirection est déclenchée par le navigateur : elle est donc falsifiable. La seule source de vérité est le webhook envoyé de serveur à serveur par Wave (ou par votre agrégateur) lorsque le paiement aboutit réellement.

Trois réflexes pour un webhook fiable :

• Vérifier la signature de chaque webhook avant d’y croire, et rejeter toute requête non signée.
• Rester idempotent : un même événement peut arriver deux fois ; identifiez-le par sa référence et ne créditez la commande qu’une seule fois.
• Revalider le montant et la devise reçus contre votre commande, au lieu de faire confiance aux paramètres de l’URL.

Les pièges fréquents

• Exposer la clé d’API côté client (dans le JavaScript) : elle doit rester sur le serveur, dans une variable d’environnement.
• Confondre les clés de test et de production : préfixez-les et isolez-les par environnement.
• Oublier les paiements abandonnés ou expirés : une session a une durée de vie limitée (statut expired).
• Manipuler les montants en nombres flottants : travaillez en entiers (le franc CFA n’a pas de centimes) pour éviter les erreurs d’arrondi.

Récapitulatif

Pour encaisser en ligne en Afrique de l’Ouest : acceptez le mobile money, pas seulement la carte. Démarrez avec un agrégateur — une intégration, tous les opérateurs — puis basculez vers l’API directe quand le volume le justifie. Et surtout, ne validez jamais une commande sur la simple redirection du navigateur : attendez un webhook signé et vérifié.

Sources

• Wave — Documentation officielle « Checkout API » (consulté le 16/06/2026)
• Axian Telecom — lancement des marques Yas et Mixx by Yas (26/11/2024)
• PayDunya — Documentation développeurs

Pour aller plus loin

• Sécuriser une API REST — JWT, HTTPS et bonnes pratiques OWASP.
• Déployer sa première application avec Docker — conteneuriser et mettre votre projet en production.