> ## 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

> Saque em moeda local ou USDT

<Note>**Beta** — o contrato da 1.0 em evolução, ainda não em produção. Os campos podem mudar até o lançamento.</Note>

## Criar saque

`POST /v1/payouts`

```json theme={null}
{
  "amount": 50000,
  "currency": "MXN",
  "payment_method": "SPEI",
  "external_id": "retiro-99",
  "destination": { "type": "spei", "clabe": "646180000000000000", "name": "Juan Pérez", "document": "PEGJ850315HDFRRN01" },
  "kind": "PLAYER_PAYOUT"
}
```

* O saldo (na moeda do saque) é debitado **atomicamente** na criação (valor + taxa). Sem saldo → `422 INSUFFICIENT_FUNDS`.
* `currency` / `payment_method` — a moeda e o trilho. Sem `currency`, o default é `BRL` (PIX).
* `destination` — polimórfico por método (veja abaixo).
* `kind`: `PLAYER_PAYOUT` (saque de player) ou `SETTLEMENT` (saque do seu próprio saldo). Idempotência por `external_id`.

## Destino por método

O `destination` vem no formato do método:

```
PIX    { type: "pix",  pix_key, pix_key_type }      pix_key_type: cpf · cnpj · email · phone · random
SPEI   { type: "spei", clabe, name, document }
USDT   { type: "usdt", address, network }           network: TRON · ETH · …
```

## Dados do recebedor

| Campo      | Obrigatório | Observação                                          |
| ---------- | ----------- | --------------------------------------------------- |
| `name`     | sim         | nome completo, 3 a 64 caracteres                    |
| `document` | sim         | documento local do recebedor (CPF/CNPJ, RFC, CURP…) |
| `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. Você já envia essas informações no
  [depósito](/v1.0/deposits) — mande as mesmas aqui.
</Warning>

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 pagamento 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
```