Connect
Get started
Onboard your accounts
Accept payments
Pay out
Manage funds
Manage accounts
Sign in
Sign up
Support
Sign in

Using Connect with Custom accounts

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

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 needed to verify the account.

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:

  1. Properly identify the country to use.
  2. Create the account.
  3. 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 it must include a reference to Stripe’s services agreement. Stripe recommends that you 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 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, Bulgaria, Canada, Cyprus, the Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hong Kong, India, Ireland, Italy, Japan, Latvia, Lithuania, Luxembourg, Malta, Mexico, the Netherlands, New Zealand, Norway, Poland, Portugal, Romania, Singapore, Slovakia, Slovenia, 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 information.

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 the country the individual or business will primarily operate in. Everything else can be collected and updated at a later time.

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 a Custom account, set type to custom in the account creation request and provide a country and the appropriate capabilities.

curl https://api.stripe.com/v1/accounts \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d country=US \
  -d type=custom \
  -d "requested_capabilities[]"=card_payments \
  -d "requested_capabilities[]"=transfers

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

account = Stripe::Account.create({
  country: 'US',
  type: 'custom',
  requested_capabilities: ['card_payments', 'transfers'],
})

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

account = stripe.Account.create(
  country='US',
  type='custom',
  requested_capabilities=['card_payments', 'transfers'],
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$account = \Stripe\Account::create([
  'country' => 'US',
  'type' => 'custom',
  'requested_capabilities' => ['card_payments', 'transfers'],
]);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

AccountCreateParams params =
  AccountCreateParams.builder()
    .setCountry("US")
    .setType(AccountCreateParams.Type.CUSTOM)
    .addRequestedCapability(AccountCreateParams.RequestedCapability.CARD_PAYMENTS)
    .addRequestedCapability(AccountCreateParams.RequestedCapability.TRANSFERS)
    .build();

Account account = Account.create(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const account = await stripe.accounts.create({
  country: 'US',
  type: 'custom',
  requested_capabilities: ['card_payments', 'transfers'],
});

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.AccountParams{
  Type: stripe.String(string(stripe.AccountTypeCustom)),
  Country: stripe.String("US"),
  RequestedCapabilities: stripe.StringSlice([]string{
    string(stripe.AccountCapabilityCardPayments),
    string(stripe.AccountCapabilityTransfers),
  }),
}
acct, _ := account.New(params)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new AccountCreateOptions
{
  Type = "custom",
  Country = "US",
  RequestedCapabilities = new List<string>
  {
    "card_payments",
    "transfers",
  },
};

var service = new AccountService();
var account = service.Create(options);

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

{
  ...
  "id": "acct_12QkqYGSOD4VcegJ",
  "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.

The easiest way to collect this information is to integrate Connect Onboarding, which lets Stripe take care of the verification complexity. Otherwise, you must not only write your own API calls for initial integration, but also continue to check for changing onboarding requirements because of changing regulations around the world.

You can collect required information when you create the account or by updating the account later. At the very least, we recommend collecting and providing the user’s name and date of birth upfront. If you collect address information upfront, make sure to validate the state value for U.S., CA, and AU connected accounts in your onboarding flow.

Webhooks

After an account is created, all notifications about changes to the account are sent to your webhooks as account.updated events. Provide your Connect webhook URL in your account settings and then watch for these events and respond to them as needed.

Next steps

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

Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.
On this page
Requirements for creating Custom accounts
Identify the country to use
Create a Custom account
Start the identity verification process
Webhooks