Migrate your Connect integration to use controller properties instead of account types
You can now 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 like which Stripe-hosted dashboard the account can access or who Stripe collects fees from. This modularity allows for more flexible configuration options.
Using account controller properties doesn’t require you to update your API version. Migrating your integration to use controller properties is optional. If you only use one type of connected account and aren’t interested in using a new configuration, you don’t need to update your integration.
We recommend you update your integration to take advantage of the increased modularity and new configurations available. The new properties are fully backwards compatible, so you can migrate your integration incrementally while continuing to work with account types.
Each account type maps to a set of controller properties. We automatically set those properties on your existing connected accounts and on any accounts that you create with account types going forward. When you update your integration to work with controller properties, you don’t have to update any of your connected accounts.
Note
You can start using features such as embedded components without making any of the changes in this guide.
Before you begin
- Learn how account controller properties work and how they map to your existing connected accounts.
- Determine which of the new account configurations make sense for your integration.
Updating your integration involves:
- Identifying code in your integration that references the account type, and updating it to reference the corresponding controller properties instead.
- Updating your account creation process to specify controller properties instead of
type
. Specifyingtype
is no longer required.
Account controller properties
You can specify values for the controller properties when you create a connected account using the Accounts API. Any property that you don’t specify is set to a default value that has the least complex integration requirements.
If you’re building a new integration, you can get a configuration recommendation by completing Connect platform onboarding.
Property | Default value | Description |
---|---|---|
controller.losses.payments | stripe | Possible values:
|
| Possible values:
When you create an account, you can only specify
For a comprehensive description of Stripe fee payment models, see the fee behavior documentation. | |
controller.requirement_collection | stripe | Possible values:
|
controller.stripe_dashboard.type | full | Possible values:
|
See the description | Possible values:
Specifying |
Mapping account types to controller parameters
Each of the three account types maps to values in the controller
hash of v1/accounts
that match the behavior of that type.
Standard
If you create an account without specifying any controller properties, the default values match the behavior of a Standard account. You can also create the equivalent of a Standard account by specifying the values that map to Standard account behavior.
These values map to a Standard account’s behavior:
losses.payments
:stripe
fees.payer
:account
requirement_collection
:stripe
stripe_dashboard.type
:full
Express
These values map to an Express account’s behavior:
losses.payments
:application
fees.payer
:application
(see note)requirement_collection
:stripe
stripe_dashboard.type
:express
Note
Creating an Express account using type
, sets the controller.fees.payer
property to application_express
instead of application
. This difference denotes a variation in Stripe fee billing behavior when your platform is using Direct charges.
Custom
These values map to a Custom account’s behavior:
losses.payments
:application
fees.payer
:application
(see note)requirement_collection
:application
stripe_dashboard.type
:none
You must also specify the account country when creating a Custom account, and request the card_payments
and transfers
capabilities.
Note
Creating a Custom account using type
, sets the controller.fees.payer
property to application_custom
instead of application
. This difference denotes a variation in Stripe fee billing behavior when your platform is using Direct charges.
Migrate code to use controller properties
In addition to updating your account creation process to use controller properties, update your integration by reviewing your code and looking for references to account types.
For each reference to an account type, determine which controller property or properties are relevant and update the code accordingly.
For example, say that your code includes a conditional statement that applies to Express and Custom accounts because it relates to your platform being responsible for negative balances. Update that logic from if type == express
or if type == custom
to if controller.losses.payments == application
.
If you create connected accounts that don’t match an account type, consider their controller properties as well when updating your code. The logic for handling those accounts can differ from your existing logic that’s based on account types.
You can use this table to identify the controller properties associated with each account type:
Account Type | 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 |
Note
Remember that Express and Custom accounts have a different value for fees.payer
than equivalent accounts created using controller properties. When updating code related to collecting fees, you must take into account the difference in behavior.
Unsupported configurations
When creating accounts with controller properties, the following combinations aren’t supported:
controller.requirement_collection
= application
isn’t compatible with any of the following values:
controller.losses.payments
=stripe
controller.fees.payer
=account
controller.stripe_dashboard.type
=express
controller.stripe_dashboard.type
=full
controller.stripe_dashboard.type
= express
isn’t compatible with any of the following values:
controller.losses.payments
=stripe
controller.fees.payer
=account
controller.requirement_collection
=application
controller.stripe_dashboard.type
= full
isn’t compatible with any of the following values:
controller.losses.payments
=application
controller.fees.payer
=application
controller.requirement_collection
=application
controller.stripe_dashboard.type
= none
isn’t supported when both of the following values are set (it’s supported when only one of them is set):
controller.requirement_collection
=stripe
controller.losses.payments
=application
Stripe-hosted onboarding and account links
Stripe-hosted onboarding doesn’t support connected accounts that have both of these controller property values:
controller.stripe_dashboard.type
=none
controller.requirement_collection
=stripe
If you create such accounts, you can’t onboard them using account links. The following example demonstrates logic for handling that scenario:
if controller.stripe_dashboard.type == "none" if controller.requirement_collection == "platform" create_account_link(account) else // Stripe-hosted onboarding is not supported end end