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

# Requests and responses

> Amounts, ids, the response envelope and pagination.

## Requests

* Send JSON with `Content-Type: application/json`.
* Send your key in `x-api-key`. See [Authentication](/get-started/authentication.md).
* Send an `Idempotency-Key` on calls that move money. See [Idempotency](/essentials/idempotency.md).
* Send only documented fields. A body with an unknown field is rejected with `422`.

## Amounts

Every amount is a whole number in the currency's **minor units**.

| Currency | Minor unit | `150000` means |
| - | - | - |
| `NGN` | kobo | ₦1,500.00 |
| `GHS` | pesewa | GH₵1,500.00 |
| `KES` | cent | KSh1,500.00 |

* **In requests**, send a JSON integer: `"amount": 150000`.
* **In responses**, amounts are strings of digits: `"sourceAmount": "150000"`. Parse them as integers.

> [!WARNING]
>
> Never use floating-point numbers for money. `1500.50` is rejected with `422`, not rounded. Convert
> to minor units with integer maths before you call the API.

## Ids

Each transaction has two identifiers.

| Field | Example | Use it for |
| - | - | - |
| `id` | `1842` | The `{id}` in a URL, such as `GET /v1/payouts/1842`. |
| `publicId` | `pyt_9c2e41b7a05d3f68` | Showing to people, support requests, and reconciliation. |

Public ids start with a prefix that tells you what they are:

| Prefix | Object |
| - | - |
| `pyt_` | Payout |
| `pin_` | Pay-in |
| `cnv_` | Conversion |
| `qte_` | Quote |
| `ben_` | Beneficiary |
| `ref_` | Refund |
| `evt_` | Webhook event |

> [!NOTE]
>
> Payout, pay-in and conversion URLs take the numeric `id`, not the `publicId`. `GET
>     /v1/payouts/pyt_9c2e...` returns `400`. Quotes, beneficiaries and refunds use their prefixed id in
> the URL.

Your own reference goes in `merchantReference`. Payve stores it and returns it on the object and in webhooks.

## Responses

A successful response wraps the result in `data`:

```json
{
  "data": {
    "id": 1842,
    "publicId": "pyt_9c2e41b7a05d3f68",
    "status": "pending"
  }
}
```

A failed request returns an `error` object. See [Errors](/essentials/errors.md).

> [!NOTE]
>
> Responses can carry fields that these docs do not describe. Ignore any field you do not recognise,
> and do not build on an undocumented one. It can change without notice.

Timestamps are ISO 8601 in UTC, for example `2026-11-18T10:00:12.000Z`.

Every response carries `Cache-Control: no-store`. Do not cache API responses.

## Pagination

Lists of payouts, pay-ins, conversions and quotes use a cursor.

```bash
curl "$PAYVE_API_URL/v1/payouts?limit=25" \
  -H "x-api-key: $PAYVE_API_KEY"
```

```json
{
  "data": [{ "id": 1842, "publicId": "pyt_9c2e41b7a05d3f68", "status": "successful" }],
  "meta": { "cursor": "eyJpZCI6MTg0MiwidHMiOiIyMDI2LTExLTE4VDEwOjAwOjEyLjAwMFoifQ" }
}
```

Pass `meta.cursor` back as `cursor` to get the next page. When `meta.cursor` is `null`, you have the last page. Results are newest first. `limit` defaults to 25.

| Parameter | Applies to | Meaning |
| - | - | - |
| `limit` | All four | Items per page. Default 25. |
| `cursor` | All four | The cursor from the previous page. |
| `status` | Payouts, pay-ins, conversions | One of `pending`, `processing`, `successful`, `failed`. |
| `from` | Payouts, pay-ins, conversions | Created at or after this ISO 8601 time. |
| `to` | Payouts, pay-ins, conversions | Created at or before this ISO 8601 time. |
| `q` | Payouts, pay-ins, conversions | Search text, such as part of a public id. |

Other lists differ:

* **Webhook events** return the cursor at the top level, as `nextCursor`.
* **Statements** use `limit` and `offset`.
* **Beneficiaries, payment links, refunds and wallets** return the whole list.

> [!TIP]
>
> Treat the cursor as an opaque string. Do not decode it or build one yourself.
