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

# Referência

> Movimente seu saldo via PIX para uma chave de sua escolha.

Withdrawals (saques) são **transferências PIX** do saldo do seu merchant
para uma chave PIX de destino.

## Como funciona

<Steps>
  <Step title="Você solicita o saque">
    `POST /withdrawals` com `amount`, `pixKey` e `pixKeyType`.
  </Step>

  <Step title="Validamos o saldo">
    Conferimos que `available >= amount + fee`.
  </Step>

  <Step title="Reservamos o valor">
    Movemos `amount + fee` de `available` para `pending`.
  </Step>

  <Step title="Enfileiramos o processamento">
    O saque entra com status `PENDING` e nosso worker o envia ao PSP.
  </Step>

  <Step title="PIX é enviado">
    Status vai para `PROCESSING` e depois `COMPLETED` (ou `FAILED`).
  </Step>

  <Step title="Webhook é disparado">
    Você recebe `WITHDRAWAL_COMPLETED` ou `WITHDRAWAL_FAILED` no seu endpoint.
  </Step>
</Steps>

## Ciclo de vida

| Status       | Significado                                     |
| ------------ | ----------------------------------------------- |
| `PENDING`    | Solicitado, aguardando processamento            |
| `PROCESSING` | Enviado ao PSP, aguardando confirmação          |
| `COMPLETED`  | PIX enviado com sucesso                         |
| `FAILED`     | Falhou — ver `failedReason`; saldo é restaurado |

## Taxa e valor líquido

A taxa do saque é **somada** ao valor solicitado e debitada do saldo:

```
Total debitado = amount + fee
PIX enviado    = amount
```

Por exemplo, para um saque de R$ 100,00 com taxa de R$ 0,50:

* Você recebe na chave PIX: **R\$ 100,00**
* É debitado do seu saldo: **R\$ 100,50** (10050 centavos)

## Tipos de chave PIX aceitos

| `pixKeyType`      | Formato esperado                    |
| ----------------- | ----------------------------------- |
| `CPF`             | 11 dígitos (`12345678900`)          |
| `CNPJ`            | 14 dígitos (`12345678000190`)       |
| `EMAIL`           | E-mail (`pagamentos@minhaloja.com`) |
| `TELEFONE`        | `+5511999999999`                    |
| `CHAVE_ALEATORIA` | UUID aleatório (EVP)                |

## Restrições

<Card title="Quando o saque é bloqueado" horizontal>
  * Saques **desabilitados** para o merchant (`withdrawalsEnabled = false`)
  * Já existe um saque **em andamento** (`PENDING` ou `PROCESSING`) — só um por vez
  * **Saldo insuficiente** (`available < amount + fee`)
  * Valor **acima do limite** configurado para o merchant
  * Valor **fora da faixa** de 50 a 100.000.000 centavos (R$ 0,50 a R$ 1.000.000,00)
</Card>

## Operações disponíveis

| Operação                                     | Endpoint                |
| -------------------------------------------- | ----------------------- |
| [Solicitar saque](/pages/withdrawals/create) | `POST /withdrawals`     |
| [Listar saques](/pages/withdrawals/list)     | `GET /withdrawals`      |
| [Obter saque](/pages/withdrawals/get)        | `GET /withdrawals/{id}` |