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

# Criar Saque

> Envia um saque Pix por chave ou código Pix Copia e Cola (BR Code); o valor solicitado é o que o destinatário recebe.

Envia um saque Pix para uma chave Pix ou um código Pix Copia e Cola (BR Code).

**Método:** `POST /api/v1/wallet/withdrawals`

**Autenticação:** Obrigatória — inclua o header `Authorization: Bearer sk_live_sua_api_key`. Requer o escopo `withdrawal.create`.

<Warning>
  Este endpoint move dinheiro. Use sempre do seu backend, nunca do navegador ou de um aplicativo público.
</Warning>

## Parâmetros do corpo

<ParamField body="amount" type="number" required>
  Valor **em reais** que o destinatário vai receber. É obrigatório também com `brCode` de valor fixo: nesse caso, o servidor decodifica novamente o código e usa o valor nele definido. Para código estático sem valor, `amount` define o pagamento. A taxa é somada ao valor debitado da carteira. Consulte `GET /wallet/withdrawals/quote` para os limites da loja.
</ParamField>

<ParamField body="pixKey" type="string">
  Chave Pix de destino: CPF, CNPJ, e-mail, telefone com DDI `55` ou chave aleatória. Envie **pixKey ou brCode**, nunca ambos.
</ParamField>

<ParamField body="brCode" type="string">
  Código Pix Copia e Cola completo (BR Code/EMV). Use no lugar de `pixKey` para pagar uma cobrança Pix diretamente com o saldo da loja. Envie **brCode ou pixKey**, nunca ambos.
</ParamField>

<ParamField body="twoFactorCode" type="string">
  TOTP atual exigido para saque com sessão; uma API key ativa com escopo `withdrawal.create` dispensa este campo.
</ParamField>

<ParamField body="idempotencyKey" type="string">
  Alternativa no corpo ao header `Idempotency-Key`. O header tem prioridade.
</ParamField>

## Exemplo: saque por chave Pix

```bash theme={null}
curl -X POST 'https://api.bukiopay.com/api/v1/wallet/withdrawals' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: saque_pedido_12345' \
  --data '{
    "amount": 100,
    "pixKey": "usuario@exemplo.com"
  }'
```

## Saque por Pix Copia e Cola

Antes do saque, confira o código com `POST /api/v1/wallet/withdrawals/pix-code/preview` usando a mesma API key (escopo `withdrawal.create`). A prévia não reserva saldo nem transfere dinheiro.

```bash theme={null}
curl -X POST 'https://api.bukiopay.com/api/v1/wallet/withdrawals/pix-code/preview' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --data '{"brCode":"00020101021226...codigo-EMV-completo...6304ABCD"}'
```

A resposta traz `preview.type` (`static` ou `dynamic`), `preview.amount`, `preview.requiresAmount`, `preview.merchantName` e `preview.recipientReference`. Confira o valor e o destinatário com o usuário. Em código estático sem valor, `preview.amount` é `null` e `requiresAmount` é `true`.

Para solicitar o saque, envie o **BR Code completo** em `brCode` e **também** `amount`. Se o código já contém valor, use o valor exibido na prévia; a API consultará e usará o valor do código. Se o código estático não contém valor, `amount` define quanto o destinatário recebe. Não envie `pixKey` junto.

```bash theme={null}
curl -X POST 'https://api.bukiopay.com/api/v1/wallet/withdrawals' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: saque_codigo_pix_12345' \
  --data '{"amount":49.90,"brCode":"00020101021226...codigo-EMV-completo...6304ABCD"}'
```

Substitua o texto abreviado por um código Pix real e completo: a API valida o formato e o CRC. O saque por `brCode` está disponível quando o gateway de saída da loja é PurinCash ou processamento manual; em outra configuração, a API retorna `400`. Códigos inválidos, fora do limite, já pagos ou expirados são rejeitados. O valor mínimo recebido é R\$ 2,00; consulte o máximo e a taxa da loja em `GET /api/v1/wallet/withdrawals/quote`.

## Resposta

Status `201 Created`.

```json theme={null}
{
  "message": "Saque Pix enviado para processamento.",
  "withdrawal": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "amount": 100,
    "feeAmount": 1,
    "totalAmount": 101,
    "currency": "BRL",
    "externalReference": "SAQ-API-6BA7B810",
    "createdAt": "2026-08-06T12:05:00.000Z",
    "processedAt": null
  }
}
```

<ResponseField name="withdrawal.amount" type="number">
  O que o destinatário recebe.
</ResponseField>

<ResponseField name="withdrawal.totalAmount" type="number">
  O que foi debitado da sua carteira, já com a taxa.
</ResponseField>

<ResponseField name="withdrawal.status" type="string">
  `pending`, `processing`, `approved` ou `rejected`.
</ResponseField>

## Idempotência

Envie o header `Idempotency-Key` para poder repetir a requisição sem risco de enviar o dinheiro duas vezes. Use de 8 a 128 caracteres, com letras, números e `. _ : -`.

| Situação | Resposta |
| - | - |
| Primeira solicitação aceita | `201 Created` |
| Repetição da mesma chave | `200 OK` com `Idempotency-Replayed: true` |
| Mesma chave com dados diferentes | `409 Conflict` |
| Chave cujo registro não existe mais | `410 Gone` |

Se você não enviar a chave, a API gera uma e devolve no header `Idempotency-Key` da resposta.

## Confirmação pendente

Se a resposta for `502` com `code: "WithdrawalConfirmationPending"`, o saque **pode** ter sido enviado e fica em `processing`.

<Warning>
  Nunca repita o saque com uma chave nova nesse caso: você corre o risco de pagar duas vezes. Mantenha a mesma `Idempotency-Key` e acompanhe o status.
</Warning>

Em falha definitiva, o `code` é `WithdrawalProcessingFailed` e o valor volta ao seu saldo. Quando o serviço está indisponível, o `code` é `WithdrawalUnavailable`.

## Acompanhar

Assine o webhook `transfer.completed` para saber da conclusão, ou consulte `GET /api/v1/wallet/activity?view=withdrawals`.


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