連結アカウントをユーザー登録する

プラットフォームは、連結アカウントから必要な情報を事前に (アップフロント) 収集するか、段階的に (インクリメンタル) 収集するかを決定する必要があります。アップフロントアカウント登録ではアカウントの eventually_due 要件を収集しますが、インクリメンタルアカウント登録では currently_due 要件のみを収集します。

アップフロントとインクリメンタルのどちらのアカウント登録を使用するかを決定するには、連結アカウントの所在地とケイパビリティに関する要件を確認してください。Stripe は連結アカウントへの影響を最小限に抑えるように努めていますが、時間の経過とともに要件が変化する可能性があります。

連結アカウントが要件回収の責任を負う場合、collection_options パラメーターを使用して将来の要件の動作をカスタマイズできます。アカウントの将来の要件を徴収するには、collection_options.future_requirements をinclude (含めるように) 設定します。

連結アカウント ID を使用して Account Link を作成し、use_case.account_onboarding.refresh_url と use_case.account_onboarding.return_url を含めます。

Stripe は、Account Link URL が既にアクセスされている場合、有効期限が切れている場合、またはその他の理由で無効になっている場合に、連結アカウントを更新された URL にリダイレクトします。ユーザー登録フローを完了または終了すると、Stripe はリターン URL にリダイレクトします。

さらに、情報を一度にすべて収集するか段階的に収集するかに応じて、use_case.account_onboarding.collection_options.fields に eventually_due か currently_due のいずれかを指定します。この例では eventually_due を指定して、currently_due と eventually_due の両方の要件を最初にまとめて収集する方式を使用しています。段階的なオンボーディングを行う場合は、currently_due を指定し、currently_due の要件のみを最初に収集します。

curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-09-30.preview" \
  --json '{
    "account": 
"{{CONNECTED_ACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'

連結アカウントにユーザー登録フローを送信する

連結アカウントをユーザー登録フローに誘導するには、Account Link の URL を提供してください。各 Account Link URL は一度しか使用できません。これは、アカウント所有者の個人情報へのアクセス権が付与されるためです。

アカウント要件に対する変更をリッスンするようにシステムを設定します。テストトリガーカードを使用して、新しい要件への対応 (および支払いと入金を無効にする方法) をテストできます。

連結アカウントに currently_due または eventually_due の要件がある場合、アカウント登録フローに送り返します。アカウント登録インターフェイスで収集が必要な情報が認識されるため、具体的な要件を特定する必要はありません。たとえば、タイプミスによってアカウント所有者の本人確認ができない場合、アカウント登録で本人確認書類のアップロードが求められます。

Stripe は、連結アカウントに影響する今後の要件の更新についてお知らせします。requested_reasons.code が future_requirements のアカウントの要件を確認することで、この情報を事前に収集できます。

Stripe が要件の収集を担当する連結アカウントの場合、アカウントリンクまたはアカウントセッションの作成後に本人確認情報の更新の受信を停止します。

アカウントは、本人確認情報を identity ハッシュに保存します。

確認エラーを処理する

v2.core.account[requirements].updated イベントをリッスンします。期限が到来したときに、アカウントで minimum_deadline.statusの currently_due 要件が含まれている場合、対応する機能は無効になり、それらのステータスは past_due になります。

Stripe ホスティング登録フォームにアカウントを誘導して、確認要件を修正できるようにします。

Connect アカウント登録では、ユーザーがプラットフォームにリダイレクトされるすべてのケースを処理するために、return_url と refresh_url の両方を渡す必要があります。ユーザーが快適に操作できるようにするには、これらを正しく実装することが重要です。

戻り URL

ユーザーがユーザー登録フローを完了するか、フローの任意の時点で 保存して後で処理 をクリックすると、Stripe は連結アカウントを return_url にリダイレクトします。これは、すべての情報が収集されたことを意味するものでも、アカウントの要件がすべて満たされたことを意味するものでもありません。ユーザーがフローに正常に入り、そこから正常に出たことのみを意味します。

この URL には状態情報は渡されません。連結アカウントを return_url にリダイレクトした後、次のいずれかの方法でアカウントがオンボーディングを完了したかを確認します。

• アカウントを取得し、requirements ハッシュで未対応の要件を確認します。
• アプリケーション内でアカウントのステータスをキャッシュし、v2.core.account[requirements].updated イベントを監視して最新の状態に保ちます。

ユーザー登録が不完全な場合は、アカウントが後でユーザー登録作業を続行できるようにアプリケーションでプロンプトを表示します。

URL を更新する

Stripe は次の場合、アカウントユーザーを refresh_url にリダイレクトします。

• リンクの有効期限切れ (リンク作成後、数分が経過)。
• ユーザーがすでに URL にアクセスしている (ユーザーがページを更新したか、ブラウザーで戻るボタンまたは進むボタンをクリックした)。
• プラットフォームがアカウントにアクセスできなくなった。
• リンクが、URL にアクセスしてプレビューを試みる、メッセージングクライアントなどのサードパーティー申し込みに共有されました。多くのクライアントが自動的にリンクにアクセスすることにより、アカウントリンクが期限切れになります。
• アカウントが拒否された。

refresh_url を設定して、サーバー上のメソッドを呼び出し、同じパラメータで新しい Account Link を作成するようにします。その後、連結アカウントを新しい Account Link URL にリダイレクトしてください。

return_url にリダイレクトされたアカウントユーザーは、ユーザー登録をまだ完了していない場合があります。/v2/core/accounts エンドポイントを使用して Account を取得し、configuration.recipient.capabilities.stripe_balance.stripe_transfers.status が active になっているかを確認してください。もしステータスが active でなく、かつ configuration.recipient.capabilities.stripe_balance.stripe_transfers.status_details.code が requirements_past_due であれば、ユーザーが新しいアカウントリンクを通じてユーザー登録を続行できるように、UI に案内を表示してください。他のコードの場合も、必要に応じて適切に処理してください。

Stripe がホストするユーザー登録では、連結アカウント自身がすでに提供した情報を更新することもサポートしています。アカウントが必要な要件を完了したときに通知を受け取るには、Webhook エンドポイントで送信される v2.core.account[requirements].updated イベントを監視してください。

Account Link を作成する際は、type を account_onboarding に設定してください。このタイプの Account Link では、未完了の要件を入力するためのフォームが提供されます。新しい連結アカウントをオンボーディングする場合、または既存アカウントに新しい要件 (例えば追加情報が必要な新しい機能をリクエストした場合) が発生した場合に使用します。