What is the 'Fintech Engineering Handbook,' which summarizes design principles to ensure that software handling money is completely free of even a 'one-yen discrepancy'?
When handling money, it's essential to avoid duplicating transactions, not arbitrarily erasing fractional amounts, and to record transactions in a way that allows for later explanation. The ' Fintech Engineering Handbook ,' which summarizes the design principles for software that handles money, is a handbook that organizes important concepts used in the fintech field.
Fintech Engineering Handbook
The handbook is written for people who have just joined fintech, people who are already working in fintech, and people from fields outside of fintech who want to know 'what makes money handling systems different.' The author, Boytek Pitura, lists three principles that run throughout the handbook: 'Don't create non-existent money or data,' 'Don't lose information,' and 'Don't trust anything.'
For example, if two withdrawal requests for 10,000 yen are made simultaneously from an account with a balance of 10,000 yen, while general log and notification processing might suffice with a 'consistency check later' approach, systems handling money would create non-existent funds by allowing the same 10,000 yen to be used twice. If it's not possible to distinguish between a retry due to a communication interruption and a genuine desire to send money twice, the user's balance and the business's accounting records will be corrupted.
The first important thing is how to represent money. The handbook explains that floating-point numbers, such as float and double used in many programming languages, should be avoided in most cases because they introduce precision errors. Instead, it says that '12.34 euros' should be stored as the smallest unit integer, such as '1234 cents,' or arbitrary-precision types like Java's BigDecimal should be used during calculations. Furthermore, instead of just storing the amount, the amount and currency must always be treated as a pair, and operations such as directly adding yen and dollars should be prohibited.
Next, rounding becomes an issue. Transactions such as fees, interest, foreign currency exchange, and cryptocurrency conversions often result in decimal values. The decision of whether to round to the nearest whole number is not merely a matter of implementation preference; it involves business and tax considerations regarding who receives the fractional portion. Rounding should be delayed as much as possible and explicitly performed only when it reaches system boundaries such as persistence or user display.
Once you can accurately represent the amounts, the next step is to create a ledger to record the movement of money. In this handbook, double-entry bookkeeping is presented as a central pattern in software design. In double-entry bookkeeping, the source and destination of the same amount are recorded in pairs, so the total amount does not increase or decrease arbitrarily. Rather than directly rewriting the balance, the balance is calculated from the history of past transactions, which has the advantage of allowing you to track 'why the balance came to be this number' later on.
Furthermore, regarding time management, the handbook states that it is necessary to record the 'time the card payment was made,' the 'time it was recorded in the system,' and the 'time the funds actually moved' separately, because these may be different times. This is because using only one time would make it impossible to explain cases where a settlement at the end of the month is recorded in the following month, or transactions that are settled several days later.
When integrating with external services, payment providers, banks, identity verification services, blockchain nodes, etc., are beyond your control. API responses may differ from specifications, notifications from external systems called Webhooks may be delayed, or the same notification may arrive multiple times. Therefore, the handbook explains that you should not blindly trust information received from external sources, but rather verify it at the boundary, save requests and responses, and cross-reference them with other sources as needed.
The mechanism for preventing duplicate processing is also explained, specifically the concept of idempotence. Idempotence is the property that even if the same request is received multiple times, only one result is produced. In a money transfer process where a communication error occurs, it may be unclear whether the transfer was successful but the response was lost, or whether the transfer itself failed. To safely retry, it is necessary to prepare a key to identify the same operation and prevent the same key from being executed twice.
Transactions such as withdrawals and transfers are divided into multiple stages, including 'balance confirmation,' 'fund reservation,' 'identity verification and compliance checks,' 'registration with external systems,' and 'fund transfer.' Even if the server crashes midway through, the money must not go missing. The handbook explains that it is important to permanently save the progress rather than saving it in memory, to be able to resume stalled processes, and to ensure that the same process is not recorded twice even if each stage is re-executed.
Auditing and access control are also important topics. If you cannot explain afterward who changed the fee settings, who approved large withdrawals, or who deployed the code to the production environment, you cannot prove the correctness of operations even if the books are correct. The handbook also treats separation of duties, which prevents important operations from being completed by one person, the 'four eyes' principle (requiring approval from a second person), least privilege, and regular access reviews as part of systems that handle money.
The handbook also covers property-based testing, backward compatibility testing to ensure compatibility with older data formats, and testing using small, real transactions in a production environment. Since the money used in these tests is real money, it must go through standard ledger, reconciliation, and audit trail processes, rather than relying on loopholes.
The Fintech Engineering Handbook is a comprehensive document covering everything from monetary types and ledgers to idempotency, webhooks, reconciliation, access control, a glossary, and examples of cryptocurrency withdrawals and card deposits. The handbook can be read in its entirety or used to refer only to relevant sections addressing specific design challenges, serving as a map for anyone creating financially-intensive applications, showing them 'where to start.'
Related Posts:
in Software, Posted by log1d_ts