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

# Solicitar Saque

> Solicita um saque do saldo disponível para uma chave PIX

## Descrição

Solicita um saque do saldo disponível para a chave PIX informada. O valor sai do saldo disponível na hora e fica em processamento até a conclusão. O resultado chega pelos webhooks `withdrawal.completed` ou `withdrawal.failed`, e também pode ser consultado em `GET /v1/payouts/`.

> [!NOTE]
>
> O campo `amount` é o valor que sai do saldo, em **centavos**. A taxa do saque (`platformFee`) é descontada desse valor.

**Rate Limit:** 60 requisições/minuto

***

## Headers

**Authorization** `string` *required* (default: Bearer YOUR\_API\_KEY)

Bearer token de autenticação. Formato: `Bearer YOUR_API_KEY`

**Content-Type** `string` *required*

Deve ser `application/json`

***

## Body

**amount** `integer` *required*

Valor do saque em centavos. Precisa respeitar o mínimo de saque da conta e ser maior que a taxa.

**pixKey** `string` *required*

Chave PIX de destino.

**pixType** `string` *required*

Tipo da chave: `cpf`, `cnpj`, `phone`, `email` ou `random`.

**description** `string`

Descrição do saque, até 140 caracteres. Se não for enviada, vale `Saque solicitado`.

***

## Saque

### Requisição

```bash cURL theme={null}
curl -X POST https://api.visepag.com/v1/payouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "pixKey": "52998224725",
    "pixType": "cpf",
    "description": "Saque semanal"
  }'
```

```javascript Node.js theme={null}
const response = await fetch('https://api.visepag.com/v1/payouts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000,
    pixKey: '52998224725',
    pixType: 'cpf',
    description: 'Saque semanal'
  })
});

const payout = await response.json();
```

### Resposta 201 Created

**id** `string`

UUID do saque, gerado pela VisePag.

**status** `string`

Status do saque: `pending`, `processing`, `completed` ou `failed`. Veja [Status](https://docs.visepag.com/concepts/status.md).

**amount** `integer`

Valor que saiu do saldo, em centavos.

**platformFee** `integer`

Taxa do saque, em centavos.

**pixType** `string`

Tipo da chave de destino.

**pixMasked** `string`

Chave de destino mascarada. A chave completa não é devolvida.

```json 201 theme={null}
{
  "id": "aa53d5f9-a2fb-4c29-b36a-f1a2ef03fd30",
  "status": "processing",
  "amount": 5000,
  "platformFee": 400,
  "description": "Saque semanal",
  "pixType": "cpf",
  "pixMasked": "********725",
  "failureReason": null,
  "createdAt": "2026-09-12T23:59:59Z",
  "completedAt": null,
  "failedAt": null,
  "currency": "brl"
}
```

***

## Erros

| Status | Código | Descrição |
| - | - | - |
| 400 | `invalid_amount` | `amount` deve ser um inteiro positivo em centavos |
| 400 | `invalid_pix_key` | Chave PIX ausente ou inválida para o tipo |
| 400 | `invalid_pix_key_type` | Tipo de chave inválido |
| 400 | `invalid_description` | `description` com mais de 140 caracteres |
| 401 | `missing_authorization` | Header `Authorization` ausente |
| 401 | `invalid_api_key` | Chave de API inválida |
| 403 | `account_not_fully_verified` | Conta sem verificação completa (KYC) |
| 422 | `amount_below_minimum` | Valor abaixo do mínimo de saque |
| 422 | `amount_below_fee` | Valor precisa ser maior que a taxa |
| 422 | `insufficient_balance` | Saldo disponível insuficiente |
| 429 | `rate_limit_exceeded` | Limite de 60 requisições/minuto excedido |
| 503 | `payout_rules_not_configured` | Saque indisponível no momento |


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