Accounts v2

An Account v2 object represents a company, individual, or other entity that your Stripe integration interacts with. It contains both identifying information and properties that control its behavior and functionality. An Account can have one or more configurations that enable sets of related features, such as allowing it to act as a merchant or customer. The Accounts v2 API is broadly available to Connect platforms, and to other users in preview. The Accounts v2 API also supports the Global Payouts preview feature.

Learn more about calling API v2 endpoints

Was this section helpful?Yes No

Create an account

POST/v2/core/accounts

Update an account

POST/v2/core/accounts/:id

Retrieve an account

GET/v2/core/accounts/:id

List accounts

GET/v2/core/accounts

Close an account

POST/v2/core/accounts/:id/close

The Account object v2

Attributes

idstring
Unique identifier for the Account.

objectstring, value is "v2.core.account"
String representing the object’s type. Objects of the same type share the same value of the object field.

applied_configurationsarray of enums
The configurations that have been applied to this account.
Possible enum values
customer
The Account can be used as a customer.
merchant
The Account can be used as a merchant.
recipient
The Account can be used as a recipient.

closednullable boolean
Indicates whether the account has been closed.

configurationnullable object
An Account represents a company, individual, or other entity that a user interacts with. Accounts store identity information and one or more configurations that enable product-specific capabilities. You can assign configurations at creation or add them later.

contact_emailnullable string
The primary contact email address for the Account.

contact_phonenullable string
The default contact phone for the Account.

createdtimestamp
Time at which the object was created. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

dashboardnullable enumConnect Only
A value indicating the Stripe dashboard this Account has access to. This will depend on which configurations are enabled for this account.
Possible enum values
express
The Account has access to the Express hosted dashboard.
full
The Account has access to the full Stripe hosted dashboard.
none
The Account does not have access to any Stripe hosted dashboard.

defaultsnullable object
Default values for settings shared across Account configurations.

display_namenullable string
A descriptive name for the Account. This name will be surfaced in the Stripe Dashboard and on any invoices sent to the Account.

future_requirementsnullable object
Information about the future requirements for the Account that will eventually come into effect, including what information needs to be collected, and by when.

identitynullable object
Information about the company, individual, and business represented by the Account.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable map
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

requirementsnullable object
Information about the active requirements for the Account, including what information needs to be collected, and by when.

The Account object

{
  "id": "acct_1Nv0FGQ9RKHgCVdK",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer",
    "merchant"
  ],
  "configuration": {
    "customer": {
      "automatic_indirect_tax": {
        "exempt": "none",
        "location": {
          "country": "US",
          "state": "NY"
        },
        "location_source": "identity_address"
      },
      "billing": {
        "invoice": {
          "next_sequence": 1,
          "prefix": "5626C87C",
          "custom_fields": []
        }
      },
      "capabilities": {
        "automatic_indirect_tax": {
          "status": "active",
          "status_details": []
        }
      }
    },
    "merchant": {
      "card_payments": {
        "decline_on": {
          "avs_failure": false,
          "cvc_failure": false
        }
      },
      "capabilities": {
        "card_payments": {
          "status": "active",
          "status_details": []
        },
        "stripe_balance": {
          "payouts": {
            "status": "active",
            "status_details": []
          }
        }
      }
    }
  },
  "contact_email": "furever@example.com",
  "created": "2025-03-28T19:59:16.000Z",
  "dashboard": "full",
  "identity": {
    "business_details": {
      "registered_name": "Furever",
      "address": {
        "country": "US",
        "postal_code": "10001"
      },
      "additional_addresses": [
        {
          "purpose": "principal_place_of_business",
          "country": "US",
          "line1": "354 Oyster Point Blvd",
          "city": "South San Francisco",
          "state": "CA",
          "postal_code": "94080"
        },
        {
          "purpose": "administrative",
          "country": "US",
          "line1": "510 Townsend St",
          "city": "San Francisco",
          "state": "CA",
          "postal_code": "94103"
        }
      ]
    },
    "country": "US",
    "entity_type": "company"
  },
  "defaults": {
    "currency": "usd",
    "responsibilities": {
      "fees_collector": "stripe",
      "losses_collector": "stripe",
      "requirements_collector": "stripe"
    }
  },
  "display_name": "Furever"
}

Create an account v2

POST /v2/core/accounts

