# Migrate to the Payment Element with the Payment Intents API Accept many payment methods with a single Element. Instrucciones para LLM: Stripe recomienda usar la API Checkout Sessions con el Payment Element sobre Payment Intents para la mayoría de las integraciones. Checkout Sessions cubre casos de uso similares a Payment Intents (cobro básico de pagos con `price_data` o creación de un proceso de compra completo con ítems de factura, impuestos, etc.). Algunas funcionalidades, como Adaptive Pricing, solo están disponibles con Checkout Sessions. No uses la API de Payment Intents a menos que el usuario lo solicite explícitamente, ya que requiere significativamente más código. Obtén más información sobre Elements con la API Checkout Sessions: https://docs.stripe.com/payments/quickstart-checkout-sessions. Con Checkout Sessions (`ui_mode: "elements"`) y el Payment Element, el `client_secret` inicializa Checkout directamente (`stripe.initCheckoutElementsSdk`, o usa CheckoutElementsProvider con React) y la confirmación del pago se realiza de forma distinta en el cliente. Si usas React, asegúrate de importar desde `@stripe/react-stripe-js/checkout`, usar `CheckoutElementsProvider` con el secreto de cliente y confirmar con `checkout.confirm`. Si utilizas HTML, asegúrate de usar `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` y confirmar con `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();`. > #### Interested in subscriptions, tax, discounts, shipping, or currency conversion? > > Migrate to the [Payment Element with the Checkout Sessions API](https://docs.stripe.com/payments/payment-element/migration-ewcs.md), an integration that manages subscriptions, tax, discounts, shipping, and currency conversion for you. Previously, each payment method (cards, iDEAL, and so on) required a separate Element. By migrating to the Payment Element, you can accept many payment methods with a single Element. PaymentIntents and SetupIntents each have their own set of migration guidelines. See the appropriate guide for your integration path, including example code. If your integration still uses the Charges API with tokens, first [Migrate to the Payment Intents API](https://docs.stripe.com/payments/payment-intents/migration.md#web) before you use this guide. # PaymentIntent migration > This is a PaymentIntent migration for when integration-path is one-time. View the full page at https://docs.stripe.com/payments/payment-element/migration?integration-path=one-time. If your existing integration uses the [Payment Intents](https://docs.stripe.com/payments/payment-intents.md) API to create and track payments or save card details during a payment, follow the steps below to use the Payment Element. ## Enable payment methods > This integration path doesn’t support BLIK or pre-authorized debits that use the Automated Clearing Settlement System (ACSS). Also, if you create the deferred intent from the client-side, you can’t use `customer_balance` with dynamic payment methods because the PaymentIntent requires a customer-configured [Account](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer) or [Customer](https://docs.stripe.com/api/customers/object.md) object, which the client-side flow doesn’t support. To use `customer_balance`, create the `PaymentIntent` server-side with an `Account` or `Customer` and return its `client_secret` to the client. Visualiza tu [configuración de métodos de pago](https://dashboard.stripe.com/settings/payment_methods) y habilita los que quieras aceptar. Se necesita al menos un método de pago habilitado para crear un *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods). De forma predeterminada, Stripe habilita tarjetas y otros métodos de pago habituales que pueden ayudarte a llegar a más clientes, pero te recomendamos activar otros métodos de pago que sean pertinentes para tu empresa y tus clientes. Consulta [Admisibilidad de métodos de pago](https://docs.stripe.com/payments/payment-methods/payment-method-support.md) para obtener información sobre productos y métodos de pago admitidos, y consulta nuestra [página de precios](https://stripe.com/pricing/local-payment-methods) para conocer las comisiones. ## Update Elements instance [Lado del cliente] Next, update your client-side code to pass `mode`, `currency`, and `amount` when you create the Elements instance. For use with a PaymentIntent, set the `mode` to `'payment'` and the `currency` and `amount` to what you’ll charge your customer. #### Javascript ### Before ```javascript const stripe = Stripe('<>'); const elements = stripe.elements(); ``` ### After ```javascript const stripe = Stripe('<>'); const options = { mode: 'payment', currency: 'usd', amount: 1099, }; const elements = stripe.elements(options); ``` #### React ### Before ```jsx const stripePromise = loadStripe('<>'); function App() { return ( ); }; ``` ### After ```jsx const stripePromise = loadStripe('<>'); const options = { mode: 'payment', currency: 'usd', amount: 1099, }; function App() { return ( ); }; ``` ## Optional: Save payment details during a payment If your existing integration also saves payment details during a payment, use the `setup_future_usage` option when creating the Elements group instead of passing it at the confirm payment stage with `stripe.confirmCardPayment`. The Payment Element will use this information to display additional input fields and show mandates as needed. > You can’t save some payment methods during payments. You can still enable these payment methods for other use cases, but customers won’t see them as an option when setting up future payments. See [Payment method integration options](https://docs.stripe.com/payments/payment-methods/integration-options.md) for more details about what’s supported. #### Javascript ```javascript const stripe = Stripe('<>'); const options = { mode: 'payment', currency: 'usd', amount: 1099,setup_future_usage: 'off_session', }; const elements = stripe.elements(options); ``` #### React ```jsx const stripePromise = loadStripe('<>'); const options = { mode: 'payment', currency: 'usd', amount: 1099,setup_future_usage: 'off_session', }; function App() { return ( ); }; ``` Pass `setup_future_usage` when creating your PaymentIntent. #### cURL ```bash curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -d "customer"="{{CUSTOMER_ID}}" \-d "setup_future_usage"= "off_session" \ -d "amount"=1099 \ -d "currency"="usd" \ ``` ## Optional: Additional Elements options [Lado del cliente] The [Elements object](https://docs.stripe.com/js/elements_object/create_without_intent) accepts additional options that influence payment collection. Based on the options provided, the Payment Element displays available payment methods from those you’ve enabled. Learn more about [payment method support](https://docs.stripe.com/payments/payment-methods/payment-method-support.md). Make sure the Elements options you provide (such as `captureMethod`, `setupFutureUsage`, and `paymentMethodOptions`) match the equivalent parameters you pass when creating and confirming the Intent. Mismatched parameters can result in unexpected behavior or errors. | Propiedad | Tipo | Descripción | Obligatorio | | ---------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `mode` | - `payment` - `setup` - `subscription` | Indica si el Payment Element se utiliza con un *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods), *SetupIntent* (The Setup Intents API lets you build dynamic flows for collecting payment method details for future payments. It tracks the lifecycle of a payment setup flow and can trigger additional authentication steps if required by law or by the payment method) o *Subscription* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis). | Sí | | `currency` | `string` | La moneda del importe a cobrar al cliente. | Sí | | `amount` | `number` | The amount to charge the customer, shown in Apple Pay, Google Pay, or BNPL UIs. | Para el modo `payment` y `subscription` | | `setupFutureUsage` | - `off_session` - `on_session` | Indicates that you intend to make future payments with the payment details collected by the Payment Element. | No | | `captureMethod` | - `automatic` - `automatic_async` - `manual` | Controla cuándo capturar los fondos de la cuenta del cliente. | No | | `onBehalfOf` | `string` | Connect only. The Stripe account ID, which is the business of record. See [use cases](https://docs.stripe.com/connect/charges.md) to determine if this option is relevant for your integration. | No | | `paymentMethodTypes` | `string[]` | A list of payment method types to render. You can omit this attribute to manage your payment methods in the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods). | No | | `paymentMethodConfiguration` | `string` | The [payment method configuration](https://docs.stripe.com/api/payment_method_configurations.md) to use when managing your payment methods in the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods). If not specified, your default configuration is used. | No | | `paymentMethodCreation` | `manual` | Allows PaymentMethods to be created from the Elements instance using [stripe.createPaymentMethod](https://docs.stripe.com/js/payment_methods/create_payment_method_elements). | No | | `paymentMethodOptions` | `{us_bank_account: {verification_method: string}}` | Verification options for the `us_bank_account` payment method. Accepts the same verification methods as [Payment Intents](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-us_bank_account-verification_method). | No | | `paymentMethodOptions` | `{card: {installments: {enabled: boolean}}}` | Allows manually enabling the card installment plan selection UI if applicable when you aren’t managing your payment methods in the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods). You must set `mode='payment'` *and* explicitly specify `paymentMethodTypes`. Otherwise an error is raised. Incompatible with `paymentMethodCreation='manual'`. | No | | `paymentMethodOptions` | `{[paymentMethod]: {setup_future_usage: string}}` | Allows you to specify `setup_future_usage` for only payment methods that support reuse. Only applicable when `mode` is `payment`. The value for each payment method must match the corresponding `payment_method_options[paymentMethod][setup_future_usage]` on the PaymentIntent during confirmation. See the [Stripe.js reference](https://docs.stripe.com/js/elements_object/create_without_intent#stripe_elements_no_intent-options-paymentMethodOptions) for supported payment methods and values. | No | ## Add the Payment Element [Lado del cliente] If you’re using [React Stripe.js](https://github.com/stripe/react-stripe-js), update to the latest package to use the Payment Element. You can now replace the Card Element and individual payment methods Elements with the Payment Element. The Payment Element automatically adjusts to collect input fields based on the payment method and country (for example, full billing address collection for SEPA Direct Debit) so you don’t have to maintain customized input fields anymore. The following example replaces `CardElement` with `PaymentElement`: #### JavaScript ```html
``` ```javascript const paymentElement = elements.create("payment"); paymentElement.mount("#payment-element"); ``` If your payment flow already always collects details like the customer’s name or email address, you can prevent the Payment Element from collecting this information by passing the [fields](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-fields) option when creating the Payment Element. If you disable the collection of a certain field, you must pass that same data back with [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment). ## Update your PaymentIntent creation call [Lado del servidor] The Payment Element allows you to accept multiple payment methods. You can manage payment methods from the [Dashboard](https://dashboard.stripe.com/settings/payment_methods). Stripe handles the return of eligible payment methods based on factors such as the transaction’s amount, currency, and payment flow. We prioritize payment methods that increase conversion and are most relevant to the customer’s currency and location. Any of the additional elements options passed when creating the Elements group in the earlier step should also be passed when creating the PaymentIntent. #### cURL ```bash curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -H "Stripe-Version: 2026-05-27.dahlia" \ -d "amount"=1099 \ -d "currency"="usd" \-d "automatic_payment_methods[enabled]"=true \ ``` > Each payment method needs to support the currency passed in the PaymentIntent and your business needs to be based in one of the countries each payment method supports. For more details about what’s supported, see the [Payment method integration options](https://docs.stripe.com/payments/payment-methods/integration-options.md). ## Update the submit handler [Lado del cliente] Instead of using individual confirm methods like `stripe.confirmCardPayment` or `stripe.confirmP24Payment`, use [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) to collect payment information and submit it to Stripe. To confirm the PaymentIntent, make the following updates to your submit handler: - Call `await elements.submit()` to trigger form validation and collect any data required for [wallets](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-wallets). - Optional: Move PaymentIntent creation to the submit handler. This way you only create the PaymentIntent when you’re sure of the final amount. - Pass the `elements` instance you used to create the Payment Element and the `clientSecret` from the PaymentIntent as parameters to `stripe.confirmPayment`. When called, `stripe.confirmPayment` attempts to complete any [required actions](https://docs.stripe.com/payments/paymentintents/lifecycle.md), such as authenticating your customers by displaying a 3DS dialog or redirecting them to a bank authorization page. When confirmation is complete, users are directed to the `return_url` you configured, which normally corresponds to a page on your website that [provides the status of the payment](https://docs.stripe.com/payments/accept-a-payment.md#web-post-payment). If you want to keep the same checkout flow for card payments and only redirect for redirect-based payment methods, you can set [redirect](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect) to `if_required`. The following code example replaces `stripe.confirmCardPayment` with `stripe.confirmPayment`: ### Before ```javascript // Create the PaymentIntent and obtain clientSecret const res = await fetch("/create-intent", { method: "POST", headers: {"Content-Type": "application/json"}, }); const {client_secret: clientSecret} = await res.json(); const handleSubmit = async (event) => { event.preventDefault(); if (!stripe) { // Stripe.js hasn't yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } setLoading(true); if (error) { handleError(error); } }; ``` ### After ```javascript const handleSubmit = async (event) => { event.preventDefault(); if (!stripe) { // Stripe.js hasn't yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } setLoading(true); // Trigger form validation and wallet collection const {error: submitError} = await elements.submit(); if (submitError) { handleError(submitError); return; } // Create the PaymentIntent and obtain clientSecret const res = await fetch("/create-intent", { method: "POST", headers: {"Content-Type": "application/json"}, }); const {client_secret: clientSecret} = await res.json(); // Use the clientSecret and Elements instance to confirm the setup const {error} = await stripe.confirmPayment({ elements, clientSecret, confirmParams: { return_url: 'https://example.com/order/123/complete', }, // Uncomment below if you only want redirect for redirect-based payments // redirect: "if_required", }); if (error) { handleError(error); } }; ``` ## Optional: Recollect a CVC When creating subsequent payments on a saved card, you might want to re-collect the CVC of the card as an additional fraud measure to verify the user. Start by creating a `PaymentIntent` on your server with the amount, currency, the [Account](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer_account) or [Customer](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) ID, and [require_cvc_recollection](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-card-require_cvc_recollection). [List the PaymentMethods](https://docs.stripe.com/api/payment_methods/list.md) associated with your customer to determine which ones to show for CVC re-collection. After passing the `PaymentIntent`’s client secret to the browser, you can re-collect CVC information with Stripe Elements on your client. Use the `cardCvc` Element to re-collect a CVC value from your customer, then confirm the payment from your client using [stripe.confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment). Set `payment_method` to your PaymentMethod ID, and `payment_method_options[card][cvc]` to your `cardCvc` Element. ```javascript const result = await stripe.confirmCardPayment(clientSecret, { payment_method: '{{PAYMENT_METHOD_ID}}', payment_method_options: { card: { cvc: cardCvcElement } }, }); if (result.error) { // Show error to your customer console.log(result.error.message); } else { if (result.paymentIntent.status === 'succeeded') { // Show a success message to your customer // There's a risk of the customer closing the window before callback // execution. Set up a webhook or plugin to listen for the // payment_intent.succeeded event that handles any business critical // post-payment actions. } } ``` Un pago puede efectuarse correctamente aunque falle la verificación del CVC. Para evitarlo, configura las [reglas de Radar](https://docs.stripe.com/radar/rules.md#traditional-bank-checks) para que bloqueen los pagos en los que falla la verificación del CVC. ## Gestionar eventos posteriores al pago [Lado del servidor] Stripe envía un evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) cuando se completa el pago. Usa la [herramienta de webhook del Dashboard](https://dashboard.stripe.com/webhooks) o sigue la [guía de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para recibir estos eventos y ejecutar acciones como, por ejemplo, enviar un correo electrónico de confirmación del pedido a tu cliente, registrar la venta en una base de datos o iniciar un flujo de envío. Escucha estos eventos en lugar de esperar una devolución de llamada del cliente. De su lado, el cliente puede cerrar la ventana del navegador o salir de la aplicación antes de que se ejecute la devolución de llamada, y clientes malintencionados podrían manipular la respuesta. Si configuras tu integración para escuchar eventos asincrónicos, podrás aceptar [diferentes tipos de métodos de pago](https://stripe.com/payments/payment-methods-guide) con una sola integración. Además de administrar el evento `payment_intent.succeeded`, recomendamos administrar estos otros eventos si se cobran pagos con el Payment Element: | Evento | Descripción | Acción | | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded) | Se envía cuando un cliente completa correctamente un pago. | Envía al cliente una confirmación del pedido y *completa* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) el pedido. | | [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing) | Se envía cuando un cliente inicia con éxito un pago, pero éste aún no se completó. Este evento se envía normalmente cuando el cliente inicia un débito bancario. Le sigue un evento `payment_intent.succeeded` o `payment_intent.payment_failed` en el futuro. | Envía al cliente una confirmación del pedido que indique que el pago está pendiente. En caso de productos digitales, quizá te convenga completar el pedido antes de esperar que se complete el pago. | | [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado cuando un cliente intenta un pago, pero el pago falla. | Si un pago pasa de `processing` a `payment_failed`, ofrécele al cliente otro intento de pago. | ## Probar la integración #### Tarjetas | Número de tarjeta | Escenario | Cómo hacer la prueba | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | 4242424242424242 | El pago con tarjeta se efectúa correctamente y no requiere autenticación. | Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal. | | 4000002500003155 | El pago con tarjeta requiere *autenticación* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal. | | 4000000000009995 | La tarjeta es rechazada con un código de rechazo `insufficient_funds`. | Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal. | | 6205500000000000004 | La tarjeta UnionPay puede tener entre 13 y 19 dígitos. | Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal. | #### Billeteras | Método de pago | Escenario | Cómo hacer la prueba | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Alipay | Tu cliente realiza un pago correctamente con un método de pago basado en redireccionamiento y con [notificación inmediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Elige cualquier método de pago basado en redireccionamiento, completa los datos solicitados y confirma el pago. Luego, haz click en **Completar pago de prueba** en la página de redireccionamiento. | #### Redireccionamientos bancarios | Método de pago | Escenario | Cómo hacer la prueba | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Débito directo BECS | Tu cliente paga satisfactoriamente con débito directo BECS. | Completa el formulario con el número de cuenta `900123456` y BSB `000000`. El PaymentIntent confirmado pasa en un principio al estado `processing` y, 3 minutos más tarde, a `succeeded`. | | Débito directo BECS | El pago de tu cliente falla con un código de error `account_closed`. | Completa el formulario con el número de cuenta `111111113` y BSB `000000`. | | Bancontact, EPS, iDEAL y Przelewy24 | Tu cliente no pasa la autenticación en la página de redireccionamiento de un método de pago basado en redireccionamiento y con notificación inmediata. | Elige cualquier método de pago basado en redireccionamiento, completa los datos solicitados y confirma el pago. Luego, haz click en **Error en el pago de prueba** en la página de redireccionamiento. | | Pay by Bank | Tu cliente paga satisfactoriamente con un método de pago basado en redireccionamiento y con [notificación diferida](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Elige el método de pago, completa los datos solicitados y confirma el pago. Luego, haz click en **Completar el pago de prueba** en la página de redireccionamiento. | | Pay by Bank | Tu cliente no pasa la autenticación en la página de redireccionamiento de un método de pago basado en redireccionamiento y con notificación diferida. | Elige el método de pago, completa los datos solicitados y confirma el pago. Luego, haz click en **Error en el pago de prueba** en la página de redireccionamiento. | | BLIK | Los pagos BLIK generan errores de varias maneras: errores inmediatos (por ejemplo, el código venció o no es válido), errores demorados (el banco lo rechaza) o tiempos de espera (el cliente no respondió a tiempo). | Usa patrones de correo electrónico para [simular los diferentes errores.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) | #### Débitos bancarios | Método de pago | Escenario | Cómo hacer la prueba | | ------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito directo SEPA | Tu cliente paga satisfactoriamente con débito directo SEPA. | Completa el formulario con el número de cuenta `AT321904300235473204`. El PaymentIntent confirmado pasa inicialmente al estado “en proceso” y, tres minutos más tarde, a “completado”. | | Débito directo SEPA | El estado del intento de pago de tu cliente pasa de `processing` a `requires_payment_method`. | Completa el formulario con el número de cuenta `AT861904300235473202`. | #### Vales | Método de pago | Escenario | Cómo hacer la prueba | | -------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | Boleto, OXXO | Tu cliente paga con un vale Boleto u OXXO. | Selecciona Boleto u OXXO como método de pago y envía el pago. Cierra el diálogo después de que aparezca. | Consulta [Pruebas](https://docs.stripe.com/testing.md) para obtener información adicional para probar tu integración. # SetupIntent migration > This is a SetupIntent migration for when integration-path is future. View the full page at https://docs.stripe.com/payments/payment-element/migration?integration-path=future. If your existing integration uses the [Setup Intents](https://docs.stripe.com/payments/setup-intents.md) API for future payments, follow the steps below to use the Payment Element. ## Enable payment methods > This integration path doesn’t support BLIK or pre-authorized debits that use the Automated Clearing Settlement System (ACSS). Also, if you create the deferred intent from the client-side, you can’t use `customer_balance` with dynamic payment methods because the PaymentIntent requires a customer-configured [Account](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer) or [Customer](https://docs.stripe.com/api/customers/object.md) object, which the client-side flow doesn’t support. To use `customer_balance`, create the `PaymentIntent` server-side with an `Account` or `Customer` and return its `client_secret` to the client. Visualiza tu [configuración de métodos de pago](https://dashboard.stripe.com/settings/payment_methods) y habilita los que quieras aceptar. Se necesita al menos un método de pago habilitado para crear un *SetupIntent* (The Setup Intents API lets you build dynamic flows for collecting payment method details for future payments. It tracks the lifecycle of a payment setup flow and can trigger additional authentication steps if required by law or by the payment method). De forma predeterminada, Stripe habilita tarjetas y otros métodos de pago habituales que pueden ayudarte a llegar a más clientes, pero te recomendamos activar otros métodos de pago que sean pertinentes para tu empresa y tus clientes. Consulta [Admisibilidad de métodos de pago](https://docs.stripe.com/payments/payment-methods/payment-method-support.md) para obtener información sobre productos y métodos de pago admitidos, y consulta nuestra [página de precios](https://stripe.com/pricing/local-payment-methods) para conocer las comisiones. ## Update Elements instance [Lado del cliente] Next, update your client-side code to pass the `mode` and `currency` when you create the Elements instance. For use with a SetupIntent, set the `mode` to `'setup'` and the `currency` to what you’ll charge your customer in the future. #### Javascript ### Before ```javascript const stripe = Stripe('<>'); const elements = stripe.elements(); ``` ### After ```javascript const stripe = Stripe('<>'); const options = { mode: 'setup', currency: 'usd', }; const elements = stripe.elements(options); ``` #### React ### Before ```jsx const stripePromise = loadStripe('<>'); function App() { return ( ); }; ``` ### After ```jsx const stripePromise = loadStripe('<>'); const options = { mode: 'setup', currency: 'usd', }; function App() { return ( ); }; ``` ## Optional: Additional Elements options [Lado del cliente] The [Elements object](https://docs.stripe.com/js/elements_object/create_without_intent) accepts additional options that influence payment collection. Based on the options provided, the Payment Element displays available payment methods from those you’ve enabled. Learn more about [payment method support](https://docs.stripe.com/payments/payment-methods/payment-method-support.md). Make sure the Elements options you provide (such as `captureMethod`, `setupFutureUsage`, and `paymentMethodOptions`) match the equivalent parameters you pass when creating and confirming the Intent. Mismatched parameters can result in unexpected behavior or errors. | Propiedad | Tipo | Descripción | Obligatorio | | ---------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `mode` | - `payment` - `setup` - `subscription` | Indica si el Payment Element se utiliza con un *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods), *SetupIntent* (The Setup Intents API lets you build dynamic flows for collecting payment method details for future payments. It tracks the lifecycle of a payment setup flow and can trigger additional authentication steps if required by law or by the payment method) o *Subscription* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis). | Sí | | `currency` | `string` | La moneda del importe a cobrar al cliente. | Sí | | `amount` | `number` | The amount to charge the customer, shown in Apple Pay, Google Pay, or BNPL UIs. | Para el modo `payment` y `subscription` | | `setupFutureUsage` | - `off_session` - `on_session` | Indicates that you intend to make future payments with the payment details collected by the Payment Element. | No | | `captureMethod` | - `automatic` - `automatic_async` - `manual` | Controla cuándo capturar los fondos de la cuenta del cliente. | No | | `onBehalfOf` | `string` | Connect only. The Stripe account ID, which is the business of record. See [use cases](https://docs.stripe.com/connect/charges.md) to determine if this option is relevant for your integration. | No | | `paymentMethodTypes` | `string[]` | A list of payment method types to render. You can omit this attribute to manage your payment methods in the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods). | No | | `paymentMethodConfiguration` | `string` | The [payment method configuration](https://docs.stripe.com/api/payment_method_configurations.md) to use when managing your payment methods in the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods). If not specified, your default configuration is used. | No | | `paymentMethodCreation` | `manual` | Allows PaymentMethods to be created from the Elements instance using [stripe.createPaymentMethod](https://docs.stripe.com/js/payment_methods/create_payment_method_elements). | No | | `paymentMethodOptions` | `{us_bank_account: {verification_method: string}}` | Verification options for the `us_bank_account` payment method. Accepts the same verification methods as [Payment Intents](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-us_bank_account-verification_method). | No | | `paymentMethodOptions` | `{card: {installments: {enabled: boolean}}}` | Allows manually enabling the card installment plan selection UI if applicable when you aren’t managing your payment methods in the [Stripe Dashboard](https://dashboard.stripe.com/settings/payment_methods). You must set `mode='payment'` *and* explicitly specify `paymentMethodTypes`. Otherwise an error is raised. Incompatible with `paymentMethodCreation='manual'`. | No | | `paymentMethodOptions` | `{[paymentMethod]: {setup_future_usage: string}}` | Allows you to specify `setup_future_usage` for only payment methods that support reuse. Only applicable when `mode` is `payment`. The value for each payment method must match the corresponding `payment_method_options[paymentMethod][setup_future_usage]` on the PaymentIntent during confirmation. See the [Stripe.js reference](https://docs.stripe.com/js/elements_object/create_without_intent#stripe_elements_no_intent-options-paymentMethodOptions) for supported payment methods and values. | No | ## Add the Payment Element [Lado del cliente] If you’re using [React Stripe.js](https://github.com/stripe/react-stripe-js), update to the latest package to use the Payment Element. You can now replace the Card Element and individual payment methods Elements with the Payment Element. The Payment Element automatically adjusts to collect input fields based on the payment method and country (for example, full billing address collection for SEPA Direct Debit) so you don’t have to maintain customized input fields anymore. The following example replaces `CardElement` with `PaymentElement`: #### JavaScript ```html
``` ```javascript const paymentElement = elements.create("payment"); paymentElement.mount("#payment-element"); ``` If your payment flow already always collects details like the customer’s name or email address, you can prevent the Payment Element from collecting this information by passing the [fields](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-fields) option when creating the Payment Element. If you disable the collection of a certain field, you must pass that same data back with [stripe.confirmSetup](https://docs.stripe.com/js/setup_intents/confirm_setup). ## Update your SetupIntent creation call [Lado del servidor] Because the Payment Element allows you to accept multiple payment methods, we recommend using `automatic_payment_methods`. When you enable it, Stripe evaluates the currency, payment method restrictions, and other parameters to determine the list of payment methods available for your customers. We prioritize payment methods that increase conversion and are most relevant to the currency and location of the customer. Add the `automatic_payment_methods` attribute to the endpoint on your server that creates the SetupIntent. Any of the additional elements options passed when creating the Elements group in the earlier step should also be passed when creating the SetupIntent. #### cURL ```bash curl https://api.stripe.com/v1/setup_intents \ -u <>: \ -H "Stripe-Version: 2026-05-27.dahlia" \ -d "customer"="{{CUSTOMER_ID}}" \-d "automatic_payment_methods[enabled]"=true ``` > You can’t save some payment methods for future payments. For more information, see [Payment method integration options](https://docs.stripe.com/payments/payment-methods/integration-options.md). ## Update the submit handler [Lado del cliente] Instead of using individual confirm methods like `stripe.confirmCardSetup` or `stripe.confirmP24Setup`, use [stripe.confirmSetup](https://docs.stripe.com/js/setup_intents/confirm_setup) to collect payment information and submit it to Stripe. To confirm the SetupIntent, make the following updates to your submit handler: - Call `await elements.submit()` to trigger form validation and collect any data required for [wallets](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-wallets). - Optional: Move SetupIntent creation to the submit handler. This way you only create the SetupIntent when the user is ready to submit their payment method details. - Pass the `elements` instance you used to create the Payment Element and the `clientSecret` from the SetupIntent as parameters to `stripe.confirmSetup`. When called, `stripe.confirmSetup` attempts to complete any [required actions](https://docs.stripe.com/payments/paymentintents/lifecycle.md), such as authenticating your customers by displaying a 3DS dialog or redirecting them to a bank authorization page. When confirmation is complete, users are directed to the `return_url` you configured, which normally corresponds to a page on your website that provides the status of the `SetupIntent`. If you want to keep the same flow for saving card payment details and only redirect for redirect-based payment methods, set [redirect](https://docs.stripe.com/js/setup_intents/confirm_setup#confirm_setup_intent-options-redirect) to `if_required`. The following code examples replaces `stripe.confirmCardSetup` with `stripe.confirmSetup`: ### Before ```javascript // Create the SetupIntent and obtain clientSecret const res = await fetch("/create-intent", { method: "POST", headers: {"Content-Type": "application/json"}, }); const {client_secret: clientSecret} = await res.json(); const handleSubmit = async (event) => { event.preventDefault(); if (!stripe) { // Stripe.js hasn't yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } setLoading(true); if (error) { handleError(error); } }; ``` ### After ```javascript const handleSubmit = async (event) => { event.preventDefault(); if (!stripe) { // Stripe.js hasn't yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } setLoading(true); // Trigger form validation and wallet collection const {error: submitError} = await elements.submit(); if (submitError) { handleError(submitError); return; } // Create the SetupIntent and obtain clientSecret const res = await fetch("/create-intent", { method: "POST", headers: {"Content-Type": "application/json"}, }); const {client_secret: clientSecret} = await res.json(); // Use the clientSecret and Elements instance to confirm the setup const {error} = await stripe.confirmSetup({ elements, clientSecret, confirmParams: { return_url: 'https://example.com/order/123/complete', }, // Uncomment below if you only want redirect for redirect-based payments // redirect: "if_required", }); if (error) { handleError(error); } }; ``` ## Probar la integración Usa datos de pago de prueba y la página de redireccionamiento de prueba para verificar tu integración. Haz click en las siguientes pestañas para ver los detalles de cada método de pago. #### Tarjetas | Método de pago | Escenario | Cómo hacer la prueba | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Tarjeta de crédito | La configuración de la tarjeta se realiza correctamente y no requiere *autenticación* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Completa nuestro formulario de tarjeta de crédito con el número de tarjeta `4242 4242 4242 4242` y la fecha de vencimiento, el CVC o el código postal. | | Tarjeta de crédito | La tarjeta requiere autenticación para la configuración inicial, pero no en los pagos sucesivos. | Completa nuestro formulario de tarjeta de crédito con el número de tarjeta `4000 0025 0000 3155` y cualquier fecha de vencimiento, CVC y código postal. | | Tarjeta de crédito | La tarjeta requiere autenticación para la configuración inicial y también requiere autenticación para los pagos sucesivos. | Completa nuestro formulario de tarjeta de crédito con el número de tarjeta `4000 0027 6000 3184` y cualquier fecha de vencimiento, CVC y código postal. | | Tarjeta de crédito | La tarjeta es rechazada durante la configuración. | Completa nuestro formulario de tarjeta de crédito con el número de tarjeta `4000 0000 0000 9995` y la fecha de vencimiento, el CVC o el código postal. | #### Redireccionamientos bancarios | Método de pago | Escenario | Cómo hacer la prueba | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bancontact | Tu cliente configura correctamente un método de pago con débito directo SEPA para uso futuro con Bancontact. | Usa cualquier nombre en el formulario de Bancontact y luego haz click en **Autorizar la configuración de prueba** en la página de redireccionamiento. | | Bancontact | Tu cliente no pasó la autenticación en la página de redireccionamiento de Bancontact. | Usa cualquier nombre en el formulario de Bancontact y luego haz click en **Error en la configuración de prueba** en la página de redireccionamiento. | | Débito directo BECS | Tu cliente paga correctamente con débito directo BECS. | Completa el formulario con el número de cuenta `900123456`. El estado `PaymentIntent` confirmado pasa inicialmente al estado `processing` y, tres minutos más tarde, a `succeeded`. | | Débito directo BECS | El pago de tu cliente falla con un código de error `account_closed`. | Completa el formulario con el número de cuenta `111111113`. | | iDEAL | Tu cliente configura correctamente un método de pago con [débito directo SEPA](https://docs.stripe.com/payments/sepa-debit.md) para uso futuro con iDEAL. | Usa cualquier nombre y banco en el formulario de iDEAL y luego haz click en **Autorizar configuración de prueba** en la página de redireccionamiento. | | iDEAL | Tu cliente no pasa la autenticación en la página de redireccionamiento de iDEAL. | Selecciona cualquier banco y usa cualquier nombre en el formulario de iDEAL. Luego, haz click en **Error en la configuración de prueba** en la página de redireccionamiento. | #### Débitos bancarios | Método de pago | Escenario | Cómo hacer la prueba | | ------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito directo SEPA | Tu cliente paga correctamente con débito directo SEPA. | Completa el formulario con el número de cuenta `AT321904300235473204`. El estado `PaymentIntent` confirmado pasa inicialmente al estado `processing` y, tres minutos más tarde, a `succeeded`. | | Débito directo SEPA | El estado `PaymentIntent` de tu cliente pasa de `processing` a `requires_payment_method`. | Completa el formulario con el número de cuenta `AT861904300235473202`. | ### Prueba de cargo a un PaymentMethod de débito SEPA guardado La confirmación del `SetupIntent` usando iDEAL, Bancontact o Sofort genera un [débito directo SEPA](https://docs.stripe.com/payments/sepa-debit.md) *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs). El débito directo SEPA es un método de pago de [notificación diferida](https://docs.stripe.com/payments/payment-methods.md#payment-notification) que pasa a un estado de `processing` intermedio antes de pasar a un estado `succeeded` o `requires_payment_method` varios días después. #### Correo electrónico Define `payment_method.billing_details.email` con uno de los siguientes valores para probar las transiciones de estado del `PaymentIntent`. Puedes incluir tu propio texto personalizado al inicio de la dirección de correo electrónico seguido de un guion bajo. Por ejemplo, `test_1_generatedSepaDebitIntentsFail@example.com` genera un PaymentMethod con débito directo SEPA que siempre da error cuando se usa con un `PaymentIntent`. | Dirección de correo electrónico | Descripción | | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `generatedSepaDebitIntentsSucceed@example.com` | El estado del `PaymentIntent`pasa de `processing` a `succeeded`. | | `generatedSepaDebitIntentsSucceedDelayed@example.com` | El estado del `PaymentIntent` pasa de `processing` a `succeeded` después de, al menos, tres minutos. | | `generatedSepaDebitIntentsFail@example.com` | El estado del `PaymentIntent` pasa de `processing` a `requires_payment_method`. | | `generatedSepaDebitIntentsFailDelayed@example.com` | El estado del `PaymentIntent` pasa de `processing` a `requires_payment_method` después de, al menos, tres minutos. | | `generatedSepaDebitIntentsSucceedDisputed@example.com` | El estado del `PaymentIntent` pasa de `processing` a `succeeded`, pero se crea inmediatamente una disputa. | | `generatedSepaDebitIntentsFailsDueToInsufficientFunds@example.com` | El estado del `PaymentIntent` pasa de `processing` a `requires_payment_method` con el código de error `inufficient_funds`. | #### PaymentMethod Usa estos PaymentMethods para probar que el `PaymentIntent` haga la transición. Estos tokens son útiles para que las pruebas automáticas adjunten un PaymentMethod al SetupIntent en el servidor. | Método de pago | Descripción | | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `pm_bancontact_generatedSepaDebitIntentsSucceed` | El estado del `PaymentIntent`pasa de `processing` a `succeeded`. | | `pm_bancontact_generatedSepaDebitIntentsSucceedDelayed` | El estado del `PaymentIntent` pasa de `processing` a `succeeded` después de, al menos, tres minutos. | | `pm_bancontact_generatedSepaDebitIntentsFail` | El estado del `PaymentIntent` pasa de `processing` a `requires_payment_method`. | | `pm_bancontact_generatedSepaDebitIntentsFailDelayed` | El estado del `PaymentIntent` pasa de `processing` a `requires_payment_method` después de, al menos, tres minutos. | | `pm_bancontact_generatedSepaDebitIntentsSucceedDisputed` | El estado del `PaymentIntent` pasa de `processing` a `succeeded`, pero se crea inmediatamente una disputa. | | `pm_bancontact_generadoSepaDebitIntentsFailsDueToInsufficientFunds` | El estado del `PaymentIntent` pasa de `processing` a `requires_payment_method` con el código de error `inufficient_funds`. |