Statum Company Logo

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"
}
Copyright © 2021 Statum Ltd