Airtel Money

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.

Caution

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.

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

1. Open Settings → Payments → Airtel Money

   Available only where the gateway is already enabled for the account.

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

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

4. Run a controlled test payment

   Pay a small amount and confirm the wallet prompt arrives and the payment reaches the ledger.

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

1. Request

   Centipid Billing authenticates against the Airtel API and posts the payment request with the resolved country and currency.

2. Authorization

   The payer approves the request on their handset.

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

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.