Getting Started

Here you'll find all the documentation you need to get up and running with the C2B M-PAY API.

This API will work together with related client services to deliver push and pull services to M-PAY merchants who wish to process C2B transactions automatically.

Pulling the API

The pull API will offer endpoints through which integrators can:

a) Query for a single Transaction searched by Mpesa transaction-id(OC33HSAKKK)

b) Query for multiple transactions related to a certain mobile number (254725742278)

c) Query for multiple transactions, where the amount and date match the amount and date values supplied.

d) Query for previously failed transactions. This will instruct the client service to try and resend any transactions that may have failed earlier.

e) Create test notifications for testing sandbox API and listening endpoints

Good to Know: In all cases, transactions that happened more than 24 hours before will be ignored. API will return a maximum of 10 records at a time to avoid network congestion.

The push service will forward new transactions to the URLs provided by the merchant. If the provided URL is not available at that particular moment, the transaction will be marked as failed but can be resent as described in c) above.

The base URL is http://40.114.209.253:87/

Push Service

The push service will POST new transactions as JSON to the https-secured URL provided by the merchant. If the merchant URL is not available at the POSTing moment, the transaction will be marked as failed but can be resent as described in the Query Failed Notification API. Below is the JSON format.

{
"SalmansId": "12456",
"TransactionType": 
"Customer Merchant Payment", 
"TransID": "OAH3FEH5DT", 
"TransTime": "20200804120859",
"TransAmount": "300.00", 
"BusinessShortCode": "12345",
"BillRefNumber": "WATER",
"OrgAccountBalance": "0.25",
"MSISDN": "0702021629",
"FirstName": "John",
"MiddleName": "Doe",
"LastName": "John", 
"CreatedOn": "2020-08-03 12:10:50.487000"
}

A successful response will have the following body

{
  "ResultCode" : 0,
  "ResultDescr": "Success"
}

And a Failed response will have the following body:

{
    "ResultCode": 1, 
    "ResultDescr": "Error Description"
}

The ResultCode value is a response is a numeric status code that indicates the status of the transaction processing. 0 means successful processing and any other code means an error occured or the transaction failed.

The ResultDescr value is a response describing the status of the transaction. A string with the message "Success or transaction has failed".

Header Parameters

Requests made on the base Url must use the following header info:

Parameter name	Description	Sample Value
Content-Type	Indicates the original media type of the resource (prior to any content encoding applied for sending.	application/json
ShortCode	A shortcode is a unique number that is allocated to a pay bill or buys goods organization through they will be able to receive customer payment. It could be a Pay bill, Buy Goods, or Till Number.	835625***
UnixTime	This is the Timestamp of the transaction, normally in the format of YEAR+MONTH+DATE+HOUR+MINUTE+SECOND (YYYYMMDDHHMMSS).	1607590160***
Authorization	Basic Auth over HTTPS, this is a base64 encoded string of an app's consumer key and consumer secret	base64.encode(Shortcode+Passkey+Timestamp)