Integrate Plaid for Fintech Operations

Provides expert patterns for Plaid API integration - Link token flows, incremental transactions sync, identity verification, ACH via the Auth product, real-time balance checks, secure webhook handling, and fintech compliance practices.

Use this skill when implementing bank account linking, syncing transaction history, initiating ACH transfers, checking real-time balances before a payment decision, or handling Plaid webhooks and item error states. Not a fit for payment processing itself (delegate to stripe-integration; Plaid handles account linking, Stripe handles the payment), budgeting/transaction analytics (analytics-specialist), or compliance auditing (security-specialist).

Link token creation and exchange shows a full server endpoint creating a short-lived, single-use link_token scoped to a user and product list (Transactions, 180-day history for recurring detection), a token exchange endpoint converting the public_token to a non-expiring access_token (encrypted at rest before storage), and a React frontend component using usePlaidLink.

Transactions sync uses /transactions/sync (preferred over /transactions/get) with cursor-based incremental pagination, processing added/modified/removed transactions in batches and persisting the cursor for the next sync, with explicit handling of the TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION error by restarting from a null cursor. A webhook handler dispatches on SYNC_UPDATES_AVAILABLE, INITIAL_UPDATE, and HISTORICAL_UPDATE to trigger fresh syncs instead of polling.

Item error handling covers creating an update-mode Link token (passing access_token instead of products) for ITEM_LOGIN_REQUIRED recovery, and webhook handling for ERROR, PENDING_DISCONNECT (proactive reauthorization prompt), and USER_PERMISSION_REVOKED (data cleanup) item states. Auth for ACH transfers shows retrieving account/routing numbers via authGet, verifying account ownership via identityGet/identityMatch with a minimum confidence score threshold before allowing a transfer, and checking real-time balance sufficiency before initiating the transfer.

Balance checking distinguishes cached balances via accountsGet (free, suitable for display) from real-time balances via accountsBalanceGet (paid, required for payment validation decisions). Webhook verification validates the Plaid-Verification JWT header against Plaid's JWKS endpoint, checks the request body SHA-256 hash matches the signed claim, enforces a 5-minute timestamp freshness window, and processes webhooks idempotently using a hash-based deduplication log to handle duplicate or out-of-order delivery.

Eight sharp edges are flagged by severity: access tokens never expire but are highly sensitive (critical), accounts/get returns cached not real-time balances (high), webhooks may arrive out of order or duplicated (high), items enter error states requiring user action (high), sandbox doesn't reflect production complexity (medium), sync mutation during pagination requires a restart (medium), Link tokens are short-lived/single-use (medium), and recurring transaction detection needs 180+ days of history (medium). Ten validation checks flag concrete anti-patterns: unencrypted access token storage, Plaid secret exposed client-side, hardcoded credentials, missing webhook signature verification, using cached balance for payment decisions, missing ITEM_LOGIN_REQUIRED handling, polling instead of webhooks, caching/reusing Link tokens, using the deprecated public key integration, and syncing without cursor persistence.

Uses the Plaid Node.js SDK (plaid package), react-plaid-link for the frontend Link flow, JWKS/JWT verification for webhooks, and delegates to stripe-integration for actual payment processing.

Fintech developers integrating Plaid for bank account linking, transaction data, or ACH transfers who need production-grade patterns for token management, sync, and webhook security rather than basic API call examples.

const response = await plaidClient.transactionsSync({
  access_token: accessToken,
  cursor: cursor || undefined,
});