Create an Account that represents a company, individual, or other entity that your business interacts with. Accounts contain identifying information about the entity, and configurations that store the features an account has access to. An account can be configured as any or all of the following configurations: Customer, Merchant and/or Recipient.

Learn more about calling API v2 endpoints

Parameters

account_tokenstring
The account token generated by the account token API.

configurationobject
An Account Configuration which allows the Account to take on a key persona across Stripe products.

contact_emailstring
The primary contact email address for the Account.

contact_phonestring
The default contact phone for the Account.

dashboardenumConnect Only
A value indicating the Stripe dashboard this Account has access to. This will depend on which configurations are enabled for this account.
Possible enum values
express
The Account has access to the Express hosted dashboard.
full
The Account has access to the full Stripe hosted dashboard.
none
The Account does not have access to any Stripe hosted dashboard.

defaultsobject
Default values to be used on Account Configurations.

display_namestring
A descriptive name for the Account. This name will be surfaced in the Stripe Dashboard and on any invoices sent to the Account.

identityobject
Information about the company, individual, and business represented by the Account.

includearray of enums

Additional fields to include in the response.

Possible enum values

configuration.customer

Include parameter to expose configuration.customer on an Account.

configuration.merchant

Include parameter to expose configuration.merchant on an Account.

configuration.recipient

Include parameter to expose configuration.recipient on an Account.

defaults

Include parameter to expose defaults on an Account.

future_requirements

Include parameter to expose future_requirements on an Account.

identity

Include parameter to expose identity on an Account.

requirements

Include parameter to expose requirements on an Account.

metadatamap
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Returns

Returns an Account object.

Error Codes

400account_capability_not_supported

Requested capability is not available.

400account_configuration_not_supported

The requested configuration is not available for the account.

400account_controller_express_dash_without_application_losses_or_fees

If dashboard is express, fees_collector must be application and losses_collector must be application.

400account_controller_stripe_pricing_platform_liable

If losses_collector is application, fees_collector must also be application.

400account_controller_ua_unsupported_configuration

Connect integration combination is not supported when UA beta is enabled.

400account_controller_unsupported_configuration

Connect integration combination is not supported when UA beta is disabled.

400account_controller_unsupported_configuration_private_preview

Responsibility combinations is not supported in private preview.

400account_country_unsupported_currency

Currency is not allowed for the account’s country.

400account_create_activation_required

Platform must be activated to create connected accounts.

400account_creation_invalid

Account creation is invalid.

400account_creation_liability_unacknowledged

Account creation error - liability unacknowledged.

400account_creation_losses_collector_unavailable

Account creation error - losses collector unavailable.

400account_creation_requirement_collection_and_liability_unacknowledged

Account creation error - requirement collection and liability unacknowledged.

400account_creation_requirement_collection_unacknowledged

Account creation error - requirement collection unacknowledged.

400account_terms_of_service_not_accepted

400account_token_required

Account token required for platforms in mandated countries (e.g., France).

400accounts_v2_access_blocked

Accounts v2 is not enabled for your merchant.

400address_characters_invalid

Invalid characters are provided for address fields.

400address_country_identity_country_mismatch

Address country doesn’t match identity country.

400address_postal_code_invalid

Address postal code is invalid.

400address_state_invalid

Address state is invalid.

400address_town_invalid

Address town is invalid.

400bgn_bank_accounts_unsupported

Creating accounts with the BGN currency is no longer supported, as Bulgaria is now using the Euro as of 2026-01-01.

400can_create_platform_owned_onboarding_accounts_required

Dormant accounts cannot create accounts where requirements collector is application (this is an account takeover prevention measure).

400cannot_create_connected_account

Platform is in an invalid state and cannot create connected accounts.

400cannot_create_new_account_rejected

Platform is in a rejected state and cannot create connected accounts.

400capability_cannot_be_unrequested_due_to_other_capability_requirement

Feature cannot be unrequested due to being a requirement for another feature.

400capability_not_available_for_dashboard_type

Feature cannot be requested for the dashboard type.

400capability_not_available_for_entity_type_in_country

Requested feature is not available for the entity type in your country.

400capability_not_available_for_loss_collector

A v2 Account cannot have both the specified capability and Stripe-owned loss liability.

400capability_not_available_in_country

Requested capability is not available in your country.

400capability_not_available_in_platform_country

Feature cannot be requested given the platform’s country.

400capability_not_available_without_other_capability

Requested feature is not available without also requesting a different feature.

400capability_not_available_without_other_capability_in_country

