Pourquoi Orange Money Web Payment domine au Senegal
Orange Money concentre la majorite des paiements mobiles au Senegal. Pour un site e-commerce ou un service en ligne, integrer l API Web Payment (WebPay) est souvent la premiere brique de monetisation. Ce guide couvre le flow reel : obtention des cles, generation du token d acces, initiation d un paiement, redirection du client, puis verification du statut.
L API repose sur deux appels principaux : un appel OAuth pour obtenir un jeton d acces, puis un appel d initiation qui renvoie une URL de paiement. Le client est redirige vers cette URL, paie depuis son application Orange Money ou par code USSD, puis revient sur votre site.
Onboarding marchand : les etapes
L acces production demande une validation marchande. Comptez 5 a 15 jours ouvres selon la completude du dossier.
| Etape | Action | Livrable | Delai indicatif |
|---|---|---|---|
| 1 | Creer un compte sur le portail developpeur Orange | Compte valide | 1 jour |
| 2 | Soumettre le dossier KYC entreprise (RCCM, NINEA) | Dossier accepte | 2 a 5 jours |
| 3 | Recevoir les cles sandbox | client_id + client_secret test | immediat |
| 4 | Integrer et tester en sandbox | Transactions test reussies | 2 a 4 jours |
| 5 | Demander le passage en production | Cles prod activees | 3 a 7 jours |
Cles a securiser
Vous recevez un couple client_id et client_secret. Ces valeurs ne doivent jamais apparaitre cote navigateur : tout appel a l API passe par votre serveur (backend). Stockez-les en variables d environnement, jamais dans le code source versionne.
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 la payment_url.
- Le client paie ; Orange redirige vers votre return_url (et notifie eventuellement votre notif_url).
- Le serveur verifie le statut via le pay_token avant de valider la commande.
Regle d or : ne validez jamais une commande sur la seule redirection navigateur. Confirmez toujours cote serveur le statut SUCCESS.
Parametres de la requete d initiation
L appel POST /webpayment attend un corps JSON. Voici les champs cles.
| Parametre | Type | Obligatoire | Description |
|---|---|---|---|
| merchant_key | chaine | oui | Cle marchand fournie a l onboarding |
| currency | chaine | oui | Devise, OUV en sandbox, XOF en prod |
| order_id | chaine | oui | Identifiant unique de commande cote marchand |
| amount | entier | oui | Montant en FCFA, sans decimales |
| return_url | url | oui | Page de retour apres paiement reussi |
| cancel_url | url | oui | Page de retour si annulation |
| notif_url | url | oui | URL serveur a serveur pour notification de statut |
| lang | chaine | non | Langue de la page de paiement, fr ou en |
| reference | chaine | non | Reference libre affichee au client |
Reponse attendue
La reponse contient un pay_token, une payment_url et un notif_token. Conservez l order_id et le pay_token en base : ils servent a reconcilier le paiement.
| Champ retourne | Type | Usage |
|---|---|---|
| pay_token | chaine | Verification du statut de la transaction |
| payment_url | url | URL de redirection du client |
| notif_token | chaine | Jeton inclus dans la notification serveur |
Environnements test et production
Les deux environnements ont des URL de base et des devises differentes. Ne melangez jamais des cles sandbox avec l URL de prod.
| Element | Sandbox | Production |
|---|---|---|
| Devise | OUV | XOF |
| Montants | Fictifs, non debites | Reels, debites |
| Numero de test | Fourni dans la console | Numero client reel |
| Validation marchande | Non requise | Requise |
| Limite de debit | Aucune | Plafonds Orange Money |
Test sans depenser
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 numero et un code PIN de test qui simulent un paiement reussi ou echoue. Validez au minimum trois scenarios : succes, annulation utilisateur, et expiration du token.
Codes d erreur a gerer
Votre backend doit traiter explicitement les erreurs. Un mapping clair evite les commandes fantomes.
| Code / statut | Signification | Action recommandee |
|---|---|---|
| INITIATED | Paiement cree, en attente | Afficher l attente, ne pas valider |
| PENDING | Client en cours de paiement | Relancer la verification apres delai |
| SUCCESS | Paiement confirme | Valider la commande |
| FAILED | Paiement echoue | Proposer un nouvel essai |
| EXPIRED | Token expire | Reinitier une transaction |
| 401 | Token OAuth invalide ou expire | Regenerer l access_token |
| 400 | Parametre manquant ou invalide | Logger et corriger le corps de requete |
Exemple de bout en bout
Cas concret : une boutique vend un sac a 25 000 FCFA. Le backend genere un order_id KOL-2026-0421, appelle POST /oauth/token, recoit 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 redirige, paie, revient sur la page de confirmation. En parallele, Orange appelle /api/orange/notif avec le statut SUCCESS et le notif_token. Le backend verifie le notif_token, controle le statut via le pay_token, puis passe la commande de PENDING a PAID. Total cote serveur : deux appels sortants et une notification entrante.
Securite et bonnes pratiques
- Idempotence : un meme order_id ne doit jamais creer deux paiements valides.
- Verification 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 cote backend : si aucune notification apres 15 minutes, marquer EXPIRED.
FAQ
Peut-on integrer Orange Money sans serveur backend ?
Non. Le client_secret et la generation du token doivent rester cote serveur. Une integration 100 pour cent front exposerait vos cles et serait rejetee en production.
Quelle devise utiliser en sandbox ?
La devise OUV en sandbox, et XOF en production. Inverser les deux est l erreur la plus frequente lors du passage en prod.
Faut-il attendre la notif_url ou la redirection suffit ?
La notif_url serveur a serveur fait foi. La redirection navigateur peut etre perdue si le client ferme l onglet. Validez toujours via la notification et la verification de statut.
Combien de temps est valable l access_token ?
Environ une heure. Generez-le a la demande et mettez-le en cache cote serveur jusqu a expiration plutot que de le regenerer a chaque requete.
Comment tester un echec de paiement ?
La console sandbox fournit un PIN dedie qui force un statut FAILED. Testez ce scenario pour valider votre gestion d erreur avant la prod.
Discutons de votre projet. Kolonell integre Orange Money, Wave et Stripe sur des sites e-commerce rapides et securises au Senegal. 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.
