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, quais arquivos são aceitos, como enviar a contestação e como acompanhar a decisão.

O prazo de defesa é de 7 dias corridos a partir da emissão da notificação. 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.
Reúna todos os documentos em um único arquivo.
Faça upload da evidência antes do prazo.
Envie a contestação para análise.
Acompanhe charge.dispute.updated e charge.dispute.closed até a decisão final.

Acontecimento	Transição
A disputa é criada e exige resposta	Início → `needs_response`
A contestação é enviada	`needs_response` → `under_review`
Você concede a disputa	`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 enviar evidências. Campos importantes:

Campo	Como usar
`id`	ID da disputa (`dp_*`). Use em consultas, upload e envio para análise.
`charge`	Charge contestada (`ch_*`). Use para reconciliar com pedido, invoice ou assinatura.
`amount`	Valor contestado, em centavos.
`customer`	Customer relacionado, quando disponível.
`evidence_details.due_by`	Prazo final para envio da contestação.
`evidence_details.has_evidence`	Indica se já existe arquivo associado.
`evidence_details.submission_count`	Quantidade de envios para análise já feitos.
`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.

No 8º dia corrido, pode haver ajuste financeiro relacionado à contestação. Isso não significa decisão final. O dispute público permanece em under_review enquanto a análise final estiver em andamento.

Prazos e estados

Momento	O que acontece	O que você deve fazer
Dia 0	Disputa criada em `needs_response`.	Comece a reunir documentos imediatamente.
Até 7 dias corridos	A contestação ainda pode ser enviada.	Faça upload do arquivo e envie para análise.
Dia 8 em diante	A disputa segue em análise quando a defesa foi enviada.	Acompanhe webhooks e reconciliação financeira.
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.

Requisitos do arquivo

A defesa deve ser consolidada em um único arquivo. A Chargefy não aceita múltiplos anexos para a mesma submissão.

Requisito	Valor
Formato	PDF ou TIF
Tamanho máximo	7 MB
Quantidade de arquivos	1 arquivo
PDF	Até 10 páginas
Resolução	Até 200 DPI
Orientação	Páginas verticais
Cor	Preferencialmente preto e branco

Também recomendamos:

Não envie arquivo protegido por senha.
Não envie páginas em branco.
Use nomes de arquivo simples, sem caracteres especiais.
Garanta que textos, comprovantes e datas estejam legíveis.
Consolide prints, comprovantes, conversas e recibos no mesmo PDF/TIF.

Se o arquivo estiver ilegível, exceder o limite ou for enviado fora do prazo, a contestação pode não ser analisada. O upload valida formato, tamanho e contagem de páginas do PDF; qualidade visual e conteúdo continuam sendo responsabilidade da organização.

O que incluir na defesa

Monte o documento pensando em uma pessoa que não conhece a venda. O arquivo precisa explicar por que a cobrança é legítima ou por que o produto/serviço foi entregue corretamente.

Fraude ou cobrança não reconhecida

Inclua evidências que conectem o comprador à transação:

Recibo ou comprovante de compra.
Dados de autenticação, login, IP, dispositivo ou aceite de termos, quando existirem.
Comprovante de entrega, uso, acesso ou ativação do serviço.
Comunicação com o comprador reconhecendo a compra.
Em casos de fraude, inclua o vínculo com Mensagem Emissor quando aplicável.

Produto não recebido

Inclua evidências de entrega ou disponibilização:

Código de rastreio, comprovante de postagem ou comprovante de entrega.
Data e endereço de entrega.
Logs de acesso, ativação ou download em produtos digitais.
Histórico de atendimento mostrando resolução ou tentativa de contato.

Produto inaceitável, cancelamento ou desacordo comercial

Inclua contexto comercial:

Descrição do produto/serviço vendido.
Política de cancelamento, troca ou reembolso aceita pelo comprador.
Comprovante de aceite dos termos.
Conversas de suporte.
Evidências de que o serviço foi prestado ou que o produto estava de acordo com a oferta.

Duplicidade, crédito não processado ou assinatura cancelada

Inclua linha do tempo e conciliação:

IDs das cobranças relacionadas.
Comprovantes de refund, cancelamento ou ausência de refund.
Histórico de invoices, assinaturas ou pedidos.
Datas de cobrança, cancelamento e comunicação com o cliente.

Enviar pelo Dashboard

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

Acesse o Dashboard da Chargefy.
Entre em Financeiro → Disputas.
Abra a disputa.
Confira o prazo, valor, charge e customer.
Faça upload do arquivo PDF/TIF.
Revise o checklist exibido na tela.
Clique em Enviar à análise.
Acompanhe o histórico de envios na própria disputa.

Se a organização decidir não defender a cobrança, use Encerrar. Essa ação concede a contestação e muda o dispute para lost.

