# Mettre votre intégration à niveau Mettre à niveau votre intégration vers la dernière version de l’API. Consultez le [journal des modifications du développeur](https://docs.stripe.com/changelog.md) pour obtenir le registre complet des modifications apportées à l’API de Stripe. Pour mettre à niveau votre intégration, suivez les étapes ci-dessous. Consultez le [journal des modifications](https://docs.stripe.com/changelog.md?api_usage=true) pour obtenir des informations propres à votre intégration. ## Définissez la version cible pour votre mise à niveau Assurez-vous de spécifier la version de l’API que vous intégrez dans votre code au lieu de vous fier à la version de l’API par défaut de votre compte. Pour tester une version plus récente pour les appels à l’API, définissez l’en-tête `Stripe-Version` (dans les environnements de production ou de test). Découvrez comment [définir une version de l’API dans nos trousses SDK côté serveur](https://docs.stripe.com/upgrades.md#specify-sdk-api-version). Consultez les versions de l’API utilisées par votre intégration dans l’onglet [Aperçu](https://dashboard.stripe.com/workbench/overview) de [Workbench](https://docs.stripe.com/workbench/overview.md). Vérifiez le [journal des modifications](https://docs.stripe.com/changelog.md) pour trouver la version cible de votre mise à niveau. ## Spécifiez la version de l’API dans votre trousse SDK Votre compte possède une *version de l’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 comment vous appelez l’API, les fonctionnalités auxquelles vous avez accès et la structure des réponses de l’API. Lorsque vous utilisez une [trousse SDK côté serveur](https://docs.stripe.com/sdks.md#server-side-libraries), vos appels à l’API à Stripe utilisent la version de l’API qui était actuelle lors de la publication de la trousse SDK. Vous ne pouvez pas cibler une version différente 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 pour chaque 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 à [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 d’API **globalement** avec la trousse 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 pour chaque requête. Si vous ne définissez aucune version de l’API, les versions récentes de stripe-python utilisent la dernière version de l’API 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 par défaut de l’API de votre compte. Pour définir la version de l’API **globalement** avec la trousse 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 pour chaque requête. Si vous ne définissez pas de version d’API, les versions récentes de stripe-php utilisent la version d’API qui était la plus récente au moment de la publication de votre version de stripe-php. Les versions de stripe-php antérieures à [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 d’API **globalement** avec la trousse 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 Puisque Java est un langage de programmation fortement typé, la version de l’API utilisée dans la trousse SDK est *fixe* et correspond à la dernière version de l’API au moment de la publication de la trousse SDK. Nous ne recommandons pas de définir une version d’API différente pour les langages de programmation fortement typés, car les objets de réponse pourraient ne pas correspondre aux types forts de la trousse SDK et entraîner des échecs de requête. 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 la trousse 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 pour chaque requête. Si vous ne définissez pas de version d’API, les versions récentes de stripe-node utiliseront la version d’API qui était la plus récente au moment de la publication de votre version de stripe-node. Les versions de stripe-node antérieures à [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 d’API **globalement** avec la trousse 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 version la plus récente de l’API. ```javascript import Stripe from 'stripe'; const stripe = new Stripe('<>', { apiVersion: '2026-08-26.dahlia' }); ``` #### Go Puisque Go est un langage de programmation fortement typé, la version de l’API utilisée dans la trousse SDK est *fixe* et correspond à la dernière version de l’API au moment de la publication de la trousse SDK. Nous ne recommandons pas de définir une version d’API différente pour les langages de programmation fortement typés, car les objets de réponse pourraient ne pas correspondre aux types forts de la trousse SDK et entraîner des échecs de requête. 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 la trousse SDK, la requête échoue. #### .NET Puisque C# est un langage de programmation fortement typé, la version de l’API utilisée dans la trousse SDK .NET est *fixe* et correspond à la dernière version de l’API au moment de la publication de la trousse SDK. Nous ne recommandons pas de définir une version d’API différente pour les langages de programmation fortement typés, car les objets de réponse pourraient ne pas correspondre aux types forts de la trousse SDK et entraîner des échecs de requête. 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 la trousse 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 Vérifiez vos requêtes les plus importantes et mettez à jour votre code pour gérer les modifications de la réponse. Pour chaque requête, vérifiez les [modifications majeures pertinentes dans le journal des modifications](https://docs.stripe.com/changelog.md?api_usage=true) pour comprendre les modifications requises pour adopter votre version cible. Consultez vos requêtes d’API dans l’onglet [Aperçu](https://dashboard.stripe.com/workbench/overview) de [Workbench](https://docs.stripe.com/workbench/overview.md). ## Mettre à 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 lien de rappel HTTP. Auparavant, les événements légers prenaient uniquement en charge les ressources de l’API v2. [En savoir plus et demander l’accès](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). Vérifiez chaque destination d’événements qui reçoit des événements d’instantané, y compris les points de terminaison de liens de rappel HTTP et les destinations infonuagiques pour Amazon EventBridge et Azure Event Grid. Pour les événements d’instantané, 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 contrôle 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 trousse SDK côté serveur. Les charges utiles d’événements légers ne sont pas versionnées. Vous pouvez définir `snapshot_api_version` uniquement lorsque vous créez une destination d’événements. Pour utiliser une version de l’API différente, 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 souscrits aux deux destinations. ## Mettez à jour vos points de terminaison de lien de rappel HTTP Pour mettre à niveau les points de terminaison de vos liens de rappel HTTP, vous devez [vérifier les signatures des liens de rappel HTTP entrants](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 points de terminaison, y rediriger le trafic, puis désactiver les anciens points de terminaison. #### Créez de nouveaux points de terminaison de lien de rappel HTTP désactivés Créez un nouveau point de terminaison de lien de rappel HTTP avec les paramètres suivants : - `url` : la même URL que votre point de terminaison de lien de rappel HTTP d’origine, mais ajoutez un paramètre de requête pour distinguer les événements envoyés aux deux différents points de terminaison. Par exemple `https://example.com/webhooks?version=2024-04-10`. - `enabled_events` : les mêmes événements que votre point de terminaison de lien de rappel HTTP d’origine. - `api_version` : la version de l’API vers laquelle vous souhaitez effectuer la mise à niveau. Si vous effectuez la mise à niveau vers la dernière version de l’API, vous pouvez utiliser le Dashboard ou l’API pour créer le point de terminaison. Pour les autres versions, utilisez l’API pour définir une version spécifique. Après avoir créé le nouveau point de terminaison de lien de rappel HTTP, désactivez-le. Vous le réactiverez à l’étape suivante. ![Deux points de terminaison, mais seul l’ancien envoie des événements](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png) #### Mettez à jour le code de votre lien de rappel HTTP pour ignorer les événements envoyés au nouveau point de terminaison Mettez à jour votre code de traitement des événements : - Si le paramètre de la requête correspond à l’ancienne version de l’API, traitez-le comme d’habitude. - Si le paramètre de la requête correspond à la nouvelle version de l’API, ignorez l’événement et renvoyez une réponse 200 pour éviter les nouvelles tentatives d’envoi. Ensuite, activez le nouveau point de terminaison de lien de rappel HTTP 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 points de terminaison envoient des événements, mais seul l’ancien est traité](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png) #### Mettez à jour le code de votre lien de rappel HTTP pour traiter les événements pour les nouveaux points de terminaison Mettez à jour votre code de traitement des événements : - Si le paramètre de requête concerne l’ancienne version, ignorez l’événement. Nous vous recommandons de renvoyer un état 400 pour permettre à Stripe de réessayer automatiquement l’événement. Cela garantit que si vous devez revenir en arrière, les événements sont renvoyés à l’ancien point de terminaison du lien de rappel HTTP. - Si le paramètre de requête concerne la nouvelle version, traitez-le. ![Deux points de terminaison envoient des événements, mais seul le nouveau est traité](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png) #### Surveillez vos points de terminaison de lien de rappel HTTP Surveillez le trafic vers les nouveaux points de terminaison de lien de rappel HTTP pour confirmer qu’ils traitent correctement les événements. Si les événements ne sont pas correctement pris en charge par votre nouveau code, essayez ce qui suit : 1. Revenez à la version antérieure de votre code. 2. Désactivez temporairement le nouveau point de terminaison du lien de rappel HTTP. 3. Traitez les événements ayant échoué (si vous avez renvoyé un état 400 comme décrit à l’étape précédente, Stripe renvoie automatiquement tous les événements). 4. Examinez et corrigez le problème. 5. Activez le nouveau point de terminaison du lien de rappel HTTP et reprenez la surveillance. #### Désactivez l’ancien point de terminaison de lien de rappel HTTP Une fois la mise à niveau réussie, désactivez l’ancien point de terminaison de lien de rappel HTTP pour empêcher votre serveur de renvoyer l’é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`. Une fois que vous aurez désactivé l’ancien point de terminaison de lien de rappel HTTP, Stripe ne renverra plus les événements qui ont renvoyé un état `400`. ![Deux points de terminaison, mais seul le nouveau envoie des événements](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png) ## Testez et suivez votre intégration [Testez votre intégration](https://docs.stripe.com/testing.md) dans un [bac à sable](https://docs.stripe.com/sandboxes.md) pour confirmer qu’elle gère la nouvelle version comme prévu. En plus des conseils de test généraux, suivez les directives pour les produits et les ressources que votre intégration utilise : - [Billing](https://docs.stripe.com/billing/testing.md) : utilisez les [horodatages de test](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 lien de rappel HTTP, 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 de lecteur simulées](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 de test pour simuler des paiements.