⚠️ Webhook de Infração

📋 Visão Geral

Os webhooks de infração notificam sobre disputas, chargebacks e outras infrações relacionadas a transações. Essas notificações são críticas para manter a saúde financeira da sua operação e responder rapidamente a contestações.

📦 Estrutura do Payload

Exemplo Completo

{
  "type": "infraction",
  "objectId": "74e5b98d-3d2b-42e7-9335-7d89f9a46df2",
  "url": "https://webhook.example.com/infraction",
  "data": {
    "id": "74e5b98d-3d2b-42e7-9335-7d89f9a46df2",
    "status": "closed",
    "endToEndId": "E9876543210987654321098765432109",
    "externalRef": "external-infraction-001",
    "transactionId": "transaction-12345",
    "report": {
      "details": "Transação suspeita de fraude detectada no sistema."
    },
    "analysis": {
      "details": "Detalhes da análise apontam discrepâncias nos dados do pagamento.",
      "result": "agreed"
    },
    "createdAt": "2025-01-10T14:30:00Z",
    "updatedAt": "2025-01-10T15:00:00Z"
  }
}

Descrição dos Status de Infração

Status	Descrição	Próximos status possíveis
OPEN	🔴 Infração aberta, aguardando resposta	ACKNOWLEDGED, CANCELLED
ACKNOWLEDGED	🟡 Reconhecida, preparando defesa	DEFENDED, CANCELLED
DEFENDED	🟡 Defesa enviada, em análise	WAITING_PSP, CLOSED
WAITING_PSP	⏳ Aguardando decisão do provedor	WON, LOST, CLOSED
WON	🎉 Disputa ganha a nosso favor	-
LOST	❌ Disputa perdida	-
CLOSED	✅ Infração encerrada	-
CANCELLED	🚫 Infração cancelada	-

Resultados de Análise

Resultado	Descrição	Significado
AGREED	🟢 Análise favorável	Disputa aceita a nosso favor
DISAGREED	🔴 Análise desfavorável	Disputa rejeitada

🧪 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/infraction

Payload de Teste

Use este payload para testar seu endpoint localmente:

{
  "type": "infraction",
  "objectId": "test-infraction-001",
  "url": "https://webhook.example.com/infraction",
  "data": {
    "id": "test-infraction-001",
    "status": "open",
    "endToEndId": "E00000000000000000000000000000000",
    "externalRef": "TEST-INFRACTION-001",
    "transactionId": "test-transaction-001",
    "report": {
      "details": "Teste de infração para desenvolvimento."
    },
    "analysis": {
      "details": "Análise de teste.",
      "result": "pending"
    },
    "createdAt": "2025-01-10T14:30:00Z",
    "updatedAt": "2025-01-10T14:30:00Z"
  }
}

❓ FAQ

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 acontece se não responder no prazo?

A infração é automaticamente perdida e o valor é debitado da sua conta, além de possíveis penalidades.

Como reduzir infrações?

1. Prevenção: Use ferramentas antifraude
2. Comunicação: Seja claro sobre políticas
3. Atendimento: Resolva problemas rapidamente
4. Documentação: Mantenha registros completos

---

📚 Próximos passos: Webhook de Transação | Webhook de Cashout