> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Plaid Bank Integration Setup Guide

> Last Updated: 2026-01-29 Related

**Last Updated:** 2026-01-29\
**Related Spec:** FA-20

## Quick Start

### Choose Your Environment

| Environment     | Data       | Cost | Limit     | Use Case                |
| --------------- | ---------- | ---- | --------- | ----------------------- |
| **Sandbox**     | Simulated  | Free | Unlimited | UI testing, development |
| **Development** | Real banks | Free | 100 Items | Integration testing     |
| **Production**  | Real banks | Paid | Unlimited | Live users              |

**Recommendation:** Start with `sandbox` to test the flow, then move to `development` for real bank testing.

***

## Step 1: Get Plaid Credentials

1. Sign up at [Plaid Dashboard](https://dashboard.plaid.com/signup)
2. Go to **Team Settings** → **Keys** in Dashboard
3. Note your:
   * **Client ID** (e.g., `5f8c1b2a3d4e5f6a7b8c9d0e`)
   * **Secret** (per environment - sandbox, development, production)
4. Go to **Developers** → **Webhooks**
5. Add a webhook endpoint: `https://your-project.supabase.co/functions/v1/plaid-webhook`

***

## Step 2: Configure Supabase Secrets

### Option A: Using Lovable Cloud (Recommended)

1. Go to your Lovable project → **Settings** → **Cloud** → **Secrets**
2. Add the following secrets:

| Secret Name         | Value                                        |
| ------------------- | -------------------------------------------- |
| `PLAID_CLIENT_ID`   | Your client ID from Plaid Dashboard          |
| `PLAID_SECRET`      | Your secret (use sandbox secret for testing) |
| `PLAID_ENVIRONMENT` | `sandbox` (or `development` / `production`)  |

### Option B: Using CLI

```bash theme={null}
# Set secrets individually
supabase secrets set PLAID_CLIENT_ID=your_client_id
supabase secrets set PLAID_SECRET=your_secret
supabase secrets set PLAID_ENVIRONMENT=sandbox
```

### Verify Secrets

```bash theme={null}
supabase secrets list
```

You should see:

```text theme={null}
NAME                 | DIGEST
---------------------|--------
PLAID_CLIENT_ID      | abc123...
PLAID_SECRET         | def456...
PLAID_ENVIRONMENT    | ghi789...
```

***

## Step 3: Enable Feature Flag

1. Navigate to **Finance & Accounting** → **Settings**
2. Go to the **Integrations** tab
3. Toggle **Enable Plaid Integration** to ON
4. Click **Save Changes**

The Plaid option will now appear in the bank connection flow.

***

## Step 4: Test the Connection

1. Navigate to **Finance** → **Bank Accounts**
2. Click **Connect Bank Account**
3. If both Teller and Plaid are enabled, select **Plaid** from the provider dialog
4. Plaid Link modal opens
5. In Sandbox mode:
   * Select any institution (e.g., "First Platypus Bank")
   * Use test credentials (see below)
   * Select accounts to connect
6. Verify the account appears with a "Plaid" provider badge

### Sandbox Test Credentials

Use these credentials when connecting banks in sandbox mode:

| Username                    | Password    | Behavior                         |
| --------------------------- | ----------- | -------------------------------- |
| `user_good`                 | `pass_good` | Standard successful login        |
| `user_transactions_dynamic` | `pass_good` | Generates new transactions daily |
| `user_bad`                  | `pass_bad`  | Invalid credentials error        |

**Test Institution ID:** `ins_109508` (First Platypus Bank)

For MFA testing:

* **Username:** `user_good`
* **Password:** `mfa_device` (triggers device-based MFA)
* **Code:** `1234` (any 4-digit code works in sandbox)

***

## Step 5: Sync Transactions

1. After connecting, click the **Sync** button on the account card
2. Transactions will be imported into Bank Statement Lines
3. A toast notification shows the sync results:
   * Transactions added
   * Transactions modified
   * Transactions removed

For Plaid sandbox accounts, use `user_transactions_dynamic` credentials to generate new transactions daily.

***

## Troubleshooting

### 🚨 "Invalid client\_id" Error

**Cause:** PLAID\_CLIENT\_ID secret not configured or incorrect.

**Fix:**

1. Verify the secret exists: `supabase secrets list`
2. Check the value matches your Plaid Dashboard
3. Secrets are case-sensitive

### 🚨 "Plaid integration is not enabled"

**Cause:** Feature flag not enabled in FA Module Settings.

**Fix:**

1. Navigate to Finance → Settings → Integrations
2. Enable "Plaid Integration"
3. Save changes

### 🚨 Plaid Link Modal Doesn't Open

**Cause:** Link token creation failed.

**Check:**

1. Browser console for errors
2. Edge function logs in Supabase Dashboard
3. Verify all three secrets are set (CLIENT\_ID, SECRET, ENVIRONMENT)

### 🚨 "Institution not supported"

**Cause:** The selected institution isn't available in sandbox mode.

**Fix:**

* Use sandbox-supported institutions (any from the Plaid Link flow)
* Switch to `development` environment for real institutions

### 🚨 Webhook Events Not Processing

**Cause:** Webhook endpoint not configured or signature verification failing.

**Check:**

1. Webhook URL is correct in Plaid Dashboard
2. Edge function logs for signature errors
3. Function is deployed: `supabase functions list`

### 🚨 Rate Limiting (429 Error)

**Cause:** Too many API requests in a short period.

**Fix:**

* Wait 60 seconds and retry
* Plaid has rate limits per client ID
* The edge functions have built-in exponential backoff

***

## Environment-Specific Setup

### Sandbox Mode (Recommended for Development)

```bash theme={null}
# Supabase secrets
PLAID_ENVIRONMENT=sandbox
```

* Uses simulated bank data
* No real bank connections
* Test credentials work (see above)
* Transactions are generated synthetically

### Development Mode (Real Banks, Limited)

```bash theme={null}
# Supabase secrets
PLAID_ENVIRONMENT=development
```

* Connects to real bank OAuth flows
* Limited to 100 Items (bank connections)
* Free tier
* Real transaction data

### Production Mode

```bash theme={null}
# Supabase secrets
PLAID_ENVIRONMENT=production
```

* Full production access
* Requires Production access approval from Plaid
* Paid based on usage
* Contact Plaid for pricing

***

## Webhook Events Handled

The `plaid-webhook` edge function processes these events:

| Event Type               | Description               | Action                           |
| ------------------------ | ------------------------- | -------------------------------- |
| `SYNC_UPDATES_AVAILABLE` | New transactions ready    | Triggers sync                    |
| `TRANSACTIONS_REMOVED`   | Transactions were removed | Updates affected records         |
| `ERROR`                  | Item has an error         | Sets status to `error`           |
| `PENDING_EXPIRATION`     | Credentials expiring      | Sets status to `reauth_required` |
| `LOGIN_REPAIRED`         | User fixed login issue    | Sets status to `connected`       |

***

## Required Secrets Summary

| Secret              | Required | Description                               |
| ------------------- | -------- | ----------------------------------------- |
| `PLAID_CLIENT_ID`   | ✅        | Your Plaid client ID                      |
| `PLAID_SECRET`      | ✅        | Environment-specific secret               |
| `PLAID_ENVIRONMENT` | ✅        | `sandbox`, `development`, or `production` |

***

## Provider Comparison

| Feature                   | Plaid                   | Teller                     |
| ------------------------- | ----------------------- | -------------------------- |
| **Institution Coverage**  | 11,000+ globally        | US only                    |
| **Auth Method**           | OAuth (browser-based)   | OAuth + mTLS               |
| **Transaction Sync**      | Sync API (cursor-based) | Polling                    |
| **Webhooks**              | JWT-verified            | HMAC-SHA256                |
| **International Support** | ✅ (CA, UK, EU)          | ❌                          |
| **Setup Complexity**      | Low                     | Medium (mTLS for dev/prod) |

***

## See Also

* [Plaid Documentation](https://plaid.com/docs/)
* [Plaid Link for Web](https://plaid.com/docs/link/web/)
* [Plaid Sandbox Guide](https://plaid.com/docs/sandbox/)
* [FA-20 Specification](../../specs/fa/specs/FA-20-plaid-bank-integration.md)
* Teller Setup Guide