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

マーケットプレイスへの連結アカウントのユーザー登録。

連結アカウントを [作成して事前入力したら](https://docs.stripe.com/connect/marketplace/tasks/create.md)、[Account Link](https://docs.stripe.com/api/v2/core/account-links.md) を作成してユーザーに送信します。これにより、ユーザーは登録プロセスを完了できます。アカウントリンクは 1 回だけ使用できる URL で、そこから連結アカウントは Connect アカウント登録フローにアクセスできます。

あるいは、[embedded components](https://docs.stripe.com/connect/get-started-connect-embedded-components.md) や [API](https://docs.stripe.com/connect/api-onboarding.md) を使って、独自のユーザー登録フローを構築することもできます。コンプライアンスや保守を簡素化するためには、Account Links を使用するか、埋め込みコンポーネントを使って独自フローを作成することをおすすめします。このガイドでは Account Links を使用します。

Connect アカウント登録フローでは、貴社が [事前入力](https://docs.stripe.com/connect/marketplace/tasks/create.md#prefill-account-information) した情報については、連結アカウントに入力を求めません。ただし、連結アカウントが [Connect 利用規約](https://docs.stripe.com/connect/service-agreement-types.md) に同意する前に、事前入力の情報を確認するように求めます。

> Stripe のホスティング登録は、ウェブブラウザーにのみ対応しています。モバイルまたはデスクトップアプリケーション内の埋め込みウェブビューでは使用できません。

## すべての情報を事前に収集するかどうかを決定する

プラットフォームは、連結アカウントから必要な情報を事前に (*アップフロント* (Upfront onboarding is a type of onboarding where you collect all required verification information from your users at sign-up)) 収集するか、段階的に (*インクリメンタル* (Incremental onboarding is a type of onboarding where you gradually collect required verification information from your users. You collect a minimum amount of information at sign-up, and you collect more information as the connected account earns more revenue)) 収集するかを決定する必要があります。アップフロントアカウント登録ではアカウントの `eventually_due` 要件を収集しますが、インクリメンタルアカウント登録では `currently_due` 要件のみを収集します。

| アカウント登録のタイプ  | メリット                                                                                                            |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
| **アップフロント**  | - 通常、すべての情報に対して 1 回のみのリクエストが必要
  - 期限に間に合わなかったために入金や処理に問題が生じる可能性を回避できる
  - アカウントが情報提供を拒否した場合の潜在的なリスクを、早期に可視化できる |
| **インクリメンタル** | - アカウントは多くの情報を提供する必要がないため、素早くアカウント登録できる                                                                         |

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

お客様が要件収集の責任を負う場合、`collection_options` パラメーターを使用して[将来の要件](https://docs.stripe.com/connect/handle-verification-updates.md)の動作をカスタマイズできます。アカウントの将来の要件を収集するには、[collection_options.future_requirements](https://docs.stripe.com/api/v2/core/account-links/create.md#create_account_links-collection_options-future_requirements) を `include` (含めるように) 設定します。

### 追加の公開情報を収集

Stripe は各連結アカウントに必要な公開情報を収集します。オンボーディング時に収集する追加フィールドは、ビジネスニーズに応じて選択できます。Stripe が必須としないフィールドはオプションとして表示され、連結アカウントは提供するかどうかを選択できます。

1. ダッシュボードの[公開情報](https://dashboard.stripe.com/settings/connect/onboarding-options/public-details)設定で、**公開情報を収集する**トグルを有効にします。
1. オンボーディング時に連結アカウントに表示するフィールドを選択します。
1. **保存** をクリックします。

#### 利用可能なフィールド

収集できる公開情報は次のとおりです。

| フィールド                                                             | 説明                                        |
| ----------------------------------------------------------------- | ----------------------------------------- |
| [明細書表記](https://docs.stripe.com/connect/statement-descriptors.md) | 連結アカウントへの決済に対して顧客のカードまたは銀行の明細書に表示されるテキスト。 |
| 顧客サポート電話番号                                                        | 連結アカウントに関連するサポートをお客様が依頼できる電話番号。           |
| 顧客サポートの住所                                                         | 顧客が連結アカウントへの連絡に使用できる郵送先住所。                |
| 顧客サポートメール                                                         | 顧客が連結アカウントへの連絡に使用できるメールアドレス。              |

> #### 要件はさまざま
> 
> Stripe の要件は、連結アカウントの事業形態、国、リクエストされたケイパビリティによって異なります。必須かどうかにかかわらず、オンボーディング時に常にフィールドが表示されるようにフィールドを有効にしてください。

## アカウントリンクを作成する

連結アカウント ID を使用して [Account Link](https://docs.stripe.com/api/v2/core/account-links/create.md) を作成し、[use_case.account_onboarding.refresh_url](https://docs.stripe.com/connect/marketplace/tasks/onboard.md#refresh-url) と [use_case.account_onboarding.return_url](https://docs.stripe.com/connect/marketplace/tasks/onboard.md#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
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "account": "{{CONNECTEDACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'
```

| パラメーター                                                                                                                                                                       | 値                    | 説明                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [account](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-account)                                                                       | 連結アカウントの ID          | アカウントリンクを作成する連結アカウントの ID に設定します。                                                                                               |
| [use_case.type](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-type)                                                           | `account_onboarding` | 必要な情報を収集するためのフォームを提供します。                                                                                                       |
| [use_case.account_onboarding.configurations](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-configurations) | `recipient`          | 連結アカウントの設定を行います。この場合、`recipient` 設定は、連結アカウントに資金を支払うことができることを意味します。                                                             |
| [use_case.account_onboarding.return_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-return_url)         | 有効な URL              | ユーザーが離脱した後、またはユーザー登録フローを完了した後にリダイレクトされる URL。                                                                                   |
| [use_case.account_onboarding.refresh_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-refresh_url)       | 有効な URL              | アカウントリンクの有効期限が切れた場合、以前にアクセスした場合、またはその他の理由で無効な場合にユーザーをリダイレクトする URL。この URL を使用して、元のアカウントリンクの作成に使用したのと同じパラメーターで新しいアカウントリンクを生成します。 |

### 連結アカウントにアカウント登録フローを送信します

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

> アカウントリンクの URL をメールやショートメッセージ、またはその他の方法で、プラットフォームのアプリケーション外に送信しないでください。URL は、アプリケーション内で認証済みのアカウント所有者に提供してください。

## 要件の更新を特定して対処する [サーバー側]

アカウント要件に対する[変更をリッスンする](https://docs.stripe.com/connect/handling-api-verification.md#verification-process)ようにシステムを設定します。[テストトリガーカード](https://docs.stripe.com/connect/testing.md#trigger-cards)を使用して、新しい要件への対応 (および支払いと入金を無効にする方法) をテストできます。

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

Stripe は、連結アカウントに影響する[今後の要件更新](https://support.stripe.com/user/questions/onboarding-requirements-updates)についてお知らせします。`future_requirements` の [requested_reasons.code](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements-entries-requested_reasons-code) を持つアカウントの要件を確認することで、この情報を事前に収集することができます。

Stripe が要件の収集を担当する連結アカウントの場合、[アカウントリンク](https://docs.stripe.com/api/v2/core/account-links.md)または[アカウントセッション](https://docs.stripe.com/api/account_sessions.md)の作成後に本人確認情報の更新の受信を停止します。

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

> #### マーケットプレイスを Accounts v1 から Accounts v2 に移行する
> 
> 新しいアカウントについては、[listen for v2.core.account[requirements].updated events](https://docs.stripe.com/connect/marketplace/tasks/onboard.md#handle-account-updates) のイベント受信先を作成してください。既存の連結アカウントは v1 と v2 双方のイベントを送信するため、お客様の連携機能は `account.updated` v1イベントではなく、`v1.account.updated` v2を受信することで管理できます。

### 確認エラーを処理する

[v2.core.account[requirements].updated](https://docs.stripe.com/api/v2/core/events/event-types.md?api-version=preview) イベントをリッスンします。期限が到来したときにアカウントに [minimum_deadline.status](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements-entries-minimum_deadline-status) が `currently_due` の要件が含まれている場合、対応する機能は無効になり、それらのステータスは `past_due` になります。

Stripe ホスティング登録フォームにアカウントを誘導して、確認要件を修正できるようにします。
 (See full diagram at https://docs.stripe.com/connect/marketplace/tasks/onboard)
## プラットフォームに戻るユーザに対応する

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

> `return_url` と `refresh_url` には、本番環境だけでなくテスト環境 (例えば localhost でのテスト) でも HTTPS を使用する必要があります。HTTP を使用すると、Account Link の作成処理は失敗します。

### URL を返す

ユーザーがユーザー登録フローを完了するか、フローの任意の時点で **保存して後で処理** をクリックすると、Stripe は連結アカウントを [return_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-return_url) にリダイレクトします。これは、すべての情報が収集されたことを意味するものでも、アカウントの要件がすべて満たされたことを意味するものでもありません。ユーザーがフローに正常に入り、そこから正常に出たことのみを意味します。

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

- [アカウントを取得](https://docs.stripe.com/api/v2/core/accounts/retrieve.md)し、[requirements](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements) ハッシュで未対応の要件を確認します。
- アプリケーション内でアカウントのステータスをキャッシュし、`v2.core.account[requirements].updated` イベントを監視して最新の状態に保ちます。

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

### URL を再読み込み

Stripe は次の場合、アカウントユーザーを [refresh_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-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](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status) が `active` になっているかを確認してください。もしステータスが `active` でなく、かつ [configuration.recipient.capabilities.stripe_balance.stripe_transfers.status_details.code](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-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 では、未完了の要件を入力するためのフォームが提供されます。新しい連結アカウントをオンボーディングする場合、または既存アカウントに新しい要件 (例えば追加情報が必要な新しい機能をリクエストした場合) が発生した場合に使用します。

## 次のステップ

連結アカウントがアクティブな場合は、貴社がサポートする[決済手段を有効](https://docs.stripe.com/connect/marketplace/tasks/enable-payment-methods.md)にします。