The Fintech Engineering Handbook: A Practical Guide

A new resource titled "Fintech Engineering Handbook" has appeared on the web, aiming to codify patterns for software engineering where money is the primary focus. The handbook, authored by W. Pitula, is structured as a living document covering representation, recording, and reconciliation of monetary values. It targets three audiences: newcomers to fintech, experienced engineers needing a reference, and developers outside fintech curious about the domain.

Three Core Principles

The handbook establishes three non-negotiable principles:

  1. No invented data: Money cannot be created out of nowhere. Enforced via idempotency, deduplication, and reconciliation.
  2. No lost data: Every money movement must be tracked and persisted. Protected via full precision, at-least-once delivery, event sourcing, audit trails, and immutability.
  3. No trust: Trust neither external providers, internal components, nor the world. Enforced by verifying webhooks, cross-checking data across sources, and failing loudly on broken assumptions.

Representing Money

Precision Handling

The handbook details four ways to represent money, with a clear warning: never use floating-point. The options are:

  • Floating-point: Fast but unpredictable precision losses. Almost never a good idea.
  • Arbitrary precision: Types like Java's BigDecimal give full control. Good for intermediate computations like FX or pricing math.
  • Minor-units precision: Store amount as integer in smallest unit (e.g., €12.34 → 1234). Follows ISO 4217 (don't assume 2 digits!). For crypto, precision is per-asset (e.g., ERC-20's decimals often 18), requiring arbitrary-width integers.
  • Rational numbers: No precision loss, but slower and cannot be converted without loss.

A critical detail: when serializing money to JSON, never use a bare number (which becomes IEEE-754 double in most parsers). Send money as a string ("12.34") or as an integer in smallest unit.

Rounding Strategies

Rounding is inevitable and must be explicit. The handbook emphasizes:

  • Rounding is a business decision with legal/tax implications.
  • Round as seldom as possible; keep full precision until boundaries (persistence or display).
  • Rounding breaks sums: if a number is split and rounded, the sum of parts may not equal the original. This requires explicit handling, e.g., a rounding account.

Currency Handling

  • Always pair amount with currency in a Money newtype.
  • Prohibit cross-currency arithmetic; require explicit conversion with controlled rates.
  • Use a controlled currency set; validate at system boundaries.
  • For crypto, use (network, contract address) pairs, not just currency codes.
  • Pegged/bridged/wrapped crypto is not equivalent to the underlying.

FX Rates

  • Rates are directional: EUR/USD ≠ USD/EUR.
  • Time matters: current-time rate vs. value-date rate.
  • Two kinds: transactional rate (falls out of actual conversion) and reference rate (for valuation).
  • No canonical rate exists; always track the source.

Recording Money: The Ledger

Double-Entry Bookkeeping

Every transaction is recorded as (credit account, debit account, amount). Money always has a source and destination; external providers get dedicated accounts. Balance is never stored—derived from movements. Accounts have types: assets, liabilities, equity, income, expense. Posted entries are immutable; corrections are compensating entries.

Value Time vs. Booking Time vs. Settlement Time

Transactions have up to three timestamps:

  • Value time: when the transaction occurred.
  • Booking time: when recorded in the system.
  • Settlement time: when money actually transferred (e.g., T+2).

Backdated transactions (booking > value) are common; forward-dated (booking < value) happen with scheduled payments. Business reports care about value or settlement time; booking time is for traceability.

Audits and Audit Trails

Financial systems must answer questions like: Are company funds commingled with user funds? Are all revenues explainable? Does the company hold enough assets? The audit trail captures, for every change: what happened, when, who, why, and the before/after state. The handbook emphasizes recording all timestamps; collapsing them into a single created_at loses reconstructible information.

Why This Matters Now

Fintech is under increasing regulatory scrutiny globally. The handbook provides a shared vocabulary and patterns that prevent costly mistakes. For developers building payment systems, ledgers, or any money-handling feature, these patterns are not optional—they are the difference between a system that passes an audit and one that fails catastrophically.

Conclusion

The Fintech Engineering Handbook is a practical, no-nonsense resource. It doesn't just tell you to avoid floating-point; it explains why and gives you four alternatives. It doesn't just say "use double-entry"; it shows how to structure accounts and handle timestamps. If you work on any system that touches money, read it, bookmark it, and contribute to it.