# 実装をアップグレードする

実装を最新の API バージョンにアップグレードします。

Stripe の API への変更の完全な記録については、[開発者向け変更履歴](https://docs.stripe.com/changelog.md)をご確認ください。

実装をアップグレードするには、次の手順を実行します。[変更ログ](https://docs.stripe.com/changelog.md?api_usage=true)で、実装に関連する情報を検索します。

## アップグレード対象バージョンの決定

アカウントのデフォルトの API バージョンに依存するのではなく、必ず実装対象の API バージョンをコードで指定してください。API コールで新しいバージョンをテストするには、本番環境またはテスト環境で `Stripe-Version` ヘッダーを設定します。[サーバー側 SDK で API バージョンを設定する方法](https://docs.stripe.com/upgrades.md#specify-sdk-api-version)をご確認ください。

[ワークベンチ](https://docs.stripe.com/workbench/overview.md)の[「概要」タブ](https://dashboard.stripe.com/workbench/overview)で、実装で使用されている API バージョンを確認します。

[変更ログ](https://docs.stripe.com/changelog.md)を確認して、アップグレードの対象バージョンを見つけます。

## SDK での API バージョンの指定

アカウントには、API の呼び出し方、利用できる機能、API レスポンスの構造を定義する*デフォルト API バージョン* (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)が設定されています。[サーバーサイド SDK](https://docs.stripe.com/sdks.md#server-side-libraries) を使用する場合、Stripe への API 呼び出しでは、その SDK のリリース時に最新だった API バージョンが使用されます。Java、Go、.NET などの強い型付けを採用する言語では、別の API バージョンを指定できません。

#### Ruby

[stripe-ruby](https://github.com/stripe/stripe-ruby) ライブラリにより、API バージョンをグローバルに、またはリクエストごとに設定できます。

API バージョンを設定しない場合、最近のバージョンの stripe-ruby では、該当するバージョンの stripe-ruby がリリースされた時点で最新だった API バージョンが使用されます。[v9](https://github.com/stripe/stripe-ruby/blob/master/CHANGELOG.md#900---2023-08-16) より前のバージョンの stripe-ruby では、アカウントのデフォルトの API バージョンが使用されます。

SDK で API バージョンを**グローバル**に設定するには、`Stripe.api_version` プロパティにバージョンを割り当てます。

```ruby
require 'stripe'
# Don't put any keys in code. See /keys-best-practices.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>', stripe_version: '2026-08-26.dahlia')
```

またはリクエストごとにバージョンを設定します。

```ruby
require 'stripe'
# Don't put any keys in code. See /keys-best-practices.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')
intent = client.v1.payment_intents.retrieve(
  'pi_1DlIVK2eZvKYlo2CW4yj5l2C',
  {
    stripe_version: '2026-08-26.dahlia',
  },
)
intent.capture
```

> グローバルまたはリクエストごとにバージョンをオーバーライドすると、API レスポンスオブジェクトもそのバージョンで返されます。

#### Python

[stripe-python](https://github.com/stripe/stripe-python) ライブラリにより、API バージョンをグローバルに、またはリクエストごとに設定できます。

API バージョンを設定しない場合、最近のバージョンの stripe-python では、利用中のバージョンの stripe-python がリリースされた時点で最新だった API バージョンが使用されます。[v6](https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md#600---2023-08-16) より前のバージョンの stripe-python では、アカウントのデフォルトの API バージョンが使用されます。

SDK で API バージョンを**グローバル**に設定するには、`stripe.api_version` プロパティにバージョンを割り当てます。

```python
import stripe
# Don't put any keys in code. See /keys-best-practices.
stripe.api_key = <<YOUR_SECRET_KEY>>
stripe.api_version = '2026-08-26.dahlia'
```

またはリクエストごとにバージョンを設定します。

```python
import stripe
intent = stripe.PaymentIntent.retrieve(
  "pi_1DlIVK2eZvKYlo2CW4yj5l2C",
  stripe_version="2026-08-26.dahlia",
)
intent.capture()
```

> グローバルまたはリクエストごとにバージョンをオーバーライドすると、API レスポンスオブジェクトもそのバージョンで返されます。

#### PHP

[stripe-php](https://github.com/stripe/stripe-php) ライブラリにより、API バージョンをグローバルに、またはリクエストごとに設定できます。

API バージョンを設定しない場合、最近のバージョンの stripe-php では、そのバージョンの stripe-php がリリースされた時点で最新だった API バージョンが使用されます。[v11](https://github.com/stripe/stripe-php/blob/master/CHANGELOG.md#1100---2023-08-16) より前のバージョンの stripe-php では、アカウントのデフォルトの API バージョンが使用されます。

SDK で API バージョンを**グローバル**に設定するには、`\Stripe\Stripe::setApiVersion()` メソッドにバージョンを渡します。

```php
$stripe = new \Stripe\StripeClient([
  // Don't put any keys in code. See /keys-best-practices.
  "api_key" => "<<YOUR_SECRET_KEY>>",
  "stripe_version" => "2026-08-26.dahlia"
]);
```

またはリクエストごとにバージョンを設定します。

```php
$intent = $stripe->paymentIntents->capture(
  'pi_1DlIVK2eZvKYlo2CW4yj5l2C',
  [],
  ['stripe_version' => '2026-08-26.dahlia']
);
```

> グローバルまたはリクエストごとにバージョンをオーバーライドすると、API レスポンスオブジェクトもそのバージョンで返されます。

#### Java

Java は強い型付けのプログラミング言語であるため、SDK で使用される API バージョンは固定されており、SDK リリース時点の最新の API バージョンになります。

強い型付けのプログラミング言語で異なる API バージョンを設定することは、レスポンスオブジェクトが SDK の型定義と一致せずリクエストが失敗する原因となるため、推奨されません。たとえば、対象の API バージョンが SDK タイプに存在しないパラメーターを必要とする場合、リクエストは失敗します。

#### Node

[stripe-node](https://github.com/stripe/stripe-node) ライブラリにより、API バージョンをグローバルに、またはリクエストごとに設定できます。

API バージョンを設定しない場合、最近のバージョンの stripe-node では、そのバージョンの stripe-node がリリースされた時点で最新だった API バージョンが使用されます。[v12](https://github.com/stripe/stripe-node/blob/master/CHANGELOG.md#1200---2023-04-06) より前のバージョンの stripe-node では、アカウントのデフォルトの API バージョンが使用されます。

SDK で API バージョンを**グローバル**に設定するには、`apiVersion` オプションを指定します。

```javascript
// Don't put any keys in code. See /keys-best-practices.
const stripe = require('stripe')('<<YOUR_SECRET_KEY>>', {
  apiVersion: '2026-08-26.dahlia',
});
```

またはリクエストごとにバージョンを設定します。

```javascript
const intent = await stripe.paymentIntents.retrieve('pi_1DlIVK2eZvKYlo2CW4yj5l2C', {
  apiVersion: '2026-08-26.dahlia',
});
```

#### TypeScript の利用

TypeScript の型には、リリース時点で最新の API バージョンが反映されます。このバージョンは [API_VERSION ファイル](https://github.com/stripe/stripe-node/blob/master/API_VERSION)にエンコードされています。

Stripe をデフォルトのインポートとしてインポートし、最新の API バージョンで `new Stripe()` としてインスタンス化します。

```javascript
import Stripe from 'stripe';
const stripe = new Stripe('<<YOUR_PUBLISHABLE_KEY>>', {
  apiVersion: '2026-08-26.dahlia'
});
```

#### Go

Go は強い型付けのプログラミング言語であるため、SDK で使用される API バージョンは固定されており、SDK リリース時点の最新の API バージョンになります。

強い型付けのプログラミング言語で異なる API バージョンを設定することは、レスポンスオブジェクトが SDK の型定義と一致せずリクエストが失敗する原因となるため、推奨されません。たとえば、対象の API バージョンが SDK タイプに存在しないパラメーターを必要とする場合、リクエストは失敗します。

#### .NET

C# は強い型付けのプログラミング言語であるため、.NET SDK で使用される API バージョンは固定されており、SDK リリース時点の最新の API バージョンになります。

強い型付けのプログラミング言語で異なる API バージョンを設定することは、レスポンスオブジェクトが SDK の型定義と一致せずリクエストが失敗する原因となるため、推奨されません。たとえば、対象の API バージョンが SDK タイプに存在しないパラメーターを必要とする場合、リクエストは失敗します。

#### cURL

```sh
curl https://api.stripe.com/v1/charges \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2026-08-26.dahlia"
```

#### Stripe CLI

```sh
stripe charges create --stripe-version 2026-08-26.dahlia
```

## コード更新による API 変更への対応

重要なリクエストを確認し、レスポンスの変更に対応できるようコードを更新します。リクエストごとに[変更ログで関連する互換性に関わる変更を確認](https://docs.stripe.com/changelog.md?api_usage=true)し、移行先のバージョンを導入するために必要な変更を把握します。

[ワークベンチ](https://docs.stripe.com/workbench/overview.md)の[「概要」タブ](https://dashboard.stripe.com/workbench/overview)で API リクエストを確認します。

## イベント送信先を更新する

> API v1 リソースの [シンイベント](https://docs.stripe.com/event-destinations.md#thin-events)は、プライベートプレビューで利用できます。これを使用すると、Webhook の設定を変更せずに実装のアップグレードを効率化できます。これまでシンイベントは API v2 リソースのみをサポートしていました。[詳細を確認し、利用を申請](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog)します。

Webhook エンドポイントや Amazon EventBridge、Azure Event Grid のクラウド送信先など、スナップショットイベントを受信する各イベント送信先を確認します。スナップショットイベントでは、送信先の [snapshot_api_version](https://docs.stripe.com/api/v2/core/event-destinations/object.md#v2_event_destination_object-snapshot_api_version) プロパティによって、イベントペイロードの生成に使用する API バージョンが決まります。この設定は、サーバーサイド SDK で使用する API バージョンとは独立しています。シンイベントのペイロードには API バージョンが適用されません。

`snapshot_api_version` は、イベント送信先の作成時にのみ設定できます。別の API バージョンを使用するには、既存の送信先を削除する前に、そのバージョンで設定した送信先を作成してテストします。移行中に両方の送信先が有効な場合、Stripe ではサブスクライブしているイベントを両方の送信先に配信するため、イベントハンドラーはべき等である必要があります。

## Webhook エンドポイントの更新

Webhook エンドポイントをアップグレードするには、[受信 Webhook の署名を検証し](https://docs.stripe.com/webhooks.md#verify-events)、Stripe の [パブリック IP アドレス](https://docs.stripe.com/ips.md)からのトラフィックを許可する必要があります。また、新しいエンドポイントを作成し、トラフィックを新しいエンドポイントにリダイレクトしたうえで、古いエンドポイントを無効にする必要があります。

#### 新しい無効な Webhook エンドポイントの作成

以下のパラメーターを使用して、新しい Webhook エンドポイントを作成します。

- `url`: 元の Webhook エンドポイントと同じ URL を使用しますが、2 つの異なるエンドポイントに送信されるイベントを区別するためにクエリパラメーターを追加します。例: `https://example.com/webhooks?version=2024-04-10`.
- `enabled_events`: 元の Webhook エンドポイントと同じイベント。
- `api_version`: アップグレード後の API バージョン。最新の API バージョンにアップグレードする場合は、ダッシュボードまたは API を使用してエンドポイントを作成できます。他のバージョンの場合は、 API を使用して特定のバージョンを設定します。

新しい Webhook エンドポイントを作成したら、これを無効にします。これは次のステップで再度有効にできます。
![2 つのエンドポイントのうち、旧バージョンのみでイベントを送信](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png)

#### 新しいエンドポイントに送信されたイベントを無視するための Webhook コードの更新

イベント処理コードを更新します。

- クエリパラメーターが以前の API バージョンのものである場合は、通常どおりに処理します。
- クエリパラメーターが新しい API バージョンのものである場合、イベントを無視して 200 のレスポンスを返し、配信の再試行を防ぎます。

次に、前のステップで作成した新しい Webhook エンドポイントを有効にします。この時点で、すべてのイベントが 2 回送信されます (古い API バージョンで 1 回、新しいバージョンで 1 回)。
![2 つのエンドポイントからのイベント送信と、旧バージョンのみの処理](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png)

#### 新しいエンドポイントのイベントを処理するための Webhook コードの更新

イベント処理コードを更新します。

- クエリパラメーターが以前のバージョンのものである場合は、イベントを無視します。Stripe がイベントを自動的に再試行できるように、400 ステータスを返すことを推奨します。これにより、元に戻す必要がある場合に、イベントが古い Webhook エンドポイントに再送信されます。
- クエリパラメーターが新しいバージョンのものである場合は、それを処理します。
![2 つのエンドポイントからイベントを送信 (新バージョンのみ処理)](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png)

#### Webhook エンドポイントの監視

新しい Webhook エンドポイントへのトラフィックを監視して、イベントが正常に処理されることを確認します。

新しいコードでイベントが正しく処理されない場合には、以下を試してください。

1. コードを以前のバージョンに戻します。
2. 新しい Webhook エンドポイントを一時的に無効にします。
3. 失敗したイベントを処理します (前のステップで説明したように 400 ステータスを返した場合、すべてのイベントは自動的に再送信されます)。
4. 問題を調査して修正します。
5. 新しい Webhook エンドポイントを有効にして、モニタリングを再開します。

#### 古い Webhook エンドポイントの無効化

アップグレードが完了したら、サーバーが `400` ステータスを返さないように、古い Webhook エンドポイントを無効にします。無効にしない場合、`200` レスポンスに依存する連携で問題が発生する可能性があります。

古い Webhook エンドポイントを無効にした後、`400` を返したイベントは再配信されません。
![2 つのエンドポイントのうち、新バージョンのみでイベントを送信](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png)

## 実装のテストと監視

[サンドボックス](https://docs.stripe.com/sandboxes.md)で[実装をテスト](https://docs.stripe.com/testing.md)し、新しいバージョンで想定どおりに動作することを確認します。

一般的なテストガイダンスに加えて、実装で使用されているプロダクトとリソースについて、次のガイドラインに従います。

- [Billing](https://docs.stripe.com/billing/testing.md): [テストクロック](https://docs.stripe.com/billing/testing/test-clocks.md)を使用して[サブスクをシミュレーション](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md)します。
- [Invoicing](https://docs.stripe.com/invoicing/integration/testing.md): Webhook 通知、決済の失敗、その他のシナリオをテストします。
- [Connect](https://docs.stripe.com/connect/testing.md): [テストアカウント](https://docs.stripe.com/connect/testing.md?accounts-namespace=v2#creating-accounts)を作成し、それを使用して[本人確認のテスト](https://docs.stripe.com/connect/testing-verification.md)を行います。
- [Terminal](https://docs.stripe.com/terminal/references/testing.md): [シミュレーションされたリーダーの更新](https://docs.stripe.com/terminal/references/testing.md?terminal-card-present-integration=terminal#simulated-reader-updates)をテストします。
- [PaymentIntent](https://docs.stripe.com/payments/quickstart-payment-intents.md#test-payment): PaymentIntent を作成し、テスト用のカード番号を使用して決済をシミュレーションします。