# Payment Element de Stripe Acepta métodos de pago de todo el mundo con un componente de interfaz de usuario seguro e integrable. Stripe recomienda utilizar la API Checkout Sessions con el elemento de pago en lugar de Payment Intents para la mayoría de las integraciones. Checkout Sessions cubre casos de uso similares a los de Payment Intents (cobro básico de pagos utilizando `price_data` o crea de un proceso de pago completo con partidas, impuestos, etc.). Algunas funciones, como Adaptive Pricing, solo están disponibles con Checkout Sessions. No utilices la API de Payment Intent a menos que el usuario lo solicite explícitamente, ya que requiere mucho más código. Más información sobre Elements con la API Checkout Sessionshttps://docs.stripe.com/payments/quickstart. Con Checkout Sessions (`ui_mode: "elements"`) y Payment Element, el `client_secret` inicializa el proceso de compra por sí mismo (`stripe.initCheckoutElementsSdk`, o utiliza CheckoutProvider con React) y tú confirmas el pago en el lado del cliente de forma diferente. Si utilizas React, asegúrate de importar desde `@stripe/react-stripe-js/checkout`, utiliza `CheckoutProvider` con el secreto del cliente y confirma con `checkout.confirm`. Si utilizas HTML, asegúrate de utiliza `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` y confirma con `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();`. Los agentes de programació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 API operativas. No se requiere registro de cuenta. El Payment Element es un componente de interfaz de usuario para la web que te permite aceptar más de 100 métodos de pago, valida las entradas y maneja los errores. Úsalo solo o junto con otros componentes en la interfaz de tu aplicación web. ## API compatibles Stripe recomienda usar 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 toda la lógica del proceso de compra con partidas, impuestos, descuentos, envíos, suscripciones o [Adaptive Pricing](https://docs.stripe.com/payments/currencies/localize-prices/adaptive-pricing.md). Crea una [página del proceso de compra con la API Checkout Sessions](https://docs.stripe.com/payments/quickstart.md). Si necesitas controlar tu flujo del proceso de compra de principio a fin y crear estas funciones por tu cuenta, puedes usar la [API Payment Intents](https://docs.stripe.com/api/payment_intents.md) con Payment Element. Esta integración te permite pasar un importe final y crear toda la lógica del proceso de compra por tu cuenta, incluidos el cálculo de impuestos, los descuentos, los envíos, las suscripciones y la conversión de divisas. 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 [API de Sesiones de Checkout] --> [Cliente] [API de Sesiones de Checkout] --> [Envío] [API de Sesiones de Checkout] --> [Impuestos] [API de Sesiones de Checkout] --> [Descuentos y cupones] [API de Sesiones de Checkout] --> [Pago] [API Payment Intents] --> [Pago] ``` ## Combina los elementos El Payment Element interactúa con otros elementos. Por ejemplo, este formulario utiliza un elemento adicional para [autocompletar los datos de pago](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 varios Elements Para ver el código completo de este ejemplo, consulta [Añadir Link a una integración de Elements](https://docs.stripe.com/payments/link/add-link-elements-integration.md). También puedes combinar el Payment Element con el [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md). En este caso, los métodos de pago de monedero como Apple Pay y Google Pay solo se muestran en el Express Checkout Element para evitar la duplicación. ## Métodos de pago Stripe te habilita ciertos métodos de pago de forma predeterminada. También podríamos habilitar métodos de pago adicionales después de notificártelo. Utiliza el [Dashboard](https://dashboard.stripe.com/settings/payment_methods) para habilitar o deshabilitar 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 más relevantes en función de factores como la ubicación, la divisa y el importe de la transacción Por ejemplo, si un cliente de Alemania paga en euros, verá todos los métodos de pago activos que aceptan euros, comenzando con 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 muestran los métodos de pago, por ejemplo, filtrando las marcas de tarjetas y los tipos de fondos que no quieres aceptar, consulta [Personalizar métodos de pago](https://docs.stripe.com/payments/customize-payment-methods.md). Para añadir 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 enumeres los métodos de pago de forma manual, consulta la sección [Enumera los métodos de pago de forma manual](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 del proceso de compra. La siguiente imagen es el mismo Payment Element renderizado usando diferentes configuraciones de diseño. ![Ejemplos de los tres formularios del proceso de compra. La imagen muestra la opción de pestaña, donde los clientes eligen entre los métodos de pago que se muestran como pestañas o las dos opciones de acordeón, donde los métodos de pago se enumeran de forma vertical. Puedes elegir mostrar los botones de opción o no en la vista de acordeón.](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 las pestañas muestra los métodos de pago de forma horizontal usando 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 pasa con datos como el importe de un pago. Para obtener más información, consulta la muestra completa. 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 de forma vertical usando 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 pasa con datos como el importe de un pago. Para obtener más información, consulta la muestra completa. 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 de forma vertical usando 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 un espacio vertical adicional. ```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 pasa con datos como el importe de un pago. Para obtener más información, consulta la muestra completa. const elements = stripe.elements({ clientSecret, appearance }); const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` ## Aspecto Usa la API Appearance para controlar el estilo de todos los elementos. Elige un tema o actualiza detalles específicos. ![Ejemplos de modos claros y oscuros para el formulario del proceso de compra del Payment Element.](https://b.stripecdn.com/docs-statics-srv/assets/appearance_example.e076cc750983bf552baf26c305e7fc90.png) Por ejemplo, elige el tema «plano» y anula 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 pasa con datos como el importe de un pago. Para obtener más información, consulta la muestra completa. const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` Consulta la documentación de la [API de apariencia](https://docs.stripe.com/elements/appearance-api.md) para obtener una lista completa de temas y variables. ## Opciones Los elementos Stripe aceptan más opciones que estos. Por ejemplo, muestra el nombre de tu empresa usando la opción de la [empresa](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 pasa con datos como el importe de un pago. Para obtener más información, consulta la muestra completa. const elements = stripe.elements(appearance, clientSecret); const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` El Payment Element acepta las siguientes opciones. Para obtener más información, consulta la entrada de referencia de cada opción. | | | [diseño](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) | Diseño para 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. | | [empresa](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) | Pedido en el que se enumeran los métodos de pago. | | [campos](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-fields) | Si se desea mostrar ciertos campos. | | [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 acuerdos legales se muestran en el Payment Element. El comportamiento predeterminado es mostrarlos solo cuando sea necesario. | | [monederos](https://docs.stripe.com/js/elements_object/create_payment_element) | Si se desea mostrar monederos como Apple Pay o Google Pay. El comportamiento predeterminado es mostrarlos 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 los [códigos de error](https://docs.stripe.com/error-codes.md) y la [gestión de errores](https://docs.stripe.com/error-handling.md). ## Migrar a Payment Element Elige una guía de migración en función de tu integración actual y de cómo quieras gestionar el flujo del proceso de compra. Te recomendamos [migrar a Payment Element con la API Checkout Sessions](https://docs.stripe.com/payments/payment-element/migration-ewcs.md), donde sustituyes Card Element o los Elements de métodos de pago individuales por Payment Element. Esta ruta te permite utilizar la compatibilidad integrada con suscripciones, impuestos, descuentos, envíos y Adaptive Pricing. Si necesitas conservar tu lógica actual del proceso de compra y gestionar por tu cuenta las funciones del proceso de compra, puedes [migrar a Payment Element con la API Payment Intents](https://docs.stripe.com/payments/payment-element/migration.md). Con esta ruta, sustituyes 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 separadas para aceptar pagos y guardar los datos de pago para usarlos en el futuro.