Fintech Engineering Handbook

The post is a short handbook for engineers entering fintech. It lays out common patterns for handling money safely, including integer or decimal amount types instead of floats, immutable records, idempotency keys, append-only logs, retries, webhooks, and auditability. Most readers agreed it is a solid primer for people who have not yet learned these lessons the hard way. The pushback was not that the core advice is wrong. It was that the hardest parts of fintech live in the exceptions and the interfaces. The biggest fight was over money representation. Plenty of people defended the handbook’s default stance that amounts should usually be stored as integers in a smallest unit or in decimal types, especially across databases and APIs. But experienced readers kept stressing that there is no universal internal format that survives every case. FX, crypto, stablecoins, fee calculations, fractional pricing, and partner integrations all break simplistic "just use cents" thinking. The consensus that emerged was sharper than the handbook itself: internal math can vary by use case, but boundary formats must be explicit, and rounding rules must be documented and enforced at every boundary where data is parsed, transformed, stored, or compared. JSON got special attention because its "number" type is underspecified in practice and often gets funneled through JavaScript-style double precision. Several readers argued that if you expose amounts in JSON, strings or explicit amount-plus-scale formats are often safer than naked numbers. Outside the amount-format fight, the strongest additions were operational. People called out that event sourcing is not mandatory everywhere, but append-only audit trails are. Exactly-once delivery is fantasy, effectively-once processing is the real goal. Store inbound and outbound payloads. Preserve data lineage so you can replay a past computation with the exact vendor inputs that existed at the time. And do not confuse available-balance checks with settlement certainty, especially in ACH. A few readers thought the handbook overreached on regulation-sensitive topics like separating personally identifiable information from financial history for deletion purposes, arguing that real retention and know-your-customer obligations are jurisdiction-specific and need legal review. That landed as a broader warning: this is useful engineering guidance, but fintech architecture is constrained as much by counterparties, settlement mechanics, and compliance regimes as by code.

Treat this as onboarding material, not a spec. If you build anything that moves money, lock down your amount formats, rounding rules, audit trail, and compliance assumptions at system boundaries before you write much code.