How to integrate Mpesa Payment into your Website - Introduction

Rai Omido

Over the past few years, Mpesa has increasingly become one of the most popular mobile payment solutions.

More businesses that operate online are embracing it as one of their payment gateways. However, the process is not very straight forward and as such can prove to be a very daunting task.

Many Software Engineers almost always find it difficult to crack at first. It doesn’t have to be that way. Over the past few weeks, I have had a couple of people asking me to either create a tutorial or guide them along the way.

I decided to give it a shot. Hopefully, this will help one or two people out there. If there’s anything that’s unclear, please leave a comment and I will be glad to have a look.

# Getting started

This tutorial aims to help the learner better understand how they would integrate Mpesa into their website.

The general process is pretty straight forward from the official documentation but can be a little challenging if you're just starting out.

The most frustrating part about the process is the scanty information. Even from the official documentation, it can be quite challenging to figure out your way around things. A good example is the fact that apparently, you can only access the Mpesa G2 portal on a windows computer. More about that later.

In this tutorial, I will try as much as possible to explain to you how the system works generally, including how to go through the process of getting approved so that you can have access to the production API.

There are several APIs you can integrate. However, for starters, I will focus on one part (C2B), that is, accepting customer payments to your website. Once you are able to successfully integrate one of the APIs, integrating the rest becomes much easier.

~The difference between a Paybill Number and a Till Number

A Paybill number is used for paying bills. It is used by regular customers of a business to pay for services offered to them on a regular basis. For example, Electricity and Water bills. The customer needs to have an established relationship with the business, that is, have some form of 'account' with the business.

A Till number, on the other hand, is used by customers of a business to pay for goods and services. They do not need to be regular customers.

You can use either of the two on your website. However, when you use a till number, the customer will have to "claim" the transaction by providing the Mpesa transaction id after making the payment. With a Paybill number, on the other hand, you may provide the user with an "account number" on a payment page, which they key in when making payment. The account number will be sent to your website alongside the transaction information from Mpesa. You can then use this account number to identify the user and balance your accounts. This is especially suitable for those intending to create some form of Wallet, which can hold customers' money on your website.

# Prerequisites

In order to avoid getting stuck and frustrated when you want to move your code to production, I am going to share with you some important things that you need to have to have in place even as you proceed with development.

~The shortcode

Your shortcode refers to either the Paybill number or Till number.

If you do not have it yet, you can follow the steps on my post here How to apply for Mpesa Paybill Number/ Till Number

~A safaricom developer account

You will need to create an account on Safaricom's developer platform dubbed Daraja.

This is where you will obtain the authentication credentials for your application (both sandbox and live), and test credentials for testing the app before moving to production.

If you haven't created your developer account yet, head over to https://developer.safaricom.co.ke/ and create it.

~Mpesa Business Administrator account

You need to have an account on the Mpesa G2 platform in order to view transactions and to authorize operations on the shortcode when you move to production.

Please take note of the following before we proceed further;

You need to send an email  to Safaricom, requesting them to create the G2 account for you. It's not something you can sign up for on your own.

Additionally, in order to access the G2 portal website, you need to have a certificate signed by the Mpesa people, installed on your  computer. A little trouble might arise when trying to apply for and installing the certificate. This is because the certficate issuing website uses Visual Basic, and ussually needs to run some VB scripts on your computer. That might mean, you can only use the portal on a Windows computer. But it's not something you can't handle. We will see how to go about this later in this tutorial.

Applying for an Mpesa G2 portal Account

In order to have an account created, you need to send an official email to M-PESABusiness@safaricom.co.ke requesting the creation. In the Email, you need to attach a scanned copy of the following documents;

  • A copy of your business registration certificate.
  • A duly signed and stamped letter requesting the account creation. You need to write this letter on your business letterhead.
  • A copy of the business owner's identification document.

Sample Email

Subject: Request for Creation of Mpesa Business Administrator Account

Dear Safaricom

I would like to request you to create an Mpesa Business Administrator Account for my Paybill/ Till Number. Please find attached the necessary documents.

Kind Regards,
Blah Blah

Sample Letter

Mpesa Business Administrator Account Sample Application Letter

If there're any additional requirements, they'll definitely let you know.

~Mpesa Certificate

To apply for an Mpesa certificate, you first of all need to send a blank email to M-PESACertpassword@safaricom.co.ke. In a few minutes time, you will receive an automated response with a link, username, and password to the certificate request website.

Do you remember the thing we said about that website using VB? Well, this is where it gets interesting.

Apparently, apart from requiring you to use Internet Explorer on Windows, it turns out that the certificate issuing website cannot work in the later versions of Internet Explorer. It only works in IE 7. So, if you're lucky enough to be working on a Windows machine, but don't have IE 7, you'll need to do some tweaking to your current version of IE in order to get the website to work properly.

See steps here Applying and Installing the Mpesa Digital Certificate

~Final thoughts

At this point, it's now time to proceed with writing code. Since I specialize in PHP, I will write a sample implementation in PHP. Later on, I might also do a sample implementation in Python.

However, the aim of this first introductory part was to give you an overall overview of how the process works. My goal was to help you avoid that general sense of lack of direction which can lead to frustration, so that you can focus on writing your code with confidence.

What's next?

How to integrate Mpesa Payment into your Website - Writing the code (PHP implementation)