Elements con el registro de cambios en versión beta de la API Checkout Sessions

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 2025-03-31.basil.
• 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 de script y sigues usando v3 o acacia, actualiza la etiqueta a basil usando la nomenclatura Stripe.js versionada como se indica a continuación:

• Elimina el encabezado beta de Stripe.js al inicializar Stripe.js.

• 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.

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 cuando inicialices 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.
    • Por ejemplo, reemplaza total.total por 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 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.
• Rompiendo Para confirmar el Express Checkout Element, llama a confirm, pasando el evento confirm 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:
  • id
  • livemode
  • businessName
• 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

• Breaking El campo lineItem.recurring.interval_count se ha eliminado y reemplazado por lineItem.recurring.intervalCount.
• Breaking El campo lineItem.amount se ha eliminado y reemplazado por lo siguiente:
  • lineItem.amountSubtotal
  • lineItem.amountDiscount
  • lineItem.amountTaxInclusive
  • lineItem.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.

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