Managed Accounts Beta

If you'd like to control your users' entire onboarding experience, you can create and work with managed Stripe accounts via the API. If you need help after reading this, check out our answers to common questions or chat live with other developers in #stripe on freenode.

A managed Stripe account will be almost completely invisible to the account holder: you will be responsible for all interactions with them and for collecting any information Stripe needs.

With managed accounts, you will have the ability to change their bank account information and modify any other information on their Stripe account programmatically. Since these users won’t be able to log into Stripe (and will most likely not even know they own a Stripe account), it’s up to you to build any onboarding, dashboard, reporting, and communication flows with them.

The only piece of information you need to create a managed account is its country: everything else can be collected and updated at a later time. The country must be the country the account holder resides in or that the business is legally established in. For example, if you are in the United States, and the business you’re creating an account for is legally represented in Canada, you would use “CA” as the country for the account being created.

Requirements for creating managed accounts

  • Minimum API version: you must be using an API version at least as recent as 2014-12-17.
  • Terms of Service update: creating managed accounts requires an update to your terms of service, as they must include a reference to Stripe’s terms.
  • Handling information requests: instead of requesting it directly from the account holder, Stripe will request information, such as a social security number or passport scan, from you. You must collect this information from the user and provide it to Stripe, otherwise Stripe may disable transfers to the account.
  • Platform in a supported country: managed accounts are in public beta. Platforms in Australia, Canada, Denmark, Finland, Ireland, Norway, Sweden, the United Kingdom, or the United States can create managed accounts for any country Stripe supports. If you would like to be notified when managed account platforms are available in your country, let us know.
  • Vetting for fraud: your platform is ultimately responsible for any losses incurred by managed accounts. To best protect against this, you will need to scrutinize any accounts that sign up via your platform for potential fraud. Refer to our best practices for more information about this.

Creating a managed account

At the bare minimum, to create and connect to a managed account, simply set managed to true in the creation request, and provide a country. The country, once set, cannot be changed.

The country value is for the managed account: where the account representative lives or that business is legally established. Do not use the platform’s country. The country value also informs what kind of bank account they can have and what requirements you have around verifying their identity.

curl https://api.stripe.com/v1/accounts \
   -u {PLATFORM_SECRET_KEY}: \
   -d country=US \
   -d managed=true
Stripe.api_key = PLATFORM_SECRET_KEY
Stripe::Account.create(
  {
    :country => "US",
    :managed => true
  }
)
stripe.api_key = PLATFORM_SECRET_KEY
stripe.Account.create(
  country="US",
  managed=True
)
\Stripe\Stripe::setApiKey(PLATFORM_SECRET_KEY);
\Stripe\Account::create(
  array(
    "country" => "US",
    "managed" => true
  )
);
Stripe.apiKey = PLATFORM_SECRET_KEY;

Map<String, Object> accountParams = new HashMap<String, Object>();
accountParams.put("country", "US");
accountParams.put("managed", true);

Account.create(accountParams);
var stripe = require('stripe')(PLATFORM_SECRET_KEY);
stripe.accounts.create(
  {
    country: "US",
    managed: true
  }
);

The result of a successful API call will be the user’s account information:

{
  ...
  "id": "acct_12QkqYGSOD4VcegJ",
  "keys": {
    "secret": "sk_live_AxSI9q6ieYWjGIeRbURf6EG0",
    "publishable": "pk_live_h9xguYGf2GcfytemKs5tHrtg"
  },
  "managed": true
  ...
}

You’ll want to store the account ID and, if you intend to use them for authentication, the secret key and publishable key. The keys will not be retrievable subsequently.

An account created with only a country is fairly limited: it can only receive a small amount of funds. If you wish to enable transfers and keep the account in good standing, you need to provide more information on the account holder. There are many other fields you likely want to set when creating a managed account. We discuss some of the more nuanced ones in other guides in this section.

At the very least, you usually want to collect name and date of birth upfront.

Webhooks

Once created, all account changes will be delivered via webhooks as an account.updated event. Be certain to establish a platform webhook URL in your account settings to watch for these.

Onward!

Managing accounts gives you flexibility, but requires more integration work. Learn more about working with managed accounts.