Elements con el registro de cambios en versión beta de la API Checkout Sessions

Realiza un seguimiento de los cambios en Elements con la integración beta de la API Checkout Sessions.

Advertencia

Este documento contiene registros de cambios relacionados con las versiones beta de Elements con la API Checkout Sessions.

Si ya estás en la versión Clover de Elements con la API Checkout Sessions, este registro de cambios no te afecta.

Migración a Clover

Cambios en Clover

Breaking El método Stripe.initCheckout ahora es sincrónico en lugar de asincrónico. Esto reduce la latencia de renderizado y permite que Elements muestre los cargadores de esqueleto antes. Consulta Actualizaciones de initCheckout para que sea sincrónico para obtener más detalles sobre la migración.
Breaking Los métodos de pago guardados ahora se habilitan automáticamente en el elemento de pago cuando se configuran en la sesión de pago, sin necesidad de configuración adicional del lado del cliente. Consulta Actualizción del comportamiento predeterminado de métodos de pago guardados para obtener más detalles.
Breaking Los códigos postales ya no se recopilan automáticamente para los pagos con tarjeta en Canadá, El Reino Unido y Puerto Rico. Consulta Eliminación del código postal para los pagos con tarjeta si depende de estos datos.
Breaking Para integraciones con React:
- Las rutas de importación han cambiado de @stripe/react-stripe-js a @stripe/react-stripe-js/checkout.
- useCheckout now returns a disjoint union describing the asynchronous state ({type: 'loading'}, {type: 'success', checkout: ...}, or {type: 'error', error: ...}) instead of throwing an error.
- CheckoutProvider now renders children unconditionally instead of rendering null when initCheckout hasn’t succeeded.

Actualización de Clover

Antes de migrar a Clover, primero actualiza tu integración a Basil.

Si usas algún paquete de Stripe NPM, debes actualizar @stripe/stripe-js al menos a8.0.0 y @stripe/react-stripe-js al menos a 5.0.0.
Si estás cargando Stripe.js a través de la etiqueta de script, actualiza la etiqueta para hacer referencia a clover usando la nomenclatura versionada de Stripe.js de la siguiente manera:

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Actualiza la versión de API para que sea al menos 2025-09-30.clover en tu integración de back-end.

Actualiza tu integración de la siguiente manera:

Elimina las llamadas en await o .then() asociadas a initCheckout.
Reemplaza tu función fetchClientSecret con una cadena secreta de cliente o Promise que se resuelva en una cadena secreta de cliente.
Llama la nueva función asincrónica checkout.loadActions() para acceder a acciones como getSession(), que reemplaza a session(), o confirm(). Solo tienes que llamar loadActions() una vez.
Si anteriormente envolviste initCheckout en un bloque try...catch, examina el valor de tipo resuelto de loadActions() para verificar si hay errores.

checkout.js
const clientSecret = fetch("/create-checkout-session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
})
  .then((r) => r.json())
  .then((r) => r.clientSecret);

const checkout = await stripe.initCheckout({
  fetchClientSecret: () => clientSecret
});
const checkout = stripe.initCheckout({
  clientSecret
});
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");

const session = checkout.session();
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  const session = loadActionsResult.actions.getSession();
}

Para obtener más detalles, consulta la entrada del registro de cambiosActualizaciones de initCheckout para que sea sincrónico.

Cómo migrar a Basil

Cambios en Basil

Breaking Los métodos asincrónicos, como confirm o applyPromotionCode, se resuelven con un esquema diferente:
- Si se realiza correctamente, el estado actualizado de la sesión se completa con la clave session. Antes, esto figuraba en la clave success.
Breaking Ahora se produce un error al especificar returnUrl en confirm cuando return_url ya se configuró en la Checkout Session.
Breaking La URL de retorno a la que se redirigió después de una confirmación correcta antes tenía parámetros de consulta incoherentes. Ahora se eliminaron los parámetros adicionales, y la URL solo contiene lo que se proporciona en returnUrl en confirm o return_url en la Checkout Session.
Breaking Mejora la latencia en la API Checkout Session para las sesiones en modo de suscripción y corrige un error que impedía a tus clientes actualizar una sesión después del primer intento de pago.
- El cambio crea la suscripción después de que el usuario haya completado el pago, por lo que checkout_session.invoice y checkout_session.subscription son nulos hasta que se complete la sesión de Checkout.
- Si actualmente usas el campo obsoleto payment_intent.invoice, te recomendamos que utilices el webhook checkout_session.completed, que garantiza la presencia de la factura, y checkout_session.invoice o la lista de pago de facturas para encontrar la factura asociada.
- Para obtener más información, lee el registro de cambios de la API 2025-03-31.basil.
Se agregó percentOff a discountAmounts como una opción para mostrar descuentos.

