サブスクリプションでイベントの送信先を使用する

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

Stripe は、イベントの送信先を使用して、アプリに通知を送信します。ほとんどのアクティビティーが非同期で発生する場合、イベントの送信先はサブスクリプションの管理に役立ちます。

サブスクリプションでイベントの送信先を使用するには、以下のようにします。

アプリで Webhook エンドポイントを作成します。
Stripe イベントを処理するロジックを追加します。サブスクリプションの場合、支払いの失敗やサブスクリプションのステータスの変化などが含まれます (trial から active ステータスへの移行など)。
Webhook エンドポイントをテストして、予期したとおりに機能していることを確認します。

アプリケーションが AWS で稼働している場合、AWS アカウントで AWS EventBridge にイベントを直接送信するように Stripe を設定できます。

イベントの送信先を設定して使用する方法をご紹介します。また、Webhook クイックスタートを使用して、最小限の Webhook エンドポイントを構築します。

Subscription events

Stripe は、サブスクリプションが作成または変更されるたびに、Event (イベント) をトリガーします。一部のイベントはサブスクリプションが作成されるとただちに送信され、その他のイベントは一定の請求間隔で発生します。

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

以下の表には、サブスクリプションに関連する最も一般的なイベントと、該当する場合は、それらのイベントを処理するための推奨アクションが示されています。



