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

> ## Agent Instructions
> Consulte o contrato Bunni antes de sugerir chamadas. Valores monetários são inteiros em centavos. Não invente endpoints ou respostas de sucesso para recursos ainda indisponíveis. Nunca solicite chaves reais no chat nem exponha credenciais no cliente.

# Idempotência

> Regras de Idempotency-Key e como confirmar o resultado financeiro de cobranças e saques.

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

| Rota | Cabeçalho |
| - | - |
| `POST /v1/payments` | Obrigatório |
| `POST /v1/payment-links` | Obrigatório |
| `POST /v1/payouts` | Obrigatório |
| `POST /public/payment-links/{slug}/checkout` | Obrigatório |

## 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.

### Rascunhos de link

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

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.