公開アプリのサンドボックスサポートを有効にする

公開アプリでサンドボックスのインストールを有効にします。

サンドボックスはデフォルトのテスト環境です。

テスト環境は、デフォルトのテスト手段ではなくなりました。Stripe アカウントには、デフォルトのテスト手段としてサンドボックスが付属しています。サンドボックスには、アカウントピッカーまたはダッシュボードのサンドボックスページからアクセスすることが可能です。

サンドボックスは分離されたテスト環境です。サンドボックスを使用して、アカウントで利用可能な Stripe の機能をテストすることが可能で、テストは本番環境のシステムに影響を与えません。ユーザーはサンドボックスにアプリをインストールして、その機能を評価できます。

テスト環境とサンドボックスのサポート

Stripe は、以下の 3 つの環境をサポートしています。サンドボックス、本番環境、テスト環境。ただし、新規の Stripe ビジネスのデフォルトのテスト方法は、サンドボックスになります。

できるだけ多くの加盟店が本番環境への移行前にアプリを評価できるよう、アプリにサンドボックスのサポートを実装しておくことを強くお勧めします。

アプリのサンドボックスのサポートを有効にする

デフォルトでは、公開アプリをサンドボックスにインストールするにはユーザーによる追加作業が必要です。

テスト環境と同様に、アプリマニフェストを更新することでサンドボックスへのインストールを有効にできます。サンドボックスのサポートを有効にしたら、アプリを審査に提出します。アプリのサンドボックスのサポートは、アプリの審査プロセスの一環として検証されます。

マネージドサンドボックス

_マネージドサンドボックス_は、Stripe がアカウントに自動で作成する独自のサンドボックスで、公開 Stripe アプリをサポートします。

初めて公開アプリをアップロードするときに、Stripe がマネージドサンドボックスを自動で作成します。
ユーザーがアプリをサンドボックスにインストールすると、マネージドサンドボックスへの接続が確立されます。
マネージドサンドボックス内のユーザーのインストール環境のイベントをデバッグおよび監視できます。
マネージドサンドボックスに加えられた変更は、本番環境またはテスト環境でアプリをインストールするユーザーには影響しません。
マネージドサンドボックスは削除できません。

マネージドサンドボックスを作成する

アカウントに初めて公開 Stripe アプリをアップロードするときに、Stripe がマネージドサンドボックスを自動で作成します。

2025 年 2 月 3 日より前にアップロードされた公開アプリの場合、Stripe はアカウントにマネージドサンドボックスを自動で作成します。

公開アプリのサンドボックスへのインストールを有効にする

stripe apps -v を実行して、最新バージョンの Stripe CLI と Stripe Apps プラグインを使用していることを確認します。アプリをアップロードする前に、バージョン 1.5.23 以降を使用する必要があります。
Command Line
```
$ stripe plugin upgrade apps
✔ upgrade to v1.7.0 complete.
$ stripe -v
stripe version 1.25.1
$ stripe apps -v
apps version 1.7.0
```
アプリマニフェストを更新して、サンドボックスへのインストールをサポートできるようにします。
(オプション) マネージドサンドボックス内にサンドボックス固有のイベントフックを作成します。サーバー側のロジックを更新して、これらの新しいエンドポイントをリッスンします。
(オプション) サーバー側のロジックを更新して、サンドボックスへのインストールで Stripe API コールを行うときにマネージドサンドボックス API キーを使用します。
アプリの新しいバージョンをメインアカウント (マネージドサンドボックスではありません) にアップロードします。
メインアカウントで、アップロードしたサンドボックスに対応する外部テストリンクを作成します。 for the sandbox-enabled version you just uploaded.
新しいサンドボックスを作成して開き、更新したアプリをテストします。
ブラウザーウィンドウで、以前作成した外部テストリンクにアクセスし、アプリをインストールします。
サンドボックスにインストールしたアプリが想定どおりに動作するかどうかをテストします。
新しいバージョンを送信してマーケットプレイスの審査を受けます。

アプリマニフェストを更新する

