Journal des modifications d’Elements avec l’API Checkout Sessions de la version bêta

Suivez les modifications apportées à l’intégration d’Elements avec l’API Checkout Sessions de la version bêta.

Alerte

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

Si vous utilisez déjà la version Basil d’Elements avec l’API Checkout Sessions, ce document ne vous concerne pas.

Migration vers Basil

Modifications

Breaking Les méthodes asynchrones, telles que confirm ou applyPromotionCode, se résolvent 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 alors que return_url a déjà été défini sur la session Checkout.
Breaking L’URL de redirection après une confirmation de réussite avait auparavant des paramètres de requête incohérents. Les paramètres supplémentaires sont désormais retirés et l’URL ne contient que ce qui est fourni dans returnUrl sur confirm ou return_url sur la session Checkout.
Breaking Amélioration de la latence sur l’API Checkout Session pour les sessions en mode abonnement et correction d’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. Par conséquent, checkout_session.invoice et checkout_session.subscription ont des valeurs nulles jusqu’à ce que la session Checkout se termine.
- 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 une liste de paiement de factures pour retrouver la facture associée.
- Pour en savoir plus, consultez le journal des modifications de l’API.
Ajout de percentOff à discountAmounts en tant qu’option d’affichage des réductions.

Mise à niveau

Avant de migrer vers Basil, commencez par mettre à jour votre intégration vers 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 à l’aide de la balise de script, mettez à jour la balise de script pour qu’elle utilise le Stripe.js versionné en remplaçant la balise comme suit :

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>

Retirez 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'],
  }
);

Retirez l’en-tête bêta de la version de l’API et indiquez que la version de l’API doit être au moins 2025-03-31.basil sur votre intégration dorsale.

Avant

Après

Journal des modifications, version bêta

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

Un en-tête bêta Stripe.js (par exemple, custom_checkout_beta_6), qui est défini dans votre intégration frontale.
Un en-tête bêta de l’API (p. ex., custom_checkout_beta=v1), défini dans l’application dorsale de votre intégration.

Versions bêta frontales

Indiquez la version bêta de l’application frontale 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 ou une version ultérieure et @stripe/react-stripe-js vers la version 3.5.0 ou une version ultérieure.

Breaking Le signe de total.appliedBalance a été inversé. Désormais, un nombre positif fait augmenter le montant à payer, tandis qu’un nombre négatif le fait diminuer.
Breaking Remplacement de clientSecret par fetchClientSecret. Mettez à jour votre intégration pour transmettre une fonction asynchrone se résolvant en 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 à n’importe quel composant Billing Address Element ou Shipping Address Element monté.
- canConfirm passe désormais à false si une confirmation est en cours.
- confirmationRequirements supprimé.
Breaking updateEmail provoque désormais une erreur si customer_email a été fourni lors de la création de la session Checkout. Si vous envisagez de préremplir une adresse de courriel que votre client pourra mettre à jour, appelez updateEmail dès le chargement de la page au lieu de transmettre customer_email.
Breaking returnUrl doit être une URL absolue (commençant par exemple par https:// plutôt que par une URL relative, comme /success).
Breaking Les champs de tarification ont été mis à jour vers un objet imbriqué pour simplifier le rendu.
- Les valeurs numériques ont été remplacées par un objet contenant amount (une chaîne de devise formatée, telle que $10.00) et minorUnitsAmount, un nombre entier représentant la valeur dans la plus petite unité de la devise. Si vous lisez déjà le montant, lisez plutôt à partir de minorUnitsAmount.
  - Par exemple, remplacez total.total par total.total.minorUnitsAmount.
- Vous devez lire soit total.total.amount, soit chacun des composants total.total.minorUnitsAmount, currency et minorUnitsAmountDivisor à partir 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 l’ajout de nouvelles fonctionnalités de Stripe, avec des modifications minimes du code de l’interface utilisateur.
Il est désormais possible de collecter les numéros d’identification fiscale des clients. Découvrez comment collecter les numéros d’identification fiscale.
Un assistant en mode test uniquement est désormais disponible au bas de votre page de paiement; il 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.
Breaking Pour confirmer Express Checkout Element, appelez la confirmation, en transmettant l’événement de confirmation comme expressCheckoutConfirmEvent
- Auparavant, Express Checkout Element était confirmé en faisant appel à event.confirm().
Breaking Lorsque la confirmation est appelée, 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é normalisé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 communiqués à votre client en affichant le message sur la page de paiement.
- Les erreurs envoyées/rejetées par une fonction représentent des erreurs dans l’intégration elle-même, telles que des paramètres ou une configuration non valides. Ces erreurs ne sont pas destinées à être affichées à vos clients.
Breaking Les méthodes asynchrones, telles que confirm ou applyPromotionCode, se résolvent avec un schéma différent :
- Un champ discriminateur type="success"|"error" a été ajouté.
- En cas de réussite, l’état de la session mise à jour est indiqué sous la clé success. Auparavant, il était indiqué 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 à confirmer.
Breaking L’Address Element ne met plus automatiquement à jour les champs billingAddress ou shippingAddress de la session.
- Tant que l’Address Element est monté, les valeurs de formulaire seront automatiquement utilisées lors de l’appel de confirmation.
- Écoutez l’événement de changement pour utiliser la valeur de l’Address Element avant la confirmation.

custom_checkout_beta_4

Ajout d’images à l’objet Session.
Ajout de champs comme option lors de la création du composant Payment Element.
Ajout de l’option paymentMethods lors de la création du composant Express Checkout Element.
Breaking La transmission d’options non valides à createElement provoque désormais une erreur. Auparavant, les options non reconnues étaient 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 de saisir des valeurs complètes peut entraîner de faibles performances.
- Au lieu d’appeler updateEmail ou updatePhoneNumber lors de l’événement de modification de chaque saisie, attendez que votre client ait terminé la saisie, par exemple lorsque le focus est retiré de la saisie ou lorsqu’il soumet le formulaire pour paiement.
- updateEmail valide désormais la saisie comme étant une adresse de courriel correctement formatée et renvoie une erreur en cas de saisie non valide.
- updatePhoneNumber ne valide toujours pas la chaîne de caractères saisie.

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 les moyens de paiement.
Breaking L’affichage par défaut du composant Payment Element a été modifié par accordion.
- Pour continuer à utiliser l’ancienne mise en page par défaut, vous devez explicitement spécifier layout='tabs'.
Breaking Le comportement par défaut de confirm a été modifié pour toujours rediriger vers votre return_url après une confirmation de réussite du paiement.
- Auparavant, confirm ne redirigeait le client que s’il choisissait un moyen de paiement basé sur la redirection. Pour continuer à utiliser l’ancien comportement, vous devez transmettre redirect=‘if_required’ sur confirm.

custom_checkout_beta_2

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

custom_checkout_beta_1

Il s’agit de la version bêta frontale initiale.

Journal des modifications de l’application dorsale

Indiquez la version bêta de l’application dorsale lors de la configuration de la bibliothèque de votre serveur.

Il n’y a aucun changement dans la version bêta de l’application dorsale.