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

# Airtel Money

> Airtel Money collections through the Airtel Africa API, and the country-catalog limitation to know about first.

# Collect payments with Airtel Money

`AIRTEL_MONEY` collects through the Airtel Africa open API. Centipid Billing
pushes a payment request to the payer's Airtel wallet, the payer authorizes it
on their handset, and the transaction status is read back from Airtel.

<Warning>
  **Airtel Money is not offered by the country catalog.** Every country list in
  the application offers some other set of gateways, and none of them includes
  Airtel Money — so it does not appear in the **Settings → Payments**
  marketplace and cannot be selected there, even though the credential form and
  the integration both exist and work.

  In practice this means the gateway is reachable only for an account already
  configured on it. Do not plan a migration onto Airtel Money without first
  confirming with support that it can be enabled for your country.
</Warning>

## Before you start

1. Confirm with support that Airtel Money is available for your account, given
   the limitation above.
2. Complete Airtel Africa developer onboarding in an account owned by the ISP,
   and collect the **client ID** and **client secret**.
3. Confirm which country and currency Airtel has approved for your merchant
   account — they decide the overrides below.

## Configure the gateway

<Steps>
  <Step title="Open Settings → Payments → Airtel Money">
    Available only where the gateway is already enabled for the account.
  </Step>

  <Step title="Enter the API credentials">
    **Airtel client ID** and **Airtel client secret** are both required. The
    secret is stored as a secret and is not echoed back after saving.
  </Step>

  <Step title="Leave the overrides blank unless Airtel told you otherwise">
    **Country code override** and **currency code override** are optional. Left
    blank, requests use your account's own country and currency, falling back to
    `UG` and `UGX`. Set them only when Airtel has approved a different explicit
    value for your merchant account.
  </Step>

  <Step title="Run a controlled test payment">
    Pay a small amount and confirm the wallet prompt arrives and the payment
    reaches the ledger.
  </Step>
</Steps>

## Credentials

| Field                  | Required | Notes                                                                                                                                 |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Airtel client ID       | Yes      | From the Airtel Africa developer portal.                                                                                              |
| Airtel client secret   | Yes      | Secret.                                                                                                                               |
| Country code override  | No       | ISO two-letter, maximum 3 characters, for example `UG`. Blank uses your account's country, then `UG`.                                 |
| Currency code override | No       | ISO three-letter, maximum 3 characters, for example `UGX`. Blank resolves from the country, then your account's currency, then `UGX`. |

Country and currency are sent as `X-Country` and `X-Currency` headers on every
request, so a wrong override is rejected by Airtel rather than silently
converted.

## Callback URLs

None are shown in Settings → Payments. Completion is established by reading the
transaction status back from Airtel rather than by waiting for a callback.

## What the payer must provide

An Airtel mobile money number, which is normalized for the resolved country
before the request is sent. Authorization happens on the handset, so no Airtel
domain needs to be added to the captive walled garden.

## How a payment completes

<Steps>
  <Step title="Request">
    Centipid Billing authenticates against the Airtel API and posts the payment
    request with the resolved country and currency.
  </Step>

  <Step title="Authorization">
    The payer approves the request on their handset.
  </Step>

  <Step title="Confirmation">
    The transaction status is queried back from Airtel. A completed transaction
    is recorded as a payment and the subscriber's package applied; a failed one
    is marked failed with the status Airtel returned.
  </Step>
</Steps>

## Troubleshooting

| Symptom                                                                   | What it means                                                  | What to do                                                                                                                                           |
| ------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Airtel Money does not appear in Settings → Payments                       | The country catalog does not offer it — see the warning above. | Contact support. Do not attempt to configure it another way.                                                                                         |
| *"Airtel Money credentials are not configured…"*                          | The client ID or secret is missing.                            | Enter both in Settings → Payments.                                                                                                                   |
| *"Unable to authenticate with Airtel Money. Please try again later."*     | Airtel rejected the credentials.                               | Re-copy the client ID and secret. Confirm the app is approved for production.                                                                        |
| *"Unable to reach Airtel Money at the moment. Please try again shortly."* | The request could not connect.                                 | Check outbound connectivity from the application host, then retry.                                                                                   |
| *"Payment initiation failed. Please try again later."*                    | Airtel refused the request.                                    | Check the payer's number is a valid Airtel wallet in the configured country, and that the country and currency overrides match what Airtel approved. |
| *"Payment failed: …"*                                                     | Airtel returned a terminal failure status.                     | Read the status in the message; ask the payer to confirm their wallet balance and status.                                                            |
| *"Payment is still pending."*                                             | Airtel has not settled the transaction yet.                    | Re-check the status before advising a retry — a retry can charge the payer twice.                                                                    |

For every gateway's fields in one place, see the
[credential reference](/billing/payment-gateways/credentials-reference).