Skip to main content

​
Übersicht

Wenn ein Zahlungsversuch fehlschlägt, gibt Dodo Payments einen standardisierten Fehlercode zurück, der den Grund angibt. Die Codes sind bei allen Zahlungsmethoden und Zahlungsabwicklern identisch, sodass ein einziger Satz von Verarbeitungsregeln für jede fehlgeschlagene Zahlung gilt. Der payment.failed-Webhook und das Zahlungsobjekt stellen für eine fehlgeschlagene Zahlung die folgenden Felder bereit:
  • error_code: ein standardisierter Fehlercode aus der folgenden Tabelle.
  • error_message: eine Erklärung für Sie, den Händler. Wenn error_code einem der folgenden standardisierten Codes entspricht, handelt es sich um eine Überschrift mit der empfohlenen Maßnahme und nicht um den unveränderten Text des Zahlungsabwicklers.
  • retry_attempt: 0 für die ursprüngliche Belastung und 1 oder höher für jeden geplanten Wiederholungsversuch einer Abonnementverlängerung. Zahlungen, die keine Abonnementverlängerungen sind, behalten den Wert 0.
Verwenden Sie diese Codes, um Kunden klares Feedback zu geben, zu entscheiden, ob ein Wiederholungsversuch erfolgreich sein kann, und mehr Umsatz zurückzugewinnen.

​
Händlertext vs. Kundentext

Jeder standardisierte Fehlercode ist zwei Nachrichten zugeordnet: eine für Sie und eine für Ihren Kunden:
Das Customer Portal gibt die Kundenformulierung in error_message zurück, während die Händler-API für dieselbe Zahlung die Händlerformulierung zurückgibt. error_code ist in beiden Fällen identisch.

Handle Payment Failures

Eine schrittweise Entwickleranleitung zum Auslesen dieser Codes aus Webhooks und der API, zu ihrer Anzeige für Kunden und zur Entscheidung, wann ein Wiederholungsversuch durchgeführt werden sollte.

​
Vorübergehende vs. endgültige Ablehnungen

Jeder Fehlercode ist entweder eine vorübergehende oder eine endgültige Ablehnung. Der Typ gibt an, ob ein späterer Versuch mit denselben Zahlungsdaten erfolgreich sein kann oder ob der Kunde zuerst handeln muss. Bei Abonnementverlängerungen nimmt Dodo Payments diese Einstufung automatisch vor. Subscription Payment Retries wiederholt Versuche bei vorübergehenden Ablehnungen. Eine endgültige Ablehnung beendet die Wiederholungskette sofort. Beheben Sie sie mit Subscription Dunning.
Geben Sie den tatsächlichen Grund für STOLEN_CARD, LOST_CARD, PICKUP_CARD oder FRAUDULENT niemals an den Kunden weiter. Die Offenlegung dieser Gründe kann einen betrügerischen Akteur warnen. Zeigen Sie dem Kunden eine allgemeine Ablehnungsnachricht (zum Beispiel “Ihre Karte wurde abgelehnt. Bitte kontaktieren Sie Ihre Bank oder verwenden Sie eine andere Karte.”) und protokollieren Sie den spezifischen Code nur intern.Dodo Payments wendet diese Regel auf den von Dodo Payments kontrollierten Oberflächen an. Bei diesen vier Codes zeigen der Checkout, das Customer Portal und Dunning-E-Mails eine allgemeine Ablehnungsnachricht, während Ihre Händlerformulierung den tatsächlichen Grund enthält. Wenden Sie dieselbe Regel überall dort an, wo Sie error_message aus der Händler-API einem Kunden anzeigen.

​
Gründe für fehlgeschlagene Transaktionen

Die folgende Tabelle enthält jeden Fehlercode mit seinem Ablehnungstyp, der Angabe, ob der Kunde das Problem beheben kann, einer Beschreibung und der empfohlenen Maßnahme.
Benutzerfehler zeigt an, ob der Kunde die Ablehnung beheben kann. Yes bedeutet, dass der Kunde das Problem beheben kann, zum Beispiel durch die Eingabe korrekter Kartendaten. No bedeutet, dass ein Problem auf Systemebene oder eine Einschränkung der Bank die Ablehnung verursacht hat und der Kunde sie nicht direkt beheben kann.
Eine kartenausgebende Bank kann eine Karte auch ablehnen, weil ihre eigene Risiko-Engine den Karteninhaber unabhängig vom Händler oder den Transaktionsdetails als hohes Risiko einstuft. Diese Ablehnungen erscheinen in der Regel als allgemeine Codes wie DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED oder FRAUDULENT. Die Bank teilt den konkreten Grund nicht mit, und weder Dodo Payments noch der Händler können diese Entscheidung außer Kraft setzen. Bitten Sie den Kunden, sich an seine Bank zu wenden, um die Sperre aufzuheben, oder eine andere Karte oder Zahlungsmethode zu verwenden.

​
Fehler programmgesteuert verarbeiten

Lesen Sie error_code aus dem payment.failed-Webhook oder dem Zahlungsobjekt aus, ordnen Sie ihn der empfohlenen Maßnahme in der Tabelle zu und entscheiden Sie, ob die Zahlung erneut versucht werden soll. Bei Abonnementverlängerungen wiederholt Dodo Payments vorübergehende Ablehnungen für Sie. Siehe Subscription Payment Retries. Informationen zu API- und Geschäftslogikfehlern, bei denen es sich nicht um Kartenablehnungen handelt, wie PAYMENT_NOT_SUCCEEDED oder REFUND_WINDOW_EXPIRED, finden Sie in der Referenz Error Codes.

​
Verwandte Themen

Handle Payment Failures

End-to-End-Anleitung zum Erkennen, Anzeigen und erneuten Ausführen fehlgeschlagener Zahlungen.

Error Codes

API- und Geschäftslogik-Fehlercodes für Fehler, die keine Ablehnungen sind.

Subscription Payment Retries

Automatische Wiederholungsversuche, die vorübergehende Ablehnungen bei Abonnementverlängerungen beheben.

Subscription Dunning

E-Mail-Sequenzen, die endgültige Ablehnungen durch Aufforderung zur Aktualisierung der Zahlungsmethode beheben.

​
Support

Wenn Sie weitere Hilfe bei fehlgeschlagenen Transaktionen oder Integrationsproblemen benötigen, wenden Sie sich unter support@dodopayments.com an das Supportteam.
Zuletzt geändert am 26. September 2026