Financial Connections fundamentals

Learn how Financial Connections works.

The Stripe Financial Connections product has two main components: end user bank account collection through the authentication flow, and data retrieval on the collected accounts. There are a number of ways to integrate Financial Connections. In the following example, we assume you’re using a Financial Connections Session. However, the overall concepts and flow diagrams function similarly with payments integrations such as Setup or Payment Intents.

To initialise and complete the Financial Connections authentication flow:

Your user initiates the bank account linking process on your client.
Create a Financial Connections Session on your server to drive the authentication flow.
Return the session’s client_secret to your client.
Initiate the authentication flow using collectFinancialConnectionsAccounts.
Your user completes the flow, which attaches accounts to the session.

After you have your user’s authenticated accounts, you can initiate data refreshes from your server. When the refreshes are complete, you can retrieve the account data.

Authentication flow

The authentication flow is the client-side UI that allows your user to consent to data sharing and link their financial accounts to you and Stripe.

Embed the UI in your client-side user flow. It works across all major browsers and platforms, including web, iOS, Android, and mobile web views.

Your user follows these steps during the authentication flow:

Step	Description
Give consent	Users consent to share requested data.
Select institution	Users select their bank either from frequently chosen banks or by searching over more than 5,000 other supported banks.
Log into bank	Users authenticate access to their accounts by logging into their bank.
Select account(s)	Users select which specific account(s) to link.
Success	Users see a success screen after authentication completes successfully.

For payments integrations such as Setup Intents, you can configure the authentication flow to use microdeposits as a fallback using the verification_method parameter.

Return user optimisation

Financial Connections enables your users to connect their accounts in fewer steps with Link, allowing them to save and quickly reuse their bank account details across Stripe businesses.

For return users, launch the Financial Connections authentication flow with a Customer that has an email address. See our use case guide for examples of how to do this for your specific use case.

How Stripe links financial accounts

During the authentication flow, your user logs into their bank through either an OAuth (bank-hosted) or non-OAuth flow to authenticate access to their accounts. Stripe typically defaults the authentication flow to OAuth if it’s available at the financial institution. Your integration doesn’t need to treat OAuth accounts differently than non-OAuth accounts.

OAuth is a standardised protocol that allows users to grant applications (for example, Stripe) access to their information within other applications (for example, bank apps). This protocol eliminates the need for users to share their login credentials.

Here’s how OAuth and Financial Connections function together:

When your user selects their bank in the Financial Connections authentication flow, they’re sent to their bank’s website or mobile app.
Your user logs into their bank and grants the bank permission to share account data (such as balances or transactions) with Stripe.
The bank redirects your user back to the authentication flow, passing a token that allows Stripe access to approved bank account information.
Your user never shares their login credentials with Stripe.

In non-OAuth flows, end users provide credentials directly to Stripe or one of our trusted partners.

Financial Connections Account

Successful completion of the authentication flow creates one Financial Connections Account for each account authorised by your user. The Financial Connections Account is the API object you use to access additional account data, such as balances and transactions. They represent external financial accounts such as current/checking, savings, loan, or credit card accounts. See the account_subcategory field on the account for a list of all account types we support. Only cash-based accounts, such as current/checking and savings accounts, allow ACH (Automated Clearing House) transfers.

Data permissions

After collecting an account, you immediately receive access to the following information:

Last four digits of the account number
Account category such as current or savings
Account nickname, if available

To access additional account data such as balances or transactions, you must request access with data permissions. You configure data permissions on server-side objects such as the Financial Connections Session using the permissions parameter.

Data Available	Permissions	Description
Account details	`payment_method`	Tokenised account and routing number (required for money movement)
Account owners	`ownership`	Account owner names and mailing addresses
Balances	`balances`	Current and available balances
Transactions	`transactions`	Pending and posted transactions

Consider the data required to fulfil your use case and request permission to access only the data you need. Requesting permissions that go well beyond your application’s scope may erode your users’ trust in how you use their data. For example, if you’re building a personal financial management application or a lending product, you might request transactions data. If you’re mitigating fraud such as account takeovers, you might want to request ownership details.

During the authentication flow, your users can see the data types that you’ve requested access to. They must provide their consent to share this data. To expand the data types you have access to, your user needs to complete the authentication flow again with the new data permissions.

Consult the balances integration guide for an example of how to access financial account data, or learn more about use cases for the different data types.