Skip to main content
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.
Enviar float (49.90) resulta em erro de validação. Para exibir, divida por 100 no seu lado.
A moeda é informada no campo currency (código ISO 4217). Hoje o único valor aceito é BRL, que também é o padrão quando você omite o campo — enviar qualquer outro código resulta em erro de validação.

​
Datas

Toda data trafega em ISO 8601 com timezone (offset):
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.

​
Escopo da conta

Sua chave de API só enxerga os recursos da sua conta. As listagens já vêm filtradas — não existe parâmetro para “ver de outra conta”, e buscar pelo ID de um recurso que não é seu responde 404, o mesmo que um ID inexistente. Você não precisa passar nenhum identificador de conta em lugar nenhum: ele vem da chave.

​
Identificadores

Cada recurso tem um ID com prefixo legível, que diz de que tipo ele é: txn_ebgsvfsb4151nmbgvj4sek6ol é uma transação, pay_ um pagamento, cust_ um cliente. A página de cada recurso mostra o prefixo dele. O prefixo serve para você reconhecer o que está lendo em log ou payload — não para parsing. Trate o ID como string opaca: não dependa do tamanho, do conjunto de caracteres, nem monte um ID a partir do prefixo. Guarde-o inteiro, do jeito que veio. Use o referenceCode para amarrar uma transação ao seu identificador interno (ex.: número do pedido). Recomendamos usar um valor único por pedido, mas a Z2Pay não valida unicidade do referenceCode — para evitar transações duplicadas em retries, use o header Idempotency-Key (veja Idempotência). Na listagem, o filtro ?referenceCode= faz match exato — envie o código completo, como foi cadastrado.

​
Paginação

Endpoints de listagem aceitam page e limit por query string:
A resposta segue o formato:

​
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), a Z2Pay não duplica a operação e retorna o mesmo resultado.
Como funciona em detalhe:
  • TTL da chave: 7 dias no POST /transactions; 24 horas nos demais endpoints idempotentes. Use um valor estável e único por intenção de operação (ex.: o ID do pedido no seu sistema).
  • Mesma chave + corpo diferente → 422 (Idempotency key already used with a different request body).
  • Requisições concorrentes com a mesma chave → a API aguarda a primeira terminar por até 5 segundos; se não terminar, responde 409.
  • Replays (respostas repetidas da mesma chave) vêm com o header Idempotency-Replayed: true.
  • Apenas respostas 2xx são memorizadas. Se a requisição original falhar (4xx/5xx), a chave é liberada e pode ser reutilizada no retry.
Nos erros de idempotência acima (422/409), error vem como texto, não como objeto: { "error": "Idempotency key already used with a different request body" }. Não há error.code nem error.message — trate pelo status HTTP. Veja Erros.
Em algumas rotas o 409 tem duas causas — e o corpo muda conforme a causa. Quando a operação já tem um conflito próprio de negócio, o mesmo status serve aos dois casos:Como distinguir: o conflito de negócio traz { "error": { "code": "...", "message": "..." } }; o de idempotência traz { "error": "texto" }, sem code. Se você trata 409 lendo error.code, o caso de idempotência devolve undefined — teste a presença do campo antes.

​
Cabeçalhos comuns