Statum Company Logo

M-Pesa Consumer To Business API

Imagine the different scenarios that require customers to pay and have this payment processed instantly!

In this day and age, cash payments are continuously advancing with customers leaning more and more towards mobile money payments. The use cases where C2B (Consumer To Business) transactions can take place vary widely from utility bills to e-commerce. This method of instant payment is convenient to both the merchant and the customer.

This API enables Pay bill and Buy Goods merchants to integrate to M-PESA Mobile Money and receive real time payments notifications.

Getting started is easy. All you will need is a to provide us with your Pay bill or Buy Goods number. You can have as many products (Pay bill or Buy Goods number) as you wish, and each will be linked to Safaricom's M-PESA through their payment channels.

Consumer To Business Payment validation

Where available, validation is usually the first callback that is invoked in order to complete a C2B transaction. This allows the detection of some error cases (for example wrong account number or amount), thereby reducing the need to reverse these transactions.

You can enable C2B validation for your payment product by configuring a validation URL in your account. The POST request that we submit to your validation callback URL will contain a JSON-encoded object that has the following parameters below. The parameter description is as on the table below.

Sample API validation request

{
  "result_code": "200",
  "result_desc": "Processed Successfully",
  "request_id": "Rm20180307054639H4adfKDJDKQ7H",
  "phone_number": "254712345678",
  "customer_name": "James Rambo",
  "amount": "200",
  "short_code": "888555",
  "bill_ref_number": "QWERT",
  "third_party_trans_id": "HR8584JDJD",
  "account_balance": "34000.00",
  "transaction_time": "2017-05-18 18:23:23"
}

Sample API validation response

Once you receive a validation callback notification you’ll be expected to send back a valid JSON response that marks the transaction as "status_code" 200 for Validated or "status_code" 400 for Failed. If Validated we will proceed to complete the transaction, if Failed, we will cancel the transaction.

Parameter Type Description Example
status_code Number The status code of the transaction.
200 for Validated, 400 for Failed
200
description String The description of the status code. Validated
{
    "status_code": 200, // or 400
    "description": "Validated" // or "Failed"
}

Consumer To Business Payment confirmation

Notification is the final step in completing a transaction.

Once we receive a payment notification to your Pay bill or Buy Goods number, we will process it and send you a simple JSON request notifying you about the completion of the transaction.

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 Rw20180307054639H4adfKDJDKQ7H
result_code String The result code of the transaction. 200
result_desc String The result description of transaction status. Processed Successfully
third_party_trans_id String The reference number as assigned by the mobile money provider HR8584JDJD
short_code String The Paybill 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 Paybill, Buygoods account balance 34000.00
bill_ref_number String The account number as entered by the subscriber. (optional – only for Paybill 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 200

Sample API result payload

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