Enviar pela API

Use este caminho quando seu sistema opera disputas server-to-server. Para plataformas, inclua o header Organization com a organização conectada que originou a disputa.

1. Consulte a disputa

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

Resposta resumida:

{
  "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": {},
  "evidence_details": {
    "due_by": "2026-05-29T03: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. Faça upload do arquivo

Envie exatamente um arquivo no campo file.

curl -X POST "https://api.chargefy.io/v1/dispute-evidence-upload" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -F "dispute_id=dp_A3bcTcGXjaqcz1VW" \
  -F "file=@/caminho/local/defesa.pdf;type=application/pdf"

Para API key de plataforma:

curl -X POST "https://api.chargefy.io/v1/dispute-evidence-upload" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Organization: org_KgmNfKrEHmy8AePB" \
  -F "dispute_id=dp_A3bcTcGXjaqcz1VW" \
  -F "file=@/caminho/local/defesa.pdf;type=application/pdf"

Erros comuns de upload:

Status	Quando ocorre
`400`	Arquivo ausente, mais de um arquivo, MIME inválido, PDF sem contagem de páginas legível ou PDF com mais de 10 páginas.
`400`	Arquivo acima de 7 MB.
`404`	Disputa não encontrada na organização autenticada.
`409`	Disputa já fechada.

3. Envie para análise

Depois do upload, envie submit: true no dispute.

curl -X POST "https://api.chargefy.io/v1/disputes/dp_A3bcTcGXjaqcz1VW" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "submit": true
  }'

Você também pode atualizar metadata e evidências textuais antes do envio:

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": "Conversation and receipt attached."
    },
    "metadata": {},
    "submit": true
  }'

Se o envio for aceito, o dispute passa para under_review.

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

Webhooks que você deve tratar

Configure seu endpoint para receber estes eventos:

Evento	Quando tratar
`charge.dispute.created`	Abrir tarefa operacional e iniciar coleta de evidências.
`charge.dispute.updated`	Atualizar status interno, evidência enviada ou contagem de submissões.
`charge.dispute.closed`	Registrar decisão final como `won` ou `lost`.

Em plataformas, use o campo top-level organization do webhook para identificar a organização conectada que originou a disputa.

Checklist operacional

Antes de clicar em Enviar à análise ou enviar submit: true, confirme:

O prazo evidence_details.due_by ainda não expirou.
O arquivo é PDF ou TIF.
O arquivo tem no máximo 7 MB.
O PDF tem até 10 páginas.
O documento está legível, vertical e preferencialmente em preto e branco.
Todas as evidências estão consolidadas em um único arquivo.
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.
Enviar vários arquivos	Consolide tudo em um único PDF/TIF antes do upload.
Arquivo ilegível	Revise o PDF/TIF como se fosse uma impressão: texto pequeno, cortes e páginas tortas reduzem a chance de análise.
Enviar defesa sem arquivo	Primeiro faça upload, depois envie `submit: true`.
Conceder por engano	Use `close` somente quando a organização decidiu aceitar a perda da contestação.
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

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

Como responder a disputas

Resumo do fluxo

O que muda quando a disputa nasce

Prazos e estados

Requisitos do arquivo

O que incluir na defesa

Fraude ou cobrança não reconhecida

Produto não recebido

Produto inaceitável, cancelamento ou desacordo comercial

Duplicidade, crédito não processado ou assinatura cancelada

Enviar pelo Dashboard

Enviar pela API

1. Consulte a disputa

2. Faça upload do arquivo

3. Envie para análise

Webhooks que você deve tratar

Checklist operacional

Erros comuns

​Resumo do fluxo

​O que muda quando a disputa nasce

​Prazos e estados

​Requisitos do arquivo

​O que incluir na defesa

​Fraude ou cobrança não reconhecida

​Produto não recebido

​Produto inaceitável, cancelamento ou desacordo comercial

​Duplicidade, crédito não processado ou assinatura cancelada

​Enviar pelo Dashboard

​Enviar pela API

​1. Consulte a disputa

​2. Faça upload do arquivo

​3. Envie para análise

​Webhooks que você deve tratar

​Checklist operacional

​Erros comuns

Resumo do fluxo

O que muda quando a disputa nasce

Prazos e estados

Requisitos do arquivo

O que incluir na defesa

Fraude ou cobrança não reconhecida

Produto não recebido

Produto inaceitável, cancelamento ou desacordo comercial

Duplicidade, crédito não processado ou assinatura cancelada

Enviar pelo Dashboard

Enviar pela API

1. Consulte a disputa

2. Faça upload do arquivo

3. Envie para análise

Webhooks que você deve tratar

Checklist operacional

Erros comuns