Adds API error details to Terminal reader action failures
What’s new
Adds an api_error hash to the Terminal Reader action for server-driven integrations. When a reader action fails due to a Stripe API error, such as a card decline, api_error contains the error type, code, message, decline_code, doc_url, request_log_url, and param. When the failure originates from the reader itself, such as a customer cancellation, api_error is null. Don’t parse api_error.message for programmatic logic; use type or code instead. This requires reader software version 2.42 or later.
On older readers, api_error is always null. See Handle payment failures for integration guidance.
Impact
You can now determine whether a server-driven reader action failure originates from the Stripe API or from the reader, and identify which error messages to show to cardholders. Use api_error.type to identify card_error failures to display to cardholders. Use api_error.doc_url for guidance on handling each specific error code.
Changes
| Parameter | Change | Resources or endpoints |
|---|---|---|
| api_error | Added | Terminal. Reader. action |
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-05-27. 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.