Adds new error codes for payment method failures
What’s new
Adds the following new error codes to report failure states across payment method types, countries, and regions:
- authentication _ failure
- expired _ payment _ method
- incorrect _ postal _ code
- payment _ method _ restricted
For detailed descriptions, see the error codes reference.
Impact
This change does not remove any error codes, so no immediate action is required. To support a wider range of error cases on the impacted endpoints, update your error handling to recognize authentication_failure, expired_payment_method, incorrect_postal_code, and payment_method_restricted.
The new code payment_method_restricted identifies issuer or platform restrictions such as those imposed after a card is reported lost or stolen. The other new error codes ( authentication_failure, expired_payment_method, and incorrect_postal_code) are similar to existing error codes, but represent failures consistently across payment method types, countries, and regions.
Previously, authentication failures reflected their specific payment object, such as payment_intent_authentication_failure and setup_intent_authentication_failure, excluding other integration paths. Payment method expiration and postal code errors reflected card-specific expired_card and region-specific incorrect_zip, respectively, excluding the many other payment method types and regions.
Changes
| Codes | Change | |
|---|---|---|
| authentication_failure expired_payment_method incorrect_postal_code payment_method_restricted | Added | Invoice.last_finalization_error PaymentIntent.last_payment_error SetupAttempt.setup_error + 3 more SetupIntent.last_setup_error StripeError Terminal.Reader.action.api_error |
Upgrade
- View your current API version in Workbench.
- If you use an SDK, upgrade to the corresponding SDK version for this API version.
- If you don’t use an SDK, update your API requests to include Stripe-Version: 2026-08-26. dahlia
- Upgrade the API version used for webhook endpoints .
- Test your integration against the new version.
- If you use Connect, test your Connect integration .
- In Workbench, perform the upgrade . You can roll back the version for 72 hours.
Learn more about Stripe API upgrades.
Related changes
- Adds support for updating Connect parameters of an existing Payment Link
- Adds a funding source identifier to Link payments
- Adds the ability to restrict card funding types in Checkout Sessions
- Adds support for metadata in confirmation tokens
- Adds a funding source identifier to Link wallet card payments