Access transactions for a Financial Connections account
Access an account's transactions with your user's permission.
The Financial Connections API allows you to retrieve transactions on a Financial Connections Account. Use transaction data to build a variety of products and solutions, such as:
- Expedite the underwriting process and improve access to credit and other financial services for your users.
- Mitigate fraud and reduce risk during user onboarding by evaluating a user’s transaction history, and understanding cash inflows and outflows from their financial accounts.
- Help your users track expenses, handle bills, and manage their finances.
Before you begin
You must have a completed Financial Connections registration to access transactions in live mode. Visit your Dashboard settings to check the state of your registration or begin the registration process. Financial Connections test data is always available.
Create a customerRecommendedServer-side
We recommend that you create a Customer with an email address to represent your user, that you then attach to your payment. Attaching a Customer
object allows you to list previously linked accounts later. By providing an email address on the Customer
object, Financial Connections can improve the authentication flow by simplifying sign-in or sign-up for your user, depending on whether they’re a returning Link user.
Request access to an account's transactionsServer-side
You must collect an account before you can access its transaction data. To learn more about how to collect Financial Connections Accounts 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 specify the data you need access to with the permissions parameter. The set of requested data permissions are viewable by the user in the authentication flow. Financial Connections Accounts are collectible through various integration paths, and how you specify the parameter varies slightly by API.
When using dynamic payment methods for certain payments APIs, you can also configure requested permissions in the Dashboard. Learn how to access additional account data on Financial Connections accounts.
Subscribe to transaction dataServer-side
When you subscribe to an account’s transaction data, Stripe automatically retrieves new transactions in the background every day and notifies you when they’re available. Subscribing to daily updates is the easiest way to keep the account’s transaction data up to date.
To get the Financial Connections Account ID you want to subscribe to transactions for, consult the documentation for our payments integrations or check the guide for Financial Connections Sessions.
Subscribe to transaction data by calling the subscribe API:
Note
Subscriptions aren’t allowed on inactive accounts.
In addition to activating a subscription to future transaction data, this API call automatically initiates a transaction refresh:
{ "id": "fca_1LDYuMGxLVUXRs6HW0lrat9T", "object": "financial_connections.account", "display_name": "Savings", "institution_name": "Test Bank", "status": "active", "permissions": ["transactions"], "subscriptions": ["transactions"], "transaction_refresh": { "id": "fctxnref_1aaaxqEitUZY8Svm4QdcWZKt", "last_attempted_at": 1706742786, "next_refresh_available_at": null, "status": "pending" } // ... }
As long as you remain subscribed to transaction data, Stripe initiates a new refresh every day.
Wait for the refresh to complete
All Financial Connections data refreshes are asynchronous. After you initiate a transaction refresh, you must wait for it to complete, then retrieve the resulting transactions.
The transaction_refresh field on a Financial Connections account represents the transaction refresh state. This field remains null
until you request the transactions
permission and initiate a refresh. After you start a transaction refresh, the state changes to pending
, and after completion, it moves to either succeeded
or failed
. We send the financial_connections.account.refreshed_transactions event when the transaction refresh completes. To determine the success of the refresh, check the transaction_
field while handling the webhook.
Retrieve transactionsServer-side
After Stripe successfully refreshes transactions on the account, you can retrieve them using the transactions list API:
Stripe returns a paginated list of up to the last 180 days of transaction history on an account, depending on the account’s financial institution.
{ "object": "list", "data": [ { "id": "fctxn_1LXp9RGxLVUXRs6HtTSVfxse", "object": "financial_connections.transaction", "account": "fca_1LDYuMGxLVUXRs6HW0lrat9T", "amount": -1000, "currency": "usd", "description": "Rocket Rides", "livemode": true, "status": "posted", "status_transitions": { "posted_at": 1651784999, "void_at": null }, "transacted_at": 1651784999, "transaction_refresh": "fctxnref_1LXp8WGxLVUXRs6Hkc5PNUXf", "updated": 1651784999 }, {...}, {...} ], "has_more": false, "url": "/v1/financial_connections/transactions" }
The status of a transaction is one of pending
, posted
, or void
. Information included in the description field varies, but can include metadata such as the business name.
Retrieving transactions since last refresh
You might wish to retrieve only new transaction data since your last data pull. For example, some users save previously retrieved transaction data to their database, and subsequently merge new or updated data as it becomes available.
To retrieve only new or updated transaction data since your last refresh, pass the transaction_
identifier provided by your last observed financial_connections.account.refreshed_transactions webhook event object to the list API:
The following is an example webhook integration that only retrieves and records new or updated transaction data:
OptionalUnsubscribe from transaction data
You can start, cancel, and resume a subscription at any point. To cancel a subscription, call the unsubscribe API:
To resume the subscription, call the subscribe API again.
OptionalRefresh transactions on demand
There are two alternatives to subscribing to daily updates: prefetching transaction data and on-demand refreshes. You might use these methods if you only want a one-time transaction data pull for a use case like underwriting. These methods are not mutually exclusive with maintaining a subscription, but most financial institutions don’t update transactions multiple times per day.
Prefetch transaction data
Specify whether you want to prefetch account transactions before account collection. This initiates the refresh process as soon as your user connects their account in the authentication flow. Set prefetch
when you require transaction data for every linked account, to make sure you receive it with minimal delay. The prefetch
parameter is available on all APIs that support Financial Connections.
After initiating a transaction refresh using prefetch
, wait for it to complete.
Initiate an on-demand refresh
Use the Refresh API to initiate on-demand transaction refreshes after account collection, and fetch transaction information for a specific account at your convenience, allowing you to defer the decision until a later time.
Note
Refreshes aren’t allowed on inactive accounts.
After initiating a transaction refresh using the Refresh API, wait for it to complete.
After a transaction refresh completes, Stripe sets the availability of future refreshes through the transaction_refresh.next_refresh_available_at field. Check this field before initiating a new transaction refresh to make sure that refreshes are currently available. If you attempt a refresh while the value is null
(as is always the case when the refresh is pending or the account is inactive) or the current time is less than the next_
timestamp, the refresh won’t be initiated.
Private preview
In the unlikely event that a refresh fails, the error
field on the refresh hash is a preview feature that provides the cause of the failure and recommended next steps. If you’d like to use it, email us for access.