Connect and the Accounts v2 API

Create connected accounts with a unified identity across Stripe.

As a Connect platform, you represent your connected accounts with Account objects. There are two versions of Accounts:

• v2 : Highly configurable and extendable support for payments to and by connected accounts, funds transfers, and other functionality
• v1 : Limited support for connected accounts and payments

v2 Accounts use configurations to enable different sets of functionality. For example, adding the merchant configuration to a v2 Account enables it to receive payments. If you want to extend an existing connected account’s functionality, you can add more configurations to it.

v1 Accounts don’t have configurations. You can only use them to manage payments for connected accounts.

Certain features don’t yet directly support v2 Accounts. However, you can still pass the ID of a v2 Account to an Accounts v1 API endpoint. When you do so, the response is structured as a v1 Account, but any updates still apply to the corresponding properties of the v2 object.

Use the Accounts v2 API to represent connected accounts

The Accounts v2 API provides:

• Flexible account configurations : Enable or change an Account ’s capabilities and compatibility with Stripe features by updating its configurations. Each capability belongs to a particular configuration.
• Centralized identity data : When you add a configuration to an existing Account to enable additional functionality, you don’t have to re-collect requirements that they already provided.
• A single API for connected accounts and customers : In most cases, you can represent any customer with an Account object. That lets you use the Accounts v2 API to manage both connected accounts and customers. You don’t have to use the Customers API at all.

The most common configurations include the following:

• The merchant configuration allows an Account to accept payments from customers. It includes the card _ payments and stripe _ balance. payouts (replacing v1 payouts ) capabilities.
• The customer configuration lets your platform charge an Account as a customer. You can use it instead of a Customer object when creating a subscription or invoice.
• The recipient configuration allows an Account to receive funds transfers. It includes the stripe _ balance. stripe _ transfers (replacing v1 transfers ) capability, which is required to use indirect charges.

The following example creates an Account using API v2. Notice that its structure differs from the structure of an Account object in API v1.

API v2 response structure

By default, Accounts v2 API calls return values for certain properties and null for other properties, regardless of their actual values. To retrieve additional property values, request them using the include parameter.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Specifying requirements in the include array returns any default requirements that apply to the new Account.

Use Accounts as customers

Any API request with a customer parameter that accepts a Customer ID also has a customer_account parameter that accepts an Account ID. You can use it to provide the ID of a v2 Account that has the customer configuration instead of providing the ID of a Customer. For example:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

If you use the Accounts v1 API, you can’t pass an Account ID to an endpoint that expects a Customer ID. If you want to charge your connected accounts using subscriptions, you have to create and manage separate Customer objects for them.

Learn more about using Accounts as customers.

Existing Connect platforms using Accounts v1 and Customers v1

You can use the Accounts v2 API to manage Accounts created using the Accounts v1 API, including assigning them the customer configuration.

Stripe discourages indefinitely maintaining both Accounts API versions simultaneously.

Accounts API v2 limitations

You must use Accounts v1 in the following cases:

• Using OAuth to authenticate connected accounts
• Signing connected accounts to a recipient service agreement
• To request or manage the following capabilities:
• treasury
• card _ issuing _ *
• deprecated capabilities such as legacy _ payments
• deprecated payment methods
• certain payment methods in public or private preview

Cross-border payouts

Use Global payouts to send cross-border payouts.