Estas reglas aplican a todos los endpoints. Vale la pena leerlas antes de empezar — evitan los
errores más comunes de integración.
Valores en centavos
Todos los valores monetarios son enteros, en centavos. Nunca use decimales.
| Valor real | Envíe |
|---|
| R$ 49,90 | 4990 |
| R$ 100,00 | 10000 |
| R$ 1,00 | 100 |
Enviar un float (49.90) resulta en error de validación. Para mostrar el valor, divídalo por 100 en su sistema.
currency (código ISO 4217, ej.: BRL). El valor predeterminado es BRL.
Fechas
Todas las fechas se transmiten en ISO 8601 con timezone (offset):
2026-06-24T15:30:45.000Z
2026-06-24T12:30:45.000-03:00
No envíe formatos localizados (24/06/2026) ni fecha sin hora (2026-06-24) en filtros de fecha —
serán rechazados. Incluya siempre el offset/timezone.
Identificadores
Cada recurso tiene un ID con prefijo legible: txn_, pay_, cust_, rec_, rfd_, spl_,
crd_, whk_, plan_, sub_, inv_, wlt_, wdr_. Trátelos como strings opacas — no dependa del
tamaño.
Use el referenceCode para vincular una transacción a su identificador interno (ej.: número de
pedido). Es único por cuenta.
Paginación
Los endpoints de listado aceptan page y limit por query string:
| Parámetro | Predeterminado | Máximo |
|---|
page | 1 | — |
limit | 20 | 100 |
curl "https://api.sandbox.z2pay.com/transactions?page=1&limit=50" \
-H "x-api-key: z2_psp_sk_..."
{
"data": [ /* ... itens ... */ ],
"pagination": { "page": 1, "limit": 50, "total": 134, "totalPages": 3 }
}
Idempotencia
Las operaciones de escritura sensibles (crear transacción, reembolsar, etc.) aceptan el header
Idempotency-Key — un valor único que usted genera por operación. Si la misma solicitud se
reenvía con la misma clave (ej.: timeout + retry), Z2Pay no duplica la operación y devuelve el
mismo resultado.
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 '{ ... }'
Para la creación de transacciones, la clave de idempotencia se guarda por 7 días. Use un valor estable
y único por intención de cobro (ej.: el ID del pedido en su sistema).
Cabeceras comunes
| Header | Obligatorio | Para qué |
|---|
x-api-key | Sí | Autenticación. Ver Autenticación. |
Content-Type: application/json | En POST/PUT | Cuerpo en JSON. |
Idempotency-Key | Recomendado | Evita duplicación en reintentos. |
