# Saques

Transfere o saldo disponível para uma chave Pix. O valor sai do seu saldo no momento em que o saque é criado, não quando é aprovado.

## Criar

`POST /withdrawals`

> ✅ Use um `Idempotency-Key`. KYC aprovado é obrigatório.

| Campo | Tipo |  | Descrição |
| --- | --- | --- | --- |
| `amount` | integer | obrigatório | Valor em centavos. |
| `pix_key_type` | string | obrigatório | "CPF", "CNPJ", "PHONE", "EMAIL" ou "EVP". |
| `pix_key` | string | obrigatório | A chave Pix de destino. |
| `holder_name` | string | opcional | Nome do titular da conta destino. |

_curl_

```bash
curl -X POST https://stacepay.com.br/api/v1/withdrawals \
  -H "Authorization: Bearer nvx_live_..." \
  -H "Idempotency-Key: saque-0912" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10000, "pix_key_type": "EMAIL", "pix_key": "financeiro@minhaloja.com"}'
```

_json_

```json
{
  "object": "withdrawal",
  "id": "wd_26421672b129ff167e64",
  "status": "pending",
  "amount": 10000,
  "fee_amount": 0,
  "total_debited": 10000,
  "currency": "BRL",
  "pix_key": "fi***@minhaloja.com",
  "pix_key_type": "email",
  "end_to_end_id": null,
  "processed_at": null,
  "created_at": "2026-08-11T21:28:07-03:00"
}
```

## Listar e buscar

`GET /withdrawals?limit=20&offset=0`

`GET /withdrawals/{id}`

## Status possíveis

| Status | Significado |
| --- | --- |
| `pending` | Aguardando aprovação. |
| `approved` | Aprovado, aguardando envio. |
| `processing` | Enviado ao parceiro, aguardando confirmação. |
| `paid` | Concluído o dinheiro chegou. |
| `rejected` | Recusado antes de enviar. |
| `failed` | Falhou no envio; o valor volta ao saldo. |
| `refunded` | Devolvido ao saldo depois de uma falha. |
| `canceled` | Cancelado. |