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

# Saques

> PIX out · saque de player e settlement

## Criar saque

`POST /v1/payouts`

```json theme={null}
{
  "amount_cents": 3000,
  "external_id": "saque-99",
  "pix_key": "player@pix.io",
  "pix_key_type": "email",
  "recipient": {
    "name": "Player Um",
    "document": "11144477735",
    "email": "player1@email.com",
    "phone": "+5511988887777"
  },
  "kind": "PLAYER_PAYOUT"
}
```

* O saldo é debitado **atomicamente** na criação (valor + taxa). Sem saldo → `422 INSUFFICIENT_FUNDS`.
* `kind`: `PLAYER_PAYOUT` (saque de player) ou `SETTLEMENT` (saque do seu próprio saldo).
* Idempotência por `external_id`.

## Dados do recebedor

| Campo      | Obrigatório | Observação                       |
| ---------- | ----------- | -------------------------------- |
| `name`     | sim         | nome completo, 3 a 64 caracteres |
| `document` | sim         | CPF ou CNPJ do recebedor         |
| `email`    | não         | e-mail do recebedor              |
| `phone`    | não         | telefone do recebedor, com DDI   |

<Warning>
  **Envie `email` e `phone` sempre que tiver.** Os adquirentes exigem identificação real de quem recebe:
  transação sem esses dados entra no radar de risco deles, e conta com dado genérico repetido é motivo de
  bloqueio. Você já envia essas informações no [depósito](/reference/deposits) — mande as mesmas aqui.
</Warning>

São **opcionais**: quem não enviar continua funcionando exatamente como hoje. E `email` malformado é
simplesmente ignorado — nunca vamos recusar o saque do seu cliente por causa de um campo cadastral.

Se a sua conta estiver com **auto-aprovação** ligada (padrão), o saque vai direto ao provedor e
fica `PROCESSING` até liquidar. Senão, fica `PENDING` aguardando aprovação do operador.

## Estados

`PENDING → PROCESSING → PAID` · ou `→ FAILED`/`REJECTED` (o valor é **estornado** ao saldo).

<Warning>
  Um `504 PROVIDER_TIMEOUT` na criação **não** estorna automaticamente — o PIX pode ter saído. O
  saque fica `PROCESSING` e é resolvido pelo webhook do provedor. Nunca refaça um saque por timeout
  sem antes consultar o status.
</Warning>

## Consultar

```
GET /v1/payouts/{id}
GET /v1/payouts?status=PROCESSING
```