Ir a contenido
Crea una cuenta
 o
Inicia sesión
Logotipo de Stripe Docs
/
Crear una cuenta
Iniciar sesión
ResumenActualiza tu integración
Pagos electrónicos
ResumenEncuentra tu caso de usoPagos administrados
Métodos de pago
Interfaces de pago
Escenarios de pago
Pagos en persona
Más allá de los pagos

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 el lanzamiento de Basil de Elements con la API Checkout Sessions, este documento no se aplica a tu caso.

Cómo migrar 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 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.
  • Se agregó percentOff a discountAmounts como una opción para mostrar descuentos.

Actualizar

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 del script, actualiza la etiqueta para usar las versiones de Stripe.js. Para ello, reemplaza la etiqueta 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/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
// 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-05-28.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 (por ejemplo, custom_checkout_beta_6), que se establece en tu integración de front-end.
  • Un encabezado beta de la versión de la API (por ejemplo, custom_checkout_beta=v1), que se establece en tu integración de back-end.

Versiones beta del front-end

Especifica la versión beta del front-end al inicializar 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.
    • 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.
  • Breaking Para confirmar el Express Checkout Element, llama a confirm, pasando el evento de confirmación 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

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 al configurar la biblioteca del servidor.

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

¿Te fue útil esta página?
SíNo
¿Necesitas ayuda? Ponte en contacto con soporte.
Únete a nuestro programa de acceso anticipado.
Echa un vistazo a nuestro registro de cambios.
¿Tienes alguna pregunta? Contacto.
¿LLM? Lee llms.txt.
Con tecnología de Markdoc