Feat: Introducing new Data Classes for CAMT XML transactions

[lukas-staab]

Hey there,

i did some work on the xml GetStatement Action and noticed some issues with the translation from CAMT to the MT940 Statements

Here is some of the friction:

• In CAMT balances are positional, not typed. A MT940 Statement has exactly two, startBalance and endBalance. A CAMT report carries a set of balances that each say what they are (Anfangs-, End-, Zwischensaldo, verfügbarer Saldo, Vortagessaldo).
  There is no slot for a balance's type and no room for a third one.
  • What that costs in practice: the model wants a start and an end balance per day, but CAMT only gives balances per report, so the parser has to invent the missing ones - and today it gives every day the same figure. A report opening at 1000 with booked entries +100 / -50 / +100 comes out as 1000 -> 1000 on all three days instead of 1000 -> 1100 -> 1050 -> 1150. MT 940 never had that problem, it ships a matching 60F/62F pair per statement. Computing the chain is possible, but we would need to invest some code into it that we are not bitten by float calc issues, this could be fixed by the php Money pattern, there are multiple libs which implement it, we could also do it ourselves if need be.
• The container is a list of day buckets. StatementOfAccount → Statement[] keyed by date bakes MT 940's day-statement structure into the top level, so an intraday report has to be bucketed even though it isn't organised by day.
• There is currency in CAMT. Right now we dont have it. Amounts are bare floats on both Statement and Transaction. This might call for a php Money libary as well, if we would want to adress that. (low prio?)
• MT Transaction is flat, CAMT entries are two-level. One amount, one counterparty per transaction — a Sammelbuchung with N items has nowhere to put the items, only the total -> loss of information
• MT booked is a boolean where CAMT has three states (gebucht / vorgemerkt / nur Information).
• The description slots are MT 940 shapes with MT 940 meanings: a numeric GVC, a text key, two free-text lines, and an array keyed by :86 tags. CAMT's equivalents are a four-part ISO code and typed reference fields. They get squeezed
  into the same slots — and nothing on the object records which format filled them, so a consumer can't tell how to read getBookingCode().
• Slots that only one format can fill, and gaps for the other. primanoten_nr and text_key_addition are dead for CAMT; the bank's plain-text entry info, charges, exchange rate, return reason and batch metadata have no slot at all.
• In Statements everything is settable. It's a mutable bag rather than a value object, so nothing keeps a statement internally consistent (e.g. readonly properties come with php8.1)

imho the biggest loose right now as is are the Sammelbuchungen and the Balances. IMHO raising the codebase to 8.1 first would be beneficial before doing this change, because we could use enums, and readonly properties.

btw: https://github.com/genkgo/camt could be a strong contender if we dont want to maintain camt parsing ourselves. It picked moneyphp/money as its money lib

[john-frandsen]

The balance chain doesn't have to be invented — CAMT does type its balances, the current model just has no slot for the type. Every <Bal> carries a code (OPBD opening booked, CLBD closing booked, ITBD interim-booked, CLAV closing available, PRCD previous-day close). Parse them into a typed list, then derive the per-day start/end pair as a fold: day-start = OPBD or previous day-end, apply booked entries grouped by their BookgDt/Dt, day-end = running total. That way the MT940-shaped StatementOfAccount becomes a projection you keep for BC, and the native model can be what CAMT actually ships — Report[] with typed balances + entries — which dissolves the day-bucket problem for intraday reports instead of papering over it.

Things worth deciding early, having lived this with PSD2 statement feeds:

• Pick one date that drives the chain (booking date) and carry ValDt as an attribute only. Entries whose booking date differs from the report date are exactly the ones that leave a reconstructed balance off by "one weird transaction", and banks do send them.
• On money: skip float, and skip hand-rolled cents too. Parse the <Amt> decimal string straight into integer minor units using the currency's exponent (JPY = 0, BHD = 3) and keep {amount, currency} as a value object — brick/money or moneyphp/money both work, or it's ~30 lines to do yourself. Since CAMT stamps every amount with Ccy, the value object fixes the missing-currency point for free.
• Carry a status on entries from day one (<Ntry>/<Sts> BOOK vs PDNG). German FinTS banks mostly send booked-only, but PSD2-direct CAMT feeds mix booked and pending, and retrofitting a status onto a model where everything was assumed booked is painful — you end up re-touching every consumer.

(Disclosure: I build open-banking.io, a PSD2 account-data API — following this because CAMT/MT940 normalization is the same problem we solve daily.)