New Surcharge Configuration Parameters

Stripe's Payment Intents API now supports granular control over surcharge handling for card-not-present payments. Two new parameters have been introduced:

• amount_details.surcharge.enforce_validation: Controls validation behavior with three modes:

  • automatic (default): Validation is enforced but can be changed later
  • enabled: Validation is enforced and cannot be changed
  • disabled: Validation is not enforced and cannot be changed

• amount_details.surcharge.amount: A new read/write property that explicitly identifies the surcharge portion of the total payment amount

Implementation Requirements

When creating or managing Payment Intents with surcharges, developers must pass the total amount inclusive of the surcharge rather than calculating it separately. The surcharge parameters are available on all four Payment Intent operations:

• Create
• Update
• Confirm
• Capture

This change ensures transparent surcharge handling and gives merchants control over validation rules applied to surcharges.

Upgrade Path

To adopt these features, developers should:

1. View their current API version in Workbench
2. Upgrade SDKs to versions compatible with API version 2026-03-25.preview
3. Update webhook endpoint configurations to use the new API version
4. Test integrations thoroughly before deploying to production
5. For Connect users, test Connect-specific integrations

API version can be pinned per-request using the Stripe-Version: 2026-03-25.preview header, and rollback is supported for 72 hours after upgrade.