サブスクリプションの仕組み

継続支払いとサブスクリプションのライフサイクルを管理します。

サブスクリプションでは、顧客は商品を利用するために継続的に支払いを行います。サブスクリプションの場合、以降も顧客に請求する必要があるため、1 回限りの購入よりも顧客について多くの情報を保持する必要があります。

Stripe では、サブスクリプション請求の管理に役立つ多くの機能を提供しています。

サブスクリプションのライフサイクル

サブスクリプションを作成および管理するプロセスは、Customers、Invoices、PaymentIntents などのコア Stripe API リソースに依存します。サブスクリプション関連リソースの一覧については、API オブジェクト定義をご覧ください。

推奨されるサブスクリプションフローは次のとおりです。

定期支払いを作成する

ダッシュボードまたは API で新しいサブスクリプションを作成できます。サブスクリプションを作成するたびに、イベントがトリガーされます。Webhook エンドポイントでこれらのイベントをリッスンし、導入で適切に処理されていることを確認します。

オプションとして、サブスクリプションの決済を必要としないトライアルを作成できます。この場合、ステータスはトライアル中です。トライアルが終了すると、サブスクリプションは有効になり、サブスクリプション顧客は請求されます。

支払い処理

サブスクリプションの payment_behavior を default_incomplete に設定して、決済の失敗や3DSなどの複雑な決済フローを処理することをお勧めします。これにより、決済が必要な場合にステータスが incomplete のサブスクリプションが作成され、その後決済情報を収集して確定してサブスクリプションを有効化できます。

payment_behavior を allow_incomplete に設定すると、Stripe は直ちに請求書の決済を徴収します。決済が失敗すると、サブスクリプションのステータスは incomplete に変わります。payment_behavior を error_if_incomplete に設定すると、決済が失敗するとサブスクリプションの作成は失敗します。

ダッシュボードで作成するサブスクリプションは、決済手段に応じて適切な決済動作がデフォルトで設定されます。

請求書を処理する

サブスクリプションを作成すると、Stripe は未払いのステータスの請求書を自動的に作成します。顧客は決済を成功させるまで約 23 時間あります。この間、サブスクリプションのステータスは未完了であり、インボイスのステータスは未払いのままです。顧客がサブスクリプションの最初の決済を行うのは、通常、オンセッション中であるため、23 時間の期間が存在します。顧客が 23 時間後にアプリケーションに戻った場合は、顧客の新しいサブスクリプションを作成します。

顧客が支払う

顧客が請求書を支払うと、サブスクリプションは有効に、請求書は決済済みに更新されます。顧客が決済を行わないと、サブスクリプションは incomplete_expired に更新され、請求書は無効になります。

請求書が決済されたかどうかを確認する場合:

Webhookエンドポイントまたはその他のタイプのイベント送信先を設定し、invoice.paidイベントをリッスンします。
サブスクリプションオブジェクトを手動で確認し、subscription.status=active を探します。自動請求または顧客による手動での支払いによって請求書への支払いが行われると、status は active になります。

詳細については、サブスクリプションステータスと決済ステータスをご覧ください。

商品へのアクセスを提供する

顧客のサブスクリプションを作成すると、その製品に関連付けられた各機能に対して有効なエンタイトルメントが作成されます。顧客がサービスにアクセスすると、その有効なエンタイトルメントを使用して、サブスクリプションに含まれる機能へのアクセスを顧客に許可します。

または、Webhook イベントでアクティブサブスクリプションを追跡を使用し、そのアクティビティに基づいて顧客に商品をプロビジョニングすることもできます。

サブスクリプションを更新する

既存のサブスクリプションは、キャンセルして再作成することなく、必要に応じて変更できます。最も重要な変更には、サブスクリプション価格のアップグレードやダウングレード、有効なサブスクリプションの決済回収の一時停止などがあります。

Webhook エンドポイントでサブスクリプションイベントをリッスンして、サブスクリプションの変更を確認できます。たとえば、決済が失敗した場合に顧客にメールを送信したり、サブスクリプションをキャンセルしたときに顧客のアクセスを取り消すことができます。

