Transfer Matching and Pairing#

Sure provides three independent mechanisms to match existing transactions as transfer pairs: automatic (post-sync heuristic), manual (user-initiated via UI), and rule-based (Transaction Rule Engine action). All three resolve to the same Transfer join record linking an outflow transaction to an inflow transaction 1.

Automatic Matching#

Family::AutoTransferMatchable is mixed into the Family model and drives the auto-matching pipeline.

Trigger: auto_match_transfers! runs automatically after every account sync via Family::Syncer#perform_post_sync 2.

Candidate detection: transfer_match_candidates issues a UNION SQL query that finds transaction pairs across the family's accounts satisfying:

• Opposite-signed amounts (one positive outflow, one negative inflow)
• Dates within the configured date_window (default 4 days) 3
• A second branch handles multi-currency pairs using exchange_rate_tolerance (default 0.1) 4
• Excludes already-matched transactions and pairs recorded in rejected_transfers

Rejection memory: Calling Transfer#reject! writes a RejectedTransfer record so the same pair is never re-proposed 5.

Manual Matching#

TransferMatchesController handles user-initiated pairing.

• new action presents candidate target accounts and pre-filtered match suggestions for the selected transaction 6.
• create action calls build_transfer, which supports two modes:
  • "existing" — links to an already-discovered matching transaction 7
  • "new" — creates a placeholder transaction in the target account for pairing when no match exists 7

Rule-Based Matching#

Rule::ActionExecutor::SetAsTransferOrPayment is the Transaction Rule Engine action that converts matching transactions to transfers automatically.

• Its execute method builds a transfer to a configured target account 8 and creates a missing counterpart transaction if needed 9.
• Naming adapts based on whether the target is a liability account 10.

⚠️ Known issue: Pending auto-matched transfers can block rule execution. Because Transfer enforces uniqueness on inflow_transaction_id/outflow_transaction_id, an existing auto-match prevents a rule from reassigning the transaction 11.

Validation Rules#

The Transfer model enforces four constraints on all three pairing paths 5:

The 4-day default in transfer_match_candidates aligns with the pending-transfer date validation; the 30-day limit for confirmed transfers allows user-confirmed matches more flexibility 1.

Kind Assignment Across All Three Paths#

All three matching paths call Transfer.kind_for_account with the destination (inflow) account to set the outflow transaction's kind:

The inflow transaction always receives kind: "funds_movement" regardless of account type 16.

⚠️ Known bug (investment↔investment misclassification): Transfer.kind_for_account only accepts the destination account. It lacks the !source_is_investment? guard present in Transfer::Creator#outflow_transaction_kind, causing investment-to-investment transfers matched via auto-match, manual match, or rules to be misclassified as investment_contribution (counted as a budget expense) instead of funds_movement 17. Suggested fix: add an optional source_account: keyword to Transfer.kind_for_account 18.

Known Issues Summary#

Key Files#