Primeiros passos

Idempotência

Requisições de criação podem ser reenviadas com segurança usando uma chave de idempotência, essencial para lidar com timeouts e retries sem cobrar o cliente duas vezes.

Como funciona

Envie um header Idempotency-Key em toda chamada POST /v1/charges. A chave deve ter no mínimo 8 caracteres e ser única por operação lógica (ex.: o ID do pedido no seu sistema).

Se a chave nunca foi vista, criamos a cobrança normalmente.
Se a chave já foi usada, retornamos a cobrança original, sem gerar novo QR nem novo lançamento.

Header obrigatório

Chamar POST /v1/charges sem Idempotency-Key (ou com menos de 8 caracteres) retorna 400 IDEMPOTENCY_KEY_REQUIRED.

Boas práticas

Derive a chave de um identificador estável do seu domínio (ID do pedido), não de um valor aleatório por tentativa.
Reutilize a mesma chave em todos os retries da mesma operação.
A idempotência é escopada por chave de API: cada cliente tem seu próprio espaço de chaves.

Requisição idempotente

curl https://apiv2.onnixpay.com/v1/charges \
  -X POST \
  -H "x-api-key: sk_live_sua_chave_aqui" \
  -H "Idempotency-Key: pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 2599, "method": "pix" }'

# Reenviar com a MESMA Idempotency-Key retorna
# a MESMA cobrança — sem criar um novo QR.

AnteriorAmbientes Próximo O objeto Charge