Linked Accounts

Part ofEmbedded Banking↗

Lists the organization's external bank accounts and lets the user connect, edit, verify with micro-deposits, and unlink them.

Quick Start

import { LinkedAccountsWidget } from '@tesouro/embedded-components-react';

export function LinkedAccountsPage() {
  return (
    <LinkedAccountsWidget
      baseUrl="https://api.example.com"
      widgetToken="wt_live_abc123"
      organizationId="org_xyz"
    />
  );
}

Behaviour

• Actions follow the token's scopes. The widget waits for widget init before fetching and hides what the token can't do:
  • Read (embedded:externalbankaccount:read or external_bank_account:read:org) lists accounts. Without it the widget shows the empty state.
  • Write (embedded:externalbankaccount:write or external_bank_account:write:org) enables connect, edit, verify and unlink.
  • Micro-deposit (embedded:externalbankaccount:micro-deposit or external_bank_account:micro_deposit:org) starts micro-deposits during connect and from unverified rows.
  • Organization read (organization:read:org) pre-fills the connect wizard's legal name on account. Without it the field starts empty and the user types the name.
• The widget shows a skeleton while the widget token is missing or widget init is loading, so a missing token looks like loading rather than an error.
• Add external account opens a three-step wizard: bank details, team member access (administrators are always on), and a success screen.
  • Bank details asks whether the account is Personal or Business (required). The choice is sent as accountHolderType so the bank uses the right ACH SEC code.
  • Bank details also asks for the Legal name on account (required), sent as nameOnAccount. It is pre-filled with the organization's legal name, not its DBA, and the user can edit it.
  • The success screen is titled "Verification deposits sent". It names the account type (for example "business checking") and the last four digits, then lists two next steps: check the bank account, then return to verify the amounts. One Done button closes it. It does not name the external bank, because the widget does not know which bank the account is at.
  • In the feature labels, {last4} is shown bold and {type} takes one of the *Type labels.
  • Without the micro-deposit scope no deposits are sent, so the screen is titled "Account added", uses the summaryAccountAddedDescription feature label and shows no next steps.
• Verify is available only after micro-deposits were sent. Each amount must be between $0.01 and $0.99.
• Edit and unlink success show a toast. The widget mounts its own toaster, so you need no toast setup.
• isLinkAccountOpen opens the Add external account wizard from your own control, for example a returned transfer's Link a new account button in TransfersWidget. It never opens without the write scope, and every opening starts on the first step.
• Failed actions show an inline alert above the rows or inside the open dialog.

Props

Widget props

Examples

Inherit auth from a root provider

import {
  LinkedAccountsWidget,
  RootWidgetProvider,
} from '@tesouro/embedded-components-react';

export function BankingPage() {
  return (
    <RootWidgetProvider
      baseUrl="https://api.example.com"
      widgetToken="wt_live_abc123"
    >
      <LinkedAccountsWidget
        organizationId="org_xyz"
        labels={{ title: 'External accounts', connectButton: 'Add account' }}
        featureLabels={{ accountLabel: 'Account #:' }}
      />
    </RootWidgetProvider>
  );
}

See the exported LinkedAccountsWidgetLabels and LinkedAccountsWidgetFeatureLabels types for every key.

TypeScript

import type {
  LinkedAccountsWidgetFeatureLabels,
  LinkedAccountsWidgetLabels,
  LinkedAccountsWidgetProps,
} from '@tesouro/embedded-components-react';