Public preview

Relink Financial Connections accounts used for data products. Public preview

Reactivate inactive accounts to retrieve data and update data permissions.

Your customers might need to reauthorize a previously linked Financial Connections account for multiple reasons, such as reactivating an account to restore data access or updating the data permissions available on the account.

Before you begin

Read about inactive Financial Connections accounts to understand why accounts become inactive and when they can be relinked.

Create a Financial Connections session Server-side

Create a Financial Connections session and specify the following:

1. Set account_holder to the same value of the Financial Connections account’s account_holder field.
2. Set the data permissions parameter. The permissions parameter is an array containing values, which might include any of payment_method, balances, ownership, or transactions. To protect the privacy of your user’s data, you can only access the account data you specified in the permissions parameter. Carefully consider the data required to fulfill your use case, and request permission to access only the data you require. When completing the authentication flow, your user sees the data you specified from the permissions parameter, and provides their consent to share this data. The following code example demonstrates how to collect balances and payment_method.
3. Set the relink_options.authorization parameter to the authorization you want to relink.
4. (Optional) Set filters.account_subcategories to limit which types of accounts can be relinked. Command Line Select a language cURL Stripe CLI Ruby Python PHP Java Node.js Go.NET No results curl https://api.stripe.com/v1/financial_connections/sessions \ -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]={{the related setting}}" \ -d "permissions[]=payment_method" \ -d "permissions[]=balances" \ -d "relink_options[authorization]={{the related setting}}" This request returns a response similar to the following: { "id": "fcsess_abcd", "object": "financial_connections.session", "livemode": true, "account_holder": { "customer": "cus_NfjonN9919dELB", "type": "customer" }, "accounts": [], "client_secret": "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh", "permissions": ["payment_method", "balances"], "relink_options": { "authorization": "{{the related setting}}" } }

Initiate the relink flow Client-side

1. Use the returned client_secret with client-side Stripe SDKs to allow your user to relink 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.
2. In Stripe.js, use collectFinancialConnectionsAccounts to show the relink authentication flow to your customer. The return value of collectFinancialConnectionsAccounts is a Promise. When the user completes the authentication flow, the Promise resolves with an object that contains a relink_result sub-object. If successful, it also contains the list of relinked accounts. // Fetch existing accounts, or embed them in the server-rendered HTML const existingAccounts = await fetchExistingAccounts(); const {financialConnectionsSession, error} = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" }); if (financialConnectionsSession) { const { relink_options: relinkOptions, relink_result: relinkResult } = financialConnectionsSession; if (relinkResult.authorization && relinkOptions.authorization === relinkResult.authorization) { // Relink succeeded for given authorization // Compare financialConnectionsSession.accounts and existingAccounts to determine if all accounts were reauthorized } else if (relinkResult.authorization) { // Customer authenticated successfully, but generated a new Authorization // Reconcile financialConnectionsSession.accounts and existingAccounts } else { // Relink was not successful switch (financialConnectionsSession.relink_result.failure_reason) { case 'no_account': // user successfully authenticated with their bank, but did not link the expected account break; case 'no_authorization': // user did not successfully authenticate with their bank break; case 'other': // unexpected failure break; } } }

Retrieve data on a Financial Connections account Server-side

After your customer has successfully completed the authentication flow, you can access or refresh the account data you specified in the permissions parameter of the Financial Connections session.

To protect the privacy of your user’s data, you can only access account data that you specified in the permissions parameter.

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

Optional Retrieve a Financial Connections authorization

Financial Connections accounts have an authorization property that corresponds to a Financial Connections authorization resource. The authorization resource describes the overall status of the data connection for all accounts on the authorization, whether or not they require relinking. When several accounts reference the same authorization, relinking one account might reactivate other accounts on the same authorization. This is expected, and only affects your integration if you:

1. Have a webhook endpoint that listens to financial _ connections. account. reactivated events.
2. Have business logic that assumes a relink session which requires the user to select a single account will reactivate exactly one account.

Retrieve an authorization to see its status:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

{
 "id": "{{AUTHORIZATION_ID}}",
 "object": "financial_connections.authorization",
 "account_holder": {
 "customer": "cus_TnvzdXv6VwjyrN",
 "type": "customer"
 },
 "institution": "fcinst_Qn1a6jqpI0Gb84",
 "institution_name": "StripeBank",
 "livemode": false,
 "status": "active",
 "status_details": {}
}

Testing

Follow the testing guide to learn how to connect a test bank account through Financial Connections. To test with a deactivated account, search for the Inactive accounts institution in the authentication flow, and connect any of the provided bank accounts. To test tokenized account number refresh behavior, search for the Tokenized Account Numbers institution in the authentication flow, and connect any of the provided bank accounts. To test with an account that will deactivate in the future, search for the Reauthentication Required Immediately or Reauthentication Required Eventually institutions in the authentication flow, and connect any of the provided bank accounts.