Accounts v2

Learn more about calling API v2 endpoints.

An Account v2 object represents a company, individual, or other entity that interacts with a platform on Stripe. 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 supports both the Global Payouts preview feature and the Connect-Billing integration preview feature. However, a particular Account can only access one of them.

The Connect-Billing integration preview feature allows an Account v2 to pay subscription fees to a platform. An Account v1 required a separate Customer object to pay subscription fees.

Endpoints

POST/v2/core/accounts

POST/v2/core/accounts/:id

GET/v2/core/accounts/:id

GET/v2/core/accounts

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

The Account object

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
Filter only accounts that have all of the configurations specified. If omitted, returns all accounts regardless of which configurations they have.
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.

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

contact_emailnullable string
The default contact email address for the Account. Required when configuring the account as a merchant or recipient.

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 enum
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 to be used on 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.

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 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_source": "identity_address"
      },
      "billing": {
        "invoice": {
          "next_sequence": 1,
          "prefix": "5626C87C"
        }
      },
      "capabilities": {
        "automatic_indirect_tax": {
          "requested": true,
          "status": "active"
        }
      }
    },
    "merchant": {
      "card_payments": {
        "decline_on": {
          "avs_failure": false,
          "cvc_failure": false
        }
      },
      "capabilities": {
        "card_payments": {
          "requested": true,
          "status": "active"
        },
        "stripe_balance": {
          "payouts": {
            "requested": true,
            "status": "active"
          }
        }
      }
    }
  },
  "contact_email": "furever@example.com",
  "created": "2025-03-28T19:59:16.000Z",
  "dashboard": "full",
  "identity": {
    "business_details": {
      "registered_name": "Furever"
    },
    "country": "US",
    "entity_type": "company"
  },
  "defaults": {
    "currency": "usd",
    "responsibilities": {
      "fees_collector": "stripe",
      "losses_collector": "stripe"
    }
  },
  "display_name": "Furever"
}

Create an Account v2

Learn more about calling API v2 endpoints.

An Account is a representation of a company, individual or other entity that a user 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.

Parameters

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

contact_emailstring
The default contact email address for the Account. Required when configuring the account as a merchant or recipient.

dashboardenum
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.

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

Response 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
Filter only accounts that have all of the configurations specified. If omitted, returns all accounts regardless of which configurations they have.
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.

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

contact_emailnullable string
The default contact email address for the Account. Required when configuring the account as a merchant or recipient.

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 enum
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 to be used on 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.

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 requirements for the Account, including what information needs to be collected, and by when.

Error Codes

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_unsupported_configuration

Connect integration combination is not supported.

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.

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.

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_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.

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.

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.

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.

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.

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_jp_kana_kanji_address

Kana Kanji script addresses must have JP country.

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

Platform has not signed up for Connect and cannot create connected accounts.

400script_characters_invalid

Provided script characters are invalid for the script.

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.

400tos_acceptance_on_behalf_not_allowed

TOS cannot is 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.

400url_invalid

URL is invalid.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/core/accounts

Server-side language

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-03-31.preview" \
  --json '{
    "contact_email": "furever@example.com",
    "display_name": "Furever",
    "identity": {
        "country": "us",
        "entity_type": "company",
        "business_details": {
            "registered_name": "Furever"
        }
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        },
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                },
                "stripe_balance": {
                    "payouts": {
                        "requested": true,
                        "status": "active"
                    }
                }
            }
        }
    },
    "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": {
      "automatic_indirect_tax": {
        "exempt": "none",
        "location_source": "identity_address"
      },
      "billing": {
        "invoice": {
          "next_sequence": 1,
          "prefix": "5626C87C"
        }
      },
      "capabilities": {
        "automatic_indirect_tax": {
          "requested": true,
          "status": "active"
        }
      }
    },
    "merchant": {
      "card_payments": {
        "decline_on": {
          "avs_failure": false,
          "cvc_failure": false
        }
      },
      "capabilities": {
        "card_payments": {
          "requested": true,
          "status": "active"
        },
        "stripe_balance": {
          "payouts": {
            "requested": true,
            "status": "active"
          }
        }
      }
    }
  },
  "contact_email": "furever@example.com",
  "created": "2025-03-28T19:59:16.000Z",
  "dashboard": "full",
  "identity": {
    "business_details": {
      "registered_name": "Furever"
    },
    "country": "US",
    "entity_type": "company"
  },
  "defaults": {
    "currency": "usd",
    "responsibilities": {
      "fees_collector": "stripe",
      "losses_collector": "stripe"
    }
  },
  "display_name": "Furever"
}

