The Updated M-PESA Daraja API Integration Guide


It is indisputable that M-Pesa is currently the most widely accepted and used mode of payment in Kenya. The service allows its 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. This Safaricom subsidiary is currently the 4th most valuable brand($245.6m) in Kenya according to a recent report by Brand Finance.

In Kenya alone, M-Pesa has over 30 million active users on monthly basis. 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 its new financial service innovations such as M-Shwari, KCB M-Pesa, Fuliza, and M-pesa global pay among others.

M-PESA products

Lipa Na Mpesa is arguably 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, virtually 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 paybill plate

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 payment 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, a website, or even a 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, this does not apply to Till numbers.

A till can have two or three different shortcodes depending on how and where it settles 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 [email protected] or [email protected]. 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: Getting the head office number for shortcodes(especially a till) acquired through a third party like banks and other middlemen is usually chaotic. It is advisable to apply the till/paybill number directly from Safaricom if you wish to use it for payment integrations.

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. This form 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 someone has been nominated to be their m-pesa business admin. Send a creation request to [email protected] or [email protected].

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 [email protected] or call 2222 on your Safaricom line. Unfortunately, one has 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 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, a passkey is sent(to the developer’s email address) which is used to initiate payment requests automatically from the backend via STK PUSH.

Daraja portal screenshot

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.