Orange Money Sénégal API : intégration pas-à-pas en 2 heures (mai 2026)

Orange Money pèse encore ~38 % des paiements mobiles au Sénégal en 2026. Ne pas l'intégrer, c'est laisser un gros tiers de votre marché payer par cash à la livraison ou abandonner le panier. Mais l'onboarding développeur est moins direct que Wave.

TL;DR

- Compte développeur Orange : validation 5-10 jours ouvrés (prévoir avant le sprint).

- L'API a 3 endpoints clés : /oauth/token (auth), /webpayment (init), /webpayment/{id} (statut).

- Pas de webhook officiel grand public en mai 2026 → polling + redirection retour.

- Comptez 2 heures pour une intégration fonctionnelle, 4 heures pour la version production-ready.

Étape 1 — créer le compte développeur

• Aller sur developer.orange.com (oui, pas orange.sn).
• Souscrire l'API "Orange Money Web Payment".
• Renseigner : raison sociale, numéro NINEA, RCCM, IBAN du compte de réception.
• Validation manuelle Orange : 5 à 10 jours ouvrés. Préparez-vous à relancer.

Étape 2 — récupérer un access_token

`ts

// lib/orange-money.ts

const OM_BASE = 'https://api.orange.com/orange-money-webpay/dev/v1';

async function getAccessToken() {

const auth = Buffer.from(

${process.env.OM_CLIENT_ID}:${process.env.OM_CLIENT_SECRET}

).toString('base64');

const res = await fetch(${OM_BASE}/oauth/token, {

method: 'POST',

headers: {

'Authorization': Basic ${auth},

'Content-Type': 'application/x-www-form-urlencoded',

},

body: 'grant_type=client_credentials',

});

const { access_token, expires_in } = await res.json();

return { access_token, expires_in };

}

`

Le token expire en 3600s. Cachez-le en Redis ou en mémoire avec TTL pour éviter de le re-générer à chaque paiement.

Étape 3 — initier un paiement

`ts

async function initPayment(orderId: string, amountXof: number) {

const { access_token } = await getAccessToken();

const res = await fetch(${OM_BASE}/webpayment, {

method: 'POST',

headers: {

'Authorization': Bearer ${access_token},

'Content-Type': 'application/json',

},

body: JSON.stringify({

merchant_key: process.env.OM_MERCHANT_KEY,

currency: 'OUV', // unités UEMOA = XOF

order_id: orderId,

amount: amountXof,

return_url: https://kolonell.com/checkout/om-return?order=${orderId},

cancel_url: https://kolonell.com/checkout/om-cancel?order=${orderId},

notif_url: https://kolonell.com/api/webhooks/orange-money,

lang: 'fr',

reference: orderId,

}),

});

return res.json(); // { pay_token, payment_url, notif_token }

}

`

L'utilisateur est redirigé vers payment_url. Il paie sur l'interface Orange Money, puis revient sur return_url.

Étape 4 — vérifier le statut au retour

L'absence de webhook fiable rend le polling obligatoire :

`ts

// app/checkout/om-return/page.tsx

async function verifyPayment(payToken: string) {

const { access_token } = await getAccessToken();

const res = await fetch(${OM_BASE}/webpayment/${payToken}, {

headers: { 'Authorization': Bearer ${access_token} },

});

const { status, txnid } = await res.json();

// status: SUCCESS | FAILED | PENDING | EXPIRED

return { status, txnid };

}

`

Sur SUCCESS → marquer la commande paid. Sur PENDING → afficher un écran "Vérification en cours" et re-poller toutes les 5s pendant 60s max.

Pièges à éviter

Coût et frais

• Frais Orange Money commerçant : 1.5 % à 2.5 % selon volume négocié.
• Pas de frais de mise en place côté API.
• Reversement : T+1 ouvré sur compte bancaire ou IBAN renseigné.

FAQ

Q : Orange Money fonctionne-t-il avec un numéro non-Orange ?

R : Non, le payeur doit avoir un compte Orange Money actif. Les numéros Free/Expresso sont rejetés.

Q : Faut-il une intégration différente pour la Côte d'Ivoire ?

R : Oui — l'environnement OM CI a un endpoint et des merchant_keys séparés. Code structuré : un connector par pays.

Q : Comment gérer les remboursements ?

R : Voir notre guide remboursement Wave + OM →.

Conclusion

Orange Money n'est pas le plus moderne des fournisseurs de paiement, mais 38 % du marché justifie l'effort. Couplé à Wave (~52 %) et un fallback carte, vous couvrez 95 % des modes de paiement préférés au Sénégal.