Log des modifications de la version bêta d'Elements avec l'API Checkout Sessions

Suivez les modifications apportées à Elements grâce à l'intégration bêta de l'API Checkout Sessions.

Avertissement

Ce document contient les listes des modifications relatives aux versions bêta d’Elements avec l’API Checkout Sessions.

Si vous utilisez déjà la version Clover d’Elements avec l’API Checkout Sessions, ce journal des modifications ne s’applique pas à votre cas.

Migration vers Clover

Modifications de Clover

Breaking La méthode stripe.initCheckout est désormais synchrone et non plus asynchrone. Cela réduit la latence de rendu et permet à Elements d’afficher plus tôt les écrans de chargement. Consultez Mise à jour d’initCheckout pour un fonctionnement synchrone pour les détails de la migration.
Breaking Les moyens de paiement enregistrés sont désormais automatiquement activés dans le Payment Element lorsqu’ils sont configurés sur la session Checkout, sans nécessiter de configuration supplémentaire côté client. Consultez Mise à jour du comportement par défaut des moyens de paiement enregistrés pour plus de détails.
Breaking Les codes postaux ne sont plus automatiquement collectés pour les paiements par carte au Canada, au Royaume-Uni et à Porto Rico. Consultez Suppression du code postal pour les paiements par carte si vous dépendez de ces données.
Breaking Pour les intégrations React :
- Les chemins d’importation sont passés de @stripe/react-stripe-js à @stripe/react-stripe-js/checkout.
- useCheckout renvoie désormais une union disjointe décrivant l’état asynchrone ({type: 'loading'}, {type: 'success', checkout: ...} ou {type: 'error', error: ...}), au lieu de lever une erreur.
- CheckoutProvider affiche désormais systématiquement les composants enfants, au lieu de renvoyer null lorsque initCheckout n’aboutit pas.

Mise à niveau de Clover

Avant de migrer vers Clover, commencez par mettre à jour votre intégration vers Basil.

Si vous utilisez des packages Stripe NPM, vous devez mettre à niveau @stripe/stripe-js vers au moins 8.0.0 et @stripe/react-stripe-js vers au moins 5.0.0.
Si vous chargez Stripe.js via une balise script, mettez-la à jour pour référencer clover en utilisant la nomenclature Stripe.js versionnée comme suit :

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Mettez à jour la version de l’API vers au moins 2025-09-30.clover dans votre intégration back-end.

Mettez à jour votre intégration comme suit :

Supprimez tous les appels await ou .then() associés à initCheckout.
Remplacez votre fonction fetchClientSecret par une clé secrète du client ou une Promise résolue par clé secrète du client.
Appelez la nouvelle fonction asynchrone checkout.loadActions() pour accéder à des actions telles que getSession(), qui remplace session(), ou confirm(). Vous n’avez besoin d’appeler loadActions() qu’une seule fois.
Si vous encapsuliez auparavant initCheckout dans un bloc try...catch, examinez plutôt la valeur type résolue de loadActions() pour détecter les erreurs.

checkout.js
const clientSecret = fetch("/create-checkout-session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
})
  .then((r) => r.json())
  .then((r) => r.clientSecret);

const checkout = await stripe.initCheckout({
  fetchClientSecret: () => clientSecret
});
const checkout = stripe.initCheckout({
  clientSecret
});
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");

const session = checkout.session();
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  const session = loadActionsResult.actions.getSession();
}

Pour plus de détails, consultez l’entrée du journal des modifications Mise à jour d’initCheckout pour un fonctionnement synchrone.

Migration vers Basil

Modifications de Basil

Breaking Les méthodes asynchrones, telles que confirm ou applyPromotionCode, sont résolues avec un schéma différent :
- En cas de réussite, le nouvel état de la session est renseigné sous la clé session. Auparavant, cette information se trouvait sous la clé success.
Breaking Une erreur est désormais générée lors de la transmission de returnUrl sur confirm lorsque return_url a déjà été défini sur la session Checkout.
Breaking L’URL de redirection utilisée après une confirmation réussie présentait auparavant des paramètres de requête incohérents. Les paramètres supplémentaires sont désormais supprimés et l’URL ne contient que ce qui est fourni dans returnUrl sur confirm ou return_url sur la session Checkout.
Breaking Améliore le temps de latence de l’API Checkout Session pour les sessions en mode abonnement et corrige un bogue qui empêchait vos clients de mettre à jour une session après la première tentative de paiement.
- La modification crée l’abonnement une fois que l’utilisateur a effectué le paiement, de sorte que checkout_session.invoice et checkout_session.subscription présentent la valeur null jusqu’à la fin de la session Checkout.
- Si vous utilisez actuellement l’ancien champ payment_intent.invoice, nous vous recommandons d’utiliser le webhook checkout_session.completed, qui garantit la présence d’une facture, et checkout_session.invoice ou Invoice Payment List pour retrouver la facture associée.
- Pour en savoir davantage, consultez le journal des modifications de l’API 2025-03-31.basil.
Ajout de percentOff à discountAmounts en tant qu’option d’affichage des remises.

