By ByteBot
A free guide to building trustworthy money systems just landed on Hacker News front page with 518 upvotes and 166 comments. The Fintech Engineering Handbook, published by Voytek Pituła—a Staff Engineer at SwissBorg who spent six years building production financial infrastructure—covers the patterns most developers only learn after something goes catastrophically wrong. Idempotency at scale. Double-entry bookkeeping. Reconciliation when your provider sends duplicate webhooks. These are not niche fintech problems. They are the problems every engineer hits the first time they build billing, payments, or anything that moves money.
The Gap That Costs Teams Real Money
Computer science curricula skip financial engineering entirely. REST API tutorials don’t cover idempotency for payment flows. ORM docs never mention that every financial transaction has three distinct timestamps—value time (when it occurred), booking time (when you recorded it), and settlement time (when the money actually moved, typically expressed as T+2 or T+3). Those three timestamps diverge constantly, and not tracking all of them creates the kind of reconciliation nightmares that consume entire engineering sprints.
The handbook frames everything around three principles: no invented data (idempotency and deduplication prevent duplicate charges from creating money from nowhere), no lost data (event sourcing and immutable audit trails prevent movements from disappearing), and no trust (webhooks and external APIs must be independently verified, never treated as ground truth). These principles map directly to production bugs. The duplicate webhook that charged a customer twice. The float precision drift that miscalculated interest for three years. The overwritten ledger entry that made reconciliation impossible.
The Float Debate the Fintech Engineering Handbook Sparked
The handbook’s position that floating-point arithmetic is inadvisable for financial data sparked the liveliest argument in those 166 Hacker News comments, and the argument is worth having. The issue is real: 0.1 + 0.2 equals 0.30000000000000004 in JavaScript. When that’s a dollar amount processed ten thousand times, accumulated error becomes a real balance discrepancy.
The handbook’s recommendation is to store amounts as integers in minor units—$12.34 becomes 1234 cents—and never serialize money as a bare JSON number, which gets silently converted to an IEEE-754 double in transit. Modern Treasury’s documentation makes the same case: integers eliminate an entire class of precision bugs at the storage layer.
However, the experienced engineers in the HN thread pushed back, and they’re not wrong. High-frequency trading and quantitative finance run on doubles and do so correctly, because those domains explicitly model and accept numerical drift. Evan Jones’s counterargument remains valid: if you round correctly at every boundary, floating-point works for financial calculations within realistic value ranges. A derivative pricing model is not a bank ledger. The actual rule is not “never use floats for money”—it’s know which domain you’re in, and apply the convention that fits. Most developers building SaaS billing or payment integrations are firmly in the integers camp.
Three Patterns Engineers Most Often Get Wrong
Idempotency is the pattern developers think they understand and don’t. The naive implementation—check if a record exists, then insert if not—fails at scale because the check and the insert are not atomic. The handbook advocates for explicit idempotency keys that are atomically deduplicated, with specific handling for out-of-order retries, because operations must stay idempotent even after state has moved forward. Testing for this matters too: middleware that automatically retries calls will expose broken implementations that slip past manual testing.
Reconciliation gets skipped or treated as an optional audit step. It isn’t. Webhooks from payment providers arrive out of order, get delayed, or fire twice for the same event. Treating a webhook payload as authoritative truth is how you build systems that slowly drift from reality. An independent reconciliation job that compares your ledger against the provider’s actual state—run hourly or nightly depending on your settlement cadence—is the only reliable ground truth.
Reversals and corrections expose a conceptual mistake developers make constantly: overwriting incorrect ledger entries. In an immutable ledger, you never overwrite. A wrong entry gets a compensating entry that nets it out. Both the original and the correction remain in the history. This is not bureaucratic pedantry—it’s the only way to preserve an audit trail that’s genuinely trustworthy. An audit trail you can edit is not an audit trail.
Why This Resource Matters Right Now
Embedded finance has been accelerating for two years. Non-fintech companies are integrating payment rails, credit, and ledger functionality directly into their products rather than delegating everything to third-party SaaS. AI agents are increasingly processing billing events and financial workflows autonomously—which means the bugs in financial logic are no longer caught by a human reviewing a screen before a transaction commits. The handbook’s emphasis on post-factum verification—nightly reconciliation jobs that catch what slipped through runtime checks—is more relevant now than when most of this was handled manually. If you’re working on billing for a SaaS product, you should also read our coverage of GitHub Copilot’s token billing switch to see these patterns in a concrete commercial context.
The handbook is free, lives on the web, and is organized as a living document with a glossary covering everything from T+X settlement to omnibus accounts to chargeback mechanics. If you build anything that touches money—billing, subscriptions, marketplace payouts, payment integrations—read it before writing the next line of code. The HN discussion is worth reading alongside it, particularly for the float debate and the compliance caveats from engineers who’ve shipped these systems at scale.
