Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
Get started
Collect payments then pay out
Enable other businesses to accept payments directly
Pay out money
Explore Connect
Onboard your accounts
Choose your account type
Standard
Express
Custom
Onboard accounts
Update accounts
Handle verification
Handle verification with the API
Required info
Future requirements
Service agreement types
Payment methods
Account capabilities
Additional verifications
Update verified info
Connect embedded UIs
Quickstart
Get started with Connect embedded UIs
Accept payments
Create a charge
Create a payments page
Create payment links with Connect
Connect integration guide
Automatic payment methods
Set statement descriptors
Connect platforms using the Payment Methods API
Create subscriptions
Create invoices
Debit Express and Custom connected accounts
Pay out
Set bank and debit card payouts
Bank accounts
Manage payout schedule
Manual payouts
Payout reversals
Instant Payouts
Cross-border payouts
Crypto payouts
Manage funds
Add money to your platform balance
Account balance
Handle multiple currencies
Manage accounts
Best practices
Listen for updates
Dashboard account management
Understanding risk offerings
Platform controls for Standard accounts
Make API calls for connected accounts
Set MCCs
Testing
Manage tax forms
Overview
Get started with tax reporting
1099 Tax Support and Communication Guide
Tax form settings
Calculation methods
File tax forms
File tax forms with states
Identify forms with missing information
Update tax forms
Deliver tax forms
E-delivery for 1099 tax forms
Correct tax forms
Split tax forms
Tax year changeover
What's new for tax year 2022
Testing
Connect
·
HomePaymentsMultiparty payments

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:

  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.

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

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 your user, Stripe requests the information it needs from you. You must collect this information from your 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, Thailand, the United Kingdom, and the United States can create Custom accounts for any country Stripe supports. Certain restrictions apply when using Connect for Stripe Thailand. Contact us to be notified when platforms in your country can use Custom accounts.
  • Countries that don’t support self-serve: Due to restrictions that apply when using Connect for Stripe India, India-based merchants can’t self-serve Custom Connect accounts. To begin onboarding for Custom Connect Accounts in India, contact us.
  • Platforms in the UAE: Platforms in the UAE can only create Custom 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.

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.

Command Line
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 (for example, 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.

See also

Learn more about working with Custom accounts.

  • Updating Accounts
  • Identity Verification
  • Authentication
  • Creating Charges
  • Full API reference
Was this page helpful?
Questions? Contact us.
Watch our developer tutorials.
Check out our product changelog.
Powered by Markdoc
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
See also
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to Stripe docs and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$