bankstatementparser-loader-bai2

A BAI2 (Bank Administration Institute, version 2) cash-management loader that parses BAI2 files into bankstatementparser Transaction objects.

Contents

• What is bankstatementparser-loader-bai2? — the problem it solves
• Install — PyPI, virtualenv
• Quick start — parse a file in three lines
• Public API — load_bai2, load_bai2_file, summarize_bai2
• Supported BAI2 subset — exactly which records are handled
• Amount and sign convention — how cents and debit/credit map
• When not to use this loader — honest boundaries
• Development — gates, make targets
• Security — input-handling posture
• Contributing — how to get changes in
• License — Apache-2.0

What is bankstatementparser-loader-bai2?

BAI2 (Bank Administration Institute, version 2) is the de-facto US cash-management file format that banks ship for intraday and prior-day balance and transaction reporting. The published bankstatementparser library parses PDF and other statement formats but does not support BAI2.

bankstatementparser-loader-bai2 is a small, dependency-light companion that fills that gap: give it a BAI2 payload and it returns a flat list of bankstatementparser.transaction_models.Transaction objects (source="bai2") that the rest of your deterministic pipeline can consume unchanged.

Install

Requires Python 3.10 or later. Works on macOS, Linux, and Windows.

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U bankstatementparser-loader-bai2

Quick start

from bankstatementparser_loader_bai2 import load_bai2_file

transactions = load_bai2_file("statement.bai")
for txn in transactions:
    print(txn.account_id, txn.currency, txn.amount, txn.description)

Or parse an in-memory payload:

from bankstatementparser_loader_bai2 import load_bai2

payload = (
    "01,SENDER,RECEIVER,260601,1200,FILE001,,,/\n"
    "02,RCVR,ORIG,1,260601,1200,USD,/\n"
    "03,0123456789,USD,010,150000,1,,/\n"
    "16,165,150000,Z,BANKREF1,CUSTREF1,Incoming wire payment/\n"
    "88,from ACME Corp invoice 42/\n"
    "16,475,2500,Z,BANKREF2,,ATM withdrawal/\n"
    "49,152500,2/\n"
    "98,152500,1,4/\n"
    "99,152500,1,6/\n"
)

for txn in load_bai2(payload):
    print(txn.amount, txn.category, txn.description)
# 1500 bai2:165 Incoming wire payment from ACME Corp invoice 42
# -25 bai2:475 ATM withdrawal

Runnable versions live in examples/.

Public API

from bankstatementparser_loader_bai2 import (
    Bai2StatementParser,
    load_bai2,
    load_bai2_file,
    summarize_bai2,
    Bai2Summary,
)

Bai2Summary is a dataclass with the fields file_id, group_count, account_count, transaction_count, and currency.

Each produced Transaction is populated as follows:

Supported BAI2 subset

BAI2 records are comma-delimited fields ending with a / delimiter, each beginning with a numeric type code. This loader implements a documented, pragmatic subset:

Any other (or unknown) leading type code is ignored so that vendor extensions do not abort the parse. Ignoring control-total trailers is a deliberate, documented choice: the goal is faithful transaction extraction, not file-level reconciliation.

Amount and sign convention

BAI2 amounts are unsigned integers in the account currency's minor units (cents), with no decimal point. They are converted to decimal.Decimal by dividing by 100. An empty amount field is treated as 0.

Debit / credit direction is derived from the documented numeric ranges of the 16 record's type code (this is the loader's chosen, documented convention):

The raw BAI2 type code is always preserved on every emitted Transaction in both category (as bai2:<code>) and reference, so no information is lost.

A small, optional lookup of well-known type codes (for example 142 "ACH credit", 301 "Commercial deposit", 475 "Check paid", 501 "Wire transfer debit") enriches the description of a 16 record that carries no free-text of its own; a record that already has text keeps its own text unchanged.

When not to use this loader

• You have ISO 20022 camt.053 or SWIFT MT940, not BAI2. Those are different formats with their own dedicated loaders.
• You need control-total reconciliation. This loader extracts transactions and deliberately ignores the 49/98/99 trailers; if you must validate file sums, do so before or after loading.
• You need the full BAI2 specification. This is a documented subset focused on transaction extraction, not an exhaustive BAI2 parser.

