Lipa na M-Pesa Online API Integration Guide

The Lipa na M-Pesa Online API provides seamless integration for online payments using M-Pesa's STK Push technology. This feature allows merchants to facilitate secure and efficient transactions directly through the mobile payment system.

The STK Push technology enables customers to complete payments by selecting items online and authorizing transactions via their mobile phones. Once a customer enters their mobile number at checkout, they receive a notification to confirm the payment using their M-Pesa PIN. The transaction amount is then deducted from their M-Pesa account.

To use the Lipa na M-Pesa Online service, you must provide a Paybill or Buy Goods number for the transactions. This integration makes it easy for businesses to manage online payments securely.

HTTP POST Resource URL

https://api.statum.co.ke/api/v2/mpesa/online

Lipa na M-Pesa Online API Request

To make a payment through your application, send an HTTP POST request to the endpoint above. Along with the API standard request headers, include the following fields in the request body:

Parameter	Type	Description	Example
short_code	String	The organization’s shortcode for receiving transactions. This shortcode must be registered with Statum.	888555
phone_number	String	The subscriber's phone number making the payment, formatted in international style.	254721553678
amount	String	The total amount of the transaction in Kenyan Shillings (KES).	2000
bill_ref_number	String	An optional unique ID for Paybill payments, provided by your third-party system.	QWERT

Sample Lipa na M-Pesa Online API Request

Here is a sample PHP request to illustrate how to interact with the Lipa na M-Pesa Online API:

<?php
// API credentials
$consumerKey = "568473daf6614cb196caeb5f8805985f";
$consumerSecret = "5a07f41de16e40e4b08b4001142a5a10";
$auth = base64_encode($consumerKey . ":" . $consumerSecret);

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.statum.co.ke/api/v2/mpesa/online',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
      "phone_number": "254721553678",
      "short_code": "709345",
      "amount": "2000",
      "bill_ref_number": "QWERT"
    }',
  CURLOPT_HTTPHEADER => array(
        "Authorization: Basic $auth",
        "Content-Type: application/json"
      ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Lipa na M-Pesa Online API Response

The API response is a JSON object with the following fields:

Parameter	Type	Description	Example
status_code	Number	The status code of the transaction response.	200
description	String	A textual description of the transaction status.	Operation successful
request_id	String	The unique identifier assigned to the request by the Statum API.	35235f08c981474abd388755ed43a427

Sample Lipa na M-Pesa Online API Response Payload

{
    "status_code": 200,
    "description": "Operation successful.",
    "request_id": "35235f08c981474abd388755ed43a427"
}

Lipa na M-Pesa Online API Result Notifications

The Lipa na M-Pesa Online API sends notifications for specific events. To receive these notifications, you must set up a callback URL in your developer account. The POST parameters included in these notifications are as follows:

Parameter	Type	Description	Example
request_id	String	The unique reference number assigned by our API.	Rw20180307054639H4adfKDJDKQ7H
result_code	String	The result code indicating the outcome of the transaction.	200
result_desc	String	A description of the transaction status.	Processed Successfully
third_party_trans_id	String	The reference number provided by the mobile money provider.	HR8584JDJD
short_code	String	The Paybill or Till number being used for the transaction.	888555
transaction_time	String	The timestamp of the transaction.	2017-05-18 18:23:23
account_balance	String	The balance of the Paybill or Buygoods account.	34000.00
bill_ref_number	String	The reference number entered by the subscriber (optional for Paybill payments).	QWERT
phone_number	String	The phone number of the subscriber making the payment.	2547*****149
customer_name	String	The name of the customer who made the payment.	James
amount	String	The amount of the transaction.	2000

Sample Lipa na M-Pesa Online API Result Payload

{
  "result_code": "200",
  "result_desc": "Processed Successfully",
  "request_id": "35235f08c981474abd388755ed43a427",
  "phone_number": "2547*****149",
  "customer_name": "James",
  "amount": "2000",
  "short_code": "888555",
  "bill_ref_number": "QWERT",
  "third_party_trans_id": "HR8584JDJD",
  "account_balance": "34000.00",
  "transaction_time": "2017-05-18 18:23:23"
}