Pourquoi Orange Money Web Payment domine au Sénégal
Orange Money concentre la majorité des paiements mobiles au Sénégal. Pour un site e-commerce ou un service en ligne, intégrer l'API Web Payment (WebPay) est souvent la première brique de monétisation. Ce guide couvre le flow réel : obtention des clés, génération du token d'accès, initiation d'un paiement, redirection du client, puis vérification du statut.
L'API repose sur deux appels principaux : un appel OAuth pour obtenir un jeton d'accès, puis un appel d'initiation qui renvoie une URL de paiement. Le client est redirigé vers cette URL, paie depuis son application Orange Money ou par code USSD, puis revient sur votre site.
Onboarding marchand : les étapes
L'accès production demande une validation marchande. Comptez 5 à 15 jours ouvrés selon la complétude du dossier.
| Étape | Action | Livrable | Délai indicatif |
|---|---|---|---|
| 1 | Créer un compte sur le portail développeur Orange | Compte validé | 1 jour |
| 2 | Soumettre le dossier KYC entreprise (RCCM, NINEA) | Dossier accepté | 2 à 5 jours |
| 3 | Recevoir les clés sandbox | client_id + client_secret test | immédiat |
| 4 | Intégrer et tester en sandbox | Transactions test réussies | 2 à 4 jours |
| 5 | Demander le passage en production | Clés prod activées | 3 à 7 jours |
Clés à sécuriser
Vous recevez un couple client_id et client_secret. Ces valeurs ne doivent jamais apparaître côté navigateur : tout appel à l'API passe par votre serveur (backend). Stockez-les en variables d'environnement, jamais dans le code source versionné.
Le flow de paiement en 5 temps
- Le serveur appelle POST /oauth/token pour obtenir un access_token (valable environ 1 heure).
- Le serveur appelle POST /webpayment avec le montant et les URL de retour pour obtenir une payment_url et un token de transaction.
- Le navigateur redirige le client vers là payment_url.
- Le client paie ; Orange redirige vers vôtre return_url (et notifie éventuellement vôtre notif_url).
- Le serveur vérifie le statut via le pay_token avant de valider la commande.
Règle d'or : ne validez jamais une commande sur la seule redirection navigateur. Confirmez toujours côté serveur le statut SUCCESS.
Paramètres de la requête d'initiation
L'appel POST /webpayment attend un corps JSON. Voici les champs clés.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| merchant_key | chaîne | oui | Clé marchand fournie à l'onboarding |
| currency | chaîne | oui | Devise, OUV en sandbox, XOF en prod |
| order_id | chaîne | oui | Identifiant unique de commande côté marchand |
| amount | entier | oui | Montant en FCFA, sans décimales |
| return_url | url | oui | Page de retour après paiement réussi |
| cancel_url | url | oui | Page de retour si annulation |
| notif_url | url | oui | URL serveur à serveur pour notification de statut |
| lang | chaîne | non | Langue de la page de paiement, fr ou en |
| référence | chaîne | non | Référence libre affichée au client |
Réponse attendue
La réponse contient un pay_token, une payment_url et un notif_token. Conservez l'order_id et le pay_token en base : ils servent à réconcilier le paiement.
| Champ retourné | Type | Usage |
|---|---|---|
| pay_token | chaîne | Vérification du statut de la transaction |
| payment_url | url | URL de redirection du client |
| notif_token | chaîne | Jeton inclus dans la notification serveur |
Environnements test et production
Les deux environnements ont des URL de base et des devises différentes. Ne mélangez jamais des clés sandbox avec l'URL de prod.
| Élément | Sandbox | Production |
|---|---|---|
| Devise | OUV | XOF |
| Montants | Fictifs, non débités | Reels, débités |
| Numéro de test | Fourni dans la console | Numéro client réel |
| Validation marchande | Non requise | Requise |
| Limite de débit | Aucune | Plafonds Orange Money |
Test sans dépenser
Besoin d'un site web professionnel ?
Kolonell crée des sites web qui attirent des clients, optimisés pour le marché sénégalais. Devis gratuit en 2 minutes.
En sandbox, Orange fournit un numéro et un code PIN de test qui simulent un paiement réussi ou échoue. Validez au minimum trois scénarios : succès, annulation utilisateur, et expiration du token.
Codes d'erreur à gérer
Votre backend doit traiter explicitement les erreurs. Un mapping clair évite les commandes fantômes.
| Code / statut | Signification | Action recommandée |
|---|---|---|
| INITIATED | Paiement crée, en attente | Afficher l'attente, ne pas valider |
| PENDING | Client en cours de paiement | Relancer la vérification après délai |
| SUCCESS | Paiement confirmé | Valider la commande |
| FAILED | Paiement échoué | Proposer un nouvel essai |
| EXPIRED | Token expiré | Réinitier une transaction |
| 401 | Token OAuth invalide ou expiré | Régénérer l'access_token |
| 400 | Paramètre manquant ou invalide | Logger et corriger le corps de requête |
Exemple de bout en bout
Cas concret : une boutique vend un sac à 25 000 FCFA. Le backend génère un order_id KOL-2026-0421, appelle POST /oauth/token, reçoit un access_token, puis appelle POST /webpayment avec amount 25000, currency XOF, return_url vers la page de confirmation et notif_url vers /api/orange/notif. Orange renvoie une payment_url. Le client est redirigé, paie, revient sur la page de confirmation. En parallèle, Orange appelle /api/orange/notif avec le statut SUCCESS et le notif_token. Le backend vérifie le notif_token, contrôle le statut via le pay_token, puis passe la commande de PENDING à PAID. Total côté serveur : deux appels sortants et une notification entrante.
Sécurité et bonnes pratiques
- Idempotence : un même order_id ne doit jamais créer deux paiements validés.
- Vérification serveur obligatoire avant toute livraison ou activation.
- HTTPS strict sur toutes les URL de retour et de notification.
- Journalisation de chaque transition de statut pour le support.
- Timeout côté backend : si aucune notification après 15 minutes, marquer EXPIRED.
FAQ
Peut-on intégrer Orange Money sans serveur backend ?
Non. Le client_secret et la génération du token doivent rester côté serveur. Une intégration 100 pour cent front exposerait vos clés et serait rejetée en production.
Quelle devise utiliser en sandbox ?
La devise OUV en sandbox, et XOF en production. Inverser les deux est l'erreur la plus fréquente lors du passage en prod.
Faut-il attendre la notif_url ou la redirection suffit ?
La notif_url serveur à serveur fait foi. La redirection navigateur peut être perdue si le client ferme l'onglet. Validez toujours via la notification et la vérification de statut.
Combien de temps est valable l'access_token ?
Environ une heure. Générez-le à la demande et mettez-le en cache côté serveur jusqu'à expiration plutôt que de le régénérer à chaque requête.
Comment tester un échec de paiement ?
La console sandbox fournit un PIN dédié qui force un statut FAILED. Testez ce scénario pour valider votre gestion d'erreur avant la prod.
Discutons de votre projet. Kolonell intègre Orange Money, Wave et Stripe sur des sites e-commerce rapides et sécurisés au Sénégal. WhatsApp +221 77 596 93 33.
Mohamed Bah
Fondateur, Kolonell
Passionné par le digital et l'entrepreneuriat en Afrique, Mohamed accompagne les entreprises sénégalaises dans leur transformation digitale depuis 2020. Fondateur de Kolonell, il croit que chaque PME mérite une présence en ligne professionnelle et accessible.
