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

# Saques PIX

> Saques por chave PIX, limites e acompanhamento.

Envie pagamentos via PIX para qualquer chave PIX de destino.

> No **ambiente de teste** o saque segue o mesmo fluxo da produção (resposta com status `ANALYSIS` e webhooks `pix_out.analysis` e `pix_out.paid`), mas não passa por banco nenhum: o pagamento é simulado, o saldo de teste é debitado e nenhum dinheiro é movimentado.

## Como funciona

1. **Solicite o saque** — Informe o valor, a chave PIX de destino e os dados do beneficiário. O saldo é reservado automaticamente e a resposta retorna com status `ANALYSIS`
2. **Acompanhe pelo webhook** — Cadastre um endpoint assinando os eventos `pix_out.*` (`pix_out.paid`, `pix_out.rejected`, `pix_out.error`, `pix_out.refunded`) para receber atualizações automáticas sobre o processamento
3. **Consulte quando precisar** — Verifique o status do saque a qualquer momento

## Status do Saque

| Status | Descrição |
| - | - |
| `ANALYSIS` | Saque solicitado, aguardando processamento |
| `PROCESSING` | Em processamento pelo sistema bancário |
| `PAID` | Saque confirmado e enviado ao destinatário |
| `REJECTED` | Saque rejeitado (saldo devolvido) |
| `ERROR` | Erro no processamento (saldo devolvido) |
| `REFUNDED` | Saque devolvido por completo pelo recebedor após ter sido enviado |

## Devolução pelo recebedor

O recebedor pode devolver um saque pago em uma ou mais devoluções parciais. A devolução também acontece quando o banco do recebedor devolve um pagamento já concluído (por exemplo, conta encerrada ou bloqueada); nesse caso costuma vir uma única devolução do valor total. Cada devolução concluída no banco é creditada no seu saldo disponível pelo valor que voltou (a taxa do saque não é devolvida) e gera um evento `pix_out.refunded`: com status `PARTIALLY_REFUNDED` e `partial: true` enquanto a soma das devoluções não chega ao valor do saque, e com status `REFUNDED` e `partial: false` na devolução que completa o valor. O saque continua `PAID` até completar o valor; ao completar, passa a `REFUNDED`. Veja **Devoluções no webhook** na seção Webhooks.

## Webhook de Saques

Quando o status de um saque é atualizado, você recebe uma notificação nos endpoints que assinam os eventos `pix_out.*`.

**Exemplo de payload:**

```json theme={null}
{
  "event": "PIX_OUT_UPDATE",
  "method": "PIX_OUT",
  "status": "PAID",
  "transactionId": "uuid-da-transacao",
  "idempotency": "sua-chave-idempotencia",
  "value": 100.00,
  "valueFee": 2.50,
  "valueLiquid": 102.50,
  "destination": {
    "pixKey": "chave-pix-destino",
    "pixType": "DOCUMENT"
  },
  "customer": {
    "fullName": "Nome Completo",
    "document": "12345678900"
  },
  "endToEndId": "E12345678202301011200abcdefghijkl",
  "messageError": null
}
```

> A URL do endpoint deve retornar HTTP 200 para confirmar o recebimento. Em caso de falha, o sistema reenvia com backoff exponencial. Veja [Configurar webhooks](https://docs.alphagateway.com.br/webhooks/configurar.md) para detalhes de eventos e validação da assinatura HMAC.


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