Send Money API
This API allows a company to send money to a recipient using their phone number.Endpoint
POST /api/sandbox/v1/send-moneyBase URL
https://api.kiotapay.co
Request Headers
| Key | Value | Required | Description |
|---|---|---|---|
Content-Type | application/json | ✅ | Specifies that the request body is in JSON format. |
Authorization | Bearer <your-token> | ✅ | API authentication token. Replace <your-token> with a valid JWT. |
Request Body
{
"phoneNumber": "254745362174",
"amount": 1000,
"remarks": "Here are the remarks",
"occasion": "Here is the occasion",
"callbackUrl": "https://kiotapay.co.ke",
"currencyCode":"KSH", // TZS, KSH , UGX
"firstName":"James", // Optional
"lastName":"maina", // Optional
"serviceCode":"TZ-TIGO-B2C", // Optional
"narration":"MOBILE PAYOUT", // Optional
"customerName":"James", //Optional
"referenceId":"123456" // Optional
}
| Field | Type | Description |
|---|---|---|
| phoneNumber | String | The recipient’s phone number in international format. It must be a valid registered Kenyan or Tanzania phone number. |
| amount | Number | The amount of money to be sent in all provided currencies(Kenya shillings(KSH), Tanzania shillings(TZS)) . Example: 1000.For TZS ,The least spending amount should be 1000 (one thousand Tanzania Shillings) |
| remarks | String | A brief transaction description . Example: "Here are the remarks". This field is mandatory for Ksh transactions |
| occasion | String | A short text describing the purpose of the transaction. Example: "Here is the occasion"This field is mandatory for Ksh Transactions |
| callbackUrl | String | A publicly accessible POST API endpoint where transaction results will be sent. Example: "https://kiotapay.co.ke". This is mandatory for both Ksh and Tzs Transactions. |
| currencyCode | String | This is the field that marks whether the payout is a Kenyan shillingor a Tanzania shilling. Only two Currencies are allowed at the moment (TZS or KSH). It defaults to KSH currency code |
| narration | String | This is a field only mandatory for Tanzania and Ugandan Shilling Transaction. It is a short narration of the transaction. |
| customerName | String | This is a field only mandatory for Ugandan shillings Transaction. What you are passing as the first and last names could be here. |
| firstName | String | This is a field only mandatory for Tanzania Shilling Transaction. It marks the first name of the receiver |
| lastName | String | This is a field only mandatory for Tanzania Shilling Transaction. It marks the last name of the receiver |
| serviceCode | String | This is a field only mandatory for Tanzania Shilling Transaction. The only accepted service code are TZ-TIGO-B2C, TZ-AIRTEL-B2C,TZ-HALOTEL-B2C . |
| referenceId | String | This 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. |
{
"status": 201,
"message": "Success",
"data": {
"requestId": "fb89a98f-20a9-4a7a-9bb2-bf7ca478f644",
"amount": 1000.0,
"phoneNumber": "254745362174",
"status": "PENDING"
}
}
{
"requestId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"phoneNumber": "254728762287",
"status": "SUCCESS", // SUCCESS, FAILED, PENDING
"amount": 1500.75
}