Skip to Content
Open Books for developers

Bank statements

Integrate bank statement extraction, supply verified opening balances and dates, and use running-balance assertions before posting transactions.

Reconciliation means checking that the transactions explain the change in the account balance. This guide covers structured exports. Use the PDF and OCR guide when the bank provides a PDF or image.

ExportWhat to prepare
CSVKeep the date, debit, credit, and running-balance columns. Supply the currency and opening balance when the export omits them.
OFX or QFXUse the original export with its currency and ledger balance. Supply an authoritative opening balance.
MT940Preserve the original opening and closing balance records and any statement segments.

Reconcile your first export

Identify the layout and currency

Use the original export for one account and statement period. A running balance is the amount after each transaction. If the CSV has no currency, supply its three-letter code, such as INR. Set date_order to dmy or mdy when you know the source convention. For example, 02/01/2026 means January 2 with dmy and February 1 with mdy.

Supply the opening balance

Bank CSV and OFX need an opening balance from the caller when they lack one. Use the verified closing balance of the preceding statement or another authoritative source. MT940 carries opening and closing records. Keep money in exact decimal form.

python -m openbooks run statement.csv --currency INR --opening 1000.00 --date-order dmy

The CLI writes the decision under out/. Use the previous statement's closing amount only after confirming the account, currency, and period.

Verify before posting

Check status first. In a release, use data.batches for opening and closing balances, data.transactions for individual movements, and assertions for the checks that passed. If your ledger expects signed amounts for bank movements, subtract debits and add credits using the separate direction field. Use decimal arithmetic and keep the currency with each amount.

Design for mismatches

  1. Hold a file that returns BALANCE_MISMATCH for review and save the refusal in your job history.
  2. Check the opening amount and compare the source running balances and closing balance. Look for missing rows, a truncated export, duplicate transactions, or a file that combines statement periods.
  3. Re-export the statement or correct verified parameters, then run it again. Use source evidence to trace the values in the release.

Supported layouts can derive an opening balance from the first movement and its running balance when you opt in. This arithmetic explains where the amount came from. Independent verification still requires evidence from the source. Use a documented opening balance when you can verify one.

For a runnable fixture and JSON output, use the bank CSV quickstart.

Compare a release with a broken balance

In the workspace, run Bank statement CSV alongside Bank CSV with a tampered balance. The second fixture uses a correct opening balance but contains a broken running-balance row. Its BALANCE_MISMATCH message reports that seven of eight rows tie out. Review the running-balance check and re-export the source if you encounter this in your own files. Changing a known opening balance would change the arithmetic for the rest of the statement.

View this page as Markdown