# Mettre à niveau votre intégration Mettez à niveau votre intégration vers la dernière version de l’API. Consultez le [Journal des modifications développeur](https://docs.stripe.com/changelog.md) pour l’historique complet des modifications apportées à l’API de Stripe. Pour mettre à niveau votre intégration, suivez les étapes suivantes. Consultez le [journal des notifications](https://docs.stripe.com/changelog.md?api_usage=true) pour obtenir des informations spécifiques à votre intégration. ## Définissez la version cible de votre mise à niveau Veillez à spécifier dans votre code la version de l’API que vous utilisez pour votre intégration, au lieu de vous fier à la version d’API par défaut de votre compte. Pour tester une version plus récente pour les appels d’API, définissez l’en-tête `Stripe-Version` (dans les environnements live ou de test). Découvrez comment [définir une version d’API dans nos SDK côté serveur](https://docs.stripe.com/upgrades.md#specify-sdk-api-version). Consultez les versions d’API utilisées par votre intégration dans l’[onglet Vue d’ensemble](https://dashboard.stripe.com/workbench/overview) de [Workbench](https://docs.stripe.com/workbench/overview.md). Consultez le [journal des notifications](https://docs.stripe.com/changelog.md) pour trouver la version cible de votre mise à niveau. ## Spécifiez la version de l’API dans votre SDK Votre compte possède une *version d’API par défaut* (If an API request doesn’t specify a version, Stripe uses your account’s default API version, which you can set in the Stripe Dashboard. We recommend specifying the version for each request (either with the Stripe-Version HTTP header or by using a pinned SDK) so your code determines the API version instead of your Dashboard settings) qui définit la façon dont vous appelez l’API, les fonctionnalités auxquelles vous avez accès et la structure des réponses de l’API. Lorsque vous utilisez un [SDK côté serveur](https://docs.stripe.com/sdks.md#server-side-libraries), vos appels à l’API vers Stripe utilisent la version de l’API en vigueur lors de la publication du SDK. Vous ne pouvez pas cibler une autre version de l’API lorsque vous utilisez un langage fortement typé, comme Java, Go ou .NET. #### Ruby La bibliothèque [stripe-ruby](https://github.com/stripe/stripe-ruby) vous permet de définir la version de l’API globalement ou par requête. Si vous ne définissez pas de version d’API, les versions récentes de stripe-ruby utilisent la version d’API la plus récente au moment de la publication de votre version de stripe-ruby. Les versions de stripe-ruby antérieures à la [v9](https://github.com/stripe/stripe-ruby/blob/master/CHANGELOG.md#900---2023-08-16) utilisent la version d’API par défaut de votre compte. Pour définir la version de l’API de manière **globale** avec le SDK, attribuez la version à la propriété `Stripe.api_version` : ```ruby require 'stripe' # Don't put any keys in code. See /keys-best-practices. client = Stripe::StripeClient.new('<>', stripe_version: '2026-08-26.dahlia') ``` Ou définissez la version par requête : ```ruby require 'stripe' # Don't put any keys in code. See /keys-best-practices. client = Stripe::StripeClient.new('<>') intent = client.v1.payment_intents.retrieve( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', { stripe_version: '2026-08-26.dahlia', }, ) intent.capture ``` > Lorsque vous remplacez la version globalement ou par requête, les objets de réponse de l’API sont également renvoyés dans cette version. #### Python La bibliothèque [stripe-python](https://github.com/stripe/stripe-python) vous permet de définir la version de l’API globalement ou par requête. Si vous ne définissez pas de version d’API, les versions récentes de stripe-python utilisent la version d’API la plus récente au moment de la publication de votre version de stripe-python. Les versions de stripe-python antérieures à [v6](https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md#600---2023-08-16) utilisent la version d’API par défaut de votre compte. Pour définir la version de l’API de manière **globale** avec le SDK, attribuez la version à la propriété `Stripe.api_version` : ```python import stripe # Don't put any keys in code. See /keys-best-practices. stripe.api_key = <> stripe.api_version = '2026-08-26.dahlia' ``` Ou définissez la version par requête : ```python import stripe intent = stripe.PaymentIntent.retrieve( "pi_1DlIVK2eZvKYlo2CW4yj5l2C", stripe_version="2026-08-26.dahlia", ) intent.capture() ``` > Lorsque vous remplacez la version globalement ou par requête, les objets de réponse de l’API sont également renvoyés dans cette version. #### PHP La bibliothèque [stripe-php](https://github.com/stripe/stripe-php) vous permet de définir la version de l’API globalement ou par requête. Si vous ne définissez pas de version d’API, les versions récentes de stripe-php utilisent la version d’API la plus récente au moment de la publication de votre version de stripe-php. Les versions de stripe-php antérieures à la [v11](https://github.com/stripe/stripe-php/blob/master/CHANGELOG.md#1100---2023-08-16) utilisent la version d’API par défaut de votre compte. Pour définir la version de l’API de manière **globale** avec le SDK, transmettez la version à la méthode `\Stripe\Stripe::setApiVersion()` : ```php $stripe = new \Stripe\StripeClient([ // Don't put any keys in code. See /keys-best-practices. "api_key" => "<>", "stripe_version" => "2026-08-26.dahlia" ]); ``` Ou définissez la version par requête : ```php $intent = $stripe->paymentIntents->capture( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', [], ['stripe_version' => '2026-08-26.dahlia'] ); ``` > Lorsque vous remplacez la version globalement ou par requête, les objets de réponse de l’API sont également renvoyés dans cette version. #### Java Comme Java est un langage de programmation fortement typé, la version de l’API utilisée dans le SDK est *fixe* et correspond à la dernière version de l’API au moment de la publication du SDK. Nous vous déconseillons de définir une version d’API différente pour les langages de programmation fortement typés, car les objets de réponse peuvent ne pas correspondre aux types forts dans le SDK et entraîner l’échec des requêtes. Par exemple, si la version de l’API que vous ciblez nécessite des paramètres qui ne sont pas présents dans les types de SDK, la requête échoue. #### Node La bibliothèque [stripe-node](https://github.com/stripe/stripe-node) vous permet de définir la version de l’API globalement ou par requête. Si vous ne définissez pas de version d’API, les versions récentes de stripe-node utilisent la version d’API la plus récente au moment de la publication de votre version de stripe-node. Les versions de stripe-node antérieures à la [v12](https://github.com/stripe/stripe-node/blob/master/CHANGELOG.md#1200---2023-04-06) utilisent la version d’API par défaut de votre compte. Pour définir la version de l’API de manière **globale** avec le SDK, fournissez l’option `apiVersion` : ```javascript // Don't put any keys in code. See /keys-best-practices. const stripe = require('stripe')('<>', { apiVersion: '2026-08-26.dahlia', }); ``` Ou définissez la version par requête : ```javascript const intent = await stripe.paymentIntents.retrieve('pi_1DlIVK2eZvKYlo2CW4yj5l2C', { apiVersion: '2026-08-26.dahlia', }); ``` #### Utilisation de Typescript Les types TypeScript reflètent la dernière version de l’API au moment de la publication. Cette version est encodée dans le [fichier API_VERSION](https://github.com/stripe/stripe-node/blob/master/API_VERSION). Importez Stripe en mode d’importation par défaut et instanciez-le en tant que `new Stripe()` avec la dernière version de l’API. ```javascript import Stripe from 'stripe'; const stripe = new Stripe('<>', { apiVersion: '2026-08-26.dahlia' }); ``` #### Go Comme Go est un langage de programmation fortement typé, la version de l’API utilisée dans le SDK est *fixe* et correspond à la dernière version de l’API au moment de la publication du SDK. Nous vous déconseillons de définir une version d’API différente pour les langages de programmation fortement typés, car les objets de réponse peuvent ne pas correspondre aux types forts dans le SDK et entraîner l’échec des requêtes. Par exemple, si la version de l’API que vous ciblez nécessite des paramètres qui ne sont pas présents dans les types de SDK, la requête échoue. #### .NET Comme C# est un langage de programmation fortement typé, la version de l’API utilisée dans le SDK .NET est *fixe* et correspond à la dernière version de l’API au moment de la publication du SDK. Nous vous déconseillons de définir une version d’API différente pour les langages de programmation fortement typés, car les objets de réponse peuvent ne pas correspondre aux types forts dans le SDK et entraîner l’échec des requêtes. Par exemple, si la version de l’API que vous ciblez nécessite des paramètres qui ne sont pas présents dans les types de SDK, la requête échoue. #### cURL ```sh curl https://api.stripe.com/v1/charges \ -u <>: \ -H "Stripe-Version: 2026-08-26.dahlia" ``` #### Interface de ligne de commande Stripe ```sh stripe charges create --stripe-version 2026-08-26.dahlia ``` ## Mettez à jour votre code pour gérer les modifications de l’API Passez en revue vos requêtes les plus importantes et mettez à jour votre code pour prendre en charge les changements de la réponse. Pour chaque requête, consultez les [modifications majeures pertinentes dans le journal des modifications](https://docs.stripe.com/changelog.md?api_usage=true) afin de comprendre les changements nécessaires pour adopter votre version cible. Consultez vos requêtes d’API dans l’[onglet Vue d’ensemble](https://dashboard.stripe.com/workbench/overview) de [Workbench](https://docs.stripe.com/workbench/overview.md). ## Mettez à jour vos destinations d’événements > Les [événements légers](https://docs.stripe.com/event-destinations.md#thin-events) pour les ressources de l’API v1 sont disponibles en version bêta privée. Vous pouvez les utiliser pour simplifier les mises à niveau d’intégration sans modifier la configuration de votre webhook. Auparavant, les événements légers prenaient uniquement en charge les ressources de l’API v2. [En savoir plus et demander un accès](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). Examinez chaque destination d’événements qui reçoit des événements snapshot, notamment les endpoints de webhook et les destinations cloud pour Amazon EventBridge et Azure Event Grid. Pour les événements snapshot, la propriété [snapshot_api_version](https://docs.stripe.com/api/v2/core/event-destinations/object.md#v2_event_destination_object-snapshot_api_version) de la destination détermine la version de l’API utilisée pour générer la charge utile de l’événement. Ce paramètre est indépendant de la version de l’API utilisée par votre SDK côté serveur. Les charges utiles des événements thin ne sont pas versionnées. Vous pouvez définir `snapshot_api_version` uniquement lors de la création d’une destination d’événements. Pour utiliser une autre version de l’API, créez et testez une destination configurée avec cette version avant de supprimer la destination existante. Si les deux destinations sont actives pendant la migration, votre gestionnaire d’événements doit être idempotent, car Stripe transmet les événements auxquels vous êtes abonné aux deux destinations. ## Mettez à jour vos endpoints de webhook Pour mettre à niveau vos endpoints de webhook, vous devez [vérifier les signatures de webhook entrantes](https://docs.stripe.com/webhooks.md#verify-events) et autoriser le trafic provenant des [adresses IP publiques](https://docs.stripe.com/ips.md) de Stripe. Vous devez également créer de nouveaux endpoints, y rediriger le trafic, puis désactiver les anciens endpoints. #### Créez de nouveaux endpoints de webhook désactivés Créez un nouvel endpoint de webhook avec les paramètres suivants : - `url` : la même URL que votre endpoint de webhook d’origine, mais ajoutez un paramètre de requête pour différencier les événements envoyés aux deux endpoints différents. Par exemple `https://example.com/webhooks?version=2024-04-10`. - `enabled_events` : les mêmes événements que votre endpoint de webhook d’origine. - `api_version`: la version d’API à laquelle vous souhaitez passer. Si vous faites une mise à niveau vers la dernière version de l’API, vous pouvez utiliser le Dashboard ou l’API pour créer l’endpoint. Pour les autres versions, utilisez l’API pour configurer une version spécifique. Après avoir créé le nouvel endpoint webhook, désactivez-le. Vous le réactiverez à l’étape suivante. ![Deux endpoints, mais seul le plus ancien envoie des événements](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png) #### Mettez à jour le code de votre webhook afin d’ignorer les événements envoyés vers le nouvel endpoint Mettez à jour votre code de traitement des événements : - Si le paramètre de la requête concerne l’ancienne version de l’API, traitez-le comme d’habitude. - Si le paramètre de la requête concerne la version la plus récente de l’API, ignorez l’événement et renvoyez une réponse 200 afin d’éviter les tentatives d’envoi. Ensuite, activez le nouvel endpoint de webhook que vous avez créé à l’étape précédente. À ce stade, chaque événement est envoyé deux fois : une fois avec l’ancienne version de l’API et une fois avec la nouvelle. ![Deux endpoints envoient des événements, mais seuls ceux du plus ancien sont traités](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png) #### Mettez à jour le code de votre webhook afin de traiter les événements destinés au nouvel endpoint Mettez à jour votre code de traitement des événements : - Si le paramètre de la requête concerne la version la plus ancienne, ignorez l’événement. Nous vous recommandons de renvoyer un code d’état 400 pour permettre à Stripe de réessayer automatiquement l’événement. Ainsi, si vous avez besoin d’annuler, vous aurez la garantie que les événements sont renvoyés à l’ancien endpoint de webhook. - Si le paramètre de la requête concerne la nouvelle version, traitez-le. ![Deux endpoints envoient des événements, mais seuls ceux du plus récent sont traités](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png) #### Surveillez vos endpoints de webhook Surveillez le trafic vers les nouveaux endpoints de webhook pour confirmer qu’ils traitent correctement les événements. Si les événements ne sont pas gérés correctement par votre nouveau code, essayez ce qui suit : 1. Revenez à la version précédente de votre code. 2. Désactivez temporairement le nouvel endpoint de webhook. 3. Traitez les événements en échec (si vous avez renvoyé un code d’état 400 comme indiqué à l’étape précédente, Stripe renvoie automatiquement tous les événements). 4. Enquêtez sur le problème et résolvez-le. 5. Activez le nouvel endpoint de webhook et reprenez la surveillance. #### Désactivez l’ancien endpoint de webhook Une fois la mise à niveau réussie, désactivez l’ancien endpoint de webhook pour empêcher votre serveur de renvoyer un état `400`. Si vous ne le désactivez pas, cela peut causer des problèmes avec les intégrations qui dépendent d’une réponse `200`. Après avoir désactivé l’ancien endpoint de webhook, Stripe ne redistribuera pas les événements qui ont renvoyé un `400`. ![Deux endpoints, mais seul le plus récent envoie des événements](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png) ## Testez et surveillez votre intégration [Testez votre intégration](https://docs.stripe.com/testing.md) dans un [environnement de test](https://docs.stripe.com/sandboxes.md) pour confirmer qu’elle prend en charge la nouvelle version comme prévu. En plus des conseils généraux de test, suivez les directives concernant les produits et les ressources utilisés par votre intégration : - [Billing](https://docs.stripe.com/billing/testing.md) : utilisez des [horloges de simulation](https://docs.stripe.com/billing/testing/test-clocks.md) pour [simuler des abonnements](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md). - [Invoicing](https://docs.stripe.com/invoicing/integration/testing.md) : testez les notifications de webhook, les échecs de paiement et d’autres scénarios. - [Connect](https://docs.stripe.com/connect/testing.md) : créez des [comptes de test](https://docs.stripe.com/connect/testing.md?accounts-namespace=v2#creating-accounts) et utilisez-les pour les [tests de vérification](https://docs.stripe.com/connect/testing-verification.md). - [Terminal](https://docs.stripe.com/terminal/references/testing.md) : testez les [mises à jour simulées des lecteurs](https://docs.stripe.com/terminal/references/testing.md?terminal-card-present-integration=terminal#simulated-reader-updates). - [Payment Intents](https://docs.stripe.com/payments/quickstart-payment-intents.md#test-payment) : créez des PaymentIntents et utilisez des numéros de carte bancaire de test pour simuler des paiements.