Pending Transaction Reconciliation#

When a banking provider delivers a new booked (settled) transaction, Sure must determine whether it corresponds to an existing pending entry so it can update the record in place rather than create a duplicate. This reconciliation is handled centrally by Account::ProviderImportAdapter#import_transaction and applies to all providers (Plaid, SimpleFIN, Enable Banking, Akahu, Up, Mercury, Lunchflow).

Matching Strategies (Priority Order)#

The adapter applies three strategies in sequence, stopping at the first match 1:

1. Plaid pending_transaction_id (highest confidence)#

Plaid supplies an explicit linking ID that ties a pending entry to its posted counterpart. When pending_transaction_id is present, the adapter does a direct find_by(external_id: pending_transaction_id, source:) lookup — no heuristics needed 2.

2. Exact Amount Match (find_pending_transaction)#

For providers without explicit linking IDs (SimpleFIN, Enable Banking, etc.), find_pending_transaction searches for an existing pending entry that matches:

• Same account, source, amount (exact), and currency
• Date within an 8-day backward window (pending date ≤ posted date)
• pending flag set in transactions.extra for any supported provider

The most recent candidate wins. On a successful match, the pending entry's external_id is updated to the posted transaction's ID, the pending flag is cleared, and the old external_id is written into extra["auto_claimed_pending_ids"] to prevent the stale pending record from being re-imported on the next sync 3.

3. Fuzzy Amount Match (suggestion only)#

When exact matching fails, find_pending_transaction_fuzzy and find_pending_transaction_low_confidence look for pending entries within ≤30% and 30–100% amount difference respectively, using a tighter 3-day window. These are designed for tip adjustments (e.g., a $50 authorization settling at $58 after tip). Unlike the exact-match path, fuzzy matches are not auto-applied — a suggestion is stored in extra["potential_posted_match"] on the pending entry for user review 4. To avoid false positives with recurring merchants, fuzzy matching requires either a unique merchant ID match or a unique name match, and returns nil if more than one candidate exists 5.

Same-ID Pending→Booked (Provider-Specific Bypass)#

Some ASPSPs (e.g., Revolut Italy via Enable Banking) reuse the same transaction_id for both the pending and booked states. In this case the adapter finds the entry by external_id from the start, so it skips the matching strategies above. When the incoming transaction is not pending but the stored entry still has a pending flag, the flag is cleared directly before saving 6.

Enable Banking: Importer-Level Pre-filtering#

Before entries reach the ProviderImportAdapter, the Enable Banking importer performs its own PDNG→BOOK deduplication. When the raw payload contains both PDNG and BOOK versions of a transaction, the importer uses dual-strategy matching to drop the pending row:

1. Fingerprint match — both rows resolve to the same compute_external_id value 7 8
2. Entry-reference cross-match — the pending and booked rows share an entry_reference even when their transaction_id values differ 9

The compute_external_id method itself uses a two-tier strategy 10:

• ID-based: "enable_banking_{transaction_id}" or "enable_banking_{entry_reference}" if available
• Content-based: MD5 hash of [date, amount, currency, credit_debit_indicator, creditor, debtor, remittance_info] — intentionally excluding status so PDNG and BOOK rows with the same logical content share the same fingerprint 11

The processor-level excluded-ID sets (auto_claimed_pending_ids + manual_merge) are pre-fetched per sync with two lateral-join queries and checked via O(1) Set lookups, preventing re-import of already-reconciled pending entries 12.

Known Edge Cases with Enable Banking#

The reconciliation logic was not originally designed for Enable Banking's behaviour, and several failure modes are tracked in issue #1470:

Workaround: Disable "Include pending transactions" in Settings → Self-Hosting to prevent pending entries from being imported at all. This eliminates duplicates but also removes real-time pending visibility 13.

Key Files#