Financial Accounts v2

The FinancialAccount object 

Attributes

  • idstring

    Unique identifier for the object.

  • objectstring, value is "v2.money_management.financial_account"

    String representing the object’s type. Objects of the same type share the same value of the object field.

  • balanceobject

    Multi-currency balance of this FinancialAccount, split by availability state. Each balance is represented as a hash where the key is the three-letter ISO currency code, in lowercase, and the value is the amount for that currency.

  • countryenum

    Two-letter country code that represents the country where the LegalEntity associated with the FinancialAccount is based in.

  • createdtimestamp

    Time at which the object was created.

  • 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

    Metadata associated with the FinancialAccount

  • othernullable object

    If this is a other FinancialAccount, this hash indicates what the actual type is. Upgrade your API version to see it reflected in type.

  • statusenum

    An enum representing the status of the FinancialAccount. This indicates whether or not the FinancialAccount can be used for any money movement flows.

    Possible enum values
    closed

    The FinancialAccount is closed and cannot be used anymore.

    open

    The FinancialAccount is open and available for use.

    pending

    The FinancialAccount was created and is in the process of being opened.

  • status_detailsnullable objectPreview feature

  • storagenullable object

    If this is a storage FinancialAccount, this hash includes details specific to storage FinancialAccounts.

  • typeenum

    Type of the FinancialAccount. An additional hash is included on the FinancialAccount with a name matching this value. It contains additional information specific to the FinancialAccount type.

    Possible enum values
    other

    The API version used does not support the FinancialAccount’s type.

    storage

    Used for the long term storage of funds and sending those funds to others.

The FinancialAccount object
{
"id": "fa_65NvTFNdpXXUx1kx1rB16NoTesLDSQ1IgNPigisRKq09iq",
"object": "v2.money_management.financial_account",
"balance": {
"available": {
"usd": {
"value": 0,
"currency": "usd"
}
},
"inbound_pending": {
"usd": {
"value": 0,
"currency": "usd"
}
},
"outbound_pending": {
"usd": {
"value": 0,
"currency": "usd"
}
}
},
"country": "US",
"created": "2023-02-24T22:48:56.363Z",
"description": "This is a sample Financial Account.",
"status": "open",
"storage": {
"holds_currencies": [
"usd"
]
},
"type": "storage"
}

Create a FinancialAccount object v2

Creates a new FinancialAccount.

Learn more about calling API v2 endpoints.

Parameters

  • typeenumRequired

    The type of FinancialAccount to create.

    Possible enum values
    storage

    Used for the long term storage of funds and sending those funds to others.

  • metadatamap

    Metadata associated with the FinancialAccount.

  • storageobject

    Parameters specific to creating storage type FinancialAccounts.

Returns

Response attributes

  • idstring

    Unique identifier for the object.

  • objectstring, value is "v2.money_management.financial_account"

    String representing the object’s type. Objects of the same type share the same value of the object field.

  • balanceobject

    Multi-currency balance of this FinancialAccount, split by availability state. Each balance is represented as a hash where the key is the three-letter ISO currency code, in lowercase, and the value is the amount for that currency.

  • countryenum

    Two-letter country code that represents the country where the LegalEntity associated with the FinancialAccount is based in.

  • createdtimestamp

    Time at which the object was created.

  • 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

    Metadata associated with the FinancialAccount

  • othernullable object

    If this is a other FinancialAccount, this hash indicates what the actual type is. Upgrade your API version to see it reflected in type.

  • statusenum

    An enum representing the status of the FinancialAccount. This indicates whether or not the FinancialAccount can be used for any money movement flows.

    Possible enum values
    closed

    The FinancialAccount is closed and cannot be used anymore.

    open

    The FinancialAccount is open and available for use.

    pending

    The FinancialAccount was created and is in the process of being opened.

  • status_detailsnullable objectPreview feature

  • storagenullable object

    If this is a storage FinancialAccount, this hash includes details specific to storage FinancialAccounts.

  • typeenum

    Type of the FinancialAccount. An additional hash is included on the FinancialAccount with a name matching this value. It contains additional information specific to the FinancialAccount type.

    Possible enum values
    other

    The API version used does not support the FinancialAccount’s type.

    storage

    Used for the long term storage of funds and sending those funds to others.

Error Codes
400already_exists

The resource already exists.

400financial_account_open_limit

The compartment has reached its limit on open FinancialAccounts.

400storer_capability_missing

The required storer capabilities are missing.

400storer_capability_not_active

The required storer capabilities are not active.

400unsupported_currency

