# Relink Financial Connections accounts used for payments or payouts.

Reactivate inactive accounts to retrieve data, reactivate tokenized account numbers, 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 refreshing deactivated [tokenized account numbers](https://docs.stripe.com/financial-connections/tokenized-account-numbers.md).

When using Financial Connections accounts to verify bank account details for payments or payouts, configure a relink session to collect a single eligible account. You can:

- [Relink a specific Financial Connections account](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-specific-account)
- [Relink any eligible Financial Connections account at the same institution](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-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 "<<YOUR_SECRET_KEY>>:" \
  -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"
    }
  }
}
```

## Relink a specific Financial Connections account [Server-side] [Client-side]

Create a relink session that specifies `relink_options.authorization` and `relink_options.account` that requires your customer to pick the Financial Connections account identified by `relink_options.account` in the authentication flow. The session succeeds with a linked account only if your customer relinks that exact account. Resources created using the existing Financial Connections account automatically update with the relinked account details, including new tokenized account numbers. If your integration doesn’t require the same account, you can allow your customer to [link a new account at the same institution](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-account).

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. If you have a [two-step confirmation](https://docs.stripe.com/payments/build-a-two-step-confirmation.md) flow or [collect payment details before creating an Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md), the Financial Connections account won’t have an `account_holder`. In this case, set `account_holder` to `null` when creating the session.

1. Set the data `permissions` parameter to include `payment_method`, and any data you want to retrieve on the account. 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 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` parameter to the same value as the Financial Connections account’s `authorization` ID.

1. Set the `relink_options.account` parameter to the Financial Connections account’s ID.

   ```curl
   curl https://api.stripe.com/v1/financial_connections/sessions \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d "account_holder[type]=customer" \
     -d "account_holder[customer]={{CUSTOMER_ID}}" \
     -d "permissions[]=payment_method" \
     -d "permissions[]=balances" \
     -d "relink_options[authorization]={{FINANCIALCONNECTIONSAUTHORIZATION_ID}}" \
     -d "relink_options[account]={{FINANCIALCONNECTIONSACCOUNT_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",
     "filters": {
       "account_subcategories": ["checking", "savings"]
     },
     "limits": {
       "accounts": 1
     },
     "permissions": ["payment_method", "balances"],
     "relink_options": {
       "authorization": "{{AUTHORIZATION_ID}}",
       "account": "{{ACCOUNT_ID}}"
     }
   }
   ```

1. Use the returned `client_secret` with client-side Stripe SDKs to allow your user to relink their account. 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 collect an account. 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.

   ```js
   const {financialConnectionsSession, error} = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" });
   
   if (financialConnectionsSession) {
     if (financialConnectionsSession.relink_result.account) {
       // relink successful
       const relinkedAccount = financialConnectionsSession.accounts[0];
     } else {
       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;
       }
     }
   }
   ```

Your customer might authenticate with their financial institution successfully, but see an error in the Financial Connections authentication flow. In this case, `relink_result.account` isn’t set because we can’t match the selected account to the account given in `relink_options.account`. When this happens, we suggest either:

- Asking your customer to set up a new payment method or external bank account.
- Asking your customer to try again using a Financial Connections session that allows [any eligible account at the same institution](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-account).

## Optional: Relink any eligible Financial Connections account at the same institution [Server-side] [Client-side]

The `relink_options.account` parameter used in the previous section requires the customer to link a specific Financial Connections account. If the customer links a different account, they see an error message in the authentication flow.

You can instead create a relink session using only `relink_options.authorization`. This asks your customer to authenticate at the same institution as the authorization, without requiring them to select a particular account. Use `filters.account_subcategories` to specify that your customer can only select checking or savings accounts, and use `limits.accounts` to limit them to select a single account.

If your customer selects an existing Financial Connections account, its `status`, `permissions`, and `account_numbers` are updated. Resources created using the existing Financial Connections account automatically update with the relinked account details, including new tokenized account numbers. If your customer links a new account, you can use it to create a payment method. Existing payment methods are not updated automatically when a new account is selected in the relink authentication flow.

To allow your customer to link one payments- or payouts-eligible Financial Connections account at the same institution as their inactive account:

1. Create a Financial Connections session with `relink_options.authorization` set to the Financial Connections authorization ID you want to repair, `limits.accounts` set to `1` and `filters.account_subcategories` set to `["checking", "savings"]`

   ```curl
   curl https://api.stripe.com/v1/financial_connections/sessions \
     -u "<<YOUR_SECRET_KEY>>:" \
     -d "account_holder[type]=customer" \
     -d "account_holder[customer]={{CUSTOMER_ID}}" \
     -d "filters[account_subcategories][]=checking" \
     -d "filters[account_subcategories][]=savings" \
     -d "limits[accounts]=1" \
     -d "permissions[]=payment_method" \
     -d "permissions[]=balances" \
     -d "relink_options[authorization]={{FINANCIALCONNECTIONSAUTHORIZATION_ID}}"
   ```

