Relink data access to a Financial Connections account with your user’s permissionPublic preview

You’re notified when a previously linked Financial Connections account becomes inactive with the financial_connections.account.deactivated webhook. If the account’s authorization is inactive, then the inactive subhash on the status_details hash on the Authorization object shows a relink_required action if it’s possible to relink an inactive authorization. For example, you might have 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-01-28.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"]
        authorization_response = r.get("https://api.stripe.com/v1/financial_connections/authorizations/" + account["authorization"], headers={"Stripe-Version": stripe.api_version}, auth=HTTPBasicAuth(SECRET_KEY, ''))
        authorization = authorization_response.json()
        if authorization["status"] == 'inactive' and authorization["status_details"]["inactive"]["action"] == 'relink_required':
          prompt_user_to_relink(authorization)
        else:
          # No action to be taken.

    return jsonify(success=True)

Additionally, you can retrieve the status of an account by retrieving the account using the account ID.

curl https://api.stripe.com/v1/financial_connections/accounts/:id \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "GET" \
  -H "Stripe-Version: 2026-01-28.preview"

{
  "id": "fca_1LDYuMGxLVUXRs6HW0lrat9T",
  "object": "financial_connections.account",
  //...,
  "authorization": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T",
  "status": "inactive"
}

You can then retrieve the authorization of the account using the authorization ID.

curl https://api.stripe.com/v1/financial_connections/authorizations/:id \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "GET" \
  -H "Stripe-Version: 2026-01-28.preview"

{
  "id": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T",
  "object": "financial_connections.authorization",
  //...,
  "status": "inactive",
  "status_details": {
    "inactive": {
      "action": "relink_required"
    }
  }
}

The authorization.status_details.inactive.action is none when an inactive account can’t be relinked for data access. In this case, redirect the end user to the usual authentication flow to select an institution and connect an account from scratch.

{
  "id": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T",
  "object": "financial_connections.authorization",
  //...,
  "status": "inactive",
  "status_details": {
    "inactive": {
      "action": "none"
    }
  }
}

In some cases, the Authorization of an account might be active, but the account itself is inactive. This might happen, for instance, if the account was closed at the institution. In these cases, the inactive account can’t be relinked for data access. Likewise in this case, redirect the end user to the usual authentication flow to select an institution and connect an account from scratch.

To reestablish data access on an inactive account, retrieve the ID of the account’s authorization from the account object.

{
  "id": "fca_1LDYuMGxLVUXRs6HW0lrat9T",
  "object": "financial_connections.account",
  //...,
  "authorization": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T",
  "status": "inactive"
}

You have two options to repair data access on a Financial Connections account, which depend on whether you want to repair an account previously linked to accept ACH Direct Debit payments with Stripe, or some other purpose.

Before you can regain data access from a user’s bank account with Financial Connections, your user must re-authenticate their account with the authentication flow. They begin the authentication flow when they want to relink their account to your site or application. Insert a button or link on your site or in your application, which allows a user to re-link their account—for example, your button might say “Re-link your bank account”.

When they see the authentication flow, your end user is prompted to authenticate access to their account at the relevant financial institution. Unlike the authentication flow where your user first links a new account, your end user won’t need to choose their financial institution from the bank picker.

After your user has successfully completed the authentication flow, 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, account data accessible to you is limited to the data you specified in the permissions parameter.

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