Accounts v2 APIPublic preview

Learn how to use the Accounts v2 API to represent your connected accounts on Stripe.

The Accounts v2 API allows you to represent your user as a single entity on Stripe.

This API structure provides:

A single entity that represents a connected account for all of its activity across multiple configurations
Structured identity data about the individual or business represented by the account
Variable configurations that support cross-product adoption and upgrades
Capabilities representing configuration-based functionality that depends on specific requirements

How Account calls return data

By default, Accounts v2 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.

The following example creates an Account without specifying any return properties to include:

The response returns values only for properties that it returns by default. It returns null for other properties, even the ones that the request assigned values to.

Response with no include
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer"
  ],
  "created": "2024-07-07T21:41:41.132Z",
  "display_name": "Furever",
  "configuration": null,
  "contact_email": "contact@test.com",
  "requirements": null,
  "identity": null,
  "defaults": null,
  "livemode": false
}

To populate additional properties in the response, specify them in the include parameter. For configurations, you must specify individual configuration types explicitly. Any configuration not requested returns a null value, regardless of its data.

The following example assigns customer and merchant configurations, but only requests the customer configuration in the include parameter.

The response shows how omitting configuration.merchant from the include array returns a null value for the merchant configuration, even though the request specifies values for it. The null value indicates only that the request’s include parameter didn’t specify that property.

Response with include but omitting merchant
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer",
    "merchant"
  ],
  "configuration": {
    "customer": {
      "automatic_indirect_tax": {
        "exempt": "none",
        "ip_address": null,
        "location": null,
        "location_source": "identity_address"
      },
      "billing": {
        "default_payment_method": null,
        "invoice": {
          "custom_fields": [],
          "footer": null,
          "next_sequence": 1,
          "prefix": "KD5JNJLZ",
          "rendering": null
        }
      },
      "capabilities": {
        "automatic_indirect_tax": {
          "requested": true,
          "status": "restricted",
          "status_details": [
            {
              "code": "requirements_past_due",
              "resolution": "provide_info"
            }
          ]
        }
      },
      "shipping": null,
      "test_clock": null
    },
    "merchant": null,
    "recipient": null
  },
  "requirements": "{...}"
}

Understand Account creation in API v2

When you create an Account, you must provide identifying information about the entity it represents and define one or more configurations that control its behavior.

Identity information

Populate the identity hash with information about the individual or business that the Account represents. The specific parameters depend on the nature of the entity.

Entity type:

For a person acting in their own capacity, set entity_type to individual and populate the individual parameter. If the person owns and operates a business with no legal distinction between the owner and the business, also set business_details.structure to sole_proprietorship.

You can add a representative person to an Account by creating an associated Person object, as in the following example.

Configurations

Each Account has one or more configurations that represent different business personas, such as a merchant or customer. They define how the Account interacts with Stripe products.

Each configuration type includes certain capabilities, which enable configuration-specific functionality when associated requirements are met. Instead of simply enabling a capability, you request it, which triggers collection of that capability’s requirements. The capability activates when Stripe verifies that its requirements are met.

Populate the Account’s configuration parameter with one or more of the following configuration types, depending on the functionality you want to provide.

Customer

The customer configuration allows a connected account to make payments to your platform and activates functionality in products such as Billing. It includes the automatic_indirect_tax capability, helps you collect the information you need to calculate taxes on the Account’s invoices, subscriptions, and payment links.

Merchant

The merchant configuration allows the controlling platform to create charges for the Account. It includes the card_payments capability, which is required for the Account to accept card payments.

Recipient

The recipient configuration allows an Account to receive funds other than direct payments, such as payouts from a Connect platform. It includes the stripe_balance.stripe_transfers capability, which allows the Account’s Stripe balance to receive fund transfers and is required for functionality such as destination charges.

How capabilities work

To activate a capability, you must first request it by setting its requested property to true. That triggers collection of the capability’s requirements, which is handled by Stripe or your platform, depending on the Account’s responsibilities properties. Requirements can involve identity and compliance documentation, as well as risk data. When Stripe verifies that a capability’s requirements are fulfilled, it becomes active.

Requirements

Requirements describe the information required by Stripe to enable capabilities for the Account, and can include:

The type of information
Why Stripe needs the information
Whether the requirement is past due (The “deadline” can be a date or some other type of threshold, such as a certain volume of payments)
Consequences that Stripe imposes at the deadline if we can’t verify the information with acceptable documentation, such as suspending certain functionality or stopping payouts from the Account’s Stripe balance
Who must take action

