Using Connect with Custom accounts

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

Identity verification requirements are updated as laws and regulations change around the world. If you’re building your own onboarding flow to onboard accounts, you must plan on reviewing and updating onboarding requirements at least every six months. To avoid this maintenance obligation, use Connect Onboarding for Custom 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 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:

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

But first, ensure you meet the minimum requirements.

French platforms must use account tokens, which are an alternative to the agent model for platform PSD2 compliance. The key benefit of tokens for French platforms is that information is transferred from the user directly to Stripe. Not having to store PII data is still a benefit, but not necessarily a requirement. For platforms in other countries, account tokens are optional but recommended.

Requirements for creating Custom accounts

Custom accounts are generally available in the U.S. and are in beta in all other countries. 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. You can view and upgrade your API version in the Dashboard if needed.
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, Brazil, Bulgaria, Canada, Cyprus, the Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hong Kong, Hungary, 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.

Platforms not located in Mexico that want to create Custom accounts in Mexico and make those accounts the settlement merchants require further review. Contact us to start the process.

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.

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.

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.

Terminal

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

U.S. platforms can create accounts for cross-border transfers by specifying the recipient service agreement.

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.

Store the received account ID. You need this information to perform requests on the user’s behalf.

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.

If you create accounts with the business_type set to individual, you need to provide at least one individual property (e.g., individual[first_name] so that a Person object is created automatically. If you create accounts with the business_type set to company, you need to create each Person for the account.

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

Learn more about working with Custom accounts.