Stripe の API バージョンを安全に運用する方法 - Stripe Sessions で学んだベストプラクティス

Stripe は高い稼働率と開発しやすい API を提供する決済サービスとして世界的に知られています。しかし一方で、機能リリースのスピードも世界トップクラスで、 Stripe Sessions 2025では、「毎日1,000 件の Pull Request を社内でマージしている」と紹介されるほどです。そしてその膨大な API アップデートの中には、 Charges API から Payment Intents API への移行のように実装の変更が必要になるものも少なからず存在しています。

Stripe は、Stripe Sessions 2025 の中で企業がどのように Stripe のメジャー API アップデートに追従し、効率的に対応していくべきかといったベストプラクティスについて紹介するセッションを用意していました。現地でセッションを聴き、内容をまとめましたのでここに紹介します。

Stripe API の新しいバージョニングモデルとは

2024年から、 Stripe の API バージョン名が変わりました。これまでは 2023-09-30 のようにリリース年月日だけが記載されていましたが、現在は年月日に加えて「リリース名」がバージョン名に追加されています。例えば 2024 年 10 月に新しいバージョニングモデルとして初めてリリースされたバージョンは、 2024-09-30.acacia でした。その後 2025 年には次のメジャーバージョンとして basil シリーズがリリースされています。このように現在の Stripe API はメジャーリリースごとに植物の名前が付けられています。これによって、例えば「今は acacia シリーズを使っているから、acacia シリーズの更新情報をチェックしよう」や「使いたい機能が basil のみだ。今 basil シリーズは使っていないので、更新計画が必要だね」のような判断が行いやすくなっています。

また、新しいバージョニングモデルに移行してからは、6ヶ月に１度のペースで、何かしらの破壊的変更を含むメジャーアップデートがリリースされます。製品の種類が非常に多いため、常にメジャーアップデートの影響を受けることは少なそうですが、Stripe 組み込み部分のコードをよりシンプルにしたり、社内ででている課題をスマートに解決できる機能がリリースされていないかなどは、チェックしておくと良いでしょう。

なぜ Stripe の API バージョンを新しくする必要があるのか？

Stripe は原則として古いバージョンの API も使い続けることができるように API が設計されています。とはいえ、2024 年にリリースされた生成 AI ユースケースに最適化された従量課金システムや Event Destination とよばれる新しい Webhook インテグレーションの形、そして Connect の連結アカウントと顧客の識別をより簡単にする Accounts API V2 などの新機能については、当然古いバージョンでは利用することができません。また、パフォーマンスの最適化やバグ修正、セキュリティの強化なども図られていることもあり、Stripe は最新版の API バージョンを利用することを推奨しています。

API バージョンの変化を知る方法

Stripe は API アップグレードに関する情報を Stripe Docs にて公開しています。バージョンごとの変化だけでなく、ロールバックに関する方法なども記載されていますので、まずはこの記事を確認することをお勧めします。

また、変更ログのページでは、メジャーバージョンごとに対応が必要な変更（破壊的変更）を一覧表示しています。このページをチェックすることで、調査や対応が必要な場所を知ることができますので、メジャーアップデートが行われた際は、必ず確認しましょう。

Stripe の API メジャーアップデートに対応する方法

Stripeではどの API バージョンを利用するかを非常に簡単に固定できます。Stripe への API リクエストを送信する際、Stripe-Version ヘッダーをリクエストに含めましょう。これによって送信されたリクエストが、どの API バージョンに基づいて処理されるかを指定できます。

curl https://api.stripe.com/v1/charges \
  -H "Authorization: Bearer sk_test_..." \
  -H "Stripe-Version: 2025-03-31.basil"

SDK を利用する場合も、クラスを初期化する際にバージョン名を指定することができます。例えば PHP では stripe_version を指定します。

$stripe = new \Stripe\StripeClient([
  "api_key" => "sk_test_xxxx",
  "stripe_version" => "2025-04-30.basil"
]);

Node.js の場合は、 apiVersion で固定することができます。パラメータ名や設定場所は SDK によって変わりますので、お使いの SDK のドキュメントをご確認ください。

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2025-04-30.basil',
});

この機能を利用し、API バージョンを変更するとどのような影響が発生するかをローカルなどのテスト環境で調査することができます。もし特定の API のみ使用するバージョンを変更したい場合は、 SDK を利用せずに Stripe API を直接呼び出すか、SDK が持つカスタムのリクエストを送信する仕組みを利用しましょう。

const response = await stripe.rawRequest(
  'POST',
  '/v1/beta_endpoint',
  {param: 123},
  {apiVersion: '2022-11-15; feature_beta=v3'}
);

ダッシュボードでバージョンを指定することもできますが、コードレベルで指定する仕組みにすることで、別のバージョンでのテストなどがやりやすくなります。省略可能な値ではありますが、できるだけバージョンを指定して SDK クライアントを作成するようにしましょう。

どの API バージョンが使われているかを調査する

