Como responder a disputas

Uma disputa acontece quando o portador questiona uma cobrança de cartão. Quando isso acontece, a Chargefy cria um objeto dispute ligado à charge original e abre um prazo para envio de evidências. Este guia mostra o que fazer quando uma disputa é criada, como montar a defesa nos campos nomeados de evidence, como enviar a contestação e como acompanhar a decisão. Para o conceito — quem participa, o ciclo de vida completo, o efeito no saldo e como prevenir disputas —, veja Como funcionam as disputas.

O prazo de defesa é de 6 dias corridos a partir da criação da disputa. Use o campo evidence_details.due_by do dispute como fonte de verdade para o prazo.

Resumo do fluxo

Receba o webhook charge.dispute.created ou veja a disputa no Dashboard.
Consulte o dispute e confirme status, reason, charge e evidence_details.due_by.
Suba cada documento da defesa com POST /v1/files e purpose=dispute_evidence (PDF, JPG ou PNG) — cada upload retorna um file_*.
Anexe cada file_* ao campo de arquivo correspondente de evidence e preencha os campos de texto com POST /v1/disputes/{id}, usando submit: false enquanto monta a defesa.
Envie a defesa com submit: true. O envio é único e irreversível.
Acompanhe charge.dispute.updated e charge.dispute.closed até a decisão final.

Um request de update que contém evidence envia a defesa por padrão: submit omitido vale true. Enquanto estiver montando a defesa em várias chamadas, mande submit: false explicitamente em cada uma.

Se o prazo termina com pelo menos um campo de arquivo preenchido e a defesa ainda não enviada, a Chargefy envia a defesa automaticamente por você. Você recebe um e-mail confirmando o envio e o charge.dispute.updated reflete a mudança para under_review.

Acontecimento	Transição
A disputa é criada e exige resposta	Início → `needs_response`
A contestação é enviada (por você ou automaticamente)	`needs_response` → `under_review`
Você concede a disputa	`needs_response` → `lost`
O prazo expira sem campo de arquivo preenchido	`needs_response` → `lost`
A defesa é aceita	`under_review` → `won`
A defesa é recusada	`under_review` → `lost`

O que muda quando a disputa nasce

Quando o dispute é criado, ele normalmente começa em needs_response. Nesse estado, a organização ainda pode montar e enviar a defesa. Campos importantes:

Campo	Como usar
`id`	ID da disputa (`dp_*`). Use em consultas e updates.
`charge`	Charge contestada (`ch_*`). Use para reconciliar com pedido, invoice ou assinatura.
`amount`	Valor contestado, em centavos.
`customer`	Customer relacionado, quando disponível.
`evidence`	Os 27 campos nomeados da defesa — texto e arquivo —, sempre presentes e `null` nos vazios.
`evidence_details.due_by`	Prazo final para envio da contestação.
`evidence_details.has_evidence`	Indica se algum campo de `evidence` já está preenchido.
`evidence_details.submission_count`	`1` depois que a defesa foi enviada para análise.
`reason`	Motivo normalizado quando disponível. Pode ser `null`.
`status`	Estado atual da disputa.

Os valores possíveis de status:

Valor	Descrição
`warning_needs_response`	Alerta prévio de disputa aguardando resposta da organização.
`warning_under_review`	Alerta prévio com resposta enviada, em análise.
`warning_closed`	Alerta prévio encerrado sem virar disputa.
`needs_response`	Disputa aberta aguardando o envio da contestação.
`under_review`	Contestação enviada, em análise.
`won`	Decisão final favorável à organização.
`lost`	Decisão final favorável ao portador.

Os valores possíveis de reason, quando informado:

Valor	Descrição
`fraudulent`	O portador alega fraude na cobrança.
`product_not_received`	O comprador alega não ter recebido o produto ou serviço.
`product_unacceptable`	O produto ou serviço recebido estava em desacordo com a oferta.
`duplicate`	O comprador alega cobrança em duplicidade.
`credit_not_processed`	Um reembolso prometido não foi processado.
`subscription_canceled`	Cobrança feita após o cancelamento de uma assinatura.
`unrecognized`	O portador não reconhece a cobrança.
`general`	Motivo genérico, sem categoria específica.

