Financial Accounts

Stripe Treasury provides users with a container for money called a FinancialAccount that is separate from their Payments balance. FinancialAccounts serve as the source and destination of Treasury’s money movement APIs.

Endpoints

POST/v1/treasury/financial_accounts

POST/v1/treasury/financial_accounts/:id

GET/v1/treasury/financial_accounts/:id

GET/v1/treasury/financial_accounts

The FinancialAccount object

Attributes

idstring
Unique identifier for the object.

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

active_featuresarray of enums
The array of paths to active Features in the Features hash.

balanceobject
The single multi-currency balance of the FinancialAccount. Positive values represent money that belongs to the user while negative values represent funds the user owes. Currently, FinancialAccounts can only carry balances in USD.

countrystring
Two-letter country code (ISO 3166-1 alpha-2).

createdtimestamp
Time at which the object was created. Measured in seconds since the Unix epoch.

featuresnullable objectExpandable
The features and their statuses for this FinancialAccount.

financial_addressesarray of objects
The set of credentials that resolve to a FinancialAccount.

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

metadatanullable object
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.

nicknamenullable stringPreview feature
The nickname for the FinancialAccount.

pending_featuresarray of enums
The array of paths to pending Features in the Features hash.

platform_restrictionsnullable object
The set of functionalities that the platform can restrict on the FinancialAccount.

restricted_featuresarray of enums
The array of paths to restricted Features in the Features hash.

statusenum
Status of this FinancialAccount.
Possible enum values
closed
The FinancialAccount is closed.
open
The FinancialAccount is open.

status_detailsobject
Details related to the status of this FinancialAccount.

supported_currenciesarray of enums
The currencies the FinancialAccount can hold a balance in. Three-letter ISO currency code, in lowercase.

The FinancialAccount object

{
  "id": "fa_1MtZmL2eZvKYlo2Cer6cdwEC",
  "object": "treasury.financial_account",
  "active_features": [
    "financial_addresses.aba",
    "outbound_payments.ach",
    "outbound_payments.us_domestic_wire"
  ],
  "balance": {
    "cash": {
      "usd": 0
    },
    "inbound_pending": {
      "usd": 0
    },
    "outbound_pending": {
      "usd": 0
    }
  },
  "country": "US",
  "created": 1680714349,
  "financial_addresses": [
    {
      "aba": {
        "account_holder_name": "Jenny Rosen",
        "account_number_last4": "7890",
        "bank_name": "STRIPE TEST BANK",
        "routing_number": "0000000001"
      },
      "supported_networks": [
        "ach",
        "us_domestic_wire"
      ],
      "type": "aba"
    }
  ],
  "livemode": true,
  "metadata": null,
  "pending_features": [],
  "restricted_features": [],
  "status": "open",
  "status_details": {
    "closed": null
  },
  "supported_currencies": [
    "usd"
  ],
  "features": {}
}

Create a FinancialAccount

Creates a new FinancialAccount. For now, each connected account can only have one FinancialAccount.

Parameters

supported_currenciesarray of stringsRequired
The currencies the FinancialAccount can hold a balance in.

featuresobject
Encodes whether a FinancialAccount has access to a particular feature. Stripe or the platform can control features via the requested field.

metadataobject
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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

nicknamestringPreview feature
The nickname for the FinancialAccount.

platform_restrictionsobject
The set of functionalities that the platform can restrict on the FinancialAccount.

Returns

Returns a FinancialAccount object.

POST /v1/treasury/financial_accounts

Server-side language

curl https://api.stripe.com/v1/treasury/financial_accounts \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "supported_currencies[]"=usd

Response

{
  "id": "fa_1MtZmL2eZvKYlo2Cer6cdwEC",
  "object": "treasury.financial_account",
  "active_features": [
    "financial_addresses.aba",
    "outbound_payments.ach",
    "outbound_payments.us_domestic_wire"
  ],
  "balance": {
    "cash": {
      "usd": 0
    },
    "inbound_pending": {
      "usd": 0
    },
    "outbound_pending": {
      "usd": 0
    }
  },
  "country": "US",
  "created": 1680714349,
  "financial_addresses": [
    {
      "aba": {
        "account_holder_name": "Jenny Rosen",
        "account_number_last4": "7890",
        "bank_name": "STRIPE TEST BANK",
        "routing_number": "0000000001"
      },
      "supported_networks": [
        "ach",
        "us_domestic_wire"
      ],
      "type": "aba"
    }
  ],
  "livemode": true,
  "metadata": null,
  "pending_features": [],
  "restricted_features": [],
  "status": "open",
  "status_details": {
    "closed": null
  },
  "supported_currencies": [
    "usd"
  ],
  "features": {}
}

