Banking Tech

Airtel Money API: How to Integrate Mobile Money in Your App

Airtel Money is one of the fastest-growing mobile financial services platforms in Uganda and across East Africa, commanding millions of active subscribers who use the network daily for peer-to-peer transfers, merchant retail checkout, utility bills, and micro-loan settlements. For software developers, e-commerce platforms, and enterprise engineering teams building applications in Uganda, integrating Airtel Money API alongside MTN MoMo is essential to capture 100% of the mobile payment market. This comprehensive developer guide provides a step-by-step technical tutorial for integrating the Airtel Money OpenAPI suite into your application backend.

Core Functional Interfaces of Airtel Money OpenAPI

The Airtel Money developer ecosystem offers three primary API interfaces engineered for enterprise business transactions:

• Customer to Business (C2B / Collections): Initiates a push notification to a customer's mobile phone, prompting them to enter their Airtel Money PIN to authorize a merchant payment.
• Business to Customer (B2C / Disbursements): Programmatically transfers funds directly from a corporate escrow account to an individual customer's Airtel Money account (ideal for loan payouts, payroll, or vendor disbursements).
• Transaction Status Inquiry & Balance APIs: Enables systems to check real-time account balances and verify the execution status of specific transaction IDs.

Step 1: Merchant Account Setup and OAuth Token Generation

Accessing the Airtel Money API requires registering on the official Airtel Developer Portal to obtain your Client ID and Client Secret. Authentication uses OAuth 2.0 Client Credentials flow:

Endpoint: POST https://openapi.airtel.africa/auth/oauth2/token
Headers: Content-Type: application/json

Request Body Payload

{
  "client_id": "YOUR_AIRTEL_CLIENT_ID",
  "client_secret": "YOUR_AIRTEL_CLIENT_SECRET",
  "grant_type": "client_credentials"
}

The API responds with an access_token string, token expiration period, and token type. Attach this token as a Bearer string in the HTTP Authorization header of all API calls.

Step 2: Mandatory HTTP Request Header Parameters

Airtel Money API requests require specific header metadata specifying target country codes and currency formats:

• Authorization: Bearer {access_token}
• X-Country: UG (for Uganda)
• X-Currency: UGX (for Ugandan Shillings)
• Content-Type: application/json

Step 3: Executing a C2B Payment Collection Request

To prompt a customer to make a payment from their Airtel Money wallet, issue a POST request to the merchant payment collection endpoint:

Endpoint: POST https://openapi.airtel.africa/merchant/v1/payments/

Request Payload Example

{
  "reference": "Ref-INV-2026-9011",
  "subscriber": {
    "country": "UG",
    "currency": "UGX",
    "msisdn": 750000111
  },
  "transaction": {
    "amount": 35000,
    "country": "UG",
    "currency": "UGX",
    "id": "TXN-DC-2026-0088"
  }
}

Note: Pass the subscriber phone number (msisdn) as an integer or string without leading zeroes or plus signs (e.g., 750000111 for 0750000111).

Step 4: Handling Webhooks and Status Verification

Once the payment request is submitted, Airtel pushes a USSD prompt to the customer's phone screen. Upon completion, Airtel dispatches an HTTP POST webhook payload to your registered callback server endpoint:

• Inspect the response status object inside the incoming webhook body. A status code 200 and result code DP00080000 indicates payment success.
• If webhooks are delayed due to telecom network maintenance, poll the status endpoint using GET https://openapi.airtel.africa/standard/v1/payments/{transaction_id}.

Error Handling and Production Readiness Best Practices

Deploying live Airtel Money payment integrations in Uganda requires engineering robust error handling routines:

1. Map Gateway Error Codes Accurately: Handle specific error codes such as insufficient subscriber funds, incorrect PIN attempts, locked account states, or network timeouts.
2. Implement Exponential Backoff Polling: When querying pending transaction states, employ exponential backoff retry algorithms to avoid triggering API rate limit throttles.
3. Secure Webhook Endpoints: Validate incoming callback request headers and restrict webhook endpoints to official Airtel server IP address ranges to prevent spoofing.

Build High-Uptime Payment Platforms with DeryCode Tech

Building high-uptime payment infrastructure requires engineering software that seamlessly manages multi-carrier mobile money integrations, automated retries, and real-time ledger synchronization. DeryCode Tech, based in Kampala, Uganda and founded by lead software engineer Asiimwe Derick, specializes in enterprise mobile money API integrations, custom payment gateways, and full-stack software development.

Looking to integrate Airtel Money, MTN MoMo, or multi-carrier payment solutions into your mobile or web app? Contact DeryCode Tech today to work with seasoned Ugandan software engineers.