1. Use the returned `client_secret` with client-side Stripe SDKs to allow your user to relink their account. 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 collect an account. 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.

1. Pass a list of linked accounts to the client-side to determine whether the customer linked a new account in the relink authentication flow.

   ```js
   // Fetch existing accounts, or embed them in the server-rendered HTML
   const existingAccountIds = await fetchExistingAccounts();
   
   const {financialConnectionsSession, error} = await stripe.collectFinancialConnectionsAccounts({
     clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh"
   });
   
   const linkedAccount = financialConnectionsSession?.accounts?.[0]
   
   if (linkedAccount) {
     const isNew = existingAccountIds.includes(linkedAccount.id);
   } else {
     // user linked no accounts
   }
   ```

We recommend allowing a customer to link a new account to handle the following edge cases when passing `relink_options.account`:

- Stripe sometimes doesn’t recognize any of the accounts available after the customer authenticates with their financial institution. When this happens and `relink_options.account` is set, the authentication flow shows an error message. When only `relink_options.authorization` is set, the customer can choose from the available accounts and proceed with the account linking flow.
- In OAuth flows, the customer can select a different account than the one initially linked in their financial institution’s OAuth modal.

## Optional: Create a payment method [Server-side] [Client-side]

Relink sessions that don’t specify `relink_options.account` might create new Financial Connections accounts. When this happens, payment methods created from existing Financial Connections accounts won’t be updated.

#### Payments

Use a `SetupIntent` to create a `PaymentMethod` using the Financial Connections account. Set the `customer` property to the same value as the Financial Connections account’s `account_holder.customer`. If your Financial Connections account doesn’t have an `account_holder` value, don’t set the `customer` property.

```curl
curl https://api.stripe.com/v1/setup_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "payment_method_types[]=us_bank_account" \
  -d "payment_method_data[type]=us_bank_account" \
  -d "payment_method_data[us_bank_account][financial_connections_account]={{FINANCIALCONNECTIONSACCOUNT_ID}}" \
  -d "payment_method_data[billing_details][name]=Jenny Rosen"
```

This creates a SetupIntent with a `status` of `requires_confirmation`. Show your customer an [ACH mandate](https://docs.stripe.com/payments/ach-direct-debit.md#mandates) and use a Stripe client library to [confirm](https://docs.stripe.com/js/setup_intents/confirm_us_bank_account_setup) the SetupIntent and collect mandate data.

```html
<!-- server-rendered HTML -->
<form id="confirmation-form" data-secret="seti_..._secret_...">
  <!-- mandate agreement text -->
  <button type="submit">Agree</button>
</form>

<script>
// client-side JS
const confirmationForm = document.getElementById('confirmation-form');

const acceptMandate = async (ev) => {
  // prevent default form submission behavior, and duplicate form submissions
  ev.preventDefault();
  confirmationForm.setAttribute('disabled', true);

  try {
    const clientSecret = ev.target.dataset.secret;

    await stripe.confirmUsBankAccountSetup(clientSecret).then(({setupIntent, error}) => {
      if (setupIntent) {
        // setupIntent was confirmed, and its payment_method is ready to use
      } else {
        // inspect error to determine what went wrong
      }
    });
  } finally {
    confirmationForm.removeAttribute('disabled');
  }
}

confirmationForm.addEventListener('submit', acceptMandate);
</script>
```

Read more about [accepting ACH payments](https://docs.stripe.com/payments/ach-direct-debit.md).

#### Payouts

Use a SetupIntent to create and confirm a PaymentMethod using the Financial Connections account. Set the `customer` property to the same value as the Financial Connections account’s `account_holder.customer`. If your Financial Connections account doesn’t have an `account_holder` value, don’t set the `customer` property.

```curl
curl https://api.stripe.com/v1/setup_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "flow_directions[]=outbound" \
  -d "payment_method_types[]=us_bank_account" \
  -d confirm=true \
  -d "payment_method_data[type]=us_bank_account" \
  -d "payment_method_data[us_bank_account][financial_connections_account]={{FINANCIALCONNECTIONSACCOUNT_ID}}" \
  -d "payment_method_data[billing_details][name]=Jenny Rosen"
```

Then create a bank account token using the `payment_method` attached to the SetupIntent. If you provided a `customer` when creating the SetupIntent, also provide it when creating the token.

```curl
curl https://api.stripe.com/v1/tokens \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "bank_account[payment_method]={{PAYMENTMETHOD_ID}}"
```

Read more about [Connect payouts](https://docs.stripe.com/connect/payouts-bank-accounts.md?bank-account-collection-integration=direct-api).

## 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 "<<YOUR_SECRET_KEY>>:" \
  -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.