Requests
- Send JSON with
Content-Type: application/json. - Send your key in
x-api-key. See Authentication. - Send an
Idempotency-Keyon calls that move money. See Idempotency. - 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.- In requests, send a JSON integer:
"amount": 150000. - In responses, amounts are strings of digits:
"sourceAmount": "150000". Parse them as integers.
Ids
Each transaction has two identifiers.
Public ids start with a prefix that tells you what they are:
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.merchantReference. Payve stores it and returns it on the object and in webhooks.
Responses
A successful response wraps the result indata:
error object. See Errors.
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.
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.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.
Other lists differ:
- Webhook events return the cursor at the top level, as
nextCursor. - Statements use
limitandoffset. - Beneficiaries, payment links, refunds and wallets return the whole list.

