Transaktionsfehler - Dodo Payments Documentation

Ü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 — einen standardisierten Ausfallgrund aus der unten stehenden Tabelle.
error_message — eine lesbare Erklärung.
retry_attempt — 0 für die ursprüngliche Belastung, 1 oder höher für jeden geplanten Abonnementerneuerungsversuch.

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.

Handle Payment Failures

Ein Schritt-für-Schritt-Entwicklerleitfaden zum Lesen dieser Codes von Webhooks und der API, zum Anzeigen an Kunden und zur Entscheidung, wann ein erneuter Versuch unternommen werden soll.

Weiche vs. Harte Ablehnungen

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

Ablehnungstyp	Bedeutung	Maßnahmen	Beispiele
Weiche Ablehnung	Vorübergehend oder korrigierbar — dieselbe Karte kann bei einem späteren Versuch erfolgreich sein oder sobald der Kunde seine Eingaben korrigiert.	Sicher erneut versuchen (nach einer Verzögerung oder sobald der Kunde seine Daten korrigiert hat).	`INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER`
Harte Ablehnung	Endgültig — ein erneuter Versuch derselben Karte wird das Ergebnis nicht ändern.	Nicht dieselbe Karte erneut versuchen. 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`

Für Abonnementerneuerungen wendet Dodo Payments diese Unterscheidung automatisch an: Weiche Ablehnungen werden von Subscription Payment Retries erneut versucht, während harte Ablehnungen die Wiederholkette sofort beenden und am besten mit Subscription Dunning behandelt werden.

Enthüllen Sie niemals den tatsächlichen Grund für STOLEN_CARD, LOST_CARD, PICKUP_CARD oder FRAUDULENT den Kunden. Das Offenlegen dieser kann einen betrügerischen Akteur aufmerken lassen. Zeigen Sie dem Kunden immer eine generische 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.

Transaktionsausfallgründe

Die folgende Tabelle listet jeden Ausfallcode, seinen Ablehnungstyp, ob der Kunde ihn beheben kann, eine Beschreibung und die empfohlene Aktion auf.

Ausfallcode	Typ	Benutzerfehler	Beschreibung	Empfohlene Aktion
`AUTHENTICATION_FAILURE`	Weich	Ja	Authentifizierung während der Transaktion fehlgeschlagen	Bitten Sie den Kunden, die 3DS-Authentifizierung erneut zu versuchen und abzuschließen oder eine andere Karte zu verwenden
`AUTHENTICATION_REQUIRED`	Weich	Ja	Zusätzliche Authentifizierung zur Durchführung der Transaktion erforderlich	Bitten Sie den Kunden, die 3DS-Authentifizierung abzuschließen. Bei Abonnementerneuerungen bitten Sie ihn, zurückzukehren und sich zu authentifizieren
`AUTHENTICATION_TIMEOUT`	Weich	Ja	Der Authentifizierungsprozess ist abgelaufen	Bitten Sie den Kunden, die Authentifizierung schnell erneut zu versuchen und abzuschließen
`CARD_DECLINED`	Weich	Nein	Die Karte wurde von der ausstellenden Bank ohne spezifischen Grund abgelehnt (generische Ablehnung)	Bitten Sie den Kunden, es erneut zu versuchen, seine Bank zu kontaktieren oder eine andere Karte zu verwenden
`CARD_NOT_ACTIVATED`	Weich	Ja	Die Karte wurde vom Karteninhaber nicht aktiviert	Bitten Sie den Kunden, die Karte bei seiner Bank zu aktivieren und es dann erneut zu versuchen
`CARD_VELOCITY_EXCEEDED`	Weich	Ja	Zu viele Transaktionen in kurzer Zeit versucht	Bitten Sie den Kunden, zu warten und es später erneut zu versuchen, oder seine Bank bezüglich der Limits zu kontaktieren
`CUSTOMER_CANCELLED`	Weich	Ja	Der Kunde hat die Transaktion abgebrochen	Lassen Sie den Kunden den Checkout neu starten, wenn er bereit ist
`DO_NOT_HONOR`	Hart	Nein	Die ausstellende Bank hat die Transaktion ausdrücklich abgelehnt (ISO 8583-Code 05 — nicht ehren); Netzwerke behandeln dies als terminal	Bitten Sie den Kunden, seine Bank zu kontaktieren; dieselbe Karte nicht erneut versuchen
`EXPIRED_CARD`	Hart	Ja	Die Karte ist abgelaufen	Bitten Sie den Kunden, eine Karte mit einem gültigen Ablaufdatum zu verwenden
`FRAUDULENT`	Hart	Ja	Die Transaktion wurde als potenziell betrügerisch markiert	Zeigen Sie dem Kunden eine generische Ablehnungsnachricht — den Grund nicht offenlegen. Bitten Sie ihn, eine andere Karte zu verwenden
`GENERIC_DECLINE`	Weich	Nein	Die Transaktion wurde aus einem nicht spezifizierten Grund abgelehnt	Bitten Sie den Kunden, seine Bank zu kontaktieren oder es mit einer anderen Karte zu versuchen
`INCORRECT_CVC`	Weich	Ja	Der eingegebene CVC-Code war falsch	Bitten Sie den Kunden, den richtigen CVC einzugeben
`INCORRECT_NUMBER`	Weich	Ja	Die Kartennummer wurde falsch eingegeben	Bitten Sie den Kunden, die richtige Kartennummer einzugeben
`INSUFFICIENT_FUNDS`	Weich	Ja	Das Konto hat nicht genügend Mittel, um die Transaktion durchzuführen	Bitten Sie den Kunden, eine andere Zahlungsmethode zu verwenden oder es erneut zu versuchen, sobald Mittel verfügbar sind
`INVALID_ACCOUNT`	Hart	Ja	Die angegebenen Kontodaten sind ungültig	Bitten Sie den Kunden, seine Bank zu kontaktieren oder eine andere Karte zu verwenden
`INVALID_AMOUNT`	Weich	Ja	Der Transaktionsbetrag ist ungültig	Überprüfen Sie den Betrag und eventuelle Kauflimits mit dem Kunden
`INVALID_CARD_NUMBER`	Weich	Ja	Das Format der Kartennummer ist ungültig	Bitten Sie den Kunden, eine gültige Kartennummer einzugeben
`INVALID_CARD_OWNER`	Weich	Ja	Die Karteninhaberinformationen sind ungültig	Bitten Sie den Kunden, den Namen des Karteninhabers zu korrigieren
`INVALID_CVC`	Weich	Ja	Das CVC-Format ist ungültig	Bitten Sie den Kunden, einen gültigen CVC einzugeben
`INVALID_EXPIRY_YEAR`	Weich	Ja	Das Ablaufjahr der Karte ist ungültig	Bitten Sie den Kunden, ein gültiges Ablaufdatum einzugeben
`INVALID_PIN`	Weich	Ja	Die eingegebene PIN ist falsch	Bitten Sie den Kunden, die korrekte PIN einzugeben
`INVALID_REQUEST`	Weich	Ja	Der Transaktionsantrag enthält ungültige Daten	Überprüfen Sie die Zahlungsanforderungsfelder und reichen Sie sie mit gültigen Daten erneut ein
`INVALID_UPI_ID`	Weich	Ja	Die angegebene UPI-ID ist ungültig	Bitten Sie den Kunden, eine gültige UPI-ID einzugeben
`LIMIT_EXCEEDED`	Weich	Ja	Die Transaktion überschreitet das Karten- oder Kontolimit	Bitten Sie den Kunden, seine Bank bezüglich der Limits zu kontaktieren, oder verwenden Sie eine andere Methode
`LIVE_MODE_TEST_CARD`	Hart	Ja	Eine Testkarte wurde im Live-Modus verwendet	Verwenden Sie eine echte Karte — das erneute Versuchen der Testkarte schlägt im Live-Modus immer fehl
`LOST_CARD`	Hart	Ja	Die Karte wurde als verloren gemeldet	Zeigen Sie dem Kunden eine generische Ablehnungsnachricht — den Grund nicht offenlegen. Bitten Sie ihn, eine andere Karte zu verwenden
`MANDATE_INVALID`	Weich	Ja	Das Zahlungsmandat ist ungültig	Bitten Sie den Kunden, das Zahlungsmandat erneut einzurichten
`MANDATE_REQUIRED`	Weich	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`	Hart	Nein	Das System erfordert ein Mandat für diesen Transaktionstyp	Stellen Sie sicher, dass der Mandatseinrichtungsprozess abgeschlossen ist, bevor Sie die Belastung vornehmen
`NETWORK_ERROR`	Weich	Nein	Während der Transaktion ist ein Netzfehler aufgetreten	Vorübergehend — versuchen Sie die Zahlung nach einer kurzen Verzögerung erneut
`NETWORK_TIMEOUT`	Weich	Nein	Die Netzwerk-Anforderung ist abgelaufen	Vorübergehend — versuchen Sie die Zahlung nach einer kurzen Verzögerung erneut
`ORDER_ALREADY_EXISTS`	Weich	Nein	Für diese Transaktion existiert bereits eine Bestellung (doppelte Bestellerstellung)	Überprüfen Sie den Status der bestehenden Bestellung, bevor Sie es erneut versuchen; wenden Sie sich an den Support, falls es weiterhin besteht
`ORDER_CREATION_FAILED`	Weich	Nein	Die Bestellung für die Transaktion konnte nicht erstellt werden	Vorübergehend/Systemfehler — versuchen Sie die Zahlung erneut; wenden Sie sich an den Support, falls es weiterhin besteht
`PAYMENT_METHOD_PROVIDER_DECLINED`	Hart	Ja	Der Zahlungsdienstanbieter hat die Transaktion abgelehnt	Bitten Sie den Kunden, seinen Anbieter zu kontaktieren oder eine andere Zahlungsmethode zu verwenden
`PAYMENT_METHOD_UNSUPPORTED`	Hart	Ja	Die Zahlungsmethode wird für diese Transaktion nicht unterstützt	Bitten Sie den Kunden, eine unterstützte Zahlungsmethode zu verwenden
`PICKUP_CARD`	Hart	Ja	Die Karte wurde als verloren oder gestohlen gemeldet und zur Abholung markiert	Zeigen Sie dem Kunden eine generische Ablehnungsnachricht — den Grund nicht offenlegen. Bitten Sie ihn, eine andere Karte zu verwenden
`PROCESSING_ERROR`	Weich	Nein	Beim Verarbeiten der Transaktion ist ein Fehler aufgetreten	Vorübergehend — versuchen Sie die Zahlung erneut; falls es weiterhin besteht, bitten Sie den Kunden, seine Bank zu kontaktieren
`PROVIDER_UNSUPPORTED`	Hart	Nein	Der Zahlungsdienstleister unterstützt diesen Transaktionstyp nicht	Bitten Sie den Kunden, eine andere Zahlungsmethode zu verwenden
`REENTER_TRANSACTION`	Weich	Ja	Die Transaktion muss erneut eingegeben werden	Bitten Sie den Kunden, die Zahlung erneut zu versuchen
`REVOCATION_OF_AUTHORIZATION`	Hart	Ja	Die Autorisierung für die Transaktion wurde widerrufen	Bitten Sie den Kunden, eine andere Zahlungsmethode zu verwenden
`STOLEN_CARD`	Hart	Ja	Die Karte wurde als gestohlen gemeldet	Zeigen Sie dem Kunden eine generische Ablehnungsnachricht — den Grund nicht offenlegen. Bitten Sie ihn, eine andere Karte zu verwenden
`SUBSCRIPTION_NOT_ACTIVE`	Hart	Nein	Das Abonnement ist nicht aktiv, daher konnte die wiederkehrende Belastung nicht verarbeitet werden	Reaktivieren Sie das Abonnement (zum Beispiel durch Aktualisierung der Zahlungsmethode), bevor Sie die Belastung erneut versuchen
`TRANSACTION_NOT_ALLOWED`	Hart	Ja	Diese Transaktion ist für diese Karte oder dieses Konto nicht zulässig	Bitten Sie den Kunden, seine Bank zu kontaktieren, um diesen Transaktionstyp zuzulassen, oder eine andere Karte zu verwenden
`TRANSACTION_NOT_APPROVED`	Hart	Ja	Die Transaktion wurde nicht genehmigt	Bitten Sie den Kunden, seine Bank zu kontaktieren oder es mit einer anderen Karte zu versuchen
`TRY_AGAIN_LATER`	Weich	Nein	Die Transaktion sollte später erneut versucht werden	Vorübergehend — versuchen Sie die Zahlung später erneut
`UNKNOWN_ERROR`	Weich	Nein	Ein unbekannter Fehler ist aufgetreten	Versuchen Sie die Zahlung erneut; falls es weiterhin besteht, kontaktieren Sie den Support