`customer.created`	Customer (顧客)の作成に成功すると送信されます。
`customer.subscription.created`	サブスクリプションが作成されると送信されます。支払いを完了するために顧客の認証が必要な場合、または `payment_behavior` を `default_incomplete` に設定した場合、サブスクリプションの `status` が `incomplete` になります。詳しくは、サブスクリプションの支払い処理をご覧ください。
`customer.subscription.deleted`	顧客のサブスクリプションが終了すると送信されます。
`customer.subscription.paused`	サブスクリプションの `status` が `paused` に変わると送信されます。たとえば、支払い方法が指定されないまま無料トライアルが終了した場合に一時停止するようサブスクリプションが設定されている場合に送信されます。サブスクリプションが再開されるまで請求書は作成されません。支払いの回収が一時停止されている場合、その期間中も請求書は引き続き作成されるため、このイベントは送信されません。
`customer.subscription.resumed`	以前に `paused` ステータスであったサブスクリプションが再開されると送信されます。支払いの回収の一時停止が解除された場合は、これに該当しません。
`customer.subscription.trial_will_end`	トライアル期間終了の 3 日前に送信されます。トライアル期間が 3 日未満の場合、このイベントがトリガーされます。
`customer.subscription.updated`	サブスクリプションが開始または変更された場合に送信されます。たとえば、サブスクリプションの更新、クーポンの追加、割引の適用、請求書アイテムの追加、プランの変更はすべて、このイベントのトリガーとなります。
`entitlements.active_entitlement_summary.updated`	顧客の有効なエンタイトルメントが更新されると送信されます。このイベントを受け取ると、商品の機能へのアクセスをプロビジョニングまたはデプロビジョニングすることができます。エンタイトルメントの導入の詳細をご覧ください。
`invoice.created`	新規または更新済みのサブスクリプションに対して請求書が作成されると送信されます。Stripe で `invoice.created` に対する成功レスポンスを受信できない場合、自動請求で指定されたすべての請求書の確定が最大 72 時間遅延します。詳しくは、請求書の確定をご覧ください。 Finalize an Invoice (請求書の確定) API にリクエストを送信することで通知に応答します。
`invoice.finalized`	請求書の確定に成功し、支払いの準備が整うと送信されます。顧客に請求書を送信できます。詳しくは、請求書の確定をご覧ください。設定に応じて、Stripe は自動的にデフォルトの支払い方法に請求するか、回収を試みます。詳しくは、確定後のメールをご覧ください。
`invoice.finalization_failed`	請求書を確定することができませんでした。ガイドを参照して、請求書の確定失敗を処理する方法をご確認ください。請求書の概要ガイドに記載されている請求書の確定を確認してください。 Invoice の last_finalization_error を調べて、エラーの原因を判別します。 Stripe Tax を使用している場合、Invoice オブジェクトの automatic_tax フィールドを確認します。 `automatic_tax[status]=requires_location_inputs` の場合、請求書を確定させることはできず、支払いを回収できません。顧客に通知し、必要な顧客の場所を収集します。 `automatic_tax[status]=failed` の場合、後でリクエストを再試行します。
`invoice.paid`	請求書の支払いに成功すると送信されます。このイベントを受け取り、サブスクリプションの `status` が `active` になると、商品へのアクセスを提供できます。
`invoice.payment_action_required`	請求書に顧客の認証を必要とする場合に送信されます。請求書でアクションが必要な場合にサブスクリプションを処理する方法をご紹介します。
`invoice.payment_failed`	請求書に対する支払いが失敗しました。PaymentIntent のステータスは `requires_action` に変わります。サブスクリプションのステータスは、サブスクリプションの最初の請求書に対して「のみ」`incomplete` のままになります。支払いが失敗した場合、以下のような処理を行います。顧客に通知します。サブスクリプションの設定を構成し、Smart Retries とその他の売上回収機能を有効にする方法をご紹介します。 PaymentIntent を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。サブスクリプションの default payment method (デフォルトの支払い方法) を更新します。
`invoice.upcoming`	サブスクリプションの更新の数日前に送信されます。何日前に送信されるかについては、ダッシュボードの次回の更新イベントに設定された数値を参照します。既存のサブスクリプションについては、日数の変更は次の請求期間から有効になります。必要に応じて、追加の請求書アイテムを加えることもできます。
`invoice.updated`	支払いが成功または失敗したときに送信されます。支払いが成功の場合には、`paid` 属性が `true` に、`status` が `paid` に設定されます。支払いが失敗の場合には、`paid` が `false` に、`status` は `open` のままになります。また、支払いの失敗は、`invoice.payment_failed` イベントもトリガーします。
`payment_intent.created`	PaymentIntent が作成されると送信されます。
`payment_intent.succeeded`	PaymentIntent が正常に支払いを完了すると送信されます。
`subscription_schedule.aborted`	サブスクリプションスケジュールが、支払いの滞納により関連するサブスクリプションが終了となったことが原因でキャンセルされた場合に送信されます。
`subscription_schedule.canceled`	サブスクリプションスケジュールがキャンセルされ、それに関連するアクティブなサブスクリプションもキャンセルされた場合に送信されます。
`subscription_schedule.completed`	サブスクリプションスケジュールのすべてのフェーズが完了した場合に送信されます。
`subscription_schedule.created`	新しいサブスクリプションスケジュールが作成された場合に送信されます。
`subscription_schedule.expiring`	サブスクリプションスケジュールが無効になる 7 日前に送信されます。
`subscription_schedule.released`	サブスクリプションスケジュールがサブスクリプションからリリースされたとき、または停止され関連付けが解除されたときに送信されます。サブスクリプションはその後も残ります。
`subscription_schedule.updated`	サブスクリプションスケジュールが更新された場合に送信されます。

Handle payment failures

イベントは、信頼性の高い方法で、サブスクリプション請求書での支払いの失敗をお客様に通知できます。支払いの失敗には、カード発行会社が最初の支払いを拒否しても、自動的に再試行を許可する可能性がある場合など、一時的なものがあります。また、顧客に対して使用可能な支払い方法がない場合など、最終的で対応が必要になるものもあります。

イベント説明

イベント	説明
`invoice.payment_failed`	請求書に対する支払いが失敗しました。PaymentIntent のステータスが `requires_payment_method` に変わり、サブスクリプションのステータスは `incomplete` に変わります。支払いが失敗した場合、以下のような処理を行います。顧客に通知します。 PaymentIntent を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。サブスクリプションのデフォルトの支払い方法を更新します。 Smart Retries を有効にすることを検討してください。

invoice.payment_failed

