Working with Treasury financial accounts
Use financial accounts to store, send, and receive funds.
After you gain API access to Treasury, 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, 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 100 USD connected account balance and a 200 USD financial account balance. In this scenario, the connected account owner has a sum of 300 USD 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_
feature. See Financial account features for more information on Feature
objects. See the 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 test mode. Test mode 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_
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.
Connected accounts can have multiple financial accounts associated with them through providing the same connected account ID as the value of the Stripe-Account
header. You can associate a maximum of 1 financial accounts with a single connected account (closed financial accounts don’t contribute to the limit). If you need a higher account threshold, contact treasury-support@stripe.com.
The following JSON defines the FinancialAccount
object structure:
Typically, you also request financial account features 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_
to check. The account’s capabilities
hash must have a treasury
value of active
.
… "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_
) capability enabled. The connected account must have this capability before you can request the card_
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_
feature results in an error.
You can set the nickname
field of a FinancialAccount
object to designate the financial account with a custom name. You can use nicknames to create unique identifiers, which you can use when working with multiple financial accounts under a single connected account. For nicknames to be valid, they must:
- Be unique for each financial account under a given connected account
- 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 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.
{ "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
Update a FinancialAccount
Use POST /v1/treasury/financial_
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 of the FinancialAccount.
Retrieve a FinancialAccount and account number
Use GET /v1/treasury/financial_
to retrieve the FinancialAccount
with the associated ID. Include the connected account ID as the Stripe-Account
header value.
By default, the account number for a financial account isn’t included in the response. To retrieve the account number, include the financial_
field in the expand
array.
If successful, the response returns the FinancialAccount
object with or without the account number depending on the inclusion of the expand
array.
For more information on the expand
parameter, see expanding responses.
Feature summary
The FinancialAccount
object contains a summary of the state of all its Features
in three arrays - active_
, pending_
, and restricted_
.
{ "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_
orfeatures restricted_
)features - Active features (included in
active_
)features - Restricted features that require action (included in
restricted_
)features
See Financial account features 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 incoming debits and credits to.
Warning
You can’t reopen financial accounts after you’ve closed them.
To close a financial account, contact treasury-support@stripe.com and provide the FinancialAccount
ID you want to close and the reason for the closure. You must provide your users with account closure notices, as detailed in the Treasury compliance guidelines.
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_
to close the financial account with the associated ID. Include the associated connected account ID as a header value.
curl https://api.stripe.com/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close \ -u
: \ -X "POST" \ -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}"sk_test_4eC39HqLyjWDarjtT1zdp7dc
The response is the FinancialAccount
object with a status
of closed
to confirm the action.
{ "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.
webhook 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.
webhook prompting that the requirements hash has changed and some new fields are now inupdated pending_
.verification
- When requesting new Features, the platform might get an
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_
orfeatures, pending_ features restricted_
arrays.features
- Indicates that one or more Features have changed status. This is reflected in changes to the