okane 0.3.0

Parser for bank statements in camt.053 XML format (Czech Banking Association dialect)

お金かね 【okane】

okane is a pure Python parser for bank statements in camt.053 XML format [1], in dialect used by the Czech Banking Association (ČBA) [2].

It parses BkToCstmrStmt XML element into okane.models.BankToCustomerStatement which is a Pydantic model. It can also work as a CLI tool, converting camt.053 XML files to JSON or CSV.

Installation

pip install okane

# or, if you'd like to use the CSV, XLSX export features and access the data as `pd.DataFrame`
pip install okane[pandas]

Example

Python API

>>> import okane
>>> statement = okane.BankToCustomerStatement.from_file("./tests/data/test2.xml")
>>> statement.opening_balance
Balance(amount=Decimal('1000.00'), currency='CZK', date=datetime.date(2023, 3, 1))
>>> statement.transactions[5].amount
Decimal('1000.00')
>>> statement.transactions[5].currency
'CZK'
>>> statement.transactions[5].related_account_id
AccountId(iban='LT6632xxxxxx', id=None)
>>> statement.transactions[5].related_account_bank_id
BankId(bic='REVOLT21', id=None)
>>> statement.transactions[3].ref
TransactionRef(message_id='XXX', end_to_end_id='XXX', account_servicer_ref=None, payment_invocation_id=None, instruction_id=None, mandate_id=None, cheque_number=None, clearing_system_ref=None)
>>> df = statement.as_dataframe()

Command-line interface

head ./tests/data/test2.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.053.001.02">
    <BkToCstmrStmt>
        <GrpHdr>
            <MsgId>camt.053-2023-04-01-001</MsgId>
            <CreDtTm>2023-04-01T12:00:00.000+02:00</CreDtTm>
            <MsgRcpt>
                <Nm>John Doe</Nm>

# okane ./tests/data/test*.xml -f json --no-indent -o output.jsonl
# okane ./tests/data/test*.xml -f csv -o output.csv
# okane ./tests/data/test*.xml -f xlsx -o output.xlsx

okane ./tests/data/test2.xml

{
    "statement_id": "XXX-STATEMENT-ID",
    "created_time": "2023-04-01T12:00:00+02:00",
    "from_time": "2023-03-01T00:00:00+01:00",
    "to_time": "2023-03-31T23:59:59.999000+02:00",
    "account_id": {
        "iban": "XXX-IBAN",
        "id": null
    },
    "opening_balance": {
        "amount": "1000.00",
        "currency": "CZK",
        "date": "2023-03-01"
    },
    "closing_balance": {
        "amount": "2000.00",
        "currency": "CZK",
        "date": "2023-03-31"
    },
    "transactions": [
        {
            "ref": {
                "message_id": "XXX",
                "end_to_end_id": "XXX",
                "account_servicer_ref": null,
                "payment_invocation_id": null,
                "instruction_id": null,
                "mandate_id": null,
                "cheque_number": null,
                "clearing_system_ref": null
            },
            "entry_ref": "XXX-REF-1",
            "amount": "-100.00",
            "currency": "CZK",
            "val_date": "2023-03-01",
            "remote_info": "Nákup dne 27.2.2023, částka 100.00 CZK",
            "additional_transaction_info": "Nákup dne 27.2.2023, částka 100.00 CZK",
            "related_account_id": null,
            "related_account_bank_id": null
        },
        {
            "ref": {
                "message_id": "XXX",
                "end_to_end_id": "XXX",
                "account_servicer_ref": null,
                "payment_invocation_id": null,
                "instruction_id": null,
                "mandate_id": null,
                "cheque_number": null,
                "clearing_system_ref": null
            },
            "entry_ref": "XXX-REF-2",
            "amount": "-200.00",
            "currency": "CZK",
            "val_date": "2023-03-02",
            "remote_info": null,
            "additional_transaction_info": "transaction note",
            "related_account_id": {
                "iban": null,
                "id": "XXX-OTHER-ACC"
            },
            "related_account_bank_id": {
                "bic": null,
                "id": "XXX-OTHER-BANK"
            }
        },
        {
            "ref": {
                "message_id": "XXX",
                "end_to_end_id": null,
                "account_servicer_ref": null,
                "payment_invocation_id": null,
                "instruction_id": null,
                "mandate_id": null,
                "cheque_number": null,
                "clearing_system_ref": null
            },
            "entry_ref": "XXX-REF-3",
            "amount": "1000.00",
            "currency": "CZK",
            "val_date": "2023-03-07",
            "remote_info": null,
            "additional_transaction_info": null,
            "related_account_id": {
                "iban": null,
                "id": "XXX-OTHER-ACC"
            },
            "related_account_bank_id": {
                "bic": null,
                "id": "XXX-OTHER-BANK"
            }
        },
        {
            "ref": {
                "message_id": "XXX",
                "end_to_end_id": "XXX",
                "account_servicer_ref": null,
                "payment_invocation_id": null,
                "instruction_id": null,
                "mandate_id": null,
                "cheque_number": null,
                "clearing_system_ref": null
            },
            "entry_ref": "XXX-REF-4",
            "amount": "400.00",
            "currency": "CZK",
            "val_date": "2023-03-08",
            "remote_info": "description",
            "additional_transaction_info": "RECIPIENT NAME",
            "related_account_id": {
                "iban": null,
                "id": "XXX-OTHER-ACC"
            },
            "related_account_bank_id": {
                "bic": null,
                "id": "XXX-OTHER-BANK"
            }
        },
        {
            "ref": {
                "message_id": "XXX",
                "end_to_end_id": "XXX",
                "account_servicer_ref": null,
                "payment_invocation_id": null,
                "instruction_id": null,
                "mandate_id": null,
                "cheque_number": null,
                "clearing_system_ref": null
            },
            "entry_ref": "XXX-REF-5",
            "amount": "-100.00",
            "currency": "CZK",
            "val_date": "2023-03-31",
            "remote_info": "transaction description",
            "additional_transaction_info": null,
            "related_account_id": null,
            "related_account_bank_id": null
        },
        {
            "ref": {
                "message_id": "XXX",
                "end_to_end_id": null,
                "account_servicer_ref": null,
                "payment_invocation_id": null,
                "instruction_id": null,
                "mandate_id": null,
                "cheque_number": null,
                "clearing_system_ref": null
            },
            "entry_ref": "XXX-REF-6",
            "amount": "1000.00",
            "currency": "CZK",
            "val_date": "2023-03-07",
            "remote_info": null,
            "additional_transaction_info": null,
            "related_account_id": {
                "iban": "LT6632xxxxxx",
                "id": null
            },
            "related_account_bank_id": {
                "bic": "REVOLT21",
                "id": null
            }
        }
    ]
}

License

MIT – see LICENSE.txt.

Changelog

0.3.0

• Refactored code into a package (it should not break most callers)
• Upgraded dependencies (works with Pandas 2.x or 3.x, lxml 5.x or 6.x)
• Added support for Python 3.13, 3.14; removed support for Python 3.10, 3.11
• Switched project management from Poetry to uv

0.2.0

• Added AccountId, BankId models to handle IBAN/BIC codes
• Added TransactionRef model to store transaction references, eg. end-to-end reference
• Pandas integration: BankToCustomerStatement.as_dataframe()
• Pandas integration: okane CLI tool can merge multiple input XMLs into one CSV/XLSX
• Upgraded Pydantic version from 1.10 to 2.5

0.1.0

• Initial release