Prevents reusing client secrets for Intents in certain states when initializing ElementsBreaking changes

What’s new

Introduces validation to prevent reusing client secrets from Payment Intents or Setup Intents that are in succeeded, canceled, processing, requires_capture, or requires_action states with non-detachable payment methods (Boleto, knet, Oxxo, us_cash_voucher) when you create an Elements instance.

Why is this a breaking change?

Previously, Elements allowed you to initialize a instance with any valid client secret, regardless of the associated PaymentIntent or SetupIntent’s state.

Now, Elements validates that the Intent is in an appropriate state before allowing the instance to be created. If you reuse client secrets from PaymentIntents or SetupIntents that are already completed or processing, they now produce validation errors.

Impact

This change prevents Elements from rendering payment forms in a broken state, which ensures that your customers don’t see broken forms on your checkout page.

Previously, you could create an Elements instance with a client secret from a completed or processing Intent, but any payment attempts by your customers would fail. Now, Elements validates the Intent state and returns an error to your integration instead of rendering a non-functional payment form.

To ensure your integration continues to work:

• Handle the new validation errors: Update your error handling to catch these validation errors when creating an Elements instance.
• Create new PaymentIntents or SetupIntents: When you receive a validation error, create a new PaymentIntent or SetupIntent and use its client secret to initialize Elements.
• Avoid reusing client secrets: Always use fresh client secrets for new payment flows or verify that the associated intent is in a valid state (typically requires_payment_method or requires_confirmation).

This validation only applies when using API version 2025-09-30.clover or later, so existing integrations on earlier API versions are unaffected.