Public preview

Relink Financial Connections accounts used for payments or payouts. Public preview

Reactivate inactive accounts to retrieve data, reactivate tokenised account numbers, and update data permissions.

Your customers might need to reauthorise a previously linked Financial Connections account for multiple reasons, such as reactivating an account to restore data access or refreshing deactivated tokenised account numbers.

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
Relink any eligible Financial Connections account at the same institution

Before you begin

Read about inactive Financial Connections accounts to understand why accounts become inactive and when they can be relinked.

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 tokenised 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.

Create a Financial Connections session and specify the following:

Set account_holder to the same value of the Financial Connections account’s account_holder field. If you have a two-step confirmation flow or collect payment details before creating an Intent, the Financial Connections account won’t have an account_holder. In this case, set account_holder to null when creating the session.
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 fulfil 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.
Set the relink_options.authorization parameter to the same value as the Financial Connections account’s authorization ID.
Set the relink_options.account parameter to the Financial Connections account’s ID. Command Line Select a language 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_Ou1w6LVt3zmVipDVJsvMeQsc:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]={{the related setting}}" \ -d "permissions[]=payment_method" \ -d "permissions[]=balances" \ -d "relink_options[authorization]={{the related setting}}" \ -d "relink_options[account]={{the related setting}}" 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": "{{the related setting}}", "account": "{{the related setting}}" } }
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.
In Stripe.js, use collectFinancialConnectionsAccounts 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. 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 .

Optional Relink any eligible Financial Connections account at the same institution Server-side Client-side

Optional Create a payment method Server-side Client-side

Optional Retrieve a Financial Connections authorisation

Financial Connections accounts have an authorisation property that corresponds to a Financial Connections authorisation resource. The authorisation resource describes the overall status of the data connection for all accounts on the authorisation, whether or not they require relinking. When several accounts reference the same authorisation, relinking one account might reactivate other accounts on the same authorisation. This is expected and only affects your integration if you:

Have a webhook endpoint that listens to financial _ connections. account. reactivated events.
Have business logic that assumes a relink session which requires the user to select a single account will reactivate exactly one account.

Retrieve an authorisation to see its status:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

{
 "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 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 tokenised account number refresh behaviour, search for the Tokenized Account Numbers institution in the authentication flow, and connect any of the provided bank accounts. To test with an account that will deactivate in the future, search for the Reauthentication Required Immediately or Reauthentication Required Eventually institutions in the authentication flow, and connect any of the provided bank accounts.