Fintech Engineering Handbook: Patterns for Software That Handles Money

Three principles for money systems

Voytek Pitula, an engineer whose background spans payments, accounting, controlling and treasury management for both fiat and crypto, has published the Fintech Engineering Handbook — a free reference on the patterns used when money is a system's primary focus. Three principles run through it. No invented data: idempotency, deduplication and reconciliation, so money is never created out of nowhere or duplicated. No lost data: full precision, at-least-once delivery, event sourcing, audit trails and immutability. And no trust — in external providers, internal components or the world — which is why webhooks are verified, data is cross-checked against independent sources, and broken assumptions fail loudly.

Representing money and recording it

Before money can move, it has to be represented. Pitula compares four approaches: floating-point numbers, which he calls almost never a good idea; arbitrary precision such as Java's BigDecimal for chained calculations; integer minor units, whose number of digits comes from ISO 4217 and is not always two; and rational numbers when no precision loss is acceptable. An amount should also never be serialized as a bare JSON number, since most parsers turn that into a double. Rounding is unavoidable, but it must be explicit, decided by the business, done as seldom as possible, and recorded when it breaks sums.

Recording money means a ledger: double-entry bookkeeping, the distinction between value time, booking time and settlement time, audit trails, event sourcing and immutability, plus reversals and corrections instead of edits, and the tension with data-deletion requirements.

Flows, the outside world and controls

Executing a money flow rests on invariants, funds reservation (hold-and-release, with a distinction between total and available balances), explicit handling of overdrafts — which cannot be made unrepresentable, because the outside world does not ask permission — idempotency under retries, and full resumability: flows are persisted state machines, an independent driver resumes them, and every step must be safe to re-run. On integrations, Pitula advises assuming APIs will misbehave, storing every request and response, watching quotas, and treating webhooks as hints rather than truth: verify the signature over the raw bytes, persist the payload, acknowledge fast, then query the API for the authoritative state. Reliable publishing uses the outbox pattern or change data capture; reconciliation is the safety net that catches whatever slips through. A final section covers segregation of duties and four-eyes approvals, least-privilege access with periodic reviews, and an auditable trail from code to production.

Appendices and honest limits

The appendices walk through three end-to-end flows — a crypto withdrawal of 0.5 ETH, a card deposit through a payment service provider, and an in-app conversion of 1,000 EUR into USDC with cashback — plus a reading list on accounting, payments, markets, crypto, KYC and AML. Pitula notes that most of the material was written by hand, with AI used for polishing, structuring, research and review, that the book is a living document open to feedback on GitHub, and that it is not legal or financial advice.