Bank Connections

Guide 9: Bank Connections (SimpleFin)

Connect your bank for automatic transaction imports

Overview

While manual file imports work well, connecting your bank through SimpleFin provides automatic transaction downloads. Transactions appear in OtterLedger without manual downloads, making it easier to stay current with your finances.

What you'll learn:

• What SimpleFin is and how it works
• Setting up a SimpleFin account
• Connecting your bank
• Managing automatic syncs
• Reading account cards and balance indicators
• Troubleshooting connection issues

Time required: 15-20 minutes for initial setup

Prerequisites

• OtterLedger installed
• Bank account(s) you want to connect
• Email address for SimpleFin account

About SimpleFin

What is SimpleFin?

SimpleFin is a privacy-focused service that connects to your bank and securely retrieves transactions. Unlike some aggregators:

• Open protocol (no vendor lock-in)
• You control the connection
• Minimal data retention
• One-time setup per bank

How It Works

Your Bank <-> SimpleFin <-> OtterLedger
              (bridge)

1. SimpleFin connects to your bank using your credentials
2. SimpleFin downloads new transactions
3. OtterLedger fetches transactions from SimpleFin
4. Transactions appear in your pending inbox

SimpleFin vs. Manual Import

Alternative: If SimpleFin does not support your bank, or you prefer not to use a third-party service, you can import transactions from PDF bank statements instead. See Guide 48: PDF Statement Import.

Setting Up SimpleFin

Step 1: Create SimpleFin Account

1. Go to SimpleFin.org
2. Click Get Started or Sign Up
3. Enter your email address
4. Create a password
5. Verify your email

[Screenshot: SimpleFin signup page]

Step 2: Get a Setup Token

1. Log in to SimpleFin
2. Go to Connections or Setup
3. Click Create New Token
4. Copy the setup token (long string of characters)

[Screenshot: SimpleFin token generation]

Important: This token is shown only once. Copy it before closing the page.

Step 3: Connect SimpleFin to OtterLedger

1. In OtterLedger, go to Settings -> Connections
2. Click Add Connection -> SimpleFin
3. Paste your setup token
4. Click Connect

[Screenshot: OtterLedger SimpleFin connection dialog]

OtterLedger validates the token and establishes the connection.

Connecting Your Bank

Step 1: Add Bank in SimpleFin

1. Log in to SimpleFin
2. Click Add Bank or Add Connection
3. Search for your bank
4. Select your bank from the list

[Screenshot: SimpleFin bank search]

Step 2: Enter Bank Credentials

1. Enter your online banking username
2. Enter your online banking password
3. Complete any security verification (MFA, security questions)
4. Click Connect

[Screenshot: Bank credential entry (generic)]

Security Note: SimpleFin uses bank-grade encryption. Your credentials are encrypted and used only to access your account.

Step 3: Select Accounts

1. SimpleFin shows available accounts
2. Check the accounts you want to sync
3. Click Save or Continue

[Screenshot: Account selection in SimpleFin]

Step 4: Map Accounts in OtterLedger

1. In OtterLedger, go to Banking -> Connections
2. Click Refresh Accounts
3. For each bank account, select the matching OtterLedger account
4. Click Save Mapping

[Screenshot: Account mapping in OtterLedger]

The Banking Center

Getting Started: Onboarding Card

If you have not connected any banks yet, the Banking view shows a welcome card explaining what SimpleFin is and how to get started. The card walks you through the same setup steps described above and provides a direct link to SimpleFin's website.

[Screenshot: Onboarding card for new users]

Once you connect your first account, the onboarding card is replaced by your account cards.

Account Cards

After syncing, each connected bank account appears as a card in the Banking Center. Cards give you an at-a-glance view of each account's current state.

Balance Information

Each card displays three balances side by side:

Being able to see the bank-reported balance alongside the OtterLedger calculated balance at a glance makes it easy to spot discrepancies before they become problems. If the bank balance and cleared balance differ by more than a few cents, the card highlights the difference so you can investigate.

Tip: A small difference between Bank Balance and Cleared Balance is normal if you have transactions that have not cleared yet (pending purchases, checks in transit). A large or growing gap usually means a transaction is missing or was entered with the wrong amount.

Sync Status Display

Cards show real-time sync status so you always know when your data was last refreshed:

The last sync time is shown in plain language: "Just now", "3h ago", "Yesterday", or a date for older syncs. After a successful sync, the card also shows how many new transactions were found (for example, "5 new transactions").

If the last sync failed, the card shows the error message so you know whether the issue is a temporary bank outage, a changed password, or a token problem.

[Screenshot: Account card with sync status and balance display]

Broken Link Indicator

When a SimpleFin connection has issues -- for example, because a token has expired or your bank requires re-authentication -- the affected account card shows a broken link warning icon alongside the account name.

Hovering over the warning icon shows a tooltip explaining the problem: "This account no longer exists in SimpleFin. Click Update to resolve."

This indicator tells you exactly which account needs attention without requiring you to dig through settings to find out why sync stopped working.

[Screenshot: Broken link warning icon on an account card]

Common reasons for a broken link:

• Your bank password changed and SimpleFin's stored credentials are no longer valid
• The bank requires periodic re-authentication (common with banks that have strict security policies)
• SimpleFin's access token for the account expired
• The account was removed from SimpleFin on the SimpleFin side

To resolve a broken link, go to Settings -> Connections, find the affected bank, and click Re-authenticate or Update. You will be prompted to log in to your bank through SimpleFin again.

Syncing Transactions

