Manage inactive Financial Connections accounts

Learn why Financial Connections accounts become inactive and how to manage them.

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

• The OAuth 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.

Behavior by bank

The institutions in the following table require customers to reauthenticate.

Understand when an account becomes inactive

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:

Python

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

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
client = stripe.StripeClient('sk_test_BQokikJOvBiI2HlWgH4olfQ2', stripe_version='2026-08-26.preview')

# If you're 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 = client.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 the account doesn't 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.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

{
 "id": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}",
 "object": "financial_connections.account",
 //...,
 "authorization": "{{AUTHORIZATION_ID}}",
 "status": "inactive",
 "status_details": {
 "inactive": {
 "action": "relink_required",
 "cause": "access_expired"
 }
 }
}

Understand when an account will become inactive in the future

In some cases, such as when the OAuth token provided to Stripe by their financial institution expires after a set period of time, the API will provide information about when the account is expected to become inactive.

To determine whether an account falls into this category, retrieve the Account and check the additional metadata in the status_details.active subhash. If the subhash is empty, we don’t have information about future deactivation for this account.

• The status _ details. active. expected _ deactivation _ date property includes the estimated date at which this account will become inactive.
• The status_details.active.cause property includes a high-level reason why we expect the Financial Connections account to become inactive . For example, when an account’s OAuth connection expires after a set period of time, its status would be access _ expired .
• The status_details.active.action property includes the action to take, if any, to prevent the account from becoming inactive . We set this property to relink _ required when we expect completing the relink authentication flow to meaningfully change the expected _ deactivation _ date . For example, we won’t recommend prompting your user to relink their account until 30 days before deactivation for time-based OAuth expiration.

We notify you 30 days before a Financial Connections account is expected to deactivate with the financial_connections.account.upcoming_deactivation webhook. When you receive this webhook, it is a good time to ask your customer to relink their account, or connect a new account, to avoid interruptions to data access.

If your integration prompts users to repair any Financial Connections account at the same institution rather than a specific account, you can view the status_details.active subhash on the Financial Connections Authorization and listen to the financial_connections.authorization.upcoming_deactivation webhook instead.

Learn more

• Relink : Repair inactive accounts with the streamlined relink flow.