Accepting mobile money in your software: MTN MoMo and Airtel Money

If you sell to Zambian customers, mobile money is not an extra payment method. For many of your customers it is the only one. This article explains how the developer APIs work, and what a business should think about before it starts.

Why mobile money matters here

The scale is in the Bank of Zambia’s own numbers. In its National Payment Systems Annual Report for 2023, the Bank reported mobile transactions worth K452.0 billion, up from K295.8 billion in 2022. Volume was about 2.24 billion transactions, up from about 1.58 billion.

Wallets tell the same story. The Bank reported 17,290,646 registered mobile money wallets at the end of 2023, of which 12,924,894 were active. Active means the customer started a transaction in the last 90 days. That active share was 74.8 per cent, against 34.4 per cent in 2019. People are not just signing up. They are using the wallets.

The agent network grew with it, to 340,053 active agents in 2023. Three providers are designated for mobile payments: Airtel Mobile Commerce Zambia, MTN Mobile Money and Zamtel Mobile Money.

One more figure is worth noting if you sell goods or services. In 2023 merchant purchases were 22 per cent of mobile money value, second only to person-to-person transfers. Customers already pay businesses this way.

How the developer APIs work, broadly

Both MTN and Airtel run developer platforms. The details differ, but the shape is the same.

Two kinds of movement

Collections take money from a customer wallet into your business account. Disbursements send money the other way, for refunds, payouts, commissions or payroll. Most businesses start with collections and discover a month later that they needed disbursements too.

The request-to-pay pattern

A collection is not a single synchronous call. Your system asks the provider to charge a phone number. The provider accepts the request and returns immediately, before any money has moved. The customer then sees a prompt on their own phone and approves it with their PIN. Only then does the transaction succeed or fail.

On the MTN MoMo Open API this is the request-to-pay call. It returns an HTTP 202, and the transaction sits in a pending state until the customer acts. On Airtel’s platform the customer confirmation arrives as a USSD push where they enter their Airtel Money PIN.

The practical consequence is the important part. Your checkout must handle a waiting state. It must not tell the customer the payment succeeded when the request was merely accepted.

Credentials and environments

Both platforms use OAuth-style credentials. You hold a client identifier and a secret, exchange them for a short-lived access token, and send that token with each call. MTN’s platform adds a subscription key per product on top of the token. Airtel’s API takes the country and currency as request headers, which matters if you operate in more than one market.

Both run a sandbox separate from production. You build and test against the sandbox with test credentials, then apply to go live. Going live involves business verification, so start it earlier than you think you need to. MTN’s developer portals are at momodeveloper.mtn.com for testing and momoapi.mtn.com for production. Airtel’s is at developers.airtel.africa.

MTN’s Open API platform covers Zambia. Airtel Money operates in Zambia and Airtel Mobile Commerce Zambia is a designated payment system business here. Country coverage and product availability change, so confirm both with the provider for your own account.

Callbacks and polling

Because the customer approves the payment on their own phone, the result reaches you later. There are two ways to learn it: the provider calls a URL you host, or your system asks for the status.

Use both. MTN’s documentation is explicit that the wallet platform sends its callback once and does not retry if your system fails to respond. If you rely on callbacks alone, one bad deployment means lost payments in your records. Keep a background job that polls anything still pending.

Reference identifiers

You generate a unique identifier for each payment request and send it with the request. It is how you check the status later, and it is what stops a retry from charging a customer twice. On MTN’s API, reusing an identifier returns a conflict rather than creating a second charge. Generate the identifier once, store it before you call, and reuse it on retry.

What a business should think about

Reconciliation

This is the real work. Your system’s idea of what was paid must match the provider’s. Store the provider’s transaction reference against your own order from the start. Build a daily check that compares the two and reports the differences to a person. Without it, disputes take hours to resolve instead of minutes.

Failed and stuck transactions

Payments fail for ordinary reasons: not enough funds, a wrong number, a customer who ignores the prompt, a network timeout. Some transactions sit in an ambiguous state for a while. Decide in advance how long you wait, what the customer sees while waiting, and who follows up. Never delete a pending record. Mark it and keep checking.

Fees and charges

Charges are commercial and they are negotiated with the provider, so we will not quote figures. Two things are worth knowing. Ask for the full schedule before you sign, including any charge on disbursements. And note that the Bank of Zambia issued directives in August 2024 on unwarranted charges and fees on electronic money services, prohibiting some charges and capping others. Ask your provider how those apply to your account.

Two providers, not one

Your customers are split across networks. If you support only one, you turn away the rest. Build your payment layer so the provider is a detail behind a common interface. Adding the second provider then costs days, not weeks.

Settlement and access

Understand when money actually reaches an account you can spend from, and who in your business can see the provider portal. Settlement timing is a commercial matter between you and the provider. Confirm it in writing.

Our own experience

We have shipped mobile money support in Luta Rentals, our car-sharing marketplace for the Zambian market. It taught us what this article says: the API call is the small part, and the states around it are the work. Waiting states, retries, reconciliation and refunds are where the time goes.

We are not claiming this is the only way to do it. We are saying we have done it in production, for real customers, in Zambia.

Where to start

• Register on both developer portals and get a sandbox working before you talk about timelines.
• Start the commercial and verification process early. It usually takes longer than the code.
• Design your payment states first: requested, pending, succeeded, failed, refunded. Everything else follows from that.
• Decide how reconciliation will work on day one, not after the first dispute.

API details in this article were correct at the time of writing and are kept general on purpose. Confirm the current specifics with MTN and Airtel before you build.