# Stripe-hosted onboarding for Custom accounts

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

> #### Newer Connect integrations
> 
> The information on this page applies only to platforms that already use legacy connected account types. For information about onboarding connected accounts with Stripe-hosted onboarding, see [Stripe-hosted onboarding](https://docs.stripe.com/connect/hosted-onboarding.md).

[Connect Onboarding for Custom Accounts](https://stripe.com/connect/onboarding) 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* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) 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, [Furever](https://furever.dev/):
![Screenshot of Connect Onboarding form](https://b.stripecdn.com/docs-statics-srv/assets/hosted_onboarding_form.e59ba8300f563e43489953f06127f52c.png)

## How to use Connect Onboarding for Custom Accounts

1. Navigate to your [onboarding settings](https://dashboard.stripe.com/settings/connect/onboarding-interface) to customize the visual appearance of the form. You must provide the name, color, and icon of your brand. You must [collect bank account details within the form](https://dashboard.stripe.com/settings/connect/payouts/external_accounts), either manually or instantly with [Stripe Financial Connections](https://docs.stripe.com/financial-connections.md).
1. Create a new account and get the account ID, or use an existing account ID (in the form of `acct_XXXXXXXX`).
1. 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](https://docs.stripe.com/api/accounts.md). The more information provide through the API, the less information Connect Onboarding prompts your user for.
1. Call the [Account Links](https://docs.stripe.com/api/account_links.md) with the following parameters (see the [API ref](https://docs.stripe.com/api/account_links.md) for more):
   - `account`
   - `refresh_url`
   - `return_url`
   - `type`
   - `collection_options` (optional)
1. In the onboarding flow for your own platform, redirect your user to the `url` returned by [Account Links](https://docs.stripe.com/api/account_links.md).
1. 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* (Incremental onboarding is a type of onboarding where you gradually collect required verification information from your users. You collect a minimum amount of information at sign-up, and you collect more information as the connected account earns more revenue). *Upfront onboarding* (Upfront onboarding is a type of onboarding where you collect all required verification information from your users at sign-up) 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](https://docs.stripe.com/connect/identity-verification.md#onboarding-flows).

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 `collection_options.fields` parameter in your calls to [Account Links](https://docs.stripe.com/api/account_links.md). Here’s an example request:

```curl
curl https://api.stripe.com/v1/account_links \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_ID}}" \
  --data-urlencode "refresh_url=https://example.com/reauth" \
  --data-urlencode "return_url=https://example.com/return" \
  -d type=account_onboarding \
  -d "collection_options[fields]=eventually_due"
```

## Redirect your user to the Account Link URL

The response to your [Account Links](https://docs.stripe.com/api/account_links.md) request includes a value for the key `url`. Redirect your user to this link to send them into the flow. You can only use your Account Link URLs one time 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 enable **Collect external account information for accounts where the platform is responsible for collecting requirements** in your [payout onboarding settings](https://dashboard.stripe.com/settings/connect/payouts/external_accounts), or if the `treasury` capability is requested, the user must set up additional authentication with Stripe before entering the onboarding flow.

> 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 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 testing (for example, to test with localhost), but live mode only accepts HTTPS. Be sure you’ve swapped any testing URLs for HTTPS URLs before going live.

#### return_url

Stripe issues 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 *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 user is redirected to your `return_url`, check the state of the `requirements` attribute on their account. You can either listen to `account.updated` webhooks or retrieve the [Account](https://docs.stripe.com/api/accounts.md) object and inspect the state of its `requirements` attribute. 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)
- 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 cause them to become expired

Your `refresh_url` should trigger a method on your server to call [Account Links](https://docs.stripe.com/api/account_links.md) 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](https://docs.stripe.com/connect/handling-api-verification.md#verification-process) for this purpose. You can test handling new requirements (and how they might disable charges and *payouts* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit)) with our [test trigger cards](https://docs.stripe.com/connect/testing.md#trigger-cards).

When [upcoming requirements updates](https://support.stripe.com/user/questions/onboarding-requirements-updates) affect your connected accounts, we’ll notify you.

If you use embedded or Stripe-hosted onboarding, you can proactively collect information to fulfill [future requirements](https://docs.stripe.com/api/accounts/object.md#account_object-future_requirements). For embedded onboarding, include the `collectionOptions` attribute in the [embedded onboarding component](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md). For Stripe-hosted onboarding, specify the `collection_options` parameter when [creating account links](https://docs.stripe.com/api/account_links/create.md#create_account_link-collection_options).

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 **Collect external account information for accounts where the platform is responsible for collecting requirements** in your [payout onboarding settings](https://dashboard.stripe.com/settings/connect/payouts/external_accounts). Learn more about [managing bank accounts and debit cards](https://docs.stripe.com/connect/payouts-bank-accounts.md).

## 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](https://docs.stripe.com/api/account_links.md). `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 attributes that are already populated on the account object and allows your user to edit previously provided information. Provide an access point in your platform website to a `type=account_update` Account Link for users to make updates themselves (for example, when their address changes). Consider framing the link as “edit my profile” or “update my verification information.”

## Supported browsers

Hosted onboarding supports the same set of browsers that the [Stripe Dashboard currently supports](https://docs.stripe.com/dashboard/basics.md):

- The last 20 major versions of Chrome and Firefox
- The last two major versions of Safari and Edge
- The last two major versions of mobile Safari on iOS

Hosted onboarding isn’t supported when embedded through webviews. It’s only supported in standalone browsers.

## See also

- [Identity verification](https://docs.stripe.com/connect/identity-verification.md)