# アカウントタイプの代わりにコントローラープロパティを使用するように Connect の実装を移行する

アカウントタイプを指定する代わりに、アカウントコントローラープロパティを使用する方法をご紹介します。

このガイドでは、アカウントコントローラーのプロパティを使用するように Connect の実装を移行する方法について説明します。

連結アカウントを Standard、Express、または Custom として定義する代わりに、アカウントコントローラープロパティを使用してアカウントを設定することもできます。これらのコントローラープロパティを使用すると、各アカウントの仕様 (Stripe ダッシュボードへのアクセス権や、Stripe がアカウントとプラットフォームのどちらから手数料を徴収するかの設定など) を指定できるようになります。このモジュールにより、より柔軟な設定が可能になります。

アカウントコントローラープロパティを使用するために、API バージョンを更新する必要はありません。**コントローラープロパティを使用するための既存のシステムの移行は任意です。**使用している連結アカウントが 1 つのタイプのみで、新しい設定の使用を希望しない場合、構築済みのシステムを更新する必要はありません。

既存のシステムを更新して、モジュール方式の向上と利用可能な新しい設定のメリットを活用することをお勧めします。新しいプロパティは完全な下位互換性があるため、アカウントタイプを引き続き処理しながら、段階的にシステムを移行できます。

各アカウントタイプは、一連のコントローラープロパティにマッピングされます。既存の連結アカウントと、今後のアカウントタイプで作成するすべてのアカウントに、これらのプロパティが自動的に設定されます。構築済みのシステムを更新してコントローラープロパティを処理する際に、連結アカウントを更新する必要はありません。