O ajuste financeiro do valor contestado acontece após o fim do prazo de defesa. Se nenhum campo de arquivo foi preenchido até lá, a disputa é encerrada como lost e você recebe charge.dispute.closed. Se a defesa foi enviada — por você ou automaticamente —, o dispute permanece em under_review até a decisão final da análise.

Prazos e estados

Momento	O que acontece	O que você deve fazer
Dia 0	Disputa criada em `needs_response`, com `evidence_details.due_by` 6 dias à frente.	Comece a subir os documentos imediatamente.
Até o fim do prazo	Você pode preencher, editar e limpar os campos de `evidence` e enviar a defesa.	Monte a defesa e envie para análise.
Fim do prazo	Editar `evidence` e enviar manualmente são bloqueados. Com campo de arquivo preenchido e defesa não enviada, a Chargefy envia automaticamente. Sem nenhum arquivo, a disputa é encerrada como `lost` no ajuste financeiro.	Trate `charge.dispute.updated` (envio automático) ou `charge.dispute.closed`.
Decisão final	O `status` muda para `won` ou `lost`.	Trate `charge.dispute.closed` e atualize seu backoffice.

A decisão final pode levar semanas e, em alguns casos, até cerca de 120 dias. Evite fazer polling agressivo: use webhooks para acompanhar a mudança de estado.

Como a defesa é montada

A defesa inteira vive nos campos nomeados de evidence do dispute: 18 campos de texto (dados do comprador, datas, explicações) e 9 campos de arquivo (recibo, conversas, comprovante de envio, políticas). Campo de arquivo recebe o file_* de um upload com purpose=dispute_evidence; campo de texto recebe string livre. Cada update faz merge por campo — o que você não enviar fica como está — e string vazia ("") limpa um campo, de texto ou de arquivo. O catálogo completo dos 27 campos, com a descrição de cada um, está na visão geral do dispute.

Requisitos e limites

Requisito	Valor
Formatos aceitos	PDF, JPG e PNG
Tamanho por arquivo	Até 7 MB
Tamanho somado	Até 6,5 MB nos arquivos preenchidos na defesa
Páginas somadas	Até 10 no total: PDF conta as páginas reais, medidas no upload; cada imagem conta 1 página
Texto somado	Até 150.000 caracteres no conjunto dos campos de texto

Os limites somados valem para o conjunto de campos preenchidos e são validados a cada update de evidence — você nunca descobre um estouro só na hora do envio, e a mensagem de erro diz quanto ainda resta. Também recomendamos, pela legibilidade da defesa:

Prefira páginas e capturas em orientação vertical.
Preto e branco costuma ficar mais legível na análise; use cor quando ela for parte da prova.
PDF protegido por senha é recusado no upload.
Não use páginas em branco.
Use nomes de arquivo simples, sem caracteres especiais.
Garanta que textos, comprovantes e datas estejam legíveis.

Se os arquivos estiverem ilegíveis ou o envio acontecer fora do prazo, a defesa pode não ser analisada. O upload valida formato, tamanho e contagem de páginas; qualidade visual e conteúdo continuam sendo responsabilidade da organização.

O que incluir na defesa

Monte a defesa pensando em uma pessoa que não conhece a venda. Os campos preenchidos precisam explicar por que a cobrança é legítima ou por que o produto/serviço foi entregue corretamente. Use os campos indicados pelo reason da disputa; uncategorized_text e uncategorized_file recebem o que não couber nos demais.

`reason` da disputa	Comece por estes campos
`fraudulent`, `unrecognized`	`receipt`, `customer_communication`, `access_activity_log`, `customer_purchase_ip`, `customer_name`, `customer_email_address`, `billing_address`, `customer_signature`
`product_not_received`	`shipping_documentation`, `shipping_carrier`, `shipping_date`, `shipping_tracking_number`, `shipping_address` — ou `access_activity_log` e `service_documentation` no digital
`product_unacceptable`	`product_description`, `service_documentation`, `service_date`, `customer_communication`, `refund_policy`, `refund_policy_disclosure`, `refund_refusal_explanation`
`subscription_canceled`	`cancellation_policy`, `cancellation_policy_disclosure`, `cancellation_rebuttal`, `customer_communication`
`duplicate`	`duplicate_charge_id`, `duplicate_charge_explanation`, `duplicate_charge_documentation`
`credit_not_processed`	`refund_policy`, `refund_policy_disclosure`, `refund_refusal_explanation`, `customer_communication`
`general` ou sem `reason`	Os campos que melhor contam a história da venda; `uncategorized_text` e `uncategorized_file` para o restante