Requested feature is not available without also requesting a different feature in your country.

400configuration_creation_invalid

Cannot create an account with an invalid configuration.

400connect_identity_not_verified

Platform is not verified and cannot create connected accounts.

400connect_profile_not_submitted

Platform has not completed platform questionnaire and cannot create connected accounts.

400cross_border_connected_account_creation_not_allowed

Cross-border connected account creation is not allowed for this platform/account country combination.

400custom_account_beta

Custom accounts cannot be created in certain countries.

400date_of_birth_age_restriction

Representative date of birth does not meet the age limit.

400date_of_birth_invalid

Representative date of birth is provided an invalid date or a future date.

400default_currency_immutable

Cannot change defaults.currency post account activation.

400default_payment_method_invalid

Default payment method provided for a customer does not exist or is otherwise invalid.

400default_payment_method_invalid_type

Specified payment method exists but its type is not allowed to be the default payment method.

400directorship_declaration_not_allowed_during_account_creation

Directorship declaration is not allowed during account creation.

400document_invalid

Provided file tokens for documents are invalid, not found, deleted, or belong to a different account.

400document_purpose_invalid

Provided file tokens for documents are of the wrong purpose.

400email_domain_invalid_for_recipient

Email contains unsupported domain.

400email_invalid

Incorrect email is provided.

400entity_type_not_supported_in_country

The identity.entity_type value is not supported in a given identity.country.

400high_risk_activities_none_cant_be_combined_with_other_options

NONE is combined with another value in the HighRiskActivities list.

400id_number_invalid

Provided ID number is of the wrong format for the given type.

400identity_country_required

The identity.country value is required but not provided.

400incorrect_id_number_for_country

Incorrect ID number is provided for a country.

400incorrect_token_wrong_type

The incorrect token type is provided .

400invalid_id_number_for_structure

ID number is provided that is not permitted for the Identity’s entity type and business structure.

400invalid_id_number_registrar

The identity.business_details.id_numbers.registrar value is an invalid DE registrar.

400invalid_konbini_payments_support_hours

Konbini Payments Support Hours is Invalid.

400invalid_konbini_payments_support_phone_number

Konbini Payments Support Phone Number is Invalid.

400invalid_sepa_creditor_id_format

The SEPA Creditor Identifier is invalid.

400invalid_timezone

Timezone provided in account defaults is invalid.

400invoice_rendering_template_invalid

Invoice rendering template does not exist or is otherwise invalid.

400ip_address_invalid

Invalid IP address is provided.

400mcc_invalid

MCC is invalid for configuration.merchant.mcc.

400non_connect_platform_accounts_v2_access_blocked

Needs to use the newer API version or onboard to Connect.

400non_jp_kana_kanji_address

Kana Kanji script addresses must have JP country.

400ownership_declaration_not_allowed_during_account_creation

Ownership declaration is not allowed during account creation.

400param_alongside_account_token

Parameter cannot be passed alongside account_token.

400person_percent_ownership_invalid

Error returned when relationship.owner is set to true but the ownership percentage is set to 0%.

400phone_invalid

Phone number is invalid.

400platform_registration_required

The direct merchant has not signed up for Connect and cannot create connected accounts.

400postal_code_required_for_jp_address

Postal code is required for Japanese addresses.

400purpose_of_funds_description_must_be_empty_for_non_other_purpose_of_funds

PurposeOfFundsDescription is not empty while PurposeOfFunds is not OTHER.

400registration_date_invalid

Registration date must be in the past.

400script_characters_invalid

Provided script characters are invalid for the script.

400sepa_debit_creditor_identifier_not_allowed

The SEPA Creditor Identifier is blocked from use at Stripe.

400sepa_debit_stripe_creditor_identifier

A Stripe-owned shared SEPA Creditor Identifier cannot be set as a custom identifier.

400shipping_address_required

Shipping address is required within the shipping hash.

400shipping_name_required

Shipping name is required within the shipping hash.

400statement_descriptor_invalid

Statement descriptor is invalid.

400structure_incompatible_for_entity_type_country

The business_details.structure value is not valid for identity.country and identity.entity_type.

400test_clock_disallowed_on_live_mode

Cannot set a test clock on a livemode customer.

400test_clock_invalid

Test clock does not exist or is otherwise invalid.

400test_clocks_advance_in_progress

Cannot modify a test clock that is currently advancing.

400test_clocks_customer_limit_reached

