Mpesa API Integration Assistant (Daraja - Safaricom Kenya)

Get an Mpesa API Integration Assistant that makes your work very easy. This is an easy to follow guide that introduces you to the technology of API integration on the Mpesa API known as Daraja from safaricom Kenya. For those looking for Mpesa API integration from other countries, that is well covered elsewhere on this website. In this post, we specialize with Safaricom owned Daraja Mpesa API version 2.0.

Note: Here is an easy to follow ready-made Mpesa API integration assistant. What you need is the information we will tell you on each Mpesa API Integration Assistant and fill it in the way we will tell you, execute and you are done.

Without digressing too much, let us dive in into the Mpesa API with important topic areas that break down this technical topic making it very easy to Understand. The topics in this Mpesa API integration are:

1. Definition of Mpesa API related terminology.
2. Types of Mpesa APIs to Integrate to
3. Requirements needed to successfully Integrate any application with the Mpesa API
4. Examples of integrating Mpesa API using different vanilla programming languages.
5. Examples of Integrating the Mpesa API on differen frameworks.
6. Examples of Integrating the Mpesa API on a mobile app using different programming languages.
7. Going Live on Daraja

Definition of terms related to Mpesa API integration

To start with, let us define terminologies that relate to the entire discipline or technicalities involved in Mpesa Integration. When you understand these terms, it becomes very easy to understand them when they are used in a development setting or environment.

Through this definition, it is easy to pick that an Mpesa API Integration is a process that helps you join Mpesa to something else. This something else could be a website, mobile app or a standalone software. This essentially means that the Mpesa API Integration assistant would join Mpesa mobile money to your web apps, mobile apps and software to start accepting mobile money on them by providing an Mpesa payment gateway for your users to pay for your goods and services using their mpesa mobile wallets.

Types of Mpesa APIs to Integrate to.

We have three major Mpesa APIs and so are there our three types of Mpesa API integration assistants. In between them are other useful APIs that work within those three major Mpesa APIs.

These are:

1. Mpesa C2B API

You want to integrate to this Mpesa API if you simpply want a way to receive Mpesa transaction responses from the Mpesa servers directly to your system. You can save these transactions into an Mpesa payments database or simply execute your application business in realtime immediately you receive payments. More details and application of this Application programming Interface in the paragraphs below.

2. Mpesa B2C API

This Mpesa API is integrated to when you want to send Payments to customers mpesa phone numbers. B2C is an acronym for business to customer. May be you want to do Bulk Payments directly from your Paybill or Till to mpesa phone numbers or simply to pay salaries to disburse money to individual mpesa numers for whatever reason, not using the Mpesa portal or manually via the phone but through your software, mobile app or website. This is the Mpesa API to think about. I will give more details in the paragraphs below as we do some application.

3. Mpesa Express API or Stk Push API

Have you heard about the Mpesa Popup message that asks you "Do you want to Pay Ksh. 3000 to ABZ company for the account 1234" then it asks for your PIN to compete transaction? This is done using the Mpesa express Mpesa API. After integration, customer phones are requested to make payment and a callack response is sent to your filled in callback url containing the response from Mpesa API about that specific stk push payment request.

1.Mpesa C2B API Integration

This Mpesa API Integration Assistant will help you integrate Mpesa C2B API in a few clicks. Just follow the steps we give you in the below guide. By the end of this guide, you should be able to receive a transaction from mpesa into your application via the Daraja API and process your business logic. In my case, I will show you how to save into a database and exactly how to process a realtime business logic based on a loan repayment application.

The requirements of integrating a C2B Mpesa API are: A shortcode (Paybill or Till numer with a store number), an Mpesa portal admin username, a Daraja app with the necessary credentials and some programming skills in your language of choice. For the same of demonstration, I will use vanilla/Plain/pure PHP to show you simply how the Mpesa API is done.

In this part, let me demosntrate in simle steps how to get the required credentials from Safaricom. For the sandbox API credentials, it is quote simple. Follow the steps below and you will have them:

• Step 1: Register and login the Daraja portal. This is found on developer.safaricom.co.ke
• Step 2: While logged in, make sure you click My Apps and ensure the active entity is Sandbox
• Step 3: Click Create a New App, name the app and select the Mpesa Sandbox product and Create App
• Step 4: The created App now has a consumer key and Consumer secret which you will need later.
• Step 5: Click the APIs menu on top, click the Customer to Business API link
• Step 6: On the left side, you will see simulator. Select your created sandbox App and go Down to click the Test Credentials Icon to open the Open the Test Credentials
• Step 7: Copy the BusinessShortCode to be used as your sandbox Shortcode and that is all for collecting the API credentials for your C2B Mpesa API.

The next part is now to write the code as per your programming language to actually do the Integration. As promised, I will do in PHP below. Feel free to do in your porgramming language or hire an experienced programmer to Integrate your application on your behalf. And because we actually know how to do it, why not hire us!!!

Part 1 of the Mpesa C2B API integration is to simply write the code in your urls. There are two urls needed. One is known as confirmation url and the second is known as the validation url. The confirmation url actually does the confirmation of the transaction and this where you write most of your confirmed transacton logic. The validation url is where you actually validate your transaction. If invalid, you can execute a logic of refunding or simply ignoring it. The Mpesa API will do exactly as the validation and confirmation url says.

