Stripe-Versionsverwaltung und Support-Richtlinie

Erfahren Sie mehr über die Versionsverwaltung für Stripe.js und die Support-Richtlinie.

Stripe.js verwendet ein Evergreen-Modell, was bedeutet, dass es im Laufe der Zeit fortlaufend aktualisiert wird. Stripe.js v3, die js.stripe.com/v3 zugrundeliegenden Skripts, war viele Jahre lang die neueste Version von Stripe.js. Wir veröffentlichen halbjährlich neue Hauptversionen wie Acacia. Diese Versionen ermöglichen es uns, wichtige Funktionen und wichtige Änderungen nach einem vorhersehbaren Zeitplan einzuführen, damit Sie Ihre Upgrades planen können. on a biannual basis. These versions allow us to introduce major features and breaking changes on a predictable schedule, so you can plan your upgrades.

Änderungstypen

Änderungen an Stripe.js lassen sich in zwei Hauptkategorien unterteilen:

Optimierungen und neue Funktionen

Die häufigsten Änderungen, die wir an Stripe.js vornehmen, sind Optimierungen und neue Funktionen.

Wir fügen neue Funktionen hinzu, nehmen Optimierungen vor und beheben Fehler, wie z. B. kritische Sicherheitsprobleme, ohne dass Änderungen an der Integration erforderlich sind. Dies geschieht automatisch für alle Stripe.js-Integrationen und wird für alle Versionen von Stripe.js fortgesetzt. Alle Versionen erhalten weiterhin diese unterbrechungsfreien Updates und werden regelmäßig gemeinsam in unserem internen Release-Prozess aktualisiert.

Einige Beispiele für Optimierungen, die wir als fehlerfrei betrachten:

Änderung der Eingabelabels im Payment Element, um sie leichter zugänglich zu machen.
Aktualisierung der Nutzeroberfläche in Payment Element für BNPL-Weiterleitungen, um die Konversion zu steigern.
Hinzufügen eines neuen Parameters, mit dem Sie angeben können, wann Sie keine Postleitzahl für eine Kartenzahlung angeben möchten.

Einige Änderungen erfordern Integrationsänderungen, um Zugriff darauf zu erhalten. Dies sind jedoch keine wichtigen Änderungen. Ein Beispiel könnte das Hinzufügen einer neuen Funktion zum Stripe-Objekt sein. Wir veröffentlichen diese Funktionen sicher für einige bestehende Stripe.js-Versionen im Rahmen unseres regulären Release-Prozesses. Dieser Vorgang wird als Rückportierung bezeichnet.

Wichtige Änderungen

Das Versionierungssystem von Stripe.js ist ein Tool, mit dem wir neue Funktionen veröffentlichen können, die andernfalls durch die Abwärtskompatibilität eingeschränkt wären. Wir veröffentlichen diese wichtigen Änderungen zweimal jährlich in den Veröffentlichungen von Stripe.

Eine wesentliche Änderung kann dazu führen, dass Ihre Integration fehlschlägt oder als fehlerhaft erscheint. Zum Beispiel:

Entfernen eines Parameters oder der Unterstützung für eine bestimmte Option. Beispielsweise wird captureMethod: manual nicht länger für stripe.elements() zugelassen.
Entfernen eines Eingabefelds, auf das Sie sich bei einer Zahlungsmethode verlassen könnten. Zum Beispiel, keine countrymehr für Klarna-Zahlungen einzuziehen.
Änderungen, die dazu führen könnten, dass Ihre Bezahlseite visuell fehlerhaft oder unübersichtlich erscheint. Wenn Sie beispielsweise das Standardverhalten für das Layout des Zahlungselements von Registerkarten zu Akkordeon ändern, kann dies zu Anzeigeproblemen führen, wenn Ihre Seite bestimmte Annahmen über das Element im Ablauf der Seite trifft.

Nutzung

Es gibt drei Möglichkeiten, versioniertes Stripe.js zu verwenden: mit einem Skript-Tag, mit dem @stripe/stripe-js-Paket auf npm oder mit dem @stripe/react-stripe-js-Paket auf npm.

Mit einem Skript-Tag

Um das versionierte Stripe.js zu verwenden, fügen Sie den Versionsnamen in die URL des Skript-Tags ein.

<script src="https://js.stripe.com/acacia/stripe.js"></script>

Wir empfehlen Ihnen, mit der neuesten Version von Stripe.js auf dem Laufenden zu bleiben. Stripe.js v3 wird nicht mehr für Integrationen empfohlen, wird aber weiterhin unterstützt.

Mit stripe-js auf npm

Wenn Sie Stripe.js mit dem @stripe/stripe-js-Paket auf npm verwenden, können Sie Stripe.js weiterhin auf diese Weise nutzen. Beginnend mit @stripe/stripe-js@6.0.0 verwendet jede Hauptversion von Stripe.js eine bestimmte feste Version von Stripe.js. @stripe/stripe-js@6.0.0 nutzt beispielsweise Stripe.js acacia. Informationen zu den Beziehungen zwischen bestimmten @stripe/stripe-js-Versionen und ihren entsprechenden Stripe.js-Versionen finden Sie auf der Seite „Versionen“…

