> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centipidbilling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orange Money

> Configure Orange Money Web Payment for francophone Africa.

# 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](https://developer.orange.com)
   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

<Steps>
  <Step title="Open Settings → Payments → Orange Money">
    Select Orange Money from the payment marketplace.
  </Step>

  <Step title="Enter the merchant key">
    **Merchant key** (required) is the Web Payment merchant key from your Orange
    Developer app — not the consumer key.
  </Step>

  <Step title="Enter the consumer key and consumer secret">
    Both are required and stored as secrets. They authenticate against the
    Orange Money API using client credentials.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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

<Steps>
  <Step title="Authenticate">
    Centipid Billing exchanges the consumer key and secret for a bearer token,
    which is cached until it expires.
  </Step>

  <Step title="Create payment">
    A Web Payment is created for the order id and amount. Orange returns a
    checkout URL and a pay token.
  </Step>

  <Step title="Payment">
    The payer completes the payment on Orange's page and is returned.
  </Step>

  <Step title="Verification">
    The payment state is read back from Orange: `SUCCESS`, `PENDING`, `FAILED`,
    or `EXPIRED`. Only `SUCCESS` records a payment and applies the package.
  </Step>
</Steps>

## 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](/billing/payment-gateways/troubleshooting). |
| 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](/billing/payment-gateways/credentials-reference).