Mise à niveau de Basil

Avant de migrer vers Basil, commencez par mettre à jour votre intégration sur custom_checkout_beta_6.

Si vous utilisez des paquets NPM Stripe, vous devez d’abord mettre à niveau @stripe/stripe-js vers la version 7.0.0, et @stripe/react-stripe-js vers la version 3.6.0 (ou une version supérieure).
Si vous chargez Stripe.js via la balise de script et que vous utilisez toujours v3 ou acacia, mettez à jour la balise pour référencer basil en utilisant la nomenclature Stripe.js versionnée comme suit :

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>

Supprimez l’en-tête bêta de Stripe.js lors de l’initialisation de Stripe.js.

checkout.js
const stripe = Stripe(
  'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_beta_6'],
  }
);

Supprimez l’en-tête bêta de la version de l’API et spécifiez que la version de l’API doit être au moins 2025-03-31.basil sur votre intégration back-end.

Avant

Après

Journal des modifications, version bêta

Elements avec la bêta de l’API Checkout Sessions utilise deux types de versions bêta :

Un en-tête de version bêta Stripe.js (par exemple, custom_checkout_beta_6), qui est défini sur votre intégration front-end.
Un en-tête de version bêta d’API (par exemple, custom_checkout_beta=v1), qui est défini sur votre intégration de back-end.

Versions bêta du front-end

Spécifiez la version bêta du front-end lors de l’initialisation de Stripe.js.

custom_checkout_beta_6

Si vous utilisez des paquets NPM Stripe, vous devez d’abord mettre à niveau @stripe/stripe-js vers la version 6.1.0, et @stripe/react-stripe-js vers la version 3.5.0 (ou une version supérieure).

Breaking Le signe de total.appliedBalance a été inversé. Un nombre positif augmente désormais le montant à payer, tandis qu’un nombre négatif le diminue.
Breaking Remplacement de clientSecret par fetchClientSecret. Mettez à jour votre intégration de manière à transmettre une fonction asynchrone aboutissant à la clé secrète du client au lieu de transmettre une valeur statique.
Breaking Les méthodes Elements ont été renommées.
- Si vous utilisez React Stripe.js, vous n’avez rien d’autre à faire que de mettre à niveau @stripe/react-stripe-js.
- Si vous utilisez HTML/JS :
  - Utilisez createPaymentElement() au lieu de createElement('payment').
  - Utilisez createBillingAddressElement() au lieu de createElement('address', {mode: 'billing'}).
  - Utilisez createShippingAddressElement() au lieu de createElement('address', {mode: 'shipping'}).
  - Utilisez createExpressCheckoutElement() au lieu de createElement('expressCheckout').
  - Utilisez getPaymentElement() au lieu de getElement('payment').
  - Utilisez getBillingAddressElement() au lieu de getElement('address', {mode: 'billing'}).
  - Utilisez getShippingAddressElement() au lieu de getElement('address', {mode: 'shipping'}).
  - Utilisez getExpressCheckoutElement() au lieu de getElement('expressCheckout').
