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

# Saques Pix

> Cote, solicite e acompanhe saques Pix com controle de reserva e deducao de tarifa.

Saques Pix permitem transferir saldo de uma carteira para uma chave Pix de destino. A API oferece cotacao previa, criacao com idempotencia e consulta sincronizada com a provedora, tudo sem necessidade de webhook.

> [!NOTE]
>
> Requer escopo `payouts:create` para criar e `payouts:read` para consultar e cotar.

## Requisitos

Antes de solicitar um saque, confirme que:

* A conta esta ativa, habilitada e com KYC aprovado.
* O servidor esta com `PAYOUTS_ENABLED=true`.
* A carteira possui saldo disponivel.
* A provedora esta configurada.
* Ao usar sessao, e necessaria confirmacao adicional recente.

## Cotação

Antes de criar, use `GET /v1/payouts/quote` para conferir o valor debitado, a tarifa e o valor que o destinatario recebera.

**amountCents** `integer` *required*

Valor em centavos de BRL. Minimo 1000 (R\$ 10,00).

**deductFee** `string`

`true` para descontar a tarifa do valor informado; `false` para cobrar a tarifa a parte. Padrao: `false`.

```bash curl theme={"theme":"github-dark-default"}
curl "https://api.bunnipay.com.br/v1/payouts/quote?amountCents=1000&deductFee=false" \
  -H "X-API-Key: SUA_CHAVE"
```

### Exemplo: deductFee = false

Solicita-se `amountCents=1000`. A tarifa de 45 centavos e cobrada a parte.

| Campo | Valor |
| - | - |
| amountCents | 1000 |
| feeCents | 45 |
| debitAmountCents | 1045 |
| recipientAmountCents | 1000 |

### Exemplo: deductFee = true

Solicita-se `amountCents=1045`. A tarifa de 45 centavos e descontada do valor.

| Campo | Valor |
| - | - |
| amountCents | 1045 |
| feeCents | 45 |
| debitAmountCents | 1045 |
| recipientAmountCents | 1000 |

> [!WARNING]
>
> Com `deductFee=true`, o destinatario deve receber pelo menos 1000 centavos. Por exemplo, `amountCents=1000` com desconto e invalido porque entregaria apenas 955 centavos.

## Solicitar saque

Envie `POST /v1/payouts` com `Idempotency-Key` obrigatorio.

**amountCents** `integer` *required*

Valor em centavos (minimo 1000).

**walletId** `string` *required*

UUID da carteira.

**destination** `object` *required*

Chave Pix do destinatario.

**destination.keyType** `string` *required*

Tipo da chave: `cpf`, `cnpj`, `email`, `phone` ou `random`.

**destination.key** `string` *required*

Valor da chave Pix.

**beneficiaryName** `string` *required*

Nome do beneficiario.

**deductFee** `boolean`

Descontar tarifa do valor. Padrao: `false`.

```bash curl theme={"theme":"github-dark-default"}
curl -X POST https://api.bunnipay.com.br/v1/payouts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Idempotency-Key: saque-456-unico" \
  -d '{
    "amountCents": 1000,
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "destination": {
      "keyType": "cpf",
      "key": "12345678900"
    },
    "beneficiaryName": "Maria Silva",
    "deductFee": false
  }'
```

## Status de um saque

| Status | Significado |
| - | - |
| `processing` | Em processamento na provedora. |
| `completed` | Concluido; o dinheiro foi entregue. |
| `failed` | Falha definitiva; a reserva sera liberada. |
| `unknown` | Resultado incerto; a reserva permanece ate confirmacao. |

## Reserva de saldo

A reserva ocorre **antes** da chamada externa a provedora:

* `completed` consome a reserva definitivamente.
* `failed` libera a reserva.
* `unknown` mantem a reserva ate confirmacao.

> [!WARNING]
>
> Somente `completed` confirma a entrega do dinheiro. `processing` e `unknown` nao garantem conclusao.

## Consultar saque

Use `GET /v1/payouts/{id}` para sincronizar a situacao com a provedora, mesmo sem webhook.

```bash curl theme={"theme":"github-dark-default"}
curl https://api.bunnipay.com.br/v1/payouts/550e8400-e29b-41d4-a716-446655440002 \
  -H "X-API-Key: SUA_CHAVE"
```

## Tarifa

A tarifa fixa de saque e de **45 centavos** por operacao. Consulte a cotacao para ver o impacto exato antes de solicitar.

## Idempotencia

Sempre envie `Idempotency-Key` ao criar. Em caso de falha de comunicacao, repita com a **mesma chave, mesmo corpo e mesma credencial**. Nao crie outra chave para resolver um resultado incerto.


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