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

# Saques

> Como o saldo sacável de um recebedor vira dinheiro na conta bancária dele — pré-requisitos, etapas e o que cada estado significa.

Um **saque** (`wdr_`) transfere o saldo sacável de um recebedor para a conta bancária dele. Você
solicita por recebedor e moeda; a Z2Pay agrega o saldo das carteiras daquela moeda e debita o
valor na hora da solicitação.

O saque não é imediato nem automático: ele nasce solicitado e **passa por aprovação** antes de
seguir para o banco. Entre a solicitação e o dinheiro na conta há estados intermediários, e é por
eles que você acompanha — não pelo retorno da chamada.

<Info>
  Todas as requisições usam o header `x-api-key`. Veja [Autenticação](/pt-BR/autenticacao).
  A base URL de sandbox é `https://api.sandbox.z2pay.com/v1`.
</Info>

***

## Endpoints

| Método | Rota                       | Descrição                                 |
| ------ | -------------------------- | ----------------------------------------- |
| `GET`  | `/withdrawals/config`      | Taxa e valor mínimo de saque da sua conta |
| `GET`  | `/withdrawals`             | Lista paginada dos saques                 |
| `GET`  | `/withdrawals/{id}`        | Busca um saque por ID                     |
| `POST` | `/withdrawals`             | Solicita um saque                         |
| `POST` | `/withdrawals/{id}/cancel` | Cancela um saque ainda não aprovado       |

***

## Status do saque

Quem determina o status é a nossa análise e, depois dela, o banco. Você só provoca dois: a
solicitação e o cancelamento.

| Status       | O que significa                 | Quando acontece                                                                                     |
| ------------ | ------------------------------- | --------------------------------------------------------------------------------------------------- |
| `requested`  | Solicitado, à espera de análise | Você chamou `POST /withdrawals`; o valor já saiu do saldo sacável                                   |
| `approved`   | Aprovado, aguardando envio      | A análise liberou o saque                                                                           |
| `processing` | A caminho do banco              | A transferência foi enviada à instituição financeira                                                |
| `paid`       | Dinheiro na conta               | O banco confirmou o crédito                                                                         |
| `cancelled`  | Cancelado por você              | Você chamou o cancelamento enquanto o saque ainda estava `requested`; o valor volta para a carteira |
| `rejected`   | Recusado na análise             | A análise não aprovou; o valor volta para a carteira                                                |
| `failed`     | Falhou no envio                 | O banco recusou a transferência — quase sempre dado bancário incorreto                              |

<Note>
  **Só três estados geram webhook**: `withdrawal.requested`, `withdrawal.paid` e
  `withdrawal.rejected`. Os demais você observa consultando o saque. Veja
  [Webhooks](/pt-BR/webhooks/eventos).
</Note>

***

## Antes de solicitar

<Warning>
  **Sem conta bancária no recebedor, a solicitação não falha — o saque nasce sem destino.** A
  criação não confere a conta: responde `201` com `bankAccountId: null`, o valor sai do saldo e o
  saque tende a ser recusado na análise (com devolução). Cadastre a conta **antes**.
</Warning>

A conta bancária faz parte do cadastro do recebedor: você a envia em `bankAccount` ao
[criar](/pt-BR/recipients/create) ou [atualizar](/pt-BR/recipients/update) o recebedor, e ela
aparece como `defaultBankAccount` na resposta. O destino do saque é resolvido a partir dela no
momento da solicitação — não é um campo do corpo.

Além da conta, o recebedor precisa estar **apto a receber** (vínculo `active`) e ter saldo
sacável na moeda. Quanto sai de taxa e qual o valor mínimo estão em
[Configuração de saque](/pt-BR/withdrawals/config); quanto há para sacar, em
[Carteiras](/pt-BR/wallets).

***

## Veja também

<CardGroup cols={2}>
  <Card title="Carteiras" icon="wallet" href="/pt-BR/wallets">
    De onde sai o dinheiro e por que o sacável difere do disponível.
  </Card>

  <Card title="Recebedores" icon="users" href="/pt-BR/recipients">
    Cadastro do recebedor e da conta bancária de destino.
  </Card>

  <Card title="Liquidação" icon="calendar-clock" href="/pt-BR/valores/liquidacao">
    Quando o saldo de uma venda fica disponível.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pt-BR/webhooks/eventos">
    Os eventos `withdrawal.*` e o que cada um carrega.
  </Card>
</CardGroup>