Chargebacks

Listar 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

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.

Escopos requeridos

charges/read

Query Parameters

typeobrigatório

sempre CHARGEBACK nesta seção

CHARGEBACK

limitopcional

itens por página, default 15

lastKeyopcional

cursor devolvido em pagination.lastKey

statusopcional

DISPUTE, REFUND_PENDING, DISPUTE_CLOSED ou CHARGED_BACK

dateFromopcional

abertos a partir deste instante, em ISO 8601 (2026-10-01T00:00:00.000Z)

dateToopcional

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

chargeIdopcional

só os chargebacks desta cobrança

searchopcional

busca por caseId, chargeId ou transactionId

← Anterior

Consultar status do estorno

Resumo de chargebacks

const url = 'https://sandbox.validapay.com.br/v1/disputes?type=CHARGEBACK&limit=15';

const options = {
  method: 'GET',
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200Sucesso▾

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
    }
}

400Tipo 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"
    }
}

← Anterior

Consultar status do estorno

Resumo de chargebacks