Obwohl die unterbrechungsfreie Laufzeitfunktionalität von Stripe.js auf alte Versionen von Stripe.js rückportiert wird, werden die TypeScript-Typen auf npm nicht auf alte Hauptversionen in @stripe/stripe-js rückportiert. Um über die neuesten TypeScript-Typen auf dem Laufenden zu bleiben, aktualisieren Sie auf die neueste Version von Stripe.js und @stripe/stripe-js.

Mit react-stripe-js auf npm

Das @stripe/react-stripe-js-Paket funktioniert weiterhin mit dem @stripe/stripe-js-Paket, indem es seine peerDependencies verwendet.

Lebenszyklus einer Version

Wir veröffentlichen zweimal jährlich Hauptversionen von Stripe.js zusammen mit den API Release Trains. Wir veröffentlichen weniger wichtige Änderungen, einschließlich Optimierungen und rückportierter Funktionen, in unserem fortlaufenden Zeitplan für regelmäßige Veröffentlichungen. Wir unterstützen und aktualisieren weiterhin ältere Versionen. twice per year. We release non-breaking changes, including both optimizations and backported features, on our ongoing frequent release schedule. We continue to support and update older versions.

Kompatibilität mit API-Versionen

Bei der Durchführung von API-Anfragen verwendet jede versionierte Datei von Stripe.js automatisch die mit der Stripe.js-Version verknüpfte API-Version. Das heißt, die Stripe.js-Version acacia verwendet eine kompatible API-Version wie 2024-12-18.acacia (die das Datum enthält), um das Veröffentlichungsdatum der API-Version darzustellen. Sie können die API-Version nicht überschreiben.

Änderungsprotokoll

Das Änderungsprotokoll zeigt den Verlauf versionierter Änderungen in Stripe.js im Zeitverlauf. Es enthält alle wesentlichen Änderungen und andere wichtige Änderungen und ist der beste Ort, um zu verstehen, welche Integrationsänderungen Sie vornehmen müssen, um Stripe.js-Versionen zu aktualisieren. shows the history of versioned changes in Stripe.js over time. It includes all breaking changes and other important changes and is the best place to understand what integration changes you need to make to upgrade Stripe.js versions.

Von Stripe.js v3 migrieren

Lesen Sie Folgendes, bevor Sie ein Upgrade von Stripe.js v3 auf eine neuere Version durchführen.

API-Änderungen

Wenn Sie Stripe.js von v3 auf acacia aktualisieren, kann dies je nach zuvor für die Anfragen verwendeter API-Version zu wesentlichen Änderungen für API-Anfragen führen. Um ältere Konten zu aktualisieren, empfehlen wir Folgendes:

Identify the current API version used in your account.
Identify the changes that affect your Stripe.js integration.
Upgrade the API version your Stripe.js integration uses to 2024-12-18.acacia gradually (if it makes sense for your needs) before upgrading Stripe.js to acacia.

API-Betaversionen

API-Versionen können wichtige Änderungen für Vorschauen enthalten, die nicht im Änderungsprotokoll aufgeführt sind. Daher müssen Sie Ihre Stripe.js-Version sorgfältig aktualisieren, wenn Sie eine Vorschau wie die Beta für Elements mit Checkout-Sitzungen verwenden.

In der Vergangenheit beinhalteten einige Vorschaufunktionen das Hinzufügen von Beta-Headern zu Ihren apiVersion von Stripe.js verwendeten Anfragen (z. B. '2025-02-24.acacia; custom_checkout_beta=v1'). Da diese Überschreibung der API-Version nicht mehr unterstützt wird, können Sie Beta-Header nicht explizit direkt zu API-Anfragen hinzufügen. Stattdessen fügen alle unterstützten Vorschauen von Stripe.js die erforderlichen Header automatisch hinzu, wenn das entsprechende Beta-Flag (zum Beispiel custom_checkout_beta_5) beim Initialisieren von Stripe.js festgelegt wird.

Für acacia wird dies ausdrücklich für custom_checkout_beta und nz_bank_account_beta unterstützt. Wenn Sie API-Header für andere Vorschauen bereitstellen, wenden Sie sich an die Ihnen für Vorschauunterstützung bereitgestellte E-Mail, um Ihre Optionen für ein Upgrade von Stripe.js oder die Migration zu einem GA-Verhalten zu ermitteln.

Unterstützung für Stripe.js v3

Wir werden den Support von js.stripe.com/v3 auf absehbare Zeit fortsetzen. Wir werden Funktionen auf diese Version zurückportieren und Stripe.js v3 weiterhin als Evergreen-Version beibehalten. Stripe.js v3 wird nicht abgeschafft, aber wir empfehlen Ihnen, Ihre Anwendungen regelmäßig auf die neueste Version von Stripe.js zu aktualisieren, um auf aktuelle Funktionen zuzugreifen, die aufgrund ihrer grundlegenden Änderungen nicht rückportiert werden können.