# Stripe Payment Element Acepta métodos de pago de todo el mundo con un componente de interfaz de usuario seguro e integrable. 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();`. 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 ofrece dos API principales de pagos compatibles con Elements. Recomendamos la [API de Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) para la mayoría de las integraciones. - Usa la [API de Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) para crear tu flujo de compra. Checkout Sessions cubre casos de uso similares a Payment Intents, incluidos pagos básicos mediante `price_data` o un proceso de pago completo con partidas en la orden, impuestos, descuentos, envío, suscripciones o [Adaptive Pricing](https://docs.stripe.com/payments/currencies/localize-prices/adaptive-pricing.md) (solo disponible con Checkout Sessions). Construye una [página de pago con la API de Checkout Sessions](https://docs.stripe.com/payments/quickstart-checkout-sessions.md). - La [API Payment Intents es una API](https://docs.stripe.com/api/payment_intents.md) de nivel más bajo que modela únicamente el paso del pago. Indica el importe final y crea toda la lógica del proceso de compra, incluido el cálculo de impuestos, descuentos, envío, suscripciones y conversión de monedas. Usa Payment Intents solo si quieres tener un control completo sobre el estado de tu proceso de pago y crear estas funcionalidades por cuenta propia. Crea una [integración personalizada desde cero con API Payment Intents](https://docs.stripe.com/payments/advanced.md). (See full diagram at https://docs.stripe.com/payments/payment-element) [Crea una integración avanzada con Payment Element y Checkout Sessions](https://docs.stripe.com/payments/quickstart-checkout-sessions.md): Crea una integración con Payment Element mediante la API de sesiones de Checkout. [Crea una integración en Payment Element y Payment Intents](https://docs.stripe.com/payments/quickstart.md): Usa la API Payment Intents para crear tu propio flujo de compra. [Clonación de una aplicación de ejemplo en GitHub](https://github.com/stripe-samples/accept-a-payment/tree/main/payment-element) ## 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). > No puedes eliminar el contrato legal Link porque es necesario para garantizar el cumplimiento de la normativa y el conocimiento adecuado por parte del usuario de las Condiciones de uso y las políticas de privacidad. Las [Condiciones](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-terms) objeto no se aplican al contrato legal Link. ![Un formulario con información de contacto, dirección de envío y campos de pago. La información de contacto se etiqueta como Link Authentication Element, la dirección de envío como Address Element y los campos de pago como Payment Element.](https://b.stripecdn.com/docs-statics-srv/assets/link-with-elements.f60af275f69b6e6e73c766d1f9928457.png) Formulario de pago que combina varios 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 los métodos de pago, consulta [Personalizar métodos de pago](https://docs.stripe.com/payments/customize-payment-methods.md). Para agregar métodos de pago integrados fuera de Stripe, puedes usar [métodos de pago Custom](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-business) | 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).