Guide to integrating to the new MPESA API

2 | 433

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

These include: 

  • C2B - Customer to busness - 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 number 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 sent to a paybill or till number. 

Early 2017, we launched which is an online MPESA Paybill and Buy Good Analytics Dashboard that enables merchants to record payments and customer details from MPESA API and analyse these information in infographic charts and graph that give them actionable insights into your customer payment patterns. It’s something like Safaricom M-Ledger but for Lipa Na Mpesa Merchants. Intially, we were using the old API and in mid 2017 we embarked on migrating to the new API. 

In the spirit of giving back to the community and assist other developers, we decided to document and share the process we 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
  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, kindly contact MPESA Business Support on 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, an 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 need 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 four sub 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 office number 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.
    • We've 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's our hope that these four steps will serve as a bridge. That they'll make your Mpesa integration journey a little bit easier and help you connect the dots.  

Well, well, you can always reach out to us and we are open to assist where we can. 


Elijah M commented 1 month ago
How do you set the initiator password have tried but in vain
Edwin commented 2 weeks ago
Hi Elijah,
1. Go to any API on developer portal eg

2.Scroll down and click on "Get Test Credentials"

4. Select either test or production to set the password.

Submit a comment

Your email address will not be published. Required fields are marked *

Back to list

About us

Sapama ERP is a cloud-based Enterprise Resource Planning (ERP) software for small and medium sized organizations.