Migrate your Connect integration to use controller properties instead of account types
Learn how to work with account controller properties instead of specifying 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.
property to application_
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_
and transfers
capabilities.
Note
Creating a Custom account using type
, sets the controller.
property to application_
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.
.
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_ | application | none |
Express | application | application_ | stripe | express |
Standard | stripe | account | stripe | full |
Note
Remember that Express and Custom accounts have a different value for fees.
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.
= 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.
= express
isn’t compatible with any of the following values:
controller.
=losses. payments stripe
controller.
=fees. payer account
controller.
=requirement_ collection application
controller.
= full
isn’t compatible with any of the following values:
controller.
=losses. payments application
controller.
=fees. payer application
controller.
=requirement_ collection application
controller.
= 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