Ü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 derpayment.failed-Webhook und das Zahlungsobjekt:
error_code— einen standardisierten Ausfallgrund aus der unten stehenden Tabelle.error_message— eine lesbare Erklärung.retry_attempt—0für die ursprüngliche Belastung,1oder höher für jeden geplanten Abonnementerneuerungsversuch.
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 |
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.Handhabung von Fehlern programmatisch
Lesen Sieerror_code vom payment.failed Webhook oder dem Zahlungsobjekt, ordnen Sie es der oben empfohlenen Aktion zu und entscheiden Sie, ob ein erneuter Versuch unternommen wird. Bei Abonnementserneuerungen werden weiche Ablehnungen automatisch für Sie erneut versucht — siehe Subscription Payment Retries.
Für API- und Geschäftsebene-Fehler (wie PAYMENT_NOT_SUCCEEDED oder REFUND_WINDOW_EXPIRED), die keine Kartenablehnungen sind, siehe das Fehlercodes Referenz.
Verwandt
Handle Payment Failures
End-to-End-Leitfaden zur Erkennung, Darstellung und zum erneuten Versuch fehlgeschlagener Zahlungen.
Error Codes
API- und Geschäftslogik-Fehlercodes für Fehler, die nicht auf Ablehnungen beruhen.
Subscription Payment Retries
Automatische Wiederholungsversuche, die weiche Ablehnungen bei Abonnementserneuerungen wiederherstellen.
Subscription Dunning
E-Mail-Sequenzen, die harte Ablehnungen durch Aufforderung zur Aktualisierung der Zahlungsmethode wiederherstellen.