Ir a contenido
Crea una cuenta
 o
inicia sesión
Logotipo de la documentación de Stripe
/
Crear cuenta
Iniciar sesión
ResumenActualiza tu integración
Pagos por Internet
ResumenEncuentra tu caso de usoManaged Payments
Métodos de pago
Interfaces de pago
Escenarios de pago
Pagos en persona
Más allá de los pagos

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.

Advertencia

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

If you’re already on the Basil release of Elements with Checkout Sessions API, this changelog doesn’t apply to you.

Migración a Basil

Cambios

  • 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 rellena con la clave session. Anteriormente, esto estaba bajo la clave success.
  • Breaking Ahora se produce un error al especificar returnUrl en confirm cuando ya se ha configurado 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 en confirm o 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 para encontrar la factura asociada.
    • To learn more, read the 2025-03-31.basil API changelog.
  • Se ha añadido percentOff a discountAmounts como opción para mostrar descuentos.

Actualizar

Antes de migrar a Basil, primero actualiza tu integración 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.
  • If you’re loading Stripe.js through the script tag, and you’re still using v3 or acacia, update the tag to reference basil using the versioned Stripe.js nomenclature as follows:
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'],
  }
);
  • 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.
Antes
Después
TypeScript
Node
Ruby
PHP
Python
Go
.NET
Java
No results
// 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';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-07-30.basil; custom_checkout_beta=v1' as any,
});
TypeScript
Node
Ruby
PHP
Python
Go
.NET
Java
No results
// 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';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  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 beta de Stripe.js (p. ej., custom_checkout_beta_6), que se configura en tu integración de front end.
  • Un encabezado beta de la versión de la API (p. ej., custom_checkout_beta=v1), que está configurado en tu integración de back end.

Versiones de front end beta

Especifica la versión beta del front end al inicializar Stripe.js.

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. Un número positivo ahora aumenta el importe a pagar, y un número negativo lo reduce.
  • Breaking Se reemplazó clientSecret por fetchClientSecret. 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 ahora responde a cualquier elemento de dirección de facturación o de dirección de envío montado.
    • canConfirm ahora pasa a ser false si hay una confirmación en curso.
    • Se han eliminado confirmationRequirements.
  • Breaking updateEmail ahora genera un error si se proporcionó 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 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.
    • 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 ID fiscales de los clientes. Descubre cómo recopilar ID fiscales.
  • 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
    • 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 confirm y especifica el evento de confirmación como expressCheckoutConfirmEvent
    • Anteriormente, el Express Checkout Element se confirmaba llamando a event.confirm().
  • Breaking Al llamar a 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 arrojados/rechazados por una función representan errores en la propia integración, como parámetros o configuraciones no válidos. Estos errores no están pensados para mostrárselos a los clientes.
  • Breaking Los métodos asincrónicos, como confirm o applyPromotionCode, 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.
  • Breaking El Address Element ya no actualiza automáticamente los campos billingAddress o 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.
    • Escucha el evento de cambio para usar el valor del Address Element antes de la confirmación.

custom_checkout_beta_4

  • Se han añadido imágenes al objeto Session.
  • Se ha añadido fields como opción al crear el Payment Element.
  • Se ha añadido paymentMethods como opción al crear el Express Checkout Element.
  • Breaking Si especificas opciones no válidas para createElement, ahora aparece un error. Antes, las opciones no reconocidas se ignoraban sin más.
  • Breaking updateEmail y updatePhoneNumber 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:
  • Ahora se pueden reutilizar las tarjetas guardadas. Descubre cómo guardar y reutilizar los métodos de pago.
  • Breaking El diseño predeterminado 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 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’ a confirm.

custom_checkout_beta_2

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.

¿Te ha sido útil la página?
SíNo