How the Airtel Money collections flow works
- Get a token. POST your client ID and secret as JSON to
/auth/oauth2/tokenwithgrant_type: client_credentials. Cache the token until shortly beforeexpires_inruns out. - Request the payment. POST to
/merchant/v1/payments/with theX-CountryandX-Currencyheaders. Airtel sends a USSD prompt to the customer's phone. The response only confirms Airtel received the request. - Get the result. Airtel posts the outcome to the callback URL registered for your app in the developer portal. If no callback arrives within a few minutes, call
GET /standard/v1/payments/{id}.
Base URLs
UAT (sandbox): https://openapiuat.airtel.africa. Production: https://openapi.airtel.africa. UAT and production have separate credentials, and production access needs Airtel to approve your business.
The request body
| Field | What to send |
|---|---|
reference | A short description, e.g. "Order 1001". |
subscriber.msisdn | The customer's number without the country code or leading 0: 752123456. |
subscriber.country, .currency | Same values as the X-Country and X-Currency headers. |
transaction.amount | The amount. Whole numbers for currencies like UGX and RWF. |
transaction.id | Your own unique ID for this payment. Never reuse it. You'll use it to check the status. |
Published examples differ on whether msisdn and amount are sent as strings or numbers. This builder sends msisdn as a string and amount as a number. If Airtel rejects either, try the other form.
Transaction statuses
| Status | Meaning | What to do |
|---|---|---|
TS | Successful | Check the amount, then fulfil the order once. |
TF | Failed | Mark unpaid; let the customer retry with a new transaction ID. |
TIP | In progress | Wait for the callback or poll with backoff. |
TA | Ambiguous | Keep checking. Don't let the customer pay again yet. |
For response codes like DP00800001006 and ESB000039, see the Airtel Money error code reference.
Countries and currencies
| Country | X-Country | X-Currency |
|---|---|---|
| Uganda | UG | UGX |
| Kenya | KE | KES |
| Tanzania | TZ | TZS |
| Zambia | ZM | ZMW |
| Rwanda | RW | RWF |
| Malawi | MW | MWK |
| DR Congo | CD | CDF or USD |
| Congo (Brazzaville) | CG | XAF |
| Gabon | GA | XAF |
| Chad | TD | XAF |
| Niger | NE | XOF |
| Madagascar | MG | MGA |
| Seychelles | SC | SCR |
| Nigeria | NG | NGN |
Airtel Money markets as of October 2026. Your app is enabled per country, so check which ones in the developer portal.
Frequently asked questions
What phone number format does the Airtel Money API expect?
subscriber.msisdn is the customer's number without the country code and without the leading 0, for example 752123456 for the Ugandan number 0752 123 456. The country is given separately in subscriber.country and the X-Country header.
Does a successful collection response mean the customer paid?
No. The response (often with code ESB000010) only means Airtel received the request and sent a USSD prompt. The customer still has to enter their PIN. Wait for the callback, or check GET /standard/v1/payments/{id} until the status is TS (paid) or TF (failed).
What is the difference between Airtel Money v1 and v2 payments?
v1 (/merchant/v1/payments/) takes a plain JSON body and is what this builder generates. v2 (/merchant/v2/payments/) adds payload encryption using keys from the developer portal. Check which version your Airtel app is enabled for in the portal.
Why do I get "Credentials are not generated yet"?
Your Airtel developer app hasn't been approved yet. UAT credentials appear once the app is set up in the portal, and production access needs Airtel to approve your business (KYC).
Where do I set the Airtel Money callback URL?
Unlike MTN MoMo, Airtel doesn't take a callback URL in each request. You register it for your app in the Airtel developer portal. Airtel then sends the result to that URL, with the transaction ID and a status code such as TS or TF.
Related
- Airtel Money collections in Node.js: a full integration with safe callbacks and tests.
- Airtel Money collections in Laravel: a service class, callbacks confirmed in a queued job, TIP/TA handling and tests.
- African Phone Number Formatter: check that a number is on Airtel, and convert it in bulk.
- Airtel Money error codes: what TF, TA and DP008… codes mean.
- MTN MoMo Request Builder: the same flow for MTN MoMo.
Endpoints and fields checked October 2026 against published Airtel Money integrations. Airtel's own documentation is in its developer portal at developers.airtel.africa and needs a login.