Guide To Integrating To The New MPESA API

3 min


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 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 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.

In the spirit of giving back to the community and assistother developers, Sapama decided to document and share the process they undertook inintegrating to theMPESAAPI:

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
  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 linkin the email to install the certificate in WindowsInternet Explorer. But you can use Chrome after installing.
  4. If you don’t have an account setup, contact MPESABusiness Support 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 numberto 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 toMPESADeveloper Portaland 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 codeSapama 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 URLyou register needs to be SSL or https. You can get a certificate from MPESAand install it on your server or useLets 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 toMpesa Developer portaland 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 butit’s our hope that thesefoursteps will serve as a bridge. That they’llmake your Mpesa integration journey a little biteasier and help you connect the dots.

Well, well,you can always reach out to Edwin via,he is open to assist where we can.

Like it? Share with your friends!