The confirmation url can look something like below in PHP:

       
        //store the received Mpesa transaction in a variable
        $mpesa_response = file_get_contents('php://input');

        //I can log so I see how it looks like. 
        //Check in your server for a file named as confirm.json
        // and open it to see how a transaction looks like after it is made

       $logFile = "confirm.json";
       $log = fopen($logFile, "a");
       fwrite($log, $mpesa_response);
       fclose($log);

     //the transaction json will look something like below

      {
            "TransactionType": "Pay Bill",
            "TransID": "PGV31DMXVD",
            "TransTime": "20210731160928",
            "TransAmount": "1.00",
            "BusinessShortCode": "9999999",
            "BillRefNumber": "TestWithBrian",
            "InvoiceNumber": "",
            "OrgAccountBalance": "1.00",
            "ThirdPartyTransID": "",
            "MSISDN": "254706745202",
            "FirstName": "BRIAN",
            "MiddleName": "WAMBUA",
            "LastName": "MBIKI"
        }

     //You can then make the above json response an array so that you can access the objects in it.

    $array = json_decode($mpesa_response, true);

    //now after this is upon you to do whatever you want like mine below

   if($mpesa_response && $mpesa_response !=''){

   //store in db

   //execute your realtime business logic like repaying the loan of the person with account  "BillRefNumber"

   }else{

//keep quiet here

  }


    

The validation url will look something like below in PHP:

       
        //store the received Mpesa transaction in a variable
        $mpesa_response = file_get_contents('php://input');

        //I can log so I see how it looks like. 
        //Check in your server for a file named as confirm.json
        // and open it to see how a transaction looks like after it is made

       $logFile = "confirm.json";
       $log = fopen($logFile, "a");
       fwrite($log, $mpesa_response);
       fclose($log);

     //the transaction json will look something like below

      {
            "TransactionType": "Pay Bill",
            "TransID": "PGV31DMXVD",
            "TransTime": "20210731160928",
            "TransAmount": "1.00",
            "BusinessShortCode": "9999999",
            "BillRefNumber": "TestWithBrian",
            "InvoiceNumber": "",
            "OrgAccountBalance": "1.00",
            "ThirdPartyTransID": "",
            "MSISDN": "254706745202",
            "FirstName": "BRIAN",
            "MiddleName": "WAMBUA",
            "LastName": "MBIKI"
        }

     //You can then make the above json response an array so that you can access the objects in it.

    $array = json_decode($mpesa_response, true);

    //now after this is upon you to do whatever you want like mine below

   if($mpesa_response && $mpesa_response !=''){

   //reject the transaction

   //Check whether this is the right transaction was sent for the right purpose and accept it if so.

   }else{

//keep quiet here

  }


    

If you have been keen, these urls appear the same except the part where you are to act on the received transaction. Ideally, the Mpesa API will send the transaction to the validation url first and if accepted, will then send to the confirmation url for logic processing. Therefore, make sure you write as code what you want the validation url to do otherwise it may reach or not reach your confirmation url and this may jeorpadize your business logic if the opposite of your needs happens.

Part 2 which is the last part of the Mpesa C2B API integration is to register the two urls. Once registered, these are the only urls which are used as the endpoints by the Mpesa API to communicate to your application or servers when a transaction happens for your paybill.

What to do in case you want to de-register registered urls or register new ones.

Sometimes, you may wish to de-register or remove the already registered urls for your Paybill. This is done through either of the fowing methods:

1. You can contact safaricom API team via email and they will help you. This may take sometime and you wil need to fill a signed letter with a letter head of your company and company or business seal/stamp stating the shortcode to have the urls changed for. After they change it, they will notify you and you can register new ones afresh if need be.
2. The second method is to de-register them through the Daraja portal. This is quite a process that you need to follow.

How to self de-register urls for your Paybil via the Daraja portal.

• Login your Daraja account on developer.safaricom.co.ke
• Click Self services top menu
• Click Url Management
• Enter your Mpesa shortcode and your First Mpesa portal username. Click Next Step and receive an OTP via your registered phone number and a field to enter the OTP appears.
• Enter the OTP and click Next Step
• Enter your second Mpesa portal username and click Next step and you will receive another OTP. Enter it and when you click next, the registered urls for that shortcode will appear.
• Click to Delete them. You are done.
• You can now register your urls afresh if need be.

2. Mpesa Express (Lipa na Mpesa Online) API Integration

Do you want that smart popup that your clients will receive on their phone with your company names, amount to pay, and for what reason with a PIN input field to just fill and fuaaaah, the transaction completes and your business logic continues? If so, then this is what is known as Mpesa Express.

Mpesa Express (Lipa na Mpesa Online) API Integration will help you integrate your website or App within minutes and through a few clicks. In this guide we will try get you to know how to do this in a simpe way.

Where to get the Mpesa Express API Integration requirements

The table below shows the Mpesa Express API requirements and where and how to get them.

3.Mpesa B2C mpesa api integration assistant.

This is for the businesses who are interested in sending or paying money to their customers of partners direct to their mpesa phone wallets. It simply means business to customer API integration helper.