💸 Webhook de Cashout
📋 Visão Geral
Os webhooks de cashout notificam sua aplicação sobre mudanças no status de saques/transferências. Isso permite automatizar processos de conciliação e manter seus registros atualizados em tempo real.
📦 Estrutura do Payload
Exemplo Completo
{
"type": "cashout",
"objectId": "a3f8c0d3-ef7b-42f1-9b90-4a31d72b9bfa",
"url": "https://webhook.example.com/cashout",
"data": {
"id": "a3f8c0d3-ef7b-42f1-9b90-4a31d72b9bfa",
"amount": 100000,
"pixKey": "john.doe@example.com",
"pixType": "EMAIL",
"beneficiary": {
"name": "John Doe",
"document": "12345678901"
},
"creditor": {
"name": "FastSoft",
"document": "98765432100"
},
"endToEndId": "E1234567890123456789012345678901",
"receiptUrl": "https://example.com/receipt/a3f8c0d3-ef7b-42f1-9b90-4a31d72b9bfa",
"description": "Transferência para pagamento de serviços",
"sellerId": "seller-54321",
"postbackUrl": "https://webhook.example.com/cashout",
"externalRef": "external-cashout-54321",
"error": null,
"status": "paid",
"updatedAt": "2025-01-10T15:45:00Z"
}
}
Descrição dos Status de Cashout
Status | Descrição | Próximos status possíveis |
---|---|---|
PENDING | ⏳ Aguardando processamento | PROCESSING , REJECTED |
PROCESSING | 🔄 Sendo processado | COMPLETED , FAILED , REJECTED |
COMPLETED | ✅ Concluído com sucesso | REFUNDED |
PAID | 💰 Pagamento confirmado | REFUNDED |
FAILED | ❌ Falha no processamento | - |
REJECTED | 🚫 Rejeitado por validação | - |
REFUNDED | ↩️ Valor devolvido | - |
Tipos de Chave PIX
Os cashouts suportam todos os tipos de chave PIX:
Tipo | Formato | Exemplo |
---|---|---|
CPF | 11 dígitos | 12345678900 |
CNPJ | 14 dígitos | 12345678000190 |
EMAIL | E-mail válido | joao@example.com |
PHONE | +55 + número | +5511999999999 |
RANDOM | UUID | 123e4567-e89b-12d3... |
🧪 Testando Webhooks
Ferramenta de Debug
Recomendamos usar ngrok para testar webhooks localmente:
# Expor seu servidor local
ngrok http 3000
# Use a URL gerada
# https://abc123.ngrok.io/webhook/cashout
Payload de Teste
Use este payload para testar seu endpoint localmente:
{
"type": "cashout",
"objectId": "test-cashout-001",
"url": "https://webhook.example.com/cashout",
"data": {
"id": "test-cashout-001",
"status": "paid",
"amount": 10000,
"pixKey": "test@example.com",
"pixType": "EMAIL",
"description": "Teste de cashout",
"externalRef": "TEST-001",
"beneficiary": {
"name": "Teste Silva",
"document": "00000000000"
},
"creditor": {
"name": "FastSoft",
"document": "00000000000"
},
"updatedAt": "2025-01-10T15:45:00Z",
"error": null
}
}
❓ FAQ
Quanto tempo leva para receber o webhook?
- Evento
created
: Imediato (< 1 segundo) - Evento
processing
: 1-5 segundos - Evento
completed
: 5-30 segundos (depende do banco) - Evento
failed
: Imediato após a falha
O que fazer se não receber um webhook?
- Verifique a URL: Certifique-se de que está correta e acessível
- Valide HTTPS: Webhooks só são enviados para URLs HTTPS
O que fazer se o cashout falhar?
- Verifique o campo
error
no webhook - Corrija o problema (saldo, dados bancários, etc.)
- Crie um novo cashout com os dados corrigidos
Como reprocessar um cashout?
Cashouts falhados não podem ser reprocessados. É necessário criar uma nova solicitação com os dados corretos.
Posso cancelar um cashout?
Cashouts podem ser cancelados apenas enquanto estão no status PENDING
. Uma vez em PROCESSING
, não podem ser cancelados.
📚 Próximos passos: Webhook de Transação | Webhook de Infração