Migrate your Connect integration to use controller properties instead of account types

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.

Using account controller properties doesnt 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 arent interested in using a new configuration, you dont 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 dont have to update any of your connected accounts.

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. Specifying type 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 dont specify is set to a default value that has the least complex integration requirements.

If youre building a new integration, you can get a configuration recommendation by completing Connect platform onboarding.

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 accounts behavior:

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

curl -X POST https://api.stripe.com/v1/accounts \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:"

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

Express

These values map to an Express accounts behavior:

• losses.payments: application
• fees.payer: application (see note)
• requirement_collection: stripe
• stripe_dashboard.type: express

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

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

Custom

These values map to a Custom accounts 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.

curl https://api.stripe.com/v1/accounts \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -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

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

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 dont 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 thats based on account types.

You can use this table to identify the controller properties associated with each account type:

Unsupported configurations

When creating accounts with controller properties, the following combinations arent supported:

controller.requirement_collection = application isnt 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 isnt compatible with the following value:

• controller.requirement_collection = application

controller.stripe_dashboard.type = full isnt compatible with any of the following values:

• controller.losses.payments = application
• controller.fees.payer = application
• controller.requirement_collection = application

controller.stripe_dashboard.type = none isnt supported when both of the following values are set (its supported when only one of them is set):

• controller.requirement_collection = stripe
• controller.losses.payments = application