Como funcionam as disputas

Uma disputa — o chargeback — nasce quando o portador de um cartão contesta uma cobrança junto ao banco que emitiu o cartão. O banco abre a disputa, o valor entra em discussão e a organização tem a chance de provar que a cobrança é legítima. Na Chargefy, cada disputa é um objeto dispute (dp_*) ligado à charge contestada. Esta página explica o conceito: quem participa, o ciclo de vida, o efeito no dinheiro, os prazos e como reduzir a chance de uma disputa acontecer. Quando uma disputa chegar, o passo a passo da resposta está em Como responder a disputas.

​

Quem participa

​

Ciclo de vida

Uma disputa formal normalmente nasce em needs_response: o valor está contestado e a organização precisa responder. Enviada a defesa — por você ou automaticamente —, ela passa a under_review e permanece assim até a decisão final, won ou lost. Em alguns casos, antes da disputa formal chega um alerta prévio (os status warning_*): o banco emissor sinaliza a disputa e dá a chance de resolver antes de formalizá-la. Um alerta pode ser encerrado sem virar disputa (warning_closed) ou dar origem à disputa formal. Além da decisão do banco, dois caminhos levam uma disputa a lost sem análise: a organização pode conceder a disputa (aceitar a perda pela ação close), e o prazo de defesa pode terminar sem nenhum campo de arquivo preenchido — nesse caso o encerramento é automático.

​

O efeito no dinheiro

• Enquanto o prazo de defesa está aberto, o valor contestado ainda não foi debitado do seu saldo.
• No fim do prazo de defesa acontece o ajuste financeiro: o valor contestado é debitado.
• Se a disputa terminar em won, o valor é devolvido ao seu saldo. Se terminar em lost, o débito permanece.

​

Prazos

No fim do prazo de defesa, o desfecho depende do que foi preenchido:

• Com pelo menos um campo de arquivo preenchido e defesa ainda não enviada, a Chargefy envia a defesa automaticamente. Você recebe um e-mail de confirmação e o webhook charge.dispute.updated reflete a mudança para under_review.
• Sem nenhum campo de arquivo preenchido, a disputa é encerrada como lost e você recebe charge.dispute.closed.

​

Motivos

O campo reason traz o motivo normalizado da disputa, quando informado — ele pode ser null. O motivo orienta quais campos de evidência preencher na defesa; o mapa completo está em Como responder a disputas.

​

Acompanhe cada disputa

• Dashboard — em Pagamentos → Disputas, cada disputa mostra prazo, valor, charge, os campos da defesa por categoria e o botão Submeter evidências.
• E-mails — a organização é avisada quando a disputa é criada, recebe lembretes 3 dias e 1 dia antes do fim do prazo e uma confirmação quando o envio automático acontece. Cada membro controla esses avisos nas notificações de disputas, em Configurações da organização → Notificações.
• Webhooks — charge.dispute.created, charge.dispute.updated e charge.dispute.closed acompanham o ciclo inteiro. O guia de resposta mostra quando tratar cada um.

​

Como prevenir disputas

A melhor disputa é a que não acontece. Boas práticas que reduzem a chance de uma cobrança ser contestada:

• Deixe claro quem está cobrando. O comprador precisa reconhecer a compra ao ler a fatura do cartão — nome, marca e valor coerentes com o que ele viu no checkout.
• Confirme a compra por e-mail, com descrição do que foi comprado, valor e um canal de suporte fácil de achar.
• Apresente as políticas antes do pagamento. Reembolso e cancelamento claros e acessíveis derrubam alegações de desacordo — e viram evidência na defesa.
• Entregue rápido e registre a entrega. Rastreio em produtos físicos; logs de acesso, ativação e download em produtos digitais.
• Resolva no suporte antes que vire disputa. Um reembolso voluntário costuma custar menos do que uma disputa perdida.
• Guarde evidências desde a venda. Conversas, aceites de política e logs guardados no dia a dia permitem montar uma defesa em minutos, não em dias.

​

Chargefy for Platforms

As disputas nascem nas vendas das suas organizações filhas, e a plataforma acompanha e responde por elas:

• Os webhooks charge.dispute.* entregues à plataforma trazem o campo top-level organization identificando a organização filha que originou a disputa.
• Nas chamadas de API do fluxo de disputa, a plataforma envia o header Organization com essa organização filha. O detalhe está na seção de plataformas do guia de resposta.

​

Próximos passos