---
name: "Plaid API (Banking & Fintech)"
description: "Integrate Plaid: Link component, Auth (account/routing), Transactions sync, Balance, Identity, ACH Transfers, Signal (risk), webhooks, environments (Sandbox/Development/Production), compliance, and pricing."
version: "1.0.0"
author: "skynet"
category: "dev"
agents: ["claude-code", "codex", "gemini"]
tags: ["plaid", "banking", "fintech", "api", "ach", "transactions"]
---

# Plaid API (Banking & Fintech)

---
name: "Plaid API (Banking & Fintech)"
description: "Integrate Plaid: Link component, Auth (account/routing), Transactions sync, Balance, Identity, ACH Transfers, Signal (risk), webhooks, environments (Sandbox/Development/Production), compliance, and pr"
version: "1.0.0"
author: "skynet"
category: "dev"
tags: ["plaid", "banking", "fintech", "api", "ach", "transactions"]
---

I will search the codebase for any existing Plaid integrations to ensure the technical reference aligns with any established patterns in your environment.
# Plaid API Integration Reference for SaaS

This reference outlines the architectural patterns, API workflows, and best practices for integrating Plaid into modern SaaS applications.

---

## 1. PRODUCTS
Plaid offers a suite of products tailored for specific financial use cases:

*   **Auth:** Instant account and routing number verification for ACH.
*   **Transactions:** Up to 24 months of transaction history with clean categorization.
*   **Identity:** Verify account holder information (Name, Address, Email, Phone) against bank records.
*   **Balance:** Real-time account balance checks to prevent NSFs.
*   **Investments:** Details on brokerage accounts, holdings, and investment transactions.
*   **Liabilities:** Real-time data for student loans, credit cards, and mortgages.
*   **Transfer:** End-to-end ACH payment platform with built-in risk analysis.
*   **Income:** Verify payroll and income sources (includes `Income Verification`).
*   **Assets:** Consolidated view of a user’s financial history (often used for lending).
*   **Signal:** Machine learning-based risk assessment for ACH transfers.

---

## 2. LINK (Client-Side Component)
Plaid Link is the high-conversion, front-end module that handles credential entry and Multi-Factor Authentication (MFA).

*   **Link Customization:** Managed via the Plaid Dashboard (logos, colors, language).
*   **Update Mode:** Used when an `access_token` becomes invalid (e.g., user changed their password). Initialize Link with the existing `access_token` to prompt re-auth.

### Example: Link Initialization (React)
```javascript
import { usePlaidLink } from 'react-plaid-link';

const Link = ({ linkToken }) => {
  const onSuccess = (public_token, metadata) => {
    // Send public_token to your server for exchange
    fetch('/api/exchange_public_token', {
      method: 'POST',
      body: JSON.stringify({ public_token }),
    });
  };

  const { open, ready } = usePlaidLink({
    token: linkToken,
    onSuccess,
  });

  return (
    <button onClick={() => open()} disabled={!ready}>
      Connect Bank Account
    </button>
  );
};
```

---

## 3. AUTH FLOW (The "Plaid Handshake")

1.  **Create Link Token (Server):** Call `/link/token/create` with your `client_id`, `secret`, and requested `products`.
2.  **Initialize Link (Client):** Use the `link_token` to open the Link UI.
3.  **Receive Public Token (Client):** Upon success, Link returns a short-lived `public_token`.
4.  **Exchange Token (Server):** Send the `public_token` to `/item/public_token/exchange` to receive a permanent `access_token` and `item_id`.
5.  **Persist Credentials:** Securely store the `access_token` in your database.

---

## 4. TRANSACTIONS SYNC
The `/transactions/sync` endpoint is the modern, preferred way to handle transaction data. It uses cursor-based pagination to track state.

*   **Cursor:** A string representing the last point your application synced. Store this alongside the `access_token`.
*   **Response Objects:**
    *   `added`: New transactions since the last sync.
    *   `modified`: Changes to existing transactions (e.g., from `pending` to `posted`).
    *   `removed`: Transactions that were deleted or reversed.

---

## 5. WEBHOOKS
Webhooks are critical for maintaining data freshness without polling.

*   **SYNC_UPDATES_AVAILABLE:** Triggered when new data is ready for `/transactions/sync`.
*   **ITEM_ERROR:** Triggered when an Item requires user intervention (e.g., `ITEM_LOGIN_REQUIRED`).
*   **Verification:** Always verify webhook signatures using Plaid’s public keys (via `/webhook_verification_key/get`) to prevent spoofing.

---

## 6. ENVIRONMENTS

| Environment | Purpose | Limit |
| :--- | :--- | :--- |
| **Sandbox** | Functional testing with mock data. | Unlimited |
| **Development** | Testing with real live bank accounts. | 100 Items |
| **Production** | Live production traffic. | Tiered |

---

## 7. ACH TRANSFERS & SIGNAL
Plaid Transfer simplifies the complexity of the ACH network.

1.  **Authorize:** Use Plaid Link with the `transfer` product.
2.  **Evaluate Risk (Signal):** Call `/signal/evaluate` before initiating a transfer to check for fraud or NSF risk.
3.  **Create Transfer:** Call `/transfer/create` to initiate the debit/credit.
4.  **Tracking:** Use the `/transfer/event/sync` endpoint to track the status (pending, cleared, failed).

---

## 8. COMPLIANCE & SECURITY
*   **Data Minimization:** Only request the products and scopes your application strictly requires.
*   **User Consent:** Link explicitly handles user consent in compliance with Open Banking standards (PSD2/FDX).
*   **Security:** Plaid is SOC 2 Type II compliant. Access tokens should be treated as highly sensitive (AES-256 encryption at rest).

---

## 9. PRICING
*   **Pay-as-you-go:** Only available in some regions; most SaaS apps use a subscription or volume-based model.
*   **Platform Fee:** Monthly fee for access to the Production environment.
*   **Per-Item Fee:** Costs vary by product (e.g., `Auth` is often a one-time fee per account, while `Transactions` is a monthly recurring fee).

---

## 10. TECHNICAL "GOTCHAS"

*   **Item Errors:** `ITEM_LOGIN_REQUIRED` is inevitable. Design your UI to handle "Connection Required" states gracefully.
*   **Transaction Duplicates:** Always use the `transaction_id` as your unique key. Never rely on the description or amount alone.
*   **Pending Transactions:** Transactions often appear as `pending: true` first. Their `transaction_id` may change when they move to `posted`, but Plaid provides a `pending_transaction_id` to link them.
*   **Institution Gaps:** Not every bank supports every product (e.g., some small credit unions don't support `Identity`). Check the `institution` metadata returned by Link.