> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Convenções

> Regras que valem para toda a API: valores em centavos, datas ISO 8601, paginação e idempotência.

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`   |

<Warning>
  Enviar float (`49.90`) resulta em erro de validação. Para exibir, divida por 100 no seu lado.
</Warning>

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)**:

```
2026-06-24T15:30:45.000Z
2026-06-24T12:30:45.000-03:00
```

<Warning>
  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.
</Warning>

## 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](#idempot%C3%AAncia)). 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:

| Parâmetro | Padrão | Máximo |
| --------- | ------ | ------ |
| `page`    | `1`    | —      |
| `limit`   | `20`   | `100`  |

```bash theme={null}
curl "https://api.sandbox.z2pay.com/v1/transactions?page=1&limit=50" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```

A resposta segue o formato:

```json theme={null}
{
  "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), a Z2Pay **não duplica** a operação e retorna o
mesmo resultado.

```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/transactions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: pedido-9f8a-2026-06-24" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

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.

<Note>
  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](/pt-BR/erros).
</Note>

<Warning>
  **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:

  | Rota                                                                         | `409` de negócio                                               |
  | ---------------------------------------------------------------------------- | -------------------------------------------------------------- |
  | [`POST /transactions/{id}/refund`](/pt-BR/transactions/refund)               | nenhum pagamento estornável                                    |
  | `POST /transactions/{transactionId}/payments/{paymentId}/refund`             | pagamento não estornável, ou valor acima do limite             |
  | [`POST /refunds/{id}/approve`](/pt-BR/refunds) · [`/refuse`](/pt-BR/refunds) | estorno não está em status que permita                         |
  | [`POST /withdrawals`](/pt-BR/withdrawals)                                    | saldo insuficiente, valor abaixo do mínimo, sem carteira ativa |
  | `POST /withdrawals/{id}/cancel`                                              | saque não cancelável no status atual                           |

  **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.
</Warning>

## Cabeçalhos comuns

| Header                           | Obrigatório | Para quê                                                |
| -------------------------------- | ----------- | ------------------------------------------------------- |
| `x-api-key`                      | Sim         | Autenticação. Veja [Autenticação](/pt-BR/autenticacao). |
| `Content-Type: application/json` | Em POST/PUT | Corpo em JSON.                                          |
| `Idempotency-Key`                | Recomendado | Evita duplicação em retries.                            |