Pular para o conteúdo principal
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

  1. 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.
  2. 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.
  3. 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.
  4. O desfecho muda o status para won quando a disputa é decidida a favor da sua organização, ou para lost quando é decidida contra.
  5. won é final. lost só muda se uma decisão favorável chegar depois do encerramento: aí o dispute passa a won e você recebe charge.dispute.closed de novo.

Dinheiro da disputa

Quando a disputa abre, o valor da venda sai do seu saldo num movimento próprio do extrato, e você recebe charge.dispute.funds.withdrawn. Quando a disputa é ganha, o mesmo valor volta num segundo movimento, e você recebe charge.dispute.funds.reinstated. A devolução nasce pending, com available_at na data em que o dinheiro volta a ficar disponível, e passa a paid quando entra no saldo. Os dois movimentos ficam em transactions, do mais antigo ao mais novo. Exemplo: numa venda de R$ 150,00 que creditou R$ 144,15, a disputa tira R$ 146,71 (os R$ 144,15 e R$ 2,56 de tarifa de recebimento de contestação). Se a disputa for ganha, voltam os R$ 146,71, e o saldo fica de novo com os R$ 144,15 da venda. Uma decisão favorável que chega depois de lost devolve o dinheiro do mesmo jeito. Existem quatro 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 quando o chargeback é confirmado, cerca de 8 dias depois da abertura, 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 chargeback seja confirmado no meio do caminho — por no máximo 130 dias contados do envio da defesa. Só a decisão favorável chega com aviso; a desfavorável não chega. Passados os 130 dias sem decisão favorável e com o valor contestado ainda debitado, o dispute é encerrado como lost e você recebe charge.dispute.closed.

Data Object

Este é o formato completo retornado em get, itens de list, update, close e em data.object dos webhooks charge.dispute.*.
string
Identificador do dispute. Usa o prefixo dp_*.
string
Sempre "dispute".
integer
Valor contestado, na menor unidade da moeda (centavos em brl).
string
ID da charge contestada (ch_*).
string
Moeda de amount, a mesma da charge contestada. Código ISO 4217 em minúsculas, como brl.
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.
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.
boolean
Indica se a charge ainda pode receber refund. É false enquanto a disputa espera resposta (needs_response) ou está em análise (under_review) e depois de perdida (lost): nessas fases o valor contestado está retido ou já voltou ao comprador pela disputa, e POST /v1/refunds responde 409 com code: "charge_disputed". É true na consulta prévia (warning_*) e depois de ganha (won).
object
Pares chave-valor livres. Quando vazio, retorna {}.
string | null
Motivo normalizado quando disponível.
array of objects
Os movimentos de dinheiro da disputa no seu extrato, do mais antigo ao mais novo, no mesmo formato de Transações: a saída quando a disputa abre (amount negativo, description: "Dispute") e a devolução quando ela é ganha (amount positivo, description: "Dispute reversal"). É uma lista vazia no alerta prévio (warning_*), que não move dinheiro, e quando a venda já tinha sido reembolsada antes da disputa.
string
Estado do dispute.