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

Create a Financial Connections session

Create a Financial Connections Session and specify the following:

1. Set account_holder[customer] to the customer id.
2. 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, transactions]. 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. 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.
3. Set the relink_options[authorization] to the authorization ID to target the authorization of the account that you want to repair data access for.
4. Set filters[account_subcategories] to checking, savings.
5. Set limits[accounts] to 1.

You can only add one debitable account to accept ACH Direct Debit payments with Stripe.

curl https://api.stripe.com/v1/financial_connections/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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]"=fcauth_1LDYuMGxLVUXRs6HW0lrat9T

The 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": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T"
  }
}

Relink a Financial Connections account

Use the returned client_secret with Stripe.js to allow your user to relink their accounts. 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.

Use stripe.collectFinancialConnectionsAccounts to collect an account.

// Fetch existing accounts on the authorization to determine whether the linked account is new.
const existing_account_ids = await fetch_existing_accounts();
const financialConnectionsSessionResult = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" });

Stripe.js loads the authentication flow, the client-side Stripe.js UI that helps your users see and consent to share the data you requested to access from the permissions parameter, and re-link their financial accounts to you and Stripe.

The authentication flow might look like the following:

The return value of stripe.collectFinancialConnectionsAccounts is a Promise. When the user completes the authentication flow, the Promise resolves with an object that contains the list of relinked accounts:

stripe.collectFinancialConnectionsAccounts(clientSecret)
  .then(({financialConnectionsSession, error}) => {
    if (error) {
      // The session failed for some reason.
      console.error(error.message);
    } else if (financialConnectionsSession.accounts.length > 0) {
      // User has authorized some account on the authorization.
      const is_new = !existing_account_ids.includes(financialConnectionsSession.accounts[0].id);
      // The user has connected a new account on the authorization.
      if (is_new) {
        // You must surface the mandate for new accounts to process ACH payments.
        return surface_mandate();
      } else {
        // User has reauthorized an existing payment account.
        reload_account(financialConnectionsSession.accounts[0].id);
        return display_success();
      }
    } else if (accounts.length == 0) {
      // The session failed to connect an account.
    }
  });

If your user has linked an account for data sharing, the length of accounts is > 0.

Within the OAuth flows of your end users’ financial institution, it’s possible for them to select a different account than the one initially linked. The is_new field will include the new account ID if your user has linked a different account than they initially linked. Follow the steps to convert the newly created Financial Connections account into a Payment Method.

If the user has no debitable accounts, length of accounts is 0.

Create a Session

Create a Financial Connections Session and specify the following:

1. Set account_holder[customer] to the customer id.
2. 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, transactions]. 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. 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.
3. Set the relink_options[authorization] to the authorization ID to target the authorization of the account that you want to repair data access for.

curl https://api.stripe.com/v1/financial_connections/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "account_holder[type]"=customer \
  -d "account_holder[customer]"=
"{{CUSTOMER_ID}}" \
  -d "permissions[]"=payment_method \
  -d "permissions[]"=balances \
  -d "relink_options[authorization]"=fcauth_1LDYuMGxLVUXRs6HW0lrat9T

The 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",
  "permissions": [
    "payment_method", "balances"
  ],
  "relink_options": {
    "authorization": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T"
  }
}

Relink a Financial Connections account

Use the returned client_secret with Stripe.js to allow your user to relink their accounts. 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.

Use stripe.collectFinancialConnectionsAccounts to collect an account.

// Fetch existing accounts on the authorization to determine whether the linked account is new.
const existing_account_ids = await fetch_existing_accounts();
const financialConnectionsSessionResult = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" });

The return value of stripe.collectFinancialConnectionsAccounts is a Promise. When the user completes the authentication flow, the Promise resolves with an object that contains the list of relinked accounts:

stripe.collectFinancialConnectionsAccounts(client_secret).then(({session, error}) => {
    if (error) {
      // The session failed for some reason.
      console.error(error.message);
    } else if (session.accounts.length > 0) {
      // User has reauthorized existing Financial Connections accounts.
      reload_accounts(session.accounts);
    } else if (accounts.length == 0) {
      // The session failed to connect an account.
    }
  });

If your user has linked an account for data sharing, the length of accounts is > 0.

Within the OAuth flows of your end users’ financial institution it’s possible for them to select a different account than the one they initially linked.