Orange Money

Collect payments with Orange Money

ORANGE_MONEY uses Orange’s Web Payment hosted checkout: Centipid Billing creates a payment, sends the payer to Orange’s page, and reads the payment state back from Orange before crediting anything.

Offered in the country catalog for Côte d’Ivoire, Burkina Faso, Cameroon, DR Congo, and Senegal.

Before you start

1. Create an application in the Orange Developer portal under an account owned by the ISP, and subscribe it to Web Payment.
2. Collect the merchant key (the Web Payment key), the consumer key, and the consumer secret.
3. Plan the walled garden: the payer’s browser must reach Orange’s checkout page, so a Hotspot subscriber who is not yet online cannot pay unless Orange is reachable pre-authentication.

Configure the gateway

1. Open Settings → Payments → Orange Money

   Select Orange Money from the payment marketplace.

2. Enter the merchant key

   Merchant key (required) is the Web Payment merchant key from your Orange Developer app — not the consumer key.

3. Enter the consumer key and consumer secret

   Both are required and stored as secrets. They authenticate against the Orange Money API using client credentials.

4. Run a controlled test payment

   Pay a small amount from the captive portal on an unauthenticated device. Confirm the Orange checkout page loads, the payer is returned, and the payment reaches the ledger.

Credentials

Field	Required	Notes
Merchant key	Yes	The Web Payment key from your Orange Developer app.
Consumer key	Yes	Secret.
Consumer secret	Yes	Secret.

All three gate the switch.

Callback URLs

None to register by hand. The return address and the notification address are both sent with each payment, carrying that payment’s own order id.

What the payer must provide

Whatever Orange’s checkout page asks for. The amount is formatted for the currency before the payment is created — most currencies served here have no minor unit, while CDF carries two decimals — so the amount the payer sees should match the ledger exactly.

How a payment completes

1. Authenticate

   Centipid Billing exchanges the consumer key and secret for a bearer token, which is cached until it expires.

2. Create payment

   A Web Payment is created for the order id and amount. Orange returns a checkout URL and a pay token.

3. Payment

   The payer completes the payment on Orange’s page and is returned.

4. Verification

   The payment state is read back from Orange: SUCCESS, PENDING, FAILED, or EXPIRED. Only SUCCESS records a payment and applies the package.

Troubleshooting

Symptom	What it means	What to do
Checkout fails before Orange’s page loads	Credentials are missing, or Orange rejected them.	Confirm all three fields are saved, and that the app is subscribed to Web Payment in the Orange Developer portal.
“Orange Money payment initiation failed.”	Orange refused to create the payment; its own message is shown when it sends one.	Read the message. A merchant key that is not a Web Payment key is a common cause.
The checkout page never loads on a Hotspot device	The walled garden does not allow Orange.	Allow Orange’s checkout domain pre-authentication — see Captive device cannot reach checkout.
Payment shows PENDING long after the payer confirms	Orange has not settled it.	Re-check the state before advising a retry — a retry can charge the payer twice.
Payment shows EXPIRED	The payer took too long on Orange’s page.	Start a fresh checkout.

For every gateway’s fields in one place, see the credential reference.