Access balances for a Financial Connections accountBeta
The Financial Connections API allows you to request, retrieve, and refresh the balances of a Financial Connections account.
Request an account's balancesServer-side
You must collect an account before you can access balances in the Financial Connections API. To learn more about how to collect a Financial Connections account, consult the integration guide most relevant to your use case: accept payments, facilitate Connect payouts or build other-data powered products.
When collecting an account, you must specify the data you need to access with the data permissions parameter, and receive a user’s consent to access it with the authentication flow.
We recommend using a Financial Connections Session to request permission to retrieve balances for an account.
Optionally, you can request to prefetch balances, which retrieves balances on account creation. The prefetch parameter saves you from making another API call to retrieve data after account creation and reduces the latency of data retrieval.
If successful, the response returns a Financial Connections Session object.
{ "id": "fcsess_1MuOL4IG1CZuezXpoeuzQJYm", "object": "financial_connections.session", "livemode": true, "client_secret": "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" }
Retrieve an account's balancesServer-side
When you collect an account for the first time, the account will have null balances.
This field is also null if you didn’t request the balances permission or if the account was disconnected.
This is an example of the response after you’ve first collected an account.
{ "id": "fca_1Jbry3BAjqvGMUSxCDjFsrLU", "object": "financial_connections.account", "account_holder": { "customer": "cus_NfjonN9919dELB", "type": "customer" }, "balance": null, "balance_refresh": null, "category": "cash", "created": 1647973464, "display_name": "Savings", "institution_name": "Test Bank", "last4": "2222", "livemode": true, "permissions": [ "balances" ], "status": "active", "subcategory": "savings", "supported_payment_method_types": [ "us_bank_account" ] }
The balance_refresh hash describes the most recent refresh of the balance. If you opted to prefetch balances, the data is immediately available to you upon account creation, and you won’t need to make a refresh call until you need updated data.
Request an asynchronous refresh to retrieve updated balances with the Financial Connections account refresh action:
This causes Stripe to retrieve the latest balance available from the financial institution.
The request returns the account, but doesn’t reflect the updated balance.
The response describes the current state of the Financial Connections account. In particular, balances_refresh.status is now pending:
{ "id": "fca_1Jbry3BAjqvGMUSxCDjFsrLU", "object": "financial_connections.account", "ownership": null, "balance_refresh": { "last_attempted_at": 1651516582, "status": "pending", }, // ... }
In the background, Stripe attempts to retrieve account balances for the account.
After a few seconds, retrieve the Financial Connections account again:
If the background process succeeds, the Financial Connections account resource shows the balances_refresh.status as succeeded, and has a value for balances:
{ "id": "fca_1Jbry3BAjqvGMUSxCDjFsrLU", "object": "financial_connections.account", "balance": { "as_of": 1651516592, "cash": { "available": { "usd": 6000 } }, "current": { "usd": 6000 }, "type": "cash" }, "balance_refresh": { "last_attempted_at": 1651516582, "status": "succeeded", }, // ...rest of FinancialConnectionsAccount resource }
The time required to fetch the most recent data can vary depending on the financial institution, but can generally be returned in seconds.
After the refresh completes, Stripe emits a financial_connections.account.refreshed_balance webhook.
The webhook includes the Financial Connections account object with the latest balances.
The balance hash describes the balances made available by a financial institution, and the availability of balances varies.
We return all available balances provided to us by the financial institution.
Different types of balances can be returned.
| Balance Types | Description |
|---|---|
current | The current balance is the amount of funds that have posted to the account. This amount ignores events which have yet to post to an account such as incoming transfers, outgoing transfers, and other holds. A positive amount indicates money owed to the account holder. A negative amount indicates money owed by the account holder. |
available | The balance object is polymorphic, with types cash and credit. If the balance has type: "cash", there will be a cash sub-object with this property: available, which is the amount of funds available for use, such as any to be transferred or paid out, after incoming and outgoing holds have been considered. |
used | The balance object is polymorphic, with types cash and credit. If the balance has type: "credit", there will be a credit sub-object with this property: used which is the amount of funds that have been consumed after outgoing holds have been taken into account. For credit balances, current and used amounts use the same sign convention used for cash balances: a positive amount means funds owed to the account holder, a negative amount means funds owed by the account holder. In most cases a credit balance has negative amounts. |
The as_of field on a balance is the date and time that the external institution calculated this balance. This is not the same as the date and time that the balance was retrieved. For example, the bank may infrequently update the balance that is available through their API.
Stripe can generally return a balance, but not always.
If there is no balance available, or the account has been disconnected, the balance hash is null. In some instances only a current balance is returned. In rare instances, most often when dealing with smaller financial institutions, Stripe can’t retrieve balance data from a financial institution or partner of any kind, in which case the balance object will be null.
For the cash type, use the available sub-object to confirm sufficient funds exist prior to initiating an ACH Direct Debit payment.
If an available balance is null, you may wish to use the current balance to confirm sufficient funds prior to initiating an ACH Direct Debit, but be mindful that this amount ignores events which have yet to post to an account such as incoming transfers, outgoing transfers, and other holds.
Refresh an account’s balancesServer-side
Depending on your use case, you may want to pull balances periodically as balances can change.
As before, to retrieve an updated balance, request an asynchronous balance refresh.
This again causes Stripe to retrieve the latest balance available from the financial institution.
After the refresh completes, Stripe emits a financial_connections.account.refreshed_balance webhook.
The webhook includes the Financial Connections account object with the latest balances.
Failure to retrieve data on an account
Retrieving a balance on an account requires communicating with a financial institution. This communication can occasionally fail.
If we can’t retrieve a balance, the balance_refresh.status will be "failed", and you’ll receive a financial_connections.account.refreshed_balance webhook with the updated Financial Connections account resource. The balance from the most recent successful refresh will still be available on the account resource.