Plaid Bank Integration Setup Guide

​

Quick Start

​

Choose Your Environment

​

Step 1: Get Plaid Credentials

1. Sign up at Plaid Dashboard
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:

​

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

supabase secrets list

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

​

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

• 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

​

Troubleshooting

​

🚨 “Invalid client_id” Error

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”

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

​

🚨 Plaid Link Modal Doesn’t Open

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”

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

​

🚨 Webhook Events Not Processing

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)

• 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

​

Required Secrets Summary

​

Provider Comparison

​

See Also

• Plaid Documentation
• Plaid Link for Web
• Plaid Sandbox Guide
• FA-20 Specification
• Teller Setup Guide