Orange Money API Web Payment: technical integration guide 2026

Why Orange Money Web Payment dominates in Senegal

Orange Money handles the majority of mobile payments in Senegal. For an e-commerce site or online service, integrating the Web Payment API (WebPay) is often the first monetization brick. This guide covers the real flow: getting keys, generating an access token, initiating a payment, redirecting the customer, then verifying the status.

The API relies on two main calls: an OAuth call to obtain an access token, then an initiation call that returns a payment URL. The customer is redirected to that URL, pays from their Orange Money app or via USSD code, then returns to your site.

Merchant onboarding: the steps

Production access requires merchant validation. Expect 5 to 15 business days depending on how complete your file is.

Keys to secure

You receive a client_id and client_secret pair. These values must never appear in the browser: every API call goes through your backend. Store them in environment variables, never in versioned source code.

The payment flow in 5 steps

• The server calls POST /oauth/token to get an access_token (valid roughly 1 hour).
• The server calls POST /webpayment with the amount and return URLs to get a payment_url and a transaction token.
• The browser redirects the customer to the payment_url.
• The customer pays; Orange redirects to your return_url (and optionally notifies your notif_url).
• The server verifies the status via the pay_token before validating the order.

Golden rule: never validate an order on the browser redirect alone. Always confirm the SUCCESS status server-side.

Initiation request parameters

The POST /webpayment call expects a JSON body. Here are the key fields.

Expected response

The response contains a pay_token, a payment_url and a notif_token. Store the order_id and pay_token: they are used to reconcile the payment.

Test and production environments

The two environments have different base URLs and currencies. Never mix sandbox keys with the prod URL.

Testing without spending

In sandbox, Orange provides a test number and PIN that simulate a successful or failed payment. Validate at least three scenarios: success, user cancellation, and token expiry.

Error codes to handle

Your backend must handle errors explicitly. A clear mapping prevents ghost orders.

End-to-end example

Concrete case: a shop sells a bag at 25,000 FCFA. The backend generates an order_id KOL-2026-0421, calls POST /oauth/token, receives an access_token, then calls POST /webpayment with amount 25000, currency XOF, return_url to the confirmation page and notif_url to /api/orange/notif. Orange returns a payment_url. The customer is redirected, pays, returns to the confirmation page. In parallel, Orange calls /api/orange/notif with the SUCCESS status and the notif_token. The backend checks the notif_token, verifies the status via the pay_token, then moves the order from PENDING to PAID. Total server-side: two outbound calls and one inbound notification.

Security and best practices

• Idempotency: a single order_id must never create two valid payments.
• Mandatory server-side verification before any delivery or activation.
• Strict HTTPS on all return and notification URLs.
• Logging of every status transition for support.
• Backend timeout: if no notification after 15 minutes, mark EXPIRED.

FAQ

Can Orange Money be integrated without a backend server?

No. The client_secret and token generation must stay server-side. A 100 percent front-end integration would expose your keys and be rejected in production.

Which currency should I use in sandbox?

The OUV currency in sandbox, and XOF in production. Swapping the two is the most common error when going live.

Should I wait for the notif_url or is the redirect enough?

The server-to-server notif_url is authoritative. The browser redirect can be lost if the customer closes the tab. Always validate via the notification and the status check.

How long is the access_token valid?

About one hour. Generate it on demand and cache it server-side until expiry rather than regenerating it on every request.

How do I test a failed payment?

The sandbox console provides a dedicated PIN that forces a FAILED status. Test this scenario to validate your error handling before prod.

Let's talk about your project. Kolonell integrates Orange Money, Wave and Stripe into fast, secure e-commerce sites in Senegal. WhatsApp +221 77 596 93 33.