# Ihre Integration aktualisieren Aktualisieren Sie Ihre Integration auf die neueste API-Version. Check the [Developer Changelog](https://docs.stripe.com/changelog.md) for the complete record of changes to the Stripe API. Um Ihre Integration zu aktualisieren, führen Sie die folgenden Schritte aus. Durchsuchen Sie das [Änderungsprotokoll](https://docs.stripe.com/changelog.md?api_usage=true) nach spezifischen Informationen zu Ihrer Integration. ## Definieren Sie die Zielversion für Ihr Upgrade Stellen Sie sicher, dass Sie in Ihrem Code die API-Version angeben, mit der Sie die Integration vornehmen, anstatt sich auf die Standard-API-Version Ihres Kontos zu verlassen. Um eine neuere Version für API-Aufrufe zu testen, legen Sie den Header `Stripe-Version` fest (in Produktions- oder Testumgebungen). Erfahren Sie, [wie Sie eine API-Version in unseren serverseitigen SDKs festlegen können](https://docs.stripe.com/upgrades.md#specify-sdk-api-version). Überprüfen Sie auf der Registerkarte [Übersicht](https://dashboard.stripe.com/workbench/overview) in [Workbench](https://docs.stripe.com/workbench/overview.md), welche API-Versionen Ihre Integration verwendet. Prüfen Sie das [Änderungsprotokoll](https://docs.stripe.com/changelog.md), um die Zielversion für Ihr Upgrade zu finden. ## Geben Sie die API-Version in Ihrem SDK an Ihr Konto verfügt über eine *Standard-API-Version* (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), die festlegt, wie Sie die API aufrufen, auf welche Funktionalität Sie zugreifen können und wie API-Antworten strukturiert sind. Wenn Sie ein [serverseitiges SDK](https://docs.stripe.com/sdks.md#server-side-libraries) verwenden, verwenden Ihre API-Aufrufe an Stripe die API-Version, die bei Veröffentlichung des SDK aktuell war. Wenn Sie eine stark typisierte Sprache wie Java, Go oder .NET verwenden, können Sie keine andere API-Version als Ziel festlegen. #### Ruby Mit der Bibliothek [stripe-ruby](https://github.com/stripe/stripe-ruby) können Sie die API-Version entweder global oder für jede einzelne Anfrage festlegen. Wenn Sie keine API-Version festlegen, verwenden aktuelle Versionen von stripe-ruby die API-Version, die zum Zeitpunkt der Veröffentlichung Ihrer Version von stripe-ruby am aktuellsten war. Versionen von stripe-ruby vor [v9](https://github.com/stripe/stripe-ruby/blob/master/CHANGELOG.md#900---2023-08-16) verwenden die Standard-API-Version Ihres Kontos. Um die API-Version **global** mit dem SDK festzulegen, weisen Sie der Eigenschaft `Stripe.api_version` die Version zu: ```ruby require 'stripe' # Don't put any keys in code. See /keys-best-practices. client = Stripe::StripeClient.new('<>', stripe_version: '2026-09-30.endive') ``` Oder legen Sie die Version anfragebasiert fest: ```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-09-30.endive', }, ) intent.capture ``` > Wenn Sie die Version global oder anfragebasiert überschreiben, werden die API-Antwortobjekte ebenfalls in dieser Version zurückgegeben. #### Python Mit der Bibliothek [stripe-python](https://github.com/stripe/stripe-python) können Sie die API-Version global oder für jede einzelne Anfrage festlegen. Wenn Sie keine API-Version festlegen, verwenden neuere Versionen von stripe-python die API-Version, die zum Zeitpunkt der Veröffentlichung Ihrer Version von stripe-python die neueste war. Versionen von stripe-python vor [v6](https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md#600---2023-08-16) verwenden die Standard-API-Version Ihres Kontos. Um die API-Version **global** mit dem SDK festzulegen, weisen Sie der Eigenschaft `Stripe.api_version` die Version zu: ```python import stripe # Don't put any keys in code. See /keys-best-practices. stripe.api_key = <> stripe.api_version = '2026-09-30.endive' ``` Oder legen Sie die Version anfragebasiert fest: ```python import stripe intent = stripe.PaymentIntent.retrieve( "pi_1DlIVK2eZvKYlo2CW4yj5l2C", stripe_version="2026-09-30.endive", ) intent.capture() ``` > Wenn Sie die Version global oder anfragebasiert überschreiben, werden die API-Antwortobjekte ebenfalls in dieser Version zurückgegeben. #### PHP Mit der Bibliothek [stripe-php](https://github.com/stripe/stripe-php) können Sie die API-Version entweder global oder für jede einzelne Anfrage festlegen. Wenn Sie keine API-Version festlegen, verwenden aktuelle Versionen von stripe-php die API-Version, die zum Zeitpunkt der Veröffentlichung Ihrer Version von stripe-php am aktuellsten war. Versionen von stripe-php vor [v11](https://github.com/stripe/stripe-php/blob/master/CHANGELOG.md#1100---2023-08-16) verwenden die Standard-API-Version Ihres Kontos. Um die API-Version **global** mit dem SDK festzulegen, übergeben Sie die Version an die Methode `\Stripe\Stripe::setApiVersion()`: ```php $stripe = new \Stripe\StripeClient([ // Don't put any keys in code. See /keys-best-practices. "api_key" => "<>", "stripe_version" => "2026-09-30.endive" ]); ``` Oder legen Sie die Version anfragebasiert fest: ```php $intent = $stripe->paymentIntents->capture( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', [], ['stripe_version' => '2026-09-30.endive'] ); ``` > Wenn Sie die Version global oder anfragebasiert überschreiben, werden die API-Antwortobjekte ebenfalls in dieser Version zurückgegeben. #### Java Da Java eine stark typisierte Programmiersprache ist, ist die im SDK verwendete API-Version *fest* und entspricht der neuesten API-Version zum Zeitpunkt der SDK-Veröffentlichung. Wir empfehlen, keine andere API-Version für stark typisierte Programmiersprachen festzulegen, da die Antwortobjekte möglicherweise nicht mit den starken Typen im SDK übereinstimmen und zu Anfragefehlern führen können. Wenn beispielsweise die von Ihnen genutzte API-Version Parameter erfordert, die in den SDK-Typen nicht vorhanden sind, schlägt die Anfrage fehl. #### Node Mit der Bibliothek [stripe-node](https://github.com/stripe/stripe-node) können Sie die API-Version entweder global oder für jede einzelne Anfrage festlegen. Wenn Sie keine API-Version festlegen, verwenden neuere Versionen des stripe-node die API-Version, die zum Zeitpunkt der Veröffentlichung Ihrer Version von stripe-node am aktuellsten war. Versionen von stripe-node vor [v12](https://github.com/stripe/stripe-node/blob/master/CHANGELOG.md#1200---2023-04-06) verwenden die Standard-API-Version Ihres Kontos. Um die API-Version **global** mit dem SDK festzulegen, geben Sie die Option `apiVersion` an: ```javascript // Don't put any keys in code. See /keys-best-practices. const stripe = require('stripe')('<>', { apiVersion: '2026-09-30.endive', }); ``` Oder legen Sie die Version anfragebasiert fest: ```javascript const intent = await stripe.paymentIntents.retrieve('pi_1DlIVK2eZvKYlo2CW4yj5l2C', { apiVersion: '2026-09-30.endive', }); ``` #### Nutzung von Typescript Die TypeScript-Typen spiegeln die zum Zeitpunkt der Veröffentlichung aktuellste API-Version wider. Diese Version ist in der Datei [API_VERSION](https://github.com/stripe/stripe-node/blob/master/API_VERSION) codiert. Importieren Sie Stripe als Standardimport und instanziieren Sie es als `new Stripe()` mit der neuesten API-Version. ```javascript import Stripe from 'stripe'; const stripe = new Stripe('<>', { apiVersion: '2026-09-30.endive' }); ``` #### Go Da Go eine stark typisierte Programmiersprache ist, ist die im SDK verwendete API-Version *fest* und entspricht der neuesten API-Version zum Zeitpunkt der SDK-Veröffentlichung. Wir empfehlen, keine andere API-Version für stark typisierte Programmiersprachen festzulegen, da die Antwortobjekte möglicherweise nicht mit den starken Typen im SDK übereinstimmen und zu Anfragefehlern führen können. Wenn beispielsweise die von Ihnen genutzte API-Version Parameter erfordert, die in den SDK-Typen nicht vorhanden sind, schlägt die Anfrage fehl. #### .NET Da C# eine stark typisierte Programmiersprache ist, ist die im .NET SDK verwendete API-Version *fest* und entspricht der neuesten API-Version zum Zeitpunkt der SDK-Veröffentlichung. Wir empfehlen, keine andere API-Version für stark typisierte Programmiersprachen festzulegen, da die Antwortobjekte möglicherweise nicht mit den starken Typen im SDK übereinstimmen und zu Anfragefehlern führen können. Wenn beispielsweise die von Ihnen genutzte API-Version Parameter erfordert, die in den SDK-Typen nicht vorhanden sind, schlägt die Anfrage fehl. #### cURL ```sh curl https://api.stripe.com/v1/charges \ -u <>: \ -H "Stripe-Version: 2026-09-30.endive" ``` #### Stripe-CLI ```sh stripe charges create --stripe-version 2026-09-30.endive ``` ## Aktualisieren Sie Ihren Code, um API-Änderungen zu verarbeiten Überprüfen Sie Ihre wichtigsten Anfragen und aktualisieren Sie Ihren Code, um Änderungen an der Antwort zu verarbeiten. Überprüfen Sie für jede Anfrage die [entsprechenden kompatibilitätsbrechenden Änderungen im Änderungsprotokoll](https://docs.stripe.com/changelog.md?api_usage=true), um zu verstehen, welche Anpassungen für die Umstellung auf Ihre Zielversion erforderlich sind. Sehen Sie sich Ihre API-Anfragen auf der Registerkarte [Übersicht](https://dashboard.stripe.com/workbench/overview) in [Workbench](https://docs.stripe.com/workbench/overview.md) an. ## Ihre Ereignisziele aktualisieren Überprüfen Sie jedes Ereignisziel, das Snapshot-Ereignisse empfängt, einschließlich Webhook-Endpoints und Cloud-Ziele für Amazon EventBridge und Azure Event Grid. Bei Snapshot-Ereignissen bestimmt die Eigenschaft [snapshot_api_version](https://docs.stripe.com/api/v2/core/event-destinations/object.md#v2_event_destination_object-snapshot_api_version) des Ziels die API-Version, die zum Rendern der Nutzlast des Ereignisses verwendet wird. Diese Einstellung ist unabhängig von der API-Version, die von Ihrem serverseitigen SDK verwendet wird. Nutzlasten von Thin-Ereignissen sind nicht versioniert. Sie können `snapshot_api_version` nur festlegen, wenn Sie ein Ereignisziel erstellen. Um eine andere API-Version zu verwenden, erstellen und testen Sie ein mit dieser Version konfiguriertes Ziel, bevor Sie das vorhandene Ziel löschen. Wenn während der Migration beide Ziele aktiv sind, muss Ihr Ereignis-Handler idempotent sein, da Stripe abonnierte Ereignisse an beide Ziele übermittelt. ## Aktualisieren Sie Ihre Webhook-Endpoints Um Ihre Webhook-Endpoints zu aktualisieren, müssen Sie die [Signaturen eingehender Webhooks überprüfen](https://docs.stripe.com/webhooks.md#verify-events) und den Datenverkehr von den [öffentlichen IP-Adressen](https://docs.stripe.com/ips.md) von Stripe zulassen. Außerdem müssen Sie neue Endpoints erstellen, den Datenverkehr auf diese umleiten und anschließend die alten Endpoints deaktivieren. #### Erstellen Sie neue deaktivierte Webhook-Endpoints Erstellen Sie einen neuen Webhook-Endpoint mit den folgenden Parametern: - `url`: dieselbe URL wie Ihr ursprünglicher Webhook-Endpoint, aber fügen Sie einen Abfrageparameter hinzu, um zwischen Ereignissen zu unterscheiden, die an die beiden verschiedenen Endpoints gesendet werden. Zum Beispiel `https://example.com/webhooks?version=2024-04-10`. - `enabled_events`: dieselben Ereignisse wie Ihr ursprünglicher Webhook-Endpoint. - `api_version`: die API-Version, auf die Sie das Upgrade durchführen möchten. Wenn Sie auf die neueste API-Version aktualisieren, können Sie den Endpoint über das Dashboard oder die API erstellen. Verwenden Sie für andere Versionen die API, um eine bestimmte Version festzulegen. Deaktivieren Sie den neuen Webhook-Endpoint, nachdem Sie ihn erstellt haben. Im nächsten Schritt werden Sie ihn wieder aktivieren. ![Zwei Endpoints, aber nur der alte sendet Ereignisse](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png) #### Aktualisieren Sie Ihren Webhook-Code so, dass an den neuen Endpoint gesendete Ereignisse ignoriert werden Aktualisieren Sie Ihren Code für die Ereignisverarbeitung: - Wenn der Abfrageparameter für die ältere API-Version gilt, verarbeiten Sie ihn wie gewohnt. - Wenn der Abfrageparameter für die neuere API-Version gilt, ignorieren Sie das Ereignis und geben Sie eine 200-Antwort zurück, um erneute Übermittlungsversuche zu verhindern. Aktivieren Sie als Nächstes den neuen Webhook-Endpoint, den Sie im vorherigen Schritt erstellt haben. Zu diesem Zeitpunkt wird jedes Ereignis zweimal gesendet: einmal mit der alten API-Version und einmal mit der neuen. ![Zwei Endpoints, die Ereignisse senden, aber nur den alten verarbeiten](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png) #### Aktualisieren Sie Ihren Webhook-Code so, dass Ereignisse für den neuen Endpoint verarbeitet werden Aktualisieren Sie Ihren Code für die Ereignisverarbeitung: - Wenn der Abfrageparameter für die ältere Version gilt, ignorieren Sie das Ereignis. Wir empfehlen, einen 400-Status zurückzugeben, damit Stripe das Ereignis automatisch wiederholen kann. Dadurch wird sichergestellt, dass Ereignisse beim Zurücksetzen erneut an den älteren Webhook-Endpoint gesendet werden. - Wenn der Abfrageparameter für die neue Version gilt, verarbeiten Sie ihn. ![Zwei Endpoints, die Ereignisse senden, aber nur den neuen verarbeiten](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png) #### Überwachen Sie Ihre Webhook-Endpoints Überwachen Sie den Datenverkehr zu den neuen Webhook-Endpoints, um zu bestätigen, dass sie Ereignisse korrekt verarbeiten. Wenn Ereignisse von Ihrem neuen Code nicht korrekt gehandhabt werden, versuchen Sie Folgendes: 1. Kehren Sie zur früheren Version Ihres Codes zurück. 2. Den neuen Webhook-Endpoint vorübergehend deaktivieren. 3. Wickeln Sie die fehlgeschlagenen Ereignisse ab (wenn Sie wie im vorherigen Schritt beschrieben einen 400-Status zurückgegeben haben, sendet Stripe alle Ereignisse automatisch erneut). 4. Suchen Sie nach dem Fehler und beheben Sie das Problem. 5. Aktivieren Sie den neuen Webhook-Endpoint und setzen Sie die Überwachung fort. #### Den alten Webhook-Endpoint deaktivieren Deaktivieren Sie nach einem erfolgreichen Upgrade den alten Webhook-Endpoint, um zu verhindern, dass Ihr Server einen `400`-Status zurückgibt. Wenn Sie ihn nicht deaktivieren, kann dies zu Problemen mit Integrationen führen, die auf eine `200`-Antwort angewiesen sind. Nachdem Sie den alten Webhook-Endpoint deaktiviert haben, wird Stripe keine Ereignisse erneut zustellen, die einen `400`-Status zurückgegeben haben. ![Zwei Endpoints, aber nur der neue sendet Ereignisse](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png) ## Integration testen und überwachen [Testen Sie Ihre Integration](https://docs.stripe.com/testing.md) in einer [Sandbox](https://docs.stripe.com/sandboxes.md), um zu bestätigen, dass sie die neue Version wie erwartet verarbeitet. Befolgen Sie zusätzlich zu den allgemeinen Testrichtlinien die Richtlinien für die Produkte und Ressourcen, die Ihre Integration verwendet: - [Billing](https://docs.stripe.com/billing/testing.md): Verwenden Sie [Test-Uhren](https://docs.stripe.com/billing/testing/test-clocks.md), um [Abonnements zu simulieren](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md). - [Invoicing](https://docs.stripe.com/invoicing/integration/testing.md): Testen Sie Webhook-Benachrichtigungen, fehlgeschlagene Zahlungen und andere Szenarien. - [Connect](https://docs.stripe.com/connect/testing.md): Erstellen Sie [Testkonten](https://docs.stripe.com/connect/testing.md?accounts-namespace=v2#creating-accounts) und verwenden Sie diese für [Verifizierungstests](https://docs.stripe.com/connect/testing-verification.md). - [Terminal](https://docs.stripe.com/terminal/references/testing.md): Testen Sie [simulierte Lesegerät-Updates](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): Erstellen Sie PaymentIntents und verwenden Sie Testkartennummern, um Zahlungen zu simulieren.