> ## Documentation Index > Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Como funcionam as disputas > O que é uma disputa de cartão, quem participa, o ciclo de vida completo, o efeito no saldo, os prazos e como prevenir 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](/payments/respond-to-disputes). ## Quem participa | Papel | O que faz | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **O portador do cartão** | Contesta a cobrança junto ao banco emissor, alegando um motivo — fraude, produto não recebido, duplicidade, entre outros. | | **O banco emissor** | Abre a disputa, recebe a defesa e **decide o resultado**. A decisão final é sempre dele. | | **Você (a organização)** | Monta a defesa nos campos de evidência e envia a contestação dentro do prazo. | | **A Chargefy** | Registra a disputa, valida e transmite a defesa, aplica o ajuste financeiro e entrega webhooks e e-mails. A Chargefy **não interfere na decisão** do banco emissor. | ## 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. | Status | 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. | 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](/api-reference/disputes/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 | Prazo | Duração | O que acontece | | ----------- | ---------------------------------------------------- | -------------------------------------------------------------- | | **Defesa** | 6 dias corridos a partir da criação da disputa | Janela para montar e enviar a contestação. | | **Análise** | Pode levar semanas — em alguns casos, até \~120 dias | O banco emissor avalia a defesa e decide entre `won` e `lost`. | Use o campo `evidence_details.due_by` do `dispute` como fonte de verdade para o prazo de defesa — não conte os dias por conta própria. 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](/payments/respond-to-disputes#o-que-incluir-na-defesa). | `reason` | O que o portador alega | Eixo da defesa | | ----------------------- | ----------------------------------------------------- | -------------------------------------------------------------------- | | `fraudulent` | Fraude — não foi ele quem fez a compra. | Provar que o titular fez e usou a compra. | | `unrecognized` | Não reconhece a cobrança na fatura. | Reconectar a cobrança à compra: recibo, descrição, dados usados. | | `product_not_received` | Não recebeu o produto ou serviço. | Provar a entrega ou a disponibilização do acesso. | | `product_unacceptable` | O que recebeu está em desacordo com a oferta. | Mostrar a oferta como anunciada e o que foi prestado. | | `duplicate` | Foi cobrado duas vezes pela mesma compra. | Demonstrar que são vendas distintas. | | `credit_not_processed` | Um reembolso prometido não foi processado. | Mostrar a política de reembolso e a tratativa com o comprador. | | `subscription_canceled` | Cobrança feita após o cancelamento de uma assinatura. | Mostrar a política de cancelamento aceita e por que a cobrança vale. | | `general` | Motivo genérico, sem categoria específica. | Contar a história completa da venda. | ## 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](/payments/respond-to-disputes) 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 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, 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](/payments/respond-to-disputes#chargefy-for-platforms). ## Próximos passos O guia operacional: montar a defesa, enviar a contestação e acompanhar a decisão. O contrato completo do `dispute`, incluindo os 27 campos de `evidence`. O payload que abre o fluxo de resposta no seu sistema. Como o valor contestado aparece nas regras financeiras da conta.