Development

This project uses Poetry and mise.

git clone https://github.com/sebastienrousseau/bankstatementparser-loader-bai2.git
cd bankstatementparser-loader-bai2
poetry env use python3.12
poetry install

A Makefile orchestrates the quality gates (kept in lockstep with CI):

Current state (v0.0.19): all tests passing, 100% line + branch coverage against a 100% enforced floor, mypy --strict clean, interrogate 100%, and a mutation-tested loader (317/336 mutants killed; the 19 survivors are documented equivalent mutants — see tests/MUTATION.md).

Security

• Read-only. The loader only reads text / files you pass it; it writes nothing.
• No XML, no network, no code execution. Parsing is a pure string-to-dataclass transformation.
• Decimal arithmetic is used throughout, avoiding float rounding surprises in financial amounts.
• Dependencies are pinned via poetry.lock and audited in CI.

To report a vulnerability, please use GitHub private vulnerability reporting rather than a public issue.

Contributing

Contributions are welcome — see the contributing instructions. Thanks to all the contributors who have helped build bankstatementparser-loader-bai2.

Ecosystem

bankstatementparser is part of a modular financial ecosystem. Optional companion packages provide specialized loaders, writers, AI agents, language servers, and transport protocol adapters:

Package	GitHub Repository	PyPI	Role	Description
bankstatementparser	sebastienrousseau/bankstatementparser		Core Engine	Unified parser for CAMT (052/053), PAIN.001, CSV, OFX, QFX, MT940, and PDF statements
bankstatementparser-mcp	sebastienrousseau/bankstatementparser-mcp		AI Protocol	Model Context Protocol (MCP) server exposing statement tools to LLMs & AI agents
bankstatementparser-lsp	sebastienrousseau/bankstatementparser-lsp		Developer Tooling	Language Server Protocol (LSP) with live SWIFT MT940 statement validation & diagnostics
bankstatementparser-transport-ebics	sebastienrousseau/bankstatementparser-transport-ebics		Transport	Automated bank statement retrieval over EBICS 3.0 (H005) and 2.5 (H004) protocols
bankstatementparser-writer-xlsx	sebastienrousseau/bankstatementparser-writer-xlsx		Output Writer	Formats and exports parsed banking transactions into styled Microsoft Excel (.xlsx) workbooks
bankstatementparser-writer-qif	sebastienrousseau/bankstatementparser-writer-qif		Output Writer	Serializes transactions into standard Quicken Interchange Format (.qif) exchange files
bankstatementparser-writer-ofx	sebastienrousseau/bankstatementparser-writer-ofx		Output Writer	Serializes transactions into standard Open Financial Exchange (.ofx) XML/SGML files
bankstatementparser-writer-swift	sebastienrousseau/bankstatementparser-writer-swift		Output Writer	Exports transactions to SWIFT MT940 customer statements and MT942 interim reports
bankstatementparser-loader-bai2	sebastienrousseau/bankstatementparser-loader-bai2		Input Loader	Parses BAI2 cash-management and account balance statements
bankstatementparser-loader-mt942	sebastienrousseau/bankstatementparser-loader-mt942		Input Loader	Parses SWIFT MT942 interim transaction reports with credit/debit summary reconciliation
bankstatementparser-loader-cfonb	sebastienrousseau/bankstatementparser-loader-cfonb		Input Loader	Parses French CFONB 120 / AFB120 120-byte fixed-width banking statement files
bankstatementparser-loader-camt054	sebastienrousseau/bankstatementparser-loader-camt054		Input Loader	Ingests ISO 20022 CAMT.054 real-time debit/credit notification stream XML
bankstatementparser-loader-sepa	sebastienrousseau/bankstatementparser-loader-sepa		Input Loader	Ingests ISO 20022 SEPA PAIN.002 payment status reports and PAIN.008 direct debit mandates
bankstatementparser-loader-bacs	sebastienrousseau/bankstatementparser-loader-bacs		Input Loader	Parses UK BACS Standard 18 / Faster Payments 106-byte fixed-width transmission files

License

Licensed under the Apache License, Version 2.0. Any contribution submitted for inclusion shall be licensed as above, without additional terms.

bankstatementparser.com · PyPI · GitHub