Orange Money API: integration tutorial for your e-commerce website

Why keep Orange Money in 2026

Even though Wave is growing fast, Orange Money still dominates several segments in Senegal: civil servants, customers over 40, diaspora sending money from France and Spain, and rural customers where Orange has better coverage than Free or Tigo.

Not offering Orange Money on your e-commerce site means excluding 40% of your market.

What the official Orange Money API covers

• Web Payment: hosted Orange page for checkout
• Cash-in / Cash-out: for agents or B2B platforms
• Transfer: pay your referral partners automatically
• Available in: Senegal, Ivory Coast, Mali, Burkina Faso, Cameroon, DRC

Setup: the real steps

1. Developer portal access

Go to developer.orange.com, create an account, then subscribe to the Orange Money Web Payment product. Orange requires your PSE contract (Point de Service Électronique) — you have to go through your Orange Business account manager. Expect 2 to 4 weeks of validation.

Yes, it is slow. Yes, it is longer than Wave. No, you cannot skip it.

2. Get the credentials

Once approved, you receive:

• Client ID and Client Secret
• Merchant Key (specific to your merchant account)
• Access to the sandbox (mandatory before production)

3. Implement the OAuth + payment flow

The flow is a 3-step dance:

• Get an OAuth token: POST https://api.orange.com/oauth/v3/token with Basic Auth
• Initiate the payment: POST /orange-money-webpay/v1/webpayment with the token
• Redirect the customer to the returned payment_url

Orange redirects back to your return_url with a pay_token parameter. You then call transactionstatus to verify the payment is truly SUCCESS before validating the order.

4. Never trust the redirect

Golden rule: the actual payment status is NOT in the return URL. You must always re-verify server-side using the transactionstatus endpoint. I have seen sites lose millions of FCFA because someone tampered with the URL parameter.

Wave vs Orange Money

My recommendation: integrate both. Wave for speed, Orange Money for coverage.

5 fatal mistakes to avoid

• Not separating sandbox and prod: create two accounts, two env variables
• Hardcoding the Merchant Key: always in .env, never in code
• Forgetting the timeout: the first OAuth request can take 8s under load, set at least 15s
• Validating only via return_url: always re-check via transactionstatus
• Not logging failures: Orange occasionally changes responses without notice — full logs are required

The architecture we use at Kolonell

• Isolated service /src/lib/payments/orange-money.ts with OAuth token cache
• Prisma Payment table with statuses: PENDING, SUCCESS, FAILED, EXPIRED
• Cron job every 5 minutes to re-check PENDING payments older than 10 min
• Slack alert if more than 3 consecutive failures

We plug Orange Money + Wave into your site

At Kolonell, we deliver e-commerce integrations covering Wave + Orange Money + Stripe on Next.js with robust webhooks and automatic accounting reconciliation. Several Dakar clients process 1 million+ FCFA/day without friction.

Request a free quote or message me on WhatsApp +221 77 596 93 33. We secure your payments in 7 days.