Transaktionsfehler

Übersicht

Dodo Payments gibt einen detaillierten Ausfallgrund zurück, wenn ein Zahlungsversuch nicht erfolgreich ist. Diese Gründe sind über Zahlungsmethoden und Anbieter hinweg standardisiert, sodass Sie in Ihrer Anwendung einheitliche Handhabung implementieren können. Wenn eine Zahlung fehlschlägt, zeigen der payment.failed-Webhook und das Zahlungsobjekt:

error_code — ein standardisierter Fehlergrund aus der nachstehenden Tabelle.
error_message — eine für Sie, den Händler, verfasste, allgemein verständliche Erklärung. Wenn error_code einem der unten aufgeführten standardisierten Codes entspricht, handelt es sich um eine Überschrift mit der empfohlenen Maßnahme und nicht um den Originaltext des Zahlungsdienstleisters.
retry_attempt — 0 für die ursprüngliche Belastung, 1 oder höher für jeden geplanten Wiederholungsversuch einer Abonnementverlängerung.

Das Verständnis dieser Ausfallgründe ermöglicht es Ihnen, den Kunden klares Feedback zu geben, zu entscheiden, ob ein erneuter Versuch lohnenswert ist, und mehr Einnahmen zu generieren.

Händlertext vs. Kundentext

Jeder standardisierte Fehlercode ist zwei unterschiedlichen Nachrichten zugeordnet, damit die richtige Zielgruppe die passende Detailstufe sieht:

Zielgruppe	Wo er erscheint	Was er aussagt
Sie	`error_message` bei der Zahlung, auf der Seite mit den Zahlungsdetails im Dashboard und in der E-Mail an den Händler über eine fehlgeschlagene Zahlung	Der tatsächliche Grund plus eine empfohlene Maßnahme, zum Beispiel “Die Karte wurde vom Karteninhaber noch nicht aktiviert. Bitten Sie den Kunden, sie bei seiner Bank zu aktivieren, und versuchen Sie es anschließend erneut.”
Ihr Kunde	Auf dem Bildschirm für fehlgeschlagene Zahlungen im Checkout, im Customer Portal und in Dunning-E-Mails	Eine kurze, leicht verständliche Erklärung, mit der der Kunde handeln kann, zum Beispiel “Ihre Karte wurde noch nicht aktiviert. Bitte aktivieren Sie sie bei Ihrer Bank und versuchen Sie es erneut.”

Das Customer Portal gibt den kundenorientierten Wortlaut in error_message zurück, während die Händler-API für dieselbe Zahlung den Händlerwortlaut zurückgibt. error_code ist in beiden Fällen identisch.

Handle Payment Failures

Eine schrittweise Anleitung für Entwickler zum Auslesen dieser Codes aus Webhooks und der API, zu ihrer Anzeige für Kunden und zur Entscheidung, wann ein erneuter Versuch unternommen werden sollte.

Vorübergehende vs. endgültige Ablehnungen

Jeder Fehlercode fällt in eine von zwei Kategorien. Diese Unterscheidung bestimmt, ob Sie dieselbe Zahlungsmethode erneut versuchen oder den Kunden um eine neue bitten sollten.

