Home Business Prerequisites and the step by step guide for MPesa API integration

Prerequisites and the step by step guide for MPesa API integration


It is indisputable that M-Pesa is the most widely accepted and used mode of payment in Kenya. The service allows users to store and transfer money through their mobile phones. Launched by Kenya’s largest mobile operator, Safaricom’s M-PESA has gained many subscribers since its inception in 2007.

In Kenya alone, M-Pesa has 30 million active users per month. Across the region, Safaricom’s mobile banking has at least 20 million other customers spread in markets across Tanzania, the Democratic Republic of Congo (DRC), Mozambique, Lesotho, Ghana, and Egypt. This exponential growth can be attributed to the innovation of new financial services such as M-Shwari, KCB M-Pesa, and Fuliza.

M-PESA products

Lipa Na Mpesa is the most popular M-pesa product. It allows businesses and individuals to collect payments from their clients. With the volume of mobile money transactions surging to 175.8 million in June 2021, every business needs to acquire an LNM Paybill/Till. Depending on the company’s need case, they can either acquire a Paybill or Till number. They almost function in a similar way only that the former allows users to enter the account number they are paying for.

To register a Paybill number, you need to visit a Safaricom shop with company registration documents like a certificate of incorporation, KRA PIN, and a Cancelled bank cheque confirming the company’s bank account details. However, it’s quite simple to acquire M-PESA Till number through the self-onboarding portal. It takes 24-48 working hours to process the request.

M-pesa shop

M-pesa API(Daraja) Integration

With the rapid adoption of technology in Kenya, the payment needs go beyond acquiring an M-Pesa paybill or till number. Some business models require M-Pesa integration with their ERP systems, websites, or mobile apps. For instance, banks use M-Pesa paybills to enable their customers to deposit money from M-pesa to their bank accounts.

Popularly known as Daraja, M-PESA API offers many endpoints to facilitate seamless and secure integrations. They include C2B API, B2C API, and B2B API. Other endpoints include Transaction status and Balance API. Below is a step-by-step guide on how to integrate C2B M-Pesa shortcode with ERP, website, or mobile app.

Step 1: Acquiring M-Pesa Till/Paybill Number

This is the first step. If you already have one, you can skip to the next step. To get a paybill or till number, assemble your KYC documents and visit the Safaricom shop or the self-onboarding portal.

Step 2: Get Head Office Number

Implementation of C2B requires a shortcode known as the head office number. For a paybill, the paybill number acts as the head office number. However, the same principle does not apply to Till numbers.

A till can have two or three different shortcodes depending on how it was registered to settle funds. If a till settles funds to a bank account, it comes with two shortcodes namely: Till number and store number. In this case, the store number acts as the head office number.

In the unfortunate event that the Till settles funds to the Owner’s nominated M-pesa number, the till requires an upgrade to be eligible for integration. An upgrade simply means changing funds settlement from an M-Pesa number to a bank account. To upgrade, send a request to M-pesaBusiness@safaricom.co.ke or lipanampesa@safaricom.co.ke. You must attach a canceled bank cheque or bank letter confirming bank account details. After a successful upgrade, the till gets a head office number, different from till and store numbers. This results in such a till having three different shortcodes.

NB: You will encounter a lot of trouble to get the head office number if the shortcode(especially a till) was acquired through a third party like banks and other middlemen.

Step 3: Creation in M-Pesa G2 portal

Once you have the head office number you are set to go. You are supposed to create a business administrator username that will later be used to go live in the Daraja portal. Fill administrator creation form available on-demand from the Safaricom M-Pesa business team. It has to be duly filled, stamped, and signed by two directors. If you are a sole proprietor, you need to indicate the same. In that form, fill the head office number as the shortcode.

You need to attach documents like an admin national ID(both sides) and a letter from the company’s board. The Board’s resolution letter should clearly show that you have been nominated to be their m-pesa business admin. Send a creation request to M-pesaBusiness@safaricom.co.ke or lipanampesa@safaricom.co.ke.

Tracking the admin creation request

You will immediately receive a tracking number for your request. In case of delay, you can contact M-Pesa Business support by email at M-pesaBusiness@safaricom.co.ke or call 2222 on your Safaricom line. Unfortunately, you need to be whitelisted first in order to be able to call the 2222 extension. They only whitelist M-Pesa nominated numbers.

Step 4: Creating Assistant roles

After getting G2 portal credentials, you need to log in here, change your password and create an assistant role user whose credentials will be used to go live in the Daraja portal.

M-pesa G2 portal login page

If you are not familiar with assistant roles, you can select default roles for a business manager. The account is always in pending active status until the assistant role user logs in. For a till you will need to create a child of the store number because the head office number does not receive callbacks.

Step 5: Create a Developer account on the Daraja portal

This is the second last step. Sign up on the daraja portal. Click go live and select verification by shortcode. Enter the assistant user username, select desired API products, and go live. You will receive production URLs in your developer’s email address immediately.

After approval, you are supposed to receive a passkey(in your email), which initiates payment requests automatically from the backend via STK PUSH.

Step 6: Register callback URLs and code your logic

This is the final step. You can register callback URLs and code the logic for processing payment notifications in the language of your choice.

In case you need help, contact Shadrack Matata(0729590095).

Facebook Comments Box
Share this on:
Previous articleYour identity can be stolen and used to secure employment using deepfake
Next articleTop web hosting companies in Kenya recommended for startups
Digital Comrade
Digital Comrade is a leading Internet Service provider empowering hundreds of thousands of Univeristy and college students in Kenya through technology.