M-Pesa Instant Payment Notification

Posted on by Craig Loftus

We shed some light on the M-Pesa Instant Payment Notification (IPN) service and answer some of the common questions that our clients raise, based on our experience of using it for a variety of applications.

M-Pesa is everywhere

Roughly 25% of Kenya’s GDP flows through the M-Pesa mobile payment system, which is used by over 17m people in Kenya. Businesses across the country accept and make payments using M-Pesa, and the online marketplace is no different.

In our opinion, the easiest way for businesses to accept and process M-Pesa payments online is the Instant Payment Notification (IPN) system. (While there are other options available, including the use of third party payment gateways and other Safaricom services, these all have issues that make them less attractive).

The IPN service

Safaricom describe the key features of IPN as follows:

MPESA IPN enables PayBill Partners to receive real-time notification to their systems whenever funds are sent to their PayBill Numbers… The main objective of M-PESA IPN application is to provide an efficient […] way for Safaricom PayBill Partners to complete real-time transactions.

Some of the common questions we have heard about the IPN service are answered below.

  • What does the service actually do?

    Whenever an M-Pesa payment is made to your PayBill number, the IPN service sends a message to a designated web server. The messages contains details of the payment - amount, sender etc which the web server can process. A detailed list of the data is included at the bottom of this article.

  • What can it be used for?

    We have seen it used for simple logging of payments to real-time e-commerce solutions.

  • Can I accept/reject payments using IPN?

    No. The IPN documentation describes how the web server can respond to the IPN, to instruct Safaricom to accept or reject a payment. However, this functionality is not implemented. Once an IPN is received, the payment has already been accepted into you PayBill account and the only way it can be reversed is through the PayBill administration portal.

  • Are notifications guaranteed to arrive?

    No. While the service is fairly reliable, the nature of web-based communication means that failures can occur. It also seems that failed notifications are not retried, so if your web server is down for any period of time then you may have missed notifications.

    It is advisable to verify all transactions using the PayBill administration portal.

  • How quickly do notifications arrive?

    Not instantly. 95% will arrive in less than 70 seconds, but we have seen a notification take 7 minutes to arrive. The slow delivery time and large variability rule out using IPN to provide real-time feedback to customers.

    The figure below shows the distribution of IPN notification times that we have observed, with values truncated to improve the resolution of the chart for typical notification times.

    Distribution of IPN notification times05101520253035404550556065700.07.515.022.530.0Time until notification (s) (Highest 5% discarded)Notifications (%)
  • Does the service allow online payments?

    The IPN service only provides notifications and is agnostic to the source of those payments. The typical way to integrate IPN with e-commerce is to present the customer with instructions to make payment to a PayBill number, and then use IPN to process that transaction in real time.

    Payments can be reconciled with orders, either by asking the customer to enter the transaction code they receive in their SMS receipt from Safaricom, or by specifying an account number that the customer should enter when making a payment.

  • How secure is the service?

    While the service does provide basic username/password authentication for messages sent from Safaricom, the way in which this is implemented is weak and falls short of best practice for secure web-based communication.

    Users of the service should ensure that their web server performs appropriate checks on the username/password sent with every message, and that SSL is used to protect information being sent to their web server. They should also take extra precautions to verify the source of those messages, even if the username and password appear to be correct.

    Where possible, manual reconciliation of transactions is advisable.

IPN message data sheet

The table below describes the parameters sent with each IPN notification.

KeyExample valueNotes
id 12345678 A unique identifier for the notification (not the transaction).
orig MPESA
dest 254722987654 Merchant’s business terminal phone number.
tstamp 2014-11-10 13:34:26 When the notification was sent by Safaricom.
text A123B456C Confirmed. on 10/11/14 at 1:33 PM Ksh1000.00 received from JOHN SMITH 254722123456. Account Number ACCOUNT New Utility balance is Ksh20,199.00 A copy of the message send to the Merchant’s business terminal.
customer_id 1234 An internal ID associated with the Merchant’s account.
user somename The username the Merchant provided for authentication with their server.
pass somepassword The password the Merchant provided for authentication with their server.
routemethod_id 2
routemethod_name HTTP
mpesa_code A123B456C A unique identifier for the transaction.
mpesa_acc ACCOUNT Account entered by sender.
mpesa_msisdn 254722123456 Sender’s phone number.
mpesa_trx_date 10/11/14 Date of the transaction.
mpesa_trx_time 1:33 PM Time of the transaction.
mpesa_amt 1000.00 Amount in KSh.
mpesa_sender JOHN SMITH The registered name of the sender.
business_number 123456 Merchant’s PayBill number.