# Migrating accounts to Stripe Start processing accounts on Stripe without disrupting payments. You can migrate an existing multiparty payments business to Stripe, including historical payment and customer data. Depending on the nature of your business, you can set up a *marketplace* (A Connect platform that provides a platform-branded storefront for products and services from its connected accounts) or a *SaaS platform* (A Software as a Service (SaaS) Connect platform that provides Stripe products and services to its connected accounts). To migrate to a Connect integration and configure *connected accounts* (A person or business accepting payments or receiving payouts on a Connect platform) representing your client businesses, follow this process: 1. Create a migration plan and timeline 1. Update your integration for connected accounts 1. Create and onboard accounts 1. Handle outstanding and ongoing requirements 1. Migrate payment and customer data to Stripe ## Create a migration plan A successful migration to Stripe includes a migration plan, a timeline, and KYC information for connected accounts, as well as payment and customer data. Connected accounts must onboard to Stripe, which requires sending Stripe Know Your Customer (KYC) data for each account. Stripe can also require collecting information from your accounts. Perform an analysis to understand what data you collected with your previous provider and what data Stripe requires. Stripe verifies KYC data before activating connected accounts. Monitor account verification status using the [account.updated](https://docs.stripe.com/api/events/types.md#event_types-account.updated) event or the [Retrieve Account](https://docs.stripe.com/api/account/retrieve.md) API. Accounts that fail to verify require action before they’re activated. Include a hard cutover date for payment data after onboarding accounts to Stripe. Payment and customer data requires [a PAN import](https://docs.stripe.com/get-started/data-migrations/pan-import.md) as part of the cutover. We recommend that you import accounts in batches. ## Update your integration Your application can require changes as part of the integration updates to migrate to Stripe. For example, consider any changes to your connected accounts’ usage of your platform, such as pricing updates. Stripe recommends communicating any changes to your accounts ahead of time. ### Stripe terms of service agreement Your connected accounts must accept the Stripe terms of service before they’re activated. For accounts where Stripe is responsible for collecting updated information when requirements are due or change (including Standard and Express accounts), the account accepts Stripe’s terms of service as part of the onboarding flow. If your platform is responsible for [collecting updated information](https://docs.stripe.com/connect/required-verification-information.md) from a connected account (including Custom accounts) when requirements change, you can [wrap Stripe’s terms of service in your own terms of service](https://docs.stripe.com/connect/updating-service-agreements.md#adding-stripes-service-agreement-to-your-terms-of-service). We recommend placing terms of service acceptance at the end of the onboarding flow, but you can also have it at the start if that makes more sense for your business. When creating or updating connected accounts, record acceptance of the [updated Terms of Service information](https://docs.stripe.com/api/accounts/update.md#update_account-tos_acceptance) to send to Stripe, and communicate that to the accounts. ### Onboard connected accounts to Stripe Stripe offers different levels of onboarding support for your connected accounts. Build an onboarding flow for your connected accounts using any of the following methods: | Method | Pros | Cons | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Stripe-hosted onboarding](https://docs.stripe.com/connect/custom/onboarding.md#stripe-hosted-onboarding) | - Lowest effort integration | - Stripe-branded with limited platform branding - Limited control over the flow logic - Connected accounts redirect to Stripe instead of completing the process without leaving your site | | [Embedded onboarding](https://docs.stripe.com/connect/custom/onboarding.md#embedded-onboarding) | - [Highly themeable](https://docs.stripe.com/connect/customize-connect-embedded-components.md) - Limited or no Stripe branding - Connected accounts remain in the flow of your site - Low effort integration | - Limited control over the flow logic | | [API-based onboarding](https://docs.stripe.com/connect/custom/onboarding.md#api-based-onboarding) | - Exercise full control over your own UI | - Expensive and time-consuming to build - Continuing high maintenance, especially to keep in compliance with changing global requirements - Can’t resolve Stripe risk reviews | ## Create and onboard accounts The following is an overview of the process: (See full diagram at https://docs.stripe.com/connect/migrate-to-stripe) ### Establish account requirements The following factors affect the [onboarding requirements](https://docs.stripe.com/connect/required-verification-information.md) for your connected accounts: - The origin country of the connected accounts - The [service agreement type](https://docs.stripe.com/connect/service-agreement-types.md) applicable to the connected accounts - The [capabilities](https://docs.stripe.com/connect/account-capabilities.md) requested for the connected accounts - The [business_type](https://docs.stripe.com/api/accounts/object.md#account_object-business_type) (for example, individual or company) and [company.structure](https://docs.stripe.com/api/accounts/object.md#account_object-company-structure) (for example, `public_corporation` or `private_partnership`) Use the [Required Verification Information](https://docs.stripe.com/connect/required-verification-information.md) tool to see how changing these factors affects the onboarding requirements for your connected accounts. ### Create the connected account For each account to be migrated to Stripe, create an associated Account. Create a connected account that specifies any desired account preferences. You can prefill any information, but you must specify the `controller` properties. The country of the account defaults to the same country as your platform, and the account confirms the selection during onboarding. > This example includes only some of the properties you can set when creating an account. For a full list of the properties you can set, such as address and URL information, see [Create Account](https://docs.stripe.com/api/accounts/create.md). ```curl curl https://api.stripe.com/v1/accounts \ -u "<>:" \ -d "controller[fees][payer]=account" \ -d "controller[losses][payments]=stripe" \ -d "controller[stripe_dashboard][type]=none" \ -d "controller[requirement_collection]=stripe" \ -d country=US \ -d "capabilities[card_payments][requested]=true" \ -d "capabilities[transfers][requested]=true" ``` If you’ve already collected information for your connected accounts, you can pre-fill that information on the `Account` object. You can pre-fill any account information, including personal and business information, external account information, and so on. After creating the `Account`, create a [Person](https://docs.stripe.com/api/persons/create.md) to represent the person responsible for opening the account, with `relationship.representative` set to true and any account information you want to prefill (for example, their first and last name). ```curl curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}}/persons \ -u "<>:" \ -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](https://docs.stripe.com/connect/service-agreement-types.md). When testing your integration, prefill account information using [test data](https://docs.stripe.com/connect/testing.md). Store the ID of the created `Account` so you can reference it later. After updating Stripe with all existing data, look for any outstanding requirements. Any outstanding requirements are listed in the `currently_due` array. All `currently_due` requirements need to be collected from the account for Stripe to verify the account and activate the account’s capabilities. ```json { ... "requirements": { "alternatives": [], "current_deadline": null"currently_due": [ "business_profile.url", "external_account", "individual.first_name", "individual.last_name", "tos_acceptance.date", "tos_acceptance.ip" ], "disabled_reason": "requirements.past_due", "errors": [], "eventually_due": [ "business_profile.url", "external_account", "individual.first_name", "individual.last_name", "individual.id_number", "tos_acceptance.date", "tos_acceptance.ip" ], "past_due": [ "business_profile.url", "external_account", "individual.first_name", "individual.last_name", "tos_acceptance.date", "tos_acceptance.ip" ], "pending_verification": [] }, ... } ``` After providing all existing data on an account, direct the account to a Stripe UI to set up Stripe credentials, confirm the information, and accept the Stripe terms of service. ### Take new accounts through an onboarding flow In addition to migrating existing accounts, build a flow for new accounts to onboard to Stripe. You can also use this onboarding flow to collect missing data for accounts being migrated. Review [onboarding options](https://docs.stripe.com/connect/onboarding.md) to create your onboarding flow. Store the ID of the created `Account` so you can reference it later. ## Handle outstanding and ongoing requirements When the connected account’s data is submitted, Stripe verifies it. This process might take minutes or hours, depending on the nature of the verification. During this process, the capabilities you requested have a `status` of `pending`. ### Review status You can retrieve the status of your connected account’s capabilities by: - Inspecting the Account object’s [capabilities](https://docs.stripe.com/api/accounts/object.md#account_object-capabilities) hash for the relevant capability. - Requesting capabilities directly from the [Capabilities API](https://docs.stripe.com/api/capabilities/retrieve.md) and inspecting the status of the relevant capability. - Listening for `account.updated` [events](https://docs.stripe.com/api/events/types.md#event_types-account.updated) in your [webhook](https://docs.stripe.com/connect/webhooks.md) endpoint and inspecting the `capabilities` hash for the relevant capability. After verifications are complete, a capability becomes `active` and available to the connected account. Account verifications run continuously, and if a future verification fails, a capability can transition out of `active`. Listen for `account.updated` events to detect changes to capability states. Confirm that your Connect integration is compliant and operational by checking that the account’s `charges_enabled` and `payouts_enabled` are both true. You can use the API or listen for `account.updated` events. For details on other relevant fields, check the account’s [requirements](https://docs.stripe.com/api/accounts/object.md#account_object-requirements) hash. You can’t confirm the integration based on a single value because statuses can vary depending on the application and related policies. - [charges_enabled](https://docs.stripe.com/api/accounts/object.md#account_object-charges_enabled) confirms that your full charge path including the charge and transfer works correctly and evaluates if either `card_payments` or `transfers` capabilities are active. - [payouts_enabled](https://docs.stripe.com/api/accounts/object.md#account_object-payouts_enabled) evaluates whether your connected account can pay out to an external account. Depending on your risk policies, you can allow your connected account to start transacting without payouts enabled. You [must eventually enable payouts](https://docs.stripe.com/connect/manage-payout-schedule.md) to pay your connected accounts. You can use the following logic as a starting point for defining a summary status to display to your connected account. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. Stripe.api_key = '<>' def account_state(account) reqs = account.requirements if reqs.disabled_reason && reqs.disabled_reason.include?("rejected") "rejected" elsif account.payouts_enabled && account.charges_enabled if reqs.pending_verification "pending enablement" elsif !reqs.disabled_reason && !reqs.currently_due if !reqs.eventually_due "complete" else "enabled" end else "restricted" end elsif !account.payouts_enabled && account.charges_enabled "restricted (payouts disabled)" elsif !account.charges_enabled && account.payouts_enabled "restricted (charges disabled)" elsif reqs.past_due "restricted (past due)" elsif reqs.pending_verification "pending (disabled)" else "restricted" end end accounts = Stripe::Account.list(limit: 10) accounts.each do |account| puts "#{account.id} has state: #{account_state(account)}" end ``` ### Handle verification errors Handle verification failures differently depending on your onboarding flow. > You can’t use the API to respond to Stripe risk reviews. You can enable your connected accounts to respond using embedded components, Stripe-hosted onboarding, or remediation links. You can also use the Dashboard to respond to risk reviews on behalf of your connected accounts. #### API Listen to the [account.updated](https://docs.stripe.com/api/events/types.md#event_types-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`. [Create a form](https://docs.stripe.com/connect/migrate-to-stripe.md#create-forms-to-collect-information) with clear instructions that the account can use to correct the information. Notify the account, then [submit the corrected information](https://docs.stripe.com/connect/migrate-to-stripe.md#update-the-connected-account) using the Accounts API. (See full diagram at https://docs.stripe.com/connect/migrate-to-stripe) If you plan to create custom flows to handle all your verification errors: - Review the details regarding all possible [verification errors and how to handle them](https://docs.stripe.com/connect/handling-api-verification.md). - [Test verification states](https://docs.stripe.com/connect/testing-verification.md). #### Embedded Listen to the [account.updated](https://docs.stripe.com/api/events/types.md#event_types-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 [Account onboarding component](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md). (See full diagram at https://docs.stripe.com/connect/migrate-to-stripe) ### Disable Stripe user authentication When using embedded onboarding, [Stripe user authentication](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#user-authentication-in-connect-embedded-components) is enabled by default. You can use [`disable_stripe_user_authentication`](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-account_onboarding-features-disable_stripe_user_authentication) to remove this behaviour. We recommend implementing two-factor authentication or equivalent security measures as a [best practice](https://docs.stripe.com/connect/risk-management/best-practices.md#prevent-account-take-overs). For account configurations that support this feature, such as Custom, you assume liability for connected accounts if they can’t pay back [negative balances](https://docs.stripe.com/connect/risk-management/best-practices.md#decide-your-approach-to-negative-balance-liability). #### Hosted Listen to the [account.updated](https://docs.stripe.com/api/events/types.md#event_types-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. (See full diagram at https://docs.stripe.com/connect/migrate-to-stripe) ## Migrate payment and customer data to Stripe After you create your connected accounts on Stripe, [request a PAN data import](https://docs.stripe.com/get-started/data-migrations/pan-import.md), which migrates your payment and customer data to them. ## See also - [Choose your onboarding configuration](https://docs.stripe.com/connect/onboarding.md) - [Handling identity verification with the API](https://docs.stripe.com/connect/handling-api-verification.md) - [Testing account identity verification](https://docs.stripe.com/connect/testing-verification.md)