Benutzerfehler zeigt an, ob die Zahlungsablehnung durch den Kunden behoben werden kann. Wenn Yes, kann der Kunde Maßnahmen ergreifen, um das Problem zu beheben (zum Beispiel durch Eingabe der richtigen Kartendaten). Wenn No, ist die Ablehnung auf systembedingte Probleme oder Bankeinschränkungen zurückzuführen, die der Kunde nicht direkt beheben kann.

Ein Karte kann auch abgelehnt werden, wenn die Risikomotor der ausstellenden Bank den Karteninhaber als Hochrisikokunden einstuft – unabhängig vom Händler oder den Transaktionsdetails. 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 keinen spezifischen Grund mit, und weder Dodo Payments noch der Händler können die Entscheidung übersteuern. Bitten Sie den Kunden, seine Bank zu kontaktieren, um das Problem zu klären, oder eine andere Karte oder Zahlungsmethode zu verwenden.

Fehler programmatisch behandeln

Lesen Sie error_code aus dem payment.failed Webhook oder dem Zahlungsobjekt, ordnen Sie es der empfohlenen Aktion oben zu und entscheiden Sie, ob ein erneuter Versuch unternommen werden soll. Bei Abonnementverlängerungen werden weiche Ablehnungen automatisch für Sie erneut versucht – siehe Abonnement Zahlungswiederholungen. Für API-Ebene und Geschäftslogikfehler (wie PAYMENT_NOT_SUCCEEDED oder REFUND_WINDOW_EXPIRED), die keine Kartenablehnungen sind, siehe die Fehlercodes Referenz.

Verwandt

End-to-End-Leitfaden zum Erkennen, Anzeigen und Wiederholen fehlgeschlagener Zahlungen. API- und Geschäftslogik-Fehlercodes für Fehler außerhalb von Ablehnungen. Automatische Wiederholungen, die weiche Ablehnungen bei Abonnementverlängerungen beheben. Email-Sequenzen, die harte Ablehnungen beheben, indem sie zur Aktualisierung der Zahlungsmethode auffordern.

Support

Für zusätzliche Hilfe zu Transaktionsfehlern oder Integrationsproblemen, kontaktieren Sie bitte unser Support-Team unter support@dodopayments.com.

​Übersicht

Handle Payment Failures

​Weiche vs. Harte Ablehnungen

​Transaktionsausfallgründe

​Fehler programmatisch behandeln

​Verwandt

​Support

Übersicht

Weiche vs. Harte Ablehnungen

Transaktionsausfallgründe

Fehler programmatisch behandeln

Verwandt

Support