# Stripe Payment Element Acepta métodos de pago de todo el mundo con un componente de interfaz de usuario seguro e integrable. 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 partidas, 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. 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();`. Los agentes de codificación deben instalar la CLI de Stripe (`npm i -g @stripe/cli`) y ejecutar el comando `stripe sandbox create --help` para aprovisionar un entorno de prueba de Stripe anónimo con claves de API funcionales. No se requiere registro de cuenta. Payment Element es un componente de la interfaz de usuario (IU) para la web que acepta más de 100 métodos de pago, valida las entradas de datos y gestiona los errores. Úsalo solo o con otros elementos en el front end de tu aplicación web. ## API compatibles Stripe recomienda utilizar la [API Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) con Payment Element. Esta integración te permite configurar pagos básicos con `price_data` o la lógica completa del proceso de compra con partidas individuales, impuesto, descuentos, envío, suscripciones o [Adaptive Pricing](https://docs.stripe.com/payments/currencies/localize-prices/adaptive-pricing.md). Crea una [página de confirmación de compra con la API Checkout Sessions](https://docs.stripe.com/payments/quickstart.md). Si necesitas controlar tu flujo de compra de principio a fin y crear estas funcionalidades tú mismo, puedes utilizar la [API Payment Intents](https://docs.stripe.com/api/payment_intents.md) con Payment Element. Esta integración te permite indicar un importe final y crear toda la lógica del proceso de compra por tu cuenta, incluido el cálculo de impuestos, descuentos, envío, suscripciones y conversión de monedas. Crea una [integración personalizada con la API Payment Intents](https://docs.stripe.com/payments/advanced.md). (See full diagram at https://docs.stripe.com/payments/payment-element) ```text [Checkout Sessions API] --> [Cliente] [Checkout Sessions API] --> [Envío] [Checkout Sessions API] --> [Impuestos] [Checkout Sessions API] --> [Descuentos y cupones] [Checkout Sessions API] --> [Pago] [API Payment Intents] --> [Pago] ``` ## Combina elementos El Payment Element interopera con otros elementos. Por ejemplo, este formulario usa un elemento adicional para [autocompletar los datos de la confirmación de compra](https://docs.stripe.com/payments/link.md) y otro para [recopilar la dirección de envío](https://docs.stripe.com/elements/address-element.md). ![Un formulario con información de contacto, dirección de envío y campos de pago. La información de contacto tiene la etiqueta Contact Details Element, la dirección de envío tiene la etiqueta Address Element y los campos de pago tienen la etiqueta Payment Element.](https://b.stripecdn.com/docs-statics-srv/assets/link-with-elements.d52f05825c982aaf84a4ad1e9bb422f3.png) Formulario de pago que combina múltiples elementos Para ver el código completo de este ejemplo, consulta [Agregar Link a una integración de Elements](https://docs.stripe.com/payments/link/add-link-elements-integration.md). También puedes combinar Payment Element con [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md). En este caso, los pagos con carteras digitales, como Apple Pay y Google Pay, solo se muestran en Express Checkout Element para evitar duplicaciones. ## Métodos de pago Stripe habilita ciertos métodos de pago para ti de forma predeterminada. También podríamos habilitar métodos de pago adicionales después de notificarte. Usa el [Dashboard](https://dashboard.stripe.com/settings/payment_methods) para activar o desactivar los métodos de pago en cualquier momento. Con el Payment Element, puedes usar [métodos de pago dinámicos](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md) para: - gestionar los métodos de pago en el [Dashboard](https://dashboard.stripe.com/settings/payment_methods) sin codificación; - mostrar de forma dinámica las opciones de pago que más corresponden en función de factores como la ubicación, la moneda y el importe de la transacción. Por ejemplo, si un cliente en Alemania paga en euros, ve todos los métodos de pago activos que aceptan esta moneda, y los primeros que se muestran son los que se usan ampliamente en Alemania. ![Una variedad de métodos de pago.](https://b.stripecdn.com/docs-statics-srv/assets/payment-element-methods.26cae03aff199d6f02b0d92bd324c219.png) Muestra los métodos de pago en orden de relevancia para tu cliente Para personalizar aún más cómo se procesan los métodos de pago, por ejemplo, filtrando las marcas de tarjetas y los tipos de fondos que no quieras admitir, consulta [Personaliza los métodos de pago](https://docs.stripe.com/payments/customize-payment-methods.md). Para agregar métodos de pago integrados fuera de Stripe, utiliza [métodos de pago personalizados](https://docs.stripe.com/payments/payment-element/custom-payment-methods.md). Si tu integración requiere que indiques los métodos de pago manualmente, consulta la sección [Lista manual de métodos de pago](https://docs.stripe.com/payments/payment-methods/integration-options.md#listing-payment-methods-manually). ## Diseño Puedes personalizar el diseño del Payment Element para que se ajuste a tu flujo de compra. En la siguiente imagen, se representa el mismo Payment Element con diferentes configuraciones de diseño. ![Ejemplos de los tres formularios de finalización de compra. En la imagen, se muestra la opción donde los clientes eligen los métodos de pago que aparecen en pestañas, o las dos opciones de acordeón, donde los métodos de pago aparecen verticalmente. En la vista de acordeón, puedes elegir mostrar los botones de opción o no.](https://b.stripecdn.com/docs-statics-srv/assets/pe_layout_example.525f78bcb99b95e49be92e5dd34df439.png) Payment Element con diferentes diseños. #### Pestañas El diseño de pestañas muestra los métodos de pago horizontalmente mediante pestañas. Para usar este diseño, establece el valor de [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) en `tabs`. También puedes especificar otras propiedades, como [layout.defaultCollapsed](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-defaultCollapsed). ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */ }; const options = { layout: { type: 'tabs', defaultCollapsed: false, } }; const elements = stripe.elements({ clientSecret, appearance }); // En una integración de trabajo, este es un valor que tu back-end especifica con datos como el importe de un pago. Consulta el ejemplo completo para obtener más detalles. const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` #### Acordeón con botones de opción El diseño de acordeón muestra los métodos de pago verticalmente mediante un acordeón. Para usar este diseño, establece el valor para [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) en `accordion`. También puedes especificar otras propiedades, como [layout.radios](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-radios) para mostrar los botones de opción. ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */ }; const options = { layout: { type: 'accordion', defaultCollapsed: false, radios: 'always', spacedAccordionItems: false } }; const clientSecret = {{CLIENT_SECRET}}; // En una integración de trabajo, este es un valor que tu back-end especifica con datos como el importe de un pago. Consulta el ejemplo completo para obtener más detalles. const elements = stripe.elements({ clientSecret, appearance }); const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` #### Acordeón sin botones de opción El diseño de acordeón muestra los métodos de pago verticalmente mediante un acordeón. Para usar este diseño, establece el valor para [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) en `accordion`. También puedes especificar otras propiedades, como [layout.spacedAccordionItems](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-spacedAccordionItems) para crear más espacio vertical. ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */ }; const options = { layout: { type: 'accordion', defaultCollapsed: false, radios: 'never', spacedAccordionItems: true } }; const clientSecret = {{CLIENT_SECRET}}; // En una integración de trabajo, este es un valor que tu back-end especifica con datos como el importe de un pago. Consulta el ejemplo completo para obtener más detalles. const elements = stripe.elements({ clientSecret, appearance }); const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` ## Appearance Usa la API Appearance para controlar el estilo de todos los elementos. Elige un tema o actualiza los detalles específicos. ![Ejemplos de modos claros y oscuros para el formulario de finalización de compra del elemento de pago.](https://b.stripecdn.com/docs-statics-srv/assets/appearance_example.e076cc750983bf552baf26c305e7fc90.png) Por ejemplo, elige el tema «plano» y sustituye el color del texto principal. ```javascript const stripe = Stripe('<>'); const appearance = { theme: 'flat', variables: { colorPrimaryText: '#262626' } }; const options = { /* options */ }; const elements = stripe.elements({ clientSecret, appearance }); // En una integración de trabajo, este es un valor que tu back-end especifica con datos como el importe de un pago. Consulta el ejemplo completo para obtener más detalles. const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` Consulta la documentación de la [API Appearance](https://docs.stripe.com/elements/appearance-api.md) para ver una lista completa de temas y variables. ## Opciones Los elementos de Stripe admiten más opciones que estas. Por ejemplo, puedes mostrar el nombre de tu empresa con la opción [business](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business). ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */}; const options = { business: { name: "RocketRides" } }; const clientSecret = {{CLIENT_SECRET}}; // En una integración de trabajo, este es un valor que tu back-end especifica con datos como el importe de un pago. Consulta el ejemplo completo para obtener más detalles. const elements = stripe.elements(appearance, clientSecret); const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` El Payment Element admite las siguientes opciones. Para obtener más información, consulta la entrada de referencia de cada opción. | | | [layout](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) | Diseño para el Payment Element. | | [defaultValues](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-defaultValues) | Información inicial del cliente para mostrar en el Payment Element. | | [business](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business) | Información sobre tu empresa para mostrarla en el Payment Element. | | [paymentMethodOrder](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-paymentMethodOrder) | Orden en el que deben aparecer los métodos de pago. | | [fields](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-fields) | Si ciertos campos se mostrarán. | | [readOnly](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-readOnly) | Si los datos de pago pueden modificarse. | | [condiciones](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-terms) | Si los mandatos u otros contratos legales se muestran en el Payment Element. Según el comportamiento predeterminado, se muestran solo cuando sea necesario. | | [carteras](https://docs.stripe.com/js/elements_object/create_payment_element) | Si se mostrarán o no billeteras como Apple Pay o Google Pay. Según el valor predeterminado, se muestran cuando sea posible. | ## Errores Payment Element muestra automáticamente mensajes de error localizados dirigidos al cliente durante la confirmación del cliente para los siguientes códigos de rechazo: - `card_declined` - `card_velocity_exceeded` - `expired_card` - `fraudulent` - `generic_decline` - `incorrect_cvc` - `incorrect_number` - `incorrect_zip` - `insufficient_funds` - `invalid_cvc` - `invalid_expiry_month` - `invalid_expiry_year` - `live_mode_test_card` - `lost_card` - `processing_error` - `stolen_card` - `test_mode_live_card` Para mostrar mensajes de otros tipos de errores, consulta [Códigos de error](https://docs.stripe.com/error-codes.md) y [gestión de errores](https://docs.stripe.com/error-handling.md). ## Migrar al Payment Element Elige una guía de migración según tu integración actual y la forma en que quieras gestionar tu flujo de compra. Te recomendamos [migrar a Payment Element con la API Checkout Sessions](https://docs.stripe.com/payments/payment-element/migration-ewcs.md), donde reemplazas Card Element o los Elements de métodos de pago individuales por Payment Element. Esta ruta te permite usar el soporte integrado para suscripciones, impuestos, descuentos, envíos y Adaptive Pricing. Si necesitas conservar tu lógica actual del proceso de compra y gestionar las funcionalidades del proceso de compra por tu cuenta, puedes [migrar a Payment Element con la API Payment Intents](https://docs.stripe.com/payments/payment-element/migration.md). Con esta ruta, reemplazas Card Element o los Elements de métodos de pago individuales por Payment Element mientras sigues usando la API Payment Intents o la API Setup Intents. La guía de migración incluye rutas distintas para aceptar pagos y guardar datos de pago para su uso futuro.