Accounts v2 で Stripe Billing と Connect を連携させる公開プレビュー

Set up your Stripe account as a Connect platform by following the onboarding process in your Dashboard.

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

If you have an existing platform, this integration doesn’t support your connected accounts that use Accounts v1. If you want to include them, you have to recreate them, following the process explained here, then remove their old accounts.

For each connected account, use the Accounts v2 API to create an Account object with the customer and merchant configurations.

• The customer configuration allows the Account to pay your platform a subscription fee using a payment method that you attach to the Account.
• The merchant configuration makes the Account a connected account that can accept card payments from its own customers. When you assign the merchant configuration, you also define other aspects of the connected account, such as:
  • 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 
{{YOUR_API_KEY}}
" \
  -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
      }
    }
  }
}

アカウントの責任

Responsibilities define certain behaviors of connected accounts, such as how they pay Stripe fees and responsibility for negative balances. You set them when you add the merchant configuration to your connected accounts.

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.

支払いタイプ

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

To use destination charges, you must set the on_behalf_of parameter to make the connected account the settlement merchant. You must also add the recipient configuration to your connected accounts and request the stripe_transfers capability for them.

To allow the transfer of funds from your platform’s Stripe balance to the connected account’s Stripe balance, add the recipient configuration and request the stripe_balance.stripe_transfers capability. Destination charges require this capability.

Requesting stripe_balance.stripe_transfers also automatically requests the recipient configuration’s stripe_balance.payouts capability, which allows the connected account to pay out to their external bank account.

The merchant configuration automatically requests its own stripe_balance.payouts capability, which is identical to the recipient configuration’s stripe_balance.payouts capability. If the account doesn’t need any other recipient capabilities, you don’t need to add the recipient configuration.

To add the recipient configuration and request the stripe_balance.stripe_transfers capability, update the Account and set the configuration.recipient.capabilities.stripe_balance.stripe_transfers.requested parameter to true.

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

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

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

• If an Account’s dashboard is full or express, the account owner adds its external account using their Dashboard.
• 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

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

You can collect SaaS subscription fees directly from a connected account’s Stripe balance. The connected account must meet the following requirements:

• It must have both the merchant and customer configurations.
• Its merchant configuration’s card_payments capability must be active.
• Its available balance must have sufficient funds to make a full payment.

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

When you collect a payment from a connected account’s Stripe balance, the account’s available balance must have sufficient funds to make the full payment. Otherwise, the payment fails. If you plan to collect payments directly from your connected accounts’ Stripe balances, we recommend configuring your integration to manage balance-related payment failures.

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.

入金による決済の失敗を回避する別の方法として、サブスクリプションの支払いの前に手動入金に変更できます。各サブスクリプション支払いの一定期間前に、すでに連結アカウントに十分な残高がある場合は、手動入金に切り替えます。サブスクリプションの支払いが終わったら自動入金に戻します。これにより、サブスクリプションの支払いに必要な資金が自動的に入金されなくなります。

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

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

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. 支払いが成功したら、連結アカウントの通常の入金スケジュールに戻します。

Instead of retrying a failed payment from a Stripe balance, you can try using a different payment method by specifying it directly on the invoice. You can also implement a flow that allows connected accounts to update their own subscription payment methods.