Update an Account v2

Learn more about calling API v2 endpoints.

Updates the details of an Account.

Parameters

idstringRequired
The ID of the Account to update.

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

contact_emailstring
The default contact email address for the Account. Required when configuring the account as a merchant or recipient.

dashboardenum
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.

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

Response 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
Filter only accounts that have all of the configurations specified. If omitted, returns all accounts regardless of which configurations they have.
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.

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

contact_emailnullable string
The default contact email address for the Account. Required when configuring the account as a merchant or recipient.

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 enum
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 to be used on 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.

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 requirements for the Account, including what information needs to be collected, and by when.

Error Codes

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_unsupported_configuration

Connect integration combination is not supported.

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.

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.

400attach_payment_method_to_customer

Default payment method is added to the customer config before attaching it to the account using /v1/payment_methods.

400can_create_platform_owned_onboarding_accounts_required

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

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_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.

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_outbound_destination_invalid

Outbound Destination ID is invalid.

400default_payment_method_invalid

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

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.

400duplicate_person_not_allowed

Duplicate person is added to an account.

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.

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.

400immutable_identity_param

Identity param has been made immutable due to the state of the account.

400incorrect_id_number_for_country

Incorrect ID number is provided for a country.

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.

400ip_address_invalid

Invalid IP address is provided.

400mcc_invalid

MCC is invalid for configuration.merchant.mcc.

400non_jp_kana_kanji_address

Kana Kanji script addresses must have JP country.

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.

400script_characters_invalid

Provided script characters are invalid for the script.

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.

400tos_acceptance_on_behalf_not_allowed

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

400total_person_ownership_exceeded

Total ownership percentages of all Persons on the account exceeds 100%.

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.

400url_invalid

URL is invalid.

400v1_account_instead_of_v2_account

V1 Account ID cannot be used in V2 Account APIs.

400v1_customer_instead_of_v2_account

V1 Customer ID cannot be used in V2 Account APIs.

404not_found

The resource wasn’t found.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/core/accounts/:id

Server-side language

curl -X POST https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-03-31.preview" \
  --json '{
    "identity": {
        "business_details": {
            "structure": "sole_proprietorship",
            "doing_business_as": "FurEver",
            "product_description": "Saas pet grooming platform at furever.dev using Connect embedded components",
            "url": "http://accessible.stripe.com",
            "id_numbers": [
                {
                    "type": "us_ein",
                    "value": "000000000"
                }
            ]
        }
    },
    "include": [
        "identity"
    ]
  }'

Response

{
  "id": "acct_1Nv0FGQ9RKHgCVdK",
  "object": "v2.core.account",
  "applied_configurations": [
    "merchant"
  ],
  "contact_email": "furever@example.com",
  "created": "2024-11-26T16:33:03.000Z",
  "dashboard": "none",
  "identity": {
    "business_details": {
      "doing_business_as": "FurEver",
      "id_numbers": [
        {
          "type": "us_ein"
        }
      ],
      "product_description": "Saas pet grooming platform at furever.dev using Connect embedded components",
      "structure": "sole_proprietorship",
      "url": "http://accessible.stripe.com"
    },
    "country": "US"
  },
  "display_name": "Furever",
  "metadata": {}
}