Update a FinancialAccount

Updates the details of a FinancialAccount.

Parameters

featuresobject
Encodes whether a FinancialAccount has access to a particular feature, with a status enum and associated status_details. Stripe or the platform may control features via the requested field.

forwarding_settingsobjectPreview feature
A different bank account where funds can be deposited/debited in order to get the closing FA’s balance to $0

metadataobject
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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

nicknamestringPreview feature
The nickname for the FinancialAccount.

platform_restrictionsobject
The set of functionalities that the platform can restrict on the FinancialAccount.

Returns

Returns a FinancialAccount object.

POST /v1/treasury/financial_accounts/:id

Server-side language

curl https://api.stripe.com/v1/treasury/financial_accounts/fa_1MtZmL2eZvKYlo2Cer6cdwEC \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "metadata[order_id]"=6735

Response

{
  "id": "fa_1MtZmL2eZvKYlo2Cer6cdwEC",
  "object": "treasury.financial_account",
  "active_features": [
    "financial_addresses.aba",
    "outbound_payments.ach",
    "outbound_payments.us_domestic_wire"
  ],
  "balance": {
    "cash": {
      "usd": 0
    },
    "inbound_pending": {
      "usd": 0
    },
    "outbound_pending": {
      "usd": 0
    }
  },
  "country": "US",
  "created": 1680714349,
  "financial_addresses": [
    {
      "aba": {
        "account_holder_name": "Jenny Rosen",
        "account_number_last4": "7890",
        "bank_name": "STRIPE TEST BANK",
        "routing_number": "0000000001"
      },
      "supported_networks": [
        "ach",
        "us_domestic_wire"
      ],
      "type": "aba"
    }
  ],
  "livemode": true,
  "metadata": {
    "order_id": "6735"
  },
  "pending_features": [],
  "restricted_features": [],
  "status": "open",
  "status_details": {
    "closed": null
  },
  "supported_currencies": [
    "usd"
  ],
  "features": {}
}

Retrieve a FinancialAccount

Retrieves the details of a FinancialAccount.

Parameters

No parameters.

Returns

Return a FinancialAccount object.

GET /v1/treasury/financial_accounts/:id

Server-side language

curl https://api.stripe.com/v1/treasury/financial_accounts/fa_1MtZmL2eZvKYlo2Cer6cdwEC \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"

Response

{
  "id": "fa_1MtZmL2eZvKYlo2Cer6cdwEC",
  "object": "treasury.financial_account",
  "active_features": [
    "financial_addresses.aba",
    "outbound_payments.ach",
    "outbound_payments.us_domestic_wire"
  ],
  "balance": {
    "cash": {
      "usd": 0
    },
    "inbound_pending": {
      "usd": 0
    },
    "outbound_pending": {
      "usd": 0
    }
  },
  "country": "US",
  "created": 1680714349,
  "financial_addresses": [
    {
      "aba": {
        "account_holder_name": "Jenny Rosen",
        "account_number_last4": "7890",
        "bank_name": "STRIPE TEST BANK",
        "routing_number": "0000000001"
      },
      "supported_networks": [
        "ach",
        "us_domestic_wire"
      ],
      "type": "aba"
    }
  ],
  "livemode": true,
  "metadata": null,
  "pending_features": [],
  "restricted_features": [],
  "status": "open",
  "status_details": {
    "closed": null
  },
  "supported_currencies": [
    "usd"
  ],
  "features": {}
}

Financial Accounts

The FinancialAccount object

Attributes

idstring

objectstring

active_featuresarray of enums

balanceobject

countrystring

createdtimestamp

featuresnullable objectExpandable

financial_addressesarray of objects

livemodeboolean

metadatanullable object

nicknamenullable stringPreview feature

pending_featuresarray of enums

platform_restrictionsnullable object

restricted_featuresarray of enums

statusenum

status_detailsobject

supported_currenciesarray of enums

Create a FinancialAccount

Parameters

supported_currenciesarray of stringsRequired

featuresobject

metadataobject

nicknamestringPreview feature

platform_restrictionsobject

Returns

Update a FinancialAccount

Parameters

featuresobject

forwarding_settingsobjectPreview feature

metadataobject

nicknamestringPreview feature

platform_restrictionsobject

Returns

Retrieve a FinancialAccount

Parameters

Returns