Protecting M-Pesa payment alerts from fakes
How a Kenyan business keeps fake M-Pesa payment alerts out of its books: Safaricom's IP whitelist, URL rules, initiator credentials and staff checks.
By Achekam · · 4 min read · For Running a business businesses in Kenya
An M-Pesa payment notification is, in effect, an instruction to your books: this invoice is paid, the goods can go. If anyone other than Safaricom can send that instruction and have it believed, they can mark invoices paid with money that never arrived.
That is why the address your system uses to receive M-Pesa alerts deserves the same care as the key to the stockroom. This article explains how the notifications work, the protections Safaricom documents, what Achekam does with the alerts it receives, and the checks staff should keep doing regardless.
Asynchronous callbacks and what can go wrong
Safaricom's Daraja documentation says M-Pesa APIs are asynchronous: they send results to the business's CallBackURL or ResultURL after the event, and Safaricom advises deploying an HTTP listener that accepts POST requests to receive them. If the receiving server is unavailable, the API gateway logs a 503 error and discards the results.
Two weak points follow from that design:
- The address is on the public internet. Safaricom must be able to reach it, which means anyone who learns it can send a request to it too.
- The message does not prove where it came from. Safaricom does not sign these notifications, so nothing inside the message itself shows that Safaricom sent it.
A lost notification is a nuisance; recovering M-Pesa payments whose alerts never came deals with that. A forged one is worse, because it creates a payment that does not exist.
Whitelisting Safaricom's gateway addresses
Safaricom publishes the list of API gateway IP addresses that businesses should whitelist, so that they only process callbacks from the Safaricom API Gateway. At the time of writing its page lists twelve addresses in three ranges.
In practice, the business's server, or the firewall in front of it, accepts M-Pesa notifications only when they come from one of those addresses and refuses everything else. Two habits keep the protection working:
- Take the list from Safaricom's own page, not from a forum post or an old configuration file.
- Check it again whenever Safaricom announces changes, and after any move to new hosting.
It also helps to log the requests the server refuses. A handful of strays is normal internet noise; a steady stream of well-formed payment messages from an unknown address means someone has found the address and is testing it, and the address should be changed.
Security credentials for initiator APIs
Notifications coming in are one side. Requests going out are the other. APIs that move money out of the business or reveal transaction details, such as B2C, B2B, Transaction Status and Reversal, need a security credential.
Safaricom's documentation describes how that credential is built: the initiator password is sealed with the M-Pesa public key certificate for the right environment, using RSA with PKCS #1.5 padding, and the result is base64-encoded. The sandbox and production environments use different certificates, so a credential built for testing will not work live.
What matters for the business is the initiator password itself. Limit who knows it, never put it in e-mails or chat messages, and change it when someone who knew it leaves.
URL rules that block common mistakes
Safaricom sets rules for the addresses that receive customer-to-business notifications in production. They must use HTTPS and be publicly reachable. They must not contain keywords such as M-PESA, Safaricom, exe, exec, cmd, SQL or query. And they must not use public URL testers such as ngrok, mockbin or requestbin. The sandbox allows plain HTTP.
The last rule closes a common gap. A developer who tests with a public tunnelling tool is effectively routing payment data through a third party's service. Safaricom's rule means that set-up cannot be carried into production.
Achekam's secret address, source check and confirmation
In Achekam, a Kenyan business can register its paybill or till so that a payment quoting an open shilling invoice number as the account number is receipted automatically, while any other payment waits in a list for a person to allocate.
Because Safaricom does not sign these notifications, Achekam protects them in two ways: a secret address, and a check of Safaricom's source addresses. The address also avoids the word "mpesa", because Safaricom refuses addresses that contain it.
For a payment prompt sent to a customer's phone, Achekam goes further: the payment is confirmed with Safaricom before it counts. A notification on its own does not mark the invoice paid.
Changing where Safaricom sends the notifications is guarded as well. Production URL registration is a one-time step per short code, and changing it needs two operators in the M-PESA org portal.
Staff checks that complement the system
System controls stop forged notifications reaching the books. They do not stop a person being fooled at the counter. Keep these habits:
- Never release goods on a message the customer shows you. Check that the payment appears in your own records or on the M-PESA statement. Fake confirmation messages are a known trick.
- Look at the code, not the wording. Search for the M-PESA code in your records; a confirmation that looks perfect but has no matching code in the books has not been paid. Reused M-Pesa codes at events covers a related risk.
- Work the allocation list daily. A payment sitting unallocated is either a customer mistake or a question worth asking.
- Restrict who can change payment settings. The fewer people who can touch the callback set-up, the fewer ways it can be altered.
Validation of payments before they are accepted is a separate control, covered in C2B validation.
Safaricom's Daraja getting-started guide introduces the M-PESA APIs and how their calls and callbacks work, and it is where Safaricom publishes the gateway addresses to whitelist.
General guidance only, not advice on your own circumstances. Tax and payroll rules change: check the current position with the authority or your adviser.
