Working with connected accounts

Request the treasury capability and collect onboarding requirements for your connected accounts.

To use Financial Accounts for platforms, your platform must have a Stripe Connect integration. Stripe Connect enables a platform to provide connected accounts to sellers and service providers. For an overview of how connected accounts fit into the Financial Accounts for platforms account structure, see the Financial Accounts for platforms accounts structure guide.

Financial Accounts for platforms only supports connected accounts that don’t use a Stripe-hosted dashboard and where your platform is responsible for requirements collection and loss liability, including Custom connected accounts. Learn how to create connected accounts that work with Financial Accounts for platforms.

As a platform with connected accounts, you’re responsible for maintaining a minimum API version, communicating terms of service updates to your connected accounts, handling information requests from them, and providing them with support. Because your platform is ultimately responsible for the losses your connected accounts incur, you’re also responsible for vetting them for fraud. To learn more, read the Financial Accounts for platforms fraud guide.

Connected accounts require specific capabilities enabled on the account to use features of Financial Accounts for platforms. Different features require different capabilities, which might require additional information about your connected account owners. The treasury capability, for example, is a requirement on connected accounts for Financial Accounts for platforms access. When you request treasury for an account, additional fields become required for that connected account before the account can use Financial Accounts for platforms.

Before you create connected accounts in live mode for your Financial Accounts for platforms integration, we recommend you first create test connected accounts in a sandbox environment. Test connected accounts can’t receive or send real money and can’t be used in live mode, but are otherwise identical in configuration and functionality.

Checking current connected account types

If your platform already has a Connect integration with connected accounts but are unsure of their type, you can use the Dashboard or API to retrieve this information.

Navigate to the Connected accounts page in the Dashboard. We list your connected accounts in a table format.

To find the account features, select an account in the table to open the detailed view, then click Profile > Account information.

Create a new connected account with the treasury capability

Notiz

This guide demonstrates how to create a new connected account using the Stripe API for Financial Accounts for platforms and isn’t exhaustive. For complete documentation on creating a connected account, including through hosted onboarding, see the Connect integration guide.

Use POST /v1/accounts to create a new connected account. Request the following capabilities for the account, which are required to use Financial Accounts for platforms:

transfers (required for all connected accounts)
treasury

Notiz

You can update the account later to request these capabilities if you don’t do so when creating the account.

If you want to issue cards with Stripe Issuing to your connected account, you must request the card_issuing capability, as well. See the Working with Stripe Issuing cards guide for more information.

If you want to use ACH to transfer funds to or from an external account, you must also request the us_bank_account_ach_payments capability.

With all the previous options included, the request resembles the following:

const account = await stripe.accounts.create({
  country: 'US',
  email: email,
  capabilities: {
    transfers: {requested: true},
    treasury: {requested: true},
    card_issuing: {requested: true},
  },
  controller: {
    dashboard: {type: "none"},
    losses: {payments: "application"},
    requirement_collection: "application",
    fees: {payer: "application"}
  },
});

If successful, the response you receive confirms the connected account and requested capabilities.

{
  "id": "acct_1234",
  "object": "account",
  "capabilities": {
    "card_issuing": "inactive", // Should be requested only for Stripe Issuing users.
    "treasury": "inactive",
    "us_bank_account_ach_payments": "inactive"
  },
  ...
}

To learn more about connected account capabilities, see the Account capabilities guide for Connect.

Update a connected account to include the treasury capability

If you already have a connected account with card_payments enabled, use POST /v1/accounts/{{CONNECTED_ACCOUNT_ID}} to update the account with the associated ID with a request for the treasury capability. The following request updates a connected account with a request for the treasury capability, and includes the optional capabilities of card_issuing and us_bank_account_ach_payments:

Use POST /v1/accounts/{{CONNECTED_ACCOUNT_ID}} to update connected account capabilities for connected accounts that already have a FinancialAccount assigned. See Working with financial accounts or the FinancialAccount object API documentation for more information.

Onboard the connected account

After you create an account, you must onboard the seller or service provider to the account for ownership. The Account object that represents the connected account has a requirements hash that contains currently_due identity verification requirements. The seller or service provider on your platform must provide the details itemized in the requirements hash to enable charges and payouts on their connected account and enable all requested features of their financial account.

You have two options for onboarding connected account owners to Financial Accounts for platforms: hosted onboarding and custom onboarding. We recommend hosted onboarding.

If you create a test Account object and want to bypass onboarding requirements to test functionality, use POST /v1/accounts/{{CONNECTED_ACCOUNT_ID}} to provide test values that fulfill all the requirements. The following request uses a previously created connected account to apply the required account details.

Using hosted onboarding

