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
Overview
Online payments
Products and prices
Invoicing
Subscriptions
Quotes
In-person payments
Multiparty payments
    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
After the payment
Add payment methods
Payment Links
Stripe Checkout
Stripe Elements
About the APIs
Regulation support
Implementation guides
Testing
Connect
·
HomePaymentsMultiparty paymentsCustom

Connect Onboarding for Custom accounts

Let Stripe collect identity verification information for your Custom connected accounts.

Connect Onboarding for Custom Accounts is a web form hosted by Stripe that takes care of collecting identity verification information from users. It dynamically adjusts the information that it collects to reflect the connected account’s capabilities, country, and business type. Connect Onboarding is the recommended solution to collect identity verification information for Custom accounts, and ensures that your flow is optimized for:

  • Mobile browsers
  • Accessibility
  • Internationalization and localization
  • Conversion rate
  • Intelligently requesting requirements based on what’s already provided on the account

Here’s what the form looks like for Stripe’s sample integration, Rocket Deliveries:

Screenshot of Connect Onboarding form

How to use Connect Onboarding for Custom Accounts

  1. Go to your Connect settings page to customize the visual appearance of the form: you can provide the name, color, and icon of your brand. You must provide this information for Connect Onboarding to work. Stripe recommends collecting bank account details within the form, either manually or instantly with Stripe Financial Connections.
  2. Create a new account and get the account ID, or use an existing account ID (in the form of acct_XXXXXXXX).
  3. If you have information about the account holder (like their name, address, or other details), you can proactively provide this through the account create or update methods. The more information provide through the API, the less information Connect Onboarding prompts your user for.
  4. Call the Account Links with the following parameters (see the API ref for more):
    • account
    • refresh_url
    • return_url
    • type
    • collect (optional)
  5. In the onboarding flow for your own platform, redirect your user to the url returned by Account Links.
  6. Handle additional account states, redirecting your user back into the Connect Onboarding flow if necessary. To handle user-initiated updates to information they’ve already provided, create a way for your user to get a new redirect to the Connect Onboarding form from your platform’s Dashboard.

Determine the information to collect

Connect Onboarding for Custom Accounts supports upfront or incremental onboarding. Upfront onboarding collects the eventually_due requirements for the account, while incremental onboarding collects the currently_due requirements. For the advantages and disadvantages of each, see the onboarding flows documentation.

The currently_due requirements request only the user information needed for verification at this specific point in time; the eventually_due requirements include a more complete set of questions that we’ll eventually need to collect.

Based on the needs of your platform, pass either currently_due or eventually_due as the value of the collect parameter in your calls to Account Links. Here’s an example request:

Command Line
curl https://api.stripe.com/v1/account_links \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d account=
{{CONNECTED_ACCOUNT_ID}}
\ -d refresh_url="https://example.com/reauth" \ -d return_url="https://example.com/return" \ -d type=account_onboarding \ -d collect=eventually_due

Redirect your user to the Account Link URL

The response to your Account Links request includes a value for the key url. Redirect your user to this link to send them into the flow. Account Link URLs are short-lived and can be used only once because they grant access to the account holder’s personal information. Be sure to authenticate the user in your application before redirecting them to this URL.

Don’t email, text, or otherwise send account link URLs directly to your user. Instead, redirect the authenticated user to the account link URL from within your platform’s application.

Handle the user returning to your platform

Connect Onboarding requires you to pass both a return_url and refresh_url to handle all cases in which the user will be redirected back to your platform. It’s important that you implement these correctly to provide the best experience for your user.

You can use HTTP for your return_url and refresh_url while you’re in test mode (for example, to test with localhost), but for live mode only HTTPS is accepted. Be sure you’ve swapped any testing URLs for HTTPS URLs before going live.

return_url

Stripe will issue a redirect back to this URL when the user completes the Connect Onboarding flow, or clicks Save for later at any point in the flow. It does not mean that all information has been collected, or that there are no outstanding requirements on the account. It only means the flow was entered and exited properly.

No state is passed with this URL. After a user is redirected to your return_url, check the state of the requirements hash on their account, either by listening to account.updated webhooks, or calling the Accounts and inspecting the state of the requirements hash. See more details in Step 4 below.

refresh_url

Your user will be redirected to the refresh_url in these cases:

  • The link is expired (a few minutes went by since the link was created)
  • The link was already visited (the user refreshed the page or clicked the back/forward button)

Your refresh_url should trigger a method on your server to call Account Links again, with the same parameters, and redirect the user back into the Connect Onboarding flow to create a seamless experience.

Handle the case of new requirements becoming due

Set up your integration to listen for changes to account requirements, if you haven’t already done so. We recommend using webhooks to do so. You can test handling new requirements (and how they may disable charges and payouts) with our test mode trigger cards.

Based on the verification needs of your application, send the user back into Connect Onboarding as necessary to satisfy currently_due or eventually_due requirements as described in step 1. You can use this as a signal of when to send your user back into the flow. Keep in mind that using Connect Onboarding means you don’t really need to worry about what the requirements are – sending the user back into Connect Onboarding means it will collect the right information.

For example, if your user mistypes their information and they can’t be verified, they could be asked to provide an Identity Document (for example, a Driver’s License in the United States). Sending this user into Connect Onboarding prompts them to upload such a document to ensure they become verified.

Connect Onboarding for Custom Accounts doesn’t collect the external_account requirement by default. To collect external_account, enable the Collect bank account information for payouts setting in Connect Settings. For more detailed instructions, refer to the Managing bank accounts and debit cards guide.

Handle the case of user-initiated updates

Most Connect Onboarding usage discussed thus far has been about prompting the user to provide new information. Connect Onboarding also supports user-initiated updates to the information they’ve already provided in the type parameter of the Account Link. type accepts one of two values: account_onboarding or account_update.

account_onboarding

This value for type provides a form for inputting outstanding requirements. Use it when you’re onboarding a new user, or when an existing user has new requirements; such as when a user had already provided enough information, but you requested a new capability that needs additional info. Send the user to the form in this mode to just collect the new information you need.

account_update

This value for type displays the fields that are already populated on the account object, and allows your user to edit previously provided information. Provide an access point in your platform’s dashboard to a type=account_update Account Link, for users to initiate updates themselves (for example, when their address changes). Consider framing this as “edit my profile” or “update my verification information.”

See also

  • Identity verification
Was this page helpful?
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
How to use Connect Onboarding for Custom Accounts
Determine the information to collect
Redirect your user to the Account Link URL
Handle the user returning to your platform
Handle the case of new requirements becoming due
Handle the case of user-initiated updates
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 your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe 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.
$