Public preview
Adds surcharge configuration options for card-not-present payments Public preview
What’s new
Adds the ability to configure surcharge validation for card-not-present payments using the new amount_details.surcharge.enforce_validation parameter on Payment Intents. It can have the following values:
- automatic : Validation is enforced, but can be changed. If you don’t specify a value, this behavior is the default.
- disabled : Validation is not enforced. You can’t change this value.
- enabled : Validation is enforced. You can’t change this value.
Also adds the amount_details.surcharge.amount property.
When creating Payment Intents for payments with surcharges, you pass the total amount inclusive of the surcharge rather than calculating it separately. Surcharge parameters are available on the create, update, confirm, and capture methods.
Impact
When you create, update, confirm, or capture a Payment Intent and specify a surcharge, include the surcharge amount in the total amount and identify the surcharge amount in the amount_details.surcharge.amount parameter.
You can also now configure validation enforcement for card-not-present payments with surcharges by specifying the amount_details.surcharge.enforce_validation parameter. If you set the parameter to enabled or disabled, you can’t change it. Setting it to automatic enables validation enforcement, but can be changed.
Changes
| Parameter | Change | Resources or endpoints |
|---|---|---|
| surcharge | Added | PaymentIntent#capture. amount_details PaymentIntent#confirm. amount_details PaymentIntent#create. amount_details + 2 more PaymentIntent#update. amount_details PaymentIntent. amount_details |
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-03-25. preview
- 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.