Accéder directement au contenu
Créez un compte
 ou
connecter-vous
Logo de la documentation Stripe
/
Créez un compte
Connectez-vous
AperçuMettre votre intégration à niveau
Paiements en ligne
PrésentationTrouver votre cas d'usageManaged Payments
Moyens de paiement
Interfaces de paiement
Scénarios de paiement
Paiements par TPE
Autres produits Stripe

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.

Copier la page

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 Basil d’Elements avec l’API Checkout Sessions, ce document ne s’applique pas à vous.

Migration vers Basil

Modifications

  • 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 plus, consultez la liste des modifications de l’API.
  • Ajout de percentOff à discountAmounts en tant qu’option d’affichage des remises.

Mise à niveau

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 à l’aide de la balise de script, mettez à jour la balise de script pour qu’elle utilise 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>
  • 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
// 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,
});

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 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.
    • 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.
  • Breaking Pour confirmer l’Express Checkout Element, appelez confirm, en transmettant l’événement confirm comme 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

custom_checkout_beta_1

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

Log des modifications du back-end

Spécifiez la version bêta du back-end lors de la configuration de la bibliothèque de votre serveur.

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

Cette page vous a-t-elle été utile ?
OuiNon
Besoin d'aide ? Contactez le service Support.
Rejoignez notre programme d'accès anticipé.
Consultez notre log des modifications.
Des questions ? Contactez l'équipe commerciale.
LLM ? Lire llms.txt.
Propulsé par Markdoc