Legacy

Working with connected accounts Legacy

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

Legacy integration

The v1 version of Treasury for platforms is a legacy integration that doesn’t support many of the features introduced in Treasury for platforms v2. Don’t build a new v1 integration.

To use Stripe Treasury 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 Treasury for platforms account structure, see the Treasury for platforms accounts structure guide.

Treasury 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 Treasury 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 Treasury for platforms fraud guide.

Connected accounts require specific capabilities enabled on the account to use features of Treasury 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 Treasury for platforms access. When you request treasury for an account, additional fields become required for that connected account before the account can use Treasury for platforms.

Before you create connected accounts in live mode for your Treasury 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

Creating a connected account for Treasury for platforms requires requesting the correct capabilities.

Note

This guide demonstrates how to create a new connected account using the Stripe API for Treasury 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 Treasury for platforms:

• transfers (required for all connected accounts)
• treasury

Note

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/{{the related setting}} 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:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Use POST /v1/accounts/{{the related setting}} 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 Treasury 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/{{the related setting}} to provide test values that fulfill all the requirements. The following request uses a previously created connected account to apply the required account details.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

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 Treasury 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:

Warning

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.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

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

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/{{the related setting}} and POST /v1/accounts/{{the related setting}}/persons/{{the related setting}} 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 Treasury for platforms Agreement. See Handling verification with the API for additional details on fulfilling onboarding requirements.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Requirements

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

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 Treasury 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.