Using Connect with Express accounts

Before onboarding your first account, go to the Connect settings page to customize the visual appearance of the form with your brand’s name, color, and icon. Connect Onboarding requires this information.

Create an Express account and set type to express in the account creation request.

curl https://api.stripe.com/v1/accounts \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d type=express

If you know the country and capabilities for your connected account, you can provide that information when you create the account. Connect Onboarding then collects the requirements for those capabilities. To reduce onboarding effort, only request the capabilities you need.

If you collect information from your connected account users as part of your sign up flow, you can prefill that information on the account object for the user and the Connect Onboarding flow won’t collect that information again. If you’re onboarding an individual without their own website, be sure to prefill the account’s business_profile.url if your platform provides the user with a personal URL. If the user does not have a URL, you can provide business_profile.product_description instead.

To learn more about the information you’ll need to collect from accounts for your use case, see Required verification information.

curl https://api.stripe.com/v1/accounts \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d country=US \
  -d type=express \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true \
  -d business_type=individual \
  -d "business_profile[url]"="https://example.com"

If you’ve already collected information for your connected accounts, you can pre-fill that information on the account object for the user. Connect Onboarding won’t ask for the pre-filled information during account onboarding. The account holder confirms the pre-filled information before accepting the Connect service agreement. You can pre-fill any information on the account, including personal and business information, external account information, and more.

Use test data to prefill when testing your integration.

If you omit capabilities, Connect Onboarding uses the settings in the Configuration settings section of the Stripe Dashboard to automatically request capabilities based on the country for the connected account.

You can create an account link with the following parameters:

• account - use the account ID returned by the API from the previous step
• refresh_url
• return_url
• type = account_onboarding

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

The response to your Account Links request includes a value for the key url. Redirect to this link to send your user into the flow. URLs from Account Links are temporary and can only be used once because they grant access to the account holder’s personal information. Authenticate the user in your application before redirecting them to this URL. If you want to prefill information, you must do so before generating the account link. After you create the account link for an Express account, you won’t be able to read or write information for the account.

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

return_url

Stripe issues a redirect to this URL when the user completes the Connect Onboarding flow. This doesn’t mean that all information has been collected or that there are no outstanding requirements on the account. This only means the flow was entered and exited properly.

No state is passed through this URL. After a user is redirected to your return_url, check the state of the details_submitted parameter on their account by doing either of the following:

• Listen to account.updated events with a Connect webhook.
• Retrieve the account with the API.

refresh_url

Your user is redirected to the refresh_url in these cases:

• The link is expired (a few minutes went by since the link was created).
• The user already visited the URL (the user refreshed the page or clicked back or forward in the browser).
• Your platform can no longer access the account.
• The account has been rejected.

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

A user that’s redirected to your return_url might not have completed the onboarding process. Retrieve the user’s account and check for charges_enabled. If the account isn’t fully onboarded, provide UI prompts to allow the user to continue onboarding later. The user can complete their account activation through a new account link (generated by your integration). You can check the state of the details_submitted parameter on their account to see if they’ve completed the onboarding process.