Send money to a mobile wallet

Transfer funds from your Kiotapay wallet to a recipient's mobile money wallet.

The response is returned immediately with a PENDING status and a requestId. The final outcome is delivered asynchronously to your callbackUrl — use the requestId to reconcile it against your own records.

Conditionally required fields

Which fields you must send depends on currencyCode:

Currency	Additionally required
`KSH` (Kenya)	`remarks`, `occasion`
`TZS` (Tanzania)	`narration`, `firstName`, `lastName`, `serviceCode`
`UGX` (Uganda)	`narration`, `customerName`

For TZS, the minimum payout is 1,000 TZS.

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 recipient's phone number in international format. Must be a valid registered Kenyan, Tanzanian or Ugandan number.

amount*number

Amount to send, in the currency given by currencyCode. For TZS the minimum is 1,000.

callbackUrl*string

A publicly reachable endpoint that accepts POST. Kiotapay delivers the transaction result here. Required for every currency.

Formaturi

currencyCode?CurrencyCode

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

Default"KSH"

Value in

"KSH"
"TZS"
"UGX"

remarks?string

Brief description of the transaction. Required for KSH.

occasion?string

Short text describing the purpose of the transaction. Required for KSH.

narration?string

Short narration of the transaction. Required for TZS and UGX.

firstName?string

Recipient's first name. Required for TZS.

lastName?string

Recipient's last name. Required for TZS.

customerName?string

Recipient's full name. Required for UGX.

serviceCode?string

Mobile money operator to pay out through. Required for TZS.

Value in

"TZ-TIGO-B2C"
"TZ-AIRTEL-B2C"
"TZ-HALOTEL-B2C"

referenceId?string

Your own system's request ID. Stored against the transaction so you can query it using your identifier.

Response Body

`application/json`

Callbacks

curl -X POST "https://example.com/api/sandbox/v1/send-money" \  -H "Content-Type: application/json" \  -d '{    "phoneNumber": "254745362174",    "amount": 1000,    "currencyCode": "KSH",    "remarks": "Here are the remarks",    "occasion": "Here is the occasion",    "callbackUrl": "https://kiotapay.co.ke",    "referenceId": "123456"  }'

{  "status": 201,  "message": "Success",  "data": {    "requestId": "fb89a98f-20a9-4a7a-9bb2-bf7ca478f644",    "amount": 1000,    "phoneNumber": "254745362174",    "status": "PENDING"  }}

Send money to a mobile wallet

Conditionally required fields

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

Callbacks

payoutResultPOST{$request.body#/callbackUrl}

`application/json`

`application/json`

`application/json`