そもそも現在稼働しているシステムがどの Stripe API バージョンを利用しているかを把握できていないケースも存在します。その時に利用できるのが、 Stripe ダッシュボードにあるワークベンチ機能です。ワークベンチには開発者が調査やデバッグに利用するための機能が多数用意されています。このうち、「概要」タブの下部にある「API バージョン」セクションを見ると、今実際に利用されている API バージョンを調査できます。

「ログ」タブを使うと、さらに詳細な分析が可能です。日付や期間を指定したり、API のパスなどを指定することで、調査したいリクエストやユースケースだけのリクエストログを取得できます。

「More filters」をクリックすると、「API バージョン」のフィールドが表示されます。ここに調査したいバージョン名を指定することで、該当の API バージョンがどれくらい使われているかなどを絞り込むことも可能です。

この機能を利用して、API バージョンの切り替え漏れがないかやアップデートが必要なリソースがどれくらいあるのかを調べることができます。

ログの詳細を確認すると、どの SDK / API キーから送信されたリクエストかも明らかになります。例えば下の例では、 API バージョン 2023-10-16 で PHP の SDK から Setup Intents API を利用していることがわかります。この情報から、マイクロサービスにおけるどのサービスが送信したリクエストなのかを調査することができます。リソースやサービスごとに制限つき API キーを設定している場合は、 API からも呼び出し元を特定することが可能となります。

Sandbox を利用した効率的なテスト環境構築

新しい API バージョンへの検証を行う際、開発チームが心配するケースの1つが他の機能開発や運用保守への影響です。開発環境とはいえ、テスト的に Stripe 上で行った変更により不整合や意図しない動作が発生してしまうと、他のチームやメンバーが取り組む開発タスクに支障をきたす恐れがあります。このようなリスクを最小化するために使えるのが Stripe Sandbox です。

Stripe Sandbox は Stripe が用意する新しいテスト環境です。これまでのテスト環境とは異なり、作成と破棄が簡単に行える文字通りのサンドボックス環境を１アカウントにつき最大5つまで用意することができます。

新しい API バージョンをテストする場合や、古い API バージョンでの挙動をチェックしたい場合には、このサンドボックス環境を新しく用意しましょう。

ここでサンドボックスの名前に、「API バージョン Basil 調査」などを設定することで、チームメンバーもなんのために作成されたテスト環境なのかを簡単に把握できます。

サンドボックス環境を作成した後は、テスト用の商品や料金・顧客データなどを作成しましょう。ここで terraform の Stripe Provider や Stripe MCP などを利用すると、より簡単にテストデータを生成できます。その後、サンドボックス用のシークレット API キーを発行しましょう。この API キーを利用して、テストしたいバージョンを設定した API リクエストを送信します。これによってバージョンを変えた時に発生するデータ構造や Webhook イベントの違いの調査を、チームメンバーや既存機能への影響を心配することなく行うことができます。

まとめ

Stripe は機能追加や改善を非常に高い頻度で行うサービスとしても有名です。そのアップデート速度に追従しつつ、既存の挙動に悪影響を及ぼさない運用を目指すためには、Stripe の API バージョンを上手に固定・変更する戦略が必要となります。

今回のリリースサイクル変更によって、6ヶ月周期というメジャーアップデートのサイクルがアナウンスされました。これによってどれくらいのペースで Stripe API の組み込みを調査すべきかのスケジュールを組みやすくなったといえます。また、 Stripe ワークベンチが持つ機能を活用することで、現在のシステムに対して変更が必要な範囲などを調査しやすくなっています。サンドボックスを利用することで、既存のシステムや他の開発チームへの影響を心配することなくテストできるようになったことも、とても大きな変化です。

API アップデートは破壊的変更による影響を考えるととても腰をあげにくいタスクの1つです。しかしより良い価格モデルやプランのオファー、請求回収ワークフローの効率化などを実現する上で、リリースされた新しい機能を無視することも次第に難しくなります。この記事で紹介した機能を活用し、システムの API バージョンを新しく保つ方法について、是非ご検討ください。

Stripe を活用したオンライン決済システム導入をサポートします

株式会社デジタルキューブは Stripe 公式パートナーとして、自社サービス開発で培った経験を活かし、Stripe を用いた決済システムの導入を支援します。多言語対応の決済フォーム実装、モバイル支払い対応、柔軟な従量課金システム構築など、ユースケースに合わせた活用方法の提案から、専用ダッシュボードの開発まで幅広くサポートします。

SaaS ダッシュボード開発や EC サイトへの Stripe 決済導入など、様々な導入実績があります。 API の呼び出しだけで決済機能を実装できる Stripe の利点を最大限に活かしたシステム構築をお手伝いします。

Stripe 導入支援サービスの詳細はこちら

著者プロフィール

岡本秀高

DigitalCube の BizDev。EC ASP の開発や Stripe の Developer Advocate としての経験を元に、SaaS や EC サイトの収益を増やすための方法・生成 AI を使った効率化や新しい事業モデルの模索などに挑戦しています。 AWS Samurai 2017 / Alexa Champions / AWS Community Builders