Requests

  • Send JSON with Content-Type: application/json.
  • Send your key in x-api-key. See Authentication.
  • Send an Idempotency-Key on 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.
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. 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.
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:
A failed request returns an 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.
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.
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. 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.
Treat the cursor as an opaque string. Do not decode it or build one yourself.