Fintech Engineering Handbook

Patterns for building software that handles money Welcome to the Fintech Engineering Handbook. This resource aims to describe the most important patterns used in software engineering, where money is the primary focus of the system. It can be read in full to get a comprehensive understanding or in parts when dealing with a particular problem. It’s meant as a living document and contributions are welcomed. Everything you will read below is a way to adhere to the three principles: Before you can move or record money, you have to represent it. These are the decisions about how a monetary value is modeled, stored, computed and converted. Getting them wrong means every layer above inherits the error. Money representation is one of the most fundamental decisions in financial systems. There are four primary ways to do it: Selecting one or the other depends on the class of the system and its responsibilities. There is no rule of thumb here, other than not using floating points. These representations are not mutually exclusive either - how you store an amount and how you compute with it are separate decisions, and a system often combines them, e.g. integer storage with BigDecimal for intermediate computation. The same care applies when an amount is being serialized. A bare JSON number is an IEEE-754 double in most parsers, so serializing money as a number reintroduces the floating-point problem at the edge, no matter how carefully you represent it internally. Send money either as a string ("12.34") or as an integer in its smallest unit. Money can’t be represented as a number alone - it comes paired with a currency. There are a few nuances when it comes to handling currencies. FX (Forex, foreign exchange currency market) rates allow us to convert money between currencies. Once represented, money movements have to be recorded in a way that balances, survives audit and can be reconstructed years later. This is where the books, their timestamps and their history live. Double-entry bookkeeping is a widely used way to store financial transactions as a list of entries in the form of (credit account, debit account, amount) (this is a compact form; the classic representation uses a separate debit and credit row per movement). Because every entry moves the same amount out of one account and into another, the books always balance - money is only moved, never created or destroyed. Transactions will usually have at least two, sometimes three timestamps associated: The first two will almost always diverge: Example: a card payment happened at T1 (value time), you recorded it at T2 (booking time), but the payment provider transferred money to your account at T3 (settlement time). Business and business-consumed reports usually care about value or settlement time, while booking time is useful for traceability. Financial systems are subject to regulatory scrutiny in the form of various audits. Some of the things that might be verified during an audit: To answer those and many other questions, financial systems have to keep track of not only the current state but the full history of how that state came to be. This history is the audit trail: a record of everything that happened, detailed enough that any balance, report or decision can be explained and reproduced from it. A useful audit trail captures, for every change: Money movements are the obvious subject, but manual interventions, configuration changes (fee schedules, rate sources, limits) and permission changes need trails too. The why is often itself the output of a decision (e.g. a compliance check or risk score). Recording just the outcome (“blocked”) rarely satisfies an audit because you’ll be asked how that outcome was reached. If that logic lives in a decision table or a rules engine (DMN, Drools, Decisions4s) instead of being buried in imperative code, the decision becomes a structured, replayable artifact that says which rules fired, on which inputs, with what result. Event sourcing is probably the most principled and systemic approach to building an audit trail. In ES, instead of storing current state with a log next to it, you store only the events and derive state from them. The double-entry ledger is an example of this pattern applied to money - balance is never stored, it is calculated from the stored entries. With this approach the trail is a primary artifact and cannot drift away from reality. In other words: event sourcing is a very good solution when an audit trail is required, but it comes with a very high price in terms of system complexity. An audit trail that can be edited proves nothing, hence records can never be updated or deleted. Our log must be append-only, and every correction should be a new record (see below). Immutability is an invariant, and the usual toolbox applies: When building a real system bugs are unavoidable and might require you to fix the event log/audit trail. In those cases it’s sometimes easier to update the trai

Fintech Engineering Handbook

Key takeaways

More in computer-science