請求書に対する支払いが失敗しました。PaymentIntent のステータスが requires_payment_method に変わり、サブスクリプションのステータスは incomplete に変わります。支払いが失敗した場合、以下のような処理を行います。

顧客に通知します。
PaymentIntent を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。
サブスクリプションのデフォルトの支払い方法を更新します。
Smart Retries を有効にすることを検討してください。

支払い方法が必要な支払いの失敗を処理する方法の詳細については、サブスクリプション概要ガイドをご覧ください。

Handle payments that require additional action

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

イベント説明

イベント	説明
`invoice.finalization_failed`	請求書を確定できませんでした。ガイドを参照して、請求書の確定失敗を処理する方法をご確認ください。請求書の概要ガイドに記載されている請求書の確定を確認してください。 Invoice の last_finalization_error を調べて、エラーの原因を判別します。 Stripe Tax を使用している場合、Invoice オブジェクトの automatic_tax フィールドを確認します。 `automatic_tax[status]=requires_location_inputs` の場合、請求書を確定させることはできず、支払いを回収できません。顧客に通知し、必要な顧客の場所を収集します。 `automatic_tax[status]=failed` の場合、後でリクエストを再試行します。
`invoice.payment_failed`	請求書に対する支払いが失敗しました。PaymentIntent のステータスが `requires_action` に変わり、サブスクリプションのステータスは `incomplete` に変わります。支払いが失敗した場合、以下のような処理を行います。顧客に通知します。 PaymentIntent を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。サブスクリプションのデフォルトの支払い方法を更新します。 Smart Retries を有効にすることを検討してください。
`invoice.payment_action_required`	請求書に対する支払いが失敗しました。PaymentIntent のステータスが `requires_action` に変わり、サブスクリプションのステータスは `incomplete` に変わります。支払いが失敗した場合、以下のような処理を行います。顧客に通知します。 PaymentIntent を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。サブスクリプションのデフォルトの支払い方法を更新します。 Smart Retries を有効にすることを検討してください。

invoice.finalization_failed

請求書を確定できませんでした。ガイドを参照して、請求書の確定失敗を処理する方法をご確認ください。請求書の概要ガイドに記載されている請求書の確定を確認してください。

Invoice の last_finalization_error を調べて、エラーの原因を判別します。
Stripe Tax を使用している場合、Invoice オブジェクトの automatic_tax フィールドを確認します。
automatic_tax[status]=requires_location_inputs の場合、請求書を確定させることはできず、支払いを回収できません。顧客に通知し、必要な顧客の場所を収集します。
automatic_tax[status]=failed の場合、後でリクエストを再試行します。

invoice.payment_failed

請求書に対する支払いが失敗しました。PaymentIntent のステータスが requires_action に変わり、サブスクリプションのステータスは incomplete に変わります。支払いが失敗した場合、以下のような処理を行います。

顧客に通知します。
PaymentIntent を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。
サブスクリプションのデフォルトの支払い方法を更新します。
Smart Retries を有効にすることを検討してください。

invoice.payment_action_required

顧客に通知します。
PaymentIntent を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。
サブスクリプションのデフォルトの支払い方法を更新します。
Smart Retries を有効にすることを検討してください。

Track active subscriptions

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

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

サブスクリプションが更新されると、Stripe は顧客に請求し、登録されている支払い方法に自動請求するか、顧客に請求書をメール送信して、支払いを回収しようとします。Stripe はイベントの送信先を介して請求書のステータスをサイトに通知します。

お客様のサイトは invoice.paid イベントを受信します。
- 決済手段に自動的に請求すると、サイトでは、更新の数日前に、設定されているイベントの送信先への invoice.upcoming イベントを受信します。このイベントをリッスンして、次回の請求書に請求書アイテムを追加できます。collection_method=send_invoice の場合、Stripe は invoice.upcoming イベントを送信しません。
アプリケーションが、決済の対象となる顧客を見つけます。
アプリケーションはデータベースで顧客のアクセス有効期限日を将来の適切な日付 (余裕を持って 1 ～ 2 日を追加) に更新します。

