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

# Saques

> Tire o saldo da conta para a chave Pix que você envia, com idempotência e acompanhamento.

O saque (`SAQ-API-`) manda o saldo disponível por Pix para a **chave Pix que você envia no pedido** (`destination`) ou para o recebedor de um **Pix Copia e Cola** (`copyPaste`). Não precisa cadastrar a chave antes: as chaves favoritas do painel são só um atalho de quem saca pela tela. Como a chave de API pode mandar dinheiro para qualquer chave, ela só funciona com o 2FA ligado na conta e dos IPs que você liberou.

> [!WARNING]
>
> Exige o escopo `withdrawals:write`, o 2FA ligado na conta e pelo menos um IP liberado na chave de API. Chamada de outro IP responde `403 IP_NOT_ALLOWED`.

> [!NOTE]
>
> **Para pagar alguém ou um Pix Copia e Cola, use o saque.** A rota antiga `POST /v1/pix/payments` (Pix enviado, `ENV-`) vai ser removida: ela ainda funciona para quem já usa e responde com os cabeçalhos `Deprecation: true` e `Link: </v1/withdrawals>`. Troque pela `POST /v1/withdrawals`, que faz o mesmo (chave ou Copia e Cola, mesma tarifa) e avisa pelos webhooks `withdrawal.*`.

## Pedir um saque

[`POST /v1/withdrawals`](https://docs.wyzecash.com.br/referencia/saques/pedir-saque) · escopo `withdrawals:write` · `Idempotency-Key` obrigatória

**amount** `integer` *required*

Valor em centavos que vai chegar na chave. A tarifa é descontada **além** desse valor (`total` na resposta).

**destination** `object`

`{ "keyType": "cpf" | "cnpj" | "email" | "phone" | "random", "key": "..." }`: a chave que vai receber.

**copyPaste** `string`

No lugar de `destination`: um Pix Copia e Cola (o saque vai para a chave do código; se ele tem valor, `amount` precisa ser igual).

**description** `string`

Até 140 caracteres, para o seu extrato.

```bash theme={null}
curl -X POST https://api.wyzecash.com.br/v1/withdrawals \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: saque-2026-10-08-001" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50000, "destination": { "keyType": "cpf", "key": "123.456.789-09" }, "description": "Fechamento do dia" }'
```

### Resposta

```json theme={null}
{
  "id": "SAQ-API-3F7K9Q2W8M4Z",
  "status": "processing",
  "amount": 50000,
  "fee": 50,
  "total": 50050,
  "channel": "api",
  "destination": { "name": "Ana S.", "institution": "Banco Exemplo", "keyType": "cpf", "key": "***.456.789-**" },
  "endToEndId": null,
  "failureReason": null,
  "createdAt": "2026-10-08T15:10:00.000Z",
  "completedAt": null
}
```

| `status` | O que significa |
| - | - |
| `processing` | em andamento. Valor e tarifa já saíram do saldo e ficam reservados até o fim; você recebe `withdrawal.completed` ou `withdrawal.failed` |
| `completed` | caiu na chave; `endToEndId` e `completedAt` preenchidos |
| `failed` · `rejected` | não realizado (`failureReason` diz o motivo); valor e tarifa voltam ao saldo |

A resposta da criação não é a conclusão: espere o webhook `withdrawal.completed` ou consulte o saque.

## Regras

* Valor mínimo por saque: o da sua conta (padrão R\$ 1,00; `GET /v1/balance` mostra em `withdrawal.minPerTransaction`): `BELOW_MINIMUM`.
* Precisa ter `amount + fee` disponível: `INSUFFICIENT_FUNDS`.
* O que é das suas [subcontas](https://docs.wyzecash.com.br/endpoints/subcontas.md) não sai no seu saque (só no saque da própria subconta): `SUBACCOUNT_FUNDS`. `GET /v1/balance` mostra `subaccounts` e `free`.
* Sem chave no pedido, ou com mais de uma forma: `DESTINATION_REQUIRED`. `pixKeyId` (favorita) não vale na API.
* Chave de conta WyzeCash não é destino de saque: `INTERNAL_ACCOUNT`.
* Com a verificação de cadastro obrigatória e a sua conta ainda sem aprovação: `403 KYC_REQUIRED` (cobranças continuam).
* Em manutenção: `503 MAINTENANCE` (receber continua).

## Consultar e listar

| Método | Rota | Escopo | O que faz |
| - | - | - | - |
| GET | [`/v1/withdrawals/{id}`](https://docs.wyzecash.com.br/referencia/saques/consultar-saque) | `transactions:read` | um saque (`SAQ-` ou `SAQ-API-`) |
| GET | [`/v1/withdrawals?limit=&cursor=`](https://docs.wyzecash.com.br/referencia/saques/listar-saques) | `transactions:read` | saques, do mais novo para o mais antigo |

## Saque automático

Se preferir não programar, o painel tem regras de saque automático (ao atingir um valor ou todo dia num horário, com % do disponível), até 5 por conta, cada uma para a chave digitada nela. Os saques gerados chegam pelos mesmos webhooks `withdrawal.*`, com `channel: "auto"`.


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