Plaid Bank Feed Integration Contract

​

Overview

​

Integration Pattern

​

Authentication Requirements

​

Environment Matrix

​

Credentials

​

API Endpoints

​

Plaid API (Outbound)

​

Edge Functions (Internal)

​

Transfer UI (One-Time Payment / Disbursement)

1. Create intent: Frontend calls plaid-transfer-intent-create with organization_id, mode (PAYMENT | DISBURSEMENT), amount, description, ach_class, user (e.g. legal_name). Backend calls Plaid POST /transfer/intent/create and returns transfer_intent_id.
2. Link token: Frontend calls plaid-create-link-token with organization_id, transfer_intent_id, and optional link_customization_name. Backend returns a link token with products: ["transfer"] and transfer.intent_id.
3. Open Link: Frontend opens Plaid Link with that token; user authorizes the transfer in Plaid’s UI.
4. Post-success: On Link onSuccess, metadata.transfer_status is available; frontend may call plaid-transfer-intent-get with transfer_intent_id to get final status, transfer_id, and failure_reason.

• Origination account: Required for transfer intent. Resolved in order: (1) fa_module_settings.plaid_origination_account_id for the organization, (2) env PLAID_ORIGINATION_ACCOUNT_ID. At least one must be set.
• Link customization: In Plaid Dashboard, create a Link customization with Account Select: Enabled for one account. Optionally set fa_module_settings.plaid_link_customization_name per org, or pass link_customization_name when requesting the link token / from frontend (useTransferUI / TransferUIButton).

​

Programmatic Plaid Transfer (HR Payroll)

1. Authorize: Call POST /transfer/authorization/create with access_token, account_id, type, network, amount, ach_class, user, and an idempotency_key. Plaid returns authorization_id and decision (approved/declined).
2. Create: If approved, call POST /transfer/create with authorization_id, access_token, account_id, and description only.

​

Data Flow

┌─────────────────┐                 ┌─────────────────┐
│   Encore OS    │                 │   Plaid API     │
│   Frontend      │                 │                 │
└────────┬────────┘                 └────────┬────────┘
         │                                    │
         │ 1. Request Link Token              │
         │    (to Edge Function)              │
         ▼                                    │
┌─────────────────┐                           │
│ plaid-create-   │ 2. POST /link/token/create│
│ link-token      ├──────────────────────────►│
│                 │                           │
│                 │ 3. link_token             │
│                 │◄──────────────────────────┤
└────────┬────────┘                           │
         │                                    │
         │ 4. link_token to frontend          │
         ▼                                    │
┌─────────────────┐                           │
│   Plaid Link    │ 5. User authenticates     │
│   (Frontend)    ├──────────────────────────►│
│                 │                           │
│                 │ 6. public_token           │
│                 │◄──────────────────────────┤
└────────┬────────┘                           │
         │                                    │
         │ 7. POST /plaid-exchange-token      │
         ▼                                    │
┌─────────────────┐ 8. POST /item/public_     │
│ plaid-exchange- │    token/exchange         │
│ token           ├──────────────────────────►│
│                 │                           │
│                 │ 9. access_token + accounts│
│                 │◄──────────────────────────┤
│                 │                           │
│                 │ 10. Store in fa_bank_accounts
└────────┬────────┘                           │
         │                                    │
         │ 11. Webhook: INITIAL_UPDATE        │
         │◄───────────────────────────────────┤
         │                                    │
         ▼                                    │
┌─────────────────┐ 12. POST /transactions/sync
│   plaid-sync    ├──────────────────────────►│
│                 │                           │
│                 │ 13. transactions + cursor │
│                 │◄──────────────────────────┤
│                 │                           │
│                 │ 14. Store in fa_bank_statement_lines
└─────────────────┘

​

Webhook Events

​

Supported Events

​

Signature Verification

1. Fetch Plaid’s verification key
2. Verify JWT signature
3. Validate claims (iat, request_body_sha256)

// Webhook verification (simplified)
const verifyPlaidWebhook = async (body: string, verification: string) => {
  // 1. Decode JWT header to get key_id
  // 2. Fetch verification key from Plaid
  // 3. Verify JWT signature
  // 4. Verify request_body_sha256 matches
  return isValid;
};

​

Database Schema

​

fa_bank_accounts (Additional Columns)

​

fa_bank_statement_lines (Additional Column)

​

fa_module_settings (Additional Columns)

​

Security Considerations

​

Token Storage

• Access tokens stored in plaid_access_token column (encrypted at rest by Supabase)
• Tokens never exposed to frontend
• Edge functions access tokens via service role

​

Multi-Tenancy

• All Edge Function queries include organization_id filter
• RLS policies prevent cross-tenant access
• Audit logging for all Plaid operations

​

Webhook Security

• JWT signature verification
• Request body hash validation
• Rate limiting via Supabase

​

Institution-specific behavior (Duplicate Items)

• Option 1: Use Plaid’s update mode to repair the existing Item (re-launch Link with the existing access_token). That will invalidate the new Item; then remove the new Item via /item/remove if it was already created.
• Option 2: Remove the old Item using Plaid’s /item/remove endpoint and use the new Item.

​

Error Handling

​

Plaid API Errors

​

Retry Strategy

// Exponential backoff for rate limiting
const delays = [1000, 2000, 4000, 8000, 16000]; // ms
for (const delay of delays) {
  const result = await callPlaidApi();
  if (result.error_code !== 'RATE_LIMIT_EXCEEDED') break;
  await sleep(delay);
}

​

Logging

​

Allowlisted Fields (Safe to Log)

• bank_account_id
• plaid_item_id (not access token)
• plaid_account_id
• transactions_synced
• sync_duration_ms

​

Prohibited (Never Log)

• plaid_access_token
• plaid_secret
• Full account numbers

​

Testing Strategy

​

Sandbox Testing

• Use Plaid sandbox environment
• Test institutions: ins_109508 (Chase), ins_109511 (Bank of America)
• Test credentials: user_good / any password

​

Integration Tests

• Link token creation
• Token exchange
• Transaction sync with deduplication
• Webhook signature verification

​

E2E Tests

• Full connect → sync → disconnect flow

​

Rollback Strategy

1. Disable feature flag: plaid_integration_enabled = false
2. UI hides all Plaid components
3. Manual CSV/OFX import continues to work
4. No data migration required

​

Account selection and GL mapping

1. Link returns public_token and metadata.accounts (all accounts the user linked at the institution).
2. The app shows PlaidAccountMappingDialog: user selects which accounts to connect and assigns a GL account to each.
3. Only selected accounts are sent to plaid-exchange-token with gl_account_id per account.
4. Backend creates fa_bank_accounts rows and triggers initial sync for each.

​

Recommendations (from Plaid docs and product)

​

Product initialization

​

Balance and cash position

​

References

• Spec: specs/fa/specs/FA-PLAID-INTEGRATION-SPEC.md
• Review: specs/fa/reviews/FA-PLAID-INTEGRATION-REVIEW.md
• Teller Integration (retired): docs/architecture/integrations/FA_TELLER_INTEGRATION.md
• Plaid Sandbox verification: docs/testing/PLAID_SANDBOX_VERIFICATION.md (env, payroll $11.11, Transfer UI flow, optional script)
• Plaid Docs: https://plaid.com/docs/
• Plaid API Reference: https://plaid.com/docs/api/
• react-plaid-link: https://github.com/plaid/react-plaid-link