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.

Bank reconciliation and bank feed workflows.

Bank Reconciliation

Bank reconciliation ensures your GL matches your bank statements.

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 – import duplicates (default: false)

Current shipped UI note: the Bank Reconciliation page now exposes advanced CSV options directly in the routed workflow: - 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, and the batch ID

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: imported count, duplicates skipped, batch ID.

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:

Current shipped UI note: the Match action now opens a ranked candidate review flow for the selected bank account. Operators pick a suggested journal entry inside the bank workspace instead of typing a raw journal-entry ID blindly.

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.
• 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 a transaction as excluded from reconciliation (e.g., personal transactions, duplicates).

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

Fields: - period_start (required) - period_end (required)

Automatically matches unmatched bank transactions to journal entries based on amount and date proximity. Returns match count and details.

Start Reconciliation

Fields: - period_start (required) - period_end (required) - statement_balance_cents (required) – ending balance from your bank statement

Creates an in_progress reconciliation session. Computes the GL balance for comparison. Only one in-progress reconciliation per bank account is allowed.

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

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.

Complete Provider Authorization

Use this after creating a Plaid/provider feed if authorization was not completed inline.

Fields: - authorization_code (required) – provider consent token/code - seed_transactions (optional) – initial provider transactions for the first sync window

When a provider feed falls behind its expected cadence or remains in retry state, the Bank Feeds page now surfaces that as an exception condition instead of treating stale feeds as normal operating posture.

After a successful authorization, the feed moves to active with sync_state=pending_initial_sync until the first sync completes.

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.