Skip to content
Create account or Sign in
The Stripe Docs logo
/
Create accountSign in

Using Connect with Custom connected accountsLegacy

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

Newer Connect integrations

The information on this page applies only to platforms that already use legacy connected account types. If you’re setting up a new Connect platform, or your integration uses the Accounts v2 API, see Configure the behavior of connected accounts to learn about connected account configurations. If your integration uses the Accounts v1 API, see Account controller properties.

A Custom connected account is almost completely invisible to the account holder. You, the platform, are responsible for all interactions with your connected accounts and for collecting all the information needed to verify each account.

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

Creating a Custom connected account involves the following steps:

  1. Make sure you meet the minimum requirements.
  2. Properly identify the country and any related requirements.
  3. Create the account.
  4. Complete the identity verification process.

Identity verification requirements are updated as laws and regulations change globally. 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.

Note

To comply with French PSD2 regulations, platforms in France must use account tokens. An additional benefit of tokens is that the platform doesn’t have to store PII data, which is transferred from the connected account directly to Stripe. For platforms in other countries, we recommend using account tokens, but they aren’t required.

Requirements for creating Custom connected accounts

To use Custom connected 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 connected 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 your connected account user, Stripe requests the information it needs from you. You must collect that information from your connected account and provide it to Stripe. Otherwise, Stripe might 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, Thailand, the United Kingdom, and the United States can create Custom accounts for any country Stripe supports. Contact us to be notified when platforms in your country can use Custom connected accounts.
  • Countries that don’t support self-serve: Due to restrictions that apply when using Connect in the United Arab Emirates, India, and Thailand, platform users in these countries can’t self-serve Custom connected accounts. To begin onboarding for Custom connected accounts in these countries, contact us.
  • Platforms in the UAE: Platforms in the UAE can only use Custom connected accounts based in the UAE with the following charge types: destination_charges and separate charges and transfers. Destination charges using the on_behalf_of attribute are not yet supported for UAE platforms.

Caution

Platforms outside of Mexico that want to create Custom connected accounts in Mexico and make them settlement merchants require further review. Contact us to start the process.

  • Vetting for fraud: Because your platform is responsible for losses incurred by Custom connected accounts, you must scrutinize all accounts that sign up through your platform for potential fraud. Refer to our risk management best practices guide for more information.

Note there’s an additional cost for active Custom connected accounts. A Custom connected 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 connected account is the country where the individual or business primarily operates. You can collect everything else at a later time.

For example, if you’re in the United States and the business or individual you’re creating a connected account for is legally represented in Canada, assign CA as the country.

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

Create a Custom connected account

The basic process to create and connect a Custom connected account is to call the account creation endpoint, setting type to custom and providing a country and the appropriate capabilities.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results

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

Stripe supports cross-border transfers on the payments balance between the United States, Canada, United Kingdom, EEA, and Switzerland. In other scenarios, your platform and any connected account must be in the same region. Attempting to transfer funds across unsupported borders or balances returns an error. See Cross-border payouts for supported funds flows between other regions.

You must only use transfers in combination with the permitted use cases for charges, tops-ups and fees. We recommend using separate charges and transfers only when you’re responsible for negative balances of your connected accounts.

The result of a successful API call is the connected account information:


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

Note

Store the received account ID. You need this information to perform requests on the connected account’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 connected account user’s name and date of birth up front. If you collect address information upfront, make sure to validate the state value for US, CA, and AU connected accounts in your onboarding flow.

Note

For accounts with business_type set to individual, provide at least one individual property (for example, individual.first_name) and a Person object is created automatically. If you don’t, or for 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.

See also

Proxying: stripe.com/docs/connect/managed-accounts ✕