La dernière version de l'API Stripe est 2026-04-22.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 exemple, 2026-04-22.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étro-compatibles (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 de la longueur des chaînes opaques (par exemple, les IDs d'objet)
Nouveaux types d'événements webhook

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

Renomination ou suppression de champs
Modifications du comportement
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 à typage dynamique (Ruby, Python, PHP, Node.js)

Ces SDKs offrent un contrôle de version flexible :

Configuration globale :

import stripe
stripe.api_version = '2026-04-22.dahlia'

Stripe.api_version = '2026-04-22.dahlia'

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

Remplacement par requête :

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

Langages à typage fort (Java, Go, .NET)

Ceux-ci utilisent une version d'API fixe correspondant à la date de publication du SDK. Ne définissez pas une version d'API différente pour les langages à typage fort 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 fier à la version d'API par défaut de votre compte :

// Bien : version explicite
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-04-22.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) sur une base bisannuelle.

Chargement de Stripe.js versionné

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-04-22.dahlia
Acacia Stripe.js utilise l'API 2024-12-18.acacia

Vous ne pouvez pas surcharger cette association.

Migration à partir de 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 basculer les versions 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 versioning sémantique (MAJEUR.MINEUR.CORRECTIF) :

MAJEUR : Modifications cassantes de l'API
MINEUR : Nouvelles fonctionnalités (rétro-compatibles)
CORRECTIF : Corrections de bugs (rétro-compatibles)

Les nouvelles fonctionnalités et corrections ne sont publiées 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 indication contraire dans la documentation.

Liste de contrôle 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 exemple, npm update stripe, pip install --upgrade stripe)
Mettez à jour le paramètre apiVersion lors de l'initialisation de votre client Stripe
Testez votre intégration avec 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 script Stripe.js ou la version du package npm si nécessaire
Mettez à jour les versions du SDK mobile dans votre gestionnaire de packages si nécessaire
Stockez les IDs d'objet Stripe dans les bases de données qui supportent jusqu'à 255 caractères (collation sensible à la casse)

Tester les modifications de version d'API

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

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

Ou dans le code :

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

Notes importantes

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

upgrade-stripe