Actualización de Basil

Antes de migrar a Basil, primero actualiza tu integración a custom_checkout_beta_6.

Si usas alguno de los paquetes de NPM de Stripe, primero debes actualizar @stripe/stripe-js al menos a 7.0.0 y @stripe/react-stripe-jsal menos a 3.6.0.
Si estás cargando Stripe.js a través de la etiqueta de script y sigues usando v3 o acacia, actualiza la etiqueta a basil usando la nomenclatura Stripe.js versionada como se indica a continuación:

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/stripe.js"></script>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Elimina el encabezado beta de Stripe.js al inicializar Stripe.js.

checkout.js
const stripe = Stripe(
  'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_beta_6'],
  }
);

Quita el encabezado de la versión beta de la API y especifica que la versión de la API sea al menos 2025-03-31.basil en tu integración del back-end.

Antes

Después

Registro de cambios de la versión beta

Elements con la versión beta de la API Checkout Sessions utiliza dos tipos de versiones beta:

Un encabezado Stripe.js beta (por ejemplo, custom_checkout_beta_6), que se configura en tu integración front-end.
Un encabezado de versión beta de la API (por ejemplo, custom_checkout_beta=v1), que se configura en tu integración de back-end.

Versiones beta del front-end

Especifica la versión beta del front-end cuando inicialices Stripe.js.

custom_checkout_beta_6

Si usas alguno de los paquetes de NPM de Stripe, primero debes actualizar @stripe/stripe-js al menos a 6.1.0 y '@stripe/react-stripe-jsal menos a “3.5.0.

Breaking Se ha invertido el signo de total.appliedBalance. Un número positivo ahora aumenta el monto a pagar y un número negativo lo disminuye.
Breaking Se reemplazó clientSecret por fetchClientSecret Actualiza tu integración para pasar una función asincrónica que resuelva el secreto de cliente en lugar de pasar un valor estático.
Breaking Se ha cambiado el nombre de los métodos de Elements.
- Si estás usando React Stripe.js, no necesitas hacer nada más que actualizar @stripe/react-stripe-js
- Si estás usando HTML/JS:
  - Usa createPaymentElement() en lugar de createElement('payment').
  - Usa createBillingAddressElement() en lugar de createElement('address', {mode: 'billing'}).
  - Usa createShippingAddressElement() en lugar de createElement('address', {mode: 'shipping'}).
  - Usa createExpressCheckoutElement() en lugar de createElement('expressCheckout').
  - Usa getPaymentElement() en lugar de getElement('payment').
  - Usa getBillingAddressElement() en lugar de getElement('address', {mode: 'billing'}).
  - Usa getShippingAddressElement() en lugar de getElement('address', {mode: 'shipping'}).
  - Usa getExpressCheckoutElement() en lugar de getElement('expressCheckout').
