# Listar chargebacks

**Área:** Chargebacks

Lista os chargebacks das cobranças de cartão da conta, do atualizado por último para o mais antigo. Um chargeback nasce quando o portador contesta a compra no banco emissor; a cobrança afetada passa a `DISPUTE` e o caso aparece aqui com o `caseId` usado nas demais rotas da seção.

`GET /v1/disputes`

**Base URL Produção:** `https://api.validapay.com.br`  
**Base URL Sandbox:** `https://sandbox.validapay.com.br`

**Scopes necessários:** `charges/read`

O item traz `charge`, o resumo da cobrança contestada (comprador, valor, produto), para você cruzar com o pedido sem uma segunda consulta. Quando a cobrança não é localizada, o campo não vem.

**Status do chargeback**

- `DISPUTE` — o portador contestou a compra no banco emissor. O caso está aberto e aceita defesa.
- `REFUND_PENDING` — a devolução do valor ao portador está em processamento.
- `DISPUTE_CLOSED` — a disputa terminou. O desfecho está em `charge.status`: `PAID` quando a defesa foi aceita e o valor fica com você, `CHARGED_BACK` quando não foi.
- `CHARGED_BACK` — o valor foi devolvido ao portador e debitado da sua conta.

`closedAt` é preenchido quando o caso chega a `DISPUTE_CLOSED` ou `CHARGED_BACK`.

**Defesa**

- `evidenceStatus`: `DRAFT` até o envio da defesa, `SUBMITTED` depois de `POST /v1/disputes/{caseId}/evidence`. `evidenceAttachmentCount` diz quantos arquivos já foram anexados.
- `submissionStatus`: andamento da defesa depois do envio — `PENDING`, `IN_REVIEW`, `SENT`, `REJECTED` ou `RESOLVED`. `null` antes do envio.

Valores em reais. A paginação usa `lastKey`: repita a chamada com o valor de `pagination.lastKey` enquanto `hasMore` for `true`.

Case de uso:
_Como lojista, quero listar os chargebacks abertos, para separar os pedidos que precisam de defesa._

### Query parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `type` | **sim** | sempre CHARGEBACK nesta seção |
| `limit` | não | itens por página, default 15 |
| `lastKey` | não | cursor devolvido em pagination.lastKey |
| `status` | não | DISPUTE, REFUND_PENDING, DISPUTE_CLOSED ou CHARGED_BACK |
| `dateFrom` | não | abertos a partir deste instante, em ISO 8601 (2026-10-01T00:00:00.000Z) |
| `dateTo` | não | abertos até este instante, em ISO 8601 com hora (2026-10-31T23:59:59.999Z). Só a data deixa de fora os casos abertos nesse dia |
| `chargeId` | não | só os chargebacks desta cobrança |
| `search` | não | busca por caseId, chargeId ou transactionId |

### Resposta 200: Sucesso

```json
{
    "items": [
        {
            "caseId": "cbk_1790512345678_k3m9q2xwz",
            "type": "CHARGEBACK",
            "status": "DISPUTE",
            "accountId": "460851686",
            "chargeId": "cha_1790012345678_a8f2k1pqz",
            "transactionId": "a1b2c3d4-0000-0000-0000-000000000000",
            "amount": 297.0,
            "originalAmount": 297.0,
            "currency": "BRL",
            "installments": 1,
            "openedAt": "2026-10-20T13:05:41.000Z",
            "updatedAt": "2026-10-20T13:05:41.000Z",
            "closedAt": null,
            "evidenceStatus": "DRAFT",
            "evidenceSubmittedAt": null,
            "evidenceAttachmentCount": 0,
            "submissionStatus": null,
            "charge": {
                "chargeId": "cha_1790012345678_a8f2k1pqz",
                "amount": 297.0,
                "status": "DISPUTE",
                "paymentType": "CREDIT_CARD",
                "customerName": "Maria Souza",
                "customerDocument": "12345678901",
                "customerEmail": "maria@exemplo.com.br",
                "productName": "Plano Pro"
            }
        }
    ],
    "pagination": {
        "total": 1,
        "limit": 15,
        "hasMore": false,
        "lastKey": null
    }
}
```


### Resposta 400: Tipo inválido

```json
{
    "error": {
        "message": "Parâmetro 'type' é obrigatório e deve ser MED, CHARGEBACK ou REFUND",
        "code": "INVALID_DISPUTE_TYPE",
        "details": null,
        "timestamp": "2026-10-28T14:20:00.000Z"
    }
}
```


---

Página: https://docs.validapay.com.br/referencia/get-listar-chargebacks  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json