> このガイドに記載されている変更を行わずに、[埋め込みコンポーネント](https://docs.stripe.com/connect/get-started-connect-embedded-components.md)などの機能の使用を開始できます。

## はじめに

- コントローラープロパティの仕組みと、既存の連結アカウントへのマッピング方法をご紹介します。
- 新しいアカウント設定のうち、どれが既存のシステムに適しているかを判断します。

組み込みのアップグレードでは以下の作業を行います。

- 既存のシステムでアカウントタイプを参照するコードを特定し、代わりに対応するコントローラープロパティを参照するようにそのコードを更新します。
- `type` の代わりにコントローラープロパティを指定するようにアカウント作成プロセスを更新します。`type` の指定は必須ではなくなりました。

## アカウントコントローラープロパティ

[Accounts API](https://docs.stripe.com/api/accounts/create.md#create_account-controller) を使用して連結アカウントを作成する際に、コントローラープロパティの値を指定できます。指定していないプロパティは、導入要件の複雑さが最も低いデフォルト値に設定されます。

新しい Stripe システムを構築する場合は、[Connect プラットフォームのアカウント登録](https://dashboard.stripe.com/connect)を完了すると推奨の設定を取得できます。

| プロパティ | デフォルト値 | 説明 |
| --- | --- | --- |
| [controller.losses.payments](https://docs.stripe.com/api/accounts/create.md#create_account-controller-losses-payments) | `stripe` | 使用可能な値:
- `application`: お客様のプラットフォームが連結アカウントの*マイナス残高に対する責任を負い* (The responsibility for managing risk and recovering negative balances on connected accounts. Stripe or the Connect platform can be liable for negative balances on connected accounts)、クレジットリスクと不正利用リスクを管理します。この場合、[ダッシュボード](https://dashboard.stripe.com/settings/connect/platform_profile)でお客様の責任内容を確認し、承認する必要があります。
- `stripe`: このアカウントが支払いによって発生したマイナス残高を返済できない場合は Stripe が責任を負います。お客様のプラットフォームには、プラットフォームアカウントのマイナス残高については引き続き責任を負います。 |
| [controller.fees.payer](https://docs.stripe.com/api/accounts/create.md#create_account-controller-fees-payer) | `account` | 使用可能な値:

- `account`: 連結アカウントが、支払い処理手数料を含むすべての Stripe 手数料を Stripe に直接支払います
- `application`: Connect プラットフォームが、支払い処理手数料を含むすべての Stripe 手数料を支払います
- `application_custom`: アカウントは type=custom で作成されました
- `application_express`: アカウントは type=express で作成されました

アカウントを作成する際には、`application` または `account` のみを指定できます。

`application_express` と `application_custom` は有効な作成パラメーターではありません。

Stripe 手数料の支払いモデルに関する総合的な説明については、[手数料の動作に関するドキュメント](https://docs.stripe.com/connect/direct-charges-fee-payer-behavior.md)をご覧ください。 |
| [controller.requirement_collection](https://docs.stripe.com/api/accounts/create.md#create_account-controller-requirement_collection) | `stripe` | 使用可能な値:

- `application`: *要件が期限切れになったときや変更されたときに* (The responsibility for collecting required information from connected accounts to keep their Stripe accounts active. Stripe or the Connect platform can be responsible for requirement collection)プラットフォームが最新の情報を収集する責任を負います。
- `stripe`: *要件が期限切れになったときや変更されたときに* (The responsibility for collecting required information from connected accounts to keep their Stripe accounts active. Stripe or the Connect platform can be responsible for requirement collection) Stripe が最新の情報を収集する責任を負います。

値が `application` の場合、プラットフォームはアカウントの [KYC プロパティ](https://docs.stripe.com/connect/identity-verification.md)にフルアクセスでき、アカウントが API を使用して [Stripe 利用契約](https://docs.stripe.com/connect/service-agreement-types.md)を確認し、同意したことを証明できます。 |
| [controller.stripe_dashboard.type](https://docs.stripe.com/api/accounts/create.md#create_account-controller-stripe_dashboard-type) | `full` | 使用可能な値:
- `express`: 連結アカウントは Express ダッシュボードにアクセスできます
- `full`: 連結アカウントは Stripe ダッシュボードの全機能を利用できます
- `none`: アカウントは Express ダッシュボードにも Stripe ダッシュボードにもアクセスできません |
| [type](https://docs.stripe.com/api/accounts/create.md#create_account-type) | 説明を見る | 使用可能な値:

- `custom`: アカウントは Custom 連結アカウントとして作成されました
- `express`: アカウントは Express 連結アカウントとして作成されました
- `standard`: アカウントは Standard 連結アカウントとして作成されたか、Standard アカウントと一致するコントローラープロパティを指定して作成されました
- `none`: アカウントはタイプ値なしで作成され、コントローラープロパティは 3 つのアカウントタイプのいずれとも一致しません

`type` の指定はオプションです。`type` を使用してアカウントを作成する場合、`custom`、`express`、または `standard` のみを指定できます。`none` は有効なアカウント作成パラメーターではありません。 |

## アカウントタイプをコントローラーパラメーターにマッピングする

3 つのアカウントタイプはそれぞれ、そのタイプの動作と一致する `v1/accounts` の `controller` ハッシュの値にマッピングされます。

> #### ダッシュボードの種類は変更不可
> 
> 既存の連結アカウントの `controller.stripe_dashboard.type` は変更できません。連結アカウントのダッシュボードを変更するには、新しい `Account` オブジェクトを作成する必要があります。

### Standard

コントローラープロパティを指定せずにアカウントを作成した場合、デフォルト値は Standard アカウントの動作と一致します。また、Standard アカウントの動作にマッピングされる値を指定して、Standard アカウントに相当するアカウントを作成することもできます。

これらの値は、Standard アカウントの動作にマッピングされます。

- `losses.payments`: `stripe`
- `fees.payer`: `account`
- `requirement_collection`: `stripe`
- `stripe_dashboard.type`: `full`

#### コントローラープロパティを使用して作成する

リクエスト (すべてのプロパティにデフォルト値を使用):

```curl
curl -X POST https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:"
```

レスポンス:

```
{
  controller: {
    type: "application",
    is_controller: true,
    losses: {
      payments: "stripe"
    },
    requirement_collection: "stripe",
    fees: {
      payer: "account",
    },
    stripe_dashboard: {
      type: "full"
    }
  },
  type: "standard"
}
```

#### タイプを指定して作成する

リクエスト:

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

レスポンス:

```json
{
  "controller": {
    "type": "application",
    "is_controller": true,
    "losses": {
      "payments": "stripe"
    },
    "requirement_collection": "stripe",
    "fees": {
      "payer": "account"
    },
    "stripe_dashboard": {
      "type": "full"
    }
  },
  "type": "standard"
}
```

### Express

これらの値は、Express アカウントの動作にマッピングされます。

- `losses.payments`: `application`
- `fees.payer`: `application` (メモ参照)
- `requirement_collection`: `stripe`
- `stripe_dashboard.type`: `express`

> `type` を使用して Express アカウントを作成し、`controller.fees.payer` プロパティを、`application` ではなく `application_express` に設定します。この違いは、プラットフォームでダイレクト支払いが使用されている場合における Stripe の[手数料請求機能](https://docs.stripe.com/connect/direct-charges-fee-payer-behavior.md)の違いを表します。

#### コントローラープロパティを使用して作成する

リクエスト:

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

レスポンス:

```json
{
  "controller": {
    "type": "application",
    "is_controller": true,
    "losses": {
      "payments": "application"
    },
    "requirement_collection": "stripe",
    "fees": {
      "payer": "application"
    },
    "stripe_dashboard": {
      "type": "express"
    }
  },
  "type": "none"
}
```

#### タイプを指定して作成する

リクエスト:

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

レスポンス:

```json
{
  "controller": {
    "type": "application",
    "is_controller": true,
    "losses": {
      "payments": "application"
    },
    "requirement_collection": "stripe",
    "fees": {
      "payer": "application_express"
    },
    "stripe_dashboard": {
      "type": "express"
    }
  },
  "type": "express"
}
```

### Custom

これらの値は、Custom アカウントの動作にマッピングされます。

- `losses.payments`: `application`
- `fees.payer`: `application` (メモ参照)
- `requirement_collection`: `application`
- `stripe_dashboard.type`: `none`

また、Custom アカウントを作成する際はアカウントの国を指定し、`card_payments` ケイパビリティと `transfers` ケイパビリティをリクエストする必要もあります。

> `type` を使用して Custom アカウントを作成し、`controller.fees.payer` プロパティを、`application` ではなく `application_custom` に設定します。この違いは、プラットフォームでダイレクト支払いが使用されている場合における Stripe の[手数料請求機能](https://docs.stripe.com/connect/direct-charges-fee-payer-behavior.md)の違いを表します。

#### コントローラープロパティを使用して作成する

リクエスト:

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "controller[stripe_dashboard][type]=none" \
  -d "controller[fees][payer]=application" \
  -d "controller[losses][payments]=application" \
  -d "controller[requirement_collection]=application" \
  -d "capabilities[transfers][requested]=true" \
  -d country=US
```

レスポンス:

```json
{
  "controller": {
    "type": "application",
    "is_controller": true,
    "losses": {
      "payments": "application"
    },
    "requirement_collection": "application",
    "fees": {
      "payer": "application"
    },
    "stripe_dashboard": {
      "type": "none"
    }
  },
  "type": "none"
}
```

#### タイプを指定して作成する

リクエスト:

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d type=custom \
  -d "capabilities[transfers][requested]=true" \
  -d country=US
```

レスポンス:

```json
{
  "controller": {
    "type": "application",
    "is_controller": true,
    "losses": {
      "payments": "application"
    },
    "requirement_collection": "application",
    "fees": {
      "payer": "application_custom"
    },
    "stripe_dashboard": {
      "type": "none"
    }
  },
  "type": "custom"
}
```

## コードを移行してコントローラープロパティを使用する

コントローラープロパティを使用するようにアカウント作成プロセスを更新するだけでなく、コードを見直してアカウントタイプへの参照を探し、既存のシステムを更新します。

アカウントタイプへの参照ごとに、関連するコントローラープロパティを特定し、それに応じてコードを更新します。

たとえば、マイナスの残高に責任を負うプラットフォームに関連するため、Express と Custom のアカウントに適用される条件付きの声明文をコードに含めるとします。そのロジックを `if type == express` または `if type == custom` から `if controller.losses.payments == application` に更新します。

アカウントタイプと一致しない連結アカウントを作成する場合は、コードを更新する際に、そのコントローラープロパティも考慮してください。これらのアカウントを処理するロジックは、アカウントタイプに基づく既存のロジックとは異なることがあります。

この表を使用して、各アカウントタイプに関連付けられているコントローラープロパティを識別できます。

| アカウントタイプ | losses.payments | fees.payer | requirement_collection | stripe_dashboard.type |
| --- | --- | --- | --- | --- |
| Custom | `application` | `application_custom` | `application` | `none` |
| Express | `application` | `application_express` | `stripe` | `express` |
| Standard | `stripe` | `account` | `stripe` | `full` |

> Express アカウントと Custom アカウントでは、コントローラープロパティを使用して作成された同等のアカウントとは `fees.payer` の値が異なることに注意してください。手数料の徴収に関連するコードを更新するときは、この動作の違いを考慮する必要があります。

## サポート対象外の設定

コントローラープロパティを指定してアカウントを作成する際、以下の組み合わせはサポートされません。

`controller.requirement_collection` = `application` は、次のいずれの値とも互換性がありません。

- `controller.losses.payments` = `stripe`
- `controller.fees.payer` = `account`
- `controller.stripe_dashboard.type` = `express`
- `controller.stripe_dashboard.type` = `full`

`controller.stripe_dashboard.type` = `express` は、次の値とも互換性がありません:

- `controller.requirement_collection` = `application`

`controller.stripe_dashboard.type` = `full` は、次のいずれの値とも互換性がありません。

- `controller.losses.payments` = `application`
- `controller.fees.payer` = `application`
- `controller.requirement_collection` = `application`

`controller.stripe_dashboard.type` = `none` は、次の両方の値が設定されている場合はサポートされません (いずれか 1 つのみが設定されている場合はサポートされます)。

- `controller.requirement_collection` = `stripe`
- `controller.losses.payments` = `application`