# Elements con registro de cambios beta de la API Checkout Sessions
Mantente al tanto 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 más tarde. 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 detalles sobre la migración.
- (Breaking) Los métodos de pagos 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 por parte del cliente. Consulta[ Actualizar el comportamiento predeterminado para los métodos de pagos guardados](https://docs.stripe.com/changelog/clover/2025-09-30/custom-checkout-saved-payment-method-defaults.md) para obtener más información.
- (Breaking) Los códigos postales ya no se recopilan automáticamente para los pagos con tarjeta en Canadá, Reino Unido y Puerto Rico. Consulta [Eliminar el 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 dependes 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 asíncrono (`{type: “loading”}`, `{type: 'success', checkout: ...}`, o `{type: “error”, error: ...}`) en lugar de generar un error.
- [heckoutProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider) ahora renderiza los elementos secundarios de forma incondicional en lugar de renderizar `null` cuando [initCheckout](https://docs.stripe.com/js/custom_checkout/init) no se ha ejecutado 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 utilizas algún paquete NPM de Stripe, debes actualizar `@stripe/stripe-js` al menos a la versión `8.0.0` y `@stripe/react-stripe-js` al menos a la versión `5.0.0`.
- Si estás cargando Stripe.js a través de la etiqueta script, actualiza la etiqueta para hacer referencia a `clover` utilizando 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 la 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 cualquier llamada a `await` o `.then()` asociada con `initCheckout`.
1. Reemplaza tu función `fetchClientSecret` por una cadena de secreto de cliente o Promise que se resuelva en una cadena de secreto de cliente.
1. Llama a la nueva función asíncrona `checkout.loadActions()` para acceder a acciones como `getSession()`, que sustituye a `session()`, o `confirm()`. Solo es necesario llamar a `loadActions()` una vez.
1. Si anteriormente envolviste `initCheckout` en un bloque `try...catch`, examina el valor `type` resuelto de `loadActions()` en su lugar para comprobar 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 `@stripe/react-stripe-js` al menos a la versión `5.0.0`. Si actualizas desde 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
Actualiza tus 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 renderizar Elements sin comprobar primero si `useCheckout` ha devuelto `type: 'success'`, lo que reduce la latencia y permite que Elements muestre los cargadores esqueléticos 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 información, 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).
## Migración 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 rellena con la clave `session`. Anteriormente, esto estaba bajo 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 ya se ha configurado [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url) en la sesión de Checkout.
- (Breaking) La URL de retorno a la que se redirige después de una confirmación correcta anteriormente tenía parámetros de consulta incoherentes. Ahora se han eliminado 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 sesión de Checkout.
- (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 null hasta que se completa la sesión de Checkout.
- Si actualmente dependes del campo obsoleto `payment_intent.invoice`, te recomendamos que uses el webhook `checkout_session.completed`, que garantiza que la factura esté presente, y `checkout_session.invoice` o [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 ha añadido [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 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 utilizas paquetes 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 utilizando `v3` o `acacia`, actualiza la etiqueta para que haga referencia a `basil` utilizando la [nomenclatura versionada de Stripe.js](https://docs.stripe.com/sdks/stripejs-versioning.md) de la siguiente manera:
```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("<>", {
});
```
- Elimina el encabezado beta de la versión de la API y especifica que la versión de la API debe ser al menos `2025-03-31.basil` en tu integración de 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 establece en tu integración front-end.
- Un encabezado Beta de versión API (por ejemplo, `custom_checkout_beta=v1`), que se establece en tu integración de back-end.
### Versiones de front end beta
Especifica la versión Beta del front-end al [iniciar Stripe.js](https://docs.stripe.com/payments/quickstart-checkout-sessions.md).
#### custom_checkout_beta_6
Si estás usando paquetes de Stripe en NPM, primero debes actualizar `@stripe/stripe-js` al a la versión `6.1.0` o superior y `@stripe/react-stripe-js` a la versión `3.5.0` o superior.
- (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 importe a pagar, y un número negativo lo reduce.
- (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 asíncrona que devuelva el secreto de cliente en lugar de un valor estático.
- (Breaking) Se han renombrado los métodos de Elements.
- Si estás usando React Stripe.js, no necesitas hacer nada excepto 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')`.
- (Importante) 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 elemento de dirección de facturación o de dirección de envío montado.
- [canConfirm](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) ahora pasa a ser `false` si hay una confirmación en curso.
- Se han eliminado `confirmationRequirements`.
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) ahora genera 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 deseas rellenar previamente un correo electrónico que tu cliente pueda actualizar, llama a `updateEmail` tan pronto como 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, que comience con `https://` en lugar de una URL relativa, como `/success`).
- (Breaking) Se actualizaron los campos de tarifas a un objeto anidado para facilitar el renderizado.
- Se reemplazaron los valores numéricos por un objeto que contiene `amount` (una cadena de divisa con formato, como `$10.00`) y `minorUnitsAmount`, un número entero que representa el valor de la unidad más pequeña de la divisa. 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 bien cada uno de `total.total.minorUnitsAmount` y `currency` y `minorUnitsAmountDivisor` desde el objeto `checkout` y mostrarlos en tu interfaz de usuario. De lo contrario, se generará un error. Esto ayuda a mantener tu página de finalización de compra sincronizada a medida que se actualiza la CheckoutSession, incluida la adición de futuras funciones de Stripe, con cambios mínimos en el código de interfaz de usuario.
- Ahora se pueden recopilar los NIF de los clientes. Aprende cómo [recopilar ID fiscales](https://docs.stripe.com/tax/checkout/tax-ids.md).
- Ahora hay disponible un asistente solo para el modo de prueba en la parte inferior de la página del proceso de compra, que ofrece orientación para tu integración y accesos directos a escenarios de prueba comunes.
#### custom_checkout_beta_5
- (Breaking) Se ha cambiado el nombre de la función `initCustomCheckout` a [initCheckout](https://docs.stripe.com/js/custom_checkout/init)
- Dentro de React Stripe.js, a `CustomCheckoutProvider` se le ha cambiado el nombre por `CheckoutProvider` y a `useCustomCheckout` se le ha cambiado el nombre por `useCheckout`.
- (Breaking) Para confirmar el Express Checkout Element, llama a [confirmar](https://docs.stripe.com/js/custom_checkout/confirm) y especifica el [evento de confirmación](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event) como `expressCheckoutConfirmEvent`.
- Anteriormente, el Express Checkout Element se confirmaba llamando a `event.confirm()`.
- (Breaking) Al llamar a [confirm](https://docs.stripe.com/js/custom_checkout/confirm), el Payment Element y el Address Element validarán las entradas del formulario y mostrarán los errores.
- (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. Estos son problemas predecibles que se le pueden comunicar a tu cliente mostrándole el `message` en la página del proceso de compra.
- Los errores generados/rechazados por una función representan errores en la propia integración, como parámetros o configuraciones no válidos. Estos errores no se muestran a los 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 ha añadido un campo discriminador `type="success"|"error"`.
- Si se realiza correctamente, el estado actualizado de la sesión se rellena con la clave `success`. Anteriormente, era con la clave `session`.
- De lo contrario, el error se sigue rellenando debajo de la clave `error`.
- Se han añadido las opciones `email`, `phoneNumber`, `billingAddress` y `shippingAddress` a [confirm](https://docs.stripe.com/js/custom_checkout/confirm).
- (Breaking) El 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 el 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 han añadido [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 ha añadido [fields](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options-fields) como opción al crear el Payment Element.
- Se ha añadido [paymentMethods](https://docs.stripe.com/js/custom_checkout/create_express_checkout_element#custom_checkout_create_express_checkout_element-options-paymentMethods) como opción al crear el Express Checkout Element.
- (Breaking) Si especificas opciones no válidas para [createElement](https://docs.stripe.com/js/custom_checkout/create_payment_element), ahora aparece un error. Antes, las opciones no reconocidas se ignoraban sin más.
- (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 introducir los valores completos puede provocar un rendimiento deficiente.
- En lugar de llamar a `updateEmail` o `updatePhoneNumber` en cada evento de modificación de entrada, espera hasta que tu cliente finalice la entrada, por ejemplo, en el desenfoque de entrada o cuando envíe 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 añadido 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)
- Ahora se pueden reutilizar las tarjetas guardadas. Descubre cómo [guardar y reutilizar](https://docs.stripe.com/payments/checkout/save-during-payment.md) los métodos de pago.
- (Breaking) El [diseño predeterminado](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) del Payment Element se ha cambiado a `accordion`.
- Para seguir utilizando el diseño predeterminado anterior, debe especificar `layout='tabs'` explícitamente.
- (Breaking) Se ha cambiado el comportamiento predeterminado de [confirm](https://docs.stripe.com/js/custom_checkout/confirm) para que siempre se redirija a tu `return_url` después de una confirmación correcta.
- Hasta ahora, `confirm` solo se redireccionaba si el cliente elegía un método de pago basado en redireccionamiento. Para continuar usando el comportamiento anterior, debes pasar el [redireccionamiento=‘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 quitado y se ha reemplazado por [lineItem.recurring.intervalCount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-recurring-intervalCount).
- (Breaking) Se ha eliminado el campo `lineItem.amount` y se ha sustituido por el 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 al [configurar tu biblioteca de servidores](https://docs.stripe.com/payments/quickstart-checkout-sessions.md#init-stripe).
*No hay cambios en la versión beta del back end.*