Stripe Checkout の組み込みでは、セッションのサブスクリプションが不完全な場合、サブスクリプションまたはその請求書を更新できません。checkout.session.completed イベントをリッスンして、セッションの完了後に更新を行うことができます。セッションのサブスクリプションをキャンセルしたり、サブスクリプションの請求書を無効にしたり、請求書を回収不能としてマークしたりする場合は、代わりにセッションを期限切れにすることもできます。

未払いのサブスクリプションを処理する

未払いの請求書があるサブスクリプションについては、その未払い請求書は引き続き未払いのまま表示されますが、さらなる決済の試行は停止されます。サブスクリプションの請求書は、引き続き各請求期間ごとに生成され、ドラフトステータスで保存されます。サブスクリプションは次の手順で有効にできます。

必要に応じて新しい支払い情報を収集します。
請求書の下書きで auto_advance を true に設定して、自動回収を有効にします。
未払い請求書の確定と支払いを行います。無効になっていない最新の請求書を期日前に支払うと、サブスクリプションのステータスが active に更新されます。

回収不能とマークされた請求書は、基になるサブスクリプションを有効に保ちます。Stripe はサブスクリプションステータスを判断する際に無効化された請求書を無視し、代わりに無効化されていない最新の請求書を使用します。

未払いのサブスクリプションのステータスは、ダッシュボードの決済失敗設定によって異なります。

サブスクリプションをキャンセルする

サブスクリプションは、請求期間の終了時や設定した請求期間回数の経過後など、いつでもキャンセルできます。

デフォルトでは、サブスクリプションをキャンセルすると、そのサブスクリプションの新しい請求書の作成が無効になり、そのサブスクリプションのすべての未払いの請求書の自動回収が停止されます。また、サブスクリプションが削除されると、サブスクリプションまたはそのメタデータは更新できなくなります。顧客が再びサブスクリプションを希望する場合、顧客から新しい決済情報を収集して新しいサブスクリプションを作成する必要があります。

サブスクリプションステータス

サブスクリプションには次のステータスがあります。サブスクリプションに対して実行できるアクションは、ステータスによって異なります。

ステータス	説明
`trialing`	サブスクリプションは現在トライアル期間中であり、顧客にプロダクトを支障なく提供できます。初回の支払いが行われると、サブスクリプションは自動的に `active` に移行します。
`active`	サブスクリプションは良好な状態です。`past_due` のサブスクリプションの場合、関連する請求書への最新の支払いまたは回収不能という判定によって、サブスクリプションは `active` に移行します。`active` は、サブスクリプションに関連するすべての未払いの請求書が支払われたことを示しているわけではないことに注意してください。その他の未払いの請求書は、支払い対象として残すか、回収不能と判定するか、必要に応じて無効化することができます。
`incomplete`	サブスクリプションを有効にするには、顧客が 23 時間以内に支払いを成功させる必要があります。または、支払いで顧客認証などの対応が必要です。保留中の支払いがあり、PaymentIntent のステータスが `processing` の場合も、サブスクリプションが `incomplete` になることがあります。
`incomplete_expired`	サブスクリプションの初回の支払いが失敗し、サブスクリプションの作成から 23 時間以内に支払いが成功しませんでした。これらのサブスクリプションは顧客に請求されません。このステータスは、サブスクリプションの有効化に失敗した顧客を追跡するために存在します。
`past_due`	最新の確定済みの請求書の決済は、失敗したか、試行されていません。サブスクリプションは、引き続き請求書を作成します。ダッシュボードのサブスクリプション設定によって、サブスクリプションの次のステータスが決まります。smart retries を試行しても請求書が未払いの場合は、サブスクリプションを`キャンセル済み`、`未払い`、または `past_due` のままにするように設定できます。サブスクリプションを再度有効にするには、顧客に最新の請求書を決済してもらいます。サブスクリプションのステータスは、決済が最新の請求書より前に行われたか、最新の請求書の期日を過ぎたかに関係なく、`有効`になります。
`canceled`	サブスクリプションがキャンセルされました。キャンセル時に未払いのすべての請求書の自動回収が無効化されます (`auto_advance=false`)。これは、更新できない最終的なステータスです。
`unpaid`	最新の請求書は支払われていませんが、サブスクリプションはそのまま保持されます。最新の請求書は未処理のままになり、請求書は引き続き生成されますが、支払いの試行は行われません。サブスクリプションが `unpaid` の場合は、`past_due` の時点で支払いの試行と再試行がすでに行われているため、プロダクトへのアクセスを取り消します。サブスクリプションのステータスを `active` にするには、期日前に最新の請求書を支払う必要があります。
`paused`	デフォルトの決済手段が設定されずにサブスクリプションのトライアル期間が終了し、trial_settings.end_behavior.missing_payment_method が `pause` に設定されています。サブスクリプションの請求書は今後作成されなくなります。デフォルトの決済手段を顧客に関連付けた後、サブスクリプションを再開できます。

