Public preview

Use the Financial Connections API to relink an account Public preview

Integrate the relink authentication flow directly into your website or application.

Your customer might need to relink an existing Financial Connections account to restore data access, refresh deactivated tokenized account numbers, or update the data permissions available on the account. Use the Financial Connections server-side API and a client-side SDK library to prompt your customer to complete a relink session directly in your website or application.

Your integration will:

1. Create a Financial Connections session on the server which sets the relink_options parameter.
2. Pass the session’s client_secret to your front end.
3. Use a client SDK method such as collectFinancialConnectionsAccounts to prompt your customer to complete the authentication flow.
4. Handle the relinking outcome on the client.
5. Optionally, handle webhook events when accounts relink successfully.

Basic API relink flow

Create a Financial Connections Session with relink_options.authorization, then pass the returned client_secret to your client.

The following example asks your customer to reauthenticate with the institution associated with an existing Financial Connections Authorization. The customer can relink any eligible account at that institution.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Use the returned client_secret with collectFinancialConnectionsAccounts to present the authentication flow to your customer. When the customer completes the flow, the returned financialConnectionsSession includes a relink_result sub-object:

const {financialConnectionsSession, error} = await stripe.collectFinancialConnectionsAccounts({
 clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh",
});

if (error) {
 // Show the error to your customer or ask them to try again.
 return;
}

if (financialConnectionsSession) {
 if (financialConnectionsSession.relink_result.authorization) {
 // Relink succeeded. Use financialConnectionsSession.accounts on your server.
 } else if (financialConnectionsSession.relink_result.failure_reason) {
 switch (financialConnectionsSession.relink_result.failure_reason) {
 case 'no_account':
 // The customer authenticated, but didn't link an eligible account.
 break;
 case 'no_authorization':
 // The customer didn't successfully authenticate with their institution.
 break;
 case 'other':
 // An unexpected failure occurred.
 break;
 }
 }
}

For payments or payouts, you might also need to constrain account selection with filters.account_subcategories and limits.accounts. For data products, you might need to reconcile all accounts on the Authorization. See the guides in the following section for those variants.

Next steps

Relink for payments or payouts

Configure the authentication flow to relink accounts used for payments or payouts.

Relink for data products

Configure the authentication flow to relink accounts used to access data such as balances, transactions, and ownership.

Stripe-hosted relink

Email your customer a link to a Stripe-hosted page to relink an account.