Retrieve an Account v2

Learn more about calling API v2 endpoints.

Retrieves the details of an Account.

Parameters

idstringRequired
The ID of the Account to retrieve.

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.

identity

Include parameter to expose identity on an Account.

requirements

Include parameter to expose requirements on an Account.

Returns

Response 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
Filter only accounts that have all of the configurations specified. If omitted, returns all accounts regardless of which configurations they have.
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.

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

contact_emailnullable string
The default contact email address for the Account. Required when configuring the account as a merchant or recipient.

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 enum
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 to be used on 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.

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 requirements for the Account, including what information needs to be collected, and by when.

Error Codes

400v1_account_instead_of_v2_account

V1 Account ID cannot be used in V2 Account APIs.

400v1_customer_instead_of_v2_account

V1 Customer ID cannot be used in V2 Account APIs.

404not_found

The resource wasn’t found.

GET /v2/core/accounts/:id

Server-side language

curl -G https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-03-31.preview" \
  -d include=identity \
  -d include="configuration.merchant"

Response

{
  "id": "acct_1Nv0FGQ9RKHgCVdK",
  "object": "v2.core.account",
  "applied_configurations": [
    "merchant",
    "customer"
  ],
  "configuration": {
    "merchant": {
      "card_payments": {
        "decline_on": {
          "avs_failure": false,
          "cvc_failure": false
        }
      },
      "capabilities": {
        "card_payments": {
          "requested": true,
          "status": "restricted",
          "status_details": [
            {
              "code": "requirements_past_due",
              "resolution": "provide_info"
            }
          ]
        }
      },
      "statement_descriptor": {
        "descriptor": "accessible.stripe.com"
      },
      "mcc": "5734"
    }
  },
  "contact_email": "furever@example.com",
  "created": "2024-11-26T16:33:03.000Z",
  "dashboard": "none",
  "identity": {
    "business_details": {
      "doing_business_as": "FurEver",
      "id_numbers": [
        {
          "type": "us_ein"
        }
      ],
      "product_description": "Saas pet grooming platform at furever.dev using Connect embedded components",
      "structure": "sole_proprietorship",
      "url": "http://accessible.stripe.com"
    },
    "country": "us"
  },
  "display_name": "Furever",
  "metadata": {}
}

Accounts v2

The Account object

Attributes

idstring

objectstring, value is "v2.core.account"

applied_configurationsarray of enums

configurationnullable object

contact_emailnullable string

createdtimestamp

dashboardnullable enum

defaultsnullable object

display_namenullable string

identitynullable object

livemodeboolean

metadatanullable map

requirementsnullable object

Create an Account v2

Parameters

configurationobject

contact_emailstring

dashboardenum

defaultsobject

display_namestring

identityobject

includearray of enums

metadatamap

Returns

Response attributes

idstring

objectstring, value is "v2.core.account"

applied_configurationsarray of enums

configurationnullable object

contact_emailnullable string

createdtimestamp

dashboardnullable enum

defaultsnullable object

display_namenullable string

identitynullable object

livemodeboolean

metadatanullable map

requirementsnullable object

Update an Account v2

Parameters

idstringRequired

configurationobject

contact_emailstring

dashboardenum

defaultsobject

display_namestring

identityobject

includearray of enums

metadatamap

Returns

Response attributes

idstring

objectstring, value is "v2.core.account"

applied_configurationsarray of enums

configurationnullable object

contact_emailnullable string

createdtimestamp

dashboardnullable enum

defaultsnullable object

display_namenullable string

identitynullable object

livemodeboolean

metadatanullable map

requirementsnullable object

Retrieve an Account v2

Parameters

idstringRequired

includearray of enums

Returns

Response attributes

idstring

objectstring, value is "v2.core.account"

applied_configurationsarray of enums

configurationnullable object

contact_emailnullable string

createdtimestamp

dashboardnullable enum