メモ

2025 年 2 月 3 日以降、マーケットプレイスに公開するアプリのアプリマニフェストでサンドボックスのサポートを true または false として宣言する必要があります。

サンドボックスへのアプリインストールをサポートするには、sandbox_install_compatible を使用してアプリマニフェストでサンドボックスのサポートを宣言する必要があります。

次のサンプルコードは、サンドボックスのサポートを宣言しています。

stripe-app.json
{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "distribution_type": "public",
  "sandbox_install_compatible": true
}

サンドボックスへの接続について

ユーザーが公開アプリをサンドボックスにインストールすると、マネージドサンドボックスへの接続が確立されます。これは、本番環境またはテスト環境でインストールされているアプリの動作とは異なります。

ユーザーがサンドボックスにアプリをインストールすると、マネージドサンドボックスへの接続が確立されます。
ユーザーが本番環境でアプリをインストールすると、本番環境とテスト環境への接続が確立されます。
ユーザーがテスト環境でアプリをインストールすると、テスト環境への接続が確立されます。

Webhook イベント

アプリがユーザーのインストールのイベントをリッスンする場合は、サンドボックスにインストールされたアプリを処理するための追加設定が必要です。

マネージドサンドボックス内で、サンドボックスイベント用の新しい Webhook を作成します。
ユーザーがアプリをサンドボックスにインストールした場合、Stripe は該当するイベントをマネージドサンドボックスのエンドポイントにのみ送信します。
サーバー側のロジックを更新して、サンドボックス固有のイベントを処理します。

メモ

インストール環境がイベントの動作に与える影響については、イベントの動作で詳細をご確認ください。

署名シークレット

Webhook の場合、マネージドサンドボックス内から署名シークレットを取得しなければならない場合もあります。

API キー

マネージドサンドボックスには、サンドボックスへのインストールを呼び出すための独自の API キーがあります。サンドボックス固有の Webhook またはイベントに応答する場合は、これらのマネージドサンドボックスキーを使用する必要があります。

マネージドサンドボックス内に、サンドボックスへのインストールに使用する正規の API キーがあります。

OAuth のサンドボックスリンク

本番環境、テスト環境、サンドボックス環境の OAuth URL は、アプリの設定内の外部テストタブで確認できます。

アプリで RAK 認証またはプラットフォーム認証を使用する場合、変更は必要ありません。

サンドボックスでのアプリのテスト

サンドボックスへのインストールを処理するようにアプリを更新したら、独自のサンドボックスでアプリをテストできます。

メインアカウントで、アップロードしたサンドボックスに対応する外部テストリンクを作成します。
新しいサンドボックスを作成して、更新したアプリをテストします。その後、新しいサンドボックスを開きます。
新しいブラウザーウィンドウで、以前作成した外部テストリンクにアクセスし、アプリをインストールします。
サンドボックスにインストールしたアプリが想定どおりに動作するかどうかをテストします。

サンドボックス API キーと Webhook の動作の検証

Workbench を使用して、サンドボックスへのインストールが正しく機能しているかどうかを検証できます。

_テストサンドボックス_内でいくつかのサンプルアクションを実行します。
次に、_マネージドサンドボックス_内で Workbench を開きます。

Workbench を使用して、API ログの確認やイベントのフィルタリングなど、アプリの動作を調べられます。アプリが適切に更新されている場合は、サンプルアクションのすべての API コールと Webhook イベントを確認できます。

イベントやレスポンスが想定どおりに表示されない場合は、マネージドサンドボックス内でテストしていることを再度確認してください。また、サンドボックス固有の Webhook エンドポイントが設定されていることと、アプリが適切なサンドボックス API キーを必要に応じて使用していることも併せて確認してください。

アプリを提出して審査を受ける

サンドボックスのサポートを有効にし、サンドボックス内でアプリが想定どおりに動作することを確認したら、アプリを審査に提出することができます。アプリのサンドボックスのサポートは、アプリの審査プロセスの一環として確認され、アプリ一覧の詳細ページに表示されます。