連結アカウントに SaaS 利用料を請求する公開プレビュー

ダッシュボードのアカウント登録プロセスに従って、Stripe アカウントを Connect プラットフォームとして設定します。

Connect 導入ガイドでは、プラットフォームの設定オプションについて説明しています。

既存のプラットフォームがある場合、このシステムは Accounts 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 に設定します。

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-04-30.preview" \
  --json '{
    "contact_email": "furever_contact@example.com",
    "display_name": "Furever",
    "dashboard": "full",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        },
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        }
    },
    "defaults": {
        "currency": "usd",
        "responsibilities": {
            "fees_collector": "stripe",
            "losses_collector": "stripe"
        },
        "locales": [
            "en-US"
        ]
    },
    "include": [
        "configuration.customer",
        "configuration.merchant",
        "identity",
        "requirements"
    ]
  }'

レスポンスには 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 を設定します。

Responsibilities are subject to the following restrictions:

• If you set losses_collector to application, then you must also set fees_collector to application.
• If you use destination charges with an Account, we recommend that you set both losses_collector and fees_collector to application.

For more information about supported configurations, see Integration recommendations.

支払いタイプ

ベータリリースでは、連結アカウントへの支払いは、ダイレクト支払いおよびデスティネーション支払いのみがサポートされています。支払いと送金別方式は使用することができません。

デスティネーション支払いを利用するには、on_behalf_of パラメーターを設定して、連結アカウントを売上処理加盟店にする必要があります。また、recipient 設定を連結アカウントに追加し、stripe_transfers ケイパビリティをリクエストしなければなりません。

プラットフォームの Stripe 残高から連結アカウントの Stripe 残高への送金を許可するには、recipient 設定を追加して、stripe_balance.stripe_transfers ケイパビリティをリクエストします。デスティネーション支払いを利用するには、このケイパビリティが必要です。

stripe_balance.stripe_transfers をリクエストすると、recipient 設定の stripe_balance.payouts ケイパビリティも自動的にリクエストされます。これにより、連結アカウントは外部銀行口座への入金を実行できるようになります。

merchant 設定では、独自の stripe_balance.payouts ケイパビリティが自動的にリクエストされます。これは、recipient 設定の stripe_balance.payouts ケイパビリティと同じです。アカウントにその他の recipient ケイパビリティが必要ない場合は、recipient 設定を追加する必要はありません。

recipient 設定を追加して stripe_balance.stripe_transfers ケイパビリティをリクエストするには、Account を更新し、configuration.recipient.capabilities.stripe_balance.stripe_transfers.requested パラメーターを true に設定します。

curl -X POST https://api.stripe.com/v2/core/accounts/acct_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-04-30.preview" \
  --json '{
    "include": [
        "identity",
        "requirements"
    ],
    "configuration": {
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    }
  }'

連結アカウントがプラットフォームを通じて支払いを受け付けられるようにするには、連結アカウントのアカウント登録が必要です。アカウントを Stripe ホスティング登録に誘導したり、Connect 埋め込みコンポーネントを使用してブランド名の入ったフローを提供したり、貴社に合わせたカスタムのアカウント登録フローをコーディングで作成したりすることができます。Stripe ホスティング登録は最もシンプルなオプションです。埋め込みコンポーネントを使用すると、ほとんどのプロセスを自動的に処理しながら、ある程度のカスタマイズが可能になります。カスタムのアカウント登録フローはプラットフォーム側で完全に制御できますが、実装と継続的な更新が必要であるため、最も多くのリソースが必要になります。

外部口座の作成プロセスは、連結アカウントがダッシュボードへのアクセス権を持っているかどうかで内容が異なります。

• Account の dashboard が full または express の場合、アカウント所有者はダッシュボードを使用して外部アカウントを追加することができます。
• Account の dashboard が none の場合、/v1/external_accounts エンドポイントを使用して外部口座を作成できます。

curl https://api.stripe.com/v1/external_accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-04-30.preview" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "external_account[account_number]"=000123456789 \
  -d "external_account[routing_number]"=110000000 \
  -d "external_account[country]"=US \
  -d "external_account[currency]"=USD \
  -d "external_account[object]"=bank_account

連結アカウントの支払いを設定するには、ダイレクト支払いまたはデスティネーション支払いの手順を参照してください。デスティネーション支払いを使用するには、on_behalf_of パラメーターを設定する必要があります。

ダッシュボードまたは API を使用して、連結アカウントの入金設定 (スケジュール、明細書表記、遅延日数など) を構成できます。

curl https://api.stripe.com/v1/balance_settings \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-04-30.preview" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d debit_negative_balances=true \
  -d "payouts[schedule][interval]"=weekly \
  -d "payouts[schedule][weekly_anchor]"=monday

アカウントの要件は、多くの場合、金融規制当局、カードネットワーク、その他の金融機関が実施する変更によって変更される可能性があります。要件変更の Webhook 通知を設定するには、Account v2 の更新イベントをリッスンするイベントの送信先を作成します。

1. Stripe ダッシュボードで、ナビゲーションメニューのフッターにある開発者をクリックして開発者メニューを開き、Webhook を選択します。
2. + 送信先を追加をクリックします。
3. Event from セクションで、Connected accounts を選択します。
4. 詳細設定を表示を選択します。Payload style セクションで、Thin を選択します。
5. Event のフィールドに「v2」と入力して、v2 イベントタイプを検索します。連結アカウントで使用される設定タイプごとに、v2.account[requirements].updated と v2.account[configuration.configuration_type].capability_status_updated タイプを選択します。

インタラクティブな Webhook エンドポイントビルダーに従って、イベントの送信先の設定を続けます。

