Using Connect with Custom Accounts

Use Custom accounts with Connect to control your users' entire experience.

With Connect, users of your platform can have one of three types of Stripe accounts:

A Custom Stripe account is almost completely invisible to the account holder. You, the platform, are responsible for all interactions with your users and for collecting all the information Stripe needs.

With Custom accounts you can modify the connected account’s details and settings through the API, including managing their bank accounts and payout schedule. Since Custom account holders can’t log into Stripe it’s up to you to build the onboarding flow, user dashboard, reporting functionality, and communication channels.

Although a simple API call creates a Custom account, there are three steps to consider for each account you create:

Properly identify the country to use.
Create the account.
Move onto the identity verification process.

But first, ensure you meet the minimum requirements.

Requirements for creating Custom accounts

To use Custom accounts, you must meet all of these requirements:

Minimum API version, you must be using an API version at least as recent as 2014-12-17.
Terms of Service update, creating Custom accounts requires an update to your terms of service, as they must include a reference to Stripe’s services agreement. You should also consult with your attorneys on whether you should update your terms acceptance language to include reference to Stripe’s terms.
Handling information requests, instead of requesting information—such as a Social Security Number or passport scan—directly from the account holder (your user), Stripe requests the information it needs from you. You must collect this information from the user and provide it to Stripe, otherwise Stripe may disable payouts to the connected account.
Platform in a supported country, platforms in Australia, Austria, Belgium, Canada, Denmark, Finland, France, Germany, Hong Kong, Ireland, Italy, Japan, Luxembourg, the Netherlands, New Zealand, Norway, Portugal, Spain, Sweden, Switzerland, the United Kingdom, and the United States can create Custom accounts for any country Stripe supports. If you would like to be notified when platforms in your country can use Custom accounts, let us know.
Vetting for fraud, your platform is ultimately responsible for losses incurred by Custom accounts. To best protect against this, you need to scrutinize all accounts that sign up via your platform for potential fraud. Refer to our best practices guide for more.

Note there’s an additional cost for active Custom accounts. A Custom account is considered active if it has received at least one successful payout in a given month.

Step 1: Identify the country to use

The only piece of information you need to create a Custom account is its country: everything else can be collected and updated at a later time. The country value is for the Custom account: where the account representative lives or that business is legally established. The country, once set, cannot be changed.

For example, if you are in the United States and the business or user you’re creating an account for is legally represented in Canada, use CA as the country for the account being created.

The country value also determines the required verification information for the connected account.

Step 2: Create a Custom account

At the bare minimum, to create and connect to a Custom account, simply set type to custom in the account creation request and provide a country.

curl https://api.stripe.com/v1/accounts \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d country=US \
   -d type=custom

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

acct = Stripe::Account.create({
    :country => "US",
    :type => "custom"
})

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

acct = stripe.Account.create(
  country="US",
  type="custom"
)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$acct = \Stripe\Account::create(array(
    "country" => "US",
    "type" => "custom"
));

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> params = new HashMap<String, Object>();
params.put("country", "US");
params.put("type", "custom");

Account acct = Account.create(params);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

stripe.accounts.create({
  country: "US",
  type: "custom"
}).then(function(acct) {
  // asynchronously called
});

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.AccountParams{
  Country: "US",
  Type: "custom",
}

acct, err := account.New(params)

The result of a successful API call is the user's account information:

{
  ...
  "id": "acct_12QkqYGSOD4VcegJ",
  "keys": {
    "secret": "sk_live_AxSI9q6ieYWjGIeRbURf6EG0",
    "publishable": "pk_live_h9xguYGf2GcfytemKs5tHrtg"
  },
  "type": "custom"
  ...
}

Store the id in your database—it’s the account ID. You’ll provide this value to authenticate as the connected account by passing it into requests in the Stripe-Account header. (It’s also possible to authenticate with the secret key returned here, but it’s more secure to store and use only the account ID instead.)

Step 3: Start the identity verification process

An account created with only a country is fairly limited: it can only receive a small amount of funds. If you wish to enable payouts and keep the account in good standing, you need to provide more information about the account holder.

The required verification information page lists the minimum and likely identity verification requirements. You can provide these when you create the account or by updating the account later.

At the very least, we recommend collected and providing the user’s name and date of birth upfront.

Webhooks

Once created, all account change notifications are delivered via webhooks as an account.updated event. Establish a Connect webhook URL in your account settings to watch for and respond to these.

Next steps

Congrats! You've created a Custom account. Now learn more about working with Custom accounts.