> For the complete documentation index, see [llms.txt](https://docs.barte.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.barte.com/guias/webhooks/disputas-e-chargebacks.md).

# Disputas e Chargebacks

{% hint style="danger" %}
**Formato v1 em descontinuação.**\
A partir de **10/08/2026**, o formato v1 será descontinuado. Todos os sellers deverão estar integrados ao [Webhook v2](https://docs.barte.com/guias/webhooks/webhooks-overview/webhook-v2-visao-geral.md). Sellers que ainda não possuem integração ativa devem integrar diretamente pelo novo modelo.
{% endhint %}

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.barte.com/guias/webhooks/disputas-e-chargebacks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