Use Connect Onboarding to efficiently collect required information. That offloads the verification complexity from your platform to Stripe and collects the terms of the service agreement. Alternatively, you can write your own API requests for initial integration, but must monitor for changes to compliance requirements to keep your onboarding workflow current. Learn how to create connected accounts that work with Financial Accounts for platforms.

Before you can use Connect Onboarding, you must provide the name, color, and icon of your brand in the Branding section of your Connect settings page. Doing so customizes the visual appearance of the form that sellers and service providers interact with when onboarding to your platform.

To take advantage of Connect Onboarding, use POST /v1/account_links to create an AccountLink to provide to the seller or service provider who’s going to take ownership of the connected account:

Achtung

For security, don’t email, text, or otherwise send account link URLs directly to your user. Instead, redirect the authenticated user to the account link URL from within your platform’s application.

The response you receive includes the URL to provide to your user.

{
  "object": "account_link",
  "created": 1612927106,
  "expires_at": 1612927406,
  "url": "https://connect.stripe.com/setup/s/iCtLfmYb2tEU"
}

Using embedded onboarding

Embedded onboarding is a themeable onboarding UI with limited Stripe branding. It gives you more UX control than Stripe’s hosted onboarding solution. With embedded onboarding, you get a customized onboarding flow without the complexity and maintenance associated with updating your onboarding integration as compliance requirements change.

Your platform embeds the Account onboarding component in your application, and your connected accounts interact with the embedded component without leaving your application. Embedded onboarding uses the Accounts API to read the requirements and generate an onboarding form with robust data validation that’s localized for all Stripe-supported countries.

Using custom onboarding

If you prefer to build custom onboarding for your users, use POST /v1/accounts/{{CONNECTED_ACCOUNT_ID}} and POST /v1/accounts/{{CONNECTED_ACCOUNT_ID}}/persons/{{PERSON_ID}} to update the relevant Account and Person objects with the required information.

You must also confirm that the connected account owner has read and agreed to the Financial Accounts for platforms Agreement. See Handling verification with the API for additional details on fulfilling onboarding requirements.

Requirements

The fields in the following table are required for Financial Accounts for platforms users.

Entity type	At onboarding
Individual, Sole proprietorship	Entity details: Business names (customer facing and legal) Legal entity type Business address Business phone number Product or service description Industry or Merchant category code Tax ID Number (SSN, ITIN, or EIN) Financial Accounts for platforms TOS acceptance Stripe TOS acceptance Owner details: Legal name Date of birth Email address Residential address Full SSN, or ID document scan for non-US persons or if SSN can’t be verified Title Phone number
Companies (LLCs, corporations, non-profits, partnerships, and so on)	Entity details: Business names (customer facing and legal) Legal entity type Business address Business phone number Product or service description Industry or Merchant category code Tax ID Number (EIN) Financial Accounts for platforms TOS acceptance Stripe TOS acceptance Owner/representative details: Legal name Date of birth Email address Residential address Phone number Title Percent ownership of company Full SSN, or ID document scan for non-US persons or if SSN can’t be verified

Entity type

At onboarding

Individual, Sole proprietorship

Entity details:

Business names (customer facing and legal)
Legal entity type
Business address
Business phone number
Product or service description
Industry or Merchant category code
Tax ID Number (SSN, ITIN, or EIN)
Financial Accounts for platforms TOS acceptance
Stripe TOS acceptance

Owner details:

Legal name
Date of birth
Email address
Residential address
Full SSN, or ID document scan for non-US persons or if SSN can’t be verified
Title
Phone number

Companies (LLCs, corporations, non-profits, partnerships, and so on)

Entity details:

Business names (customer facing and legal)
Legal entity type
Business address
Business phone number
Product or service description
Industry or Merchant category code
Tax ID Number (EIN)
Financial Accounts for platforms TOS acceptance
Stripe TOS acceptance

Owner/representative details:

Legal name
Date of birth
Email address
Residential address
Phone number
Title
Percent ownership of company
Full SSN, or ID document scan for non-US persons or if SSN can’t be verified

Completion

The connected account onboarding process is complete when you receive an account.updated webhook confirming the following fields on your connected account:

{
  "object": {
    "object": "account",
    "id": "acct_1234",
    "capabilities": {
      "treasury": "active",
      "card_issuing": "active", // Only appears if requesting the `card_issuing` capability.
      "us_bank_account_ach_payments": "active", // Only appears if requesting the `us_bank_account_ach_payments` capability.
    },
    ...
  }
}

Account onboarding latency when your platform’s bank partner is Evolve Bank & Trust is less than 5 minutes.

Updates to requirements

To adapt to changes in financial regulations, Stripe must occasionally update information collection requirements for Financial Accounts for platforms. The requirements.eventually_due array on the Account object captures the updated information required by these regulation changes. Learn more about the requirements hash.