---
title: Working with Treasury financial accounts
subtitle: Use financial accounts to store, send, and receive funds.
route: /treasury/account-management/financial-accounts
---

# Working with Treasury financial accounts

Use financial accounts to store, send, and receive funds.

After you [gain API access to Treasury](https://docs.stripe.com/treasury/access.md), Stripe attaches a financial account to your platform account and enables you to provision financial accounts for eligible connected accounts on your platform. Each financial account has its own distinct [balance of funds](https://docs.stripe.com/treasury/account-management/working-with-balances-and-transactions.md), separate from the balance of the account it’s linked to. For example, the owner of a connected account on your platform might have a  connected account balance and a  financial account balance. In this scenario, the connected account owner has a sum of  spread between their financial account and connected account balances. These two balances remain separate, but the API provides the ability to move money from the connected account balance to the financial account balance.

In the Stripe API, `FinancialAccount` objects serve as the source and destination of money movement API requests. You request `Features` through the API to assign to `FinancialAccounts` that provide additional functionality for the financial accounts on your platform. For example, to enable payment card features on a specific financial account, you send an API request with the `FinancialAccount` ID for the `card_issuing` feature. See [Financial account features](https://docs.stripe.com/treasury/account-management/financial-account-features.md) for more information on `Feature` objects. See the [Available features](https://docs.stripe.com/treasury/account-management/financial-account-features.md#available-features) section within that guide to check required connected account capabilities for each `Feature`.

Before you create financial accounts in live mode for your Treasury integration, we recommend you first create test financial accounts in a *sandbox* environment. Test financial accounts can’t receive or send real money, can’t be used in live mode, and don’t generate a live account with real routing and account information, but are otherwise identical in configuration and functionality.

## Create a FinancialAccount

Use `POST /v1/treasury/financial_accounts` to create `FinancialAccounts`. Include the connected account ID as the value of the `Stripe-Account` header of the call to associate the `FinancialAccount` with a connected account.

The following JSON defines the `FinancialAccount` object structure:

```json
{
  "object": "treasury.financial_account",
  "created": 1612927106,
  "id": "fa_123",
  "country": "US",
  "supported_currencies": ["usd"],
  // Arrays of active, pending and restricted features summarize the status of all requested features
  "active_features": ["financial_addresses.aba", "deposit_insurance"],
  "pending_features": ["inbound_transfers.ach"],
  "restricted_features": ["intra_stripe_flows", "outbound_payments.ach", "outbound_payments.us_domestic_wire"],
  "balance": {
    "cash": {"usd": 9000},
    "inbound_pending": {"usd": 0},
    "outbound_pending": {"usd": 1000}
  },
  // The FinancialAccount gains a FinancialAddress once the `financial_addresses.aba` feature is active. For more information, see "Activating features"
  "financial_addresses": [
    {
      "type": "aba",
      "supported_networks": ["ach", "domestic_wire_us"],
      "aba": {
        "account_number_last4": "7890",
        // Use the expand[] parameter to view the `account_number` field hidden by default
        "account_number": "1234567890",
        "routing_number": "000000001",
        "bank_name": "Goldman Sachs"
      }
    }
  ],
  "livemode": true,
  // Financial accounts begin in the "open" state, but can be closed
  // `status_details.closed` is populated once a financial account is closed
  "status": "open",
  "status_details": {
    "closed": {
      // List of one or more reasons why the FinancialAccount was closed:
      // - account_rejected
      // - closed_by_platform
      // - other
      "reasons": [],
    }
  },
  // User-defined metadata
  "metadata": {},
  "nickname": {},
  // Restrictions that the platform can apply to the FinancialAccount
  "platform_restrictions": {
    "inbound_flows": "unrestricted",
    "outbound_flows": "restricted"
  },
}
```

```json
{
  "object": "treasury.financial_account",
  "created": 1612927106,
  "id": "fa_123",
  "country": "US",
  "supported_currencies": ["usd"],
  "active_features": ["financial_addresses.aba", "deposit_insurance"],
  "pending_features": ["inbound_transfers.ach"],
  "restricted_features": ["intra_stripe_flows", "outbound_payments.ach", "outbound_payments.us_domestic_wire"],
  "balance": {
    "cash": {"usd": 9000},
    "inbound_pending": {"usd": 0},
    "outbound_pending": {"usd": 1000}
  },
  "financial_addresses": [
    {
      "type": "aba",
      "supported_networks": ["ach", "domestic_wire_us"],
      "aba": {
        "account_number_last4": "7890",
        "account_number": "1234567890",
        "routing_number": "000000001",
        "bank_name": "Goldman Sachs"
      }
    }
  ],
  "livemode": true,
  "status": "open",
  "status_details": {
    "closed": null
  },
  "metadata": {},
  "platform_restrictions": {
    "inbound_flows": "unrestricted",
    "outbound_flows": "restricted"
  },
}
```

Typically, you also request [financial account features](https://docs.stripe.com/treasury/account-management/financial-account-features.md) when you make the API request to create the account. Regardless of the `Features` you request, the connected account must have the `treasury` capability enabled. If you’re unsure if the connected account has the capability, use `GET /v1/accounts/{{CONNECTED_ACCOUNT_ID}}` to check. The account’s `capabilities` hash must have a `treasury` value of `active`.

```json
…
  "capabilities": {
    "card_issuing": "active",
    "card_payments": "active",
    "transfers": "active",
    "treasury": "active",
    "us_bank_account_ach_payments": "active"
  },
…
```

If you want to issue cards attached to the financial account balance, your platform’s connected accounts must also have the Issuing (`card_issuing`) capability enabled. The connected account must have this capability before you can request the `card_issuing` feature for its financial account. If the connected account doesn’t have the capability, attempting to create a `FinancialAccount` with a request for the `card_issuing` feature results in an error.

Set the `nickname` field of a `FinancialAccount` object to designate a custom name for the financial account. You can use nicknames to create identifiers, which is useful when working with multiple financial accounts under a single connected account. Valid nicknames must:

- Be a non-blank string
- Contain less than 250 characters

If you don’t provide a nickname upon account creation, the nickname field will be empty and will return `null`. You can [update](https://docs.stripe.com/treasury/account-management/financial-accounts.md#update-a-financialaccount) nicknames after creating a `FinancialAccount`.

The following request creates a financial account assigned to the connected account with the ID assigned in the `Stripe-Account` header.

The response is a `FinancialAccount` object to confirm financial account creation.

```json
{
  "object": "treasury.financial_account",
  "created": 1612927106,
  "id": "{{FINANCIAL_ACCOUNT_ID}}",
  "country": "US",
  "supported_currencies": ["usd"],
  "active_features": [
    "card_issuing",
  ],
  // Features that require activation enter a pending state before activating
  "pending_features": [
    "deposit_insurance",
    "financial_addresses.aba",
    "inbound_transfers.ach",
    "intra_stripe_flows",
    "outbound_payments.ach",
    "outbound_payments.us_domestic_wire",
    "outbound_transfers.ach",
    "outbound_transfers.us_domestic_wire"
  ],
  "restricted_features": [],
  // A FinancialAddress is not added until the financial_addresses.aba feature has been activated
  "financial_addresses": [],
  "livemode": true,
  "nickname": "{{ACCOUNT_NICKNAME}}",
  "status": "open",
  ...
}
```

## Update a FinancialAccount

Use `POST /v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}` to update the `FinancialAccount` with the associated ID. Include the connected account ID as the `Stripe-Account` header value. The following example updates the [metadata](https://docs.stripe.com/api/metadata.md) of the FinancialAccount.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Treasury.FinancialAccountUpdateOptions
{
    Metadata = new Dictionary<string, string> { { "key", "value" } },
};
var service = new Stripe.Treasury.FinancialAccountService();
Stripe.Treasury.FinancialAccount financialAccount = service.Update(
    "<<treasuryFinancialAccount>>",
    options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.TreasuryFinancialAccountParams{};
params.AddMetadata("key", "value")
result, err := financialaccount.Update("<<treasuryFinancialAccount>>", params);
```

```java
Stripe.apiKey = "<<secret key>>";

FinancialAccount resource = FinancialAccount.retrieve("<<treasuryFinancialAccount>>");

FinancialAccountUpdateParams params =
  FinancialAccountUpdateParams.builder().putMetadata("key", "value").build();

FinancialAccount financialAccount = resource.update(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const financialAccount = await stripe.treasury.financialAccounts.update(
  '<<treasuryFinancialAccount>>',
  {
    metadata: {
      key: 'value',
    },
  }
);
```

```python
import stripe
stripe.api_key = "<<secret key>>"

financial_account = stripe.treasury.FinancialAccount.modify(
  "<<treasuryFinancialAccount>>",
  metadata={"key": "value"},
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$financialAccount = $stripe->treasury->financialAccounts->update(
  '<<treasuryFinancialAccount>>',
  ['metadata' => ['key' => 'value']]
);
```

```ruby
Stripe.api_key = '<<secret key>>'

financial_account = Stripe::Treasury::FinancialAccount.update(
  '<<treasuryFinancialAccount>>',
  {metadata: {key: 'value'}},
)
```

## Retrieve a FinancialAccount and account number

Use `GET /v1/treasury/financial_accounts/{{FINANCIALACCOUNT_ID}}` to retrieve the `FinancialAccount` with the associated ID. Include the connected account ID as the `Stripe-Account` header value.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var service = new Stripe.Treasury.FinancialAccountService();
Stripe.Treasury.FinancialAccount financialAccount = service.Get("<<treasuryFinancialAccount>>");
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.TreasuryFinancialAccountParams{};
result, err := financialaccount.Get("<<treasuryFinancialAccount>>", params);
```

```java
Stripe.apiKey = "<<secret key>>";

FinancialAccount financialAccount = FinancialAccount.retrieve("<<treasuryFinancialAccount>>");
```

```node
const stripe = require('stripe')('<<secret key>>');

const financialAccount = await stripe.treasury.financialAccounts.retrieve(
  '<<treasuryFinancialAccount>>'
);
```

```python
import stripe
stripe.api_key = "<<secret key>>"

financial_account = stripe.treasury.FinancialAccount.retrieve("<<treasuryFinancialAccount>>")
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$financialAccount = $stripe->treasury->financialAccounts->retrieve(
  '<<treasuryFinancialAccount>>',
  []
);
```

```ruby
Stripe.api_key = '<<secret key>>'

financial_account = Stripe::Treasury::FinancialAccount.retrieve('<<treasuryFinancialAccount>>')
```

By default, the account number for a financial account isn’t included in the response. To retrieve the account number, include the `financial_addresses.aba.account_number` field in the `expand` array.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Treasury.FinancialAccountGetOptions
{
    Expand = new List<string> { "financial_addresses.aba.account_number" },
};
var service = new Stripe.Treasury.FinancialAccountService();
Stripe.Treasury.FinancialAccount financialAccount = service.Get(
    "<<treasuryFinancialAccount>>",
    options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.TreasuryFinancialAccountParams{};
params.AddExpand("financial_addresses.aba.account_number")
result, err := financialaccount.Get("<<treasuryFinancialAccount>>", params);
```

```java
Stripe.apiKey = "<<secret key>>";

FinancialAccountRetrieveParams params =
  FinancialAccountRetrieveParams.builder()
    .addExpand("financial_addresses.aba.account_number")
    .build();

FinancialAccount financialAccount =
  FinancialAccount.retrieve("<<treasuryFinancialAccount>>", params, null);
```

```node
const stripe = require('stripe')('<<secret key>>');

const financialAccount = await stripe.treasury.financialAccounts.retrieve(
  '<<treasuryFinancialAccount>>',
  {
    expand: ['financial_addresses.aba.account_number'],
  }
);
```

```python
import stripe
stripe.api_key = "<<secret key>>"

financial_account = stripe.treasury.FinancialAccount.retrieve(
  "<<treasuryFinancialAccount>>",
  expand=["financial_addresses.aba.account_number"],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$financialAccount = $stripe->treasury->financialAccounts->retrieve(
  '<<treasuryFinancialAccount>>',
  ['expand' => ['financial_addresses.aba.account_number']]
);
```

```ruby
Stripe.api_key = '<<secret key>>'

financial_account = Stripe::Treasury::FinancialAccount.retrieve({
  expand: ['financial_addresses.aba.account_number'],
  id: '<<treasuryFinancialAccount>>',
})
```

If successful, the response returns the `FinancialAccount` object with or without the account number depending on the inclusion of the `expand` array.

```json
{
  "id": {{FINANCIAL_ACCOUNT_ID}},
  ...
  "financial_addresses": [
    {
      "aba": {
        "account_holder_name": "jenny",
        "account_number": "4242424242420239",
        "account_number_last4": "0239",
        "bank_name": "Stripe Test Bank",
        "routing_number": "000000001"
      },
      ...
    }
  ],
  ...
}
```

```json
{
  "id": {{FINANCIAL_ACCOUNT_ID}},
  ...
  "financial_addresses": [
    {
      "aba": {
        "account_holder_name": "jenny",
        "account_number_last4": "0239",
        "bank_name": "Stripe Test Bank",
        "routing_number": "000000001"
      },
      ...
    }
  ],
  ...
}
```

For more information on the `expand` parameter, see [expanding responses](https://docs.stripe.com/expand.md).

### Feature summary

The `FinancialAccount` object contains a summary of the state of all its `Features` in three arrays - `active_features`, `pending_features`, and `restricted_features`.

```json
{
  "object": "treasury.financial_account",
  "id": "fa_987",
  "status": "open",
  ...
  "active_features": ["card_issuing"],
  "pending_features": ["financial_addresses.aba"],
  "restricted_features": ["outbound_transfers.ach"],
}
```

These arrays provide a convenient way to see:

* Inactive features (included in `pending_features` or `restricted_features`)
* Active features (included in `active_features`)
* Restricted features that require action (included in `restricted_features`)

See [Financial account features](https://docs.stripe.com/treasury/account-management/financial-account-features.md) for more information.

## Close a FinancialAccount

You can permanently close a financial account if it meets the following conditions:

* There are no pending inbound transfers.
* All attached Issuing cards are canceled.
* The account balance is zero and the account has no activity in the past 75 days. Alternatively, you can provide another financial account or external account to [forward](#handling-transactions-on-closed-accounts) incoming debits and credits to.

You can’t reopen financial accounts after you’ve closed them.

Closing a financial account has no impact on data retention for associated objects, such as `Transactions`.

## FinancialAccount closure using the API

You can use `POST/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close` to close the financial account with the associated ID. Include the associated connected account ID as a header value.

```bash
curl https://api.stripe.com/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close \
  -u <<secret key>>: \
  -X "POST" \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}"
```

The response is the `FinancialAccount` object with a `status` of `closed` to confirm the action.

```json
{
  "id": "{{FINANCIAL_ACCOUNT_ID}}",
  "object": "treasury.financial_account",
  "status": "closed",
  "status_details": {
    "closed": {
      "reasons": ["closed_by_platform"]
    }
  },
  "active_features": [],
  "pending_features": [],
  "restricted_features": ["financial_addresses.aba"],
  ...
}
```

### Handling transactions on closed accounts

In rare circumstances, financial accounts might receive credits or debits on closed accounts that Stripe can’t return automatically. As a platform owner, you’re responsible for negative balances incurred after account closure. Stripe support works with you to return any remaining funds owed to the seller or service provider and to remediate closed accounts with a negative balance. By including forwarding settings when closing a financial account, Stripe can automatically forward debits and credits to the selected account.

## Webhooks

You can create financial accounts before fulfilling onboarding requirements. In this case, the financial account opens asynchronously and then triggers a `treasury.financial_account.features_status_updated` [webhook](https://docs.stripe.com/webhooks.md) with an updated view on any features still restricted due to outstanding onboarding requirements.

* `account.updated`
  * When requesting new Features, the platform might get an `account.updated` webhook prompting that the requirements hash has changed and some new fields are now in `pending_verification`.
* `treasury.financial_account.created`
  * Triggered whenever a new FinancialAccount is created.
* `treasury.financial_account.closed`
  * Notifies when the status of the top-level FinancialAccount changes to closed.
* `treasury.financial_account.features_status_updated`
  * Indicates that one or more Features have changed status. This is reflected in changes to the `active_features, pending_features` or `restricted_features` arrays.