Zahlungsausfälle handhaben

Wenn eine Zahlung fehlschlägt, teilt Ihnen Dodo Payments warum mit durch einen standardisierten error_code und eine lesbare error_message. Dieser Leitfaden zeigt, wie diese Felder gelesen werden, entschieden wird, ob ein neuer Versuch sinnvoll ist, und wie die Zahlung wiederhergestellt wird, ohne sensible Informationen an Kunden weiterzugeben.

Wie Dodo Payments einen Ausfall meldet

Jede fehlgeschlagene Zahlung – sei es ein einmaliger Kauf oder eine Abonnementverlängerung – enthält dieselben Fehlerfelder im Zahlungsobjekt:

Field	Type	Description
`status`	string	`failed` für eine fehlgeschlagene Zahlung. Andere nicht erfolgreiche Zustände sind `cancelled`, `requires_customer_action` und `requires_payment_method`.
`error_code`	string \| null	Der standardisierte Fehlergrund, zum Beispiel `INSUFFICIENT_FUNDS` oder `PROCESSING_ERROR`. Die vollständige Liste finden Sie in der Referenz Transaction Failures.
`error_message`	string \| null	Eine für Menschen lesbare Erklärung des Fehlers, die für Sie und nicht für Ihre Kunden verfasst ist. Bei einem standardisierten `error_code` handelt es sich um eine Überschrift plus die empfohlene Aktion, nicht um den Rohtext des Prozessors.
`retry_attempt`	integer	`0` für die ursprüngliche Belastung. `1` oder höher kennzeichnet einen geplanten Wiederholungsversuch bei einer Verlängerung des Abonnements.

error_code und error_message sind null, bis eine Zahlung tatsächlich fehlschlägt. Überprüfen Sie zuerst status, und dann lesen Sie die Fehlerfelder.

error_message aus der Merchant API ist ein für Händler bestimmter Text. Er kann den tatsächlichen Grund für eine Ablehnung nennen, einschließlich betrugsbezogener Gründe. Zeigen Sie ihn daher niemals direkt einem Kunden an. Ordnen Sie error_code stattdessen Ihren eigenen kundenfreundlichen Formulierungen zu, wie unter Fehler sicher für Kunden anzeigen gezeigt.

Der `payment.failed` Webhook

Die zuverlässigste Methode, einen Fehler zu erkennen, ist der payment.failed Webhook. Das Ereignis enthält das vollständige Zahlungsobjekt in data:

payment.failed payload

{
  "business_id": "bus_P3SXLcppjXgagmHS",
  "type": "payment.failed",
  "timestamp": "2025-08-04T05:36:41.609359Z",
  "data": {
    "payload_type": "Payment",
    "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
    "status": "failed",
    "error_code": "PROCESSING_ERROR",
    "error_message": "An error occurred while processing your card. Try again in a little bit.",
    "retry_attempt": 0,
    "subscription_id": null,
    "currency": "USD",
    "total_amount": 400,
    "payment_method": "card",
    "card_last_four": "0119",
    "card_network": "VISA",
    "payment_link": "https://test.checkout.dodopayments.com/cbq",
    "customer": {
      "customer_id": "cus_8VbC6JDZzPEqfB",
      "email": "test@acme.com",
      "name": "Test user"
    }
  }
}

Ein minimaler Handler liest error_code aus und führt anhand dieses Werts eine Weiterleitung durch:

import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
// Mount the raw body parser so the exact payload is available for verification
app.use(express.raw({ type: "application/json" }));

const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY);

app.post("/webhooks/dodo", async (req, res) => {
  // Verify the signature against the raw body before trusting the payload
  const payload = req.body.toString();
  await webhook.verify(payload, req.headers);

  const event = JSON.parse(payload);

  if (event.type === "payment.failed") {
    const payment = event.data;

    console.log(
      `Payment ${payment.payment_id} failed: ${payment.error_code} (${payment.error_message})`
    );

    if (payment.subscription_id) {
      // Subscription renewal — Dodo retries soft declines for you
      await flagSubscriptionPaymentIssue(payment.subscription_id, payment.error_code);
    } else {
      // One-time payment — prompt the customer to try again
      await notifyCustomerOfFailedPayment(payment.customer.customer_id, payment.error_code);
    }
  }

  res.json({ received: true });
});

