Skip to main content
A Bunni Pay exige o cabeçalho Idempotency-Key ao criar cobranças Pix, rascunhos de links, saques e checkouts. Esse mecanismo evita duplicacao de intencoes quando uma requisicao é repetida por falha de rede ou timeout.

Regras do Idempotency-Key

  • O valor deve ter entre 8 e 128 caracteres.
  • A chave identifica uma intenção: preserve a mesma chave, o mesmo corpo e a mesma credencial em uma repeticao.
  • Nao crie outra chave para tentar resolver um resultado incerto.
  • Conflitos de idempotência retornam HTTP 409.
  • Nao ha fallback automatico de provedora.

Onde usar

Comportamento por rota

Cobranças Pix

POST /v1/payments registra a intencao antes de chamar a provedora.
  • Mesma chave e mesmo corpo: retorna a intencao persistida e, quando disponível, a resposta original de emissao.
  • Mesma chave e corpo diferente: 409 IDEMPOTENCY_CONFLICT.
  • Intencao ainda em processamento: 409 PAYMENT_IN_PROGRESS; aguarde e mantenha os mesmos dados.
POST /v1/payment-links persiste a chave junto com o rascunho.
  • Mesma chave e mesmo corpo: retorna o rascunho ja criado.
  • Mesma chave e corpo diferente: 409 IDEMPOTENCY_CONFLICT.

Saques Pix

POST /v1/payouts exige Idempotency-Key para evitar duplicacao de solicitacoes de saque.

Confirmação financeira

HTTP 200 na criacao confirma que a intencao foi persistida, mas nao confirma entrega de dinheiro.
Um pagamento so esta confirmado no estado paid. Um saque so esta confirmado no estado completed. Estados como pending, processing e unknown nao confirmam entrega de dinheiro.
As consultas individuais de pagamento, Pix, checkout e saque sincronizam a situacao com a provedora. Listagens e indicadores leem o estado persistido. Nao é necessário configurar webhook para consultar a situacao.

Falhas de comunicacao

Timeout ou erro 5xx nao comprovam o resultado financeiro. Quando ja tiver o identificador do recurso, consulte-o diretamente em vez de gerar uma nova intencao automaticamente.