Cannot add customer to a test clock that has already reached its customer limit.

400token_already_used

The token is re-used with a different idempotency key.

400token_expired

Token has expired.

400tos_acceptance_on_behalf_not_allowed

TOS cannot be accepted on behalf of accounts when requirement collection is stripe.

400unsupported_field_for_configs

Cannot set responsibilities on the current configurations.

400unsupported_identity_field_for_configs

Cannot set identity fields when the Account is only configured as a customer.

400unsupported_postal_code

Address is in an unsupported postal code.

400unsupported_state

Address is in an unsupported state.

400url_invalid

URL is invalid.

400v1_token_invalid_in_v2

A v1 token ID is passed in v2 APIs.

403invalid_account_token

Invalid account token.

409idempotency_error

An idempotent retry occurred with different request parameters.

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2026-09-30.endive" \
  --json '{
    "contact_email": "furever@example.com",
    "display_name": "Furever",
    "identity": {
        "country": "us",
        "entity_type": "company",
        "business_details": {
            "registered_name": "Furever",
            "additional_addresses": [
                {
                    "purpose": "principal_place_of_business",
                    "country": "us",
                    "line1": "354 Oyster Point Blvd",
                    "city": "South San Francisco",
                    "state": "CA",
                    "postal_code": "94080"
                },
                {
                    "purpose": "administrative",
                    "country": "us",
                    "line1": "510 Townsend St",
                    "city": "San Francisco",
                    "state": "CA",
                    "postal_code": "94103"
                }
            ]
        }
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        },
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        }
    },
    "defaults": {
        "responsibilities": {
            "fees_collector": "stripe",
            "losses_collector": "stripe"
        }
    },
    "dashboard": "full",
    "include": [
        "configuration.merchant",
        "configuration.customer",
        "identity",
        "defaults"
    ]
  }'

Response

{
  "id": "acct_1Nv0FGQ9RKHgCVdK",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer",
    "merchant"
  ],
  "configuration": {
    "customer": {
      "applied": "2025-03-28T19:59:16.000Z",
      "automatic_indirect_tax": {
        "exempt": "none",
        "location_source": "identity_address"
      },
      "billing": {
        "invoice": {
          "next_sequence": 1,
          "prefix": "5626C87C",
          "custom_fields": []
        }
      },
      "capabilities": {
        "automatic_indirect_tax": {
          "status": "active",
          "status_details": []
        }
      }
    },
    "merchant": {
      "applied": "2025-03-28T19:59:16.000Z",
      "card_payments": {
        "decline_on": {
          "avs_failure": false,
          "cvc_failure": false
        }
      },
      "capabilities": {
        "card_payments": {
          "status": "active",
          "status_details": []
        },
        "stripe_balance": {
          "payouts": {
            "status": "active",
            "status_details": []
          }
        }
      }
    }
  },
  "contact_email": "furever@example.com",
  "created": "2025-03-28T19:59:16.000Z",
  "dashboard": "full",
  "identity": {
    "business_details": {
      "registered_name": "Furever",
      "additional_addresses": [
        {
          "purpose": "principal_place_of_business",
          "country": "US",
          "line1": "354 Oyster Point Blvd",
          "city": "South San Francisco",
          "state": "CA",
          "postal_code": "94080"
        },
        {
          "purpose": "administrative",
          "country": "US",
          "line1": "510 Townsend St",
          "city": "San Francisco",
          "state": "CA",
          "postal_code": "94103"
        }
      ]
    },
    "country": "US",
    "entity_type": "company"
  },
  "livemode": false,
  "defaults": {
    "currency": "usd",
    "responsibilities": {
      "fees_collector": "stripe",
      "losses_collector": "stripe",
      "requirements_collector": "stripe"
    }
  },
  "display_name": "Furever"
}

Accounts v2

The Account object v2

Attributes

idstring

objectstring, value is "v2.core.account"

applied_configurationsarray of enums

closednullable boolean

configurationnullable object

contact_emailnullable string

contact_phonenullable string

createdtimestamp

dashboardnullable enumConnect Only

defaultsnullable object

display_namenullable string

future_requirementsnullable object

identitynullable object

livemodeboolean

metadatanullable map

requirementsnullable object

Create an account v2

Parameters

account_tokenstring

configurationobject

contact_emailstring

contact_phonestring

dashboardenumConnect Only

defaultsobject

display_namestring

identityobject

includearray of enums

metadatamap

Returns