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

Onboard your connected account

Onboard your connected accounts to your marketplace.

After you create and prefill a connected account, create an Account Link and send it to the user so they can complete the onboarding process. An Account Link is a single-use URL that you send to a connected account that grants them permission to access the Connect onboarding flow.

Alternatively, you can also build out a custom onboarding flow using embedded components or the API. To streamline compliance and maintenance, use Accounts Links or create your own onboarding flow with embedded components. This guide uses Account Links.

The Connect onboarding flow doesn’t ask your connected account for any information that you prefilled. However, it does ask the connected account to confirm the prefilled information before they accept the Connect service agreement.

Note

Stripe-hosted onboarding is only supported in web browsers. You can’t use it in embedded web views inside mobile or desktop applications.

Create an Account Link

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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
ParameterValueRequired?Description
accountThe ID of the connected accountYesSet this to the ID of the connected account you’re creating an Account Link for.
return_urlA valid URLYesThe URL to redirect the user to after they leave or complete the onboarding flow.
refresh_urlA valid URLYesThe URL to redirect the user to if the Account Link expired, was previously visited, or is otherwise invalid. Use this URL to generate a new Account Link with the same parameters you used to create the original Account Link.
typeaccount_onboardingYesProvides a form to just collect the new information you need.

Redirect your user to the Account Link URL

The response to your Account Links request includes a value for the key url. Redirect to this link to send the connected account into the onboarding flow.

URLs from the Account Links API are temporary and can only be used once, because they grant access to the connected account user’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, you can’t read or write information for the connected account.

Security tip

Don’t email, text, or otherwise send account link URLs outside of your platform application. Instead, provide them to the authenticated account holder within your 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 where the user is redirected to your platform. It’s important that you implement these correctly to provide the best experience for your user.

Note

You can use HTTP for your return_url and refresh_url while you’re in a testing environment (for example, to test with localhost), but live mode only accepts HTTPS. Be sure to swap testing URLs for HTTPS URLs before going live.

Set the return URL

Stripe redirects the connected account back to the return_url when they complete the onboarding flow or click Save for later at any point in the flow. It doesn’t 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 connected account is redirected to the return_url, determine if the account has completed onboarding by either:

  • Retrieving the account and checking the requirements hash for outstanding requirements.
  • Listening to the account.updated event sent to your webhook endpoint and caching the state of the account in your application. If the account hasn’t completed onboarding, provide prompts in your application to allow them to continue onboarding later.

Set the refresh URL

Stripe redirects your user to the refresh_url in these cases:

  • The link expired (a few minutes elapsed after 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 is no longer able to access the account.
  • The link was shared in a third-party application such as a messaging client that attempts to access the URL to preview it. Many clients automatically visit links, which causes an Account Link to expire.
  • The account has been rejected.

Configure the refresh_url to call a method on your server to call Account Links again to create a new Account Link with the same parameters, then redirect the connected account to the new Account Link URL.

Handle users who haven't completed onboarding

A user who’s redirected to your return_url might not have completed the onboarding process. To see if a user has completed the onboarding process, retrieve the user’s account and check that details_submitted set to true. If details_submitted is false, the account isn’t fully onboarded. Provide UI prompts in your application to allow the user to continue onboarding later. The user can complete their account activation through a new Account Link generated by your integration.

Next steps

Next, enable the payment methods that you want to support.

Was this page helpful?
YesNo