Relink Financial Connections accounts used for data products.Version bêta publique

Your customer’s linked Financial Connections Accounts might become inactive for several reasons, including:

• Le token OAuth fourni à Stripe par sa banque expire au bout d’une certaine période ou pour cause d’inactivité.
• 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. 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 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:

import stripe
import requests as r
from requests.auth import HTTPBasicAuth

stripe.api_version = '2026-03-04.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 https://api.stripe.com/v1/financial_connections/accounts/
{{ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2026-03-04.preview"

{
  "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 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

   Sélectionner une langue

   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]"=
   "{{CUSTOMER_ID}}" \
     -d "permissions[]"=payment_method \
     -d "permissions[]"=balances \
     -d "relink_options[authorization]"=
   "{{AUTHORIZATION_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}}"
     }
   }
   

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;
       }
     }
   }

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.

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.