These rules apply to all endpoints. It is worth reading through them before you start — they prevent the most common integration mistakes.
Amounts in cents
All monetary values are integers, in cents. Never use decimal places.
| Actual value | Send |
|---|
| R$ 49.90 | 4990 |
| R$ 100.00 | 10000 |
| R$ 1.00 | 100 |
Sending a float (49.90) will result in a validation error. To display the amount, divide by 100 on your end.
currency field (ISO 4217 code, e.g. BRL). The default is BRL.
Dates
All dates are transmitted as ISO 8601 with timezone offset:
2026-06-24T15:30:45.000Z
2026-06-24T12:30:45.000-03:00
Do not send localized formats (24/06/2026) or date-only strings (2026-06-24) in date filters —
they are rejected. Always include the offset/timezone.
Identifiers
Each resource has an ID with a human-readable prefix: txn_, pay_, cust_, rec_, rfd_, spl_,
crd_, whk_, plan_, sub_, inv_, wlt_, wdr_. Treat them as opaque strings — do not rely on
their length.
Use referenceCode to tie a transaction to your internal identifier (e.g. an order number). It must be unique per account.
List endpoints accept page and limit as query string parameters:
| Parameter | Default | Maximum |
|---|
page | 1 | — |
limit | 20 | 100 |
curl "https://api.sandbox.z2pay.com/transactions?page=1&limit=50" \
-H "x-api-key: z2_psp_sk_..."
{
"data": [ /* ... items ... */ ],
"pagination": { "page": 1, "limit": 50, "total": 134, "totalPages": 3 }
}
Idempotency
Sensitive write operations (create transaction, refund, etc.) accept the
Idempotency-Key header — a unique value you generate per operation. If the same request is
retried with the same key (e.g. after a timeout), Z2Pay will not duplicate the operation and returns the
same result.
curl -X POST https://api.sandbox.z2pay.com/transactions \
-H "x-api-key: z2_psp_sk_..." \
-H "Idempotency-Key: pedido-9f8a-2026-06-24" \
-H "Content-Type: application/json" \
-d '{ ... }'
For transaction creation, the idempotency key is stored for 7 days. Use a stable and unique value per billing intent (e.g. the order ID in your system).
| Header | Required | Purpose |
|---|
x-api-key | Yes | Authentication. See Authentication. |
Content-Type: application/json | On POST/PUT | JSON request body. |
Idempotency-Key | Recommended | Prevents duplication on retries. |
