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.

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

Le système de gestion des versions de Stripe.js est un outil qui nous permet de publier de nouvelles fonctionnalités qui, autrement, pourraient être limitées par la prise en charge de la rétrocompatibilité. Nous publions ces changements importants dans les versions Stripe, deux fois par an.

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/basil/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.

Bien que la fonctionnalité d’exécution mineure de Stripe.js soit rétroportée vers d’anciennes versions de Stripe.js, les types TypeScript sur npm ne sont pas rétroportés vers d’anciennes versions majeures dans @stripe/stripe-js. Pour utiliser les types TypeScript les plus récents, mettez à jour Stripe.js et @stripe/stripe-js vers la version la plus récente.

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.

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.

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

Lorsque vous mettez à jour Stripe.js vers acacia à partir de la v3, cela peut entraîner des changements importants pour les requêtes API, selon la version d’API que vous avez précédemment utilisée pour les requêtes. Pour mettre à niveau des comptes plus anciens, nous vous recommandons de :

Identifiez la version actuelle de l’API utilisée sur votre compte.
Identifiez les changements qui affectent votre intégration Stripe.js.
Mettez progressivement à niveau la version de l’API utilisée par votre intégration Stripe.js vers 2024-12-18.acacia (si cela est adapté à vos besoins) avant de mettre à niveau Stripe.js vers acacia.

Versions bêta des API

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.