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

# Requests and responses

> Authentication, the response envelope, phone numbers and paging.

## Authentication

Send your key as a bearer token. `X-Api-Key: sk_…` also works.

```bash theme={null}
curl https://api.cloudpay.africa/cloudpay/v1/merchants/$MERCHANT_ID/balances \
  -H "Authorization: Bearer sk_test_..."
```

A key acts for one business, with exactly the scopes it was created with. Scopes are `read`, `collect`, `disburse`, `links`, `transfer`, `settle`, `rails`, `credentials` and `settings`. A key can never manage people or other keys, so a leaked key can't create more keys. A call outside the key's scopes returns `403 permission_denied`.

> [!WARNING]
>
> API keys are for servers only. Never put one in a browser, a mobile app or a git repository. If a key leaks, revoke it under **API keys**. It stops working immediately.

## Requests

* Bodies are JSON (`Content-Type: application/json`), up to 64 KB.
* **Unknown fields are rejected** with `400 invalid_body`. This catches typos such as `ammount` before any money moves.
* Times are RFC 3339, for example `2026-11-16T09:30:00+03:00`.

## The envelope

Every response has the same shape. Success puts the result in `data`:

```json theme={null}
{
  "status": { "ok": true, "code": 200, "desc": "OK" },
  "data": [{ "account": "main", "currency": "KES", "posted": 1250000, "available": 1200000 }]
}
```

A failure puts it in `errors`:

```json theme={null}
{
  "status": { "ok": false, "code": 403, "desc": "Forbidden" },
  "errors": { "code": "permission_denied", "message": "you are not allowed to do this for this merchant" }
}
```

Every response also carries an `X-Request-Id` header. Log it with failures: Cloudpay support can find any request by it.

`status.code` is always the same as the HTTP status. `errors.code` is stable, so write your logic against it. `errors.message` is written for people and may change. See the [error reference](https://docs.cloudpay.africa/errors/reference.md) for the full list of codes.

## Phone numbers

You can send a number in any of these forms: `0712345678`, `0112345678`, `+254712345678` or `254712345678`. Responses always return it as `254712345678`.

## Lists and paging

Lists are newest first. To page, pass the `created_at` of the last item you saw as `before`, and set `limit`:

```bash theme={null}
GET /v1/merchants/{id}/collections?status=completed&limit=50&before=2026-11-16T09:30:00Z
```

| Parameter | |
| - | - |
| `limit` | Default 50, maximum 200 |
| `before` | Return items created strictly before this time |
| `from` | Return items created at or after this time. Use it with `before` to request a window. |

An empty page is `[]`, never `null`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.