Use the Accounts v2 API in your existing integration

Follow this guide if you want to update your Accounts v1 and Customers v1 Connect platform integration to gain access to the following Accounts v2 features:

• Associate your connected accounts with payments they make to your platform without creating Customer objects.
• Avoid network costs by allowing connected accounts to pay your platform using their Stripe balance.
• Enable your connected accounts to hold funds on your platform using v2 Financial Accounts.

If you don’t need Accounts v2 features, you can continue to use your Accounts v1 and Customers v1 platform integration.

Use v2 endpoints for all your accounts

You can use the Accounts v2 API with your existing v1 Accounts without making any changes to them.

Add a customer configuration

Adding the customer configuration to an Account allows you to provide the Account ID in any API request that accepts a Customer ID, such as creating a subscription. Instead of providing a Customer ID in the customer parameter, you provide the Account ID in the customer_account parameter.

The following example uses the Accounts v2 API to add the customer configuration to an existing v1 Account, then updates an existing subscription to charge the Account using its Stripe balance.

1. Update the Account to add the customer configuration.

curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'

1. Retrieve the connected account to confirm it has the card_payments capability in the merchant configuration. This capability must be active in order to use the Stripe balance as a payment method.

curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "include": [
        "configuration.merchant",
        "identity",
        "defaults"
    ]
  }'

1. Add the connected account’s Stripe balance as a payment method.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer_account=acct_1abc \
  -d "payment_method_types[]"=stripe_balance \
  -d confirm=true \
  -d usage=off_session \
  -d "payment_method_data[type]"=stripe_balance

1. Create a subscription that charges the connected account using its Stripe balance.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer_account=acct_1abc \
  -d payment_behavior=default_incomplete \
  -d "items[0][price]"={{PRICE_ID}} \
  -d "payment_settings[save_default_payment_method]"=on_subscription

You no longer need to maintain a separate Customer object to accept subscription payments from this connected account.

Transition your integration in stages

Because you can use both the Accounts v1 and v2 APIs with your Accounts, you can update your integration at the pace that meets your business needs. For example, you can:

• Call /v2/core/accounts endpoints for Accounts created using API v1.
• Call /v1/accounts endpoints for Accounts created using API v2.
• Call /v1/customers endpoints for Accounts with the customer configuration.
• Use the Events API v2 to listen for changes to objects created using either API version.

These compatibilities let you update your integration in stages, without maintaining multiple versions in production or updating your entire integration at once.

We recommend updating your integration in this order:

1. Set up a new endpoint to listen to v2 Events.
2. Change your Account and Customer create calls to create customer-configured Accounts using /v2/core/accounts.
3. Change your Account and Customer update calls to use /v2/core accounts.
4. Change your Account and Customer retrieve calls to use /v2/core/accounts.

Use v2 Accounts in v1 endpoints

If you reference v2 objects in v1 endpoints, the response returns the v2 data in the v1 object structure. For example,

• Referencing a v2 Account in a /v1/accounts endpoint returns the data in the structure of a v1 Account.
• Referencing a v2 Account in a /v1/customers endpoint returns the data in the structure of a v1 Customer, and includes both the customer ID and customer_account ID.

curl https://api.stripe.com/v1/customers/acct_1abc \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d business_name="Furever Plus"

You can use customer-configured Accounts in the Customers v1 API, but you can’t reference v1 Customers in the Accounts v2 API. You must either migrate customer data into a new customer-configured Account, or update an existing connected account to add the customer configuration.

Webhook events

Accounts send both v1 (snapshot) Events and v2 (thin) Events. We recommend setting up a new endpoint to listen for Accounts v2 events.

1. In your Stripe Dashboard, open the Developers menu by clicking Developers in the navigation menu footer, then select Webhooks.
2. Click + Add destination.
3. In the Events from section, select Connected accounts.
4. Select Show advanced options. In the Payload style section, select Thin.
5. In the Events field, select one or more events corresponding to the Account object version:
   • For v1, type “v1” to search for v1 object event types. Select v1.account.updated.
   • For v2, type “v2” to search for v2 object event types. Select v2.core.account.updated or any other v2.core.account[*].updated event.
6. Continue setting up your event destination by following the interactive webhook endpoint builder.

For example, updating an Account of either version can send:

• A v1 account.updated event
• A v2 v1.account.updated event
• A v2 v2.core.account.updated event

Account version differences in the Events v2 API

Most v2.core.account event types don’t correspond directly to v1.account event types. For example, changing any property on an Account triggers a v1.account.updated event. However, the same action might trigger property-specific events for v2, such as v2.core.account[identity].updated or v2.core.account[configuration.recipient].updated.

We send the v2.core.account.updated event only for updates to top-level properties, such as dashboard or display_name, that don’t trigger one of the more specific update events.

Accounts API v2 limitations

You must use Accounts v1 in the following cases:

• Accounts connected using OAuth
• Accounts that have signed a recipient service agreement
• To request or manage the following capabilities:
  • treasury
  • card_issuing_*
  • deprecated capabilities such as legacy_payments
  • deprecated payment methods
  • payment methods in public or private preview