Fraude ou cobrança não reconhecida

Conecte o comprador à transação:

receipt: recibo ou comprovante da compra.
customer_communication: conversas em que o comprador reconhece a compra.
access_activity_log e customer_purchase_ip: autenticação, login, IP, dispositivo ou uso do produto.
customer_name, customer_email_address e billing_address: dados usados na compra.
customer_signature: assinatura em contrato ou comprovante de retirada.
product_description: o que foi vendido e como é entregue.

Produto não recebido

Prove a entrega ou disponibilização:

shipping_documentation: comprovante de postagem ou de entrega.
shipping_carrier, shipping_date, shipping_tracking_number e shipping_address: transportadora, datas, rastreio e endereço.
Em produtos digitais, access_activity_log e service_documentation mostram acesso, ativação ou download.

Produto inaceitável ou desacordo comercial

Mostre o contexto comercial:

product_description: a oferta como anunciada.
service_documentation e service_date: o que foi prestado e quando.
customer_communication: tratativas de suporte.
refund_policy, refund_policy_disclosure e refund_refusal_explanation: a política de reembolso, como o comprador tomou ciência dela e sua justificativa.

Cancelamento de assinatura

Mostre a regra aceita pelo comprador:

cancellation_policy e cancellation_policy_disclosure: a política de cancelamento e como ela foi apresentada.
cancellation_rebuttal: por que a cobrança é válida mesmo com a alegação.
customer_communication: histórico com o cliente.

Duplicidade ou crédito não processado

Monte a linha do tempo e a conciliação:

duplicate_charge_id: a charge (ch_*) que o comprador aponta como duplicata.
duplicate_charge_explanation e duplicate_charge_documentation: por que são vendas distintas.
refund_policy e refund_refusal_explanation: contexto do reembolso prometido ou recusado.

Enviar pelo Dashboard

Use este caminho quando a operação é feita por uma pessoa da organização.

Acesse o Dashboard da Chargefy.
Entre em Pagamentos → Disputas.
Abra a disputa.
Confira o prazo, valor, charge e customer.
Anexe os documentos nos campos de arquivo e preencha os campos de texto da defesa. Você pode editar e limpar os campos enquanto o prazo estiver aberto.
Revise os campos preenchidos e as Orientações exibidas na tela.
Clique em Submeter evidências. O envio é único e irreversível.
Acompanhe o histórico na própria disputa.

Se a organização decidir não defender a cobrança, encerre a disputa pela API com close. Essa ação concede a disputa e muda o dispute para lost.

Enviar pela API

Use este caminho quando seu sistema opera disputas server-to-server. As diferenças para contas com Chargefy for Platforms estão na seção dedicada mais abaixo.

1. Consulte a disputa

curl -X GET "https://api.chargefy.io/v1/disputes/dp_A3bcTcGXjaqcz1VW" \
  -H "Authorization: Bearer {{API_KEY}}"

O dispute nasce com o hash de evidence completo — todas as 27 chaves, em ordem alfabética, null enquanto vazias:

{
  "id": "dp_A3bcTcGXjaqcz1VW",
  "object": "dispute",
  "amount": 15000,
  "charge": "ch_8jkm3zq9icME7BL8",
  "closed_at": null,
  "created_at": "2026-05-22T03:00:00Z",
  "currency": "brl",
  "customer": "cus_rPDKcQYE3M1J9uKC",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "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": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {},
  "payment_intent": "pi_mALqiee6SkiBG3g9",
  "reason": "fraudulent",
  "status": "needs_response",
  "updated_at": "2026-05-22T03:00:00Z"
}

Veja o contrato completo em Consultar dispute.

2. Suba os documentos

Cada documento da defesa é um upload próprio em POST /v1/files, com purpose=dispute_evidence. Repita para cada arquivo — um file_* por documento.

curl -X POST "https://api.chargefy.io/v1/files" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -F "purpose=dispute_evidence" \
  -F "file=@/caminho/local/recibo.pdf;type=application/pdf"

