KCB MPESA STK PUSH API SPECIFICATION DOCUMENT
Version 1.0
Introduction
The M-Pesa Express API, also known as STK Push, enables businesses to initiate
mobile money transactions on behalf of their customers. It simplifies the payment process
by prompting customers to approve payments directly on their mobile phones using their
M-Pesa PIN via the M-Pesa SIM Toolkit (STK), this document seeks to provide guidance
and specifications on how to integrate to M-Pesa Express (STK PUSH) API.
Prerequisites
The developer/third party needs to register/create account on the API gateway
accessible on the link: https://sandbox.buni.kcbgroup.com/devportal/apis
Guide on how to get started in consuming APIs is available on the following link
https://buni.kcbgroup.com/getting-started
Authorization (Bearer Token)
API Gateway requires the authentication tokens.
Token Generation
To generate a token for the M-Pesa Express API, use:
Endpoint: https://uat.buni.kcbgroup.com/token?grant_type=client_credentials
Create an application and subscribe to M-Pesa Express API then obtain consumer key and
consumer secret on Sandbox Keys.
1
To generate access tokens, you will have to pass basic authorization header whose value
is base64encode of the two keys above separated by a colon with no spaces between e.g.
Consumer Key:Consumer Secret.
The following sample curl example command shows how to generate an access token
from the above keys using the Password Grant type.
curl --location --request POST
'https://uat.buni.kcbgroup.com/token?grant_type=client_credentials' \
--header 'Authorization: Basic
RzNDRDU0QTK0T25PcFFxY1NvbFg3VFVuQmQpzN0JjJeEdWeWJUTKBLMlRPYT
FMUXdh' \
--header 'Cookie:
4b1f380494b4bbde9d5435be4996a54d=56b891aadc02ec5ac0a2dc4f95247c6d'
Note: The value of Basic Authorization header is the base64encode of the Consumer Key
and Consumer Secret separated by a colon with no spaces.
Mpesa Express Service
REQUEST
Transport Protocol HTTPS
Message Format JSON
Interaction Type Asynchronous
Method POST
Request Parameter Definition
REQUEST PAYLOAD
Name Type Presence Description
phoneNumber String Mandatory The mobile number to which the STK Pin
Prompt should be sent.
amount String Mandatory This is the amount to be transferred.
invoiceNumber String Mandatory Unique code assigned to each invoice.
Format: KCBTILLNO-YOURACCREF
2
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 Optional This is the organization’s short-code
used to identify an organization and receive
the transaction.
orgPassKey String Optional Unique pass key for the organization.
transactionDescription String Optional This is any additional information about the
payment.
callbackUrl String 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 Mandatory Unique code that indicates whether the
request successfully processed or not
statusDescription String Mandatory Provides additional information about the
status of the transaction.
response
3
MerchantRequestID String Mandatory Uniquely identifies the merchant request
ResponseCode String Mandatory Unique code that identifies the status of
the transaction.
CustomerMessage String Mandatory Information that describes thestatus of the
transaction.
CheckoutRequestID String Boolean Either true or false.
ResponseDescription String 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""ResultDesc":: 0"The service request is processed
successfully.", ,
"CallbackMetadata": {
4
"Item"{ : [
"Name": "Amount",
}, "Value": 1.00
{
"Name": "MpesaReceiptNumber",
"Value": "ABCDE12345"
}{,
"Name": "Balance"
}{,
"Name": "TransactionDate",
}, "Value": 20230721153232
{
"Name""Value": :"PhoneNumber" 254700000000,
}
]
}
}}
}
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
