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.