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
- O caso começa em
needs_responseou, quando chega como alerta antecipado, emwarning_needs_response. Nesse momento, a organização precisa decidir se vai enviar defesa. - Enquanto o caso espera resposta,
evidence_details.due_byindica 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 deevidence(arquivos e textos) quantas vezes precisar; depois do prazo, essas ações são recusadas. - 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 eevidencenão aceita mais alteração. - O desfecho muda o
statusparawonquando a disputa é decidida a favor da sua organização, ou paralostquando é decidida contra. woné final.lostsó muda se uma decisão favorável chegar depois do encerramento: aí o dispute passa awone você recebecharge.dispute.closedde novo.
Dinheiro da disputa
Quando a disputa abre, o valor da venda sai do seu saldo num movimento próprio do extrato, e você recebecharge.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 emget, itens de list, update,
close e em data.object dos webhooks charge.dispute.*.
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.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.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).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.
