Zahlungsausfälle handhaben

Wenn eine Zahlung fehlschlägt, stellt Dodo Payments einen standardisierten error_code und eine verständliche error_message bereit. Dieser Leitfaden zeigt, wie Sie diese Felder lesen, entscheiden, ob ein erneuter Versuch sinnvoll ist, und die Zahlung sicher wiederherstellen.

Wie Dodo Payments einen Ausfall meldet

Jede fehlgeschlagene Zahlung enthält diese Felder im Zahlungsobjekt:

Feld	Typ	Beschreibung
`status`	string	`failed` für eine fehlgeschlagene Zahlung. Andere Status, die keinen Erfolg anzeigen: `cancelled`, `requires_customer_action`, `requires_payment_method`.
`error_code`	string \| null	Standardisierte Fehlerursache, z. B. `INSUFFICIENT_FUNDS` oder `PROCESSING_ERROR`. Die vollständige Liste finden Sie unter Transaktionsfehler.
`error_message`	string \| null	Händlerseitige Erklärung mit empfohlener Maßnahme. Nicht für Kunden bestimmt.
`retry_attempt`	integer	`0` für die ursprüngliche Belastung. `1` oder höher für geplante Wiederholungsversuche bei der Abonnementverlängerung.

error_code und error_message sind null, bis eine Zahlung fehlschlägt. Prüfen Sie immer zuerst status.

error_message ist für Händler bestimmt und kann betrugsbezogene Gründe offenlegen. Zeigen Sie diesen Wert niemals Kunden. Ordnen Sie error_code stattdessen einer kundenfreundlichen Formulierung zu (siehe Fehler sicher gegenüber Kunden anzeigen).

Der `payment.failed` Webhook

Der payment.failed-Webhook ist die zuverlässigste Methode, einen Fehler zu erkennen. 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 minimalistischer Handler liest error_code und leitet anhand dieses Werts weiter:

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 payment. If Payment Retries is on, Dodo retries failed renewals.
      // On-demand charges are never retried automatically: handle those yourself.
      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 payment. If Payment Retries is on, Dodo retries failed renewals.
            # On-demand charges are never retried automatically: handle those yourself.
            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.

Ablehnungstyp	Beispiele	Maßnahme
Weiche Ablehnung	`INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`	Nach einer Verzögerung oder sobald der Kunde seine Eingaben korrigiert hat, erneut versuchen.
Harte Ablehnung	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`	Nicht erneut dieselbe Karte verwenden. Den Kunden um eine andere Zahlungsmethode bitten.

Die vollständige Liste der Ablehnungstypen und empfohlenen Maßnahmen finden Sie unter Transaktionsfehler.

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 befindet sich gerade im Checkout. Zeigen Sie eine klare Nachricht an und ermöglichen Sie ihm, es erneut zu versuchen oder eine andere Karte zu verwenden.

requires_payment_method — der Kunde hat keine Zahlungsmethode angegeben. Dies ist in der Regel ein Abbruch während des Checkouts 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.

Der Kunde ist nicht anwesend. Wenn eine Verlängerung fehlschlägt, wechselt das Abonnement zu on_hold und subscription.on_hold wird ausgelöst. Wenn Ihr Unternehmen eine Kulanzfrist vorsieht, wechselt es zunächst zu past_due (subscription.past_due) und behält den Zugriff bis zum Ende der Kulanzfrist bei.

Weiche Ablehnungen werden automatisch erneut versucht, wenn Sie Wiederholungsversuche für Abonnementzahlungen aktivieren (standardmäßig deaktiviert). Wiederholungsversuche gelten nur für geplante Verlängerungen, nicht für bedarfsgesteuerte Belastungen.
Harte Ablehnungen (und erschöpfte Wiederholungsversuche) bei geplanten Verlängerungen werden mit Subscription Dunning wiederhergestellt. Dabei wird dem Kunden eine E-Mail gesendet, in der er zur Aktualisierung seiner Zahlungsmethode aufgefordert wird. Informationen zu fehlgeschlagenen bedarfsgesteuerten Belastungen finden Sie unter On-Demand Subscriptions.

Den vollständigen Ablauf von „On Hold“ bis zur Reaktivierung finden Sie im Leitfaden zur Abonnementintegration.

Erneuter Versuch einer fehlgeschlagenen Zahlung

Abonnements: Aktivieren Sie Wiederholungsversuche für Abonnementzahlungen, um weiche Ablehnungen automatisch wiederherzustellen. Wenn Sie sofort statt nach dem Zeitplan einen erneuten Versuch durchführen möchten, verwenden Sie Manueller Zahlungswiederholungsversuch im Dashboard oder in der API. Sie können die Wiederherstellung auch auslösen, indem Sie den Kunden seine Zahlungsmethode über die API zum Aktualisieren der Zahlungsmethode aktualisieren lassen. Dabei werden alle ausstehenden Beträge belastet. Einmalzahlungen: Senden Sie den Checkout oder payment_link erneut, damit der Kunde es mit einer anderen Methode versuchen kann. Für Einmalzahlungen gibt es keine automatischen Wiederholungsversuche.

Versuchen Sie nicht, harte Ablehnungen erneut mit derselben Karte durchzuführen. Kartennetzwerke kennzeichnen wiederholte Ablehnungen als missbräuchlich, was Ihre Autorisierungsrate beeinträchtigt.

Fehler sicher gegenüber Kunden anzeigen

Zeigen Sie Kunden eine freundliche Nachricht an, niemals den rohen error_code oder den händlerseitigen error_message.

Auf von Dodo Payments kontrollierten Oberflächen (Checkout, Customer Portal, Dunning-E-Mails) wird diese Zuordnung bereits für Sie vorgenommen, einschließlich eines Fallbacks auf eine allgemeine Nachricht bei betrugsbezogenen Ablehnungen. Die folgende Zuordnung benötigen Sie 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. Dadurch könnten Sie einen Betrüger auf die richtige Spur bringen. Zeigen Sie eine allgemeine Ablehnungsnachricht an und protokollieren Sie den spezifischen error_code ausschließlich intern.

Transaction Failures

Jeder Ablehnungscode, sein Typ und die empfohlene Maßnahme.

Error Codes

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

Subscription Payment Retries

Automatische Wiederherstellung weicher Ablehnungen bei Abonnementverlängerungen.

Subscription Dunning

E-Mail-Sequenzen zur Wiederherstellung harter Ablehnungen.

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 gegenüber 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 gegenüber 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 gegenüber Kunden anzeigen

Verwandte Themen