Vai al contenuto principale
Come tuo Merchant of Record, Dodo Payments gestisce il processo di disputa e chargeback con i circuiti delle carte per tuo conto. Questi webhook mantengono i tuoi sistemi sincronizzati mentre una disputa attraversa il suo ciclo di vita in modo da poter revocare l’accesso, raccogliere prove e conciliare i tuoi registri.

Eventi Webhook di Disputa

Una disputa emette un evento in ogni fase del suo ciclo di vita:
EventoQuando si attivaCosa significa di solito
dispute.openedUn titolare di carta apre una disputa su un pagamentoI fondi sono bloccati; preparati a rispondere
dispute.challengedLe prove sono state presentate per contestare la disputaLa disputa è in revisione da parte del network
dispute.acceptedLa disputa è stata accettata (non contestata)I fondi vengono restituiti al titolare della carta
dispute.cancelledLa disputa è stata ritirata o annullataNessuna ulteriore azione necessaria
dispute.expiredLa finestra di risposta è scaduta senza risoluzioneTipicamente si risolve contro di te
dispute.wonLa disputa è stata risolta a tuo favoreI fondi vengono trattenuti
dispute.lostLa disputa è stata risolta a favore del titolare della cartaI fondi vengono restituiti al titolare della carta
Le dispute risolte automaticamente tramite Visa Rapid Dispute Resolution (RDR) appaiono come dispute.lost con is_resolved_by_rdr: true. Questo è previsto — il rimborso è stato emesso automaticamente per prevenire un chargeback formale.

Gestione degli Eventi di Disputa

Quando dispute.opened si attiva, l’importo contestato è immediatamente bloccato. Usa l’evento per aggiornare i tuoi registri e, se intendi contestarlo, raccogli le prove nel dashboard.
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 });
});
Verifica sempre la firma del webhook prima di elaborarlo — vedi la guida ai Webhook per la configurazione. Il gestore sopra omette la verifica per brevità.
Hai 4 giorni per rispondere a una disputa dopo che è stata creata. Vedi Migliori pratiche di risposta alla disputa per le prove da raccogliere e come formattarle.

Status e Fase della Disputa

L’oggetto della disputa riporta i suoi progressi attraverso due campi:
CampoValori
dispute_statusdispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lost
dispute_stagepre_dispute, dispute, pre_arbitration

Correlati

Managing Disputes

Come rispondere alle dispute, presentare prove e come RDR protegge il tuo tasso di dispute.

Handle Payment Failures

Rileva e recupera pagamenti falliti prima che diventino dispute.

Schema del Payload Webhook

amount
string
obbligatorio

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

business_id
string
obbligatorio

The unique identifier of the business involved in the dispute.

created_at
string<date-time>
obbligatorio

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

currency
string
obbligatorio

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

dispute_id
string
obbligatorio

The unique identifier of the dispute.

dispute_stage
enum<string>
obbligatorio

The current stage of the dispute process.

Opzioni disponibili:
pre_dispute,
dispute,
pre_arbitration
dispute_status
enum<string>
obbligatorio

The current status of the dispute.

Opzioni disponibili:
dispute_opened,
dispute_expired,
dispute_accepted,
dispute_cancelled,
dispute_challenged,
dispute_won,
dispute_lost
payment_id
string
obbligatorio

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

Ultima modifica il 18 giugno 2026