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

# withdrawal.*

> Solicitado, pago ou negado. Os três momentos em que o seu saldo muda de lado.

Cada mudança de estado de um saque dispara um evento na URL configurada na conta, em
[Dashboard → API e Desenvolvedores → Webhooks](https://purincash.com/dashboard/api).

| Evento                 | Quando                                        |
| ---------------------- | --------------------------------------------- |
| `withdrawal.requested` | O saque foi solicitado e entrou na fila       |
| `withdrawal.completed` | O saque foi pago                              |
| `withdrawal.denied`    | O saque foi negado e o valor voltou pro saldo |

Em sandbox os nomes mudam para `withdrawal.test.requested` e `withdrawal.test.completed`.

<CodeGroup>
  ```json Solicitado theme={null}
  {
    "event": "withdrawal.requested",
    "withdrawalId": "665f1a2b3c4d5e6f7a8b9c0d",
    "code": "SAQ-A1B2C3",
    "amount": 150.00,
    "method": "pix",
    "walletAddress": "chave-pix-ou-carteira",
    "status": "pendente",
    "requestedAt": "2026-03-18T14:00:00.000Z",
    "sandbox": false
  }
  ```

  ```json Pago theme={null}
  {
    "event": "withdrawal.completed",
    "withdrawalId": "665f1a2b3c4d5e6f7a8b9c0d",
    "code": "SAQ-A1B2C3",
    "amount": 150.00,
    "method": "pix",
    "walletAddress": "chave-pix-ou-carteira",
    "status": "concluido",
    "processedAt": "2026-03-18T15:30:00.000Z"
  }
  ```

  ```json Negado theme={null}
  {
    "event": "withdrawal.denied",
    "withdrawalId": "665f1a2b3c4d5e6f7a8b9c0d",
    "code": "SAQ-A1B2C3",
    "amount": 150.00,
    "method": "pix",
    "walletAddress": "chave-pix-ou-carteira",
    "status": "negado",
    "processedAt": "2026-03-18T15:30:00.000Z"
  }
  ```
</CodeGroup>

## Campos

<ResponseField name="event" type="string" required>
  `withdrawal.requested`, `withdrawal.completed` ou `withdrawal.denied`.
</ResponseField>

<ResponseField name="withdrawalId" type="string" required>
  Identificador do saque.
</ResponseField>

<ResponseField name="code" type="string" required>
  Código legível do saque, como `SAQ-A1B2C3`. É por ele que o suporte localiza a operação.
</ResponseField>

<ResponseField name="amount" type="number" required>
  Valor em reais, decimal.
</ResponseField>

<ResponseField name="method" type="string" required>
  `pix`, `pix_turbo`, `ltc` ou `usd`.
</ResponseField>

<ResponseField name="walletAddress" type="string" required>
  Destino do saque. Chave PIX, endereço LTC ou endereço USDT, conforme o método.
</ResponseField>

<ResponseField name="status" type="string" required>
  `pendente`, `concluido` ou `negado`.
</ResponseField>

<ResponseField name="requestedAt" type="string">
  Presente em `withdrawal.requested`.
</ResponseField>

<ResponseField name="processedAt" type="string">
  Presente em `withdrawal.completed` e `withdrawal.denied`.
</ResponseField>

<Note>
  Repare que o `status` aqui vem em português (`pendente`, `concluido`, `negado`), enquanto
  as cobranças usam inglês (`pending`, `paid`). São domínios diferentes da API e cada um
  manteve o vocabulário da sua área.
</Note>

## Um uso que compensa

Saque negado devolve o valor pro saldo, mas ninguém fica olhando o painel esperando isso.
Um alerta no `withdrawal.denied` costuma ser a diferença entre resolver no mesmo dia e
descobrir na semana seguinte:

```js theme={null}
if (evento.event === "withdrawal.denied") {
  await avisarFinanceiro({
    titulo: `Saque ${evento.code} negado`,
    valor: evento.amount,
    metodo: evento.method,
    em: evento.processedAt,
  });
}
```

<Warning>
  Este webhook não cobre todos os estados. O `processing` do [saque
  turbo](/guias/saques#saque-turbo), que significa "o dinheiro saiu e o banco ainda não
  confirmou", é visto por `GET /v1/payouts`. Não trate ausência de
  `withdrawal.completed` como saque não realizado.
</Warning>

As garantias são as mesmas dos outros: assinatura HMAC em `X-Webhook-Signature`,
idempotência em `X-Webhook-Id` e reentrega com backoff.