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 uso
Métodos de pago
Interfaces de pago
Escenarios de pago
Pagos en persona
Otros productos de Stripe

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.

Copia la página

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 de Basil de Elements con la API Checkout Sessions, esta documentación no se aplica en tu caso.

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
    • The change creates the subscription after the user has completed the payment, so checkout_session.invoice and checkout_session.subscription are null until the Checkout Session completes.
    • If you currently rely on the deprecated payment_intent.invoice field, we recommend using the checkout_session.completed webhook, which ensures an invoice is present, and checkout_session.invoice or Invoice Payment list to find the associated invoice.
    • Para obtener más información, consulta el registro de cambios de la API.
  • 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.
  • Si vas a cargar Stripe.js a través de la etiqueta del script, actualízala para usar Stripe.js versionado reemplazando la etiqueta de la siguiente manera:
checkout.html
<head>
 <title>Checkout</title>
 <script src="https://js.stripe.com/v3"></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
// 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; custom_checkout_beta=v1' as any,
});
// 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.

Registro de cambios 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
¿Necesitas ayuda? Ponte en contacto con el equipo de soporte.
Únete a nuestro programa de acceso anticipado.
Echa un vistazo a nuestro registro de cambios.
¿Tienes alguna pregunta? Ponte en contacto con el equipo de ventas.
¿LLM? Lee llms.txt.
Con tecnología de Markdoc