M-Pesa Business to Consumer (B2C) API Integration Guide

In modern financial systems, processing outward payments is crucial for various applications, such as salary disbursements and merchant payments. The M-Pesa Business to Consumer (B2C) API facilitates these transactions, enabling companies to send payments directly to customers or other parties through M-Pesa. What is M-Pesa B2C API? It is a service that allows businesses to make payments to consumers efficiently.

This API is designed for Business to Customer (B2C) transactions, allowing businesses to send payments to end-users who receive these payments through M-Pesa. The B2C M-Pesa API is essential for businesses looking to streamline their payment processes.

To use the M-Pesa B2C API, you must have a valid and verified B2C M-Pesa Short code registered with Statum.

API Endpoint URL

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

Making an M-Pesa B2C API Request

To initiate a payment, send an HTTP POST request to the endpoint provided above. Ensure that you include the standard API request headers and the following fields in your request body:

Parameter	Type	Description	Example
short_code	String	The shortcode of the organization initiating the transaction. It should be registered on the Statum dashboard.	132345
phone_number	String	The phone number receiving the payment, formatted in international style.	254712345678
amount	String	The amount of money being transferred, specified in Kenyan Shillings (KES).	2000

Sample M-Pesa B2C API Request

Here’s an example of how to make a request using PHP:

<?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;

M-Pesa B2C API Response

The response from the API will be a JSON object with the following fields:

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

Sample M-Pesa B2C API Response Payload

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

Handling M-Pesa B2C API Results

The M-Pesa B2C API also sends notifications when certain events occur. To receive these notifications, configure a callback URL in your developer account settings. The notification POST parameters include:

Parameter	Type	Description	Example
request_id	String	A unique reference number assigned by the API.	20e0f508e00d41238fae6cbfe832443d
result_code	String	The result code indicating the outcome of the transaction.	200
result_desc	String	A description of the result or delivery status.	Processed Successfully
third_party_trans_id	String	The reference number assigned by the mobile money provider.	HR8584JDJD
short_code	String	The Paybill or Till number used for the transaction.	888555
transaction_time	String	The timestamp when the transaction occurred.	2017-05-18 18:23:23
account_balance	String	The balance of the Paybill or Buy Goods account after the transaction.	3000
bill_ref_number	String	An optional unique ID provided by the third-party system for Paybill payments.	QWERT
phone_number	String	The phone number of the subscriber making the payment.	254712345678
customer_name	String	The name of the subscriber who made the payment.	John Rambo
amount	String	The amount transacted.	2000

Sample M-Pesa B2C API Result Payload

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