Estas regras valem para todos os endpoints. Vale a pena ler antes de começar — elas evitam os
erros mais comuns de integração.
Valores em centavos
Todos os valores monetários são inteiros, em centavos. Nunca use casas decimais.
| Valor real | Envie |
|---|
| R$ 49,90 | 4990 |
| R$ 100,00 | 10000 |
| R$ 1,00 | 100 |
Enviar float (49.90) resulta em erro de validação. Para exibir, divida por 100 no seu lado.
currency (código ISO 4217, ex.: BRL). O padrão é BRL.
Datas
Toda data trafega em ISO 8601 com timezone (offset):
2026-06-24T15:30:45.000Z
2026-06-24T12:30:45.000-03:00
Não envie formatos localizados (24/06/2026) nem data sem hora (2026-06-24) em filtros de data —
são rejeitados. Sempre inclua o offset/timezone.
Identificadores
Cada recurso tem um ID com prefixo legível: txn_, pay_, cust_, rec_, rfd_, spl_,
crd_, whk_, plan_, sub_, inv_, wlt_, wdr_. Trate-os como strings opacas — não dependa do
tamanho.
Use o referenceCode para amarrar uma transação ao seu identificador interno (ex.: número do
pedido). Ele é único por conta.
Paginação
Endpoints de listagem aceitam page e limit por query string:
| Parâmetro | Padrão | 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 }
}
Idempotência
Operações de escrita sensíveis (criar transação, estornar, etc.) aceitam o header
Idempotency-Key — um valor único que você gera por operação. Se a mesma requisição for
reenviada com a mesma chave (ex.: timeout + retry), o Z2Pay não duplica a operação e retorna o
mesmo 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 criação de transação, a chave de idempotência é guardada por 7 dias. Use um valor estável
e único por intenção de cobrança (ex.: o ID do pedido no seu sistema).
Cabeçalhos comuns
| Header | Obrigatório | Para quê |
|---|
x-api-key | Sim | Autenticação. Veja Autenticação. |
Content-Type: application/json | Em POST/PUT | Corpo em JSON. |
Idempotency-Key | Recomendado | Evita duplicação em retries. |
