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 would allow 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. This means integrations that were reusing client secrets from completed or processing intents will now receive validation errors instead of successfully creating an Elements instance.

Impact

This change ensures that your customers don’t see broken payment forms by preventing Elements from rendering those forms in a broken state. 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 upfront 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 fresh 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.