# 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.
> Ce document contient les listes des modifications relatives aux versions bêta d’Elements avec l’API Checkout Sessions.
>
> Ce journal des modifications ne s’applique pas si vous utilisez [Clover](https://docs.stripe.com/changelog/clover.md) ou une version ultérieure. Consultez plutôt le [journal des modifications Stripe](https://docs.stripe.com/changelog.md).
## Migration vers Clover
### Modifications de Clover
- (Breaking) La méthode [stripe.initCheckout](https://docs.stripe.com/js/custom_checkout/init) 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](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md) 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](https://docs.stripe.com/changelog/clover/2025-09-30/custom-checkout-saved-payment-method-defaults.md) 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](https://docs.stripe.com/changelog/clover/2025-09-30/postal_code_in_card_form_for_non_us_countries.md) 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](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) 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](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider) affiche désormais systématiquement les composants enfants, au lieu de renvoyer `null` lorsque [initCheckout](https://docs.stripe.com/js/custom_checkout/init) n’aboutit pas.
### Mise à niveau de Clover
Avant de migrer vers Clover, commencez par [mettre à jour votre intégration](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#migrating-to-basil) 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](https://docs.stripe.com/sdks/stripejs-versioning.md) comme suit :
```html
Checkout
```
- Mettez à jour la version de l’API vers au moins `2025-09-30.clover` dans votre intégration back-end.
#### HTML + JS
Mettez à jour votre intégration comme suit :
1. Supprimez tous les appels `await` ou `.then()` associés à `initCheckout`.
1. Remplacez votre fonction `fetchClientSecret` par une clé secrète du client ou une Promise résolue par clé secrète du client.
1. 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.
1. 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.
```javascript
const clientSecret = fetch("/create-checkout-session", {
method: "POST",
headers: { "Content-Type": "application/json" },
})
.then((r) => r.json())
.then((r) => r.clientSecret);
const checkout = stripe.initCheckout({
clientSecret
});
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
const session = loadActionsResult.actions.getSession();
}
```
#### React
Mettez à niveau votre dépendance `@stripe/react-stripe-js` vers la version `5.0.0` au minimum. Si vous effectuez une mise à jour depuis une version antérieure à `4.0.0`, veillez à lire les [notes de version v4.0.0](https://github.com/stripe/react-stripe-js/releases/tag/v4.0.0) pour connaître les étapes de migration supplémentaires.
#### Modifications des imports
Mettez à jour vos imports pour utiliser le nouveau point d’entrée spécifique au paiement :
```jsx
import {useCheckout, PaymentElement} from '@stripe/react-stripe-js/checkout';
```
#### Modifications de CheckoutProvider et useCheckout
Remplacez `fetchClientSecret` par `clientSecret`. Vous pouvez désormais afficher Elements sans vérifier au préalable si `useCheckout` a renvoyé `type: 'success'`, ce qui réduit la latence et permet à Elements d’afficher des écrans de chargement plus tôt.
```jsx
const App = () => {
const promise = useMemo(() => {
return fetch('/create-checkout-session', {
method: 'POST',
headers: { "Content-Type": "application/json" },
})
.then((res) => res.json())
.then((data) => data.clientSecret);
}, []);
return (
);
}
const CheckoutPage = () => {
const {type, ...rest} = useCheckout();
return (
);
}
```
Pour plus de détails, consultez l’entrée du journal des modifications [Mise à jour d’initCheckout pour un fonctionnement synchrone](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md).
## Migration vers Basil
### Modifications de Basil
- (Breaking) Les méthodes asynchrones, telles que [confirm](https://docs.stripe.com/js/custom_checkout/confirm) ou [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code), 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](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) sur [confirm](https://docs.stripe.com/js/custom_checkout/confirm) lorsque [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) sur [confirm](https://docs.stripe.com/js/custom_checkout/confirm) ou [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/api/invoice-payment/list.md) pour retrouver la facture associée.
- Pour en savoir davantage, consultez le [journal des modifications de l’API 2025-03-31.basil](https://docs.stripe.com/changelog/basil/2025-03-31/paiement-legacy-subscription-upgrade.md).
- Ajout de [percentOff](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts-percentOff) à [discountAmounts](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-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](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#beta-changelog) 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](https://docs.stripe.com/sdks/stripejs-versioning.md) comme suit :
```html
Checkout
```
- Supprimez l’en-tête bêta de Stripe.js lors de l’initialisation de Stripe.js.
#### HTML + JS
```js
const stripe = Stripe(
'<>', {
}
);
```
#### React
```javascript
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe("<>", {
});
```
- 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.
### Before
#### TypeScript
```javascript
// 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';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
apiVersion: '2026-04-22.dahlia; custom_checkout_beta=v1' as any,
});
```
### After
#### TypeScript
```javascript
// 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';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
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 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](https://docs.stripe.com/payments/quickstart-checkout-sessions.md).
#### 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](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-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](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-clientSecret). 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](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) répond désormais à tout composant Billing Address Element ou Shipping Address Element monté.
- [canConfirm](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) devient désormais `false` en cas de confirmation à la volée.
- Suppression de `confirmationRequirements`.
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) génère désormais une erreur si [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-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`](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-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.
- Les numéros fiscaux des clients peuvent désormais être collectés. Découvrez comment [collecter les numéros fiscaux](https://docs.stripe.com/tax/checkout/tax-ids.md).
- 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](https://docs.stripe.com/js/custom_checkout/init)
- 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](https://docs.stripe.com/js/custom_checkout/confirm), en transmettant l’événement [ confirm event ](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event) sous la forme `expressCheckoutConfirmEvent`.
- Auparavant, l’Express Checkout Element était confirmé par un appel à `event.confirm()`.
- (Breaking) Lorsque [confirm](https://docs.stripe.com/js/custom_checkout/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 levées ou renvoyées par une fonction représentent des erreurs dans l’intégration elle-même, telles que des paramètres ou une configuration invalides. Ces erreurs ne sont pas destinées à être affichées à vos clients.
- (Breaking) Les méthodes asynchrones, telles que [confirm](https://docs.stripe.com/js/custom_checkout/confirm) ou [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code), 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](https://docs.stripe.com/js/custom_checkout/confirm).
- (Breaking) L’Address Element ne met plus automatiquement à jour les champs [billingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-billingAddress) et [shippingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-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](https://docs.stripe.com/js/custom_checkout/confirm).
- Écoutez l’[événement de modification](https://docs.stripe.com/js/element/events/on_change?type=addressElement) pour utiliser la valeur de l’Address Element avant confirmation.
#### custom_checkout_beta_4
- Ajout d’[images](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-images) à l’[objet Session](https://docs.stripe.com/js/custom_checkout/session_object).
- Ajout de l’option [fields](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options-fields) du Payment Element.
- Ajout de l’option [paymentMethods](https://docs.stripe.com/js/custom_checkout/create_express_checkout_element#custom_checkout_create_express_checkout_element-options-paymentMethods) lors de la création du Express Checkout Element.
- (Breaking) Transmettre des options non valides à [createElement](https://docs.stripe.com/js/custom_checkout/create_payment_element) génère désormais une erreur. Auparavant, les options non reconnues étaient silencieusement ignorées.
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) et [updatePhoneNumber](https://docs.stripe.com/js/custom_checkout/update_phone_number) 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](https://docs.stripe.com/js/custom_checkout/session_object) :
- [id](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-id)
- [livemode](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-livemode)
- [businessName](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-businessName)
- Les cartes enregistrées peuvent désormais être réutilisées. Découvrez comment [enregistrer et réutiliser](https://docs.stripe.com/payments/checkout/save-during-payment.md) des moyens de paiement.
- (Breaking) La [disposition](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) 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](https://docs.stripe.com/js/custom_checkout/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’](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-redirect) sur `confirm`.
#### custom_checkout_beta_2
- (Breaking) Le champ `lineItem.recurring.interval_count` a été supprimé et remplacé par [lineItem.recurring.intervalCount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-recurring-intervalCount).
- (Breaking) Le champ `lineItem.amount` a été supprimé et remplacé par le suivant :
- [lineItem.amountSubtotal](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountSubtotal)
- [lineItem.amountDiscount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountDiscount)
- [lineItem.amountTaxInclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxInclusive)
- [lineItem.amountTaxExclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxExclusive)
#### 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](https://docs.stripe.com/payments/quickstart-checkout-sessions.md#init-stripe).
*Aucun changement n’a été apporté à la version bêta du back-end.*