KCB MPESA STK PUSH API SPECIFICATION DOCUMENT

Version 1.0

Introduction
This Interface speci/ication document describes the integration points between a third-
party system and the KCB API Gateway, for the Mpesa Express/STK Push service via KCB
Bank’s paybill 522533.

Prerequisites
The developer/third party needs to register on the API gateway accessible on the
below link.
https://sandbox.buni.kcbgroup.com/devportal/apis

Guide on how to get started in consuming our APIs is available on the following link
https://buni.kcbgroup.com/getting-started

Authentication Token
Use the below curl to generate the token
curl --location 'https://uat.buni.kcbgroup.com/token?grant_type=client_credentials' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic
OOE5NaF9qMWZJeE9seWZhZjQ0NzYTpoYnRZdGQzZTFfX0E3elBHb2ZvY1pKRk5scUFh' \
--data-urlencode 'grant_type=client_credentials'

Mpesa Express Service

REQUEST

Transport Protocol HTTPS

Message Format JSON

Interaction Type Asynchronous

Method POST

1
Request Parameter Definition
REQUEST PAYLOAD

Name Type Presence Description

phoneNumber String(20) Mandatory The mobile number to which the STK Pin Prompt
should be sent.
amount String(30) Mandatory This is the amount to be transferred.

invoiceNumber String(30) Mandatory Unique code assigned to each invoice. Format:

KCBTILLNO-YOURACCREF

sharedShortCode Boolean Mandatory This is KCB’S short-code (Paybill or Till) used to

receive the transaction.
If provided value should be set to true.
orgShortCode String(30) Optional This is the organisation’s short-code used to
identify an organisation and receive the transaction
orgPassKey String(30) Optional Unique pass key for the organization.

transactionDescription String(30) Optional This is any additional information about the

payment
callbackUrl String(50) Mandatory Endpoint to which the M-Pesa API will send the
results. Must be a secure URL

Sample Request

{
"phoneNumber": "254700123456",
"amount": "1",
"invoiceNumber": "KCBTILLNO-YOURACCREF",
"sharedShortCode": true,
"orgShortCode": "",
"orgPassKey": "",
"callbackUrl": "https://posthere.io/f613-4b7f-b82b",
"transactionDescription": "school fee payment"
}

Response Parameter Definition

RESPONSE PAYLOAD

Name Type Presence Description

header Mandatory

statusCode String(30) Mandatory Unique code that indicates whether the request
successfully processed or not
statusDescription String(30) Mandatory Provides additional information about the status
of the transaction.
response

MerchantRequestID String(30) Mandatory Uniquely identiVies the merchant request

2
 ResponseCode String(30) Mandatory Unique code that identiVies the status of the
transaction.
CustomerMessage String(30) Mandatory Information that describes the status of the
transaction.
CheckoutRequestID String(10) Boolean Either true or false

ResponseDescription String(30) Mandatory Provides additional information about the

response code.

Sample Response

{
"response": {
"MerchantRequestID": "7432-920544-1",
"ResponseCode": "0",
"CustomerMessage": "Success. Request accepted for processing",
"CheckoutRequestID": false,
"ResponseDescription": "Success. Request accepted for processing"
},
"header": {
"statusDescription": "Success. Request accepted for processing",
"statusCode": "0"
}
}

Sample Result
{
"Body": {
"stkCallback": {
"MerchantRequestID": "17684-56147665-1",
"CheckoutRequestID": "ws_CO_21072023153404650713165445",
"ResultCode": 0,
"ResultDesc": "The service request is processed successfully.",
"CallbackMetadata": {
"Item": [
{
"Name": "Amount",
"Value": 1.00
},
{
"Name": "MpesaReceiptNumber",
"Value": "ABCDE12345"
},
{
"Name": "Balance"
},
{
"Name": "TransactionDate",
"Value": 20230721153232
},
{
"Name": "PhoneNumber",
"Value": 254700000000
}
]
}
}
}
}

3
HTTP Response Codes
Response code Description

200 Request processed successfully

400 Bad request

401 Unauthorized request

403 Request is forbidden

404 The request resource is not found

500 Internal Host Error

503 Service unavailable

For any additional support, please write to buni@kcbgroup.com