Link bank accounts with Plaid in Safeclose

Safeclose uses Plaid to let signers verify and link their bank accounts as part of the signing flow. When a signer connects their bank, Safeclose retrieves a short-lived token on their behalf, passes it through the secure Plaid Link UI, and exchanges it for a persistent item reference — no raw bank credentials ever touch your application. You can try the Plaid Link flow interactively in the Safeclose signing lab at /signing/plaid-lab.

Which Plaid environment is active (sandbox or production) is configured by your workspace administrator. In sandbox mode, use Plaid’s test credentials to complete the flow without a real bank account.

How the Plaid Link flow works

Request a link token

Call POST /api/plaid/link-token from your signed-in session. Safeclose returns a short-lived link_token scoped to the current user.

curl -X POST https://your-app.com/api/plaid/link-token \
  -H "Cookie: <your-session-cookie>"

{
  "link_token": "link-sandbox-abc123..."
}

The link_token expires quickly — pass it to the Plaid Link UI immediately.

Initialize Plaid Link

Use the link_token to open the Plaid Link UI. In a React app, pass the token to usePlaidLink from the react-plaid-link package:

import { usePlaidLink } from 'react-plaid-link';

const { open, ready } = usePlaidLink({
  token: linkToken,   // from POST /api/plaid/link-token
  onSuccess: (publicToken, metadata) => {
    // exchange the public_token on your server
  },
});

The user selects their institution and authenticates inside the Plaid Link modal. Your app code never handles credentials directly.

Exchange the public token

After the user completes Plaid Link, Plaid calls your onSuccess callback with a one-time public_token. Send it to POST /api/plaid/exchange to exchange it for a persistent item reference.

curl -X POST https://your-app.com/api/plaid/exchange \
  -H "Cookie: <your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "public_token": "public-sandbox-abc123..." }'

{
  "item_id": "eVBnVMp7zxNmBoTgB3K",
  "institution_id": "ins_3",
  "persisted": true,
  "persist_hint": null
}

Field	Description
`item_id`	Plaid’s stable identifier for the linked bank item.
`institution_id`	Plaid’s identifier for the financial institution.
`persisted`	`true` when the connection was saved to your account.
`persist_hint`	Non-null message if the connection could not be saved (ask your admin to check encryption key configuration).

Call POST /api/plaid/exchange from your server-side code or immediately after onSuccess. The public_token can only be exchanged once and expires after 30 minutes.

Check link status

At any time, call GET /api/plaid/status to check whether the signed-in user has a linked Plaid item.

curl https://your-app.com/api/plaid/status \
  -H "Cookie: <your-session-cookie>"

{
  "connected": true,
  "itemId": "eVBnVMp7zxNmBoTgB3K",
  "institutionId": "ins_3"
}

{
  "connected": false,
  "itemId": null,
  "institutionId": null
}

Use connected: false to prompt the user to complete the Plaid Link flow.

API summary

Method	Path	Auth	Description
`POST`	`/api/plaid/link-token`	Session required	Returns a `link_token` to initialize Plaid Link.
`POST`	`/api/plaid/exchange`	Session required	Exchanges a `public_token` for a stored item reference. Body: `{ "public_token": "..." }`.
`GET`	`/api/plaid/status`	Session required	Returns whether the current user has a linked Plaid item.

Plaid webhook events

Plaid sends item update notifications to Safeclose automatically — for example, when new transactions are available or when a linked item needs re-authentication. These events arrive at POST /api/webhooks/plaid and are processed asynchronously.

Webhook configuration

Learn how Safeclose verifies Plaid webhook events and what your administrator needs to configure.

Get Started

Core Concepts

Guides

Integrations

Reference

Link bank accounts with Plaid in Safeclose

How the Plaid Link flow works

API summary

Plaid webhook events

Webhook configuration

​How the Plaid Link flow works

​API summary

​Plaid webhook events

Webhook configuration

How the Plaid Link flow works

API summary

Plaid webhook events