The currency is not supported for Financial Accounts.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/money_management/financial_accounts
curl -X POST https://api.stripe.com/v2/money_management/financial_accounts \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-07-30.preview" \
--json '{
"type": "storage",
"storage": {
"holds_currencies": [
"usd"
]
},
"metadata": {
"nickname": "My Financial Account"
}
}'
Response
{
"id": "fa_65So897Og7nsSRgcz1L16SmeOD0tE9TfqsMPW2uZH3IEky",
"object": "v2.money_management.financial_account",
"balance": {
"available": {
"usd": {
"value": 0,
"currency": "usd"
}
},
"inbound_pending": {
"usd": {
"value": 0,
"currency": "usd"
}
},
"outbound_pending": {
"usd": {
"value": 0,
"currency": "usd"
}
}
},
"country": "US",
"created": "2025-06-27T21:52:05.197Z",
"metadata": {
"nickname": "My Financial Account"
},
"other": null,
"status": "pending",
"storage": {
"holds_currencies": [
"usd"
]
},
"type": "storage",
"livemode": true
}

Retrieve a FinancialAccount object v2

Retrieves the details of an existing FinancialAccount.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    ID of the FinancialAccount to be fetched.

Returns

Response attributes

  • idstring

    Unique identifier for the object.

  • objectstring, value is "v2.money_management.financial_account"

    String representing the object’s type. Objects of the same type share the same value of the object field.

  • balanceobject

    Multi-currency balance of this FinancialAccount, split by availability state. Each balance is represented as a hash where the key is the three-letter ISO currency code, in lowercase, and the value is the amount for that currency.

  • countryenum

    Two-letter country code that represents the country where the LegalEntity associated with the FinancialAccount is based in.

  • createdtimestamp

    Time at which the object was created.

  • 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

    Metadata associated with the FinancialAccount

  • othernullable object

    If this is a other FinancialAccount, this hash indicates what the actual type is. Upgrade your API version to see it reflected in type.

  • statusenum

    An enum representing the status of the FinancialAccount. This indicates whether or not the FinancialAccount can be used for any money movement flows.

    Possible enum values
    closed

    The FinancialAccount is closed and cannot be used anymore.

    open

    The FinancialAccount is open and available for use.

    pending

    The FinancialAccount was created and is in the process of being opened.

  • status_detailsnullable objectPreview feature

  • storagenullable object

    If this is a storage FinancialAccount, this hash includes details specific to storage FinancialAccounts.

  • typeenum

    Type of the FinancialAccount. An additional hash is included on the FinancialAccount with a name matching this value. It contains additional information specific to the FinancialAccount type.

    Possible enum values
    other

    The API version used does not support the FinancialAccount’s type.

    storage

    Used for the long term storage of funds and sending those funds to others.

Error Codes
404not_found

The resource wasn’t found.

GET /v2/money_management/financial_accounts/:id
curl https://api.stripe.com/v2/money_management/financial_accounts/fa_65NvTFNdpXXUx1kx1rB16NoTesLDSQ1IgNPigisRKq09iq \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-07-30.preview"
Response
{
"id": "fa_65NvTFNdpXXUx1kx1rB16NoTesLDSQ1IgNPigisRKq09iq",
"object": "v2.money_management.financial_account",
"balance": {
"available": {
"usd": {
"value": 0,
"currency": "usd"
}
},
"inbound_pending": {
"usd": {
"value": 0,
"currency": "usd"
}
},
"outbound_pending": {
"usd": {
"value": 0,
"currency": "usd"
}
}
},
"country": "US",
"created": "2023-02-24T22:48:56.363Z",
"status": "open",
"storage": {
"holds_currencies": [
"usd"
]
},
"type": "storage",
"livemode": true
}

List all FinancialAccount objects v2

Lists FinancialAccounts in this compartment.

Learn more about calling API v2 endpoints.

Parameters

  • limitinteger

    The page limit.

  • pagestring

    The page token.

  • statusenumPreview feature

    The status of the FinancialAccount to filter by. By default, closed FinancialAccounts are not returned.

    Possible enum values
    closed

    The FinancialAccount is closed and cannot be used anymore.

    open

    The FinancialAccount is open and available for use.

    pending

    The FinancialAccount was created and is in the process of being opened.

Returns

Response attributes

  • dataarray of objects

    Financial Accounts retrieved.

  • next_page_urlnullable string

    The next page URL.

  • previous_page_urlnullable string

    The previous page URL.

GET /v2/money_management/financial_accounts
curl https://api.stripe.com/v2/money_management/financial_accounts \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-07-30.preview"
Response
{
"data": [
{
"id": "fa_65NvTFNdpXXUx1kx1rB16NoTesLDSQ1IgNPigisRKq09iq",
"object": "v2.money_management.financial_account",
"balance": {
"available": {
"usd": {
"value": 0,
"currency": "usd"
}
},
"inbound_pending": {
"usd": {
"value": 0,
"currency": "usd"
}
},
"outbound_pending": {
"usd": {
"value": 0,
"currency": "usd"
}
}
},
"country": "US",
"created": "2023-02-24T22:48:56.363Z",
"status": "open",
"storage": {
"holds_currencies": [
"usd"
]
},
"type": "storage",
"livemode": true
}
],
"next_page_url": null,
"previous_page_url": null
}