API と高度な使用法
ダッシュボードと API でテストクロックを使用するための高度な戦略をご紹介します。
高度なシミュレーションを実行するために、サブスクリプションとは別にテストクロックを作成できます。このシナリオでは、まずテストクロックを作成してから、そこにさまざまなテストケースを追加します。
完全統合型のソリューションをご希望でない場合、サブスクリプションのシミュレーションの実行についてStripe のガイドをご覧ください。
![テストクロックを設定して、サブスクリプションの時間経過をシミュレーションする方法。](https://b.stripecdn.com/docs-statics-srv/assets/test-clock-lifecycle.b711b9cf4feb52351e27958b8b924cb3.png)
テストクロックのライフサイクル
以下の手順でテストクロックの使用を開始します。
テストケースごとに必要に応じてクロックの時間を進めたり、変更をモニターしたり、シミュレーションを更新したりできます。
クロックを作成して時間を設定する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
シミュレーションを開始するには、クロックを作成し、その凍結時刻を設定します。これは、クロックに関連付けられたすべてのサブスクリプションの時間的な開始点です。この時刻は過去または未来に設定して、さまざまなシミュレーションをテストできますが、設定後は進行のみが可能になります。
シミュレーションを設定する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
次に、シミュレーションのためのテストケースを設定します。まず顧客を作成してから、その顧客のためのサブスクリプションを作成する必要があります。
最初のステップで作成した Clock オブジェクトに Customer と Subscription の両方のオブジェクトが関連付けられます。ダッシュボードでは、 アイコンにより、オブジェクトがクロックに関連付けられたことが示されます。
シミュレーションの時間を進める![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
テストクロックを作成してテストケースを設定した後で、クロックのシミュレーションの時間を進めます。初めて時間を進める場合は、クロックの作成時に設定した元の凍結時刻から時間を進めることになります。時間を進めることで、サブスクリプションの終了時、更新時、またはその他の変化が発生したとき (無料トライアルから有料のサブスクリプションへのアップグレードなど) に、システムがどのように機能するかを確認できます。
テストクロックは任意の期間で進めることができますが、一度に進めることができるのは元の凍結時刻から最大 2 期間までです。この期間の長さは、テストクロックに関連付けられた最短のサブスクリプション期間に基づき、継続価格によって決まります。たとえば月次のサブスクリプションがある場合、一度に進めることができるのは、2 カ月までです。テストクロックにサブスクリプションまたはサブスクリプションのスケジュールがない場合は、元の凍結時刻から最大 2 年間進めることができます。
変更を監視して処理する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
API リクエストまたはダッシュボード操作が成功すると、クロックは数秒後に指定された時間に進みます。いつクロックの状態が変化したかを知るには、Webhook を使用してイベント通知をリッスンするか、クロックをポーリングします。ダッシュボードにも変更が反映されます。たとえば、請求書ページにアクセスして、サブスクリプションの請求書が作成されたか、または支払われたかを確認できます。
Webhook を使用している場合には、以下のイベント通知をリッスンします。本番環境に移行する前に、システムが、以下に記載されたものに加え、その他の請求固有のイベント通知も正しく処理することを確認してください。
イベント | 説明 |
---|---|
test_ | クロックは進み始めましたが、指定された時間に達していません。 |
test_ | クロックは、指定された時間への進行を終了しました。 |
クロックの状態をポーリングするには、ID を使用して状態を取得し、status
を調べます。
シミュレーションを更新する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
続けて変更を加え、以下のようなシミュレーションに合わせてクロックを進めることができます。
- 顧客の残高を追加する。
- サイクルの途中でアップグレードする。
- 1 回限りの請求書アイテムを追加する。
それぞれの更新の後、再び変更を監視します。テストケースに対応するために、必要に応じて何回も繰り返します。
クロックを削除する![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
テストクロックは、作成から 30 日経過すると自動的に削除されますが、テストの終了後に削除してテスト環境を整然と保つことができます。
クロックを削除すると、クロックに関連付けられたテスト用の顧客も削除され、そのサブスクリプションがキャンセルされます。テストクロックはテスト環境のみで使用できるため、クロックを削除しても本番環境のオブジェクトは何も削除されません。
ユースケース![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
サブスクリプションの更新をテストする![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
まず、以下の手順でテストクロックの使用を開始します。
次に、テストクロックを使用して特定のサブスクリプションの更新をテストできます。たとえば、月額 50 USD のサブスクリプションが正しく更新されるかどうかをテストするとします。テストクロックを使用してこの状況をシミュレーションするには、以下のようにします。
- 新しいテストクロックを作成して
frozen_
を 1 月 1 日に設定します。time - 顧客を追加して、その顧客の支払い方法を追加します。
顧客の支払い方法を追加した後、新しい顧客に対して月額 50 USD に設定されたサブスクリプションを作成します。そうすると、50 USD の請求書が自動的に支払われ、サブスクリプションは
active
になります。日付を 2 月 1 日に進めて、50 USD の請求書が作成されたことを確認します。デフォルトでは、請求書は 1 時間にわたって
draft
状態で表示されます。時間を 1 時間進めて、請求書が確定され、自動的に支払われることを確認します。
比例配分が適用されるサイクル途中のアップグレードをテストする![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
まず、以下の手順でテストクロックの使用を開始します。
次に、請求サイクルの途中でプランをアップグレードする顧客の比例配分 (日割り / 秒割り計算) をテストできます。たとえば、2 つの商品があるとします。1 つの商品は月額 50 USD (‘basic plan’) で、もう 1 つの商品は月額 100 USD (‘premium plan’) です。この場合、請求サイクルの途中で ‘basic plan’ を ‘premium plan’ にアップグレードする顧客の比例配分をテストできます。テストクロックを使用してこの状況をシミュレーションするには、以下のようにします。
- 新しいテストクロックを作成して
frozen_
を 1 月 1 日に設定します。time - 顧客を作成して支払い方法を追加します。ここでは、 テストカードを使用します。
- ‘basic plan’ の月額 50 USD のサブスクリプションを作成します。これを完了すると、月額 50 USD の請求書が作成され、確定されて自動的に支払われたことが分かります。
- 日付を 2 週間進めます。ここでは日付を 1 月 16 日に設定します。
- サブスクリプションを月額 100 USD の ‘premium plan’ にアップグレードします。
サブスクリプションをアップグレードした後、customer.subscription.updated Webhook イベントが作成されます。
比例配分の場合は保留中の請求書アイテムも作成されます。‘basic plan’ の未使用時間に対するマイナスの比例配分 -25 USD と、残り半月における ‘premium plan’ の使用に対するプラスの比例配分 50 USD が示されます。この時点では、請求書は生成されません。
日付を 2 週間進めます。ここでは日付を 2 月 1 日に設定します。サブスクリプションが循環したことが分かります。請求書が
draft
状態で生成され、マイナスの比例配分、プラスの比例配分、2 月の支払い総額を含む保留中の請求書アイテムが取り込まれ、125 USD になっています。デフォルトでは、請求書は約 1 時間にわたってdraft
状態で表示されます。請求書を確定するには、時間を 1 時間進めます。
トライアルをテストする![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
まず、以下の手順でテストクロックの使用を開始します。
次に、テストクロックを使用してトライアルのテストを開始できます。たとえば、顧客に支払いを開始する前に 7 日間のトライアルで商品を無料で試してもらい、決済情報は事前に収集するとします。テストクロックを使用してこの状況をシミュレーションするには、以下のようにします。
- 新しいテストクロックを作成して
frozen_
を 1 月 1 日に設定します。time - 顧客を追加して支払い方法を含めます。ここでは、 のテストカードを使用します。
- サブスクリプションを作成して、7 日間無料のトライアル期間を追加します。
- 7 日間無料のトライアル期間を設けてサブスクリプションを作成すると、サブスクリプションが
trialing
状態で作成されます。無料トライアルであるため、$0.00 の請求書が生成されます。 - 日付を 1 月 5 日に進めて、customer.subscription.trial_will_end のイベント通知を確認します。Stripe はトライアル終了の 3 日前に通知を送信します。この Webhook イベントを使用して、トライアルがまもなく終了することを顧客に通知できます。
- 日付を 1 月 8 日に進めて、サブスクリプションが
paid
になり、50 USD の請求書が作成されたことを確認します。 - サイクルを 1 つ (月次サブスクリプションの場合は 2 月 8 日まで) 進めて、サブスクリプションが更新されることを確認します。
制限事項![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
テストクロックを効率的に進めるために、Stripe は、各シミュレーションの複雑度に関する制限を以下のように設定しています。
- 3 名の顧客
- 顧客ごとに 3 件のサブスクリプション (スケジュール済みサブスクリプションを含む)
- 顧客に関連付けられていない 10 件の見積もり
すべての結果のリストで省略されたテストクロックオブジェクト![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Stripe のリスト API (請求書の一覧など) では、すべてのリクエストを一覧表示するテストクロックで生成された結果が省略されます。これらのケースでテストクロックによって生成された結果を確認するには、test_
、customer
、または subscription
など、特定の親内の結果をリクエストする必要があります。
たとえば、GET /v1/invoices
はテストクロックで生成された請求書を返しませんが、GET /v1/invoices/{customer_
は、テストクロックで生成されたものも含め、その顧客のすべての請求書を返します。
同様に、この例でテストクロック ID を指定して、そのテストクロックに関連するすべての請求書を取得することも、サブスクリプション ID を指定して、テストクロックによって生成された請求書を含む、そのサブスクリプションに対して請求されたすべての請求書を返すこともできます。
決済処理の注意事項![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
現在、テストクロックの進行は銀行口座引き落としによる支払いの回収 (支払い方法のタイプ us_
など) に対応していません。Stripe は、テストクロックが時間を進めた後で支払いを回収します。支払いの失敗をテストするには、次の手順を実行します。
Cancel subscription after all payment retries fail (すべての支払いの再試行が失敗した後にサブスクリプションをキャンセルする) 設定を選択します。
支払いが失敗した顧客に
us_
の支払い方法のタイプを追加します。bank_ account その顧客でサブスクリプションを作成します。
テストクロックを進めて、サブスクリプションで支払いを繰り返して回収します。
テストクロックが時間を進めた後、サブスクリプションのステータスは active
のままになります。これは、テストクロックの進行中に支払いの回収が試行されなかったことを示し、サブスクリプションは payment_
による canceled
ステータスにはまだなっていません。
invoice.
イベントをリッスンして、遅延が生じたサブスクリプションのステータスと請求書の支払いをモニターします。customer.
イベントは、サブスクリプションのステータスが canceled
に設定されたことを示します。