Eventos de Saques
Lista completa de eventos de webhook relacionados a saques, com descrições e exemplos de payload.
Eventos disponíveis
| Evento | Descrição |
|---|---|
withdrawal.requested | Saque solicitado (aguardando aprovação ou auto-aprovado) |
withdrawal.approved | Saque aprovado por um administrador |
withdrawal.rejected | Saque rejeitado por um administrador |
withdrawal.processing | Saque em processamento pela adquirente |
withdrawal.completed | Saque concluído com sucesso |
withdrawal.failed | Saque falhou no processamento |
Quando cada evento dispara
withdrawal.requested
Disparado quando um saque é solicitado via API ou pelo painel. Se o merchant possui aprovação automática habilitada, o saque é processado imediatamente; caso contrário, aguarda aprovação manual.
withdrawal.approved
Disparado quando um administrador aprova um saque pendente. O saque é então enviado para processamento pela adquirente.
withdrawal.rejected
Disparado quando um administrador rejeita um saque pendente. O valor reservado é devolvido à carteira do merchant/submerchant.
withdrawal.processing
Disparado quando a adquirente confirma que o saque está em processamento. Este evento é originado por notificações da adquirente (webhook da adquirente).
withdrawal.completed
Disparado quando a adquirente confirma que o saque foi concluído e o valor foi transferido ao destinatário.
withdrawal.failed
Disparado quando o saque falha no processamento pela adquirente. O valor reservado é devolvido automaticamente à carteira do merchant/submerchant.
Payload de exemplo
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"event": "withdrawal.completed",
"withdrawal": {
"id": "w1d2r3a4-w5a6-7890-wdrl-000000000001",
"merchant_id": "m1e2r3c4-h5a6-7890-ntid-000000000001",
"submerchant_id": null,
"wallet_id": "w1a2l3l4-e5t6-7890-wllt-000000000001",
"status": "completed",
"amount": 50000,
"fee": 500,
"net_amount": 49500,
"recipient_snapshot": {
"type": "pix",
"details": {
"pix_key": "joao@exemplo.com",
"pix_key_type": "email"
}
},
"failure_reason": null,
"external_id": "ext-wdr-123",
"metadata": null,
"processed_at": "2026-03-30T14:00:00.000Z",
"completed_at": "2026-03-30T14:05:00.000Z",
"failed_at": null,
"created_at": "2026-03-30T13:55:00.000Z",
"updated_at": "2026-03-30T14:05:00.000Z"
},
"occurred_at": "2026-03-30T14:05:00.000Z"
}Campos do objeto withdrawal
| Campo | Tipo | Descrição |
|---|---|---|
id | string | ID único do saque |
merchant_id | string | ID do merchant proprietário |
submerchant_id | string | null | ID do submerchant (se aplicável) |
wallet_id | string | ID da carteira de origem |
status | string | Status atual (pending, processing, completed, failed, canceled) |
amount | number | Valor bruto do saque em centavos |
fee | number | Taxa total cobrada em centavos |
net_amount | number | Valor líquido em centavos (amount - fee) |
recipient_snapshot | object | null | Dados do destinatário no momento da solicitação |
failure_reason | string | null | Motivo da falha ou rejeição |
external_id | string | null | ID externo na adquirente |
metadata | object | null | Metadados (inclui dados de aprovação/rejeição) |
processed_at | string | null | Data/hora do envio para processamento (ISO 8601) |
completed_at | string | null | Data/hora da conclusão (ISO 8601) |
failed_at | string | null | Data/hora da falha (ISO 8601) |
created_at | string | Data/hora da criação (ISO 8601) |
updated_at | string | Data/hora da última atualização (ISO 8601) |
Tipos de destinatário (recipient_snapshot)
PIX
{
"type": "pix",
"details": {
"pix_key": "joao@exemplo.com",
"pix_key_type": "email"
}
}TED
{
"type": "ted",
"details": {
"bank_code": "001",
"branch_number": "1234",
"branch_check_digit": "0",
"account_number": "12345",
"account_check_digit": "6",
"account_type": "checking",
"holder_name": "Joao Silva",
"holder_tax_id": "12345678900"
}
}Criptomoeda
{
"type": "crypto",
"details": {
"crypto_currency": "USDT",
"crypto_network": "tron",
"crypto_wallet": "TXyz..."
}
}