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

# Saques PIX (Outbound Withdrawals)

> Transferência e liquidação automatizada de saldo para chaves PIX externas.

## Solicitar Saque

`POST /v1/withdrawals`  •  escopo `withdrawals:write`

### Parâmetros do Saque

| Campo          | Tipo   | Obrigatório | Descrição / Tipos Aceitos                                                                                                |
| -------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| `amount`       | string | **Sim**     | Valor do saque em Reais como **string decimal com duas casas** (ex: `"100.00"`). Veja [Formato de Valores](/parametros). |
| `pix_key`      | string | **Sim**     | Chave PIX de destino (criptografada em AES-256 no banco).                                                                |
| `pix_key_type` | string | **Sim**     | Tipo da chave: `CPF`, `CNPJ`, `EMAIL`, `TELEFONE`, `EVP`.                                                                |
| `description`  | string | Opcional    | Identificador ou motivo do saque.                                                                                        |

```bash theme={null}
curl -X POST https://api.kavropay.online/v1/withdrawals \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wit_req_88192" \
  -d '{
    "amount": "100.00",
    "pix_key": "12345678909",
    "pix_key_type": "CPF",
    "description": "Retirada de comissão de vendas"
  }'
```

<Check>
  **Resposta (HTTP 201 Created)**

  ```json theme={null}
  {
    "id": "WIT7A28F1B3E4C9D01",
    "amount": 100.00,
    "fee": 2.50,
    "net": 97.50,
    "status": "processing",
    "pix_key": "***.456.789-**",
    "pix_key_type": "CPF",
    "created_at": "2026-08-26T12:10:00.000Z"
  }
  ```
</Check>

<Warning>
  **Erro: Saldo Insuficiente (HTTP 402 Payment Required)**

  ```json theme={null}
  {
    "statusCode": 402,
    "message": "Saldo disponível insuficiente para realizar esta transferência.",
    "error": "Request Error",
    "timestamp": "2026-08-26T12:10:00.000Z",
    "path": "/v1/withdrawals"
  }
  ```

  Veja o formato completo do corpo de erro em [Central de Erros & Status](/erros-status).
</Warning>

## Consultar Saque

`GET /v1/withdrawals/{id}`  •  escopo `withdrawals:read`

Busca os dados detalhados de um saque específico. O parâmetro `{id}` é o ID retornado na criação (`WIT...`).

```bash theme={null}
curl https://api.kavropay.online/v1/withdrawals/WIT7A28F1B3E4C9D01 \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

**Resposta (HTTP 200 OK)**

```json theme={null}
{
  "id": "WIT7A28F1B3E4C9D01",
  "amount": 100.00,
  "fee": 2.50,
  "net": 97.50,
  "status": "completed",
  "pix_key": "***.456.789-**",
  "pix_key_type": "CPF",
  "description": "Retirada de comissão de vendas",
  "created_at": "2026-08-26T12:10:00.000Z",
  "completed_at": "2026-08-26T12:10:45.000Z"
}
```

## Listar Saques (Paginado)

`GET /v1/withdrawals`  •  escopo `withdrawals:read`

**Query Params:** `status` (pending/processing/completed/failed), `limit` (1 a 100), `offset` (0, 20...)

```bash theme={null}
curl "https://api.kavropay.online/v1/withdrawals?status=completed&limit=50&offset=0" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

<CardGroup cols={2}>
  <Card title="Anterior: Gestão de Clientes" icon="arrow-left" horizontal href="/gestao-clientes" />

  <Card title="Próximo: Consulta de Saldo" icon="arrow-right" horizontal href="/saldo-conta" />
</CardGroup>