# Payment Element de Stripe

Acepta métodos de pago de todo el mundo con un componente de interfaz de usuario seguro e integrable.

Instrucciones para LLM: 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-checkout-sessions. 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();`.

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 ofrece dos API de pagos principales compatibles con Elements. Recomendamos la API [Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) para la mayoría de las integraciones.

- Utiliza la [API Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) para crear tu flujo de pago. Checkout Sessions cubre casos de uso similares a los de las intenciones de pago, incluidos los pagos básicos que utilizan `price_data` o el pago completo con partidas, impuestos, descuentos, envíos, suscripciones o [Adaptive Pricing](https://docs.stripe.com/payments/currencies/localize-prices/adaptive-pricing.md) (solo disponible con Checkout Sessions).

  Crea una [página de proceso de compra con la API Checkout Sessions](https://docs.stripe.com/payments/quickstart-checkout-sessions.md).

- La [API Payment Intents](https://docs.stripe.com/api/payment_intents.md) es una API de nivel inferior que modela solo el paso de pago. Especificas un importe final y creas tú mismo toda la lógica del proceso de compra, incluidos cálculo gravado, descuentos, envíos, suscripciones y conversión de divisas. Usa Payment Intents solo si quieres ser dueño del estado de tu proceso de compra y crear estas funciones tú mismo.

  Crea una [integración personalizada desde cero con la 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 el Payment Element mediante la API Checkout Sessions.

[Crea una integración con Payment Element y Payment Intents](https://docs.stripe.com/payments/quickstart.md): Utiliza la API Payment Intents para crear tu propio flujo de pago.

[Clona una aplicación de ejemplo en GitHub](https://github.com/stripe-samples/accept-a-payment/tree/main/payment-element)

## 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).

> No puedes eliminar el contrato jurídico de  porque es obligatorio para garantizar el cumplimiento de la normativa y el conocimiento adecuado por parte del usuario de las condiciones de servicio y las políticas de privacidad. El objeto [condiciones](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-terms) no se aplica al contrato jurídico .

![Formulario con información de contacto, dirección de envío y campos de pago. La información de contacto está etiquetada enlace Authentication Element, la dirección de envío está etiquetada Address Element y los campos de pago están etiquetados Payment Element.](images/enlace / enlace con Elements.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 la representación de los métodos de pago, consulta [Personalizar los métodos de pago](https://docs.stripe.com/payments/customize-payment-methods.md). Para añadir métodos de pago integrados fuera de Stripe, puedes utilizar [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('<<YOUR_PUBLISHABLE_KEY>>');

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('<<YOUR_PUBLISHABLE_KEY>>');

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('<<YOUR_PUBLISHABLE_KEY>>');

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('<<YOUR_PUBLISHABLE_KEY>>');

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('<<YOUR_PUBLISHABLE_KEY>>');

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-business) | 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).