Pular para o conteúdo principal

💸 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

StatusDescriçãoPróximos status possíveis
PENDING⏳ Aguardando processamentoPROCESSING, REJECTED
PROCESSING🔄 Sendo processadoCOMPLETED, FAILED, REJECTED
COMPLETED✅ Concluído com sucessoREFUNDED
PAID💰 Pagamento confirmadoREFUNDED
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:

TipoFormatoExemplo
CPF11 dígitos12345678900
CNPJ14 dígitos12345678000190
EMAILE-mail válidojoao@example.com
PHONE+55 + número+5511999999999
RANDOMUUID123e4567-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?

  1. Verifique a URL: Certifique-se de que está correta e acessível
  2. Valide HTTPS: Webhooks só são enviados para URLs HTTPS

O que fazer se o cashout falhar?

  1. Verifique o campo error no webhook
  2. Corrija o problema (saldo, dados bancários, etc.)
  3. 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