# 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.
> Este documento contiene registros de cambios relacionados con las versiones beta de Elements con la API Checkout Sessions.
>
> Este registro de cambios no se aplica a ti si estás en [Clover](https://docs.stripe.com/changelog/clover.md) o posterior. En su lugar, consulta el [registro de cambios de Stripe](https://docs.stripe.com/changelog.md).
## Migración a Clover
### Cambios en Clover
- (Breaking) El método [Stripe.initCheckout](https://docs.stripe.com/js/custom_checkout/init) 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](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md) 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](https://docs.stripe.com/changelog/clover/2025-09-30/custom-checkout-saved-payment-method-defaults.md) 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 ](https://docs.stripe.com/changelog/clover/2025-09-30/postal_code_in_card_form_for_non_us_countries.md) 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](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) ahora devuelve una unión disjunta que describe el estado asincrónico (`{type: 'loading'}`, `{type: 'success', checkout: ...}` o `{type: 'error', error: ...}`) en lugar de arrojar un error.
- [CheckoutProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider) ahora representa a los niños de manera incondicional en lugar de representar `null` cuando [initCheckout](https://docs.stripe.com/js/custom_checkout/init) no se ha realizado correctamente.
### Actualización de Clover
Antes de migrar a Clover, primero [actualiza tu integración](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#migrating-to-basil) a Basil.
- Si usas algún paquete de Stripe NPM, debes actualizar `@stripe/stripe-js` al menos a`8.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 ](https://docs.stripe.com/sdks/stripejs-versioning.md) de la siguiente manera:
```html
Checkout
```
- Actualiza la versión de API para que sea al menos `2025-09-30.clover` en tu integración de back-end.
#### HTML + JS
Actualiza tu integración de la siguiente manera:
1. Elimina las llamadas en `await` o `.then()` asociadas a `initCheckout`.
1. Reemplaza tu función `fetchClientSecret` con una cadena secreta de cliente o Promise que se resuelva en una cadena secreta de cliente.
1. 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.
1. Si anteriormente envolviste `initCheckout` en un bloque `try...catch`, examina el valor `de tipo` resuelto de `loadActions()` para verificar si hay errores.
```javascript
const clientSecret = fetch("/create-checkout-session", {
method: "POST",
headers: { "Content-Type": "application/json" },
})
.then((r) => r.json())
.then((r) => r.clientSecret);
const checkout = stripe.initCheckout({
clientSecret
});
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
const session = loadActionsResult.actions.getSession();
}
```
#### React
Actualiza tu dependencia de `@stripe/react-stripe-js` al menos a la versión `5.0.0`. Si actualizas de una versión anterior a la `4.0.0`, asegúrate de leer las [notas de la versión v4.0.0](https://github.com/stripe/react-stripe-js/releases/tag/v4.0.0) para conocer los pasos adicionales de migración.
#### Importar cambios
Actualice sus importaciones para utilizar el nuevo punto de entrada específico para el proceso de compra:
```jsx
import {useCheckout, PaymentElement} from '@stripe/react-stripe-js/checkout';
```
#### Cambios en CheckoutProvider y useCheckout
Reemplaza `fetchClientSecret` por `clientSecret`. Ahora puedes procesar Elements sin verificar primero si `useCheckout` devolvió el `tipo: 'success'`, lo que reduce la latencia y permite que Elements muestre los cargadores esqueleto antes.
```jsx
const App = () => {
const promise = useMemo(() => {
return fetch('/create-checkout-session', {
method: 'POST',
headers: { "Content-Type": "application/json" },
})
.then((res) => res.json())
.then((data) => data.clientSecret);
}, []);
return (
);
}
const CheckoutPage = () => {
const {type, ...rest} = useCheckout();
return (
);
}
```
Para obtener más detalles, consulta la entrada del registro de cambios[Actualizaciones de initCheckout para que sea sincrónico](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md).
## Cómo migrar a Basil
### Cambios en Basil
- (Breaking) Los métodos asincrónicos, como [confirm](https://docs.stripe.com/js/custom_checkout/confirm) o [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code), 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](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) en [confirm](https://docs.stripe.com/js/custom_checkout/confirm) cuando [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) en [confirm](https://docs.stripe.com/js/custom_checkout/confirm) o [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/api/invoice-payment/list.md) para encontrar la factura asociada.
- Para obtener más información, lee el [registro de cambios de la API 2025-03-31.basil](https://docs.stripe.com/changelog/basil/2025-03-31/checkout-legacy-subscription-upgrade.md).
- Se agregó [percentOff](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts-percentOff) a [discountAmounts](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts) como una opción para mostrar descuentos.
### Actualización de Basil
Antes de migrar a Basil, primero [actualiza tu integración](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#beta-changelog) 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-js`al 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](https://docs.stripe.com/sdks/stripejs-versioning.md) como se indica a continuación:
```html
Checkout
```
- Elimina el encabezado beta de Stripe.js al inicializar Stripe.js.
#### HTML + JS
```js
const stripe = Stripe(
'<>', {
}
);
```
#### React
```javascript
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe("<>", {
});
```
- 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.
### Before
#### TypeScript
```javascript
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
apiVersion: '2026-04-22.dahlia; custom_checkout_beta=v1' as any,
});
```
### After
#### TypeScript
```javascript
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
apiVersion: '2025-03-31.basil' as any,
});
```
## 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](https://docs.stripe.com/payments/quickstart-checkout-sessions.md).
#### 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-js`al menos a “`3.5.0`.
- (Breaking) Se ha invertido el signo de [total.appliedBalance](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-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](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-clientSecret) 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](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) ahora responde a cualquier Billing Address Element o Shipping Address Element montado.
- [canConfirm](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) ahora se convierte en `false` si hay una confirmación en tránsito.
- Se ha eliminado `confirmationRequirements`.
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) ahora arroja un error si se proporcionó [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-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`](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-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 los ID de impuesto de los clientes. [Cómo recopilar ID de impuesto](https://docs.stripe.com/tax/checkout/tax-ids.md).
- 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](https://docs.stripe.com/js/custom_checkout/init)
- 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](https://docs.stripe.com/js/custom_checkout/confirm), pasando el evento [confirm](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event) como `expressCheckoutConfirmEvent`.
- Anteriormente, Express Checkout Element se confirmaba llamando a `event.confirm()`.
- (Breaking) Cuando se llama a [confirm](https://docs.stripe.com/js/custom_checkout/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 que arroja o rechaza una función representan errores en la propia integración, como parámetros o configuración no válidos. Estos errores no deben mostrarse a tus clientes.
- (Breaking) Los métodos asincrónicos, como [confirm](https://docs.stripe.com/js/custom_checkout/confirm) o [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code), 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](https://docs.stripe.com/js/custom_checkout/confirm).
- (Breaking) Address Element ya no actualiza automáticamente los campos [billingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-billingAddress) o [shippingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-shippingAddress) en la sesión.
- Siempre que Address Element esté montado, los valores del formulario se usarán automáticamente al llamar a [confirm](https://docs.stripe.com/js/custom_checkout/confirm).
- Escucha el [evento de cambio](https://docs.stripe.com/js/element/events/on_change?type=addressElement) para usar el valor del Address Element antes de la confirmación.
#### custom_checkout_beta_4
- Se agregaron [imágenes](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-images) al [objeto Session](https://docs.stripe.com/js/custom_checkout/session_object).
- Se agregaron [campos](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options-fields) como una opción al crear el Payment Element.
- Se agregó [paymentMethods](https://docs.stripe.com/js/custom_checkout/create_express_checkout_element#custom_checkout_create_express_checkout_element-options-paymentMethods) como una opción al crear Express Checkout Element.
- (Breaking) Si pasas opciones no válidas a [createElement](https://docs.stripe.com/js/custom_checkout/create_payment_element), ahora se produce un error. Anteriormente, las opciones no reconocidas se ignoraban en silencio.
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) y [updatePhoneNumber](https://docs.stripe.com/js/custom_checkout/update_phone_number) 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](https://docs.stripe.com/js/custom_checkout/session_object):
- [id](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-id)
- [livemode](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-livemode)
- [businessName](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-businessName)
- Las tarjetas guardadas ahora se pueden reutilizar. Aprende a [guardar y reutilizar](https://docs.stripe.com/payments/checkout/save-during-payment.md) los métodos de pago.
- (Breaking) El [diseño](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) 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](https://docs.stripe.com/js/custom_checkout/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’](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-redirect) a `confirm`.
#### custom_checkout_beta_2
- (Breaking) El campo `lineItem.recurring.interval_count` se ha eliminado y reemplazado por [lineItem.recurring.intervalCount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-recurring-intervalCount).
- (Breaking) El campo `lineItem.amount` se ha eliminado y reemplazado por lo siguiente:
- [lineItem.amountSubtotal](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountSubtotal)
- [lineItem.amountDiscount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountDiscount)
- [lineItem.amountTaxInclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxInclusive)
- [lineItem.amountTaxExclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxExclusive)
#### 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](https://docs.stripe.com/payments/quickstart-checkout-sessions.md#init-stripe).
*No hay cambios en la versión beta del back-end.*