更新された要件を収集して更新イベントに応答するようにアプリケーションを構成します。

開発時にローカルリスナーを設定する

Stripe CLI をインストールし、ローカルリスナーを設定することで、ローカルサーバーにイベントを送信し、開発に使用することができます。

1. Stripe ダッシュボードにログインします。
2. Stripe CLI で、stripe login コマンドを入力します。ブラウザーにリダイレクトされ、アカウントの確認と認証が行われます。
3. 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

Stripe Billing を使用して連結アカウントから継続料金を回収するには、以下の手順を実行します。

1. 継続料金に対応する商品を 1 つ以上作成します。
2. アカウントを顧客として、手数料商品のサブスクリプションを作成します。
3. (オプション) カードなどの他の決済手段に付随する取引手数料を回避して、連結アカウントの Stripe 残高から直接サブスクリプション料金を回収するには、デスティネーション支払いを決済手段として設定します。

継続料金で商品を作成する

サブスクリプション料金を表す商品と料金を作成します。API またはダッシュボードを使用できます。

curl https://api.stripe.com/v1/products \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Connected account subscription fee" \
  -d "default_price_data[unit_amount]"=1000 \
  -d "default_price_data[currency]"=usd \
  -d "default_price_data[recurring][interval]"=month \
  -d "expand[]"=default_price

サブスクリプションを作成して連結アカウントに請求する

連結アカウントの Stripe 残高から SaaS サブスクリプション料金を直接回収できます。連結アカウントは以下の要件を満たしている必要があります。

• merchant 設定と customer 設定の両方が必要です。
• merchant 設定の card_payments ケイパビリティを有効にする必要があります。
• 利用可能残高には、全額を支払うのに十分な資金が必要です。

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-04-30.preview" \
  -d "payment_method_types[]"=stripe_balance \
  -d confirm=true \
  -d customer_account=acct_xxxxxxxxxxxxxx \
  -d usage=off_session \
  -d "payment_method_data[type]"=stripe_balance

{
  "id": "seti_123",
  "object": "setup_intent",
  "customer": "cus_xxxxxxxxxxxxxx",
  "customer_account": "acct_xxxxxxxxxxxxxx",
  "payment_method": "pm_xxxxxxxxxxxxxx",
  "status": "succeeded"
}

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-04-30.preview" \
  -d customer_account=acct_xxxxxxxxxxxxxx \
  -d default_payment_method=pm_xxxxxxxxxxxxxx \
  -d "items[0][price]"=price_xxxxxxxxxxxxxx \
  -d "items[0][quantity]"=1 \
  -d "payment_settings[payment_method_types][0]"=stripe_balance

連結アカウントの Stripe 残高から支払いを回収する際は、アカウントの利用可能残高に全額を支払えるだけの十分な資金がなければなりません。残高が十分でなかった場合、支払いは失敗します。連結アカウントの Stripe 残高から直接支払いを回収する場合は、残高に関連する支払いの失敗を管理するようにシステムを設定することをお勧めします。

Avoid balance payment failures

Because payments from a connected account’s Stripe balance rely on its available funds, you can avoid payment failures by taking steps to maximize your connected accounts’ balances.

連結アカウントの入金スケジュールを調整する

Coordinate your payout schedules with your subscription billing cycles. For example, if you charge subscription fees on the first day of each month, and schedule weekly payouts on Mondays, then months with more Mondays have more payouts. Those months have lower available balances than months with fewer payouts, making payment failures more likely.

Another way to avoid payment failures due to payouts is to change to manual payouts before a subscription payment. At a set time before each subscription payment, if a connected account has sufficient available funds, switch it to manual payouts so the subscription payment gets paid before the automatic payout clears the account. After the subscription payment, resume automatic payouts.

連結アカウントの最低残高を設定する

アカウントの最低残高を定義することで、自動入金によって連結アカウントの利用可能残高が一定額を下回るのを防ぐことができます。

1. ダッシュボードでアカウントを見つけます。
2. アカウントのオーバーフローメニュー () から、…のダッシュボードを表示を選択します。
3. 歯車のアイコンをクリックし、設定を選択します。
4. アカウント設定でビジネスをクリックします。
5. 外部の入金口座とスケジュール設定タブを選択します。
6. 支払い残高に最低金額を保持するをオンにして、金額を入力します。

連結アカウントごとに最低残高を手動で設定する必要があります。

Handle balance payment failures

Set up webhooks and event destinations to receive notifications about subscription payments. Identify payment failures by listening for the invoice.payment_failed event. When a payment fails:

• PaymentIntent のステータスが requires_action に変わります。
• 現在の請求書のサブスクリプションステータスは incomplete のままです。
• サブスクリプションは引き続き請求書を生成しますが、請求書は draft ステータスのままです。

If a payment from a Stripe balance fails due to insufficient available funds, you can retry it by following these steps:

1. 連結アカウントの入金スケジュールの期間を manual に設定します。
2. 次回連結アカウントに入金される支払いをリッスンしてから、アカウントの利用可能な残高を確認します。
3. 利用可能な残高がサブスクリプション料金以上の場合は、未払い請求書の決済手段を stripe_balance に設定して再試行します。それ以外の場合は、利用可能な残高が請求書の支払いに十分になるまで、支払いのリッスンを続けます。
4. 支払いが成功したら、連結アカウントの通常の入金スケジュールに戻します。

失敗した Stripe 残高での支払いを再試行する代わりに、別の決済手段を請求書で直接指定して、試すことができます。また、連結アカウントが自身のサブスクリプションの決済手段を更新できるようにするフローを実装することもできます。