How to integrate the new MPESA API

Sapama ERP

How to integrate the new MPESA API

MPESA released their new API (Application Programming Interface)to enable developers to access M-Pesa services;

These include:

  • C2B – Customer to business – This is the normal paybill and till number service.
  • B2C – Business to customer – This enables business to send money directly to a list of phone numbers from their bulk account. This is a convenient service to pay salaries to many staff to reduce time and error in doing this one by one.
  • B2B – Business to business – This enables business to pay other businesses. It’s the same as B2C but instead of sending money to a personal phone number, you send to a paybill or till number.

Early 2017, Sapama launched which is an online MPESA Paybill and Buy Goods Analytics Dashboard that enables merchants to record payments and customer details from MPESA API and analyse these information in an infographic charts and graph that gives them actionable insights into your customer payment patterns. It’s something like Safaricom M-Ledger but for Lipa Na Mpesa Merchants. Initially, they were using the old API and inmid 2017 migrated to the new API.

Read also: Safaricom appoints the new CEO

In the spirit of giving back to the community and assist other developers, Sapama decided to document and share the process they undertook in integrating to the MPESA API:

Step 1: Creating an account on MPESA G2 Portal

The MPESA G2 portal is an online platform where merchants access paybill or till number transactions. The purpose of this step is to create a user who will be sent a One Time Password (OTP) before going live. Although online, you need to install a certificate in your Windows Internet Explorer. Below is the procedure:

  1. To request the weekly certificate password to setup the MPESA portal, kindly send a blank email to [email protected].
  2. Click on the link in the autoresponder email to request the certificate.
  3. Unfortunately, MPESA will not inform you when the certificate is generated and you’ll need to go back to the link in the email to install the certificate in Windows Internet Explorer. But you can use Chrome after installing.
  4. If you don’t have an account setup, contact MPESA Business Support on [email protected] or 0722002222 and request them to setup for you an account on MPESA G2 portal.
  5. Login to the MPESA portal by going to, go to “Operator Management and create a user and give the user “Business Manager” and all roles that have an”API” word in them.
  6. Ensure you set your phone number to get notification via SMS and not email. For security purposes, the phone number will be sent a one time password (OTP) just before going live.

Step 2: Creating an app on MPESA Developer Portal

MPESA Developer Portal enables a developer to create an app and use that app to access the MPESA API’s. The purpose of this step is to be able to create an app. There is the test app and live app. The test app is used for development and after going live, a live app will be automatically created.This involves the following steps:

  1. Go to MPESA Developer Portal and create an account
  2. Create an app

Step 3: Writing to C2B, B2C or B2C code

You need to write the code to handle C2B request or to send B2C and B2C request. The code can be written in the programming language of your choice. Kindly check this MPESA API wrapper that you can use to write the code Sapama Pay Github

The library will enable you to register endpoint urls and test the API’s. During this step you’ll use the Consumer Key’s and Consumer Secret of the test app created in Step 2. The URL you register needs to be SSL or https. You can get a certificate from MPESA and install it on your server or use Lets Encrpt

Step 4: Going live

After making sure that your code is working correctly, you’ll need to go live that is a foursub step processes that enables you to verify you are the actual owner of the API by sending a one time password to the phone number of the user you created in Step 1.

  1. Login to Mpesa Developer portal and click on “Go Live”
  2. Verification Step 1: Upload test case. Fortunately or unfortunately, Mpesa does not validate the test cases so just download the excel, fill it and re-upload it 🙂
  3. Verification step 2: The following is a guide on how to fill the fields in this form
    • Verification Type: Short Code
    • Organization Name – Paybill or Till Company Registration Name
    • Organization Short Code – For Paybill your short code and for till number, use a head officenumber and not store number. For till number it’s not clearly documented
    • MPesa User Name- Use the user name of the user you created in Step 1 above. Note that this is case sensitive.
    • You’ll receive a one time password (OTP) to the number registered in Step 1.
  4. Verification step 3: Enter password received and click “Submit”
  5. Verification step 4: Tick all the check and key in the OTP and click “Submit”
  6. Switch to the live app and use the live app’s Consumer Key’s and Secret in the code written in step 3.

Maybe, we might have missed something but it is our hope that these four steps will serve as a bridge. That they will make your Mpesa integration journey a little bit easier and help you connect the dots.

Well, well, you can always reach out to Edwin via email [email protected] for further advice

This blog was first posted here

Author: Edwin Mugendi,

Read also How Escrow Kenya is solving the problem of trust in online transactions