Configuration Changes

Stripe has updated the Payment Element to support setting setup_future_usage on the PaymentIntent or Payment Element itself, rather than exclusively through payment_method_save_usage on the CustomerSession. This provides developers with more flexibility in where and how they configure future payment handling.

When enabling payment_method_save for a CustomerSession, developers can now configure future usage in two ways:

• Use payment_method_save_usage: Set this on the CustomerSession and omit setup_future_usage entirely from the PaymentIntent, Payment Element, and stripe.elements() configuration
• Use setup_future_usage: Set this on the PaymentIntent or Payment Element (including payment method-specific overrides in payment_method_options), and do not set payment_method_save_usage on the CustomerSession

Breaking Changes

This update removes the ability to set both payment_method_save_usage and setup_future_usage simultaneously. Attempting to configure both parameters for the same CustomerSession now returns an IntegrationError during render.

Additionally, enabling payment_method_save no longer requires setting payment_method_save_usage. Developers must provide either payment_method_save_usage or setup_future_usage, but not both.

Required Actions

Developers with existing integrations that set both parameters must update their code to use only one approach. The migration path depends on your current implementation:

• Review your CustomerSession configuration for payment_method_save_usage settings
• Check your PaymentIntent and Payment Element code for setup_future_usage configurations
• Remove duplicate configurations to avoid IntegrationError exceptions
• Test thoroughly, as this is a breaking change affecting payment method saving behavior

Related Updates

This change is part of a larger API update. Stripe has also made related breaking changes including Address Element state field formatting defaults, the elements.update() method now returning a Promise, removal of boolean values in options.layout.radios, deprecation of legacy methods, and initialization method renames for Checkout and Embedded Checkout.