Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.kiotapay.co/llms.txt

Use this file to discover all available pages before exploring further.

​
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
    "narration": "MOBILE PAYOUT",//Optional
    "customerName": "Doris" //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 ,a valid registered Tanzanian phone number or a valid registered Ugandan 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 , KSH and UGX
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.
narrationStringThis is an optional field that is only required for Uganda collections.
customerNameStringThis is an optional field that is only required for Uganda collections.
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": 10,
  "phoneNumber": "254728762287"
}