SimpleFIN Integration#

SimpleFIN is Sure's primary US/global bank connectivity provider, covering depository, credit card, loan, investment, and crypto account types. It uses a bridge model: users create a SimpleFIN Bridge that aggregates one or more financial institutions, then generate a setup token to connect it to Sure. Unlike Plaid, no server-side cleanup is needed on disconnect — the access URL simply becomes inactive 1.

Architecture: Provider/Client Pattern#

Provider::Simplefin (app/models/provider/simplefin.rb) is an HTTParty-based client 2 with a 120-second timeout and SslConfigurable support. Its public interface has three methods:

• claim_access_url(setup_token) — Base64-decodes the setup token and POSTs to the claim URL to exchange it for an access URL containing embedded HTTP Basic Auth credentials.
• get_accounts(access_url, start_date:, end_date:, pending:) — Fetches accounts (with optional transactions/holdings) using Unix-timestamp date params. Returns parsed JSON or raises a typed SimplefinError.
• get_info(base_url) — Fetches server info lines from the bridge.

Transient network errors (SocketError, Net::*Timeout, ECONNRESET, etc.) are retried up to 3 times with exponential backoff and 25% jitter 34. The claim endpoint uses max_retries: 1, backoff: false for low-latency token exchange 5.

Runtime configuration is centralized in config/initializers/simplefin.rb, which reads:

• SIMPLEFIN_INCLUDE_PENDING (default: true) — controls whether pending transactions are fetched 6
• SIMPLEFIN_DEBUG_RAW (default: false) — enables raw payload logging 7
• money_market_tickers and money_market_patterns — lists for detecting cash-equivalent holdings in investment accounts 8

Data Model#

The Item → Account → account_providers chain mirrors the pattern used by other Sure providers (Akahu, EnableBanking). See Banking Provider Integration for the shared architecture overview.

Family
  → SimplefinItem (one bridge connection)
      → SimplefinAccount[] (one per upstream bank account)
          → AccountProvider (polymorphic join, provider_type="SimplefinAccount")
          → Account (Sure's canonical internal account)

simplefin_items — owns the bridge credential 9:

simplefin_accounts — mirrors each upstream account 10:

Encryption is applied to all sensitive fields via encrypts when encryption_ready? 1112. SimplefinItem also encrypts access_url deterministically (enabling exact-match queries) 13.

The account_providers polymorphic join table links SimplefinAccount to Account. SimplefinAccount#current_account prefers the AccountProvider-linked account and falls back to the legacy direct FK (accounts.simplefin_account_id) during the dual-write migration window 14.

Sync Pipeline#

The sync is driven by SimplefinItem::Syncer (app/models/simplefin_item/syncer.rb), which SimplefinItem exposes via the shared Syncable concern.

Phase 1 – Discovery / Balances-only#

When no linked accounts exist yet (first connection), the syncer runs a balances-only import via Importer#import_balances_only 15. This fetches /accounts without date filters, upserts minimal SimplefinAccount attributes, and updates balances for any already-linked accounts — but does not create new Account records or fetch transactions. last_synced_at is left nil so the next full sync triggers the chunked-history path 16.

Phase 2 – Chunked History Import (first full sync)#

When last_synced_at is nil or all linked accounts have no transactions yet, Importer#import_with_chunked_history runs 17. It:

1. Calls perform_account_discovery — an unbounded /accounts fetch to discover all accounts regardless of date 18.
2. Walks backwards in 60-day chunks from today up to 1 year (max 6 chunks) 19.
3. Stops early after 2 consecutive empty chunks (adaptive stopping) 20.
4. Merges transactions across chunks by ID (or composite key fallback) with a comparator that prefers non-pending records with real posted timestamps 21.

Phase 3 – Regular Sync#

Subsequent syncs use import_regular_sync, which fetches a 30-day lookback window from last_synced_at with a buffer 2223.

Phase 4 – Account Processing#

After import, SimplefinItem#process_accounts dispatches SimplefinAccount::Processor for each linked account 24. The processor runs four sub-steps 25:

1. process_account! — normalizes the balance (including liability sign logic via OverpaymentAnalyzer), updates accounts.balance and accounts.cash_balance, and calls account.set_current_balance which feeds CurrentBalanceManager to write the current_anchor valuation 26.
2. process_transactions — delegates to SimplefinAccount::Transactions::Processor.
3. process_investments — for Investment accounts: runs TransactionsProcessor and HoldingsProcessor; enqueues SimplefinHoldingsApplyJob when holdings change 2728.
4. process_liabilities — for CreditCard/Loan: delegates to CreditProcessor or LoanProcessor 29.

Balance history is then computed in a child Account::Syncer sync via the reverse-balance strategy (start from today's anchor, work backwards). See Balance History System.

Deduplication and Stale Linkage Repair#

Transaction deduplication uses the transaction id (or fitid) as the primary key, falling back to a [posted, amount, description] composite key when both are absent 30. During import, pending records are superseded by matching posted records using the priority comparator in Importer#import_account 31. After each account is processed, Entry.reconcile_pending_duplicates auto-resolves exact pending↔posted matches, and Entry.auto_exclude_stale_pending excludes pending entries older than 8 days 32.

Stale linkage repair handles the scenario where a user deletes and re-adds an institution in SimpleFIN, which generates new account_id values upstream. SimplefinItem#repair_stale_linkages detects unlinked SimplefinAccount records that have transactions but no Account link, matches them to linked records by name (case-insensitive), merges their transaction history, and transfers the AccountProvider (or legacy FK) from the old record to the new one 33.

Orphaned SimplefinAccount records (upstream account_id no longer returned by the API and not linked to any Account) are pruned during perform_account_discovery 34.

Key Files#