Pular para o conteúdo principal
Como seu Merchant of Record, a Dodo Payments gerencia o processo de disputa e chargeback com as redes de cartões em seu nome. Esses webhooks mantêm seus sistemas sincronizados à medida que uma disputa avança em seu ciclo de vida para que você possa revogar acesso, reunir evidências e reconciliar seus registros.

Eventos de Webhook de Disputa

Uma disputa emite um evento em cada estágio do seu ciclo de vida:
EventoDispara quandoO que geralmente significa
dispute.openedUm portador do cartão abre uma disputa em um pagamentoFundos são retidos; prepare-se para responder
dispute.challengedEvidências foram enviadas para contestar a disputaA disputa está sendo revisada pela rede
dispute.acceptedA disputa foi aceita (não contestada)Os fundos são devolvidos ao portador do cartão
dispute.cancelledA disputa foi retirada ou canceladaNenhuma ação adicional é necessária
dispute.expiredO prazo de resposta passou sem resoluçãoTipicamente resolve contra você
dispute.wonA disputa foi resolvida a seu favorFundos são retidos
dispute.lostA disputa foi resolvida a favor do portador do cartãoOs fundos são devolvidos ao portador do cartão
Disputas auto-resolvidas através do Visa Rapid Dispute Resolution (RDR) aparecem como dispute.lost com is_resolved_by_rdr: true. Isso é esperado — o reembolso foi emitido automaticamente para evitar um chargeback formal.

Tratamento de Eventos de Disputa

Quando dispute.opened dispara, o valor em disputa é retido imediatamente. Use o evento para atualizar seus registros e, se você pretende contestá-lo, reúna evidências no painel.
Handling dispute events
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'dispute.opened': {
      const dispute = event.data;
      // Record the dispute and consider revoking access while it is open
      await recordDispute(dispute.dispute_id, dispute.payment_id, dispute.amount);
      // Gather and submit evidence from the Dodo Payments dashboard (within 4 days)
      break;
    }
    case 'dispute.won': {
      // Funds retained — restore normal state in your records
      await markDisputeResolved(event.data.dispute_id, 'won');
      break;
    }
    case 'dispute.lost': {
      // Funds returned to the cardholder — reconcile and keep access revoked
      await markDisputeResolved(event.data.dispute_id, 'lost');
      break;
    }
  }

  res.json({ received: true });
});
Sempre verifique a assinatura do webhook antes de processar — consulte o guia de Webhooks para configuração. O manipulador acima omite a verificação para brevidade.
Você tem 4 dias para responder a uma disputa após ela ser criada. Veja Melhores Práticas de Resposta a Disputa para as evidências a serem reunidas e como formatá-las.

Status e Etapa da Disputa

O objeto disputa reporta seu progresso através de dois campos:
CampoValores
dispute_statusdispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lost
dispute_stagepre_dispute, dispute, pre_arbitration

Relacionado

Managing Disputes

Como responder a disputas, enviar evidências e como o RDR protege sua taxa de disputas.

Handle Payment Failures

Detectar e recuperar pagamentos falhos antes que se tornem disputas.

Esquema de Payload de Webhook

amount
string
obrigatório

The amount involved in the dispute, represented as a string to accommodate precision.

business_id
string
obrigatório

The unique identifier of the business involved in the dispute.

created_at
string<date-time>
obrigatório

The timestamp of when the dispute was created, in UTC.

currency
string
obrigatório

The currency of the disputed amount, represented as an ISO 4217 currency code.

dispute_id
string
obrigatório

The unique identifier of the dispute.

dispute_stage
enum<string>
obrigatório

The current stage of the dispute process.

Opções disponíveis:
pre_dispute,
dispute,
pre_arbitration
dispute_status
enum<string>
obrigatório

The current status of the dispute.

Opções disponíveis:
dispute_opened,
dispute_expired,
dispute_accepted,
dispute_cancelled,
dispute_challenged,
dispute_won,
dispute_lost
payment_id
string
obrigatório

The unique identifier of the payment associated with the dispute.

is_resolved_by_rdr
boolean | null

Whether the dispute was resolved by Rapid Dispute Resolution

remarks
string | null

Remarks

Última modificação em 18 de junho de 2026