Stripe-hosted onboarding

Go to the Connect settings page in the Dashboard to customize the visual appearance of the form with your brands name, color, and icon. Stripe-hosted onboarding requires this information. Stripe also recommends collecting bank account information from your connected accounts as theyre onboarding.

Create a connected account with the default controller properties. See design an integration to learn more about controller properties. Alternatively, you can create a connected account by specifying an account type.

If you specify the accounts country or request any capabilities for it, then the account owner cant change its country. Otherwise, it depends on the accounts Dashboard access:

• Full Stripe Dashboard: During onboarding, the account owner can select any acquiring country, the same as when signing up for a normal Stripe account. Stripe automatically requests a set of capabilities for the account based on the selected country.
• Express Dashboard: During onboarding, the account owner can select from a list of countries that you configure in your platform Dashboard Onboarding options. You can also configure those options to specify the default capabilities to request for accounts in each country.
• No Stripe Dashboard: If Stripe is responsible for collecting requirements, then the onboarding flow lets the account owner select any acquiring country. Otherwise, your custom onboarding flow must set the country and request capabilities.

curl https://api.stripe.com/v1/accounts \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -d "controller[fees][payer]=application" \
  -d "controller[losses][payments]=application" \
  -d "controller[stripe_dashboard][type]=express"

The response includes the ID, which you use to reference the Account throughout your integration.

Request capabilities

You can request capabilities when creating an account by setting the desired capabilities requested property to true. For accounts with access to the Express Dashboard, you can also configure your Onboarding options to automatically request certain capabilities when creating an account.

Stripes onboarding UIs automatically collect the requirements for requested capabilities. To reduce onboarding effort, request only the capabilities you need.

Prefill information

If you have information about the account holder (like their name, address, or other details), you can simplify onboarding by providing it when you create or update the account. The onboarding interface asks the account holder to confirm the pre-filled information before accepting the Connect service agreement. The account holder can edit any pre-filled information before they accept the service agreement, even if you provided the information using the Accounts API.

If you onboard an account and your platform provides it with a URL, prefill the accounts business_profile.url. If the business doesnt have a URL, you can prefill its business_profile.product_description instead.

When testing your integration, use test data to simulate different outcomes including identity verification, business information verification, payout failures, and more.

As the platform, you must decide if you want to collect the required information from your connected accounts up front or incrementally. Up-front onboarding collects the eventually_due requirements for the account, while incremental onboarding only collects the currently_due requirements. You can control this behavior using the collection_options.fields parameter.

To determine whether to use up-front or incremental onboarding, review the requirements for your connected accounts locations and capabilities. While Stripe tries to minimize any impact to connected accounts, requirements might change over time.

For connected accounts where youre responsible for requirement collection, you can customize the behavior of future requirements using the collection_options parameter. To collect the accounts future requirements, set collection_options.future_requirements to include.

Collect additional public details

Stripe collects the required public details for each connected account. You can choose additional fields to collect during onboarding according to your business needs. Any fields you choose that Stripe doesnt require appear as optional, and connected accounts can choose whether to provide them.

1. In the Public details settings in the Dashboard, enable the Collect public details toggle.
2. Select the fields to show to connected accounts during onboarding.
3. Click Save.

Available fields

You can collect the following public details:

Create an Account Link using the connected account ID and include a refresh URL and a return URL. Stripe redirects the connected account to the refresh URL if the Account Link URL has already been visited, has expired, or is otherwise invalid. Stripe redirects connected accounts to the return URL when they have completed or left the onboarding flow. Additionally, based on the information you need to collect, pass either currently_due or eventually_due for collection_options.fields. This example passes eventually_due to use up-front onboarding. For incremental onboarding, set it to currently_due.

curl https://api.stripe.com/v1/account_links \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -d "account=
{{CONNECTED_ACCOUNT_ID}}" \
  --data-urlencode "refresh_url=https://example.com/refresh" \
  --data-urlencode "return_url=https://example.com/return" \
  -d type=account_onboarding \
  -d "collection_options[fields]=eventually_due"

Redirect your connected account to the Account Link URL

Redirect the connected account to the Account Link URL to send them to the onboarding flow. You can only use each temporary Account Link URL once, because it grants access to the account holders personal information. Authenticate the account in your application before redirecting them to this URL. Prefill any account information before generating the Account Link because you cant read or write information for the connected account afterward.

import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

Set up your integration to listen for changes to account requirements. You can test handling new requirements (and how they might disable charges and payouts) with the test trigger cards.

Send a connected account back through onboarding when it has any currently_due or eventually_due requirements. You dont need to identify the specific requirements, because the onboarding interface knows what information it needs to collect. For example, if a typo is preventing verification of the account owners identity, onboarding prompts them to upload an identity document.

Stripe notifies you about any upcoming requirements updates that affect your connected accounts. You can proactively collect this information by reviewing the future requirements for your accounts.

For connected accounts where controller.requirement_collection is stripe, stop receiving updates for identity information after creating an Account Link or Account Session.

Accounts store identity information in the company and individual hashes.

Handle verification errors

Listen to the account.updated event. If the account contains any currently_due fields when the current_deadline arrives, the corresponding functionality is disabled and those fields are added to past_due.

Let your accounts remediate their verification requirements by directing them to the Stripe-hosted onboarding form.

The Account Link requires a refresh_url and return_url to handle all cases in which the connected account is redirected back to your platform. Its important to implement these correctly to provide the best onboarding flow for your connected accounts.

Refresh URL

Your connected account is redirected to the refresh_url when:

• The link is expired (a few minutes went by since the link was created).
• The link was already visited (the connected account refreshed the page or clicked the back or 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 causes an Account Link to expire.

The refresh_url should call a method on your server to create a new Account Link with the same parameters and redirect the connected account to the new Account Link URL.

Return URL

Stripe redirects the connected account back to this URL when they complete the onboarding flow or click Save for later at any point in the flow. It doesnt 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. Retrieve the account and check the requirements hash for outstanding requirements. Alternatively, listen to the account.updated event sent to your webhook endpoint and cache the state of the account in your application. If the account hasnt completed onboarding, provide prompts in your application to allow them to continue onboarding later.

For information about tracking the status of connected accounts during the onboarding process, see Track connected account onboarding status.

Stripe-hosted onboarding also supports connected account-initiated updates to the information theyve already provided. Listen to the account.updated event sent to your webhook endpoint to be notified when the account completes requirements and updates their information.

When you create an Account Link, you can set the type to either account_onboarding or account_update.

Account Links for account_onboarding

Account Links of this type provide a form for inputting outstanding requirements. Use it when youre onboarding a new connected account, or when an existing user has new requirements (such as when a connected account had already provided enough information, but you requested a new capability that needs additional info). Send them to this type of Account Link to just collect the new information you need.

Account Links for account_update

Account Links of this type are enabled for accounts where your platform is responsible for requirement collection. account_update links display the attributes that are already populated on the account object and allow the connected account to edit previously provided information. Provide an option in your application (for example, edit my profile or update my verification information) for connected accounts to make updates themselves.