Bank Operations

Scope

Bank operations matter once cash movement becomes material to the business. This guide keeps the operator-facing control model and removes private connectivity and API detail.

Authority recovery and provider-state guidance

When Keystone cannot prove an older transaction’s legal entity and connection, the row is labeled Authority unavailable and remains non-matchable. Choose the row’s direct Recover Authority action; it opens the recovery form without opening a disabled Match action. Search the eligible business-labelled connections for that bank account, select the legal entity, and enter a specific reason. Recovery is one-time and audited; do not select a convenient current entity unless it is the transaction’s actual authority.

Connected feeds require a legal entity and bank account during setup. Keystone creates the internal ingestion authority automatically. Operators never need an ETL connection ID.

Provider-pending transactions are evidence only and cannot be matched or reconciled. Wait for the provider to post, remove, or reverse the item. A currency mismatch or missing currency blocks cursor advancement and leaves a visible feed recovery state; configure the correct account/entity authority rather than converting the amount manually.

Auto-match reports how many rows were processed, matched, and still require review. If work remains, use the visible Match, Classify, or Exclude recovery action. Reconciliation completion is safe to retry after an ambiguous response; Keystone returns the same completed result and prevents another active reconciliation for the same bank account.

Bank reconciliation and bank feed workflows.

Statement Import Recovery

Statement import history lists the ten most recent immutable upload attempts with source filename/type, original imported/skipped counts, exact persisted legal-entity/bank-GL/connection authority, and current matched, excluded, reconciled, and remaining-review totals. Duplicate-only attempts remain visible as Replay: no new rows. Choose Review exceptions to filter the transaction table to that exact batch and its unmatched rows, or View batch for a resolved population. Each unmatched row exposes named Match and Exclude controls. Classify a row when no journal candidate exists; exclusions require a retained reason. A batch is Resolved only when it has no unmatched rows. Reconciliation completion remains a separate controlled step and still requires zero difference.

Authority unavailable; review required on an older batch means migration could not prove one historical entity and connection. Keystone labels that evidence legacy_incomplete; selecting a current company does not rewrite it. Use the surrounding transaction and audit evidence for controlled review rather than treating missing authority as a clean or resolved claim.

The the relevant workflow workspace keeps imports, server-paged transactions, match/exclude/unmatch actions, reconciliation sessions, two-column evidence, drill-down, and structured recovery guidance in one routed workflow. A failed dependency remains visible and retryable instead of being represented as an empty bank state.

Reconciliation Completion Readiness

An in-progress reconciliation now shows its completion readiness beside the statement difference. Unmatched transactions are a separate blocker even when the statement-to-ledger difference is $0.00. Select the unmatched count to open Import & Match already filtered to the reconciliation’s bank account and statement dates. When every row is matched or excluded but the ledger difference remains nonzero, the blocker opens all transactions for that account and period so an incorrect exclusion can be restored and classified. The Complete action appears only when no unmatched transactions remain and the stored difference is within tolerance. A server-side completion rejection remains visible on the affected reconciliation row until it is resolved or dismissed by navigating to the blocker population.

Bank Reconciliation

Recover a Transaction With No Match Candidate

When Match finds no existing journal entry, the modal stays in the reconciliation workflow and opens the classification form. Select the legal entity and search the offset-account picker, confirm the posting date, enter a specific accounting memo, then choose Create Entry & Match. Keystone creates a balanced two-line journal entry and matches the bank transaction as one operation.

Deposits debit the selected bank account and credit the offset account. Withdrawals debit the offset account and credit the bank account. The posting date must belong to an open fiscal period for the selected entity. If it does not, Keystone preserves the unmatched transaction and identifies the period that must be created or opened before retrying.

In operator navigation this workspace is Bank Statements & Reconciliation. Use it for CSV, OFX, and QFX statement uploads, transaction matching, duplicate import recovery, and reconciliation sessions. Connected Bank Feeds owns provider synchronization. Provider Journal Imports owns provider-generated accounting journals before they post to the ledger.

Bank reconciliation ensures your GL matches your bank statements.

Statement lists and reconciliation sessions remain tenant-scoped, but every manual upload requires an explicit legal entity. Keystone stores that entity together with the selected GL bank account on the import connection so later matching and classification use durable authority rather than an implicit default.

Workflow

