Migrate to a supported Connect configuration

When you create indirect charges (destination charges or separate charges and transfers), the following are always true, regardless of your connected account settings:

• Your platform is responsible for negative balances.
• Your connected accounts can’t manage refunds or disputes.
• Stripe collects its fees directly from the platform.
• If you also use direct charges, their behavior is still controlled by your connected account settings. This can require you to maintain two different monetization flows.

If you use indirect charges, Stripe recommends that you assign responsibility for Stripe fees and negative balances to your platform. Otherwise, the actual behavior can conflict with your settings. This recommendation applies regardless of whether you use the on_behalf_of parameter or not.

If your existing integration violates this recommendation, we recommend that you either:

• Change your payments to direct charges. Doing so makes your connected accounts the merchant of record and allows them to handle their own refunds and disputes.
• Change responsibility for negative balances and paying Stripe fees to your platform. In this case, your connected accounts can no longer use the full Stripe Dashboard.

Change the charge type to direct charges

Change your charge type to direct charges if:

• Your Connect integration currently uses indirect charges (destination charges or separate charges and transfers)
• You want to keep using the same connected account configuration where:
  • Stripe owns negative balance liabilities
  • Your connected accounts pay payment processing fees

Changing your charge type affects several aspects of your workflow, including data availability, revenue reporting, and how you handle refunds and chargebacks.

API changes

These examples show the different approaches for creating a PaymentIntent when you use direct charges instead of indirect charges.

# Destination charges
stripe payment_intents create  \
  --amount=1000 \
  --currency=usd \
  --application-fee-amount=123 \
  -d "transfer_data[destination]"='{{CONNECTED_ACCOUNT_ID}}'

# Direct charges
stripe payment_intents create  \
  --stripe-account '{{CONNECTED_ACCOUNT_ID}}' \
  --amount=1000 \
  --currency=usd \
  --application-fee-amount=123

Webhooks

Data availability and migration

Migrate payment methods from the platform to connected accounts

Use the Payment Methods API to clone the relevant PaymentMethods saved on your platform account to each desired connected account. See how to share payment methods across multiple accounts for direct charges.

Merchant of record

Because the charge type you use determines the merchant of record, make sure the charge type you use aligns with your business model. Correctly designate the merchant of record to avoid fines for your platform.

Revenue reporting

Refunds and chargebacks

Change your connected account configuration

Change your connected account configuration if:

• Your Connect integration uses indirect charges (destination charges or separate charges and transfers) and you want to keep using this charge type
• Stripe owns negative balance liabilities
• Your connected accounts pay payment processing fees

Instead of the standard Stripe Dashboard, migrate to using an Embedded or Express Dashboard.

Stripe doesn’t support directly changing the type of an existing connected account. Instead, you need to create new connected accounts with the desired account configuration and re-onboard your users.

Prerequisites

• Use controller properties: If you use legacy account types (Standard, Express, or Custom), we recommend that you migrate your accounts to use controller properties instead of using account types.
• Potential legal or TOS updates: Confirm with your legal team that you can update your platform terms of service with the ability to manage and control connected accounts. You might already have provisions laid out in your terms of service. The Stripe terms of service account for changes in management and control of the connected account by Connect platforms. Depending on the configuration of the connected account, you might also need to include the Stripe connected account agreement in your platform terms of service.
• Communicate with connected accounts about the migration: Prepare to send a message to your users about the updates to their migration. Include the following information in your message:
  • Any updates to the terms of service
  • Reasons why the user is onboarding to a new account
  • Any updates or changes to user experience
  • How the user can reach out to your support team with questions
• Prepare your support and ops teams: We recommend documenting all the changes that users might experience on their new accounts, and any changes to pricing, risk management, and account management. Prepare an answer sheet your support team can use to help users who have questions. If your users still have access to Stripe support after the migration, coordinate with your Stripe account team to build support for handling exceptions and to create a library of FAQs.
• Ensure feature parity for standard accounts migrating to Express or Custom: If you have standard accounts who use their Stripe Dashboard regularly, let them know that they won’t be able to access their Dashboard, and that they still have access to any functionality they expect to retain through either an Express Dashboard or your platform UI using embedded components.

Create new connected accounts

1. Create a new connected account with the new Connect account configuration. In account creation, write the previous account ID onto the Accounts v1 metadata object, and store it for your own records. This maps a user’s existing account ID to the new connected account ID. This mapping copies the correct customers and payment methods to the new accounts, and tracks old and new accounts.
2. (Optional) Use networked onboarding for your connected accounts, which allows connected account owners to reuse certain information, such as their legal company name or business details. Alternatively, prefill account information from the old account to expedite the process for connected accounts. Hosted or embedded onboarding skips pre-filled fields, and the connected account must confirm their information and re-accept the Connect Terms of Service before completing onboarding.
3. Invite your connected accounts to complete onboarding.

Batch the migration into phases

We recommend batching the migration for existing users into phases, depending on your platform’s specific use cases. Start the migration with a small group of users to make sure that the integration works and that you can work with these users and collect feedback during the process.

Platforms can have Standard, Express, and Custom connected accounts at the same time. We recommend onboarding new accounts using the new connected account configuration and migrating existing accounts in parallel.