Disputas e Chargebacks

Os eventos de disputa e chargeback notificam que um comprador contestou ou solicitou estorno de uma cobrança.

• Disputas (DISPUTE): indicam que um cliente abriu contestação em uma transação.

• Alerta de disputa (DISPUTE_ALERT): notifica que uma disputa foi iniciada, mas ainda não há resolução final.

• Chargebacks: seguem o mesmo payload de ORDER, pois o status CHARGEBACK é enviado via webhook de Orders.

🔹 Todos os eventos trazem dados do comprador e do seller, permitindo rastrear e reagir rapidamente.

---

Payload — Disputa

{
  "uuid": "c5a7f2b1-3a91-4a93-8e11-8b4e7f7a61d2",
  "dateTime": "2025-10-10T14:32:18.00",
  "status": "DISPUTE",
  "domain": "ORDER",
  "uuidBuyer": "a9fbc3e8-21e4-4f12-8f6b-74a9b37e8b6a",
  "documentBuyer": "12345678909",
  "address": {
    "country": "BR",
    "state": "SP",
    "city": "São Paulo",
    "district": "Pinheiros",
    "street": "Rua dos Pinheiros",
    "zipCode": "05422-001",
    "number": "850",
    "complement": "Sala 12"
  },
  "emailBuyer": "[email protected]",
  "cnpjSeller": "27865738000105",
  "idSeller": 16199,
  "metadata": [
    {
      "key": "",
      "value": ""
    }
  ]
}

🔹 O domain ainda é ORDER, pois disputas e chargebacks estão ligados à transação original.

Payload — Dispute Alert

{
  "uuid": "12dfdf90-8742-479d-b36b-8016faa877a9",
  "dateTime": "2025-10-22T02:29:17.437Z",
  "status": "DISPUTE_ALERT",
  "domain": "ORDER",
  "uuidBuyer": "a8d3a8a3-db99-4558-a0e4-a0dae69be4b4",
  "documentBuyer": "25307027800",
  "country": "BR",
  "state": "SP",
  "city": "Cotia",
  "district": "Parque Dom Henrique",
  "street": "Avenida Benedito Isaac Pires",
  "zipCode": "06716-300",
  "number": "2100",
  "complement": "Casa 03",
  "emailBuyer": "[email protected]",
  "cnpjSeller": "17830029000101",
  "idSeller":622
}

🔹 Alertas de disputa podem ser usados para monitorar e acionar fluxos internos antes da disputa ser oficialmente registrada.

---

Fluxo de Disputa → Chargeback

1. A transação é criada com status PAID.

2. O comprador abre uma disputa → status muda para DISPUTE.

3. Após ~1 semana, se não houver resolução, o sistema altera para CHARGEBACK.

4. Se a disputa for ganha, o status retorna para PAID.

5. Caso seja perdida, permanece CHARGEBACK.

Esse fluxo segue o comportamento padrão das bandeiras e instituições financeiras.

Campos importantes

Campo	Descrição
uuid	Identificador da transação/ordem contestada
dateTime	Data e hora do evento
status	DISPUTE ou DISPUTE_ALERT
domain	Sempre ORDER
uuidBuyer	Identificador do comprador
documentBuyer	CPF ou CNPJ do comprador
address	Endereço completo do comprador
emailBuyer	E-mail do comprador
cnpjSeller	CNPJ do seller responsável
idSeller	ID do seller
metadata	Dados adicionais opcionais

---

Observações importantes

• Nem toda disputa se transforma em chargeback, mas a maioria das disputas evolui automaticamente para CHARGEBACK após uma semana.

• Se a disputa for ganha, o status é revertido para PAID.

• O webhook de DISPUTE é enviado assim que o status é atualizado pela adquirente.