Skip to main content
Plaid provides access to banking data from over 12,000 financial institutions across the United States, Canada, and Europe. Sure supports both US and EU Plaid environments.

​
What Plaid Connects To

Plaid enables connections to:
  • Depository Accounts: Checking and savings accounts
  • Credit Cards: Credit card accounts and transactions
  • Loans: Mortgages, auto loans, student loans
  • Investments: Some brokerage accounts (via Plaid Investments product)

​
Supported Regions

  • US (plaid_region: us): US financial institutions
  • EU (plaid_region: eu): European banks and institutions
Each region requires separate API credentials. You can configure both regions to support accounts from both geographies.

​
Prerequisites

1

Create a Plaid Account

Sign up for a free Plaid account at https://dashboard.plaid.com/signup
  • Development: Free for testing with 100 Items
  • Production: Requires approval and has per-item costs
2

Get API Credentials

From your Plaid Dashboard:
  1. Navigate to Team Settings → Keys
  2. Copy your client_id (same for all environments)
  3. Copy the appropriate secret for your environment:
    • Sandbox: For testing
    • Development: For real accounts in dev mode
    • Production: For live deployment
3

Configure Webhooks (Optional)

Webhooks enable real-time updates when transactions are available:
  • US Webhook URL: https://yourdomain.com/webhooks/plaid
  • EU Webhook URL: https://yourdomain.com/webhooks/plaid_eu
Configure these in your Plaid Dashboard under API → Webhooks.

​
Configuration

Set the following environment variables:
.env
# Plaid API Credentials
PLAID_CLIENT_ID=your_client_id_here
PLAID_SECRET=your_secret_here

# Plaid Environment (sandbox, development, or production)
PLAID_ENV=development

# For EU support (optional)
PLAID_EU_CLIENT_ID=your_eu_client_id
PLAID_EU_SECRET=your_eu_secret
PLAID_EU_ENV=development

# Webhook URL for development (optional)
DEV_WEBHOOKS_URL=https://your-ngrok-url.ngrok.io
Never commit your Plaid secrets to version control. Use .env.local for local development and secure environment variable management in production.

​
Connecting a Plaid Account

1

Navigate to Accounts

From the Sure dashboard, go to the Accounts page.
2

Add Account via Plaid

  1. Click “Add Account”
  2. Select “Connect with Plaid”
  3. Choose your region (US or EU)
  4. Select account type:
    • Depository (Checking/Savings)
    • Credit Card
    • Investment
    • Loan
3

Authenticate with Your Bank

The Plaid Link interface will open:
  1. Search for your financial institution
  2. Enter your online banking credentials
  3. Complete any multi-factor authentication
  4. Select which accounts to connect
4

Link to Sure Account

After successful authentication:
  • New accounts are automatically created in Sure
  • Or link to an existing manual account
  • Initial sync begins immediately

​
Data Syncing

Plaid syncs the following data:

​
Transactions

  • Historical transactions (up to 24 months, depending on institution)
  • New transactions as they post
  • Pending transactions (if supported by institution)
  • Transaction metadata: merchant name, category, location

​
Balances

  • Current balance
  • Available balance
  • Credit limits (for credit cards)
  • Real-time balance updates via webhooks

​
Account Details

  • Account name and mask (last 4 digits)
  • Account type and subtype
  • Currency
  • Institution information and logo

​
Sync Frequency

  • Webhooks Enabled: Real-time updates when new transactions are available
  • Manual Sync: Click the sync button on any Plaid account
  • Automatic Sync: Daily background sync for all accounts
Plaid Items can be manually synced at any time. If an item is already syncing, additional sync requests are queued.

​
Connection Management

​
Updating Expired Connections

If your bank credentials change or the connection expires:
1

Identify Expired Connection

Look for accounts marked with “Requires Update” status.
2

Reconnect

  1. Click on the expired Plaid connection
  2. Click “Update Connection”
  3. Re-authenticate with your bank
  4. Existing account links are preserved

​
Removing a Connection

# From the UI: Accounts → Plaid Item → Delete
# This will:
# - Remove the item from Plaid
# - Schedule accounts for deletion
# - Clean up associated transactions
Source: app/controllers/plaid_items_controller.rb:35

​
Troubleshooting

​
”Item Login Required” Error

Cause: Your bank credentials have changed or the connection has expired. Solution: Click “Update Connection” and re-authenticate.

​
No Transactions Syncing

Checklist:
  1. Verify the Plaid Item status is “good” (not “requires_update”)
  2. Check that webhook URL is configured correctly
  3. Ensure the Plaid product includes transactions
  4. Manually trigger a sync to force a refresh

​
Duplicate Transactions

Cause: Multiple Plaid Items connected to the same account, or mixing Plaid with manual entry. Solution:
  • Only connect each bank account once
  • Use account reconciliation to mark duplicates

​
Institution Not Found

Cause: Not all institutions support all Plaid products. Solution:
  • Try SimpleFIN as an alternative for US banks
  • Use CSV Import for unsupported institutions

​
API Reference

Sure uses the Plaid Ruby SDK (gem plaid): 
# Source: app/models/plaid_item.rb:40
def get_update_link_token(webhooks_url:, redirect_url:)
  family.get_link_token(
    webhooks_url: webhooks_url,
    redirect_url: redirect_url,
    region: plaid_region,
    access_token: access_token
  )
end

​
Processing Transactions

# Source: app/models/plaid_item.rb:64
def import_latest_plaid_data
  PlaidItem::Importer.new(self, plaid_provider: plaid_provider).import
end

​
Handling Webhooks

Webhooks are received at:
  • US: /webhooks/plaid (app/controllers/plaid_items_controller.rb:106)
  • EU: /webhooks/plaid_eu (app/controllers/plaid_items_controller.rb:112)

​
Supported Products

Plaid offers multiple products. Sure primarily uses:
  • ✅ Transactions: Core transaction data
  • ✅ Auth: Account and routing numbers
  • ✅ Balance: Real-time balance data
  • ✅ Investments: Holdings and positions (for Investment accounts)
  • ✅ Identity: Account holder information
Source: app/models/plaid_item.rb:138
Plaid charges per Item (connection) and per product. Review Plaid’s pricing before connecting many accounts in production.

​
Best Practices

  1. Use Webhooks: Enable webhooks for real-time transaction updates
  2. Handle Update Flows: Implement UI to guide users through connection updates
  3. Monitor Status: Regularly check PlaidItem status and prompt users to reconnect
  4. Respect Rate Limits: Don’t sync too frequently; webhooks reduce the need for polling
  5. Test in Sandbox: Use Plaid’s sandbox environment for development

​
Additional Resources

Plaid Documentation

Official Plaid API documentation

Plaid Dashboard

Manage your Plaid integration

SimpleFIN Alternative

Privacy-focused alternative for US banks

Build docs developers (and LLMs) love

Get started for freeTalk to us