Core Resources
Payment Methods
Money Management
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Financial Accounts v2

A FinancialAccount represents a balance and can be used as the source or destination for the money management (/v2/money_management) APIs.

Learn more about calling API v2 endpoints.
Endpoints

The Financial Account 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.

  • display_namenullable string

    A descriptive name for the FinancialAccount, up to 50 characters long. This name will be used in the Stripe Dashboard and embedded components.

  • 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 Financial Account 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",
  "display_name": "Sample FinancialAccount",
  "livemode": true,
  "metadata": null,
  "status": "open",
  "storage": {
    "holds_currencies": [
      "usd"
    ]
  },
  "type": "storage"
}

Create a financial account 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.

  • display_namestring

    A descriptive name for the FinancialAccount, up to 50 characters long. This name will be used in the Stripe Dashboard and embedded components.

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

  • display_namenullable string

    A descriptive name for the FinancialAccount, up to 50 characters long. This name will be used in the Stripe Dashboard and embedded components.

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

400platform_financial_account_currency_required

The currency is not supported as the platform does not have a Financial Account that holds the currency.

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-12-15.preview" \
  --json '{
    "type": "storage",
    "storage": {
        "holds_currencies": [
            "usd"
        ]
    },
    "display_name": "Sample FinancialAccount"
  }'
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",
  "display_name": "Sample FinancialAccount",
  "livemode": true,
  "metadata": null,
  "status": "pending",
  "storage": {
    "holds_currencies": [
      "usd"
    ]
  },
  "type": "storage"
}

Update a financial account v2

Updates an existing FinancialAccount.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    ID of the FinancialAccount to get updated.

  • display_namestring

    A descriptive name for the FinancialAccount, up to 50 characters long. This name will be used in the Stripe Dashboard and embedded components.

  • metadatamap

    Metadata associated with the FinancialAccount.

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.

  • display_namenullable string

    A descriptive name for the FinancialAccount, up to 50 characters long. This name will be used in the Stripe Dashboard and embedded components.

  • 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
400platform_financial_account_currency_required

The currency is not supported as the platform does not have a Financial Account that holds the currency.

400unsupported_operation_on_managed_financial_account_resource

Modification of an object is not allowed on a managed account.

404not_found

The resource wasn’t found.

POST /v2/money_management/financial_accounts/:id
curl -X POST https://api.stripe.com/v2/money_management/financial_accounts/fa_65NvTFNdpXXUx1kx1rB16NoTesLDSQ1IgNPigisRKq09iq \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "display_name": "My FinancialAccount",
    "metadata": {
        "key": "value"
    }
  }'
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": "2025-06-27T21:52:05.197Z",
  "display_name": "My FinancialAccount",
  "livemode": true,
  "metadata": {
    "key": "value"
  },
  "status": "open",
  "storage": {
    "holds_currencies": [
      "usd"
    ]
  },
  "type": "storage"
}

Retrieve a financial account 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.

  • display_namenullable string

    A descriptive name for the FinancialAccount, up to 50 characters long. This name will be used in the Stripe Dashboard and embedded components.

  • 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-12-15.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",
  "display_name": "Sample FinancialAccount",
  "livemode": true,
  "metadata": null,
  "status": "open",
  "storage": {
    "holds_currencies": [
      "usd"
    ]
  },
  "type": "storage"
}