Guide to integrating to the new MPESA API

25 | 4,716

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 8 months ago
How do you set the initiator password have tried but in vain
Edwin commented 7 months 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.

Kennedy commented 6 months ago
What kind of structure is expected on callback codes and their responses?
Edwin commented 5 months ago
Dear Ken,
To view the responses,
1. kindly go to this link API docs
2. Click "MPESA API" at the left and the exact API
3. On the right, you'll see the json responses.
I hope this helps?
Kennedy commented 5 months ago
Sure. Thanks. I hadn't seen that part.
Muhyadin Rashid commented 5 months ago
Thank you for the tutorial. I will go through it and try to integrate it with my laravel 5.5 app.
Peter commented 5 months ago
Check out the tutorial below also:
kelvin commented 4 months ago
i am receiving the following error when going live... Kindly assist.... Paybill Verification failed due to the following reason: No paybill verification data found Service Request for Regsitration Failed
Edwin commented 4 months ago
@Kelvin, Login to the MPESA portal by going to, go to "Operator Management and create a user and give the user "Business Manager" role
Jeff commented 4 months ago
Hi guys, thanks for the tutorial. I'd like to request you make a simple php app working with lnmo payments. I'll highly appreciate. Thanks
Jeff commented 4 months ago
Hi guys, thanks for the tutorial. I'd like to request you make a simple php app working with lnmo payments. I'll highly appreciate. Thanks
Ahmed Badr commented 4 months ago
Dear Edwin, I have one comment, can we use B2B APIs as settlement APIs that moves money between accounts? Please advise I appreciate your quick response
Marwa Salah commented 4 months ago
Hi, I need your help to integrate to MPESA B2B API , my first question is it still supported as soap service or only REST regards, marwa
Max Peter commented 4 months ago
@Ahmed, if you mean movement between accounts of the same Paybill, no, but for movement between different accounts of different paybills that is possible using B2B
Edwin commented 4 months ago
@Jeff, Kindly send me a link of Inmo payments, I take a look.

@Ahemd, yes, you can use B2B to move money from Business to Business or B2C from Business to Customers. Although, since the last time I checked, you cannot use the same paybill for both C2B and B2C.

@Marwa, the new API only supports REST.

Peter commented 4 months ago
@Marwa yes, the SOAP API is still there, but you must have quite a good business reason to access it, since it requires a VPN and is used for larger clients. You might most probably be redirected to the REST one
Edwin commented 4 months ago
@Peter, thanks for sharing your link.

Which tool did you use to create the API documentation?

Peter commented 4 months ago
@Edwin, it was not any tool, but a customized layout using Bootstrap + Angular. I thought it would be useful for quick testing
Stella commented 3 months ago
Hi, I want to ask about C2B Going live - Switch to the live app and use the live app's Consumer Key's and Secret in the code written in step 3. Is there a possibility to test new rest api before migration and if something goes wrong during migration how to revert to old broker api? Thanks
Ketan Solanki commented 3 months ago
Hello Edwin, I am getting the following error in the response. { "Result":{ "ResultType":0, "ResultCode":2001, "ResultDesc":"The initiator information is invalid.", "OriginatorConversationID":"7682-789956-1", "ConversationID":"AG_20180612_0000691967b7bca2394b", "TransactionID":"MFC01H59M6", "ReferenceData":{ "ReferenceItem":{ "Key":"QueueTimeoutURL", "Value":"https:\/\/\/mpesa\/b2cresults\/v1\/submit" } } } } Kindly let me know here Am i making the mistake. I have tried the code sample taken from the following link : Any help will be highly appriciated. -- Ketan Solanki
Mike commented 1 month ago
At what point do one register the production confirmation and validation url?
Edwin commented 1 month ago

you can have 3 environments. A test and live environment using the test and live keys respectively so that you can use either during migration. Also, perform a dry run.

The initiator error means that either the paybill or Head Office number (when using till number) is incorrect. Kindly confirm this from the client.

You register the urls after going live. Also, remember to use the production consumer key and secret from the "live" app

Max Peter commented 1 month ago

Join the following group to enquire more on the API:

SABASTIAN MUOKA commented 1 month ago


please help me on what is required to setup and automate freelancers payouts such that freelancers will only request withdrawal (hit withdraw + select amount) and the app will automatically aprove and send money to their registered Mpesa acounts. the condition is there must be enough money to withdraw and pay the fees for processing payments.

a developer needs this information to intergrate Mpesa payments into my app.

Edwin commented 1 month ago


You need to integrate B2C API so that you can automatically payout from your Bulk M-Pesa account. Kindly note that you need at least 35,000 in that account to test.

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.