Politique de gestion des versions et de prise en charge de Stripe.js

En savoir plus sur la politique de prise en charge et de gestion des versions de Stripe.js.

Stripe.js utilise un modèle évolutif, ce qui signifie qu’il reçoit continuellement des mises à jour au fil du temps. Stripe.js v3, les scripts sur lesquels repose js.stripe.com/v3, était la version la plus récente de Stripe.js pendant de nombreuses années. Nous publions de nouvelles versions importantes comme Acacia chaque semestre. Ces versions nous permettent d’introduire des fonctionnalités majeures et des changements importants selon un calendrier prévisible, afin que vous puissiez planifier vos mises à niveau. on a biannual basis. These versions allow us to introduce major features and breaking changes on a predictable schedule, so you can plan your upgrades.

Types de modifications

Les modifications apportées à Stripe.js se répartissent en deux principales catégories :

Optimisations et nouvelles fonctionnalités

Les modifications les plus courantes que nous apportons à Stripe.js sont les optimisations et les nouvelles fonctionnalités.

Nous ajoutons de nouvelles fonctionnalités, effectuons des optimisations et corrigeons des bogues tels que des problèmes de sécurité critiques, sans aucune modification de l’intégration. C’est automatiquement le cas pour toutes les intégrations Stripe.js, et pour toutes les versions de Stripe.js. Toutes les versions continuent de recevoir ces mises à jour minimes et sont régulièrement mises à jour ensemble dans notre processus de publication interne.

Voici quelques exemples d’optimisations que nous considérons comme mineures :

Modification des libellés de saisie dans le Payment Element pour optimiser l’accessibilité.
Mise à jour de l’interface utilisateur dans Payment Element pour les redirections BNPL afin d’augmenter la conversion.
Ajout d’un nouveau paramètre qui vous permet d’indiquer quand vous ne souhaitez pas soumettre de code postal pour un paiement par carte.

Certaines modifications nécessitent des modifications d’intégration pour être accessibles, mais ne constituent pas des modifications importantes. Par exemple, l’ajout d’une nouvelle fonction sur l’objet Stripe. Nous publions ces fonctionnalités en toute sécurité dans certaines versions existantes de Stripe.js dans le cadre de notre processus de publication régulier. C’est ce qu’on appelle le rétroportage.

Modifications majeures

The Stripe.js versioning system is a tool that enables us to release new features that might otherwise be constrained by our need to support backward compatibility. We release these breaking changes in Stripe releases, done twice per year.

Un changement important est un élément susceptible d’entraîner un échec ou de donner l’impression que votre intégration présente un problème. Par exemple :

Suppression d’un paramètre ou de la prise en charge d’une option spécifique. Par exemple, vous n’autorisez plus captureMethod: manual pour stripe.elements().
Suppression d’un champ de saisie susceptible d’être utilisé pour un moyen de paiement. Par exemple, vous ne collectez plus country pour les paiements Klarna.
Modifications susceptibles de rendre votre page de paiement confuse ou de causer des problèmes d’affichage. Par exemple, la modification du comportement par défaut de la mise en page du Payment Element d’onglets à accordéon peut entraîner des problèmes d’affichage si votre page fait certaines hypothèses sur l’élément dans le flux de la page.

Utilisation

Il existe trois façons d’utiliser Stripe.js versionné : avec une balise de script, avec le paquet @stripe/stripe-js sur npm ou avec le paquet @stripe/react-stripe-js sur npm.

À l’aide d’une balise de script

Pour utiliser le fichier Stripe.js versionné, incluez le nom de la version dans l’URL de la balise de script.

<script src="https://js.stripe.com/acacia/stripe.js"></script>

Nous vous recommandons de toujours utiliser la dernière version de Stripe.js. Stripe.js v3 n’est plus recommandé pour les intégrations, mais nous continuerons de le prendre en charge.

Avec stripe-js sur npm

Si vous utilisez Stripe.js avec le paquet @stripe/stripe-js sur npm, vous pouvez continuer à utiliser Stripe.js de cette façon. À partir de @stripe/stripe-js@6.0.0, chaque version majeure de Stripe.js utilise une version fixe spécifique de Stripe.js. Par exemple, @stripe/stripe-js@6.0.0 consomme Stripe.js acacia. Pour en savoir plus sur les relations entre des versions @stripe/stripe-js spécifiques et les versions de Stripe.js correspondantes, consultez la page des versions…