Breaking Mise à jour des champs liés à la confirmation pour refléter plus précisément l’état de la session.
- canConfirm répond désormais à tout composant Billing Address Element ou Shipping Address Element monté.
- canConfirm devient désormais false en cas de confirmation à la volée.
- Suppression de confirmationRequirements.
Breaking updateEmail génère désormais une erreur si customer_email a été fourni lors de la création de la session Checkout. Si vous avez l’intention de préremplir une adresse e-mail que votre client pourra modifier, appelez updateEmail dès le chargement de la page au lieu de transmettre customer_email.
Breaking returnUrl doit être une URL absolue (par exemple une adresse commençant par https://, par opposition à une URL relative, comme /success).
Breaking Les champs de tarification ont été modifiés en un objet imbriqué pour faciliter l’affichage.
- Les valeurs numériques ont été remplacées par un objet contenant les attributs amount (une chaîne de devise formatée, par exemple $10.00) et minorUnitsAmount, un entier représentant la valeur dans la plus petite unité de la devise. Si vous lisez déjà le montant, lisez-le plutôt à partir de minorUnitsAmount.
  - Remplacez par exemple total.total par total.total.minorUnitsAmount.
- Vous devez lire soit total.total.amount, soit l’ensemble des attributs total.total.minorUnitsAmount, currency et minorUnitsAmountDivisor de l’objet checkout, et les afficher dans votre interface utilisateur, sinon une erreur sera générée. Cela permet de synchroniser votre page de paiement avec toutes les mises à jour de CheckoutSession, y compris tout ajout de nouvelles fonctionnalités par Stripe, avec des modifications minimes du code de votre interface utilisateur.
Il est désormais possible de collecter les numéros fiscaux des clients. Découvrez comment collecter les numéros fiscaux.
Un assistant spécifique au mode test est désormais disponible au bas de votre page de paiement. Il vous propose des conseils pour votre intégration et des raccourcis pour des scénarios de test courants.

custom_checkout_beta_5

Breaking La fonction initCustomCheckout a été renommée initCheckout
- Dans React Stripe.js, CustomCheckoutProvider a été renommé CheckoutProvider et useCustomCheckout a été renommé useCheckout.
% badge color=“green” label=“Breaking” %} Pour confirmer le composant Express Checkout Element, appelez confirm, en transmettant l’événement confirm event sous la forme expressCheckoutConfirmEvent.
- Auparavant, l’Express Checkout Element était confirmé par un appel à event.confirm().
Breaking Lorsque confirm est appelé, le Payment Element et l’Address Element valident les entrées de formulaire et affichent les erreurs éventuelles.
Breaking Les messages d’erreur ont été standardisés et améliorés.
- Les erreurs renvoyées/résolues par une fonction représentent des scénarios connus, tels que des informations de paiement non valides ou des fonds insuffisants. Il s’agit de problèmes prévisibles qui peuvent être signalés au client en affichant le message sur la page de paiement.
- Les erreurs renvoyées/rejetées par une fonction représentent des erreurs dans l’intégration elle-même, telles que des paramètres ou des configurations non valides. Ces erreurs ne sont pas destinées à être transmises à vos clients.
Breaking Les méthodes asynchrones, telles que confirm ou applyPromotionCode, sont résolues avec un schéma différent :
- Un champ discriminant type="success"|"error" a été ajouté.
- En cas de réussite, le nouvel état de la session est renseigné sous la clé success. Auparavant, cette information se trouvait sous la clé session.
- Dans le cas contraire, l’erreur continue d’être renseignée sous la clé error.
Ajout des options email, phoneNumber, billingAddress et shippingAddress à confirm.
Breaking L’Address Element ne met plus automatiquement à jour les champs billingAddress et shippingAddress de la session.
- Tant que l’Address Element est monté, les valeurs du formulaire seront automatiquement utilisées lors de l’appel de confirm.
- Écoutez l’événement de modification pour utiliser la valeur de l’Address Element avant confirmation.

custom_checkout_beta_4

Ajout d’images à l’objet Session.
Ajout de l’option fields du Payment Element.
Ajout de l’option paymentMethods lors de la création du Express Checkout Element.
Breaking Transmettre des options non valides à createElement génère désormais une erreur. Auparavant, les options non reconnues étaient silencieusement ignorées.
Breaking updateEmail et updatePhoneNumber appliquent les modifications de manière asynchrone. L’appel de ces méthodes avant que le client n’ait fini d’entrer des valeurs complètes peut nuire aux performances.
- Au lieu d’appeler updateEmail ou updatePhoneNumber à chaque événement de modification d’entrée, attendez que votre client ait terminé la saisie, par exemple quand l’utilisateur clique en dehors du champ de saisie ou quand il envoie le formulaire pour paiement.
- updateEmail valide désormais que l’entrée est une adresse e-mail correctement formée et renvoie une erreur si une entrée non valide est utilisée.
- updatePhoneNumber n’effectue toujours aucune validation sur la chaîne d’entrée.

custom_checkout_beta_3

Les champs suivants ont été ajoutés à l’objet Session :
Les cartes enregistrées peuvent désormais être réutilisées. Découvrez comment enregistrer et réutiliser des moyens de paiement.
Breaking La disposition par défaut de Payment Element a été remplacée par accordion.
- Pour continuer à utiliser la mise en page par défaut précédente, vous devez spécifier explicitement layout='tabs'.
Breaking Le comportement par défaut de confirm a été modifié pour toujours rediriger vers votre return_url après une confirmation réussie.
- Auparavant, confirm redirigeait uniquement si le client choisissait un moyen de paiement avec redirection. Pour continuer à utiliser l’ancien comportement, vous devez basculer redirect=‘if_required’ sur confirm.

custom_checkout_beta_2

Breaking Le champ lineItem.recurring.interval_count a été supprimé et remplacé par lineItem.recurring.intervalCount.
Breaking Le champ lineItem.amount a été supprimé et remplacé par le suivant :

custom_checkout_beta_1

Il s’agit de la version bêta initiale du front-end.

Versions du back-end

Spécifiez la version bêta du back-end lorsque vous configurez la bibliothèque de votre serveur.

Aucun changement n’a été apporté à la version bêta du back-end.