> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kiotapay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](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:

```json theme={null}
{
  "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**

```json theme={null}
{
    "status": 201,
    "message": "Success",
    "data": {
        "requestId": "8fa1fab3-a1d6-41fd-9199-d5517efc0d41",
        "accountNumber": "22442244",
        "businessNumber": "2232334",
        "amount": 1000.0,
        "status": "PENDING"
    }
}
```

**Sample Callback Body**

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