# サブスクリプションで Webhook を使用する

Webhook を使用して、サブスクリプションのアクティビティ通知を受信する方法をご紹介します。

アプリでは Webhook イベントを介して Stripe から通知を受け取ります。[イベントの送信先](https://docs.stripe.com/events/set-up-events.md)を作成し、Webhook エンドポイント、または Amazon EventBridge や Azure Event Grid などの送信先でこれらのイベントを処理します。ほとんどの*サブスク* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis)の処理は非同期で行われるため、サブスクの実装には Webhook イベントを処理する送信先が必要です。

サブスクリプションでの Webhook の使用:

1. アプリに Webhook エンドポイントを作成します。
2. ワークベンチで [Webhook エンドポイント](https://docs.stripe.com/webhooks.md)を登録します。
3. Stripe イベントを処理するロジックを追加します。Subscriptions については、支払いの失敗やサブスクリプションステータスの変更 (`trial` から `active` ステータスへの移行など) が含まれます。[webhook quickstart](https://docs.stripe.com/webhooks/quickstart.md) を用いて、最小限の webhook エンドポイントを構築することができます。[受信イベントが Stripe からのものであること](https://docs.stripe.com/webhooks.md#verify-events)を必ず確認してください。
4. Webhook エンドポイントをテストして、想定どおりに動作していることを確認します。

アプリケーションがAWSで実行されている場合は、[AWSアカウントのAWS EventBridgeに直接イベントを送信するようにStripeを設定](https://docs.stripe.com/event-destinations/eventbridge.md)できます。アプリケーションがAzureで実行されている場合は、[AzureサブスクリプションのAzure Event Gridに直接イベントを送信するようにStripeを設定](https://docs.stripe.com/event-destinations/eventgrid.md)できます。

## サブスクリプションイベント

Stripe は、サブスクリプションが作成または変更されるたびに、[イベント](https://docs.stripe.com/api.md#event_types)をトリガーします。一部のイベントはサブスクリプションが作成されるとただちに送信され、その他のイベントは一定の請求期間で発生します。

自社の構築済みのシステムでイベントが適切に処理されることを確認します。たとえば、支払いが失敗すると顧客にメールを送信したり、サブスクリプションがキャンセルされると顧客のアクセスを取り消したりすることができます。

次の表は、サブスクリプションに関連する最も一般的なイベントについて説明したものであり、該当する場合は、イベントを処理するためのアクションを提示しています。

> Accounts v2 API は、Connect ユーザー向けに GA になり、その他の Stripe ユーザー向けには公開プレビューになります。
> 
> 顧客を表すのに [Accounts v2](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) オブジェクトまたは [Customer](https://docs.stripe.com/api/customers.md) オブジェクトのいずれを使用する場合でも、`customer.subscription` イベントを使用してサブスクリプションイベントを追跡します。

| イベント | 説明 |
| --- | --- |
| `v2.core.account.created` | [v2 Account](https://docs.stripe.com/api/v2/core/accounts/object.md) が正常に作成されたときに送信されます。 |
| `customer.created` | [Customer (顧客)](https://docs.stripe.com/api/customers/object.md)の作成に成功すると送信されます。 |
| `customer.subscription.created` | サブスクリプションが作成されると送信されます。決済を完了するために顧客の認証が必要な場合、または `payment_behavior` を [default_incomplete](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-payment_behavior) に設定した場合、サブスクリプションの `status` が `incomplete` になる場合があります。 |
| `customer.subscription.deleted` | 顧客のサブスクリプションが終了すると送信されます。 |
| `customer.subscription.paused` | サブスクリプションの `status` が `paused` に変更されたときに送信されます。たとえば、決済手段がないまま[トライアル期間が終了する](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#create-free-trials-without-payment)とサブスクリプションを一時停止するように[設定した場合](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-trial_settings-end_behavior-missing_payment_method)に、このイベントを送信します。サブスクリプションが[再開される](https://docs.stripe.com/api/subscriptions/resume.md)まで、請求処理は行われません。請求書はその期間中も作成され続けるため、[決済の回収を一時停止する](https://docs.stripe.com/billing/subscriptions/pause-payment.md)場合、このイベントは送信されません。 |
| `customer.subscription.resumed` | 以前に `paused` ステータスだったサブスクリプションを再開すると送信されます。これは、[決済の回収](https://docs.stripe.com/billing/subscriptions/pause-payment.md#unpausing)の一時停止を解除した場合には適用されません。 |
| `customer.subscription.trial_will_end` | [トライアル期間が終了する ](https://docs.stripe.com/billing/subscriptions/trials.md)3 日前に送信されます。トライアルが 3 日未満の場合も、このイベントがトリガーされます。 |
| `customer.subscription.updated` | サブスクリプションが開始または[変更](https://docs.stripe.com/billing/subscriptions/change.md)された場合に送信されます。たとえば、サブスクリプションの更新、クーポンの追加、割引の適用、請求書アイテムの追加、プランの変更はすべて、このイベントのトリガーとなります。 |
| `entitlements.active_entitlement_summary.updated` | 顧客の有効なエンタイトルメントが更新されると送信されます。このイベントを受け取ると、商品の機能へのアクセスをプロビジョニングまたはデプロビジョニングすることができます。[エンタイトルメントの導入](https://docs.stripe.com/billing/entitlements.md)の詳細をご覧ください。 |
| `invoice.created` | 新規または更新済みのサブスクリプションに対して請求書が作成されると送信されます。Stripe で `invoice.created` に対する成功レスポンスを受信できない場合、[自動請求](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md)で指定されたすべての請求書の確定が最大 72 時間遅延します。詳しくは、[請求書の確定](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized)をご覧ください。
- [Finalize an Invoice (請求書の確定)](https://docs.stripe.com/api/invoices/finalize.md) API にリクエストを送信することで通知に応答します。 |
| `invoice.finalized` | 請求書の確定に成功し、支払いの準備が整うと送信されます。
- 顧客に請求書を送信できます。詳しくは、[請求書の確定](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized)をご覧ください。
- 設定に応じて、Stripe は自動的にデフォルトの支払い方法に請求するか、回収を試みます。詳しくは、[確定後のメール](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#emails)をご覧ください。 |
| `invoice.finalization_failed` | 請求書の確定に失敗しました。[請求書の確定の失敗を処理する方法](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures)と[請求書の確定](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized)の詳細を見る。
- 請求書の [last_finalization_error](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) を調べて、エラーの原因を特定します。
- Stripe Tax を使用している場合は、`Invoice` オブジェクトの[automatic_tax](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) フィールドを確認してください。
- `automatic_tax[status]=requires_location_inputs` の場合、請求書を確定させることはできず、決済を回収できません。顧客に通知し、必要な[顧客の住所情報](https://docs.stripe.com/tax/customer-locations.md)を回収します。
- `automatic_tax[status]=failed` の場合、後でリクエストを再試行します。 |
| `invoice.paid` | 請求書の支払いに成功すると送信されます。このイベントを受け取り、サブスクリプションの `status` が `active` になると、商品へのアクセスを提供できます。 |
| `invoice.payment_action_required` | 請求書に顧客の認証を必要とする場合に送信されます。請求書で[アクションが必要](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action)な場合にサブスクリプションを処理する方法をご紹介します。 |
| `invoice.payment_failed` | 請求書に対する決済が失敗しました。PaymentIntent のステータスは`requires_action` に変わります。サブスクリプションのステータスは、サブスクリプションの最初の請求書に対して_のみ_ `incomplete` のままになります。決済が失敗した場合、以下のような処理を行います。

- 顧客に通知します。
- ダッシュボードで[サブスクリプション設定](https://dashboard.stripe.com/settings/billing/automatic)を行い、[Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) およびその他の売上の回収機能を有効にします。
- PaymentIntent を使用している場合、新しい支払情報を収集し、[PaymentIntent を確定](https://docs.stripe.com/api/payment_intents/confirm.md)します。
- サブスクリプションの [default payment method (デフォルトの支払い方法)](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method) を更新します。 |
| `invoice.upcoming` | サブスクリプションの更新の数日前に送信されます。何日前に送信されるかについては、[ダッシュボード](https://dashboard.stripe.com/settings/billing/automatic)の**次回の更新イベント**に設定された数値を参照します。既存のサブスクリプションについては、日数の変更は次の請求期間から有効になります。必要に応じて、[追加の請求書アイテム](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items)を加えることもできます。 |
| `invoice.updated` | 決済が成功または失敗したときに送信されます。決済が成功した場合、`paid` 属性は `true` に設定され、`status` は `paid` になります。決済が失敗した場合、`paid` は `false` に設定され、`status` は `open` のままになります。決済の失敗では、`invoice.payment_failed` イベントもトリガーされます。 |
| `payment_intent.created` | [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) が作成されると送信されます。 |
| `payment_intent.succeeded` | PaymentIntent が正常に支払いを完了すると送信されます。 |
| `subscription_schedule.aborted` | サブスクリプションスケジュールが、支払いの滞納により関連するサブスクリプションが終了となったことが原因でキャンセルされた場合に送信されます。 |
| `subscription_schedule.canceled` | サブスクリプションスケジュールがキャンセルされ、それに関連するアクティブなサブスクリプションもキャンセルされた場合に送信されます。 |
| `subscription_schedule.completed` | サブスクリプションスケジュールのすべての[フェーズ](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#subscription-schedule-phases)が完了した場合に送信されます。 |
| `subscription_schedule.created` | 新しいサブスクリプションスケジュールが作成された場合に送信されます。 |
| `subscription_schedule.expiring` | サブスクリプションスケジュールが無効になる 7 日前に送信されます。 |
| `subscription_schedule.released` | サブスクリプションスケジュールがサブスクリプションから[リリース](https://docs.stripe.com/api/subscription_schedules/release.md)されたとき、または停止され関連付けが解除されたときに送信されます。サブスクリプションはその後も残ります。 |
| `subscription_schedule.updated` | サブスクリプションスケジュールが更新された場合に送信されます。 |

## リスクイベントと顧客データイベントを処理する

上記のサブスクのライフサイクルイベントにより、請求およびエンタイトルメントの変更が実装に通知されます。本番環境の実装で決済を受け付けている場合は、返金、不審請求の申し立て、不正利用の警告に関するイベントも処理します。これらのイベントを処理しないと、不審請求の申し立てが行われた場合や、不正利用の疑いがあるとしてフラグが立てられた場合に、実装に通知されません。

実装で顧客データをローカルに保存する場合は、`customer.updated` の処理も検討してください。

| イベント | サブスクで重要な理由 |
| --- | --- |
| `charge.dispute.created` | 顧客または顧客の銀行から支払いに対して不審請求の申し立てが行われました。このイベントを使用して、反証資料を提出するか、アカウントへのアクセスを制限するか、その他の対応を行うかを判断します。関連するサブスクへの対応については、[返金、不審請求の申し立て、不正利用の早期警告イベントを処理する](https://docs.stripe.com/billing/subscriptions/webhooks.md#refund-events)を参照してください。 |
| `charge.refunded` | サブスクの請求に関連する支払いが全額または一部返金されました。関連するサブスクへの対応については、[返金、不審請求の申し立て、不正利用の早期警告イベントを処理する](https://docs.stripe.com/billing/subscriptions/webhooks.md#refund-events)を参照してください。 |
| `radar.early_fraud_warning.created` | カード発行会社またはネットワークが、支払いを潜在的な不正利用として特定しました。これは通常、正式な不審請求の申し立てが行われる前に発生します。関連するサブスクへの対応については、[返金、不審請求の申し立て、不正利用の早期警告イベントを処理する](https://docs.stripe.com/billing/subscriptions/webhooks.md#refund-events)を参照してください。 |
| `customer.updated` | [顧客](https://docs.stripe.com/api/customers/object.md)のプロパティが変更されると、このイベントが Stripe から送信されます。[カスタマーポータル](https://docs.stripe.com/customer-management.md)のフローでは、請求情報やデフォルトの決済手段など、顧客レベルの詳細を更新できます。顧客データをローカルに保存している場合、または顧客フィールドの変更に応じた対応が必要な場合は、このイベントをリッスンします。顧客を [Accounts v2](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) で表している場合は、代わりに顧客の設定変更については `v2.core.account[configuration.customer].updated` を、本人確認情報の変更については `v2.core.account[identity].updated` をリッスンします。 |

実装に必要なイベントのみをサブスクライブします。リスクイベントを除外すると、ダッシュボードを確認するまで、不審請求の申し立てや不正利用の警告がアプリケーションに通知されません。

## 支払いの失敗を処理する

イベントは、Stripe がサブスクリプションの請求書の支払い失敗を通知するために利用する信頼性の高い方法です。支払い失敗のケースには一時的なものもあり、たとえば、カード発行会社が最初の支払いを拒否しているにもかかわらず、自動再試行を許可した場合などにこの一時的な支払い失敗が発生します。それ以外の支払い失敗は最終的なもの (例: 顧客が使用できる決済手段がないなど) であり、アクションが必要です。

| イベント | 説明 |
| --- | --- |
| `invoice.payment_failed` | 請求書の支払いが失敗しました。PaymentIntent のステータスが `requires_payment_method` になり、サブスクリプションのステータスは `incomplete` になります。支払いの失敗があった場合、以下の対応を検討してください。

- 顧客に通知します。
- PaymentIntents を使用している場合、新しい支払情報を収集し、[PaymentIntent を確定](https://docs.stripe.com/api/payment_intents/confirm.md)します。
- サブスクリプションの[デフォルトの支払い方法](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method)を更新します。
- [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) を有効にすることを検討してください。 |

## 追加のアクションが必要な支払いを処理する

支払い方法によっては、顧客認証のような追加手順の完了が必要になることがあります。こうしたイベントを受け取ったら、お客様のアプリから顧客に対して、必要な対応を行うように通知する必要があります。[追加措置が必要なイベントを処理する](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action)方法については、サブスクリプション概要ガイドをご覧ください。

| イベント | 説明 |
| --- | --- |
| `invoice.finalization_failed` | 請求書を確定できませんでした。[請求書確定失敗](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures)の対処方法については、ガイドをご覧ください。[請求書確定](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized)の詳細については、請求書概要ガイドをご覧ください。
- Invoice の [last_finalization_error](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) を調べて、エラーの原因を判別します。
- Stripe Tax を使用している場合は、請求書オブジェクトの [automatic_tax](https://docs.stripe.com/api/invoices/object.md#invoice_object-automatic_tax) フィールドを確認してください。
- `automatic_tax[ステータス]=requires_location_inputs` の場合、請求書を確定させることはできず、支払いを回収できません。顧客に通知し、必要な[顧客店舗](https://docs.stripe.com/tax/customer-locations.md)を徴収します。
- `automatic_tax[status]=failed` の場合は、後でリクエストを再試行してください。 |
| `invoice.payment_failed` | 請求書の支払いが失敗しました。PaymentIntent のステータスが `requires_action` になり、サブスクリプションのステータスは `incomplete` になります。支払いの失敗があった場合、以下の対応を検討してください。

- 顧客に通知します。
- PaymentIntents を使用している場合、新しい支払情報を収集し、[PaymentIntent を確定](https://docs.stripe.com/api/payment_intents/confirm.md)します。
- サブスクリプションの[デフォルトの支払い方法](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method)を更新します。
- [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) を有効にすることを検討してください。 |
| `invoice.payment_action_required` | 請求書に顧客の認証を必要とする場合に送信されます。請求書で[アクションが必要](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action)な場合にサブスクリプションを処理する方法をご紹介します。 |

## 返金、不審請求の申し立て、不正利用の早期警告イベントを処理する

サブスクに関連付けられた支払いが返金された場合や、不審請求を申し立てられた場合、または不正利用としてマークされた場合に、Stripe は次のいずれかのイベントを送信します。

- `charge.refunded`: 更新された [Charge](https://docs.stripe.com/api/charges/object.md) が含まれます。
- `charge.dispute.created`: [Dispute](https://docs.stripe.com/api/disputes/object.md) が含まれ、[charge](https://docs.stripe.com/api/disputes/object.md#dispute_object-charge) と null 許容の [payment_intent](https://docs.stripe.com/api/disputes/object.md#dispute_object-payment_intent) が公開されます。
- `radar.early_fraud_warning.created`: [EarlyFraudWarning](https://docs.stripe.com/api/radar/early_fraud_warnings/object.md) が含まれ、[charge](https://docs.stripe.com/api/radar/early_fraud_warnings/object.md#early_fraud_warning_object-charge) と null 許容の [payment_intent](https://docs.stripe.com/api/radar/early_fraud_warnings/object.md#early_fraud_warning_object-payment_intent) が公開されます。

請求書やサブスクに関連付けられていない支払いおよび PaymentIntent もあります。サブスクを特定する方法は API バージョンによって異なります。

### API バージョン 2025-03-31.basil 以降

1. [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) ID を取得します。`charge.refunded` の場合、Charge の [payment_intent](https://docs.stripe.com/api/charges/object.md#charge_object-payment_intent) フィールドを使用します。`charge.dispute.created` または `radar.early_fraud_warning.created` の場合、Dispute オブジェクトまたは EarlyFraudWarning オブジェクトの `payment_intent` フィールドを使用します。`payment_intent` が null の場合は、[Charge を取得](https://docs.stripe.com/api/charges/retrieve.md)し、その [payment_intent](https://docs.stripe.com/api/charges/object.md#charge_object-payment_intent) フィールドを使用します。Charge にも `payment_intent` がない場合 (従来のダイレクト支払いなど)、この手順は適用されません。
2. [payment.type](https://docs.stripe.com/api/invoice-payment/list.md#list_invoice_payments-payment-type) を `payment_intent` に、[payment.payment_intent](https://docs.stripe.com/api/invoice-payment/list.md#list_invoice_payments-payment-payment_intent) を PaymentIntent ID に、[status](https://docs.stripe.com/api/invoice-payment/list.md#list_invoice_payments-status) を `paid` に設定して、[請求書のすべての支払い一覧を取得](https://docs.stripe.com/api/invoice-payment/list.md)エンドポイントを使用します。リストが空の場合、この手順では関連付けられた請求書を特定できません。
3. 1 つの PaymentIntent が複数の請求書に関連付けられている場合があるため、このエンドポイントは複数の `InvoicePayment` を返すことがあります。`has_more` が true である間は、すべての結果をページネーションして取得します。各 `InvoicePayment` には、関連付けられた請求書 ID を含む [invoice](https://docs.stripe.com/api/invoice-payment/object.md#invoice_payment_object-invoice) フィールドが含まれます。
4. 各請求書 ID で Invoice を取得し、[parent.type](https://docs.stripe.com/api/invoices/object.md#invoice_object-parent-type) が `subscription_details` であることを確認します。次に、[parent.subscription_details.subscription](https://docs.stripe.com/api/invoices/object.md#invoice_object-parent-subscription_details-subscription) を使用して [Subscription](https://docs.stripe.com/api/subscriptions/object.md) を取得します。

### 2025-03-31.basil より前の API バージョン

以前の API バージョンでは、Charge オブジェクトに [invoice](https://docs.stripe.com/api/charges/object.md?api-version=2025-02-24.acacia#charge_object-invoice) フィールドが含まれます。

1. Charge を取得します。`charge.refunded` の場合は、イベントの Charge を使用します。`charge.dispute.created` または `radar.early_fraud_warning.created` の場合、Dispute または EarlyFraudWarning の `charge` フィールドは ID です。その ID を使用して [Charge を取得](https://docs.stripe.com/api/charges/retrieve.md)します。
2. Charge の `invoice` フィールドが null の場合、この手順では関連付けられた請求書を特定できません。それ以外の場合は、Invoice を取得し、その [subscription](https://docs.stripe.com/api/invoices/object.md?api-version=2025-02-24.acacia#invoice_object-subscription) フィールドを使用して Subscription を取得します。

## 有効なサブスクリプションを追跡する

サブスクリプションでは、お客様のウェブサイトと Stripe 間での調整が必要になります。顧客の継続課金の成功または失敗によって、顧客が商品またはサービスの利用を継続できるかどうかが決まります。

一般的なシステムの場合、顧客がサブスクリプションを登録したときに顧客の認証情報と、その顧客のアクセス有効期限を表すマッピングされたタイムスタンプ値がサイトに保存されます。顧客のログイン時に、タイムスタンプが将来の日付になっているかを確認してください。顧客がログインしたときのタイムスタンプが将来の日付である場合、そのアカウントは有効であり、顧客は引き続きサービスにアクセスできます。

サブスクリプションが[更新](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle)されると、Stripe は登録されている顧客の決済手段に[自動請求](https://docs.stripe.com/invoicing/automatic-charging.md)するか、または顧客に[請求書をメールで送付](https://docs.stripe.com/invoicing/integration.md#accept-invoice-payment)して支払いの回収を試みます。Stripe は Webhook イベントを送信して、お客様のサイトに請求書のステータスを通知します。

1. サイトが `invoice.paid` イベントを受信します。

   - 決済手段に自動請求する場合、更新の数日前にお客様のサイトは、設定した [Webhook エンドポイント](https://docs.stripe.com/webhooks.md)への `invoice.upcoming` イベントを受信します。このイベントをリッスンして、次の請求書に[請求書項目を追加](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items)することができます。`collection_method=send_invoice` の場合、Stripe は `invoice.upcoming` イベントを送信しません。

2. アプリケーションは、支払い済みの顧客を検索します。

3. `invoice.paid` を受信した後、関連するサブスクを取得し、ステータスが `active` であることを確認してから、顧客のアクセス有効期限を延長します。ステータスの判定にすべての請求を使用する場合、支払い済みの請求によってサブスクが必ずしも `active` に移行するとは限りません。

## サブスクリプションのステータス変化を検出する

次の表で説明するサブスクリプションステータスの移行が、システムで適切に監視・処理されていることを確認してください。

一部のステータス変更には特別な注意が必要です。

- トライアル期間が終了し、サブスクリプションが `trialing` から `active` に移行する数日前に、`customer.subscription.trial_will_end` イベントが送信されます。このイベントを受け取ったら、顧客に請求するための決済手段が顧客にあるか確認します。必要に応じて、今後請求されることを顧客に通知します。

- サブスクリプションが `past_due` に移行すると、顧客に直接通知し、支払い詳細を更新するように依頼します。Stripe はこのプロセスを自動化するのに役立ついくつかの機能を提供しています。[売上回収](https://docs.stripe.com/billing/revenue-recovery.md)についてご確認ください。

- サブスクリプションが `canceled` または `unpaid` に変更されたら、製品へのアクセスを取り消します。

| ステータス | 説明 |
| --- | --- |
| `trialing` | サブスクリプションは現在トライアル期間中であり、顧客にプロダクトを支障なく提供できます。初回の支払いが行われると、サブスクリプションは自動的に `active` に移行します。 |
| `active` | サブスクの状態は良好です。`past_due` のサブスクを `active` に移行するために、どの請求書を決済する必要があるかは、[サブスク設定](https://dashboard.stripe.com/settings/billing/subscriptions#manage-failed-payments)によって決まります。ステータスの判定に最新の請求書が使用される場合、Stripe は無効化されていない最新の請求書を使用してサブスクのステータスを判定します。その請求書を支払うか、手動で回収不能としてマークすると、サブスクは `active` に移行します。ステータスの判定にすべての請求書が使用される場合は、該当するすべての未払い請求書を決済して、サブスクを `active` に移行します。

`active` ステータスは、サブスクに関連するすべての未払い請求書が支払われたことを必ずしも示すものではありません。ステータスの解決に直近の請求書を使用する場合、必要に応じて、その他の未払い請求書を決済待ち (未処理) のままにするか、回収不能としてマークするか、または無効にすることができます。 |
| `incomplete` | 顧客がサブスクを有効にするには、23 時間以内に支払いを正常に完了する必要があります。あるいは、顧客認証など、支払いに[アクションが必要](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action)となる場合もあります。保留中の支払いがあり、PaymentIntent のステータスが `processing` の場合も、サブスクは `incomplete` になることがあります。 |
| `incomplete_expired` | サブスクリプションの初回の支払いが失敗し、サブスクリプションの作成から 23 時間以内に支払いが成功しませんでした。これらのサブスクリプションは顧客に請求されません。このステータスは、サブスクリプションの有効化に失敗した顧客を追跡するために存在します。 |
| `past_due` | 確定された直近の請求書に対する決済が失敗したか、試行されませんでした。ステータスの解決にすべての請求書を使用する場合、`past_due` は、該当する過去の請求書が未払いのままであることを示す場合もあります。この間も引き続きサブスクの請求書は作成されます。サブスクが `past_due` の間、Stripe は決済を再試行することがありますが、このステータスによって必ず決済が再試行されるわけではありません。サブスクの次のステータスは、ダッシュボードの[サブスクの設定](https://dashboard.stripe.com/settings/billing/subscriptions#manage-failed-payments)によって決定されます。すべての[決済の再試行](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md)が終了した後も請求書が未払いのままである場合、サブスクを `canceled` または `unpaid` に移行させるか、`past_due` のまま維持するかを設定できます。

サブスクを再有効化するには、ステータス判定で最新の請求書を使用する場合は、無効化されていない最新の請求書を支払うか、手動で回収不能としてマークします。あるいは、すべての請求書を使用する場合は、該当する未払い請求書を決済します。必要な請求書を決済したタイミングが支払期日の前か後かにかかわらず、サブスクは `active` になります。 |
| `canceled` | サブスクリプションがキャンセルされました。キャンセル時に未払いのすべての請求書の自動回収が無効化されます (`auto_advance=false`)。これは、更新できない最終的なステータスです。 |
| `unpaid` | Stripe がサブスクのステータスを `unpaid` に設定するのは、ダッシュボードの[サブスク設定](https://dashboard.stripe.com/settings/billing/subscriptions#manage-failed-payments)でこの結果が選択されている場合のみです。サブスクのステータスを規定する請求書は決済されていませんが、サブスクは維持されます。サブスクは請求書の生成を継続しますが、決済の試行は行いません。サブスクが `past_due` の間に Stripe はすでに決済を試行および再試行しているため、サブスクが `unpaid` になった時点でプロダクトへのアクセス権を取り消してください。サブスクを `active` に移行するには、ステータス判定で最新の請求書を使用する場合は、無効化されていない最新の請求書を支払うか、手動で回収不能としてマークします。あるいは、すべての請求書を使用する場合は、該当する未払い請求書を決済します。 |
| `paused` | サブスクリプションはデフォルトの決済手段なしでトライアル期間が終了し、[trial_settings.end_behavior.missing_payment_method](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#create-free-trials-without-payment) が `pause` に設定されています。サブスクリプションの請求書は作成されなくなりました。顧客にデフォルトの決済手段を関連付けた後で、[サブスクリプションを再開](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#resume-a-paused-subscription)できます。 |

## Webhook エンドポイントとインボイス

Webhook エンドポイントを登録して、請求書のステータスを追跡します。請求書を正しく確定できるかどうかの問題はサブスクリプションシステムにとって重要であり、確定に失敗した場合でも適切に処理しなければなりません。

[自動回収](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md)を有効にすると、Stripe は自動的に[インボイス](https://docs.stripe.com/billing/invoices/subscription.md)を確定し、自動回収を開始します。

- Stripe が `invoice.created` の成功応答を受信できない場合、[自動回収](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md)の設定された請求書の確定が最大 72 時間延期されます。ただし、[カスタムの確定日を設定](https://docs.stripe.com/invoicing/scheduled-finalization.md)している請求書はこの限りではありません。
- `invoice.created` に正しく応答すると、アカウントに設定されたすべての Webhook エンドポイントだけでなく、連結されたあらゆるプラットフォームの Webhook エンドポイントも処理されます。これには、[Organizations](https://docs.stripe.com/get-started/account/orgs.md) で設定された Webhook エンドポイントは含まれません。組織で `invoice.created` をリッスンすることはできますが、自動回収を使用している場合、正しく応答しても請求書の確定に影響を与えることはありません。
- 同期的に決済を試行するようにサブスクリプションを更新した (初回の請求書で、および一部の更新で) 場合には、このような遅延は発生しません。
- 請求書を確定しない限り、請求書の支払いは回収できません。Webhook エンドポイントで `invoice.finalization_failed` イベントをリッスンできることを確認してください。

### 請求書の確定に関連する Webhook イベント

[請求書のイベントタイプ](https://docs.stripe.com/api/events/types.md#event_types-invoice.created)の一覧をご覧ください。

| イベント | 説明 |
| --- | --- |
| `invoice.created` | インボイスは正常に作成され、確定の準備が整っています。[請求書の確定](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized)についての詳細は、ドキュメントをご確認ください。
- [Finalize an Invoice (請求書の確定)](https://docs.stripe.com/api/invoices/finalize.md) API にリクエストを送信することで通知に応答します。 |
| `invoice.finalized` | 請求書は正常に確定され、支払いの準備が整っています。
- 顧客にインボイスを送信できます。[請求書の確定](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized)についてご確認ください。
- 設定に応じて、Stripe は自動的にデフォルトの決済手段に請求するか、収集を試みます。[確定後のメール](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#emails)についてご確認ください。 |
| `invoice.finalization_failed` | インボイスを確定できませんでした。ガイドを参照して、[請求書の確定の失敗を処理](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures)する方法をご確認ください。請求書の概要ガイドに記載されている[請求書の確定](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized)を確認してください。
- Invoice の [last_finalization_error](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) を調べて、エラーの原因を判別します。
- Stripe Tax を使用している場合、Invoice オブジェクトの [automatic_tax](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) フィールドを確認します。
- `automatic_tax[status]=requires_location_inputs` の場合、インボイスを確定させることはできず、支払いを回収できません。顧客に通知し、必要な[顧客の場所](https://docs.stripe.com/tax/customer-locations.md)を収集します。
- `automatic_tax[status]=failed` の場合、後でリクエストを再試行します。 |

### 成功した請求書の確定

Stripe は `invoice.created` イベントへの成功応答を受信してから 1 時間待機し、その後に決済を試みます。 72 時間以内に成功応答を受信できない場合には、Stripe は請求書の確定と送信を試みます。

1 回限りの請求書をサブスクリプションの請求書とは異なる方法で処理する場合、Webhook 本文の `subscription` プロパティを確認してください。このプロパティーは、請求書がサブスクリプション用として作成されたかどうかを示します。

本番環境では、Webhook エンドポイントが正しく応答しない場合、Stripe は指数バックオフを使用して最長 3 日間 Webhook 通知の再試行を続けます。サンドボックスでは、数時間にわたって 3 回再試行します。その間は、正常な応答を受信しない限り顧客への請求を試行しません。また、Webhook にエラーが発生していることを知らせるメールも送信します。

この動作は、お客様のアカウントで定義されたすべての Webhook エンドポイントに適用されます。[Connect アプリケーション](https://stripe.com/works-with)、またはその他のサードパーティーサービスで受信 Webhook を処理できない場合も含まれます。

### 請求書確定の失敗

Stripe でインボイスを確定できない場合、`invoice.finalization_failed` [イベント](https://docs.stripe.com/api/events/types.md#event_types-invoice.finalization_failed)が Webhook エンドポイントに送信されます。インボイスを確定できない場合、サブスクリプションは引き続きアクティブなままです。そのため、支払いの回収ができなくても、ユーザーはまだ商品にアクセスできる可能性があります。確定できないインボイスは確実に処理してください。確定されていないインボイスに対して支払いを回収することはできません。

請求書の確定が失敗した理由を判別するには、インボイスオブジェクトの `last_finalization_error` [フィールド](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error)を確認してください。ここには、処理を進める方法を含む、失敗に関する詳細な情報が示されています。

Stripe Tax を使用している場合は、[automatic_tax.status](https://docs.stripe.com/api/invoices/object.md#invoice_object-automatic_tax-status) フィールドが `requires_location_inputs` になっていないか確認してください。これは、住所情報が無効または不十分であることを示します。認識済みの顧客の所在地が Stripe Tax で見つからない場合、請求書を確定することはできません。[請求書の確定失敗を処理する](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures)方法をご紹介します。

## テスト

Webhook エンドポイントまたは[イベントの送信先](https://docs.stripe.com/events/how-events-work.md)をテストするには、次の 2 つのオプションのいずれかを選択します。

1. イベント送信先に実際のイベントをトリガーするアクションをサンドボックスで実行してください。たとえば、[charge.succeeded](https://docs.stripe.com/api.md#event_types-charge.succeeded) イベントをトリガーするには、[支払いが成功するテストカード](https://docs.stripe.com/testing.md#cards)を使用します。
2. [Stripe CLI を使用してイベントをトリガー](https://docs.stripe.com/webhooks.md#test-webhook)するか、[Stripe for Visual Studio Code を使用](https://docs.stripe.com/stripe-vscode.md#webhooks)してイベントをトリガーします。

## See also

- [サブスクリプションのライフサイクル](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle)
- [サブスクリプションをテストする](https://docs.stripe.com/billing/testing.md)