Collect an account to build data-powered products

Collect your user's account and use data such as balances, ownership details, and transactions to build products.

Available in:

Financial Connections lets your users securely share their financial data by linking their external financial accounts to your business. You can use Financial Connections to access user-permissioned financial data such as tokenized account and routing numbers, account balances, account owner information, and historical transactions.

Some common examples of how you can use Financial Connections to improve product experiences for your users include:

Mitigate fraud when onboarding a customer or business by verifying the ownership information of an account, such as the name and address of the bank account holder.
Help your users track expenses, handle bills, manage their finances and take control of their financial well-being with transactions data.
Speed up underwriting and improve access to credit and other financial services with transactions and balances data.
Enable your users to connect their accounts in fewer steps with Link, allowing them to save and quickly reuse their bank account details across Stripe merchants.

Set up Stripe
Server-side

Use our official libraries for access to the Stripe API from your application:

Create or retrieve an account holder
Server-side

Create a Customer object when users create an account with your business. By providing an email address, Financial Connections can optimize the authentication flow by dynamically showing a streamlined user interface, for returning Link users.

Create a Financial Connections Session
Server-side

Before you can retrieve data from a user’s bank account with Financial Connections, your user must authenticate their account with the authentication flow.

Your user begins the authentication flow when they want to connect their account to your site or application. Insert a button or link on your site or in your application, which allows a user to link their account—for example, your button might say “Link your bank account”.

Create a Financial Connections Session by posting to /v1/financial_connections/sessions:

Set account_holder[customer] to the Customer id.
Set the data permissions parameter to include the data required to fulfill your use case.
(Optional) set the prefetch parameter for retrieving the data on account creation.

The permissions parameter controls which account data you can access. You must request at least one permission. When completing the authentication flow, your user can see the data you’ve requested access to, and provide their consent to share it.

Consider the data required to fulfill your use case and request permission to access only the data you need. Requesting permissions that go well beyond your application’s scope might 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.

After your user authenticates their account, you can expand data permissions only by creating a new Financial Connections Session and specifying a new value for the permissions parameter. Your user must complete the authentication flow again, where they’ll see the additional data you’ve requested permission to access, and provide consent to share their data.

The optional prefetch parameter controls which data you retrieve immediately after the user connects their account. Use this option if you know you always want a certain type of data. It removes the need to make an extra API call to initiate a data refresh.

To preserve the option to accept ACH Direct Debit payments, request the payment_method permission.

Collect a Financial Connections account
Client-side

Use the returned client_secret with Stripe.js to allow your user to connect their accounts. A client_secret allows client-side Stripe SDKs to make changes to the Financial Connections Session. Don’t store it, log it, embed it in URLs, or expose it to anyone other than your end user. Make sure that you have TLS enabled on any page that includes the client secret.

Use collectFinancialConnectionsAccounts to collect an account.

const stripe = new Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
)
const financialConnectionsSessionResult = await stripe.collectFinancialConnectionsAccounts({
  clientSecret: "{{SESSION_CLIENT_SECRET}}",
});

This method loads the authentication flow, the client-side Stripe.js UI that helps your users link their financial accounts to you and Stripe.

The return value of stripe.collectFinancialConnectionsAccounts is a Promise. When the user completes the authentication flow, the Promise resolves with an object that contains the list of connected accounts:

{
  "financialConnectionsSession": {
    "id": "fcsess_123",
    "accounts": [
      {
        "id": "fca_456",
        "object": "financial_connections.account",
        "category": "Checking",
        "display_name": "Premium Checking",
        "institution_name": "Test Bank",
        "last4": "4242"
      }
    ]
  }
}

If the user connects no accounts, or exits the authentication flow early, the response contains an empty accounts array.

Successful completion of the authentication flow also sends one financial_connections.account.created webhook per account connected.

Retrieve data on a Financial Connections account
Server-side

After your user has successfully completed the authentication flow, access or refresh the account data you’ve specified in the permissions parameter of the Financial Connections Session.

To protect the privacy of your user’s data, account data accessible to you is limited to the data you’ve specified in the permissions parameter.

Follow the guides for balances, ownership and transactions to start retrieving account data.

OptionalAccept an ACH Direct Debit payment from a Financial Connections account

You can optionally accept ACH Direct Debit payments on a previously collected Financial Connections account as long as the supported_payment_method_types attribute on the account includes us_bank_account.

Only US bank accounts are eligible to accept ACH Direct Debits such as a checking or savings account.

To accept an ACH Direct Debit payment on a previously collected account, you must have specified payment_method in the data permissions parameter on the Financial Connections Session.

Create a Payment Intent or Setup Intent

Use the Payment Intents API to accept an ACH Direct payment for an account you want to charge now. Use the Setup Intents API to save details for future ACH Direct Debit payments. Learn more about the difference between a Payment Intent and Setup Intent.

This path shows you how to accept an ACH Direct Debit payment using the Payment Intents API.

Use the Financial Connections account ID and the customer ID to create a Payment Intent:

This will return a Payment Intent similar to:

{
  "id": "pi_1GszXf2eZvKYlo2Ce7rjvnPP",
  "object": "payment_intent",
  "amount": 100,
  "amount_capturable": 0,
  "amount_details": {
    "tip": {
      "amount": null
    }
  },
  "amount_received": 0,
  "application": null,
  "application_fee_amount": null,
  "automatic_payment_methods": null,
  "canceled_at": null,
  "cancellation_reason": null,
  "capture_method": "automatic",
  "charges": {
    "object": "list",
    "data": [

Collect mandate acknowledgement and submit the payment

Before you can initiate the payment, you must obtain authorization from your customer by displaying mandate terms for them to accept.

To be compliant with Nacha rules, you must obtain authorization from your customer before you can initiate payment by displaying mandate terms for them to accept. For more information on mandates, see Mandates.

Confirm the Payment Intent

To confirm this Payment Intent, you need to provide either a mandate parameter with an existing Mandate ID, or provide mandate_data to create a new mandate.

For example, if you have a checkout page with a “Place Order” button, clicking that button could trigger a POST to an endpoint on your server. That endpoint could extract the request’s User Agent and the client’s IP address, and then make the following request to Stripe’s API:

After successfully confirming the Payment Intent, it will look similar to:

{
  "id": "pi_1GszXf2eZvKYlo2Ce7rjvnPP",
  "object": "payment_intent",
  "amount": 100,
  "amount_capturable": 0,
  "amount_received": 0,
  "application": null,
  "application_fee_amount": null,
  "automatic_payment_methods": null,
  "canceled_at": null,
  "cancellation_reason": null,
  "capture_method": "automatic",
  "charges": {
    "object": "list",
    "data": [
      {
        "id": "py_17F8CPDyDglZKgWE3uzOAUe9",
        "object": "charge",
        "amount": 100,
        "amount_captured": 100,

ACH Direct Debit is a delayed notification payment method. This means that it can take up to four business days to receive notification of the success or failure of a payment after you initiate a debit from your customer’s account.

The PaymentIntent you create initially has a status of processing. After the payment succeeds, the PaymentIntent status is updated from processing to succeeded. Learn about the events that are sent when the PaymentIntent status is updated.