M-Pesa Mobile Business To Consumer API

Many systems that process receipts will also require outward payments processing. This could range from employees' salary disbursements to paying other merchants that accept M-PESA payments.

This API enables Business to Customer (B2C) transactions between a company and customers who are the end-users of its products or services.

Use of this API requires a valid and verified B2C M-Pesa Short code.

HTTP POST Resource URL

https://api.statum.co.ke/api/v2/mpesa-wallet

API Request

Make payment through your application by making a HTTP POST request to the endpoint above.

In addition to the API standard request headers, the body of the request should contain the following fields:

Parameter	Type	Description	Example
short_code	String	Organization’s shortcode initiating the transaction; should be registered on the dashboard	132345
phone_number	String	Phone number receiving the amount in international format	254712345678
amount	String	The amount being transacted in Kenya Shillings.	2000

Sample API request

<?php

$curl = curl_init();

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

$response = curl_exec($curl);

curl_close($curl);
echo $response;

API response

The body of the response will be a JSON object containing the following fields:

Parameter	Type	Description	Example
status_code	Number	The status code of the transaction.	200
description	String	The status description of the transaction.	Operation successful
request_id	String	The unique reference number as assigned by the Statum API	35235f08c981474abd388755ed43a427

Sample API response payload

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

API result

The M-Pesa Mobile Business To Consumer (B2C) API sends a notification when a specific event happens. To receive these notifications you need to setup a callback URL on your developer account.

The POST parameters that will be passed will be as follows:

Parameter	Type	Description	Example
request_id	String	The unique reference number as assigned by the our API	20e0f508e00d41238fae6cbfe832443d
result_code	String	The result code of the transaction.	200
result_desc	String	The result description of delivery status.	Processed Successfully
third_party_trans_id	String	The reference number as assigned by the mobile money provider	HR8584JDJD
short_code	String	The Pay bill number or Till number being paid to	888555
transaction_time	String	The date and time stamp of the transaction	2017-05-18 18:23:23
account_balance	String	The Pay bill, Buy goods account balance	3000
bill_ref_number	String	The unique id passed by the third party system. (optional – only for Pay bill payments).	QWERT
phone_number	String	The subscriber's phone number (subscriber making the payment)	254712345678
customer_name	String	The name of the subscriber who made the payment	John Rambo
amount	String	The transaction amount	2000

Sample API result payload

{
  "result_code": "200",
  "result_desc": "Processed Successfully",
  "request_id": "35235f08c981474abd388755ed43a427",
  "phone_number": "254712345678",
  "customer_name": "James Rambo",
  "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"
}