fastify-xplaid

Plaid integration for Fastify v5. Covers the full Plaid data access surface — Link token creation, public token exchange, accounts, transaction sync, balances, identity, ACH auth, investments, liabilities, webhooks, institution search, and sandbox helpers. Every method validates inputs and attaches the original Plaid error object on failure.

Installation

npm install @xenterprises/fastify-xplaid plaid

Quick Start

import Fastify from "fastify";
import xPlaid from "@xenterprises/fastify-xplaid";

const fastify = Fastify({ logger: true });

await fastify.register(xPlaid, {
  clientId: process.env.PLAID_CLIENT_ID,
  secret: process.env.PLAID_SECRET,
  environment: "sandbox",
});

// 1. Create a Link token for the frontend
const { linkToken } = await fastify.xplaid.link.createToken({
  userId: "user_123",
  clientName: "My App",
  products: ["transactions"],
  countryCodes: ["US"],
});

// 2. After the user completes Plaid Link, exchange the public token
const { accessToken } = await fastify.xplaid.link.exchangePublicToken(publicToken);

// 3. Sync transactions incrementally
const { added, nextCursor } = await fastify.xplaid.transactions.sync(accessToken);

await fastify.listen({ port: 3000 });

Options

Methods

fastify.xplaid.link

• createToken — Create a Link token to initialize Plaid Link in the browser.
• exchangePublicToken — Exchange a temporary public token for a permanent access token.
• getToken — Get metadata for an existing Link token.

fastify.xplaid.accounts

• get — Get all accounts for an Item.
• getBalance — Get real-time account balances (fresh call, not cached).

fastify.xplaid.transactions

• sync — Incremental transaction sync with cursor (recommended).
• get — Fetch transactions by date range.
• refresh — Force-refresh transaction data for an Item.
• getRecurring — Get recurring transaction streams (inflow and outflow).

fastify.xplaid.identity

• get — Get identity data (names, emails, phone numbers, addresses).

fastify.xplaid.auth

• get — Get ACH routing and account numbers.

fastify.xplaid.investments

• getHoldings — Get investment holdings and securities.
• getTransactions — Get investment transactions by date range.

fastify.xplaid.liabilities

• get — Get credit card, mortgage, and student loan liabilities.

fastify.xplaid.items

• get — Get Item status and metadata.
• remove — Permanently remove an Item and revoke the access token.
• getInstitution — Get institution details by ID.
• searchInstitutions — Search institutions by name.

fastify.xplaid.webhooks

• update — Update the webhook URL for an Item.
• getVerificationKey — Get the webhook verification key for signature validation.

fastify.xplaid.sandbox

• createPublicToken — Create a sandbox public token without the Link UI.
• resetItem — Reset an Item's login state (forces re-authentication).

Other properties

Error Reference

On Plaid API failure every method throws with:

{
  message: "Human-readable error",
  statusCode: 400,          // HTTP status from Plaid
  plaidError: {
    error_type: "INVALID_REQUEST",
    error_code: "INVALID_ACCESS_TOKEN",
    error_message: "...",
    display_message: "...",
    request_id: "..."
  }
}

Startup Errors

Common Plaid API Error Types

Environment Variables

How It Works

On registration the plugin validates clientId, secret, and environment, creates a PlaidApi client with the appropriate base URL and authentication headers, then decorates fastify.xplaid with namespaced service objects. Every method validates required parameters before making an API call and wraps failures in a try/catch that attaches the original Plaid error object as .plaidError and the HTTP status as .statusCode. The sandbox namespace provides helpers for automated testing without the Link UI. The raw property exposes the full PlaidApi client for endpoints not yet wrapped by the plugin.

AI Context

package: "@xenterprises/fastify-xplaid"
type: fastify-plugin
use-when: Plaid financial data — bank account linking, transactions, balances, identity, ACH auth, investments, liabilities, webhooks
decorator: fastify.xplaid (link, accounts, transactions, identity, auth, investments, liabilities, items, webhooks, sandbox, config, constants, raw)
env: PLAID_CLIENT_ID, PLAID_SECRET, PLAID_ENV (optional)
peer-deps: plaid
error-shape: { message, statusCode, plaidError } on API failures
flow: createToken → [user completes Plaid Link] → exchangePublicToken → store accessToken → sync/get data