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

Mise à jour des versions Stripe

Ce guide couvre la mise à jour des versions de l'API Stripe, des SDKs côté serveur, 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 ex. 2026-06-24.dahlia, 2025-08-27.basil, 2024-12-18.acacia). La version d'API de votre compte détermine le comportement des requêtes et réponses.

Types de modifications

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

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

Modifications incompatibles (nécessitent des mises à jour de code) :

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

Consultez le Changelog API pour toutes les modifications entre les versions.

Versioning des SDKs côté 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-06-24.dahlia'

Stripe.api_version = '2026-06-24.dahlia'

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

Remplacement par requête :

stripe.Customer.create(
  email="customer@example.com",
  stripe_version='2026-06-24.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 pourraient 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 la version d'API avec laquelle vous intégrez dans votre code au lieu de vous appuyer sur la version d'API par défaut de votre compte :

// Bon : version explicite
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-06-24.dahlia'
});

// À éviter : reliance sur 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) publiées semestriellement.

Charger une version spécifique de Stripe.js

Via balise 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 :

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

Vous ne pouvez pas modifier cette association.

Migration depuis v3

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

Versioning des SDKs mobiles

Voir Mobile SDK Versioning pour les détails.

SDKs iOS et Android

Les deux plateformes suivent le semantic versioning (MAJOR.MINOR.PATCH) :

MAJOR : Modifications cassantes de l'API
MINOR : Nouvelle fonctionnalité (rétrocompatible)
PATCH : Corrections de bugs (rétrocompatible)

Les nouvelles fonctionnalités et correctifs ne sont publiés que 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) : modifications cassantes ET nouvelles fonctionnalités
Mises à jour de patch (y) : corrections de bugs critiques uniquement

Compatibilité backend

Tous les SDKs mobiles fonctionnent avec n'importe quelle version d'API Stripe que vous utilisez sur votre backend sauf si la documentation précise autrement.

Checklist de mise à jour

Consultez le Changelog API pour les modifications entre vos versions actuelle et cible
Vérifiez le Guide de mise à jour pour les conseils de migration
Mettez à jour la version du package SDK côté serveur (par ex. 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 de webhooks pour gérer les nouvelles structures d'événements
Mettez à jour la balise 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 acceptent jusqu'à 255 caractères (collation sensible à la casse)

Test des modifications 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-06-24.dahlia"

Ou dans le code :

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

Remarques importantes

Votre écouteur de webhook doit gérer gracieusement les types d'événements inconnus
Testez les webhooks avec la nouvelle structure de version avant la mise à jour
Les modifications cassantes sont étiquetées par zones de produit affectées (Payments, Billing, Connect, etc.)
Plusieurs versions d'API coexistent simultanément, permettant une adoption progressive

upgrade-stripe