Airtel Money API Integration in Tanzania: Developer Guide

Airtel Money is the third of Tanzania's three mobile money rails, alongside Vodacom M-Pesa and Tigo Pesa. It is operated by Airtel Tanzania, a subsidiary of Airtel Africa, which runs mobile money services across 14 African countries.

While Airtel Money has a smaller subscriber base than M-Pesa and Tigo Pesa in Tanzania, it is still a significant rail. Excluding it from your payment options means losing transactions from millions of Airtel subscribers. In a fully interoperable market like Tanzania, customers expect to pay from their primary wallet regardless of which provider you support.

For developers, the Airtel Africa developer platform is the entry point. Airtel has invested in developer-facing tools across its African markets, and the API documentation is generally better structured than what Tigo Pesa offers, though still not as polished as Safaricom's Daraja.

The integration architecture is identical to the other two providers: REST API, request-callback pattern, webhook handling. If you have built a payment integration against any mobile money API, Airtel Money is not a new concept. It is a new set of credentials and endpoints.

The Airtel Money API follows the same pattern as every mobile money API in the region:

1. Authenticate. The Airtel Africa API uses OAuth 2.0 for authentication. You send your client ID and client secret to the token endpoint and receive an access token. This is closer to Safaricom's Daraja than to Vodacom's session key approach.
2. Initiate a payment request. For C2B (customer to business), you POST to the collection endpoint with the customer's Airtel phone number, the amount in TZS, and a transaction reference.
3. Customer confirms. Airtel pushes a prompt to the customer's phone. The customer enters their Airtel Money PIN to authorize the payment.
4. Receive a callback. Airtel sends a POST request to your callback URL with the transaction status. Your server processes this, updates the order, and returns a response.

For B2C (business to customer, used for disbursements), the flow is similar: you POST to the disbursement endpoint with the recipient's phone number and amount, and receive a callback with the result.

Because Airtel uses OAuth 2.0, the authentication is very similar to Safaricom Daraja. If you have written the token generation code for Daraja, adapting it for Airtel is a matter of changing the credentials and token endpoint URL. This is one of the reasons McTaba teaches Daraja first: the patterns it uses are closer to what Airtel (and many other APIs) use than Vodacom's session key mechanism.

As with Vodacom and Tigo, direct API access to Airtel Money in Tanzania requires a business relationship with Airtel. You need a registered Tanzanian business, an Airtel business account, and approval from their commercial team. The timeline is variable, often two to six weeks.

The Airtel Africa developer portal does offer sandbox access for testing, which is more straightforward to obtain than production credentials. If you want to test the API flow before committing to the full onboarding process, the sandbox is a reasonable starting point.

For production, the aggregator path remains the fastest for most developers:

• Selcom: Tanzania's largest aggregator. Supports all three rails. Strong local presence and developer support.
• Azampay: Growing Tanzanian aggregator with a modern API and competitive fees.
• ClickPesa: Tanzania-based aggregator with support for mobile money and bank transfers.
• Pesapal: East Africa-wide aggregator. Supports Airtel Money alongside M-Pesa, Tigo Pesa, and card payments.

Each aggregator has one API that covers all three rails. This means your integration work for Airtel Money is already done if you integrated M-Pesa through the same aggregator. The aggregator abstracts the provider-specific details and gives you a unified callback format.

Unlike Vodacom M-Pesa (Tanzania-specific) and Tigo Pesa (Tanzania-specific), Airtel Money operates across 14 African countries under the Airtel Africa umbrella. This creates an unusual advantage for developers: the Airtel Africa API is designed to work across markets, with country-specific configurations rather than entirely separate APIs.

If you integrate Airtel Money in Tanzania, the architecture and much of the code applies to Airtel Money in Kenya, Uganda, Rwanda, Malawi, and other Airtel Africa markets. The country code, currency, and some market-specific parameters change. The authentication, endpoint structure, and callback handling remain the same.

For developers building products that span multiple East African markets, this consistency is valuable. You build the Airtel integration once and configure it per country, rather than building separate integrations from scratch.

McTaba's M-Pesa Integration for Developers course (KES 9,999 / ~TZS 200,000) teaches both Safaricom M-Pesa (Daraja) and Airtel Money integration. Because Airtel uses OAuth 2.0 and the same request-callback pattern as Daraja, the two APIs are natural companions in a single course. The skills you build are immediately applicable to Airtel Money Tanzania.

A few things to keep in mind when integrating Airtel Money in Tanzania:

• Phone number format. Airtel Tanzania numbers use the 255 country code prefix. Ensure your code normalizes user input to the international format before sending API requests.
• TZS formatting. All amounts are in Tanzanian Shillings, with no decimal places. If your system handles multiple currencies, make sure TZS amounts are treated as integers.
• Callback reliability. Like all mobile money callbacks, Airtel callbacks can be delayed or fail to arrive during network issues. Implement a transaction status check (polling) as a fallback for cases where the callback does not arrive within your expected timeframe.
• Token caching. OAuth tokens have an expiry. Do not request a new token for every API call. Cache the token and refresh it before expiry. This reduces latency and avoids unnecessary API calls.
• Error messages. Airtel error codes are different from Vodacom and Daraja codes. Map them to user-friendly messages. "Insufficient funds" should say "Insufficient funds," not display a raw error code to the customer.

For a full guide on handling errors across all three Tanzanian providers, see our common mobile money API errors article.