Catch subscription status changes

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

一部のステータス変更には、特に注意する必要があります。

トライアルが終了し、サブスクリプションが trialing から active に移行する数日前に、customer.subscription.trial_will_end イベントを受信します。このイベントを受信したら、顧客に支払い方法の指定があり、請求可能な状態であることを確認します。必要に応じて、請求が行われることを顧客に通知します。
サブスクリプションが past_due に移行すると、顧客に直接通知し、支払い詳細を更新するように依頼します。Stripe はこのプロセスを自動化するのに役立ついくつかの機能を提供しています。売上回収についてご確認ください。
サブスクリプションが canceled または unpaid に変わると、商品へのアクセスを取り消します。

ステータス	説明
`trialing`	The subscription is currently in a trial period and you can safely provision your product for your customer. The subscription transitions automatically to `active` when a customer makes the first payment.
`active`	The subscription is in good standing and the most recent payment is successful. You can safely provision your product for your customer.
`incomplete`	The customer must make a successful payment within 23 hours to activate the subscription. Or the payment requires action, such as customer authentication. Subscriptions can also be `incomplete` if there’s a pending payment and the PaymentIntent status is `processing`.
`incomplete_expired`	The initial payment on the subscription failed and the customer didn’t make a successful payment within 23 hours of subscription creation. These subscriptions don’t bill customers. This status exists so you can track customers that failed to activate their subscriptions.
`past_due`	Payment on the latest finalized invoice either failed or wasn’t attempted. The subscription continues to create invoices. Your subscription settings determine the subscription’s next state. If the invoice is still unpaid after all attempted smart retries, you can configure the subscription to move to `canceled`, `unpaid`, or leave it as `past_due`. To move the subscription to `active`, pay the most recent invoice before its due date.
`canceled`	The subscription was canceled. During cancellation, automatic collection for all unpaid invoices is disabled (`auto_advance=false`). This is a terminal state that can’t be updated.
`unpaid`	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`	The subscription has ended its trial period without a default payment method and the trial_settings.end_behavior.missing_payment_method is set to `pause`. Invoices are no longer created for the subscription. After attaching a default payment method to the customer, you can resume the subscription.

Webhook と請求書

Register a webhook endpoint to keep track of invoice statuses. Your subscription integration depends on correctly finalizing invoices and properly handling invoice finalization failures.

自動回収を有効にすると、Stripe は自動的にインボイスを確定し、自動回収を開始します。

If Stripe fails to receive a successful response to invoice.created, we delay finalizing all invoices with automatic collection for up to 72 hours, excluding those where you have set a custom scheduled finalization time.
invoice.created への応答が正しく行われると、アカウントに設定されたすべての Webhook エンドポイントだけでなく、連結されたあらゆるプラットフォームの Webhook エンドポイントも処理されます。
同期的に決済を試行するようにサブスクリプションを更新した (初回の請求書で、および一部の更新で) 場合には、このような遅延は発生しません。
Invoice finalization failure prevents payment collection for the invoice. Make sure you listen for the invoice.finalization_failed event in your webhook endpoint.

See a complete list of invoice event types.

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

成功した請求書の確定

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

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

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

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

請求書確定の失敗

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

インボイスの確定が失敗した理由を判別するには、インボイスオブジェクトの last_finalization_error フィールドを確認してください。ここには、処理を進める方法を含む、失敗に関する詳細な情報が示されています。

If you’re using Stripe Tax, check if the automatic_tax.status field is requires_location_inputs, indicating that the address details are invalid or insufficient. If Stripe Tax can’t find a recognized customer location, we can’t finalize the invoice. Learn how to handle invoice finalization failures.

Testing

To test event destinations, choose one of these two options:

Perform actions in test mode that send legitimate events to your event destination. For example, to trigger the charge.succeeded event, you can use a test card that produces a successful charge.
Stripe CLI を使用してイベントをトリガーするか、Stripe for Visual Studio Code を使用してイベントをトリガーします。

注