Skip to main content
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

1

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>"
The link_token expires quickly — pass it to the Plaid Link UI immediately.
2

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.
3

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..." }'
FieldDescription
item_idPlaid’s stable identifier for the linked bank item.
institution_idPlaid’s identifier for the financial institution.
persistedtrue when the connection was saved to your account.
persist_hintNon-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.
4

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>"
Use connected: false to prompt the user to complete the Plaid Link flow.

​
API summary

MethodPathAuthDescription
POST/api/plaid/link-tokenSession requiredReturns a link_token to initialize Plaid Link.
POST/api/plaid/exchangeSession requiredExchanges a public_token for a stored item reference. Body: { "public_token": "..." }.
GET/api/plaid/statusSession requiredReturns 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.