1. Import bank transactions – upload CSV or OFX file
2. Match transactions – review ranked journal-entry candidates and confirm the right match
3. Start reconciliation session – specify period and statement balance
4. Complete reconciliation – verify difference is zero

Import Bank Transactions

Upload a CSV or OFX/QFX file (multipart form upload, max 10 MB).

Form fields:

• file (required) – the bank statement file
• date_col – CSV column name for date (default: date)
• description_col – CSV column name for description (default: description)
• amount_col – CSV column for single amount (default: amount)
• debit_col, credit_col – alternative: separate debit/credit columns
• date_format – date parsing format (default: %Y-%m-%d)
• force_import – retain CSV rows that match the fallback date/amount/description duplicate check (default: false); exact OFX/QFX transaction IDs are never duplicated

Current shipped UI note: the Bank Reconciliation page now exposes advanced CSV options directly in the routed workflow:

• required legal-entity and GL bank-account selection; an unavailable entity directory blocks upload and provides Retry
• custom date/description/amount column mapping
• separate debit/credit column mode
• force_import with duplicate-risk warning
• an import summary showing imported rows, duplicates skipped, batch ID, and the persisted authority snapshot
• durable attempt history showing original source/outcome evidence beside current exception progress

OFX/QFX uploads still ignore the CSV mapping fields, but they do honor force_import.

Supported formats:

• CSV – configurable column mapping
• OFX/QFX – auto-detected by file extension or content; handles both OFX 2.x (XML) and OFX 1.x (SGML)

Returns import statistics, batch ID, status, and exact persisted authority. Duplicate detection is scoped to the signed-in tenant and selected bank account, so another tenant’s source identity or matching economic row can never suppress an import. OFX/QFX transaction IDs are durable provider identities. CSV and other rows receive a durable identity from the uploaded file fingerprint and source row. Keystone checks exact source identity first, then may link one matching date/signed-amount/description economic candidate per incoming row; authority_linked counts those cross-format identity links. This capacity rule preserves legitimate repeated equal transactions instead of allowing one old row to suppress every match.

List Bank Transactions

Returns a paged response:

Current shipped UI note: the Bank Reconciliation page now pages transactions from this server response directly instead of preloading the entire list into the browser. The routed workspace also exposes a bank-account filter and an explicit account column so multi-account review stays visible.

Match a Transaction

Link a bank transaction to a journal entry or source document.

Fields:

Before completing a reconciliation, Keystone rechecks every matched row against its persisted journal or allowed source. If a legacy row only says matched but its target is missing or invalid, completion identifies that transaction and remains blocked. Unmatch the row, then match or classify it against current evidence.

Review Match Candidates

Returns ranked journal-entry candidates for the selected bank transaction.

• Candidates are limited to the same bank account, posted journal entries, and a short date-review window. Scores are review guidance, not permission to bypass the server’s entity and amount checks.
• The routed Bank Reconciliation page uses this lookup to power the candidate picker in the Match modal.
• If no candidate is returned, the operator still knows the transaction, bank account, and amount that need exception review.

Exclude a Transaction

Mark an unmatched transaction as excluded from reconciliation (e.g., personal transactions or duplicate provider rows). Matched transactions must be unmatched first so exclusion cannot leave contradictory journal linkage.

An exclusion remains reversible until its reconciliation is completed. Choose Restore on an excluded row to return it to unmatched, then match it to an existing journal or use Create Entry & Match for a real bank fee, interest item, or other ledger difference. Restore clears the exclusion reason and records the prior reason in audit evidence. Completed reconciliation evidence remains immutable and returns controlled-correction guidance.

Unmatch a Transaction

• The transaction must currently be in “matched” status.
• Unmatching is blocked if the transaction belongs to a completed reconciliation (returns 400).
• Transactions in an in-progress reconciliation can be unmatched.
• The routed Bank Reconciliation page shows an “Unmatch” button on every matched transaction row.

Auto-Match

Use the durable, entity-scoped run from the Bank Reconciliation workspace. It returns immediately, polls bounded progress, and exposes cancel/retry recovery; the removed synchronous endpoint is not a supported contract.

For CSV/OFX statement rows, Keystone also requires the journal to belong to the connection’s displayed legal entity and to contain an exact debit or credit on the displayed GL bank account. Each exact journal bank line provides one match unit. This permits separate bank lines in one balanced journal to reconcile their corresponding statement rows, but retries and duplicate statement rows cannot reuse an already-consumed line or create another journal entry.