Although non-breaking runtime functionality of Stripe.js is backported to old versions of Stripe.js, the TypeScript types on npm aren’t backported to old major versions in @stripe/stripe-js. To stay up to date with the most recent TypeScript types, update to the most recent release of Stripe.js and @stripe/stripe-js.

Avec react-stripe-js sur npm

Le paquet @stripe/react-stripe-js continue de fonctionner avec le paquet @stripe/stripe-js à l’aide de son peerDependencies.

Cycle de vie des versions

Deux fois par an, nous publions les versions majeures de Stripe.js en même temps que les release trains de l’API. Nous publions des modifications mineures, y compris des optimisations et des fonctionnalités rétroportées, dans le cadre de notre calendrier de mises à jour fréquentes. Nous continuons à prendre en charge et à mettre à jour les anciennes versions. twice per year. We release non-breaking changes, including both optimizations and backported features, on our ongoing frequent release schedule. We continue to support and update older versions.

Compatibilité avec les versions d’API

Lors de l’exécution de requêtes API, chaque version du fichier Stripe.js utilise automatiquement la version de l’API associée à la version de Stripe.js. En d’autres termes, la version acacia de Stripe.js utilise une version d’API compatible telle que 2024-12-18.acacia (qui inclut la date) pour représenter la date de publication de la version de l’API. Vous ne pouvez pas remplacer la version de l’API.

Log des modifications

Le log des modifications affiche l’historique des modifications versionnées dans Stripe.js au fil du temps. Il inclut toutes les modifications importantes. C’est le meilleur moyen de comprendre les changements d’intégration que vous devez apporter pour mettre à niveau les versions de Stripe.js. shows the history of versioned changes in Stripe.js over time. It includes all breaking changes and other important changes and is the best place to understand what integration changes you need to make to upgrade Stripe.js versions.

Migrer à partir de Stripe.js v3

Veuillez prendre en compte les éléments suivants avant de passer de Stripe.js v3 à une version plus récente.

Modifications apportées à l’API

When you update Stripe.js to acacia from v3, this might cause breaking changes for API requests, depending on the API version you previously used for the requests. To upgrade older accounts, we recommend you:

Identify the current API version used in your account.
Identify the changes that affect your Stripe.js integration.
Upgrade the API version your Stripe.js integration uses to 2024-12-18.acacia gradually (if it makes sense for your needs) before upgrading Stripe.js to acacia.

API betas

Les versions d’API peuvent contenir des modifications importantes pour les versions bêta qui ne sont pas répertoriées dans le log des modifications. Vous devez donc mettre à niveau votre version de Stripe.js avec précaution si vous utilisez une version bêta telle que la version bêta d’Elements with Checkout Sessions…

Historiquement, certaines fonctionnalités en version bêta nécessitaient l’ajout d’en-têtes bêta à vos apiVersion utilisés par les requêtes Stripe.js (par exemple, '2025-02-24.acacia; custom_checkout_beta=v1'). Étant donné que nous ne prenons plus en charge ce remplacement de version d’API, vous ne pouvez pas ajouter explicitement d’en-têtes bêta directement aux requêtes API. Au lieu de cela, toutes les versions bêta Stripe.js pris en charge ajoutent automatiquement les en-têtes nécessaires lorsque l’indicateur bêta correspondant (par exemple custom_checkout_beta_5) est défini lors de l’initialisation de Stripe.js.

Pour acacia, ceci est expressément pris en charge pour custom_checkout_beta et nz_bank_account_beta. Si vous fournissez des en-têtes d’API pour d’autres versions bêta, écrivez à l’adresse e-mail qui vous a été fournie afin de déterminer les options de mise à niveau de Stripe.js ou de migration vers le comportement GA.

Prise en charge de Stripe.js v3

Nous continuerons à prendre en charge js.stripe.com/v3 dans le futur. Nous allons rétroporter les fonctionnalités vers cette version et maintenir Stripe.js v3 en tant que version permanente. Stripe.js v3 n’est pas obsolète, mais nous vous encourageons à mettre régulièrement à jour vos applications vers la dernière version de Stripe.js pour accéder aux fonctionnalités récentes qui ne peuvent pas être rétroportées en raison de leurs modifications majeures.