# サブスクリプションで Webhook を使用する Webhook を使用して、サブスクリプションのアクティビティ通知を受信する方法をご紹介します。 Webhook イベントを介してアプリ内で Stripe から通知を受け取ります。[イベント送信先](https://docs.stripe.com/event-destinations.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` | サブスクリプションスケジュールが更新された場合に送信されます。 | ## 支払いの失敗を処理する イベントは、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](https://docs.stripe.com/api/charges/object.md) オブジェクトを含む `charge.refunded` イベントが送信されます。返金された Charge がどのサブスクリプションに属するかを特定するには、次の手順に従います。 1. [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) ID を、[payment_intent](https://docs.stripe.com/api/charges/object.md#charge_object-payment_intent) フィールドを使用して `Charge` から取得します。 2. [請求書のすべての決済を一覧表示](https://docs.stripe.com/api/invoice-payment/list.md)エンドポイントを使用し、[payment.payment_intent](https://docs.stripe.com/api/invoice-payment/list.md#list_invoice_payments-payment-payment_intent) を `PaymentIntent` ID に設定します。 3. 返される `InvoicePayment` には、関連付けられた `Invoice` ID を含む [invoice](https://docs.stripe.com/api/invoice-payment/object.md#invoice_payment_object-invoice) フィールドがあります。 4. `Invoice` を取得し、そのサブスクの参照を使用して、返金に関連付けられた [Subscription](https://docs.stripe.com/api/subscriptions/object.md) を取得します: - API バージョン `2025-03-31.basil` 以降の場合は、[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) を使用します。 - `2025-03-31.basil` より前の API バージョンの場合は、[subscription](https://docs.stripe.com/api/invoices/object.md?api-version=2025-02-24.acacia#invoice_object-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. アプリケーションにおいて、データベース内における顧客のアクセス有効期限が将来の適切な日付 (余裕として 1 ～ 2 日を追加) に更新されます。 ## サブスクリプションのステータス変化を検出する 次の表で説明するサブスクリプションステータスの移行が、システムで適切に監視・処理されていることを確認してください。 一部のステータス変更には特別な注意が必要です。 - トライアル期間が終了し、サブスクリプションが `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` に移行します。 `active` のステータスは、サブスクに関連付けられたすべての未払いの請求書が支払われたことを意味するものではありません。必要に応じて、その他の未払いの請求書を支払いのために未処理のままにするか、回収不能としてマークするか、または無効にすることができます。 | | `incomplete` | 顧客がサブスクを有効にするには、23 時間以内に支払いを正常に完了する必要があります。あるいは、顧客認証など、支払いに[アクションが必要](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action)となる場合もあります。保留中の支払いがあり、PaymentIntent のステータスが `processing` の場合も、サブスクは `incomplete` になることがあります。 | | `incomplete_expired` | サブスクリプションの初回の支払いが失敗し、サブスクリプションの作成から 23 時間以内に支払いが成功しませんでした。これらのサブスクリプションは顧客に請求されません。このステータスは、サブスクリプションの有効化に失敗した顧客を追跡するために存在します。 | | `past_due` | Payment on the latest *finalized* invoice either failed or wasn’t attempted. The subscription continues to create invoices. Stripe might retry payment while the subscription is `past_due`, but this status doesn’t guarantee another payment attempt. Your Dashboard [subscription settings](https://dashboard.stripe.com/settings/billing/subscriptions#manage-failed-payments) determine the subscription’s next status. If the invoice is still unpaid after all attempted [payment retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md), you can configure the subscription to move to `canceled`, `unpaid`, or leave it as `past_due`. サブスクを再度有効にするには、最新の請求書の支払いを顧客に依頼します。支払いが最新の請求書の期日より前に行われたか後に行われたかに関係なく、サブスクのステータスは `active` になります。 | | `canceled` | サブスクリプションがキャンセルされました。キャンセル時に未払いのすべての請求書の自動回収が無効化されます (`auto_advance=false`)。これは、更新できない最終的なステータスです。 | | `unpaid` | Stripe sets a subscription’s status to `unpaid` only when your Dashboard [subscription settings](https://dashboard.stripe.com/settings/billing/subscriptions#manage-failed-payments) select this outcome. The latest invoice hasn’t been paid but the subscription remains in place. The latest invoice remains open and invoices continue to generate, but payments aren’t attempted. Revoke access to your product when the subscription is `unpaid` because payments were already attempted and retried while `past_due`. To move the subscription to `active`, pay the most recent invoice before its due date. | | `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/event-destinations.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)