Disputas

Um dispute é uma disputa (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 disputa: 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 montar e enviar a contestação — 6 dias corridos a partir da criação. Até lá você pode preencher, editar e limpar os campos de evidence (arquivos e textos) quantas vezes precisar; depois do prazo, essas ações são recusadas.
Depois que a defesa é enviada com sucesso — por você ou automaticamente —, o dispute passa para under_review. Esse status indica que a defesa foi recebida e a decisão final ainda está sendo avaliada. O envio é único: o caso não aceita novo envio e evidence não aceita mais alteração.
O desfecho muda o status para won quando a disputa é 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 três 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; pode vir de uma ação sua, chamando close pra encerrar o caso sem defender (mais detalhes na página de close); ou pode acontecer automaticamente — se o prazo de evidência vence sem nenhum campo de arquivo de evidence preenchido, o dispute é encerrado como lost no momento do ajuste financeiro do valor contestado, e você recebe charge.dispute.closed. Quando o prazo vence com pelo menos um campo de arquivo preenchido e a defesa ainda não enviada, o desfecho é outro: a Chargefy envia a defesa automaticamente, e o dispute segue para under_review como num envio manual. Quando a defesa foi enviada, o dispute permanece em under_review até a decisão final da análise, mesmo que o ajuste financeiro aconteça no meio do caminho.

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": {
    "access_activity_log": "2026-05-20 14:02 UTC — login e acesso ao conteúdo pelo IP 187.34.12.90",
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": "file_c1P8mQdVYE3Jt7Kw",
    "customer_email_address": "[email protected]",
    "customer_name": "Comprador",
    "customer_purchase_ip": "187.34.12.90",
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": "Assinatura mensal do plano Pro, com acesso imediato",
    "receipt": "file_xsGLuXhwUAEYUnAy",
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": "2026-05-28T03: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, com um campo nomeado para cada tipo de evidência. O hash tem sempre as mesmas 27 chaves, em ordem alfabética, com null nas que não foram preenchidas. Campos de texto recebem string livre; campos de arquivo recebem o ID de um file (file_*) enviado com purpose=dispute_evidence — veja Criar arquivo.Preencha, edite e limpe os campos com Atualizar disputa: o merge é por campo, e string vazia ("") limpa um campo — de texto ou de arquivo. Depois do envio da defesa, evidence fica somente leitura e permanece no objeto como histórico.

Campo	Tipo	Descrição
`access_activity_log`	texto	Registro de atividade do comprador (acessos, logins, uso do produto) que o conecta à compra.
`billing_address`	texto	Endereço de cobrança usado na compra.
`cancellation_policy`	arquivo	Política de cancelamento apresentada ao comprador.
`cancellation_policy_disclosure`	texto	Como e quando o comprador tomou ciência da política de cancelamento.
`cancellation_rebuttal`	texto	Sua justificativa contra a alegação de cancelamento.
`customer_communication`	arquivo	Comunicação com o comprador (e-mails, chat, mensagens) relevante ao caso.
`customer_email_address`	texto	E-mail do comprador.
`customer_name`	texto	Nome do comprador.
`customer_purchase_ip`	texto	Endereço IP usado pelo comprador na compra.
`customer_signature`	arquivo	Assinatura do comprador (contrato, comprovante de retirada).
`duplicate_charge_documentation`	arquivo	Documentação da outra cobrança, mostrando que são vendas distintas.
`duplicate_charge_explanation`	texto	Explicação de por que as cobranças não são duplicadas.
`duplicate_charge_id`	texto	ID da charge (`ch_*`) que o comprador alega ser duplicata da contestada.
`product_description`	texto	Descrição do produto ou serviço vendido.
`receipt`	arquivo	Recibo ou comprovante da compra.
`refund_policy`	arquivo	Política de reembolso apresentada ao comprador.
`refund_policy_disclosure`	texto	Como e quando o comprador tomou ciência da política de reembolso.
`refund_refusal_explanation`	texto	Sua justificativa para recusar o reembolso.
`service_date`	texto	Data em que o serviço foi prestado.
`service_documentation`	arquivo	Prova de que o serviço foi prestado.
`shipping_address`	texto	Endereço de entrega do pedido.
`shipping_carrier`	texto	Transportadora responsável pela entrega.
`shipping_date`	texto	Data de envio do pedido.
`shipping_documentation`	arquivo	Comprovante de envio ou entrega (rastreio, recibo assinado).
`shipping_tracking_number`	texto	Código de rastreio da entrega.
`uncategorized_file`	arquivo	Documento que não se encaixa nos outros campos.
`uncategorized_text`	texto	Contexto adicional que não se encaixa nos outros campos.

object

Resumo do estado da evidência: o prazo pra envio (due_by), se já existe algum campo preenchido (has_evidence), se esse prazo já passou (past_due) e se a defesa já foi enviada pra análise (submission_count). Veja o detalhe de cada subcampo abaixo.

Mostrar Campos de evidence_details

string | null

Data limite pra você preencher evidence e enviar a defesa. Quando o dispute é criado num estado que exige resposta, esse prazo é de 6 dias corridos a partir da criação — passado esse prazo, editar evidence ou enviar a defesa é recusado (veja a página de update). Se o prazo termina com pelo menos um campo de arquivo preenchido e a defesa não enviada, a Chargefy envia a defesa automaticamente. Fora dos estados que aguardam resposta (por exemplo, under_review, won, lost), não é atribuído prazo novo.

boolean

Indica se existe algum campo de evidence preenchido — de texto ou de arquivo.

boolean

Indica que o prazo em due_by já passou. Esse campo não é recalculado em tempo real a cada leitura: a Chargefy o marca pouco depois de o prazo vencer, então logo após a virada é possível ler past_due: false por um curto período mesmo com due_by já no passado. Um envio de defesa bem-sucedido zera esse valor. Quem sempre confere o prazo contra o relógio, na hora, é o próprio endpoint de envio de defesa.

integer

0 enquanto a defesa não foi enviada e 1 depois que ela foi aceita — o envio é único, feito por você (via submit) ou automaticamente pela Chargefy no fim do prazo quando havia campo de arquivo preenchido. Preencher ou limpar campos de evidence não mexe nesse 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`	Disputa 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`	Disputa decidida a favor da organização.
`lost`	Disputa decidida contra a organização.

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Ciclo de vida

Data Object

​Ciclo de vida

​Data Object

Ciclo de vida

Data Object