> ## 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 till payment

# Till New API

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

## Endpoint

POST /api/sandbox/v1/till

### 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

```json theme={null}
{
    "businessNumber":"12345",
    "amount":100,
    "remarks":"Here are the remarks",
    "occasion":"Here is the occasion",
    "callbackUrl":"https://kiotapay.co.ke",
"referenceId":"1234"
}
```

**Explanation**

| Field          | Type   | Description                                                                                                                                                           |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| businessNumber | String | The shortcode to which money will be moved                                                                                                                            |
| accountNumber  | String | The account number to be associated with the payment. Up to 13 characters.                                                                                            |
| amount         | Number | The transaction amount in Kenyan Currency.                                                                                                                            |
| remarks        | String | Any additional information to be associated with the transaction. It should be upto 100 characters.                                                                   |
| occasion       | String | Any additional information to be associated with the transaction. It should be upto 100 characters.                                                                   |
| callbackUrl    | String | A valid **POST**  url where the callback 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 Bidy**

```json theme={null}
{
    "status": 201,
    "message": "Success",
    "data": {
        "requestId": "89720296-239a-4391-9ecd-c4ca4d2eded0",
        "accountNumber": "435567676",
        "businessNumber": "12345",
        "amount": 100.0,
        "status": "PENDING"
    }
}
```

**Sample Callback Body**

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