Payment Systems

Payment bugs are paid for in real money, and every one is a security bug. Design for three facts:

1. Networks fail in the middle. A timeout means unknown, not failed.
2. Everything is delivered at least once. Requests, webhooks, and events all repeat.
3. Every movement must be explainable later, to customers, auditors, and reconciliation.

Regulatory rules vary by country and licence (in Vietnam, the State Bank of Vietnam). Confirm them with the compliance team; this skill covers engineering, not legal advice.

Money

• Store integer minor units plus an ISO 4217 currency: amount_minor BIGINT, currency CHAR(3). The exponent varies (VND 0, USD 2, KWD 3), so read it from a currency table instead of assuming 2.
• Never use binary floating point. In Java use long minor units or BigDecimal with an explicit scale and RoundingMode. Never use new BigDecimal(double).
• Define a rounding rule for each calculation (fees, FX, tax, interest) and where the remainder goes. When splitting, allocate the remainder deterministically (largest remainder), so the parts always sum to the whole.
• An FX conversion is two ledger legs with a recorded rate, rate source, and timestamp, not a currency change on one row.

State Machine