import os
from fastapi import FastAPI, Request
from standardwebhooks import Webhook

app = FastAPI()
webhook = Webhook(os.environ["DODO_PAYMENTS_WEBHOOK_KEY"])

@app.post("/webhooks/dodo")
async def handle_webhook(request: Request):
    # Verify the signature before trusting the payload
    payload = await request.body()
    webhook.verify(payload, dict(request.headers))

    event = await request.json()

    if event["type"] == "payment.failed":
        payment = event["data"]

        print(
            f"Payment {payment['payment_id']} failed: "
            f"{payment['error_code']} ({payment['error_message']})"
        )

        if payment["subscription_id"]:
            # Subscription renewal — Dodo retries soft declines for you
            flag_subscription_payment_issue(payment["subscription_id"], payment["error_code"])
        else:
            # One-time payment — prompt the customer to try again
            notify_customer_of_failed_payment(payment["customer"]["customer_id"], payment["error_code"])

    return {"received": True}

Überprüfen Sie immer die Webhook-Signatur, bevor Sie den Webhook verarbeiten. Im Webhooks-Leitfaden finden Sie die vollständige Einrichtung einschließlich Signaturüberprüfung und Idempotenz.

Entscheiden, ob ein Wiederholungsversuch sinnvoll ist: Soft- und Hard-Declines

error_code zeigt an, ob sich ein erneuter Versuch mit derselben Zahlungsmethode lohnt.

