# 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.

***

### <i class="fa-gear-code">:gear-code:</i> Payload — Disputa

```json
{
  "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": "cliente.exemplo@email.com",
  "cnpjSeller": "27865738000105",
  "idSeller": 16199,
  "metadata": [
    {
      "key": "",
      "value": ""
    }
  ]
}
```

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

###

### <i class="fa-gear-code">:gear-code:</i> Payload — Dispute Alert

```json
{
  "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": "andremaria1980@gmail.com",
  "cnpjSeller": "17830029000101",
  "idSeller":622
}
```

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

***

### <i class="fa-arrows-rotate-reverse">:arrows-rotate-reverse:</i> 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.

### <i class="fa-puzzle-piece">:puzzle-piece:</i> 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                  |

***

#### <i class="fa-light-emergency-on">:light-emergency-on:</i> 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.