Build custom Plaid account linking

You can launch Plaid Link from your own interface without embedding a Layer React component. Your application controls the button, loading states, and account-selection experience, while Layer creates the Plaid Link token, securely stores the resulting access token, and imports account activity. This guide uses Plaid’s React SDK in its examples. You can follow the same API flow with another Plaid Link SDK.

Prerequisites

Before starting, you will need:

Plaid enabled for your Layer account
The ID of the Layer business connecting an account
A business-scoped access token

Install Plaid’s React SDK:

npm install react-plaid-link

Link an account

Generate business scoped access token

Follow Authentication to generate an access token for the Layer business.

Request a Plaid Link token

When the customer chooses to connect an account, request a short-lived Link token from Layer.

curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/plaid/link \
  --header "Authorization: Bearer <business_access_token>" \
  --header "Content-Type: application/json" \
  --data '{}'

const response = await fetch(
  `https://sandbox.layerfi.com/v1/businesses/${businessId}/plaid/link`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${businessAccessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  },
);

if (!response.ok) {
  throw new Error("Unable to start account linking");
}

const { data } = await response.json();
const linkToken = data.link_token;

Layer returns the token that your frontend will pass to Plaid:

{
  "data": {
    "type": "Link_Token",
    "link_token": "link-sandbox-...",
    "hosted_link": null
  }
}

Request a new Link token each time the customer starts a new linking session. Do not persist or reuse it.For an implementation example, see the layer-react Link-token request.

Open Plaid Link

Initialize Plaid Link with the token returned by Layer. Open the modal only after the SDK reports that it is ready:

import { useEffect } from "react";
import { usePlaidLink } from "react-plaid-link";

const { open, ready } = usePlaidLink({
  token: linkToken,
  onSuccess: (publicToken, metadata) => {
    void exchangePublicToken(publicToken, metadata.institution);
  },
  onExit: () => {
    setLinkToken(null);
  },
});

useEffect(() => {
  if (ready) {
    open();
  }
}, [open, ready]);

Plaid owns the credential-entry modal. Your application owns the interface that launches it and the experience shown before and after it.For an implementation example, see how layer-react initializes and opens Plaid Link.

Exchange the public token

Plaid calls onSuccess with a short-lived public token and institution metadata. Send both to Layer:

curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/plaid/link/exchange \
  --header "Authorization: Bearer <business_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "public_token": "public-sandbox-...",
    "institution": {
      "institution_id": "ins_123",
      "name": "Example Bank"
    }
  }'

type PlaidInstitution = {
  institution_id: string;
  name: string;
};

async function exchangePublicToken(
  publicToken: string,
  institution: PlaidInstitution | null,
) {
  const response = await fetch(
    `https://sandbox.layerfi.com/v1/businesses/${businessId}/plaid/link/exchange`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${businessAccessToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        public_token: publicToken,
        institution,
      }),
    },
  );

  if (!response.ok) {
    throw new Error("Unable to connect the account");
  }
}

The institution value may be null. After a successful exchange, Layer securely stores the Plaid access token and begins importing account data.

Do not exchange the public token directly with Plaid. Layer must perform the exchange so it can manage the Plaid Item and synchronize its accounts.

For implementation examples, see the layer-react exchange request and success handler.

Load the connected accounts

After the exchange succeeds, call List bank accounts:

cURL

curl https://sandbox.layerfi.com/v1/businesses/{businessId}/bank-accounts \
  --header "Authorization: Bearer <business_access_token>"

A newly connected account may still be synchronizing. Poll the endpoint while any entry in external_accounts has is_syncing set to true. As a reference, layer-react polls every five seconds and stops after 15 minutes.For implementation examples, see the layer-react bank-account request and polling configuration.

Confirm which accounts belong to the business

Layer pauses data synchronization for accounts that require confirmation. An external account requires relevance confirmation when its notifications array contains:

{
  "type": "CONFIRM_RELEVANT"
}

If the customer uses the account for their business, call Confirm external account:

cURL

curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/external-accounts/{externalAccountId}/confirm \
  --header "Authorization: Bearer <business_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"is_relevant": true}'

If the account is not used for the business, call Exclude external account:

cURL

curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/external-accounts/{externalAccountId}/exclude \
  --header "Authorization: Bearer <business_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"is_irrelevant": true}'

Use the external account’s id, not the containing bank account’s id. Refetch the bank accounts after processing every selection. Confirming a relevant account allows Layer to begin synchronizing it.For implementation examples, see how layer-react identifies accounts requiring confirmation and submits confirmations and exclusions.

Repair a Plaid connection

When an external account has a non-null connection_needs_repair_as_of value, request an update-mode Link token. Pass that external account’s connection_external_id as plaid_item_id:

cURL

curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/plaid/update-mode-link \
  --header "Authorization: Bearer <business_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "plaid_item_id": "<plaid_item_id>"
  }'

Open Plaid Link with the returned link_token using the same process described above. After Plaid calls onSuccess, do not exchange the public token. Instead, ask Layer to refresh the connection status:

cURL

curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/external-accounts/update-connection-status \
  --header "Authorization: Bearer <business_access_token>"

Then refetch the business’s bank accounts. For implementation examples, see the layer-react update-mode token request and update-mode success handling.

Handle failures

Your interface should let the customer retry each network operation independently:

If Link-token creation fails, keep the customer on your connection screen and request a new token when they retry.
If the customer exits Plaid Link, discard the Link token.
If the public-token exchange fails, show an error and let the customer start a new linking session.
If account synchronization takes longer than expected, stop polling and provide a manual refresh action.

Get started

Integration steps

API details

Build custom Plaid account linking

Prerequisites

Link an account

Repair a Plaid connection

Handle failures

​Prerequisites

​Link an account

​Repair a Plaid connection

​Handle failures

Prerequisites

Link an account

Repair a Plaid connection

Handle failures