Decline type	What it means	What to do
Soft decline	Vorübergehend oder korrigierbar (zum Beispiel `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`).	Ein erneuter Versuch – nach einer Verzögerung oder sobald der Kunde seine Eingaben korrigiert hat – kann erfolgreich sein.
Hard decline	Endgültig (zum Beispiel `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).	Versuchen Sie es nicht erneut mit derselben Karte. Bitten Sie den Kunden um eine andere Zahlungsmethode.

Die Referenz Transaction Failures enthält für jedes error_code den Typ der Ablehnung und die empfohlene Aktion.

Fehlerbehandlung beim Checkout und bei Verlängerungen

Wie Sie den Fehler beheben, hängt davon ab, ob der Kunde anwesend ist.

At checkout (customer present)
On subscription renewal (customer not present)

Der Kunde führt gerade den Checkout durch. Zeigen Sie eine klare Meldung an und ermöglichen Sie ihm, es sofort erneut zu versuchen oder eine andere Karte zu verwenden.

requires_payment_method – der Kunde hat nie eine Zahlungsmethode angegeben: Er hat keine Kartendaten eingegeben oder wurde dazu aufgefordert und hat keine Aktion ausgeführt. Dies ist normalerweise ein Abbruch beim Checkout und keine Ablehnung – sprechen Sie den Kunden erneut an, damit er die Zahlung abschließt (siehe Wiederherstellung abgebrochener Warenkörbe).
requires_customer_action – eine zusätzliche Authentifizierung (z. B. 3DS) ist erforderlich. Lassen Sie den Kunden diese abschließen. Siehe 3D-Secure-Verarbeitung.

Der Kunde ist nicht anwesend, daher können Sie ihn nicht in Echtzeit auffordern. Wenn eine Verlängerung fehlschlägt, wechselt das Abonnement zu on_hold und subscription.on_hold wird ausgelöst.

Soft declines werden automatisch von Subscription Payment Retries erneut versucht.
Hard declines (sowie ausgeschöpfte Wiederholungsversuche) lassen sich am besten mit Subscription Dunning beheben. Dabei wird dem Kunden eine E-Mail gesendet, damit er seine Zahlungsmethode aktualisiert.

Den vollständigen Ablauf für „On hold“ → Reaktivierung finden Sie im Leitfaden zur Subscription-Integration.

Erneuter Versuch einer fehlgeschlagenen Zahlung

Abonnements: Aktivieren Sie Subscription Payment Retries, um Soft declines ohne Integrationsaufwand zu beheben. Sie können die Wiederherstellung auch auslösen, indem der Kunde seine Zahlungsmethode über die Update Payment Method API aktualisiert, wodurch alle ausstehenden Beträge belastet werden.
Einmalige Zahlungen: Senden Sie den Checkout oder payment_link erneut, damit der Kunde es mit einer anderen Zahlungsmethode versuchen kann. Für einmalige Zahlungen gibt es keinen automatischen Wiederholungsversuch.

Versuchen Sie Hard declines nicht erneut mit derselben Karte. Kartennetzwerke können wiederholte Ablehnungen als Missbrauch einstufen, was Ihre Autorisierungsrate beeinträchtigt.

Fehler sicher für Kunden anzeigen

Zeigen Sie Kunden eine freundliche Meldung an – niemals den rohen error_code und niemals den für Händler bestimmten error_message.

Auf von Dodo Payments kontrollierten Oberflächen – Checkout, dem Customer Portal und Dunning-E-Mails – ist diese Zuordnung bereits für Sie eingerichtet, einschließlich des Fallbacks auf eine allgemeine Meldung bei betrugsbezogenen Ablehnungen. Sie benötigen die folgende Zuordnung nur, wenn Sie Fehler in Ihrem eigenen Produkt anzeigen.

Customer-facing messaging

const CUSTOMER_MESSAGES = {
  INSUFFICIENT_FUNDS: "Your card has insufficient funds. Please use another card.",
  EXPIRED_CARD: "Your card has expired. Please use a card with a valid expiry date.",
  INCORRECT_CVC: "The security code (CVC) is incorrect. Please re-enter it.",
};

function customerMessage(errorCode) {
  // Sensitive declines must never reveal the real reason
  const SENSITIVE = ["STOLEN_CARD", "LOST_CARD", "PICKUP_CARD", "FRAUDULENT"];
  if (SENSITIVE.includes(errorCode)) {
    return "Your card was declined. Please contact your bank or use another card.";
  }
  return CUSTOMER_MESSAGES[errorCode] ?? "Your payment could not be processed. Please try another card.";
}

Geben Sie niemals den tatsächlichen Grund für STOLEN_CARD, LOST_CARD, PICKUP_CARD oder FRAUDULENT preis. Die Anzeige dieser Gründe kann einen Betrüger warnen. Zeigen Sie eine allgemeine Ablehnungsmeldung an und protokollieren Sie den spezifischen error_code nur intern.

Transaction Failures

Jeder Ablehnungscode, sein Typ und die empfohlene Aktion.

Error Codes

API- und Geschäftslogikfehler, bei denen es sich nicht um Kartenablehnungen handelt.

Subscription Payment Retries

Automatische Behebung von Soft declines bei Verlängerungen von Abonnements.

Subscription Dunning

E-Mail-Sequenzen zur Behebung von Hard declines.

Payment Webhooks

Vollständiges Payload-Schema für Zahlungsereignisse.

Testing Failures

Testkarten, die Ablehnungen und Fehler bei Verlängerungen simulieren.

Integration Guides

Billing Deconstructions

Cookbooks

Wie Dodo Payments einen Ausfall meldet

Der `payment.failed` Webhook

Entscheiden, ob ein Wiederholungsversuch sinnvoll ist: Soft- und Hard-Declines

Fehlerbehandlung beim Checkout und bei Verlängerungen

Erneuter Versuch einer fehlgeschlagenen Zahlung

Fehler sicher für Kunden anzeigen

Verwandte Themen

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Wie Dodo Payments einen Ausfall meldet

​Der payment.failed Webhook

​Entscheiden, ob ein Wiederholungsversuch sinnvoll ist: Soft- und Hard-Declines

​Fehlerbehandlung beim Checkout und bei Verlängerungen

​Erneuter Versuch einer fehlgeschlagenen Zahlung

​Fehler sicher für Kunden anzeigen

​Verwandte Themen

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Wie Dodo Payments einen Ausfall meldet

Der `payment.failed` Webhook

Entscheiden, ob ein Wiederholungsversuch sinnvoll ist: Soft- und Hard-Declines

Fehlerbehandlung beim Checkout und bei Verlängerungen

Erneuter Versuch einer fehlgeschlagenen Zahlung

Fehler sicher für Kunden anzeigen

Verwandte Themen