サブスクリプションで Webhook を使用する
Stripe は Webhook を使用してアプリに通知を送信します。ほとんどのアクティビティーが非同期で発生する場合は特に、サブスクリプションに Webhook は重要です。
サブスクリプションでの Webhook の使用:
- アプリで Webhook エンドポイントを作成します。
- Stripe イベントを処理するロジックを追加します。サブスクリプションの場合、支払いの失敗やサブスクリプションの状態の変更などがあります (trial から active 状態への移行など)。
- Webhook エンドポイントをテストして、期待どおりに機能していることを確認します。
Webhooks に関するその他の有用な資料を以下に示します。
- 着信する Webhook の設定と使用の詳細については、ガイドをご覧ください。
- 最小限の Webhook エンドポイントを作成する方法を学べる、実践的な体験に関する Webhook クイックスタートを使用します。
サブスクリプションの Webhook イベント
Stripe は、サブスクリプションが作成または変更されるたびに、Events (イベント) をトリガーします。一部のイベントはサブスクリプションが作成されるとただちに送信され、その他のイベントは一定の請求間隔で発生します。
組み込みでイベントが適切に処理されることを確認します。たとえば、支払いが失敗すると顧客にメールを送信したり、サブスクリプションがキャンセルされると顧客のアクセスを取り消したりすることができます。
以下の表には、サブスクリプションに関連する最も一般的なイベントと、該当する場合は、それらのイベントを処理するための推奨アクションが示されています。
customer.created | 顧客の作成に成功すると送信されます。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | Sent when a customer’s active entitlements are updated. When you receive this event, you can provision or de-provision access to your product’s features. Read more about integrating with entitlements. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.created | 新規または更新サブスクリプションに対してインボイスが作成されると送信されます。Stripe で invoice.created に対する成功応答を受信できない場合、自動請求が指定されたすべてのインボイスの確定が最大 72 時間遅延します。インボイスの確定についてご確認ください。
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.finalized | インボイスの確定に成功し、支払いの準備が整うと送信されます。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.finalization_failed | インボイスを確定することができませんでした。ガイドを参照して、インボイスの確定失敗を処理する方法をご確認ください。インボイス概要ガイドのインボイスの確定に関する詳細をご確認ください。
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.paid | インボイスの支払いに成功すると送信されます。このイベントを受け取り、サブスクリプションの status が active になると、商品へのアクセスを提供できます。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice.payment_action_required | インボイスに顧客の認証が必要なときに送信されます。インボイスでアクションが必要な場合にサブスクリプションを処理する方法をご確認ください。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| インボイスに対する支払いが失敗しました。PaymentIntent のステータスは
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | サブスクリプションスケジュールが更新された場合に送信されます。 |
支払いの失敗に対処する
Webhook による通知は、信頼性の高い方法で、サブスクリプションインボイスでの支払いの失敗をお客様に通知できます。支払いの失敗には、カード発行会社が最初の支払いを拒否しても、自動的に再試行を許可する可能性がある場合など、一時的なものがあります。また、顧客に対して使用可能な決済手段がない場合など、最終的で対応が必要になるものもあります。
イベント | 説明 |
---|---|
| インボイスに対する支払いが失敗しました。PaymentIntent のステータスが
|
決済手段が必要な支払いの失敗を処理する方法の詳細については、サブスクリプション概要ガイドをご覧ください。
追加措置が必要な支払いを処理する
決済手段によっては、顧客認証のような追加手順の完了が必要になることがあります。こうしたイベントを受け取ったら、お客様のアプリから顧客に対して、必要な対応を行うように通知する必要があります。追加措置が必要なイベントを処理する方法については、サブスクリプション概要ガイドをご覧ください。
イベント | 説明 |
---|---|
invoice.finalization_failed | インボイスを確定することができませんでした。ガイドを参照して、インボイスの確定失敗を処理する方法をご確認ください。インボイス概要ガイドのインボイスの確定に関する詳細をご確認ください。
|
| インボイスに対する支払いが失敗しました。PaymentIntent のステータスが
|
| インボイスに対する支払いが失敗しました。PaymentIntent のステータスが
|
有効なサブスクリプションを追跡する
サブスクリプションでは、お客様のサイトと Stripe 間での調整が必要になります。顧客の継続支払いの成功または失敗によって、顧客が商品またはサービスの利用を継続できるかどうかが決まります。
一般的な組み込みでは、顧客がサブスクライブする際に、顧客の認証情報と、顧客のアクセス有効期限日を表すマッピングされたタイムスタンプ値をサイトに保存します。顧客がログインしたら、タイムスタンプがまだ将来の時刻であるかどうかを確認します。ログイン時にタイムスタンプが将来の時刻である場合、アカウントは有効であり、顧客は引き続きサービスにアクセスできます。
サブスクリプションが更新されると、Stripe は顧客に請求し、登録されている決済手段に自動請求するか、顧客にインボイスをメール送信して、支払いを回収しようとします。Stripe は Webhook を介してインボイスのステータスをサイトに通知します。
お客様のサイトは
invoice.paid
イベントを受信します。- 決済手段に自動的に請求すると、サイトは更新の数日前に、Webhook エンドポイントで
invoice.upcoming
イベントを受信します。このイベントをリッスンして、次回のインボイスにインボイスアイテムを追加できます。collection_method=send_invoice
の場合、Stripeはinvoice.upcoming
イベントを送信しません。
- 決済手段に自動的に請求すると、サイトは更新の数日前に、Webhook エンドポイントで
Webhook エンドポイントが、決済の対象となる顧客を見つけます。
Webhook エンドポイントはデータベースで顧客のアクセス有効期限日を将来の適切な日付 (余裕を持って 1 ~ 2 日を追加) に更新します。
サブスクリプションステータスの変化を把握する
組み込みにより、次の表で説明されているサブスクリプションステータス間での移行が適切に監視され、処理されていることを確認します。
一部のステータス変更には、特に注意する必要があります。
トライアルが終了し、サブスクリプションが
trialing
からactive
に移行する数日前に、customer.subscription.trial_will_end
イベントを受け取ります。このイベントを受け取ったら、顧客に指定された決済手段があり、請求可能な状態であることを確認します。必要に応じて、請求が行われることを顧客に通知します。サブスクリプションが
past_due
に移行すると、顧客に直接通知し、支払い詳細を更新するように依頼します。Stripe はこのプロセスを自動化するのに役立ついくつかの機能を提供しています。売上回収についてご確認ください。サブスクリプションが
canceled
またはunpaid
に代わると、商品へのアクセスを取り消します。
ステータス | 説明 |
---|---|
trialing | サブスクリプションは現在トライアル期間中であり、顧客に商品を提供しても安全です。 最初の支払いが行われると、サブスクリプションは自動的に active に移行します。 |
active | サブスクリプションは良好な状態であり、直近の支払いは正常に行われました。 顧客に商品を提供しても安全です。 |
incomplete | サブスクリプションを有効にするには、23 時間以内に支払いを成功させる必要があります。あるいは、支払いで顧客の認証などのアクションが必要です。保留中の支払いがあるときも、サブスクリプションは incomplete になる場合があります。その場合、PaymentIntent のステータスは processing です。 |
incomplete_expired | サブスクリプションの初回の支払いが失敗し、サブスクリプションの作成から 23 時間以内に成功した支払いがありませんでした。これらのサブスクリプションは顧客に請求しません。このステータスは、サブスクリプションの有効化に失敗した顧客を追跡するために存在します。 |
past_due | latest finalized invoice に対する支払いは、失敗したか、実行されていないかのどちらかです。サブスクリプションは請求書の作成を継続します。サブスクリプションの設定によって、サブスクリプションの次の状態が決まります。すべての Smart Retries が試行された後でも請求書が未払いである場合、サブスクリプションが canceled 、unpaid に移行するか、past_due のままになるように設定できます。サブスクリプションを active に移行するには、期日前に最新の請求書を支払ってください。 |
canceled | サブスクリプションはキャンセルされています。キャンセルの際に未払いのすべてのインボイスの自動回収が無効化されます (auto_advance=false )。これは、それ以上更新ができない最終的なステータスです。 |
unpaid | 最新のインボイスは支払われていませんが、サブスクリプションはそのままで保持されます。最新のインボイスは未払いステータスのままになり、インボイスの生成は続行されますが、支払いの試行は行われません。支払いはすでに試行され past_due であったときに再試行されたため、サブスクリプションが unpaid の場合、商品へのアクセスを取り消す必要があります。サブスクリプションを active に移行するには、その期日前に最新のインボイスへの支払いを行います。 |
paused | サブスクリプションは、デフォルトの決済手段を指定されずにトライアル期間が終了し、trial_settings.end_behavior.missing_payment_method は pause に設定されます。サブスクリプションに対してインボイスは作成されなくなります。デフォルトの決済手段が顧客に関連付けられた後、サブスクリプションを再開できます。 |
Webhooks およびインボイス
Webhook エンドポイントを登録して、インボイスのステータスを追跡し続けることをお勧めします。インボイスのステータスの追跡は、サブスクリプションで生成されたインボイスの場合は特に重要です。
自動回収を有効にすると、Stripe は自動的にインボイスを確定し、自動回収を開始します。
サブスクリプションの組み込みが、確実に期待通りに動作する (サブスクリプションが生成した請求書に対する支払いの受け取りの継続など) ように、請求書の確定に関連する Webhook を正しく処理する必要があります。インボイスを正常に確定し、インボイス確定の失敗を適切に処理することは、サブスクリプションの組み込みとって重要です。
Stripe で
invoice.created
への成功応答を受信できない場合、自動請求が指定されたすべての請求書の確定が最大 72 時間遅延します。invoice.created
への応答が正しく行われると、アカウントに設定されたすべての Webhook エンドポイントだけでなく、連結されたあらゆるプラットフォームの Webhook エンドポイントも処理されます。同期的に決済を試行するようにサブスクリプションを更新した (初回のインボイスで、および一部の更新で) 場合には、このような遅延は発生しません。
インボイスを確定できない場合、インボイスで支払いを回収することはできません。Webhook エンドポイントで
invoice.finalization_failed
イベントをリッスンしていることを確認します。
インボイスの確定に関連する Webhook イベント
イベント | 説明 |
---|---|
invoice.created | インボイスは正常に作成され、確定の準備が整っています。インボイスの確定の詳細については、ドキュメントをご確認ください。
|
invoice.finalized | インボイスは正常に確定され、支払いの準備が整っています。 |
invoice.finalization_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
フィールドを確認してください。ここには、処理を進める方法を含む、失敗に関する詳細な情報が示されています。
Stripe Tax を使用している場合、automatic_tax
フィールドを確認して、失敗が顧客の場所の検証に関連しているかどうかを判別します。Stripe Tax で認識された顧客の場所が見つからない場合、インボイスを確定することはできません。インボイス確定の失敗を処理する方法についてご確認ください。
テスト
Webhook をテストするには、2 つのオプションがあります。
- テスト環境でエンドポイントに正規のイベントを送信するアクションを実行します。たとえば、charge.succeeded イベントをトリガーするには、支払いを成功させるテストカードを使用できます。
- Stripe CLI を使用してイベントをトリガーするか、Stripe for Visual Studio Code を使用します。