Skip to content
Create account or Sign in
/Ask AI
Create accountSign in
APIs & SDKsHelp
Canada
English (United States)

Use the Accounts v2 API in your existing integration

Learn how to update integrations built on Accounts v1 and Customers v1.

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

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.

Account creation delay

A new v1 Account might require up to 10 minutes before you can use it with an Accounts v2 endpoint. When the Account is ready for API v2 requests, it sends a v2.core.account.created webhook event.

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.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \
  -H "Authorization: Bearer sk_test_Hrs6SAopgFPF0bZXSN3f6ELN" \
  -H "Stripe-Version: 2026-07-29.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.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \
  -H "Authorization: Bearer sk_test_Hrs6SAopgFPF0bZXSN3f6ELN" \
  -H "Stripe-Version: 2026-07-29.preview" \
  --json '{
    "include": [
        "configuration.merchant",
        "identity",
        "defaults"
    ]
  }'
  1. Add the connected account’s Stripe balance as a payment method.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/setup_intents \
  -u "sk_test_Hrs6SAopgFPF0bZXSN3f6ELN:" \
  -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.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions \
  -u "sk_test_Hrs6SAopgFPF0bZXSN3f6ELN:" \
  -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.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/customers/acct_1abc \
  -u "sk_test_Hrs6SAopgFPF0bZXSN3f6ELN:" \
  -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

v2 Accounts send both v1 (snapshot) Events and v2 (thin) Events. The v1 events depend on the updated configuration. For example, updating properties of the merchant configuration emits v1 account.updated events, while updating properties of the customer configuration emits v1 customer.updated events.

We recommend setting up new endpoints to listen to v2 events.

Webhooks for Connect users listen for events in different scopes, depending on the source of the event:

  • Your account: Most events triggered by resources that exist in your account. That includes most requests made using your API keys and without authenticating as another Stripe account, such as:
    • v2.core.account.* events for v2 Accounts in your account
    • Events for Customers in your account
    • Events for direct charges on your account
    • Events for indirect charges on your account for your connected accounts
  • Connected accounts: Events triggered by resources that exist in connected accounts and some resources that exist in your account, such as:
    • v2.core.account.* events for v2 Accounts representing customers and recipients of your connected accounts
    • v1 account.updated events for both v1 and v2 Accounts representing customers and recipients of your connected accounts
    • Direct charges for customers of your connected accounts

Event scopes for v2 Accounts representing connected accounts

v2 Account objects trigger both v1 and v2 Events, which can have different scopes. For events triggered by connected accounts, v2 Events use the Your account scope, while v1 Events use the Connected accounts scope, even when triggered by the same v2 Account.

The behavior of v2 Account events differs from that of v1 Account events, in that all events associated with v1 Account objects use the Connected accounts scope.

The following table describes which scope to select when you create a webhook:

Event sourceEvent scope
Updates to v1 Account objects representing connected accountsConnected accounts
Updates to v2 Account objects representing connected accounts
  • v2 events: Your account (scope changed from API v1)
  • v1 events: Connected accounts
Updates to Customer objects representing connected accountsYour account
Updates to v2 Account objects representing customers of connected accounts that pay direct charges
  • v2 events: Connected accounts
  • v1 events: Connected accounts
Updates to Customer objects representing customers of connected accounts that pay direct chargesConnected accounts
Updates to v2 Account objects representing customers of connected accounts that pay indirect charges created on the platform
  • v2 events: Your account
  • v1 events: Your account
Updates to Customer objects representing customers of connected accounts that pay indirect charges created on the platformYour account
Direct charges paid to connected accountsConnected accounts
Updates to Invoices and Subscriptions that connected accounts charge their customers using direct chargesConnected accounts
Indirect charges created on the platform for customers of connected accountsYour account
Updates to Invoices and Subscriptions that customers of connected accounts pay using indirect charges created on the platformYour account
Direct charges created on the platform, including charges paid by connected accountsYour account

To listen to v2 Events triggered by Accounts representing your connected accounts:

  1. Open the Webhooks tab in Workbench.
  2. Create a new event destination, or modify an existing one.
  3. In the Events from section, select Your account.
  4. In the Events section, select the v2 event types you want the webhook to listen to, then click Continue.
  5. Select the Destination type and click Continue.
  6. Complete the endpoint setup by following the interactive builder for the selected destination type.

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:

Cross-border payouts

Use Global payouts to send cross-border payouts.

On this page
Morty Proxy This is a proxified and sanitized view of the page, visit original site.