Initiate an STK push

Push a payment prompt to a customer's phone. They approve it with their mobile money PIN and the funds land in your Kiotapay wallet.

The response comes back immediately with a requestId; the customer has not paid yet at that point. The outcome arrives on your callbackUrl once they approve, decline, or the prompt times out.

Conditionally required fields

Currency	Additionally required
`KSH` (Kenya)	`accountReference`
`TZS` (Tanzania)	`channel`
`UGX` (Uganda)	`narration`, `customerName`

Watch the length limits: description is capped at 13 characters and accountReference at 12, because both are rendered inside the PIN prompt on the customer's handset.

Authorization

bearerAuth

AuthorizationBearer <token>

The access_token returned by POST /api/v1/get-token.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

phoneNumber*string

The number to prompt, in international format. Must be a registered Kenyan, Tanzanian or Ugandan mobile money number.

amount*integer

Amount to collect. Whole numbers only.

callbackUrl*string

A publicly reachable endpoint accepting POST, where the result is delivered.

Formaturi

description?string

Free-text comment carried with the request. Maximum 13 characters.

Lengthlength <= 13

accountReference?string

Alphanumeric identifier for the transaction, shown to the customer in the STK PIN prompt alongside your business name. Maximum 12 characters. Required for KSH.

Lengthlength <= 12

currencyCode?CurrencyCode

Currency of the transaction. KSH — Kenyan shilling, TZS — Tanzanian shilling, UGX — Ugandan shilling.

Default"KSH"

Value in

"KSH"
"TZS"
"UGX"

channel?string

Mobile money channel to collect through. Required for TZS.

Value in

"TZ-TIGO-C2B"
"TZ-AIRTEL-C2B"

narration?string

Short narration. Required for UGX.

customerName?string

Customer's full name. Required for UGX.

referenceId?string

Your own system's request ID, stored against the transaction so you can query by your identifier.

Response Body

`application/json`

Callbacks

curl -X POST "https://example.com/api/sandbox/v1/stk/new" \  -H "Content-Type: application/json" \  -d '{    "phoneNumber": "254745362174",    "amount": 10,    "currencyCode": "KSH",    "description": "Order 4821",    "accountReference": "INV-4821",    "callbackUrl": "https://kiotapay.co.ke",    "referenceId": "1234"  }'

{  "status": 201,  "message": "Stk request has been accepted for request",  "data": {    "requestId": "4dc43b5a-d43f-4b0e-b677-3a6167d2c654",    "phoneNumber": "0745362174",    "requestedAmount": 10  }}

Initiate an STK push

Conditionally required fields

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

Callbacks

transactionResultPOST{$request.body#/callbackUrl}

`application/json`

`application/json`

`application/json`