Cheat sheet · Business processes
Money and rounding
The problem
A shop sells in so'm and issues e-invoices with 12% VAT. With prices as floating-point numbers, a payment of exactly the right amount fails an equality check. Amounts become integers in minor units with a currency, and then the real questions start: which rounding rule, where to round (per line or per invoice), how to split an amount without losing a tiyin, how to convert at a rate you can still prove a week later, and why formatting belongs only at the very edge.
What you learn
- Why binary floating point cannot hold 0.1 or 19 990.10 exactly, and how integer minor units with a currency fix it (currencies with 0, 2 and 3 decimals)
- Rounding modes: half-up, half-even (banker's) and the asymmetric Math.round, and why the rule is a business decision written down once
- Rounding per line versus per invoice: a 1-tiyin VAT difference, and the rule that totals are sums of the lines as printed
- Splitting an amount with the largest remainder method, converting currency with a stored rate and timestamp, and formatting per locale at the edge
Diagram as code
The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.
Mermaid: flowchart
flowchart LR
n_app(["Checkout"])
n_api["Order service"]
n_db[("Orders DB")]
n_tax>"E-invoice system"]
n_fx>"Rates provider"]
n_app -->|"call"| n_api
n_api --> n_db
n_api -->|"async"| n_tax
n_api -->|"call"| n_fxMermaid: request sequence
sequenceDiagram
participant n_app as Checkout
participant n_api as Order service
participant n_db as Orders DB
participant n_tax as E-invoice system
participant n_fx as Rates provider
Note over n_app,n_api: An order with prices as plain numbers
n_app->>n_api: POST /v1/orders HTTP/1.1
n_api-->>n_app: HTTP/1.1 201 Created
Note over n_app,n_api: The right payment does not match the total
n_app->>n_api: #62; 19990.1 * 3
Note over n_app,n_api: Store integers of the smallest unit
n_app->>n_api: POST /v1/orders HTTP/1.1
n_api-->>n_app: currency exponent 1 unit =
Note over n_api,n_db: Rounding modes: what happens at exactly half
n_api->>n_db: 1.5% fee on 10 003.00 so'm = 15 004.5 tiyin
Note over n_api,n_tax: The VAT of the lines does not add up to the total
n_api->>n_tax: invoice INV-2026-11-04417 VAT 12%
n_tax-->>n_api: rejected: total VAT 10 660.71 != sum of line VAT 10 660.72
Note over n_api,n_tax: Round once per line, sum what you stored
n_api->>n_tax: POST /v1/invoices INV-2026-11-04417
n_tax-->>n_api: accepted INV-2026-11-04417
Note over n_api,n_db: Three installments, one tiyin missing
n_api->>n_db: installments: 100 000.00 so'm in 3 months = 10 000 000 tiyin / 3
Note over n_api,n_db: Allocate the remainder, largest first
n_api->>n_db: allocate a 5 000.00 so'm discount (500 000 tiyin) by line net
Note over n_api,n_fx: A refund at today's rate
n_api->>n_fx: order o_8120 49.99 USD, paid in UZS on 2026-11-09
Note over n_api,n_db: Store the rate, its source and time with the conversion
n_api->>n_db: INSERT INTO conversions (order o_8120)
n_db-->>n_api: 4999 x 1268743 / 100 = 63 424 462.57 -#62; 63 424 463 tiyin
Note over n_app,n_api: Format only at the edge, per locale
n_app->>n_api: stored: minor 63424463, currency UZSD2
direction: right
n_app: "Checkout" {
shape: rectangle
}
n_api: "Order service" {
shape: rectangle
}
n_db: "Orders DB" {
shape: cylinder
}
n_tax: "E-invoice system" {
shape: cloud
}
n_fx: "Rates provider" {
shape: cloud
}
n_app -> n_api: "call"
n_api -> n_db
n_api -> n_tax: "async"
n_api -> n_fx: "call"PlantUML: request sequence
@startuml
participant "Checkout" as n_app
participant "Order service" as n_api
database "Orders DB" as n_db
boundary "E-invoice system" as n_tax
boundary "Rates provider" as n_fx
note over n_app, n_api : An order with prices as plain numbers
n_app -> n_api : POST /v1/orders HTTP/1.1
n_api --> n_app : HTTP/1.1 201 Created
note over n_app, n_api : The right payment does not match the total
n_app -> n_api : > 19990.1 * 3
note over n_app, n_api : Store integers of the smallest unit
n_app -> n_api : POST /v1/orders HTTP/1.1
n_api --> n_app : currency exponent 1 unit =
note over n_api, n_db : Rounding modes: what happens at exactly half
n_api -> n_db : 1.5% fee on 10 003.00 so'm = 15 004.5 tiyin
note over n_api, n_tax : The VAT of the lines does not add up to the total
n_api ->> n_tax : invoice INV-2026-11-04417 VAT 12%
n_tax -->> n_api : rejected: total VAT 10 660.71 != sum of line VAT 10 660.72
note over n_api, n_tax : Round once per line, sum what you stored
n_api ->> n_tax : POST /v1/invoices INV-2026-11-04417
n_tax -->> n_api : accepted INV-2026-11-04417
note over n_api, n_db : Three installments, one tiyin missing
n_api -> n_db : installments: 100 000.00 so'm in 3 months = 10 000 000 tiyin / 3
note over n_api, n_db : Allocate the remainder, largest first
n_api -> n_db : allocate a 5 000.00 so'm discount (500 000 tiyin) by line net
note over n_api, n_fx : A refund at today's rate
n_api -> n_fx : order o_8120 49.99 USD, paid in UZS on 2026-11-09
note over n_api, n_db : Store the rate, its source and time with the conversion
n_api -> n_db : INSERT INTO conversions (order o_8120)
n_db --> n_api : 4999 x 1268743 / 100 = 63 424 462.57 -> 63 424 463 tiyin
note over n_app, n_api : Format only at the edge, per locale
n_app -> n_api : stored: minor 63424463, currency UZS
@endumlPlantUML: components
@startuml
left to right direction
agent "Checkout" as n_app
component "Order service" as n_api
database "Orders DB" as n_db
cloud "E-invoice system" as n_tax
cloud "Rates provider" as n_fx
n_app --> n_api : call
n_api --> n_db
n_api --> n_tax : async
n_api --> n_fx : call
@endumlRecap
Seven rules for money.
1) Never floats: integers in minor units, always with a currency. 2) Decimals come from the currency table: 0, 2 or 3. 3) Choose the rounding mode by rule and use one function with an explicit mode. 4) Round in one defined place, store the rounded amounts, and make totals the sums of what was stored. 5) Split with allocation, so the parts always add up. 6) Store every conversion with its rate, source and time, and reuse it for refunds. 7) Format per locale only in the app.
Numbers: at the start and at the end
| Metric | Start | End |
|---|---|---|
| Difference, tiyin | 0 | 0 |
| Mismatched documents | 0/day | 0/day |
| Refund shortfall, tiyin | 0 | 0 |
Steps
- Case An order with prices as plain numbers
The checkout sends an order: three packs of tea at 19 990.10 so'm.
- Problem The right payment does not match the total
In binary floating point, 19 990.10 is stored as the nearest binary fraction, which is a little off.
- Fix Store integers of the smallest unit
Every amount is now an integer number of minor units plus a currency: 1 999 010 tiyin of UZS.
- Fix Rounding modes: what happens at exactly half
Integers do not remove rounding: a 1.5% fee on 10 003.00 so'm is 15 004.5 tiyin, and only whole tiyin can be charged.
- Problem The VAT of the lines does not add up to the total
An invoice has three lines.
- Fix Round once per line, sum what you stored
The rule is now: VAT is rounded per line, half-up, when the line is created, and stored.
- Problem Three installments, one tiyin missing
A customer pays 100 000.00 so'm in 3 monthly installments.
- Fix Allocate the remainder, largest first
Allocation splits an amount by weights so that the parts always add up.
- Problem A refund at today's rate
A product is priced at 49.99 USD and the customer pays in so'm.
- Fix Store the rate, its source and time with the conversion
Every conversion is now a record: the original amount, the rate as an exact decimal, where it came from and when, the converted amount and the rounding mode.
- Fix Format only at the edge, per locale
The database, the APIs and the logs keep minor units and a currency.
- Recap Recap
Seven rules for money.
Terms
- Floating-point error
- A binary double cannot store decimal fractions such as 0.1 exactly, so 0.1 + 0.2 gives 0.30000000000000004. Money uses integers or a decimal type instead.
- Rounding mode
- The rule for a value exactly halfway: half-up sends the half away from zero, half-even (banker's rounding) to the even neighbour. Law or contract decides which one applies.
- Largest remainder method
- A way to split an amount: every part gets its share rounded down, and the leftover minor units go one each to the parts with the largest remainders, so the parts always add up.
- Stored exchange rate
- The rate recorded with a conversion, together with its source, time and rounding mode. Refunds and audits use these numbers instead of fetching the rate again.