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.
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 |
sandbox to test the flow, then move to development for real bank testing.
Step 1: Get Plaid Credentials
- Sign up at Plaid Dashboard
- Go to Team Settings → Keys in Dashboard
- Note your:
- Client ID (e.g.,
5f8c1b2a3d4e5f6a7b8c9d0e)
- Secret (per environment - sandbox, development, production)
- Go to Developers → Webhooks
- Add a webhook endpoint:
https://your-project.supabase.co/functions/v1/plaid-webhook
Option A: Using Lovable Cloud (Recommended)
- Go to your Lovable project → Settings → Cloud → Secrets
- 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
# 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
You should see:
NAME | DIGEST
---------------------|--------
PLAID_CLIENT_ID | abc123...
PLAID_SECRET | def456...
PLAID_ENVIRONMENT | ghi789...
Step 3: Enable Feature Flag
- Navigate to Finance & Accounting → Settings
- Go to the Integrations tab
- Toggle Enable Plaid Integration to ON
- Click Save Changes
The Plaid option will now appear in the bank connection flow.
Step 4: Test the Connection
- Navigate to Finance → Bank Accounts
- Click Connect Bank Account
- If both Teller and Plaid are enabled, select Plaid from the provider dialog
- Plaid Link modal opens
- In Sandbox mode:
- Select any institution (e.g., “First Platypus Bank”)
- Use test credentials (see below)
- Select accounts to connect
- 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 |
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
- After connecting, click the Sync button on the account card
- Transactions will be imported into Bank Statement Lines
- 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:
- Verify the secret exists:
supabase secrets list
- Check the value matches your Plaid Dashboard
- Secrets are case-sensitive
🚨 “Plaid integration is not enabled”
Cause: Feature flag not enabled in FA Module Settings.
Fix:
- Navigate to Finance → Settings → Integrations
- Enable “Plaid Integration”
- Save changes
🚨 Plaid Link Modal Doesn’t Open
Cause: Link token creation failed.
Check:
- Browser console for errors
- Edge function logs in Supabase Dashboard
- 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:
- Webhook URL is correct in Plaid Dashboard
- Edge function logs for signature errors
- 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)
# 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)
# Supabase secrets
PLAID_ENVIRONMENT=development
- Connects to real bank OAuth flows
- Limited to 100 Items (bank connections)
- Free tier
- Real transaction data
Production Mode
# 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