curl -X POST "https://api.chargefy.io/v1/files" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -F "purpose=dispute_evidence" \
  -F "file=@/caminho/local/conversa.png;type=image/png"

Cada upload retorna o file criado — guarde o id:

{
  "id": "file_9TkQ2wXr5PmB8dNc",
  "object": "file",
  "created_at": "2026-05-22T14:10:00Z",
  "expires_at": null,
  "filename": "recibo.pdf",
  "livemode": false,
  "metadata": {},
  "mime_type": "application/pdf",
  "purpose": "dispute_evidence",
  "size": 182044,
  "updated_at": null,
  "url": "https://storage.chargefy.io/file_9TkQ2wXr5PmB8dNc"
}

No upload, a Chargefy conta as páginas do documento (PDF conta as páginas reais; cada imagem conta 1) e recusa PDF protegido por senha ou ilegível. Os detalhes estão em Criar arquivo.

3. Anexe os arquivos e preencha os textos

Aponte cada file_* para o campo de arquivo correspondente de evidence e preencha os campos de texto, com submit: false enquanto monta. O merge é por campo; pra trocar um documento, envie o campo de novo com outro file_*; pra limpar um campo, envie "".

curl -X POST "https://api.chargefy.io/v1/disputes/dp_A3bcTcGXjaqcz1VW" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": {
      "customer_communication": "file_G5hJ3rN8sD6bY2wK",
      "customer_email_address": "[email protected]",
      "customer_purchase_ip": "187.34.12.90",
      "product_description": "Assinatura mensal do plano Pro, com acesso imediato",
      "receipt": "file_9TkQ2wXr5PmB8dNc"
    },
    "submit": false
  }'

Cada chamada valida os arquivos apontados (existência, organização, purpose) e os limites somados da defesa. O mesmo file_* não pode ocupar dois campos.

4. Envie a defesa

Com pelo menos um campo de arquivo preenchido, envie a defesa. O request final pode completar os últimos campos e enviar na mesma chamada:

curl -X POST "https://api.chargefy.io/v1/disputes/dp_A3bcTcGXjaqcz1VW" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": {
      "access_activity_log": "2026-05-20 14:02 UTC — login e acesso ao conteúdo pelo IP 187.34.12.90"
    },
    "submit": true
  }'

Se o envio for aceito, o dispute passa para under_review e evidence fica somente leitura. O envio é único: depois de aceito, a defesa não pode ser alterada nem reenviada. Os parâmetros, validações e erros completos estão em Atualizar disputa.

POST /v1/disputes/{id}/close não envia defesa. Essa ação concede a disputa e retorna o dispute como lost.

Erros comuns do fluxo:

Status	Quando ocorre
`400`	Chave desconhecida em `evidence`, `file` inexistente ou com purpose errado, mesmo `file_*` em dois campos, ou estouro dos limites somados.
`404`	Disputa não encontrada na organização autenticada.
`409`	Disputa já fechada, defesa já enviada, prazo expirado ou envio sem nenhum campo de arquivo preenchido.

Webhooks que você deve tratar

Configure seu endpoint para receber estes eventos — o cadastro do endpoint, a verificação de assinatura e a reentrega estão em Entrega de webhooks:

Evento	Quando tratar
`charge.dispute.created`	Abrir tarefa operacional e iniciar coleta de evidências.
`charge.dispute.updated`	Atualizar status interno, campos de evidência e o envio da defesa — inclusive o envio automático.
`charge.dispute.closed`	Registrar o encerramento: `won`, `lost` — inclusive o automático no fim do prazo — ou `warning_closed`.

Chargefy for Platforms

Esta seção só se aplica a contas com o produto Chargefy for Platforms habilitado. Nesse produto, uma plataforma opera pagamentos para suas organizações filhas.

As disputas nascem nas vendas das suas organizações filhas. O fluxo é o mesmo descrito acima, com duas diferenças:

Webhooks — nos eventos charge.dispute.* entregues à plataforma, o campo top-level organization identifica a organização filha que originou a disputa. Use-o para rotear o caso no seu sistema.
Chamadas de API — envie o header Organization com essa organização filha em todas as chamadas do fluxo, inclusive nos uploads de POST /v1/files. Sem o header, a disputa da organização filha não é encontrada.

