# Relink Financial Connections accounts used for data products. Reactivate inactive accounts to retrieve data and update data permissions. Your customers might need to reauthorize a previously linked [Financial Connections account](https://docs.stripe.com/api/financial_connections/accounts/object.md) for [multiple reasons](https://docs.stripe.com/financial-connections/relink.md), such as reactivating an account to restore data access or updating the data permissions available on the account. ## Understand when an account becomes inactive [Server-side] Your customer’s linked Financial Connections Accounts might become inactive for several reasons, including: - The [OAuth](https://docs.stripe.com/financial-connections/fundamentals.md#how-stripe-links-financial-accounts) token provided to Stripe by their financial institution expires after a set period of time or because of inactivity. - The financial institution changes their authentication requirements, such as requiring multi-factor authentication (MFA), or the customer changes their username and password. - The customer revokes access through their online banking portal. - The customer closes their account at their financial institution. We notify you when a Financial Connections Account becomes inactive with the `financial_connections.account.deactivated` [webhook](https://docs.stripe.com/financial-connections/webhooks.md). Inactive Financial Connections Accounts include additional status metadata in the `status_details.inactive` subhash. You can’t repair every underlying cause for an inactive account. For example, you can’t repair a closed account unless your customer reopens it. Accounts that you can’t repair have a `status_details.inactive.action` of `none`. You can [retrieve a Financial Connections Account](https://docs.stripe.com/api/financial_connections/accounts/retrieve.md) at any time to check its status. - The `status_details.inactive.cause` property includes a high-level reason why a Financial Connections Account is inactive. For example, when an account’s OAuth connection expires, its status is `access_expired`. - The `status_details.inactive.action` property includes the action to take, if any, to reactivate the account. If your customer can reactivate the account by completing a relink authentication flow, its status is `relink_required`. When `status_details.inactive.action` is `relink_required`, prompt your customer to complete the authentication flow to reactivate the account. For example, you might create a webhook handler like the one below to process webhook events: #### Python ```python import stripe import requests as r from requests.auth import HTTPBasicAuth stripe.api_version = '2026-03-25.preview' # If you are testing your webhook locally with the Stripe CLI you # can find the endpoint's secret by running `stripe listen` # Otherwise, find your endpoint's secret in your webhook settings in # the Developer Dashboard endpoint_secret = 'whsec_...' @app.route('/webhook', methods=['POST']) def webhook(): event = None payload = request.data sig_header = request.headers["STRIPE_SIGNATURE"] try: event = stripe.Webhook.construct_event(payload, sig_header, endpoint_secret) except ValueError as e: # Invalid payload raise e except stripe.error.SignatureVerificationError as e: # Invalid signature raise e if event["type"] == "financial_connections.account.deactivated": account = event["data"]["object"] if account["status"] == "inactive": if "status_details" in account: if account["status_details"]["inactive"]["action"] == "relink_required": prompt_user_to_relink(account) else: # if account does not have "status_details", check that the event destination is configured with the most recent public preview API version else: # No action to be taken. return jsonify(success=True) ``` The `status` and `status_details` of an account are also available when you retrieve a Financial Connections Account. ```curl curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" ``` ```json { "id": "{{ACCOUNT_ID}}", "object": "financial_connections.account", //..., "authorization": "{{AUTHORIZATION_ID}}", "status": "inactive", "status_details": { "inactive": { "action": "relink_required", "cause": "access_expired" } } } ``` ## Create a Financial Connections session [Server-side] [Create a Financial Connections session](https://docs.stripe.com/api/financial_connections/sessions/create.md) and specify the following: 1. Set [account_holder](https://docs.stripe.com/api/financial_connections/sessions/create.md#financial_connections_create_session-account_holder) to the same value of the Financial Connections account’s `account_holder` field. 1. Set the data [permissions](https://docs.stripe.com/api/financial_connections/sessions/create.md#financial_connections_create_session-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`. 1. Set the [relink_options.authorization](https://docs.stripe.com/api/financial_connections/sessions/create.md#financial_connections_create_session-relink_options-authorization) parameter to the `authorization` you want to relink. 1. (Optional) Set [filters.account_subcategories](https://docs.stripe.com/api/financial_connections/sessions/create.md#financial_connections_create_session-filters-account_subcategories) to limit which types of accounts can be relinked. ```curl curl https://api.stripe.com/v1/financial_connections/sessions \ -u "<>:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]={{CUSTOMER_ID}}" \ -d "permissions[]=payment_method" \ -d "permissions[]=balances" \ -d "relink_options[authorization]={{FINANCIALCONNECTIONSAUTHORIZATION_ID}}" ``` 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": "{{AUTHORIZATION_ID}}" } } ``` ## Initiate the relink flow [Client-side] 1. Use the returned [client_secret](https://docs.stripe.com/api/financial_connections/sessions/object.md#financial_connections_session_object-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. 1. In Stripe.js, use [collectFinancialConnectionsAccounts](https://docs.stripe.com/js/financial_connections/collect_financial_connections_accounts) 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](https://docs.stripe.com/api/financial_connections/sessions/object.md#financial_connections_session_object-relink_result) sub-object. If successful, it also contains the list of relinked accounts. ```js // 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](https://docs.stripe.com/financial-connections/balances.md), [ownership](https://docs.stripe.com/financial-connections/ownership.md), and [transactions](https://docs.stripe.com/financial-connections/transactions.md) to retrieve account data. ## Optional: Retrieve a Financial Connections authorization Financial Connections accounts have an `authorization` property that corresponds to a [Financial Connections authorization](https://docs.stripe.com/api/financial_connections/authorizations/object.md) resource. The authorization resource describes the overall status of the data connection for all accounts on the authorization. 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. 1. 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: ```curl curl https://api.stripe.com/v1/financial_connections/authorizations/{{FINANCIALCONNECTIONSAUTHORIZATION_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" ``` ```json { "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](https://docs.stripe.com/financial-connections/testing.md) 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.