Ablehnungstyp	Bedeutung	Maßnahme	Beispiele
Vorübergehende Ablehnung	Vorübergehend oder korrigierbar — dieselbe Karte kann bei einem späteren Versuch oder nach einer Korrektur durch den Kunden erfolgreich sein.	Ein erneuter Versuch ist unbedenklich (nach einer Verzögerung oder sobald der Kunde seine Angaben korrigiert hat).	`INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER`
Endgültige Ablehnung	Endgültig — ein erneuter Versuch mit derselben Karte wird das Ergebnis nicht ändern.	Versuchen Sie es nicht erneut mit derselben Karte. Bitten Sie den Kunden, eine andere Zahlungsmethode zu verwenden oder seine Bank zu kontaktieren.	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`

Bei Abonnementverlängerungen wendet Dodo Payments diese Unterscheidung automatisch an: Vorübergehende Ablehnungen werden von Subscription Payment Retries erneut versucht, während endgültige Ablehnungen die Versuchskette sofort beenden und am besten mit Subscription Dunning behandelt werden.

Legen Sie den tatsächlichen Grund für STOLEN_CARD, LOST_CARD, PICKUP_CARD oder FRAUDULENT niemals gegenüber dem Kunden offen. Die Anzeige dieser Informationen kann einen Betrüger warnen. Zeigen Sie dem Kunden immer 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 setzt diese Regel bereits auf den von Dodo Payments kontrollierten Oberflächen durch: Bei diesen vier Codes greifen Checkout, das Customer Portal und Dunning-E-Mails immer auf eine allgemeine Ablehnungsnachricht zurück, während Ihr eigener Text den tatsächlichen Grund beibehält. Wenden Sie dieselbe Regel überall dort an, wo Sie error_message aus der Händler-API für einen Kunden anzeigen.

Gründe für fehlgeschlagene Transaktionen

Die folgende Tabelle enthält jeden Fehlercode, seinen Ablehnungstyp, die Information, ob der Kunde das Problem beheben kann, eine Beschreibung und die empfohlene Maßnahme.

Fehlercode	Typ	Benutzerfehler	Beschreibung	Empfohlene Maßnahme
`AUTHENTICATION_FAILURE`	Soft	Ja	Die Authentifizierung während der Transaktion ist fehlgeschlagen	Bitten Sie den Kunden, es erneut zu versuchen und die 3DS-Authentifizierung abzuschließen oder eine andere Karte zu verwenden
`AUTHENTICATION_REQUIRED`	Soft	Ja	Für den Abschluss der Transaktion ist eine zusätzliche Authentifizierung erforderlich	Fordern Sie den Kunden auf, die 3DS-Authentifizierung abzuschließen. Bitten Sie den Kunden bei Abonnementverlängerungen, zurückzukehren und sich zu authentifizieren
`AUTHENTICATION_TIMEOUT`	Soft	Ja	Der Authentifizierungsvorgang ist abgelaufen	Bitten Sie den Kunden, es erneut zu versuchen und die Authentifizierung unverzüglich abzuschließen
`CARD_DECLINED`	Soft	Nein	Die Karte wurde von der ausstellenden Bank ohne konkreten Grund abgelehnt (allgemeine Ablehnung)	Bitten Sie den Kunden, es erneut zu versuchen, seine Bank zu kontaktieren oder eine andere Karte zu verwenden
`CARD_NOT_ACTIVATED`	Soft	Ja	Die Karte wurde vom Karteninhaber noch nicht aktiviert	Bitten Sie den Kunden, die Karte bei seiner Bank zu aktivieren und es anschließend erneut zu versuchen
`CARD_VELOCITY_EXCEEDED`	Soft	Ja	In kurzer Zeit wurden zu viele Transaktionen versucht	Bitten Sie den Kunden, zu warten und es später erneut zu versuchen oder sich wegen der Limits an seine Bank zu wenden
`CUSTOMER_CANCELLED`	Soft	Ja	Der Kunde hat die Transaktion abgebrochen	Lassen Sie den Kunden den Checkout neu starten, sobald er bereit ist
`DO_NOT_HONOR`	Hard	Nein	Die ausstellende Bank hat die Transaktion ausdrücklich abgelehnt (ISO 8583-Code 05 — nicht akzeptieren); Netzwerke behandeln dies als endgültig	Bitten Sie den Kunden, seine Bank zu kontaktieren; versuchen Sie es nicht erneut mit derselben Karte
`EXPIRED_CARD`	Hard	Ja	Die Karte ist abgelaufen	Bitten Sie den Kunden, eine Karte mit gültigem Ablaufdatum zu verwenden
`FRAUDULENT`	Hard	Ja	Die Transaktion wurde als potenziell betrügerisch eingestuft	Zeigen Sie dem Kunden eine allgemeine Ablehnungsnachricht — geben Sie den Grund nicht bekannt. Bitten Sie ihn, eine andere Karte zu verwenden
`GENERIC_DECLINE`	Soft	Nein	Die Transaktion wurde aus einem nicht näher bezeichneten Grund abgelehnt	Bitten Sie den Kunden, seine Bank zu kontaktieren oder eine andere Karte zu versuchen
`INCORRECT_CVC`	Soft	Ja	Der angegebene CVC-Code war falsch	Bitten Sie den Kunden, den korrekten CVC erneut einzugeben
`INCORRECT_NUMBER`	Soft	Ja	Die Kartennummer wurde falsch eingegeben	Bitten Sie den Kunden, die korrekte Kartennummer erneut einzugeben
`INSUFFICIENT_FUNDS`	Soft	Ja	Das Konto verfügt nicht über ausreichendes Guthaben für die Transaktion	Bitten Sie den Kunden, eine andere Zahlungsmethode zu verwenden oder es erneut zu versuchen, sobald Guthaben verfügbar ist
`INVALID_ACCOUNT`	Hard	Ja	Die angegebenen Kontodaten sind ungültig	Bitten Sie den Kunden, seine Bank zu kontaktieren oder eine andere Karte zu verwenden
`INVALID_AMOUNT`	Soft	Ja	Der Transaktionsbetrag ist ungültig	Überprüfen Sie den Betrag und etwaige Kauflimits mit dem Kunden
`INVALID_CARD_NUMBER`	Soft	Ja	Das Format der Kartennummer ist ungültig	Bitten Sie den Kunden, eine gültige Kartennummer erneut einzugeben
`INVALID_CARD_OWNER`	Soft	Ja	Die Angaben zum Karteninhaber sind ungültig	Bitten Sie den Kunden, den Namen des Karteninhabers zu korrigieren
`INVALID_CVC`	Soft	Ja	Das CVC-Format ist ungültig	Bitten Sie den Kunden, einen gültigen CVC erneut einzugeben
`INVALID_EXPIRY_YEAR`	Soft	Ja	Das Ablaufjahr der Karte ist ungültig	Bitten Sie den Kunden, ein gültiges Ablaufdatum einzugeben
`INVALID_PIN`	Soft	Ja	Die angegebene PIN ist falsch	Bitten Sie den Kunden, die korrekte PIN erneut einzugeben
`INVALID_REQUEST`	Soft	Ja	Die Transaktionsanfrage enthält ungültige Daten	Überprüfen Sie die Felder der Zahlungsanfrage und senden Sie sie mit gültigen Daten erneut
`INVALID_UPI_ID`	Soft	Ja	Die angegebene UPI ID ist ungültig	Bitten Sie den Kunden, eine gültige UPI ID einzugeben
`LIMIT_EXCEEDED`	Soft	Ja	Die Transaktion überschreitet das Karten- oder Kontolimit	Bitten Sie den Kunden, sich wegen der Limits an seine Bank zu wenden oder eine andere Methode zu verwenden
`LIVE_MODE_TEST_CARD`	Hard	Ja	Im Live-Modus wurde eine Testkarte verwendet	Verwenden Sie eine echte Karte — ein erneuter Versuch mit der Testkarte wird im Live-Modus immer fehlschlagen
`LOST_CARD`	Hard	Ja	Die Karte wurde als verloren gemeldet	Zeigen Sie dem Kunden eine allgemeine Ablehnungsnachricht — geben Sie den Grund nicht bekannt. Bitten Sie ihn, eine andere Karte zu verwenden
`MANDATE_INVALID`	Soft	Ja	Das Zahlungsmandat ist ungültig	Bitten Sie den Kunden, das Zahlungsmandat erneut einzurichten
`MANDATE_REQUIRED`	Soft	Ja	Für diese Transaktion ist ein Mandat erforderlich	Richten Sie ein Mandat ein und bitten Sie den Kunden, es vor der Belastung zu autorisieren
`MANDATE_REQUIRED_SYSTEM`	Hard	Nein	Das System erfordert für diesen Transaktionstyp ein Mandat	Stellen Sie sicher, dass der Ablauf zur Mandatseinrichtung vor der Belastung abgeschlossen ist
`NETWORK_ERROR`	Soft	Nein	Während der Transaktion ist ein Netzwerkfehler aufgetreten	Vorübergehend — versuchen Sie die Zahlung nach kurzer Verzögerung erneut
`NETWORK_TIMEOUT`	Soft	Nein	Die Netzwerkanfrage ist abgelaufen	Vorübergehend — versuchen Sie die Zahlung nach kurzer Verzögerung erneut
`ORDER_ALREADY_EXISTS`	Soft	Nein	Für diese Transaktion existiert bereits eine Bestellung (doppelte Erstellung einer Bestellung)	Überprüfen Sie vor einem erneuten Versuch den Status der bestehenden Bestellung; wenden Sie sich an den Support, falls das Problem bestehen bleibt
`ORDER_CREATION_FAILED`	Soft	Nein	Die Bestellung für die Transaktion konnte nicht erstellt werden	Vorübergehender/Systemfehler — versuchen Sie die Zahlung erneut; wenden Sie sich an den Support, falls das Problem bestehen bleibt
`PAYMENT_METHOD_PROVIDER_DECLINED`	Hard	Ja	Der Anbieter der Zahlungsmethode hat die Transaktion abgelehnt	Bitten Sie den Kunden, seinen Anbieter zu kontaktieren oder eine andere Zahlungsmethode zu verwenden
`PAYMENT_METHOD_UNSUPPORTED`	Hard	Ja	Die Zahlungsmethode wird für diese Transaktion nicht unterstützt	Bitten Sie den Kunden, eine unterstützte Zahlungsmethode zu verwenden
`PICKUP_CARD`	Hard	Ja	Die Karte wurde als verloren oder gestohlen gemeldet und zur Einziehung markiert	Zeigen Sie dem Kunden eine allgemeine Ablehnungsnachricht — geben Sie den Grund nicht bekannt. Bitten Sie ihn, eine andere Karte zu verwenden
`PROCESSING_ERROR`	Soft	Nein	Bei der Verarbeitung der Transaktion ist ein Fehler aufgetreten	Vorübergehend — versuchen Sie die Zahlung erneut; falls das Problem bestehen bleibt, bitten Sie den Kunden, seine Bank zu kontaktieren
`PROVIDER_UNSUPPORTED`	Hard	Nein	Der Zahlungsanbieter unterstützt diesen Transaktionstyp nicht	Bitten Sie den Kunden, eine andere Zahlungsmethode zu verwenden
`REENTER_TRANSACTION`	Soft	Ja	Die Transaktion muss erneut eingegeben werden	Bitten Sie den Kunden, die Zahlung erneut zu versuchen
`REVOCATION_OF_AUTHORIZATION`	Hard	Ja	Die Autorisierung für die Transaktion wurde widerrufen	Bitten Sie den Kunden, eine andere Zahlungsmethode zu verwenden
`STOLEN_CARD`	Hard	Ja	Die Karte wurde als gestohlen gemeldet	Zeigen Sie dem Kunden eine allgemeine Ablehnungsnachricht — geben Sie den Grund nicht bekannt. Bitten Sie ihn, eine andere Karte zu verwenden
`SUBSCRIPTION_NOT_ACTIVE`	Hard	Nein	Das Abonnement ist nicht aktiv, daher konnte die wiederkehrende Belastung nicht verarbeitet werden	Reaktivieren Sie das Abonnement (zum Beispiel durch Aktualisieren der Zahlungsmethode), bevor Sie die Belastung erneut versuchen
`TRANSACTION_NOT_ALLOWED`	Hard	Ja	Die Transaktion ist für diese Karte oder dieses Konto nicht zulässig	Bitten Sie den Kunden, seine Bank zu kontaktieren, damit dieser Transaktionstyp zugelassen wird, oder eine andere Karte zu verwenden
`TRANSACTION_NOT_APPROVED`	Hard	Ja	Die Transaktion wurde nicht genehmigt	Bitten Sie den Kunden, seine Bank zu kontaktieren oder eine andere Karte zu versuchen
`TRY_AGAIN_LATER`	Soft	Nein	Die Transaktion sollte später erneut versucht werden	Vorübergehend — versuchen Sie die Zahlung später erneut
`UNKNOWN_ERROR`	Soft	Nein	Ein unbekannter Fehler ist aufgetreten	Versuchen Sie die Zahlung erneut; wenden Sie sich an den Support, falls das Problem bestehen bleibt

Benutzerfehler gibt an, ob der Kunde die Zahlungsablehnung beheben kann. Wenn Yes, kann der Kunde Maßnahmen ergreifen, um das Problem zu beheben (zum Beispiel korrekte Kartendaten eingeben). Wenn No, ist die Ablehnung auf systembedingte Probleme oder Bankbeschränkungen zurückzuführen, die der Kunde nicht direkt beheben kann.

Eine Karte kann auch abgelehnt werden, wenn die Risikoprüfung der ausstellenden Bank den Karteninhaber unabhängig vom Händler oder den Transaktionsdetails als Kunden mit hohem Risiko einstuft. Diese Ablehnungen erscheinen typischerweise als allgemeine Codes wie DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED oder FRAUDULENT. In diesen Fällen teilt die Bank den konkreten Grund nicht mit, und weder Dodo Payments noch der Händler können die Entscheidung außer Kraft setzen. Bitten Sie den Kunden, seine Bank zu kontaktieren, um die Markierung zu klären, oder eine andere Karte bzw. Zahlungsmethode zu verwenden.

Fehler programmgesteuert verarbeiten

Lesen Sie error_code aus dem payment.failed-Webhook oder dem Zahlungsobjekt aus, ordnen Sie ihn der oben genannten empfohlenen Maßnahme zu und entscheiden Sie, ob ein erneuter Versuch unternommen werden soll. Bei Abonnementverlängerungen werden vorübergehende Ablehnungen automatisch für Sie erneut versucht — siehe Subscription Payment Retries. Informationen zu Fehlern auf API-Ebene und in der Geschäftslogik (wie PAYMENT_NOT_SUCCEEDED oder REFUND_WINDOW_EXPIRED), die keine Kartenablehnungen sind, finden Sie in der Referenz Error Codes.

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 zusätzliche Hilfe bei fehlgeschlagenen Transaktionen oder Integrationsproblemen benötigen, wenden Sie sich bitte unter support@dodopayments.com an unser Supportteam.

API Reference

Checkout Sessions

Payments

Subscriptions

Discounts

Licenses

Entitlements

Customers

Customer Wallets

Products

Localized Pricing

Addons

Credit Entitlements

Meters

Usage Events

Refunds

Disputes

Payouts

Balance Ledger

Brands

Webhooks

Miscellaneous

Product Collections

Übersicht

Händlertext vs. Kundentext

Handle Payment Failures

Vorübergehende vs. endgültige Ablehnungen

Gründe für fehlgeschlagene Transaktionen

Fehler programmgesteuert verarbeiten

Verwandte Themen

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Support

​Übersicht

​Händlertext vs. Kundentext

Handle Payment Failures

​Vorübergehende vs. endgültige Ablehnungen

​Gründe für fehlgeschlagene Transaktionen

​Fehler programmgesteuert verarbeiten

​Verwandte Themen

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

​Support

Übersicht

Händlertext vs. Kundentext

Vorübergehende vs. endgültige Ablehnungen

Gründe für fehlgeschlagene Transaktionen

Fehler programmgesteuert verarbeiten

Verwandte Themen

Support