連結アカウントに SaaS 利用料を請求する公開プレビュー
Billing を使用して、SaaS 利用料のサブスクリプションを連結アカウントに直接請求します。
このガイドでは、Accounts v2 を使用して Billing と Connect を SaaS プラットフォームに連携させ、サブスクリプション料金を連結アカウントに直接請求できるようにする方法をご紹介します。
Connect プラットフォームの Accounts v2 はダッシュボードから有効にできます。
テスト環境
この連携を試すには、サンドボックスを使用する必要があります。テスト環境は使用できません。
プラットフォームのアカウントを Connect に登録する
ダッシュボードのアカウント登録プロセスに従って、Stripe アカウントを Connect プラットフォームとして設定します。
Connect 導入ガイドでは、プラットフォームの設定オプションについて説明しています。
既存のプラットフォームがある場合、このシステムは Accounts v1 を使用する連結アカウントをサポートしません。これらを含める場合、ここで説明する手順に従ってアカウントを再作成した後、古いアカウントを削除する必要があります。
Accounts v2 API を使用して連結アカウントを作成する
注
この実装では、API v2 の Account (アカウント)、Event (イベント)、EventDestination (イベントの送信先)、Person (個人) のみを使用します。他のオブジェクトはすべて API v1 に属するものです。
Accounts v2 API を使用して、連結アカウントごとに customer
設定と merchant
設定を持った Account
オブジェクトを作成します。
customer
設定を通じてAccount
は、Account
に関連付けられた決済手段を使用して、プラットフォームにサブスクリプション料金を支払うことができます。merchant
設定により、Account
を顧客からカード支払いを受け付けられる連結アカウントにすることができます。merchant
設定を割り当てる際は、以下の連結アカウントの機能も定義する必要があります。- configuration.merchant.capabilities.card_payments.requested を true に設定して、カード決済を受け付ける機能をリクエストします。
- dashboard を設定して、Stripe ダッシュボードへのアクセスを指定します。次の例では、
dashboard
をfull
に設定しています。これは、Account
が完全な Stripe ダッシュボードにアクセスできることを意味します。 Account
から手数料を徴収する責任者を指定するには、defaults.responsibilities.fees_collector をstripe
またはapplication
に設定します。Account
のマイナス残高に対する責任者を指定するには、defaults.responsibilities.losses_collector をstripe
またはapplication
に設定します。
include を使用してレスポンスにオブジェクトを読み込む
API v2 で Account
を作成、取得、更新する際、include パラメーターで指定した場合にのみ、特定のプロパティがレスポンスに入力されます。プロパティを指定しなかった場合は、実際の値に関係なく、レスポンスに null として表示されます。
レスポンスには ID が含まれており、システム全体で Account
を参照する場合はこれを使用します。
{ "id": "acct_xxxxxxxxxxxxxxxx", "object": "v2.core.account", "applied_configurations": [ "customer", "merchant" ], "configuration": { "customer": { "automatic_indirect_tax": { "exempt": "none", "ip_address": null, "location": null, "location-source": "identity_address" }, "billing": { ... }, "capabilities": { "automatic_indirect_tax": { "requested": true, "status": "restricted", "status_details": [ { "code": "requirements_past_due", "resolution": "provide_info" } ] } }, "shipping": ..., "test_clock": ... }, "merchant": { "bacs_debit_payments": null, "branding": { ... }, "capabilities": { ... "card_payments": { "requested": true, "status": "restricted", "status_details": [ { "code": "requirements_past_due", "resolution": "provide_info" } ] }, "stripe_balance": { "payouts": { "requested": true, "status": "restricted", "status_details": [ { "code": "requirements_past_due", "resolution": "provide_info" } ] } }, ... }, "card_payments": { "decline_on": { "avs_failure": false, "cvc_failure": false } }, "mcc": null, ... "statement_descriptor": { ... }, "support": { "address": { ... }, ... } }, "recipient": null }, "contact_email": "furever_contact@example.com", "created": "2025-03-04T02:23:20.000Z", "dashboard": "full", "identity": { "attestations": { ... }, "terms_of_service": { "account": null }, "business_details": { ... "registered_name": "Furever", ... }, "country": "US", "entity_type": "company", "individual": null }, "defaults": null, "display_name": "Furever", "metadata": {}, "requirements": { "collector": "stripe", "entries": [ { "awaiting_action_from": "user", "description": "representative.surname", "errors": [], "impact": { "restricts_capabilities": [ { "capability": "card_payments", "configuration": "merchant", "deadline": { "status": "past_due" } }, { "capability": "stripe_balance.payouts", "configuration": "merchant", "deadline": { "status": "past_due" } } ] }, "minimum_deadline": { "status": "past_due" }, "reference": null, "requested_reasons": [ { "code": "routine_onboarding" } ] } ], "summary": { "minimum_deadline": { "status": "past_due", "time": null } } } }
アカウントの責任
Stripe 手数料の支払い方法やマイナス残高に対する責任など、連結アカウントの一部の動作を責任によって定義できます。この責任は、連結アカウントに merchant
設定を追加するときに設定します。
Accounts
が連結アカウントとして支払いを回収できるようにするには、次の responsibilities
を設定します。
プロパティ | 説明 | 値 |
---|---|---|
defaults.responsibilities.fees_collector | Stripe が連結アカウントのダイレクト支払いに対して、支払い手数料を徴収する方法を定義します (デスティネーション支払いまたは支払いと送金別方式の場合、Stripe は常にプラットフォームから手数料を徴収します)。 |
|
defaults.responsibilities.losses_collector | 連結アカウントで発生したマイナス残高に対する責任を割り当てます。 |
|
責任には次の制限が適用されます。
losses_
をcollector application
に設定した場合は、fees_
もcollector application
に設定する必要があります。- アカウントでデスティネーション支払いを使用する場合には、
losses_
とcollector fees_
をcollector application
に設定することをお勧めします。
サポートされている設定について、詳細はシステムの推奨事項をご覧ください。
支払いタイプ
ベータリリースでは、連結アカウントへの支払いは、ダイレクト支払いおよびデスティネーション支払いのみがサポートされています。支払いと送金別方式は使用することができません。
デスティネーション支払いを利用するには、on_behalf_of パラメーターを設定して、連結アカウントを売上処理加盟店にする必要があります。また、recipient
設定を連結アカウントに追加し、stripe_
ケイパビリティをリクエストしなければなりません。
受信者設定を連結アカウントに追加する
プラットフォームの Stripe 残高から連結アカウントの Stripe 残高への送金を許可するには、recipient
設定を追加して、stripe_
ケイパビリティをリクエストします。デスティネーション支払いを利用するには、このケイパビリティが必要です。
stripe_
をリクエストすると、recipient
設定の stripe_
ケイパビリティも自動的にリクエストされます。これにより、連結アカウントは外部銀行口座への入金を実行できるようになります。
merchant
設定では、独自の stripe_
ケイパビリティが自動的にリクエストされます。これは、recipient
設定の stripe_
ケイパビリティと同じです。アカウントにその他の recipient
ケイパビリティが必要ない場合は、recipient
設定を追加する必要はありません。
注
ベータリリースでは、海外入金はサポートされていません。
recipient
設定を追加して stripe_
ケイパビリティをリクエストするには、Account
を更新し、configuration.recipient.capabilities.stripe_balance.stripe_transfers.requested パラメーターを true に設定します。
連結アカウントのアカウントを登録する
連結アカウントがプラットフォームを通じて支払いを受け付けられるようにするには、連結アカウントのアカウント登録が必要です。アカウントを Stripe ホスティング登録に誘導したり、Connect 埋め込みコンポーネントを使用してブランド名の入ったフローを提供したり、貴社に合わせたカスタムのアカウント登録フローをコーディングで作成したりすることができます。Stripe ホスティング登録は最もシンプルなオプションです。埋め込みコンポーネントを使用すると、ほとんどのプロセスを自動的に処理しながら、ある程度のカスタマイズが可能になります。カスタムのアカウント登録フローはプラットフォーム側で完全に制御できますが、実装と継続的な更新が必要であるため、最も多くのリソースが必要になります。
連結アカウントの外部口座の作成
外部口座の作成プロセスは、連結アカウントがダッシュボードへのアクセス権を持っているかどうかで内容が異なります。
Account
のdashboard
がfull
またはexpress
の場合、アカウント所有者はダッシュボードを使用して外部アカウントを追加することができます。Account
のdashboard
がnone
の場合、/v1/external_accounts エンドポイントを使用して外部口座を作成できます。
連結アカウントの支払いを設定する
連結アカウントの支払いを設定するには、ダイレクト支払いまたはデスティネーション支払いの手順を参照してください。デスティネーション支払いを使用するには、on_behalf_of パラメーターを設定する必要があります。
連結アカウントの入金を設定する
ダッシュボードまたは API を使用して、連結アカウントの入金設定 (スケジュール、明細書表記、遅延日数など) を構成できます。
連結アカウントの要件変更をリッスンする
アカウントの要件は、多くの場合、金融規制当局、カードネットワーク、その他の金融機関が実施する変更によって変更される可能性があります。要件変更の Webhook 通知を設定するには、Account v2 の更新イベントをリッスンするイベントの送信先を作成します。
- Stripe ダッシュボードで、ナビゲーションメニューのフッターにある開発者をクリックして開発者メニューを開き、Webhook を選択します。
- + 送信先を追加をクリックします。
- Event from セクションで、Connected accounts を選択します。
- 詳細設定を表示を選択します。Payload style セクションで、Thin を選択します。
- Event のフィールドに「v2」と入力して、v2 イベントタイプを検索します。連結アカウントで使用される設定タイプごとに、v2.account[requirements].updated と v2.account[configuration.configuration_type].capability_status_updated タイプを選択します。
インタラクティブな Webhook エンドポイントビルダーに従って、イベントの送信先の設定を続けます。
更新された要件を収集して更新イベントに応答するようにアプリケーションを構成します。
開発時にローカルリスナーを設定する
Stripe CLI をインストールし、ローカルリスナーを設定することで、ローカルサーバーにイベントを送信し、開発に使用することができます。
- Stripe ダッシュボードにログインします。
- Stripe CLI で、
stripe login
コマンドを入力します。ブラウザーにリダイレクトされ、アカウントの確認と認証が行われます。 - CLI に戻り、次のコマンドを実行します。プラットフォームと連結アカウントで利用可能なすべての V2 イベントをリッスンし、http://localhost:4242 に転送します。
stripe listen --thin-events 'v2.core.account[requirements].updated,v2.core.account[configuration.recipient].capability_status_updated,v2.core.account[configuration.merchant].capability_status_updated,v2.core.account[configuration.customer].capability_status_updated' --forward-thin-to http://localhost:4242
Billing を連携させて継続料金を回収する
Stripe Billing を使用して連結アカウントから継続料金を回収するには、以下の手順を実行します。
- 継続料金に対応する商品を 1 つ以上作成します。
- アカウントを顧客として、手数料商品のサブスクリプションを作成します。
- (オプション) カードなどの他の決済手段に付随する取引手数料を回避して、連結アカウントの Stripe 残高から直接サブスクリプション料金を回収するには、デスティネーション支払いを決済手段として設定します。
注
連結アカウントは、支払いを行うのに十分な利用可能残高がある場合にのみ、Stripe 残高を使用して支払うことができます。残高支払いの失敗回を避するための推奨事項をこの手順の後半で説明しています。
継続料金で商品を作成する 
サブスクリプション料金を表す商品と料金を作成します。API またはダッシュボードを使用できます。
サブスクリプションを作成して連結アカウントに請求する 
連結アカウントの Stripe 残高から SaaS サブスクリプション料金を直接回収できます。連結アカウントは以下の要件を満たしている必要があります。
merchant
設定とcustomer
設定の両方が必要です。merchant
設定のcard_
ケイパビリティを有効にする必要があります。payments - 利用可能残高には、全額を支払うのに十分な資金が必要です。
Stripe 残高の支払い失敗を処理するようシステムを設定する
連結アカウントの Stripe 残高から支払いを回収する際は、アカウントの利用可能残高に全額を支払えるだけの十分な資金がなければなりません。残高が十分でなかった場合、支払いは失敗します。連結アカウントの Stripe 残高から直接支払いを回収する場合は、残高に関連する支払いの失敗を管理するようにシステムを設定することをお勧めします。
残高支払いの失敗を回避する
連結アカウントの Stripe 残高での支払いは、利用可能な資金に依存するため、連結アカウントの残高を最大化する手順を実行することで、支払いの失敗を回避できます。
連結アカウントの入金スケジュールを調整する
入金スケジュールをサブスクリプションの請求サイクルに合わせて調整します。たとえば、毎月 1 日にサブスクリプション料金を請求し、毎週月曜日に入金をスケジュール設定する場合、月曜日が多い月は入金額が多くなります。これらの月は、入金の少ない月よりも利用可能な残高が少なくなり、支払いが失敗する可能性が高くなります。
入金による決済の失敗を回避する別の方法として、サブスクリプションの決済前に手動入金に変更できます。各サブスクリプション決済の一定期間前に、連結アカウントに十分な残高がある場合は手動入金に切り替えて、自動入金によってアカウントが清算される前にサブスクリプションの決済が行われるようにします。サブスクリプションの決済後に、自動入金を再開します。
連結アカウントの最低残高を設定する
アカウントの最低残高を定義することで、自動入金によって連結アカウントの利用可能残高が一定額を下回るのを防ぐことができます。
- ダッシュボードでアカウントを見つけます。
- アカウントのオーバーフローメニュー () から、…のダッシュボードを表示を選択します。
- 歯車のアイコンをクリックし、設定を選択します。
- アカウント設定でビジネスをクリックします。
- 外部の入金口座とスケジュール設定タブを選択します。
- 支払い残高に最低金額を保持するをオンにして、金額を入力します。
連結アカウントごとに最低残高を手動で設定する必要があります。
残高支払いの失敗に対応する
Webhook とイベントの送信先を設定して、サブスクリプションの支払いに関する通知を受信します。invoice.
イベントをリッスンして、支払いの失敗を特定します。支払いに失敗したときは、以下のようになります。
- PaymentIntent のステータスが
requires_
に変わります。action - 現在の請求書のサブスクリプションステータスは
incomplete
のままです。 - サブスクリプションは引き続き請求書を生成しますが、請求書は
draft
ステータスのままです。
注
Stripe 残高での支払いは、Smart Retries に対応していません。
残高不足が原因で、Stripe 残高での支払いに失敗した場合は、以下の手順で再試行できます。
- 連結アカウントの入金スケジュールの期間を
manual
に設定します。 - 次回連結アカウントに入金される支払いをリッスンしてから、アカウントの利用可能な残高を確認します。
- 利用可能な残高がサブスクリプション料金以上の場合は、未払い請求書の決済手段を
stripe_
に設定して再試行します。それ以外の場合は、利用可能な残高が請求書の支払いに十分になるまで、支払いのリッスンを続けます。balance - 支払いが成功したら、連結アカウントの通常の入金スケジュールに戻します。
失敗した Stripe 残高での支払いを再試行する代わりに、別の決済手段を請求書で直接指定して、試すことができます。また、連結アカウントが自身のサブスクリプションの決済手段を更新できるようにするフローを実装することもできます。
プレビューに関する考慮事項
Accounts v2 では、支払いを直接回収するプラットフォーム上のビジネスごとに、設定可能な 1 つのアカウントを使用できます。プレビュー版リリースは、Treasury、Issuing、プレビュー段階の決済手段には対応していません。Accounts v1 では、Treasury、Issuing、プレビュー段階の決済手段を引き続き使用できます。
Connect プラットフォームの Accounts v2 はダッシュボードから有効にします。