La dernière version de l'API Stripe est 2026-07-29.dahlia - utilisez cette version lors de la mise à jour sauf si l'utilisateur spécifie une version cible différente.

Mise à niveau des versions Stripe

Ce guide couvre la mise à niveau des versions de l'API Stripe, des SDKs serveur, de Stripe.js et des SDKs mobiles.

Comprendre le versioning de l'API Stripe

Stripe utilise des versions d'API basées sur la date (par exemple, 2026-07-29.dahlia, 2025-08-27.basil, 2024-12-18.acacia). La version de l'API de votre compte détermine le comportement des requêtes et des réponses.

Types de changements

Changements rétrocompatibles (ne nécessitent pas de mises à jour du code) :

Nouvelles ressources API
Nouveaux paramètres de requête optionnels
Nouvelles propriétés dans les réponses existantes
Changements dans les longueurs des chaînes opaques (par exemple, les IDs d'objet)
Nouveaux types d'événements webhook

Changements cassants (nécessitent des mises à jour du code) :

Renommages ou suppressions de champs
Modifications comportementales
Suppression d'endpoints ou de paramètres

Consultez le Changelog API pour tous les changements entre les versions.

Versioning des SDKs serveur

Voir SDK Version Management pour les détails.

Langages dynamiquement typés (Ruby, Python, PHP, Node.js)

Ces SDKs offrent un contrôle de version flexible :

Configuration globale :

import stripe
stripe.api_version = '2026-07-29.dahlia'

Stripe.api_version = '2026-07-29.dahlia'

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-07-29.dahlia'
});

Remplacement par requête :

stripe.Customer.create(
  email="customer@example.com",
  stripe_version='2026-07-29.dahlia'
)

Langages fortement typés (Java, Go, .NET)

Ceux-ci utilisent une version d'API fixe correspondant à la date de sortie du SDK. Ne définissez pas une version d'API différente pour les langages fortement typés car les objets de réponse peuvent ne pas correspondre aux types forts du SDK. À la place, mettez à jour le SDK pour cibler une nouvelle version d'API.

Bonne pratique

Spécifiez toujours dans votre code la version d'API avec laquelle vous intégrez plutôt que de vous fier à la version d'API par défaut de votre compte :

// Bon : Version explicite
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-07-29.dahlia'
});

// À éviter : Dépendre de la valeur par défaut du compte
const stripe = require('stripe')('sk_test_xxx');

Versioning de Stripe.js

Voir Stripe.js Versioning pour les détails.

Stripe.js utilise un modèle evergreen avec des versions majeures (Acacia, Basil, Clover, Dahlia) tous les six mois.

Chargement de Stripe.js avec version

Via balise de script :

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

Via npm :

npm install @stripe/stripe-js

Les versions majeures npm correspondent à des versions spécifiques de Stripe.js.

Appairage des versions d'API

Chaque version de Stripe.js s'appaire automatiquement avec sa version d'API correspondante. Par exemple :

Stripe.js Dahlia utilise l'API 2026-07-29.dahlia
Stripe.js Acacia utilise l'API 2024-12-18.acacia

Vous ne pouvez pas remplacer cette association.

Migration depuis v3

Identifiez votre version d'API actuelle dans le code
Consultez le changelog pour les changements pertinents
Envisagez de mettre à jour progressivement votre version d'API avant de basculer les versions de Stripe.js
Stripe continue à supporter v3 indéfiniment

Versioning des SDKs mobiles

Voir Mobile SDK Versioning pour les détails.

SDKs iOS et Android

Les deux plates-formes suivent le semantic versioning (MAJEUR.MINEUR.CORRECTIF) :

MAJEUR : Changements cassants de l'API
MINEUR : Nouvelles fonctionnalités (rétrocompatibles)
CORRECTIF : Corrections de bugs (rétrocompatibles)

Les nouvelles fonctionnalités et corrections sortent uniquement sur la dernière version majeure. Mettez à jour régulièrement pour accéder aux améliorations.

SDK React Native

Utilise un modèle différent (schéma 0.x.y) :

Changements de version mineure (x) : Changements cassants ET nouvelles fonctionnalités
Mises à jour de correctif (y) : Corrections de bugs critiques uniquement

Compatibilité avec le backend

Tous les SDKs mobiles fonctionnent avec n'importe quelle version de l'API Stripe que vous utilisez sur votre backend sauf si la documentation le spécifie autrement.

Liste de contrôle de mise à niveau

Consultez le Changelog API pour les changements entre votre version actuelle et votre version cible
Vérifiez le Guide de mises à niveau pour les conseils de migration
Mettez à jour la version du package SDK serveur (par exemple, npm update stripe, pip install --upgrade stripe)
Mettez à jour le paramètre apiVersion dans l'initialisation de votre client Stripe
Testez votre intégration contre la nouvelle version d'API en utilisant l'en-tête Stripe-Version
Mettez à jour les gestionnaires webhook pour gérer les nouvelles structures d'événements
Mettez à jour la balise de script Stripe.js ou la version du package npm si nécessaire
Mettez à jour les versions des SDKs mobiles dans votre gestionnaire de packages si nécessaire
Stockez les IDs d'objet Stripe dans les bases de données qui accommodent jusqu'à 255 caractères (collation sensible à la casse)

Tester les changements de version d'API

Utilisez l'en-tête Stripe-Version pour tester votre code contre une nouvelle version sans modifier votre version par défaut :

curl https://api.stripe.com/v1/customers \
  -u sk_test_xxx: \
  -H "Stripe-Version: 2026-07-29.dahlia"

Ou dans le code :

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-07-29.dahlia'  // Tester avec la nouvelle version
});

Notes importantes

Votre écouteur webhook doit gérer les types d'événements non familiers avec élégance
Testez les webhooks avec la nouvelle structure de version avant la mise à niveau
Les changements cassants sont étiquetés par domaines de produits affectés (Payments, Billing, Connect, etc.)
Plusieurs versions d'API coexistent simultanément, permettant une adoption progressive

upgrade-stripe