The routed workspace retains that result after the toast disappears. A non-zero unmatched count is a visible exception outcome and directs the operator to Match or Exclude each remaining row before reconciliation completion. A zero unmatched count directs the operator to open the reconciliation session and verify its statement difference.

Start Reconciliation

Fields:

• period_start (required)
• period_end (required)
• statement_balance_cents (required) – ending balance from your bank statement

Complete Reconciliation

Finalizes the reconciliation. Fails if:

• Any unmatched transactions remain in the period (match or exclude them first)
• The difference between statement balance and GL balance exceeds 1 cent

When the reconciliation completes successfully, the cleared transactions in that period are stamped with the reconciliation ID so the closed session can be reconstructed later.

List Reconciliations

Returns a paged response with items plus the full total count so the routed UI can page reconciliation history server-side.

Two-Column Reconciliation View

Returns the AS 2301-style two-column reconciliation view for one reconciliation:

• book side: GL balance plus bank-fee, interest, and NSF adjustments
• bank side: statement balance plus deposits-in-transit and outstanding-check adjustments

Auto-categorization note: all bank transaction creation points (CSV/OFX import, provider sync, API push ingest, ETL engine) now auto-populate transaction_category using core.utils.bank_categorizer.categorize_bank_transaction(). Categories are inferred from description patterns (bank fees, interest, NSF), check numbers (outstanding checks), amount sign (deposits in transit), and match status (cleared). For historical transactions without a category, the endpoint derives the category on-the-fly as a fallback.

Current routed UI note: the “Reconciliation Sessions” tab shows a Columns icon on each completed reconciliation. Clicking it opens a two-column modal with side-by-side cards for the Book Side (GL balance + bank fee/interest/NSF adjustments = adjusted book balance) and Bank Side (statement balance + deposits-in-transit - outstanding checks = adjusted bank balance). A green or red alert shows whether the adjusted balances match. A “View Transactions” button switches to the drill-down modal.

Reconciliation Transaction Drill-Down

Returns transactions stamped with a specific reconciliation, with filtering and pagination.

Query params:

• skip, limit (max 200)

Current routed UI note: the “Reconciliation Sessions” tab shows an Eye icon on each completed reconciliation. Clicking it opens a drill-down modal with a category filter dropdown, a paginated transaction table (date, description, amount, category badge, status badge), and check-number display where applicable. A “Two-Column View” button switches to the AS 2301 view. Both modals cross-link to each other for seamless navigation.

Every bank-data page keeps the full ingestion path visible in the shell: Connections, Imports, Transform rules, Matching rules, Bank feed, and Reconcile. The active step is marked, and unauthorized steps are omitted. This is the canonical recovery path when an import, mapping, match, or reconciliation needs follow-up.

Bank Feeds

Bank feeds provide automated or semi-automated import of bank transactions from external sources.

Connection Types

Type	Description
plaid	First-party provider onboarding and sync
manual_import	Manual CSV/OFX upload
api_push	External system pushes transactions

Create a Bank Feed Connection

Fields:

• name (required) – display name
• institution_name (required) – bank name
• account_number_masked – last 4 digits of account
• sync_frequency_hours – default: 24

Connections start in pending_auth status.

Provider-connected feeds are no longer expected to be synced only by manual button press. Keystone now runs a scheduler-backed bank-feed cadence loop that checks sync_frequency_hours, respects retry backoff windows, and leaves the manual Sync Now action as an operator override or recovery tool.

Connection Statuses

Status	Description
pending_auth	Awaiting authentication setup
active	Connected and syncing
inactive	Deactivated
error	Sync failed (check last_error)

Trigger Manual Sync

Only works on provider-connected active or error feeds.

Current shipped behavior: this action imports unseen provider transactions using the feed’s stored provider cursor, updates freshness metadata, and clears retry state on success. If the provider requires reauthorization or a transient sync error occurs, Keystone returns an explicit recovery state and, on transient failures, schedules the next retry window.

If Plaid reports a modification or removal for a matched or reconciled transaction, Keystone preserves the provider cursor and stores a structured controlled_transaction_conflict on the feed. The feed detail and failed sync response identify the provider transaction and recovery action. The issue remains visible until reauthorization completes or a later provider sync succeeds; those recovery paths clear the issue without disturbing the encrypted feed credential.