決済ステータス

PaymentIntent は、すべての決済のライフサイクルを追跡します。サブスクリプションの決済期日になると、Stripe は請求書と PaymentIntent を生成します。PaymentIntent ID は請求書に関連付けられ、請求書オブジェクトとサブスクリプションオブジェクトからアクセスできます。

PaymentIntent のステータスは、請求書とサブスクリプションのステータスに影響を与えます。決済のさまざまな結果が、さまざまなステータスにどのようにマッピングされるかを以下に示します。

支払い結果	PaymentIntent ステータス	請求書のステータス	サブスクリプションのステータス
成功	`succeeded`	`paid`	`active`
カードエラーによる失敗	`requires_payment_method`	`open`	`incomplete`
認証による失敗	`requires_action`	`open`	`incomplete`

注

ACH 口座振替などの非同期決済手段は、サブスクリプションのステータス変更を即時決済手段とは異なる方法で処理します。非同期決済手段を用いる際には、サブスクリプションは作成後に active ステータスに直接移行し、他の決済タイプに通常見られる未完了ステータスを回避します。非同期の決済が後で失敗した場合、関連付けられた請求書は無効になりますが、サブスクリプションは active ステータスのままになります。しかし、この動作は即時決済手段とは対照的です。即時決済手段では、決済の失敗によって未完了または past_due ステータスになることがよくあります。この区別に注意し、サブスクリプションのステータス、アクセスコントロール、決済再試行メカニズムを管理するための適切なロジックを実装してください。

以降のセクションでは、これらのステータスと、各ステータスに対するアクションを説明します。

支払いの成功

顧客の決済が成功した場合:

PaymentIntent のステータスは succeeded に移行します。
サブスクリプションのステータスは active です。
請求書のステータスは支払い済みです。
設定済みの Webhook エンドポイントに Stripe が invoice.paid イベントを送信します。

処理期間が長い決済手段では、サブスクリプションは直ちに有効になります。このような場合、決済が成功するまで、PaymentIntent のステータスは 有効なサブスクリプションに対して処理中である可能性があります。

サブスクリプションが有効になったので、商品へのアクセスを提供します。

支払い方法が必要

支払い拒否などのカードエラーが原因で決済が失敗した場合:

PaymentIntent のステータスは requires_payment_method です。
サブスクリプションのステータスは未完了です。
請求書のステータスはオープンです。

これらのシナリオを処理するには、以下のステップに従います。

顧客に通知します。
新しい決済情報を徴収し、PaymentIntent を確定します。
サブスクリプションの default payment method (デフォルトの支払い方法) を更新します。
Stripe は Smart Retries を使用するか、カスタムリトライルールに基づいて決済を再試行します。
invoice.payment_failed イベントを使用して、サブスクリプション決済失敗イベントを監視し、更新を再試行します。請求書の決済試行後、その next_payment_attempt 値はダッシュボードの現在のサブスクリプション設定を使用して設定されます。

サブスクリプションの支払い失敗を処理する方法は以下のとおりです。

アクションが必要

決済手段によっては、決済プロセスを完了するために 3D セキュア (3DS) による顧客認証が必要です。3DS は認証プロセスを完了します。決済手段で認証が必要かどうかは、Radar ルールとカード発行会社によって異なります。

顧客が決済を認証する必要があるために決済が失敗した場合:

PaymentIntent のステータスは requires_action です。
サブスクリプションのステータスは未完了です。
請求書のステータスはオープンです。