Make a Paybill Payment

Paybill Payment API

This API allows a company to create a new spending transaction using Paybill (business) information.

---

Endpoint

POST /api/sandbox/v1/paybill

---

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

The body must contain the following fields:

{
  "businessNumber": "2232334",
  "accountNumber": "22442244",
  "amount": 1000,
  "remarks": "Here are the remarks",
  "occasion": "Here is the occasion",
  "callbackUrl": "https://kiotapay.co.ke",
"referenceId":"1234"
}

Explanation

Field	Type	Description
businessNumber	String	The Paybill number associated with the receiver.
accountNumber	String	The account number associated with the receipient’s paybill
amount	Number	The amount to be transacted in the Kenyan Shillings currency.
remarks	String	Additional information about the transaction.
occasion	String	A description or purpose for the transaction.
callbackUrl	String	A valid POST URL where payment confirmation will be sent.
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": "8fa1fab3-a1d6-41fd-9199-d5517efc0d41",
        "accountNumber": "22442244",
        "businessNumber": "2232334",
        "amount": 1000.0,
        "status": "PENDING"
    }
}

Sample Callback Body

{
  "accountNumber": "1234567890",
  "businessNumber": "9876543210",
  "requestId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "amount": 1500.75,
  "status": "SUCCESS" // SUCCESS, FAILED, PENDING
}