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

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

You can configure connected accounts using account controller properties instead of defining accounts as Standard, Express, or Custom. These controller properties let you specify discrete account behaviors, such as access to a Stripe-hosted Dashboard and whether Stripe collects fees from the account or the platform. This modularity allows for more flexible configuration options.

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

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

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

注

このガイドに記載されている変更を行わずに、埋め込みコンポーネントなどの機能の使用を開始できます。

はじめに

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

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

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

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

Accounts API を使用して連結アカウントを作成する際に、コントローラープロパティの値を指定できます。指定していないプロパティは、導入要件の複雑さが最も低いデフォルト値に設定されます。

新しい Stripe システムを構築している場合は、Connectプラットフォームのアカウント登録を完了すると、設定の推奨事項を受け取ることができます。

プロパティ	デフォルト値	説明
controller.losses.payments	`stripe`	使用可能な値: `application`: お客様のプラットフォームが連結アカウントのマイナス残高に対する責任を負い、クレジットリスクと不正利用リスクを管理します。この場合、ダッシュボードでお客様の責任内容を確認し、承認する必要があります。 `stripe`: このアカウントが支払いによって発生したマイナス残高を返済できない場合は Stripe が責任を負います。お客様のプラットフォームには、プラットフォームアカウントのマイナス残高については引き続き責任を負います。
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 手数料の支払いモデルに関する総合的な説明については、手数料の動作に関するドキュメントをご覧ください。
controller.requirement_collection	`stripe`	使用可能な値: `application`: 要件が期限切れになったときや変更されたときにプラットフォームが最新の情報を収集する責任を負います。 `stripe`: 要件が期限切れになったときや変更されたときに Stripe が最新の情報を収集する責任を負います。値が `application` の場合、プラットフォームはアカウントの KYC プロパティにフルアクセスでき、アカウントが API を使用して Stripe 利用契約を確認し、同意したことを証明できます。
controller.stripe_dashboard.type	`full`	使用可能な値: `express`: 連結アカウントは Express ダッシュボードにアクセスできます `full`: 連結アカウントは Stripe ダッシュボードの全機能を利用できます `none`: アカウントは Express ダッシュボードにも Stripe ダッシュボードにもアクセスできません
type	説明を見る	使用可能な値: `custom`: アカウントは Custom 連結アカウントとして作成されました `express`: アカウントは Express 連結アカウントとして作成されました `standard`: アカウントは Standard 連結アカウントとして作成されたか、Standard アカウントと一致するコントローラープロパティを指定して作成されました `none`: アカウントはタイプ値なしで作成され、コントローラープロパティは 3 つのアカウントタイプのいずれとも一致しません `type` の指定はオプションです。`type` を使用してアカウントを作成する場合、`custom`、`express`、または `standard` のみを指定できます。`none` は有効なアカウント作成パラメーターではありません。

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

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

Standard

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

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

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

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

レスポンス:

{
  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 の手数料請求機能の違いを表します。

リクエスト:

レスポンス:

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

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 の手数料請求機能の違いを表します。

リクエスト:

レスポンス:

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

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

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

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

たとえば、マイナスの残高に責任を負うプラットフォームに関連するため、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.losses.payments = stripe
controller.fees.payer = account
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