💸 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?

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