Manage payout accounts for connected accounts

Learn how to manage external bank accounts and debit cards for connected accounts.

Payout accounts can be bank accounts or debit cards. Stripe recommends collecting external account details with the Connect Onboarding web form, which helps you:

Save design and development time.
Eliminate the need to store sensitive data such as account and routing numbers on your server.
Eliminate the need to build form validations when users enter account details.

In the US, we also recommend using Stripe Financial Connections, which lets your users securely link their financial accounts to your business. It helps you:

Increase onboarding conversion by preventing your accounts from having to interrupt the process to locate their account and routing numbers.
Reduce first payout failure rates by eliminating errors that result from manual entry of account and routing numbers.
Eliminate the need to store sensitive data such as account and routing numbers on your server.
Eliminate the need to build form validations when accounts enter account details in custom onboarding forms.
(Accounts v1 only) Enable your accounts to authenticate in fewer steps by reusing bank account details they’ve saved to Link. Accounts that save their account information at any of the Stripe businesses using Link can share their account details with your platform the next time they use Financial Connections.
Access additional information on an account’s external bank account, such as balances, ownership details, and transactions. You can mitigate fraud during onboarding by verifying that information, such as the name and address of the external bank account holder.

Financial Connections is free when you include Link. Otherwise, using it incurs fees.

Alternatively, if you use API onboarding for your connected accounts, you can collect payout account details with a custom form in your account onboarding flow.

Opting out of external account collection

For accounts where the platform is responsible for collecting requirements, such as Custom accounts, you may opt not to collect external account information in onboarding. You may do this if, for instance, you build your own onboarding flow where you want to collect external account information.

In embedded onboarding, you can disable external account collection by setting the external_account_collection feature on the Account Session to false. Alternatively, in hosted onboarding you can go to your Connect external accounts settings and then under Accounts where the platform is responsible for collecting requirements enable or disable collecting external account information. Note that this is off by default.

Collecting external accounts

Stripe-hosted onboarding for connected accounts uses a web form hosted by Stripe to collect the information required to onboard connected accounts. Stripe-hosted onboarding can collect both bank accounts and debit cards. You can use Financial Connections with Stripe-hosted onboarding to collect bank account details. However, you can’t use Financial Connections to collect debit card details.

If you’re responsible for connected accounts that can’t cover negative balances, including Custom and Express accounts, you can customize the collection flow of external accounts in your External account settings. These settings aren’t applicable if you’re using direct API calls from your own form.

In your External account settings, you can:

Enable or disable the collection of debit cards, by making a selection under Allow debit cards?.
Require that connected accounts must add at least one bank account before being able to add any other type of external account, such as a debit card. You can access this setting under Require at least one bank account?. This is useful for ensuring auto debit support.
Control whether or not connected accounts to add more than one external account in a given currency. There is a limit of five external accounts per currency. You can access this setting under Collect multiple external accounts per currency.

Available in

United States

Stripe platforms in the US can enable Stripe Financial Connections within the Stripe-hosted onboarding form by following these steps:

Navigate to your External Account settings, where you manage optional Connect onboarding features.
For connected accounts where your platform collects account information when requirements change, including for Custom accounts, you must allow Stripe-hosted onboarding to collect external account details. Under Stripe-hosted onboarding for Custom accounts, allow Stripe to collect external account information by turning on the toggle.
Under How will bank account details be collected?, select Financial Connections.
(Optional) Request permission to access additional data on the accounts instantly verified with Financial Connections, such as balances, ownership details, and transactions. If you opt to request this additional information, you’ll be prompted to sign up for Stripe Financial Connections.

When external account detail collection is enabled, all connected accounts are prompted to authenticate their bank account using the Stripe-hosted modal UI embedded within the onboarding form.

A Connect onboarding flow using Stripe Financial Connections to collect a payout account.

If a connected account can’t instantly verify their bank account using Financial Connections, the verification process automatically falls back to manual entry:

A Connect onboarding flow using the Stripe Financial Connections modal to collect a payout account using manual entry.

After onboarding, the specified bank account automatically attaches to the connected account.

Retrieve data on a Financial Connections account Server-side

You can determine if your user linked a Financial Connections Account by retrieving any linked Financial Connections Accounts using their connected account ID. Be sure to specify their account ID in the Stripe-Account header.

This returns an API response similar to the following:

{
  "object": "list",
  "data": [
    {
      "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid",
      "object": "financial_connections.account",
      "account_holder": {
        "account": "{{CONNECTED_ACCOUNT_ID}}"
,
        "type": "account"
      },
      ...
      "supported_payment_method_types": [
        "us_bank_account"
      ]
    }
    ...
  ]
}

If any Financial Connections accounts are listed, it indicates that the connected account linked them during the onboarding process. You can use the id value to access or refresh the data you specified in your External Account settings. To protect the privacy of your connected account’s data, you can only access the data you specified.

To start retrieving account data, follow the guides for balances, ownership, and transactions. On all subsequent account retrieval and refresh requests, be sure to include the Stripe-Account header with the connected account ID:

Allow connected accounts to update their external account

When a connected account tries to update their external account (bank account or debit card), they typically must provide details about the existing external account or verify their identity. However, some accounts, particularly non-profits and accounts on certain compliance plans, might not be able to do so. For example, the existing external account might belong to a previous account owner, or Stripe might not have collected certain identity information (such as date of birth) during onboarding.

If your platform is responsible for negative balances, you can generate a unique code that allows a connected account to update their external account without verifying their identity. This feature is only available in live mode.

You can generate an external account update code only when your platform is responsible for negative balances, which excludes accounts that have access to the full Stripe Dashboard. If your platform isn’t responsible for negative balances, then a connected account that wants to update their external account must complete standard verification or contact Stripe Support.

How it works

Normally, when a connected account tries to update their external account in the Express Dashboard, Stripe prompts them to either enter their existing external account information or verify their identity. However, if you generate an external account update code for a connected account, Stripe instead prompts them to enter the code.

The code is valid for 7 days. If it expires before the connected account updates their external account, you can generate another one.

Generate an external account update code

When you generate an update code for a connected account, your platform accepts sole legal and financial liability for any errors that result from incorrect external account changes. Before generating a code, verify the identity of the person requesting the change. Document the change request, including any supporting information.

To generate the code, follow these steps:

In your platform Dashboard, navigate to the Connected accounts page.
Select the connected account that needs to update their external account.
Confirm that the account owner information is correct and matches the information in the change request.
In the Payout information section, open the overflow menu () next to the external account, and then click Generate update code.
Confirm the account owner’s information and accept liability.
Click Send to email the update code to the connected account owner.