last_payment_error documentation
Overview#
The last_payment_error object contains detailed information about the most recent payment failure. It helps developers understand why a payment did not succeed and provides data to display user-friendly messages or handle errors programmatically.last_payment_error.code is a short identifier for the type of error.
last_payment_error.decline_code is returned when the card issuer declines the payment and indicates the specific reason, if available. Not all card declines include a decline_code.last_payment_error.message provides a human-readable description of the error.
Code Reference#
| Code | Description |
|---|
| system_error | System encountered an error |
| payment_intent_authentication_failed | 3D Secure authentication failed. User action required. |
| authentication_failed | 3D Secure authentication failed. User action required. |
| card_declined | The card issuer declined the transaction. |
| payment_method_not_available | The requested payment method or service is not enabled for the account. |
| reenter_transaction | Transaction failed, please re-enter details or contact the issuer bank if issue persists. |
| processing_error | An error occurred during card processing. Try again later or use a different payment method. |
| fraudulent | Payment blocked by the payment provider’s risk control system. |
Decline Code Reference#
| Decline Code | Description |
|---|
| insufficient_funds | The card has insufficient funds to complete the payment. |
| lost_card | The card has been reported lost. |
| stolen_card | The card has been reported stolen. |
| expired_card | The card has expired. |
| incorrect_cvc | The CVC code entered is incorrect. |
| restricted_card | The card cannot be used for this type of transaction. |
| transaction_not_allowed | The card cannot be used for this transaction type. |
| card_velocity_exceeded | The card has exceeded the allowed transaction frequency or volume. |
| pin_try_exceeded | Too many incorrect PIN attempts. |
| call_issuer | The cardholder should contact their bank. |
| do_not_honor | The transaction is declined for unspecified reasons. |
| fraudulent | The transaction was flagged as fraudulent by the issuer. |
| processing_error | An error occurred while processing the card. |
Usage Notes#
code provides a general classification of the payment failure for programmatic handling.
decline_code gives the issuer-specific reason for card declines, only available when provided by the bank.
Combine with last_payment_error.message to show user-friendly explanations.
Not all failed payments will have a decline_code; system or network errors usually only have code.
Modified at 2025-10-29 08:51:17