Breaking Se actualizaron los campos relacionados con la confirmación para reflejar con mayor precisión el estado de la sesión.
- canConfirm ahora responde a cualquier Billing Address Element o Shipping Address Element montado.
- canConfirm ahora se convierte en false si hay una confirmación en tránsito.
- Se ha eliminado confirmationRequirements.
Breaking updateEmail ahora arroja un error si se proporcionó customer_email al crear la sesión de Checkout. Si tienes la intención de completar previamente un correo electrónico que tu cliente pueda actualizar, llama a updateEmail apenas se cargue la página en lugar de pasar customer_email.
Breaking returnUrl debe ser una URL absoluta (por ejemplo, comienza con https:// en lugar de una URL relativa, como /success).
Breaking Se actualizaron los campos de precios a un objeto anidado para facilitar la representación.
- Se reemplazaron los valores numéricos por un objeto que contiene amount (una cadena de moneda con formato, como $10.00) y minorUnitsAmount, un número entero que representa el valor en la unidad más pequeña de la moneda. Si ya estás leyendo el importe, lee en su lugar desde minorUnitsAmount.
  - Por ejemplo, reemplaza total.total por total.total.minorUnitsAmount.
- Debes leer total.total.amount o cada uno de total.total.minorUnitsAmount, currency y minorUnitsAmountDivisor en el objeto checkout y mostrarlo en tu interfaz de usuario. De lo contrario, se producirá un error. Esto ayuda a mantener tu página de confirmación de compra sincronizada a medida que se actualiza la CheckoutSession, incluida la adición de futuras funcionalidades de Stripe, con cambios mínimos en el código de la interfaz de usuario.
Ahora se pueden recopilar las identificaciones fiscales de los clientes. Aprende a recopilar identificaciones fiscales.
En la parte inferior de la página de confirmación de compra, ahora hay disponible un asistente solo para el modo de prueba, que ofrece orientación para la integración y accesos directos para escenarios de prueba comunes.

custom_checkout_beta_5

Breaking Se renombró la función initCustomCheckout como initCheckout
- Dentro de React Stripe. js, se renombró al CustomCheckoutProvider como CheckoutProvider y a useCustomCheckout como useCheckout.
Rompiendo Para confirmar el Express Checkout Element, llama a confirm, pasando el evento confirm como expressCheckoutConfirmEvent.
- Anteriormente, Express Checkout Element se confirmaba llamando a event.confirm().
Breaking Cuando se llama a confirm, el Payment Element y Address Element validarán las entradas del formulario y representarán cualquier error.
Breaking Los mensajes de error se han estandarizado y mejorado.
- Los errores devueltos/resueltos por una función representan escenarios conocidos, como datos de pago no válidos o fondos insuficientes. Se trata de problemas predecibles que se pueden comunicar a tu cliente mostrando el message en la página de pago.
- Los errores arrojados/rechazados por una función representan errores en la propia integración, como parámetros o configuración no válidos. Estos errores no están pensados para mostrarse a tus clientes.
Breaking Los métodos asincrónicos, como confirm o applyPromotionCode, se resuelven con un esquema diferente:
- Se agregó un campo discriminador type="success"|"error".
- Si se realiza correctamente, el estado de sesión actualizado se completa automáticamente en la clave success. Anteriormente, esto se encontraba en la clave session.
- De lo contrario, el error se sigue completando automáticamente en la clave error.
Se agregaron las opciones email, phoneNumber, billingAddress y shippingAddress a confirm.
Breaking Address Element ya no actualiza automáticamente los campos billingAddress o shippingAddress en la sesión.
- Siempre que Address Element esté montado, los valores del formulario se usarán automáticamente al llamar a confirm.
- Escucha el evento de cambio para usar el valor del Address Element antes de la confirmación.

custom_checkout_beta_4

Se agregaron imágenes al objeto Session.
Se agregaron campos como una opción al crear el Payment Element.
Se agregó paymentMethods como una opción al crear Express Checkout Element.
Breaking Si pasas opciones no válidas a createElement, ahora se produce un error. Anteriormente, las opciones no reconocidas se ignoraban en silencio.
Breaking updateEmail y updatePhoneNumber aplican los cambios de forma asincrónica. Llamar a estos métodos antes de que el cliente termine de escribir los valores completos puede provocar un rendimiento deficiente.
- En lugar de llamar a updateEmail o updatePhoneNumber en el evento de cambio de cada entrada, espera hasta que tu cliente termine la entrada, por ejemplo, en el desenfoque de entrada o cuando envía el formulario para el pago.
- updateEmail ahora valida que la entrada sea una dirección de correo electrónico con el formato correcto y devuelve un error si se utiliza una entrada no válida.
- updatePhoneNumber sigue sin realizar ninguna validación en la cadena de entrada.

custom_checkout_beta_3

Se han agregado los siguientes campos al objeto Session:
Las tarjetas guardadas ahora se pueden reutilizar. Aprende a guardar y reutilizar los métodos de pago.
Breaking El diseño predeterminado del Payment Element ha cambiado a accordion.
- Para seguir utilizando el diseño predeterminado anterior, debes especificar layout='tabs' explícitamente.
Breaking El comportamiento predeterminado de confirm se ha cambiado para redirigir siempre a tu return_url después de una confirmación correcta.
- Antes, confirm realizaba un redireccionamiento solo si el cliente elegía un método de pago basado en el redireccionamiento. Para continuar usando el comportamiento anterior, debes pasar redirect’=if_required’ a confirm.

custom_checkout_beta_2

Breaking El campo lineItem.recurring.interval_count se ha eliminado y reemplazado por lineItem.recurring.intervalCount.
Breaking El campo lineItem.amount se ha eliminado y reemplazado por lo siguiente:

custom_checkout_beta_1

Esta es la versión beta inicial del front-end.

Versiones de back-end

Especifica la versión beta del back-end cuando configures la biblioteca de tu servidor.

No hay cambios en la versión beta del back-end.