M-Pesa is a mobile phone-based money transfer, payments, and micro-financing service, launched in 2007 by Vodafone and Safaricom, the largest mobile network operator in Kenya. It has since expanded to Tanzania, Uganda, Mozambique, Lesotho, Ghana, Egypt, and South Africa.
Mpesa allows you to deposit, withdraw, send money, buy airtime and borrow a loan from M-Shwari or Fuliza service. On the same note, you can pay for goods or services via Paybill or buy goods till number. Almost every business organization has a Lipa na Mpesa till number or Paybill number to accept payments from customers and other business organizations.
This guide provides a step-by-step process for M-PESA API integration for your website, mobile application, point of sale, or any other software systems for you to accept payments via Mpesa.
M-PESA API Integration
The latest M-PESA platform dubbed G2 (for M-PESA 2nd generation platform) offers versatile integration capabilities that our development partners can take advantage of, to create excellent M-PESA journeys across the different industries they serve. This was a key factor in moving to the new platform. We have been consolidating the different interfaces our developers have expressed interest in to enable innovation around M-PESA.
As expected, most of these are about the payment journeys, covering both disbursements (Business to Customers – B2C) and service payments (Customer to Business – C2B and Business to Business – B2B). These and other features are now available through secure Application Programming Interfaces (APIs) that allow for third-party applications to easily plug into M-PESA.
M-PESA has been very successful mainly because of its simplicity of use and device agnostic nature. The API rides on the same concept, providing open interfaces over standard protocols through web services. Unlike the old system (G1) where a lot of workarounds had been done to automate payment experiences, developers can now hook directly to the core M-PESA and get creative with the systems they run. Let’s look at the payment use cases below:
Automated Payment Receipt Processing
Imagine the different scenarios that require customers to pay and have this processed instantly! Before G2, this was handled purely through Instant Payment Notification (IPN) which has served quite well. As the name indicates, IPN is only for notification processing.
The use cases for payment processing are as many as your imagination can get, from utility bills to woo/e-commerce, and the future is likely to get even more interesting. With the new system, the notifications are taken a notch higher by incorporating an optional payment validation step for Paybill. This allows the payment recipient (merchants) to confirm whether to accept the incoming payment or not.
While this may not sound very beneficial on the face of it, think of how many customers send payments to the right Paybill number but enter the wrong account. Money moves from the customer’s M-PESA account but their service payment will not be processed and they have to follow up.
This has been creating a big problem with the merchants, leading to massive reversal requests. This can now be handled through the validation API which allows the recipient to validate any of the payment parameters, including, account, amount, and, even sender and, only accept the payment if processing can be guaranteed.
Automated Payment Disbursements
Many systems that process receipts will also require outward payment processing. This could range from employees’ salary disbursements to paying other merchants that accept M-PESA payments. This feature was only available via a web portal for business to customers (B2C) with limitations on cap the city that made it unsuitable for large disbursements.
With the new platform, developers can have this done via API, which empowers them and cuts off the manual process of generating payments files, putting them in them the right format then uploading them to the web portal, after which it has to be approved by a different user. With the B2C API, this is now seamless.
Automated Payments Reversal
Even with an elaborate system, there is always a unique case that calls for a reversal. Imagine a situation where a customer has made a payment for services that the merchant is no longer able to render. The best way to handle this would be to have a reversal process that the merchant can adapt based on their internal processes. G2 supports secure payment reversal automation for such cases. The implementation will fully depend on the service journey and controls required at the recipient’s business.
A step-by-step guide for M-PESA API integration for your website, App, or, System
Step 1: Create an account on Mpesa G2 Portal
Accessing pay bill and till number transactions require you to have an account on Mpesa G2 Portal. Creating an account on Mpesa G2 Portal will enable you to create a user who will be sent a One Time Password (OTP) that you can use to test if M-PESA API integration is a success.
Safaricom will respond to the email automatically with a link for you to request a certificate. Click on the link to install the certificate in your Internet Explorer.
Note: You can use chrome to continue the process once you have installed the certificate.
To get an account on the Mpesa G2 portal send an email to [email protected] or call 0722002222 and request Safaricom to set up the Mpesa G2 portal for you.
Login to the portal and go to “Operator management”
Create a user with the name “Business Manager”
Set phone number (not email) to get notification via SMS.
Step 2: Create an App on the Mpesa Developer portal
Go to Mpesa Developer Portal and register for an account
Create an app
The app will be used to access the Mpesa API
Step 3: Write C2B, B2C, or B2B code
The third step is where it gets interesting. You have to write the code for handling all the transactions. You can use any language that you are comfortable with when writing the code. Check the article Demystifying the M-Pesa API to learn how to write a code to handle transactions.
We will go through all the steps provided in this tutorial and do all the processes for you. All that you will be required to do is apply for a Paybill account only and we will take care of the rest.
Step 4: Go live
The fourth step in M-PESA API integration is to go live. Before you go live, ensure that your code runs properly to be testing the code.
Go to the developer portal and “Go live”
You will be required to verify that you are the actual owner of the API before going live.
The first step for verification is to upload the test case.
The second step is to fill in the company details. The following substeps will guide you on how to fill out the forms.
- Verification Type: Short Code
- Organization Name: Enter your pay bill or till name
- Organization Short Code: Enter either your pay bill number
- Mpesa User Name: use the name you created in step 2
- You will receive an OTP to the number you registered in step 1
- Enter the received password and click Submit
- Tick all the check and key in the OTP then click “Submit”
- Switch to the live app and use the live app’s secret code written in step 2 and Consumer Keys
Once you have done this, enter the URL endpoints to the action button which a customer will click on your website(WordPress using an M-Pesa plugin), app, or system. Test if the integration was a success by clicking on the button to initiate payments and pay before making your site or app live for customers to make payments.