Stripe.js のバージョン管理とサポートのポリシー

Stripe.js のバージョン管理とサポートのポリシーについてご確認ください。

Stripe.js はエバーグリーンモデルを使用しているため、時間の経過とともに継続的に更新を受信します。Stripe.js v3 は、js.stripe.com/v3 をサポートするスクリプトであり、長年にわたって Stripe.js の最新バージョンでした。Acacia などの新しいメジャーバージョンを半年ごとにリリースしています。これらのバージョンでは、主要な機能や対応が必要な変更を予測可能なスケジュールで導入できるため、アップグレードを計画できます。

変更の種類

Stripe.js の変更は、主に次の 2 つのカテゴリに分類されます。

最適化と新機能

Stripe.js に加える最も一般的な変更の種類は、最適化と新機能です。

新機能の追加、最適化、重大なセキュリティ問題などのバグの修正を、必要な実装の変更なしで行います。これはすべての Stripe.js の実装で自動的に行われ、Stripe.js のすべてのバージョンでも継続されます。すべてのバージョンは、これらの対応不要な更新を引き続き取得し、内部リリースプロセスで定期的に一緒に更新されます。

対応不要と見なされる最適化の例を、いくつか示します。

Payment Element の入力ラベルを、よりアクセスしやすいものに変更します。
BNPL リダイレクト用に Payment Element 内の UI を更新し、コンバージョン率を高めます。
カード支払いの郵便番号を送信しないタイミングを指定できる新しいパラメーターを追加します。

一部の変更では、アクセスするために実装の変更が必要ですが、対応が必要な変更ではありません。1 つの例は、Stripe オブジェクトに新しい関数を追加することです。これらの機能は、通常のリリースプロセスで既存の Stripe.js バージョンの一部で安全にリリースされています。このプロセスは、「バックポートと呼ばれます」。

対応が必要な変更点

Stripe.js のバージョン管理システムは、下位互換性のサポートの必要性により制約を受ける可能性のある新機能を、リリースできるようにするツールです。これらの対応が必要な変更は、年に 2 回行われる Stripe リリースでリリースされます。

対応が必要な変更とは、実装が失敗したり、壊れているように見えたりする原因となり得る変更です。以下に例を挙げます。

特定のオプションに対するパラメーターまたはサポートの削除。たとえば、stripe.elements()``captureMethod: manual を許可しなくなりました。
依存する可能性のある入力フィールドを決済手段から削除する。たとえば、Klarna 決済の country を回収しなくなります。
決済ページが視覚的に壊れたり、わかりにくかったりする可能性がある変更。たとえば、Payment Element レイアウトのデフォルト動作をタブからアコーディオンに変更すると、ページがフロー内の要素について特定の仮定をしている場合に、表示上の問題が発生する可能性があります。

使用状況

バージョン管理された Stripe.js を使用するには、script タグを使用する方法、npm の @stripe/stripe-js パッケージを使用する方法、npm の @stripe/react-stripe-js パッケージを使用する方法の 3 つがあります。

script タグを使用

バージョン管理された Stripe.js を使用するには、スクリプトタグの URL にバージョン名を含めます。

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

最新バージョンの Stripe.js を最新の状態に保つことをお勧めします。Stripe.js v3 は実装には推奨されなくなりましたが、引き続きサポートします。

npm で stripe-js を使用

npm の @stripe/stripe-js パッケージで Stripe.js を使用する場合は、この方法で Stripe.js を引き続き使用できます。@stripe/stripe-js@6.0.0 以降、Stripe.js の各メジャーバージョンは、特定の修正バージョンの Stripe.js を使用します。たとえば、@stripe/stripe-js@6.0.0 は Stripe.js acacia を使用します。特定の @stripe/stripe-js バージョンとそれに対応する Stripe.js バージョン間の関係については、リリースページを参照してください。

Stripe.js の対応不要なランタイム機能は古いバージョンの Stripe.js にバックポートされていますが、npm の TypeScript 型は @stripe/stripe-js の古いメジャーバージョンにバックポートされていません。最新の TypeScript タイプを最新の状態に保つには、Stripe.js と @stripe/stripe-js を最新リリースに更新してください。

npm の react-stripe-js を使用

@stripe/react-stripe-js パッケージは、その peerDependencies を使用して、@stripe/stripe-js パッケージと引き続き連携します。

バージョンのライフサイクル

Stripe.js のメジャーバージョンは、API リリーストレインと一緒に年に 2 回リリースされます。最適化とバックポートされた機能の両方を含む、対応不要な変更は、継続的な頻繁なリリーススケジュールでリリースされます。古いバージョンのサポートと更新は継続されます。

API バージョンとの互換性

API リクエストを実行する際、バージョン管理された各 Stripe.js は、Stripe.js バージョンに関連付けられた API バージョンを自動的に使用します。つまり、Stripe.js acacia バージョンは、2024-12-18.acacia (日付を含む) などの互換性のある API バージョンを使用して、API バージョンのリリース日を表します。API バージョンを上書きすることはできません。

変更ログ

changelog には、Stripe.js のバージョン管理された変更の履歴が経時的に表示されます。これには、すべての対応が必要な変更とその他の重要な変更が含まれており、Stripe.js のバージョンをアップグレードするために必要な実装の変更を、理解するのに適した場所です。

Stripe.js v3 からの移行

Stripe.js v3 から新しいバージョンにアップグレードする前に、以下の考慮事項を確認してください。

API の変更点

Stripe.js を v3 から acacia に更新すると、以前に要求に使用した API バージョンによっては、API リクエストに対応が必要な変更が発生する可能性があります。古いアカウントをアップグレードするには、次のことをお勧めします。

アカウントで使用されている現在の API バージョンを特定します。
Stripe.js の実装に影響する変更を特定します。
Stripe.js の実装で使用されている API バージョンを徐々に 2024-12-18.acacia にアップグレードしてから、Stripe.js を acacia にアップグレードします。

API ベータ版

API バージョンには、変更ログに記載されていないプレビューに対応が必要な変更が含まれている可能性があるため、Elements with Checkout Sessions ベータ版などのプレビューを使用している場合は、Stripe.js バージョンを慎重にアップグレードする必要があります。

従来、一部のプレビュー機能では、Stripe.js リクエスト ('2025-02-24.acacia; custom_checkout_beta=v1' など) で使用される apiVersion にベータヘッダーを追加する必要がありました。この API バージョンのオーバーライドはサポートされなくなったため、ベータヘッダーを API リクエストに直接明示的に追加することはできません。一方、サポートされている Stripe.js プレビューでは、Stripe.js の初期化時に対応するベータフラグ (custom_checkout_beta_5 など) が設定されると、必要なヘッダーが自動的に追加されます。

acacia の場合、これは custom_checkout_beta と nz_bank_account_beta で明示的にサポートされています。他のプレビュー用に API ヘッダーを提供する場合は、プレビューサポートのために提供されたメールに連絡して、Stripe.js をアップグレードするか、GA 動作に移行するためのオプションを確認してください。

Stripe.js v3 のサポート

当面の間、js.stripe.com/v3 のサポートを継続します。この機能をこのバージョンにバックポートし、引き続き Stripe.js v3 をエバーグリーンバージョンとして維持します。Stripe.js v3 は非推奨ではありませんが、アプリケーションを定期的に最新バージョンの Stripe.js に更新して、対応が必要な変更が理由でバックポートできない最新の機能にアクセスすることをお勧めします。