curl -X GET "https://api.chargefy.io/v1/disputes/dp_A3bcTcGXjaqcz1VW" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: org_5Nq8rT2wX7mK4pV9"

Checklist operacional

Antes de enviar a defesa — pelo Dashboard ou pela API —, confirme:

O prazo evidence_details.due_by ainda não expirou.
Todos os arquivos são PDF, JPG ou PNG, com até 7 MB cada.
O conjunto preenchido respeita os limites somados: até 10 páginas e 6,5 MB de arquivos, e até 150.000 caracteres de texto.
Pelo menos um campo de arquivo está preenchido — o envio exige arquivo.
Os documentos estão legíveis, de preferência em orientação vertical.
A defesa explica o contexto da compra, entrega, uso ou cancelamento.
Seu sistema está preparado para receber charge.dispute.closed.

Erros comuns

Situação	Como evitar
Perder o prazo	Crie automação interna no recebimento de `charge.dispute.created` e trate `due_by` como prazo fatal. Com campo de arquivo preenchido, a Chargefy envia automaticamente no fim do prazo — mas preencher a tempo continua sendo sua responsabilidade.
Enviar sem querer	Um request com `evidence` e sem `submit` envia a defesa por padrão. Enquanto monta a defesa, mande `submit: false` em cada chamada.
Estourar os limites somados	Cada update de `evidence` valida os limites e recusa o campo que estouraria o conjunto; a mensagem de erro diz quanto ainda resta.
Reusar o mesmo arquivo em 2 campos	Cada campo de arquivo recebe um upload próprio; o mesmo `file_*` em dois campos é recusado.
Arquivo ilegível	Revise cada documento como se fosse uma impressão: texto pequeno, cortes e páginas tortas reduzem a chance de análise.
Enviar defesa sem arquivo	Preencha ao menos um campo de arquivo antes do envio — só texto é recusado com `409`.
Conceder por engano	Use `close` somente quando a organização decidiu aceitar a perda da disputa.
Ignorar `closed`	A decisão final pode chegar muito depois do envio; trate `charge.dispute.closed` para fechar o caso no seu sistema.

Pagamentos online

Receber pagamentos

Clientes e faturamento

Assinaturas

Operação e pós-pagamento

Marketing e rastreamento

Como responder a disputas

Resumo do fluxo

O que muda quando a disputa nasce

Prazos e estados

Como a defesa é montada

Requisitos e limites

O que incluir na defesa

Fraude ou cobrança não reconhecida

Produto não recebido

Produto inaceitável ou desacordo comercial

Cancelamento de assinatura

Duplicidade ou crédito não processado

Enviar pelo Dashboard

Enviar pela API

1. Consulte a disputa

2. Suba os documentos

3. Anexe os arquivos e preencha os textos

4. Envie a defesa

Webhooks que você deve tratar

Chargefy for Platforms

Checklist operacional

Erros comuns

​Resumo do fluxo

​O que muda quando a disputa nasce

​Prazos e estados

​Como a defesa é montada

​Requisitos e limites

​O que incluir na defesa

​Fraude ou cobrança não reconhecida

​Produto não recebido

​Produto inaceitável ou desacordo comercial

​Cancelamento de assinatura

​Duplicidade ou crédito não processado

​Enviar pelo Dashboard

​Enviar pela API

​1. Consulte a disputa

​2. Suba os documentos

​3. Anexe os arquivos e preencha os textos

​4. Envie a defesa

​Webhooks que você deve tratar

​Chargefy for Platforms

​Checklist operacional

​Erros comuns

Resumo do fluxo

O que muda quando a disputa nasce

Prazos e estados

Como a defesa é montada

Requisitos e limites

O que incluir na defesa

Fraude ou cobrança não reconhecida

Produto não recebido

Produto inaceitável ou desacordo comercial

Cancelamento de assinatura

Duplicidade ou crédito não processado

Enviar pelo Dashboard

Enviar pela API

1. Consulte a disputa

2. Suba os documentos

3. Anexe os arquivos e preencha os textos

4. Envie a defesa

Webhooks que você deve tratar

Chargefy for Platforms

Checklist operacional

Erros comuns