Skip to main content

​
Send Money API

This API allows a company to send money to a recipient using their phone number.

​
Endpoint

POST /api/sandbox/v1/send-money

​
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

{
  "phoneNumber": "254745362174",
  "amount": 1000,
  "remarks": "Here are the remarks",
  "occasion": "Here is the occasion",
  "callbackUrl": "https://kiotapay.co.ke",
  "currencyCode":"KSH", // TZS, KSH
  "firstName":"James",  // Optional
  "lastName":"maina",  // Optional
  "serviceCode":"TZ-TIGO-B2C",  // Optional
  "narration":"MOBILE PAYOUT",  // Optional
  "referenceId":"123456" // Optional
}
Explanation
FieldTypeDescription
phoneNumberStringThe recipient’s phone number in international format. It must be a valid registered Kenyan or Tanzania phone number.
amountNumberThe 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)
remarksStringA brief transaction description . Example: "Here are the remarks". This field is mandatory for Ksh transactions
occasionStringA short text describing the purpose of the transaction. Example: "Here is the occasion"
This field is mandatory for Ksh Transactions
callbackUrlStringA 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.
currencyCodeStringThis 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
narrationStringThis is a field only mandatory for Tanzania Shilling Transaction. It is a short narration of the transaction.
firstNameStringThis is a field only mandatory for Tanzania Shilling Transaction. It marks the first name of the receiver
lastNameStringThis is a field only mandatory for Tanzania Shilling Transaction. It marks the last name of the receiver
serviceCodeStringThis is a field only mandatory for Tanzania Shilling Transaction. The only accepted service code are TZ-TIGO-B2C, TZ-AIRTEL-B2C,TZ-HALOTEL-B2C .
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": "Success",
    "data": {
        "requestId": "fb89a98f-20a9-4a7a-9bb2-bf7ca478f644",
        "amount": 1000.0,
        "phoneNumber": "254745362174",
        "status": "PENDING"
    }
}
Sample Callback Body 
{
  "requestId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "phoneNumber": "254728762287",
  "status": "SUCCESS", // SUCCESS, FAILED, PENDING
  "amount": 1500.75
}