Plaid Setup

Plaid enables automatic bank transaction import. Users link their real bank accounts through a Plaid-hosted authentication flow, and transactions sync automatically.

Without Plaid credentials, Geekonomics works fully for manual entry and Square/Stripe sync — bank linking is simply not available.

1. Create a Plaid account

Register at dashboard.plaid.com and create an application. Plaid offers a free sandbox environment for testing.

2. Get your credentials

From the Plaid dashboard:

• Client ID → PLAID_CLIENT_ID
• Secret (sandbox or production) → PLAID_SECRET

3. Add to .env

PLAID_CLIENT_ID=your-client-id
PLAID_SECRET=your-plaid-secret
PLAID_ENV=sandbox

Use PLAID_ENV=production for live bank connections. Switch to your production secret as well.

Restart the container:

docker compose restart

4. Link a bank account

Once configured, users link bank accounts per-account in Geekonomics:

1. Go to Accounts
2. Open an account (e.g. your checking account)
3. Click Link Bank Account
4. Complete Plaid Link — search for your bank and authenticate
5. Click Sync to import transactions

How sync works

Plaid sync:

• Fetches new transactions since the last sync date
• Deduplicates by plaid_transaction_id — re-syncing is always safe
• Maps Plaid's sign convention: positive amounts = expenses, negative = income (Plaid uses the bank's perspective)
• Assigns transactions to the linked account automatically

Plaid environments

Environment	Purpose	Real bank data
sandbox	Testing with fake credentials	No
development	Testing with real accounts (limited)	Yes
production	Full live access	Yes

Start with sandbox to test the flow. Sandbox provides test credentials (username: user_good, password: pass_good for most institutions).

Disconnecting

To unlink a bank account without deleting the account:

1. Open the account in Geekonomics
2. Click Disconnect Bank

This removes the Plaid access token from the database. Existing transactions are preserved. The user can re-link at any time.

Plaid pricing

Plaid charges per-institution per-month after a free tier. Check plaid.com/pricing for current rates. For most small self-hosters with 1–2 linked accounts, usage stays within the free tier.