Plaid Integration#

Sure integrates with Plaid as a banking and investment data provider. The integration covers depository, credit, investment, and loan accounts across US/CA and EU regions 1. The top-level API client lives in Provider::Plaid, which wraps the Plaid Ruby SDK. All orchestration flows through PlaidItem, the ActiveRecord model that represents a single Plaid Link connection (one access_token per institution) 2.

Key Models#

Sync Pipeline (5 Phases)#

PlaidItem::Syncer#perform_sync drives each sync in sequence 3:

1. Import — plaid_item.import_latest_plaid_data calls PlaidItem::Importer, which fetches item metadata and all account data from the Plaid API and stores raw payloads 4.
2. Process accounts — plaid_item.process_accounts runs PlaidAccount::Processor for every PlaidAccount, creating or updating Sure Account records and the AccountProvider join 5 6.
3. Setup stats — counts unlinked accounts and sets pending_account_setup on the PlaidItem 7.
4. Schedule account syncs — for every linked account, calls account.sync_later(...) to calculate historical balances 8.
5. Collect stats — aggregates transaction, holdings, and health metrics onto the Sync record 9.

Data Fetching & Pagination#

All Plaid API calls are made at the item level by PlaidItem::AccountsSnapshot, then scoped down per account 10.

Transactions (cursor-based)#

Regular transactions use Plaid's transactions_sync endpoint with a cursor: the loop runs until has_more is false, accumulating added, modified, and removed arrays 11. The cursor is saved to PlaidItem.next_cursor at the end of each successful import 12, so subsequent syncs are incremental. History at link time is bounded by MAX_HISTORY_DAYS — 730 days in production, 90 in development 13.

Fetching is gated: transactions are only requested if the item supports_product?("transactions") and has at least one account 14.

Investment Transactions (offset-based)#

Investment transactions use investments_transactions_get with offset pagination — a date window (start_date/end_date) is fixed at call time, and the loop increments offset until transactions.length >= response.total_investment_transactions 15. When no start_date is provided, it falls back to MAX_HISTORY_DAYS.days.ago 16. Holdings and their securities are fetched in the same get_item_investments call and merged with transaction securities 17.

Investment data is only fetched when supports_product?("investments") is true and there is at least one account of type == "investment" 18.

PlaidAccount → Account Linkage#

Each PlaidAccount can link to a Sure Account via two paths 19:

1. New path: has_one :account_provider, as: :provider → has_one :linked_account, through: :account_provider (the AccountProvider join record).
2. Legacy path: has_one :account, foreign_key: :plaid_account_id (being migrated out).

current_account returns linked_account || account, preferring the new path 20.

Impact on sync failures: PlaidItem#accounts resolves only PlaidAccount records where current_account is non-nil 21. If process_account! fails for a PlaidAccount (e.g., due to a processing error), that account won't be linked and schedule_account_syncs will skip it — its balance history won't be recalculated. The Syncer tracks this by counting plaid_accounts where current_account.nil? and setting pending_account_setup: true on the item 22.

process_account! halts the entire processor on failure; process_transactions, process_investments, and process_liabilities each fail independently — exceptions are swallowed, reported to Sentry, and processing continues 23.

Error Handling#

PlaidItem::Importer catches Plaid::ApiError at the import boundary 24:

• ITEM_LOGIN_REQUIRED: sets plaid_item.status = :requires_update and swallows the error (sync is considered succeeded) 25.
• All other errors: re-raised, propagating to the Sync record and marking it failed.

PlaidItem#remove_plaid_item (called on before_destroy) ignores ITEM_NOT_FOUND, INVALID_API_KEYS, INVALID_CLIENT_ID, and INVALID_SECRET from Plaid when deleting, so local cleanup proceeds regardless 26.

PlaidItem#get_update_link_token catches ITEM_NOT_FOUND on re-link attempts, sets status: :requires_update, and returns nil so callers can render a friendly error instead of crashing 27.

Rate Limiting#

Provider::Plaid itself does not include Provider::RateLimitable. The RateLimitable concern 28 is a shared mixin for providers that need interval-based throttling (e.g., enforcing a MIN_REQUEST_INTERVAL between calls via throttle_request). Rate limit handling for Plaid is instead governed by Plaid's API itself; errors surface as Plaid::ApiError and propagate through the standard error chain.

Products & Region Support#

Provider::Plaid supports three products: transactions, investments, and liabilities 29. The primary product selected at link time depends on the account type being connected — investment accounts get investments, credit/loan accounts get liabilities, everything else gets transactions 30. EU items are always linked with transactions as the primary product regardless of type 31.

Country codes differ by region: US/CA for the us region; 15 EU countries for the eu region 32. Webhooks are verified via JWT/ES256 with a 5-minute expiry window 33.

Related Topics#

• Banking Provider Integration — shared Syncable mixin and sync infrastructure used by all providers including Plaid
• Pending Transaction Reconciliation — how Plaid's pending_transaction_id enables high-confidence pending→posted matching 34
• Transaction Sync Windows and Lookback — cursor vs. date-window strategies across providers 35
• SnapTrade Integration — separate brokerage provider, distinct from Plaid's investment data pipeline