Skip to main content

​
STK Push Collection API

This API allows a company to initiate an STK (Sim Toolkit) push collection for mobile payments.

​
Endpoint

POST /api/sandbox/v1/stk/new

​
Base URL

https://api.kiotapay.co

​
Request Headers

KeyValueRequiredDescription
Content-Typeapplication/json✅Specifies that the request body is in JSON format.
AuthorizationBearer <your-token>✅API authentication token. Replace <your-token> with a valid JWT.

​
Request Body

The body must contain the following fields: 
{
    "description": "Here is the description",
    "phoneNumber": "254745362174",
    "amount": 10,
    "accountReference": "Here is the reference",
    "callbackUrl": "https://kiotapay.co.ke",
	"currencyCode":"KSH", // KSH, TZS
    "channel": "TZ-AIRTEL-C2B", // Optional
	"referenceId":"1234" // Optional
}
Explanation
FieldTypeDescription
descriptionStringThis is any additional information/comment that can be sent along with the request from your system. Maximum of 13 Characters.
phoneNumberStringA valid phone number where the push will be sent It must be a valid registered Kenyan phone number or a valid registered Tanzanian phone number.It’s Mandatory.
amountIntegerThis is the Amount transacted normally a numeric value. Money that the customer pays to the Shortcode. Only whole numbers are supported.
accountReferenceStringAccount Reference: This is an Alpha-Numeric parameter that is defined by your system as an Identifier of the transaction for the CustomerPayBillOnline transaction type. Along with the business name, this value is also displayed to the customer in the STK Pin Prompt message. Maximum of 12 characters.
Mandatory only on if it’s a KSH request.
callbackUrlStringA valid POST url where the callback will be sent
currencyCodeStringThis refers to the currency for the collection.
The only valid codes are TZS and KSH.
This request defaults to KSH.
channelStringThis is an optional field and is only required for Tanzania collections.
It refers to a valid channel. The supported channels are; TZ-TIGO-C2B and TZ-AIRTEL-C2B.
referenceIdStringThis is an optional field that represents the request ID from your system. It can be used to query the transaction, as it maps to the identifier used in your system.
Sample Response Body 
{
    "status": 201,
    "message": "Stk request has been accepted for request",
    "data": {
        "requestId": "4dc43b5a-d43f-4b0e-b677-3a6167d2c654",
        "phoneNumber": "0745362174",
        "requestedAmount": 10.0
    }
}
Sample Callback Body 
{
  "requestId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "SUCCESS", // SUCCESS, FAILED, PENDING
  "amount": 1500,
  "phoneNumber": "254728762287"
}