Streitfall

Die Nutzlast, die an Ihren Webhook-Endpunkt gesendet wird, wenn ein Streitfall erstellt oder aktualisiert wird und wie man mit jedem Ereignis im Lebenszyklus eines Streitfalls umgeht.

Als Ihr Merchant of Record verwaltet Dodo Payments den Streit- und Rückbuchungsprozess mit den Kartennetzwerken in Ihrem Namen. Diese Webhooks halten Ihre Systeme synchron, während ein Streitfall seinen Lebenszyklus durchläuft, sodass Sie den Zugriff widerrufen, Beweise sammeln und Ihre Unterlagen abgleichen können.

​

Streitfall-Webhook-Ereignisse

Ein Streitfall löst in jeder Phase seines Lebenszyklus ein Ereignis aus:

Ereignis	Wird ausgelöst, wenn	Was es normalerweise bedeutet
dispute.opened	Ein Karteninhaber eröffnet einen Streitfall über eine Zahlung	Gelder werden zurückgehalten; Vorbereitung zur Antwort
dispute.challenged	Beweise wurden eingereicht, um den Streitfall anzufechten	Der Streitfall wird vom Netzwerk überprüft
dispute.accepted	Der Streitfall wurde akzeptiert (nicht angefochten)	Die Gelder werden dem Karteninhaber zurückgegeben
dispute.cancelled	Der Streitfall wurde zurückgezogen oder storniert	Keine weiteren Maßnahmen erforderlich
dispute.expired	Die Antwortfrist verstrich ohne Lösung	Typischerweise gegen Sie entschieden
dispute.won	Der Streitfall wurde zu Ihren Gunsten gelöst	Gelder werden einbehalten
dispute.lost	Der Streitfall wurde zugunsten des Karteninhabers gelöst	Gelder werden dem Karteninhaber zurückgegeben

Streitfälle, die automatisch über Visa Rapid Dispute Resolution (RDR) gelöst werden, erscheinen als dispute.lost mit is_resolved_by_rdr: true. Dies ist zu erwarten — die Rückerstattung wurde automatisch ausgestellt, um eine formelle Rückbuchung zu vermeiden.

​

Umgang mit Streitfallereignissen

Wenn dispute.opened ausgelöst wird, wird der umstrittene Betrag sofort gehalten. Verwenden Sie das Ereignis, um Ihre Aufzeichnungen zu aktualisieren, und wenn Sie es anfechten möchten, sammeln Sie Beweise im 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 });
});

Verifizieren Sie immer die Webhook-Signatur, bevor Sie fortfahren — siehe den Webhooks-Leitfaden für die Einrichtung. Der obige Handler lässt die Verifizierung der Kürze halber weg.

Sie haben 4 Tage Zeit, um auf einen Streitfall zu reagieren, nachdem er erstellt wurde. Siehe Best Practices für die Streitfallantwort für die zu sammelnden Beweise und deren Formatierung.

​

Streitfallstatus und -phase

Das Streitfallobjekt meldet seinen Fortschritt über zwei Felder:

Feld	Werte
dispute_status	dispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lost
dispute_stage	pre_dispute, dispute, pre_arbitration

​

Verwandte Themen

Managing Disputes

Wie man auf Streitfälle reagiert, Beweise einreicht und wie RDR Ihre Streitfallrate schützt.

Handle Payment Failures

Erkennen und Wiederherstellen fehlgeschlagener Zahlungen, bevor sie zu Streitfällen werden.

​

Webhook-Nutzlastschema

amount · string · erforderlich

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

business_id · string · erforderlich

The unique identifier of the business involved in the dispute.

created_at · string<date-time> · erforderlich

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

currency · string · erforderlich

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

dispute_id · string · erforderlich

The unique identifier of the dispute.

dispute_stage · enum<string> · erforderlich

The current stage of the dispute process.

Verfügbare Optionen: pre_dispute, dispute, pre_arbitration

dispute_status · enum<string> · erforderlich

The current status of the dispute.

Verfügbare Optionen: dispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lost

payment_id · string · erforderlich

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