Migrating accounts to Stripe

Stripe enables you to migrate your existing connected accounts along with your payment and customer data. Doing so allows you to continue to collect payments and pay out or enable other businesses to accept payments directly. To successfully bring your existing platform business to Stripe, you need to:

1. Create a migration plan and timeline
2. Update your integration for connected accounts
3. Create and onboard accounts
4. Handle outstanding and ongoing requirements
5. 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’s requirements can require collecting additional information from your accounts. Perform an analysis to understand what data has been 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 event or the Retrieve Account 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 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 from a connected account (including Custom accounts) when requirements change, you can wrap Stripe’s terms of service in your own 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 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:

Create and onboard accounts

The following is an overview of the process:

Establish account requirements

The following factors affect the onboarding requirements for your connected accounts:

• The origin country of the connected accounts
• The service agreement type applicable to the connected accounts
• The capabilities requested for the connected accounts
• The business type (for example, individual or company) and company.structure (for example, public corporation or private partnership)

Use the interactive form to see how changing these factors affects the requirements.

Create the connected account

For each account to be migrated to Stripe, create an associated Account.

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

{
  ...
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  ...
}

{
  ...
  "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": [],

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 required. During this process, the capabilities you requested have a pending status.

Review status

You can retrieve the status of your connected account’s capabilities by:

• Inspecting the Account object’s capabilities hash for the relevant capability.
• Requesting capabilities directly from the Capabilities API and inspecting the status of the relevant capability.
• Listening for account.updated events in your webhook endpoint and inspecting the capabilities hash for the relevant capability.

After verifications are complete, the 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 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 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 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 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.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

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.

Migrate payment and customer data to Stripe

After your connected accounts are created on Stripe, request a PAN data import, which migrates your payment and customer data for use on Stripe.