Using Connect with Express connected 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.

Use the Create Account API to create a connected account with type set to express. You can prefill any information, but at a minimum, you must specify the type. The country of the account defaults to the same country as your platform, and the account confirms the selection during onboarding.

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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, request only the capabilities you need.

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

If you’ve already collected information for your connected accounts, you can prefill that information on the Account object. You can prefill any account information, including personal and business information, external account information, and so on.

After creating an account, create a Person with relationship.representative set to true to represent the person responsible for opening the account and any account information you want to prefill (for example, their first and last name).

curl https://api.stripe.com/v1/accounts/
{{ACCOUNT_ID}}
/persons \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d first_name=Jenny \
  -d last_name=Rosen \
  -d "relationship[representative]"=true

Connect Onboarding doesn’t ask for the prefilled information. However, it does ask the account holder to confirm the prefilled information before accepting the Connect service agreement.

When you onboard an account without its own website and your platform provides it with a personal URL, prefill its business_profile.url. If the account doesn’t have a URL, you can prefill its business_profile.product_description instead.

When testing your integration, prefill account information using test data.

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 account’s country.

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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
"{{CONNECTED_ACCOUNT_ID}}" \
  --data-urlencode refresh_url="https://example.com/reauth" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding

An Account Link contains a url. Redirect the account to this link to send your account into the onboarding flow. Each Account Link URL can only be used once because it grants access to the account holder’s personal information. Authenticate the account in your application before redirecting them to this URL.

Before creating the first account link for an Express connected account, prefill any Know Your Customer (KYC) information. After you create an account link for an Express connected account, you can’t read or update its KYC information.

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

return_url

Stripe issues a redirect to this URL when the connected account 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 connected account 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 connected account is redirected to the refresh_url in these cases:

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

Set up your refresh_url to trigger a method on your server to call Account Links again with the same parameters, and redirect the connected account to the Connect Onboarding flow to create a seamless experience.

A connected account that’s redirected to your return_url might not have completed the onboarding process. Retrieve their account and check for charges_enabled. If the account isn’t fully onboarded, provide UI prompts to allow them to continue onboarding later. They 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.