Company representatives

Some capabilities might require you to create a Person object for the Account with relationship.representative set to true.

In addition to any capability-specific consequences, if a capability has past-due requirements, its status becomes restricted, with a status_details.code of requirements_past_due.

The following example requests the stripe_balance.stripe_transfers capability, which belongs to the recipient configuration. It assumes that the Account already has the recipient configuration.

To see all the requirements for an Account’s requested capabilities, retrieve the Account and specify both requirements and the assigned configuration types in the include parameter.

The following example returns the status and requirements for capabilities belonging to the recipient configuration.

In the example response, the stripe_balance.stripe_transfers capability has been requested, but its requirements are past due. Because the request didn’t ask for the customer or merchant configurations, they return null values even if they’re defined on the Account.

Capability activation response showing requirements
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "recipient"
  ],
  "configuration": {
    "customer": null,
    "merchant": null,
    "recipient": {
      "capabilities": {
        ...
        "stripe_balance": {
          "payouts": {
            "requested": true,
            "status": "restricted",
            "status_details": [
              {
                "code": "requirements_past_due",
                "resolution": "provide_info"
              }
            ]
          },
          "stripe_transfers": {
            "requested": true,
            "status": "restricted",
            "status_details": [
              {
                "code": "requirements_past_due",
                "resolution": "provide_info"
              }
            ]
          }
        }
      },
      ...
    }
  },
  "contact_email": "furever_contact@example.com",
  "created": "2025-04-01T20:29:43.000Z",
  "dashboard": "full",
  "identity": null,
  "defaults": null,
  "display_name": "Furever",
  "metadata": {},
  "requirements": {
    "collector": "stripe",
    "entries": [
      {
        "awaiting_action_from": "user",
        "description": "identity.business_details.address.country",
        "errors": [],
        "impact": {
          "restricts_capabilities": [
            {
              "capability": "card_payments",
              "configuration": "merchant",
              "deadline": {
                "status": "past_due"
              }
            },
            {
              "capability": "stripe_balance.stripe_transfers",
              "configuration": "recipient",
              "deadline": {
                "status": "past_due"
              }
            },
            {
              "capability": "stripe_balance.payouts",
              "configuration": "recipient",
              "deadline": {
                "status": "past_due"
              }
            }
          ]
        },
        "minimum_deadline": {
          "status": "past_due"
        },
        "reference": null,
        "requested_reasons": [
          {
            "code": "routine_onboarding"
          }
        ]
      },
    ...
    ],
    "summary": {
      "minimum_deadline": {
        "status": "past_due",
        "time": null
      }
    }
  }
}

The following variables affect the requirements imposed on an Account:

Requested capabilities
The Account’s origin country
The Account’s entity type

A requirement’s impact describes how capabilities are affected when that requirement is past due. Its minimum_deadline.status is the earliest deadline status across all capabilities listed in its impact. To prioritize your requirements collection, inspect the deadline.status for each impact.

Most Stripe users satisfy requirements during account onboarding. Regardless of which onboarding flow you use, you can choose from two strategies:

Incremental: Collect only the minimum requirements during onboarding, meaning those with a status of currently_due or past_due.
Upfront: Collect all requirements during onboarding, regardless of their deadline status.

Monitor requirement updates

Because laws and regulations can change at any time, Stripe continuously updates our compliance and risk systems. That can affect the requirements for your connected accounts’ capabilities. To avoid interruption to their business, you must continuously monitor their capability and requirement statuses and implement processes to update requirements as needed.

Reference Accounts v2 objects in v1 requests

You can reference a v2 Account ID in other Stripe APIs in either an account or customer_account parameter.

A request with a customer parameter can accept the ID of a v2 Account, but you must provide it in the customer_account parameter instead of the customer parameter. The Account must have the customer configuration.
A request with an account parameter can accept the ID of any v2 Account in that parameter.

Information for Accounts v1 users

If your platform currently uses Accounts v1 and Customers v1, you can start using Accounts v2 in addition to them. However, you can’t use API v2 to manage Account and Customer objects created in API v1. Your platform must handle v1 and v2 objects separately.

Preview considerations

Accounts v2 allows you to use a single, configurable account for each business on your platform that collects payments directly. The preview release doesn’t support Treasury, Issuing, or payment methods that are in preview. You can still use Treasury, Issuing, or payment methods in preview with Accounts v1.

Enable Accounts v2 for your Connect platform from your Dashboard.