Disputas

Um dispute é uma contestação (chargeback) aberta pelo comprador sobre uma charge — geralmente porque ele não reconhece a cobrança, alega fraude ou diz que não recebeu o produto. O objeto acompanha o ciclo inteiro dessa contestação: desde o alerta inicial, passando pelo prazo pra você enviar a defesa, até a decisão final. Ele sempre aponta de volta pra charge original através do campo charge.

Ciclo de vida

O caso começa em needs_response ou, quando chega como alerta antecipado, em warning_needs_response. Nesse momento, a organização precisa decidir se vai enviar defesa.
Enquanto o caso espera resposta, evidence_details.due_by indica o prazo para anexar evidência e enviar a contestação.
Depois que a evidência é enviada com sucesso, o dispute passa para under_review. Esse status indica que a defesa foi recebida e a decisão final ainda está sendo avaliada.
O desfecho muda o status para won quando a contestação é decidida a favor da sua organização, ou para lost quando é decidida contra.
won e lost são estados finais. Depois de um desses status, o dispute não muda mais.

Existem duas formas de um dispute chegar em lost: a decisão pode vir de fora, através de um evento informando o resultado da análise, ou pode vir de uma ação sua, chamando close pra encerrar o caso sem enviar defesa (mais detalhes na página de close). Fora isso, vale reforçar desde já: não existe um fechamento automático quando o prazo de evidência vence — se você deixar o prazo passar sem enviar nada nem chamar close, o dispute simplesmente continua parado no mesmo status até que a decisão chegue por fora ou você encerre manualmente. Isso é explicado com mais detalhe no campo evidence_details abaixo.

Data Object

Este é o formato completo retornado em get, itens de list, update, close e em data.object dos webhooks charge.dispute.*.

{
  "id": "dp_jPjYRE9o4GRdgN3k",
  "object": "dispute",
  "amount": 15000,
  "charge": "ch_4HP9Axh4w9HqikC9",
  "closed_at": null,
  "created_at": "2026-05-22T03:00:00Z",
  "currency": "brl",
  "customer": "cus_3PdrU2SDLFkMd3L5",
  "evidence": {
    "file": "file_xsGLuXhwUAEYUnAy"
  },
  "evidence_details": {
    "due_by": "2026-05-29T03:00:00Z",
    "has_evidence": true,
    "past_due": false,
    "submission_count": 1
  },
  "is_charge_refundable": true,
  "livemode": true,
  "metadata": {},
  "payment_intent": "pi_ZzqRX1oPHKv1zKqy",
  "reason": "fraudulent",
  "status": "under_review",
  "updated_at": "2026-05-22T18:10:00Z"
}

string

Identificador do dispute. Usa o prefixo dp_*.

string

Sempre "dispute".

integer

Valor contestado, em centavos.

string

ID da charge contestada (ch_*).

object

Conteúdo da defesa: texto livre que você mandou explicando o caso (por exemplo, histórico de conversa com o cliente) mais a referência ao arquivo anexado. Quando existe um arquivo de evidência, file aponta pro ID do arquivo (file_*) — o objeto completo do arquivo, incluindo caminho de armazenamento, fica interno e não aparece aqui. Só existe um arquivo “vivo” por dispute: anexar um novo substitui o anterior.

object

Resumo do estado da evidência: o prazo pra envio (due_by), se já existe algo anexado (has_evidence), se esse prazo já passou (past_due) e quantas vezes você já enviou a defesa pra análise (submission_count). Veja o detalhe de cada subcampo abaixo.

Show Campos de evidence_details

string | null

Data limite pra você enviar a defesa. Quando o dispute é criado num estado que exige resposta, esse prazo é de 7 dias a partir da criação — passado esse prazo, tentar enviar defesa é recusado (veja a página de update). Fora dos estados que aguardam resposta (por exemplo, under_review, won, lost), não é atribuído prazo novo.

boolean

Indica se existe algo registrado em evidence (texto e/ou arquivo).

boolean

Indica que o prazo em due_by já tinha passado no momento em que esse valor foi calculado. Esse campo não é recalculado em tempo real a cada leitura — ele reflete o estado na última vez que o dispute foi atualizado (por um evento novo ou por um envio de defesa bem-sucedido, que sempre zera esse valor). Ou seja, é possível ler past_due: false mesmo com due_by no passado, se nada novo aconteceu com o dispute desde então. Quem sempre confere o prazo contra o relógio, na hora, é o próprio endpoint de envio de defesa.

integer

Quantas vezes você já enviou a defesa com sucesso (submit: true aceito). Anexar ou trocar o arquivo de evidência sozinho não conta aqui — só envios de fato aceitos incrementam esse número.

boolean

Indica se a charge ainda pode receber refund.

object

Pares chave-valor livres. Quando vazio, retorna {}.

string | null

Motivo normalizado quando disponível.

Valor	Descrição
`fraudulent`	O comprador alega fraude na cobrança.
`product_not_received`	O comprador alega que não recebeu o produto.
`product_unacceptable`	O comprador alega que o produto veio com defeito ou diferente do anunciado.
`duplicate`	O comprador alega cobrança duplicada.
`credit_not_processed`	O comprador alega que um reembolso prometido não foi processado.
`subscription_canceled`	O comprador alega cobrança após cancelar a assinatura.
`unrecognized`	O comprador não reconhece a cobrança.
`general`	Contestação sem motivo específico.

string

Estado do dispute.

Valor	Descrição
`warning_needs_response`	Alerta antecipado aguardando resposta.
`warning_under_review`	Alerta antecipado em análise.
`warning_closed`	Alerta antecipado encerrado.
`needs_response`	Aguardando envio da defesa.
`under_review`	Defesa em análise.
`won`	Contestação decidida a favor da organização.
`lost`	Contestação decidida contra a organização.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Ciclo de vida

Data Object

​Ciclo de vida

​Data Object

Ciclo de vida

Data Object