# Stripe のホスティング登録

Stripe のホスティング登録フローにリダイレクトして連結アカウントを登録します。

Stripe のホスティング登録が連結アカウントからの事業情報と本人確認情報の収集を処理するため、プラットフォームが担当する作業は最小限で済みます。これは Stripe がオンラインで提供するウェブフォームであり、各連結アカウントのケイパビリティ、国、業種に基づいて動的にレンダリングされます。
![](https://b.stripecdn.com/docs-statics-srv/assets/hosted_onboarding_form.e59ba8300f563e43489953f06127f52c.png)

Stripe サンプルインテグレーションのホスト型オンボーディングフォームである [Furever](https://furever.dev/)。

Stripe がホストするアカウント登録サポートは [ネットワーク化されたアカウント登録](https://docs.stripe.com/connect/networked-onboarding.md)に対応しており、複数の Stripe アカウントを持つ所有者がビジネス情報を共有できます。アカウントのユーザー登録時に、既存のアカウントから再利用でき、再提出する必要はありません。

## アカウント登録フォームをカスタマイズする [ダッシュボード]

ダッシュボードの [Connect 設定ページ](https://dashboard.stripe.com/account/applications/settings)に移動して、ブランド名、色、アイコンを使用してフォームの外観をカスタマイズします。Stripe がホストするアカウント登録では、この情報が必要です。また、アカウント登録時に連結アカウントから[銀行口座情報を収集](https://dashboard.stripe.com/settings/connect/payouts/external_accounts)することもお勧めします。

## アカウントを作成し、情報を事前入力する [サーバー側]

デフォルトの[コントローラー](https://docs.stripe.com/api/accounts/create.md#create_account-controller)プロパティーを使用して[連結アカウント](https://docs.stripe.com/api/accounts.md)を作成します。コントローラープロパティーの詳細については、[連携の設計](https://docs.stripe.com/connect/interactive-platform-guide.md)をご覧ください。または、アカウントの[種類](https://docs.stripe.com/api/accounts/create.md#create_account-type)を指定して連結アカウントを作成することもできます。

アカウントの国を指定するか、アカウントのケイパビリティをリクエストした場合、アカウント所有者は国を変更できません。それ以外の場合は、アカウントのダッシュボードへのアクセス権によって異なります。

- \** Stripe ダッシュボードの全機能:** アカウント登録時に、アカウント所有者は通常の Stripe アカウントへの登録時と同様に、任意の取引国を選択できます。Stripe は、選択された国に基づいて、アカウントのケイパビリティのセットを自動的にリクエストします。
- **Express ダッシュボード:** アカウント登録時に、アカウント所有者は、プラットフォームのダッシュボードの[アカウント登録オプション](https://dashboard.stripe.com/settings/connect/onboarding-options/countries)で設定された国のリストから選択できます。また、これらのオプションを設定して、各国のアカウントにリクエストするデフォルトのケイパビリティを指定することもできます。
- **Stripe ダッシュボードなし**:Stripe が要件収集を担当する場合、アカウント登録フローではアカウント所有者が任意の取引国を選択できます。それ以外の場合は、カスタムのアカウント登録フローで国を設定し、ケイパビリティをリクエストする必要があります。

#### コントローラープロパティを使用した場合

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "controller[fees][payer]=application" \
  -d "controller[losses][payments]=application" \
  -d "controller[stripe_dashboard][type]=express"
```

#### アカウントタイプを使用した場合

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d type=standard
```

レスポンスには ID が含まれており、システム全体で `Account` を参照する場合はこれを使用します。

### ケイパビリティをリクエストする

アカウントの作成時に、必要なケイパビリティの `requested` プロパティを true に設定することで、[ケイパビリティ](https://docs.stripe.com/connect/account-capabilities.md#creating)をリクエストできます。Express ダッシュボードにアクセスできるアカウントの場合は、[アカウント登録オプション](https://dashboard.stripe.com/settings/connect/onboarding-options/countries)を設定して、アカウントの作成時に特定のケイパビリティを自動的にリクエストすることもできます。

Stripe のアカウント登録 UI は、リクエストされたケイパビリティの要件を自動的に収集します。アカウント登録の負荷を軽減するため、必要なケイパビリティのみをリクエストしてください。

### 情報を事前入力する

アカウント所有者に関する情報 (氏名、住所、その他の詳細など) を入手している場合、アカウントの作成時または更新時にそれを提供することで、アカウント登録をシンプルにできます。アカウント登録インターフェイスは、アカウント所有者に対して、[Connect 利用規約](https://docs.stripe.com/connect/service-agreement-types.md)に同意する前に、事前入力された情報を確認するよう求めます。アカウント所有者は、Accounts API を使用して情報を提供した場合でも、その事前入力された情報を利用規約に同意する前に編集することができます。

アカウント登録を行い、プラットフォームから URL が提供されている場合は、アカウントの [business_profile.url](https://docs.stripe.com/api/accounts/create.md#create_account-business_profile-url) を事前入力します。ビジネスに URL がない場合には、代わりに [business_profile.product_description](https://docs.stripe.com/api/accounts/create.md#create_account-business_profile-product_description) を事前入力できます。

実装内容をテストする際は、[テストデータ](https://docs.stripe.com/connect/testing.md)を使用して、本人確認、事業情報の確認、入金の失敗などのさまざまな結果をシミュレーションできます。

## 収集する情報を決定する

プラットフォームは、連結アカウントから必要な情報を事前に (*アップフロント* (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/account_links/create.md#create_account_link-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/account_links/create.md) を作成し、[更新 URL](https://docs.stripe.com/connect/hosted-onboarding.md#refresh-url) と[戻り URL](https://docs.stripe.com/connect/hosted-onboarding.md#return-url) を含めます。アカウントリンク URL がすでにアクセスされているか、有効期限が切れているか、その他の理由で無効な場合、Stripe は連結アカウントを更新 URL にリダイレクトします。Stripe は、連結アカウントがアカウント登録フローを完了または離脱したときに、戻り URL にリダイレクトします。さらに、収集する必要がある情報に基づいて、`collection_options.fields` に `currently_due` または `eventually_due` を渡します。この例では、`eventually_due` を渡して、事前登録を使用します。増分登録の場合は、`currently_due` に設定します。

```curl
curl https://api.stripe.com/v1/account_links \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_ID}}" \
  --data-urlencode "refresh_url=https://example.com/refresh" \
  --data-urlencode "return_url=https://example.com/return" \
  -d type=account_onboarding \
  -d "collection_options[fields]=eventually_due"
```

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

連結アカウントを Account Link URL にリダイレクトして、ユーザー登録フローに送ります。各一時 Account Link URL は、アカウント所有者の個人情報へのアクセスを許可するため、1 回のみ使用できます。この URL にリダイレクトする前に、アプリケーションでアカウントを認証します。連結アカウントの情報をその後は読み書きできないため、Account Link を生成する前にアカウント情報を [事前入力](https://docs.stripe.com/connect/hosted-onboarding.md#prefill-information) します。

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

#### iOS

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Android

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

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

アカウント要件に対する[変更をリッスンする](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)について通知します。アカウントの[今後の要件](https://docs.stripe.com/api/accounts/object.md#account_object-future_requirements)を確認することで、この情報を事前に収集できます。

[controller.requirement_collection](https://docs.stripe.com/api/accounts/object.md#account_object-controller-requirement_collection) が `stripe` である連結アカウントの場合は、[Account Link (アカウントリンク)](https://docs.stripe.com/api/account_links.md) または [Account Session (アカウントセッション)](https://docs.stripe.com/api/account_sessions.md) の作成後に本人確認情報の更新の受信を停止します。

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

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

[account.updated](https://docs.stripe.com/api/events/types.md#event_types-account.updated) イベントをリッスンします。`current_deadline` が着信したときにアカウントに `currently_due` フィールドが含まれている場合は、対応する機能が無効になり、そのフィールドが `past_due` に追加されます。

Stripe ホスティング登録フォームにアカウントを誘導して、確認要件を修正できるようにします。
 (See full diagram at https://docs.stripe.com/connect/hosted-onboarding)
## プラットフォームに戻る連結アカウントを処理する [サーバー側]

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

> テスト環境 (ローカルでのテストなど) では、`refresh_url` と `return_url` に HTTP を使用できますが、本番環境では HTTPS のみがサポートされます。本番環境へ移行する前に、テスト用の URL をすべて HTTPS URL に更新する必要があります。

### 再読み込み URL

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

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

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

### 戻り先 URL

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

この URL を通じて状態が渡されることはありません。連結アカウントが `return_url` にリダイレクトされたら、アカウント登録が完了したかどうかを確認します。[アカウントを取得](https://docs.stripe.com/api/accounts/retrieve.md)し、[requirements](https://docs.stripe.com/api/accounts/object.md#account_object-requirements) ハッシュで未対応の要件がないか確認します。または、Webhook エンドポイントに送信された `account.updated` イベントをリッスンし、アプリケーションでアカウントの状態をキャッシュします。アカウント登録を完了していない場合は、後でアカウント登録を続行できるように、アプリケーションにメッセージを表示します。

## 連結アカウントによって開始された更新を処理する [サーバー側]

Stripe がオンラインで提供するオンボーディングでは、連結アカウントによって開始される、すでに提供された情報の更新もサポートされます。Webhook エンドポイントに送信された `account.updated` イベントをリッスンして、アカウントが ID チェックを完了し情報を更新したときに通知されるようにします。

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

> #### アカウントLink 種別による制限
> 
> `account_update` タイプのアカウント Link は、Custom アカウントなど、プラットフォームが要件の収集を担当する連結アカウントに対してのみ作成できます。Stripe がホストするダッシュボードにアクセスできるアカウントに対しては作成できません。[Connect 組み込みコンポーネント](https://docs.stripe.com/connect/get-started-connect-embedded-components.md)を使用する場合は、連結アカウントが自身の情報を更新できるようにするコンポーネントを含めることができます。Stripe がホストするダッシュボードにアクセスできないアカウントがマイナス残高に対する責任を負う場合は、埋め込みコンポーネントを使用する必要があります。

### account_onboarding のアカウントリンク

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

### account_update のアカウントリンク

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

## ブラウザーのサポート

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