連結アカウントをユーザー登録する公開プレビュー

プラットフォームは、連結アカウントから必要な情報を事前に (アップフロント) 収集するか、段階的に (インクリメンタル) 収集するかを決定する必要があります。アップフロントアカウント登録ではアカウントの 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 を含めます。アカウントリンク URL がすでにアクセスされているか、有効期限が切れているか、その他の理由で無効な場合、Stripe は連結アカウントを更新 URL にリダイレクトします。Stripe は、連結アカウントがアカウント登録フローを完了または離脱したときに、戻り URL にリダイレクトします。さらに、収集する必要がある情報に基づいて、use_case.account_onboarding.collection_options.fields に currently_due または eventually_due を渡します。この例では、事前登録を使用するように eventually_due を渡します。インクリメンタルアカウント登録の場合は、currently_due に設定します。

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

連結アカウントをアカウントリンク URL にリダイレクトする

連結アカウントを Account Link の URL にリダイレクトして、アカウント登録フローに送ります。各 Account Link の URL は、アカウント所有者の個人情報へのアクセスを許可するため、1 回しか使用できません。この 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 ホスティング登録フォームにアカウントを誘導して、確認要件を修正できるようにします。

連結アカウントがプラットフォームにリダイレクトされるすべてのケースに対応するために、アカウントリンクには refresh_url と return_url が必要です。連結アカウントに最適なアカウント登録フローを提供するには、これらを正しく実装することが重要です。

再読み込み URL

以下の場合、連結アカウントは refresh_url にリダイレクトされます。

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

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

戻り先 URL

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

この URL は状態を渡しません。連結アカウントを return_url にリダイレクトした後、アカウント登録が完了したかどうかを判断します。アカウントを取得し、requirements ハッシュで未対応の要件がないか確認します。または、Webhook エンドポイントに送信された v2.core.account[requirements].updated イベントをリッスンし、アプリケーションでアカウントの状態をキャッシュします。アカウント登録を完了していない場合は、後でアカウント登録を続行できるように、アプリケーションにメッセージを表示します。

Stripe のホスティング登録では、すでに提供した情報に対する、連結アカウントによって開始される更新もサポートされます。Webhook エンドポイントに送信された v2.core.account[requirements].updated イベントをリッスンして、アカウントが要件に対応し、情報を更新したときに通知されるようにします。

アカウントリンクを作成する際、type を account_onboarding または account_update のいずれかに設定できます。

account_onboarding のアカウントリンク

このタイプのアカウントリンクは、未対応の要件を入力するためのフォームを提供します。新しい連結アカウントをユーザー登録する場合、または既存のユーザーに新しい要件がある場合 (たとえば、連結アカウントからすでに十分な情報が提供されていたが、追加情報を必要とする新しいケイパビリティをリクエストした場合など) に使用します。このタイプのアカウントリンクにユーザーを送ると、必要な新しい情報のみが収集されます。

account_update のアカウントリンク

このタイプのアカウントリンクは、プラットフォームが要件の徴収について責任を負うアカウントに対して有効になります。account_update リンクには、アカウントオブジェクトにすでに入力されている属性が表示され、連結アカウントは以前に提供した情報を編集できます。ご使用のアプリケーションで、連結アカウントが自身で更新するためのオプション (「プロフィールの編集」や「本人確認情報の更新」など) を用意します。