Send Money B2C Send Money

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

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
  "firstName":"James",  // Optional
  "lastName":"maina",  // Optional
  "serviceCode":"TZ-TIGO-B2C",  // Optional
  "narration":"MOBILE PAYOUT",  // Optional
  "referenceId":"123456" // Optional
}

Explanation

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 Shilling Transaction. It is a short narration of the transaction.
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.

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
}