Automatic Sync

By default, OtterLedger syncs with SimpleFin:

• When you open the application
• Every 4 hours while running
• When you manually request a sync

Manual Sync

To sync immediately:

1. Go to Banking
2. Click Sync Now button
3. Wait for sync to complete

[Screenshot: Sync button and progress indicator]

Viewing New Transactions

After sync, new transactions appear in the Pending Inbox:

1. Go to Banking
2. Review the Pending transactions
3. For each transaction:
   • Categorize it
   • Verify payee name
   • Accept to add to your account

[Screenshot: Pending transaction inbox]

Managing Connections

View Connected Banks

Go to Settings -> Connections to see:

• Connected banks
• Last sync time
• Sync status
• Error messages (if any)

[Screenshot: Connections overview]

Edit Account Mapping

If you create new OtterLedger accounts:

1. Settings -> Connections
2. Click on the bank connection
3. Click Edit Mapping
4. Assign new accounts
5. Save

Disconnect a Bank

1. Settings -> Connections
2. Click on the bank
3. Click Disconnect
4. Confirm

This removes the connection but keeps all imported transactions.

Pause Syncing

To temporarily stop syncing:

1. Settings -> Connections
2. Click on the connection
3. Toggle Pause Sync

Useful when troubleshooting or traveling.

Sync Settings

Configure Sync Behavior

Go to Settings -> Connections -> Sync Settings:

[Screenshot: Sync settings panel]

Handling Bank Issues

Re-authentication Required

Banks periodically require re-authentication:

1. You'll see a notification: "Bank requires re-authentication"
2. Click the notification or go to Connections
3. Click Re-authenticate
4. Log in to your bank through SimpleFin again

Tip: Watch for the broken link warning icon on account cards -- it appears as soon as OtterLedger detects that a connection has gone stale, before the next scheduled sync would otherwise fail silently.

Bank Not Supported

If your bank isn't in SimpleFin's list:

1. Check SimpleFin's supported banks page
2. Request support for your bank
3. Use manual import as an alternative -- see Guide 48: PDF Statement Import

Connection Errors

Privacy & Security

What Data is Shared

SimpleFin receives:

• Your bank login credentials (encrypted)
• Transaction data (to pass to OtterLedger)
• Account balances

SimpleFin does NOT:

• Sell your data
• Store transaction history long-term
• Have access to move your money

Revoking Access

To completely remove SimpleFin access:

1. Disconnect in OtterLedger
2. Log in to SimpleFin and delete the bank connection
3. Optionally, change your bank password

Supported Banks

SimpleFin supports thousands of US banks and credit unions. Common supported institutions:

Major Banks:

• Chase
• Bank of America
• Wells Fargo
• Citibank
• US Bank

Credit Unions:

• Navy Federal
• Pentagon Federal
• State Employees Credit Union
• Many local credit unions

Credit Cards:

• American Express
• Discover
• Capital One
• Barclays

Investment Accounts:

• Fidelity
• Vanguard
• Charles Schwab

Check SimpleFin's website for the full list.

Tips & Best Practices

1. Start with one bank - Get familiar with the process before connecting everything

2. Review pending transactions - Don't auto-accept until you're confident in the sync quality

3. Keep credentials updated - If you change bank passwords, update SimpleFin immediately

4. Watch account cards - The bank-reported balance on each card makes it easy to catch discrepancies before reconciliation time

5. Act on broken link warnings promptly - A broken link means no new transactions are coming in; the longer you wait, the larger the gap to catch up

6. Check periodically - Verify synced balances match your bank

7. Use both methods - SimpleFin for daily updates, manual import or PDF statements for historical data

8. Watch for duplicates - If you also import files, watch for overlapping date ranges

Troubleshooting

Q: Sync shows no new transactions

A:

• Check your bank for recent activity
• Verify account mapping is correct
• Some transactions take 1-2 days to appear

Q: Duplicate transactions after sync

A:

• Check if you also imported a file for the same dates
• Use Tools -> Find Duplicates
• Consider pausing file imports while using SimpleFin

Q: Bank requires re-authentication frequently

A: Some banks have strict security. This is normal for banks with aggressive session timeouts. The broken link warning icon will appear on the account card whenever this happens, so you can re-authenticate without needing to check settings manually.

Q: Wrong account linked

A:

• Go to Connections -> Edit Mapping
• Reassign the bank account to the correct OtterLedger account

Q: Transactions are missing categories

A: SimpleFin provides raw transaction data. Use OtterLedger's AI categorization or create rules.

Q: How do I sync investment accounts?

A: SimpleFin supports some investment accounts for balance and transactions. Holdings sync is not available.

Q: The bank balance on the card doesn't match my bank's website

A: Bank balances are retrieved at sync time. Click Sync Now to fetch the latest balance. If the discrepancy persists after syncing, check whether the account is mapped correctly and whether SimpleFin shows the same balance on its own dashboard.

Q: My bank isn't supported by SimpleFin

A: You can still import transactions manually. OtterLedger supports QIF, OFX, QBO, and CSV file imports, as well as PDF statement parsing. See Guide 48: PDF Statement Import for the PDF option.

What's Next?

With bank connections set up:

• Guide 10: Reconciliation - Verify synced data
• Guide 23: AI Categorization - Auto-categorize transactions
• Guide 24: Creating Rules - Automate processing
• Guide 48: PDF Statement Import - Import from PDF statements (alternative to SimpleFin)

Need help? Visit the OtterLedger community at github.com/openledger or check the FAQ.