# 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.
> Ce document contient les journaux 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](https://docs.stripe.com/changelog.md) Stripe.
## Migrer vers Clover
### Modifications apportées à Clover
- (Breaking) La méthode [Stripe.initCheckout](https://docs.stripe.com/js/custom_checkout/init) est désormais synchrone au lieu d’être asynchrone. Cela réduit la latence d’affichage et permet à Elements d’afficher les écrans squelettes plus tôt. Pour plus de détails sur la migration, consultez la page [Updates initCheckout to be synchronous (Mises à jour d’initCheckout pour qu’elle soit synchrone)](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md).
- (Breaking) Les modes de paiement enregistrés sont désormais activés de manière automatique dans le composant Payment Element lorsqu’ils sont configurés sur la Session Checkout, sans nécessiter de configuration supplémentaire côté client. Pour en savoir plus, consultez [Updates default behavior for saved payment methods (Mises à jour du comportement par défaut des modes de paiement enregistrés)](https://docs.stripe.com/changelog/clover/2025-09-30/custom-checkout-saved-payment-method-defaults.md).
- (Breaking) Les codes postaux ne sont plus recueillis automatiquement pour les paiements par carte au Canada, au Royaume-Uni et à Porto Rico. Consultez le paramètre[Removes postal code for card payments (Supprime le 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 ces données vous sont utiles pour vos opérations.
- (Breaking) pour les intégrations de la bibliothèque 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: ...}`), plutôt que de renvoyer une erreur.
- [CheckoutProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider) affiche désormais les enfants sans restriction, au lieu d’afficher la valeur `null` lorsque l’action [initCheckout](https://docs.stripe.com/js/custom_checkout/init) n’a pas réussi.
### 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 paquets NPM de Stripe, 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 au moyen de la balise script, mettez à jour la balise pour permettre le référencement de `clover` en utilisant la [nomenclature Stripe.js versionnée](https://docs.stripe.com/sdks/stripejs-versioning.md) comme suit :
```html
Checkout
```
- Mettez à jour l’API à au moins la version `2025-09-30.clover` sur votre intégration dorsale.
#### HTML + JS
Mettez à jour votre intégration en procédant comme suit :
1. Supprimez les appels `await` ou `.then()` associés à `initCheckout`.
1. Remplacez votre fonction `fetchClientSecret` par une chaîne de clés secrètes du client ou promesses qui est résolue par une chaîne de clés secrètes du client.
1. Appelez la nouvelle fonction asynchrone `Checkout.loadActions()` pour accéder à des actions telles que `getSession()`, en remplacement de `session()`, ou `confirm()`. Vous n’avez besoin d’appeler la fonction `loadActions()` qu’une seule fois.
1. Si vous avez déjà inclus `initCheckout` dans un bloc `try...catch`, examinez plutôt le`type` de valeur pour `loadActions()` résolu afin de vérifier s’il y a des 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 passez d’une version antérieure à la version `4.0.0`, assurez-vous de lire les [notes de publication pour la 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 apportées aux importations
Mettez à jour vos importations pour utiliser le nouveau point d’entrée spécifique à Checkout :
```jsx
import {useCheckout, PaymentElement} from '@stripe/react-stripe-js/checkout';
```
#### Modifications apportées à CheckoutProvider et à useCheckout
Remplacez `fetchClientSecret` par `clientSecret`. Vous pouvez désormais afficher Elements sans vérifier au préalable si `useCheckout` a renvoyé l’information `type : 'opération réussie'`, ce qui réduit la latence et permet à Elements d’afficher les écrans squelettes 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 obtenir plus de détails, consultez l’entrée [Updates initCheckout to be synchronous (Mises à jour d’initCheckout pour qu’elle devienne asynchrone)](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md) dans le journal des modifications.
## Migration vers Basil
### Modifications apportées à 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), 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](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) sur [confirm](https://docs.stripe.com/js/custom_checkout/confirm) alors que [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 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](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é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](https://docs.stripe.com/api/invoice-payment/list.md) pour retrouver la facture associée.
- Pour en savoir plus, consultez le [journal des modifications des API 2025-03-31.basil](https://docs.stripe.com/changelog/basil/2025-03-31/checkout-legacy-abonnement-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 réductions.
### 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) 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 à travers le tag script, et que vous utilisez toujours `v3` ou `acacia`, mettez à jour le tag 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
```
- Retirez 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("<>", {
});
```
- 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.
### 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 l’API Checkout Sessions de la version bêta utilise deux types de versions bêta :
- Un en-tête Stripe.js bêta (par exemple, `custom_checkout_beta_6`), qui est défini sur votre intégration frontale.
- Un en-tête API version bêta (par exemple, `custom_checkout_beta=v1`), qui est défini dans votre intégration back-end.
### Versions bêta frontales
Spécifiez la version bêta du frontal 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` 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](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-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](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-clientSecret). 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](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) répond désormais à n’importe quel composant Billing Address Element ou Shipping Address Element monté.
- [canConfirm](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) passe désormais à `false` si une confirmation est en cours.
- `confirmationRequirements` supprimé.
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) provoque 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 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](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-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`](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-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.
- Les numéros d’identification fiscale des clients peuvent désormais être collectés. Découvrez comment [collecter les numéros d’identification fiscale](https://docs.stripe.com/tax/checkout/tax-ids.md).
- 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](https://docs.stripe.com/js/custom_checkout/init)
- Dans React Stripe.js, `CustomCheckoutProvider` a été renommé à `CheckoutProvider` et `useCustomCheckout` a été renommé à `useCheckout`.
- (Breaking) Pour confirmer le composant Checkout Express Element, appelez [confirm](https://docs.stripe.com/js/custom_checkout/confirm), en transmettant le [confirm event](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event) à `expressCheckoutConfirmEvent`.
- Auparavant, Express Checkout Element était confirmé en faisant appel à `event.confirm()`.
- (Breaking) Lorsque la [confirmation](https://docs.stripe.com/js/custom_checkout/confirm) 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 généré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](https://docs.stripe.com/js/custom_checkout/confirm) ou [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code), 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](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) ou [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 de formulaire seront automatiquement utilisées lors de l’appel de [confirmation](https://docs.stripe.com/js/custom_checkout/confirm).
- Écoutez l’[événement de changement](https://docs.stripe.com/js/element/events/on_change?type=addressElement) pour utiliser la valeur de l’Address Element avant la 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 [champs](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options-fields) comme option lors de la création du composant 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 composant Express Checkout Element.
- (Breaking) La transmission d’options non valides à [createElement](https://docs.stripe.com/js/custom_checkout/create_payment_element) provoque désormais une erreur. Auparavant, les options non reconnues étaient 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 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](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) les moyens de paiement.
- (Breaking) L’[affichage](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) 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](https://docs.stripe.com/js/custom_checkout/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’](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é retiré 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 champ 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 frontale initiale.*
### Versions dorsales
Spécifiez la version bêta dorsale lors de la [configuration de votre bibliothèque de serveurs](https://docs.stripe.com/payments/quickstart-checkout-sessions.md#init-stripe).
*Il n’y a aucun changement dans la version bêta de l’application dorsale.*