Multi-Currency Payments
Pathrule2 Rules • 2 Memories
Multi-currency payment systems fail when one amount is reused for pricing, customer display, processor settlement, and accounting. This bundle makes every amount currency-qualified, snapshots quoted exchange rates, preserves actual settlement evidence, isolates rounding, and reconciles gains and losses. Unlike Pricing and Plan Modeling, it governs currency conversion and money movement rather than subscription packaging or entitlement structure.
Suggested path map
Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.
/ workspace root
src/
money/
Every amount carries its currency and unit contract
Rounding belongs to named business boundaries
payments/
Snapshot quoted FX and preserve actual settlement FX
ledger/
Presentment, settlement, and functional currency stay distinct
Rules
2Every amount carries its currency and unit contract/src/moneyhighstrictMoney values are integer minor units or explicit decimal quantities paired with an ISO currency and defined rounding rule.
| 1 | A bare number is not money. Represent every amount with its currency and a documented unit contract, and never infer currency from account, locale, route, or a neighboring field. Currency exponents differ and some operations require provider-specific constraints, so one universal divide-by-100 helper is unsafe. |
| 2 | |
| 3 | - Centralize currency metadata, accepted precision, formatting, comparison, allocation, and rounding behavior. |
| 4 | - Reject arithmetic, equality, aggregation, or persistence that mixes currencies without an explicit conversion operation. |
| 5 | - Parse machine amounts independently from localized display strings and never round through binary floating point. |
| 6 | - Allocate remainders deterministically and retain which line received each smallest unit. |
| 7 | |
| 8 | Verification: Test zero-decimal and multi-decimal currencies, negative adjustments, large values, allocations, and cross-currency misuse; confirm invalid arithmetic cannot compile or execute. |
Snapshot quoted FX and preserve actual settlement FX/src/paymentshighstrictCustomer quotes and processor settlements keep separate rates, sources, timestamps, currencies, fees, and converted amounts.
| 1 | A customer-facing quote and the processor's eventual settlement conversion answer different questions. Snapshot the quote rate, source, timestamp, expiration, base and quote currencies, input amount, output amount, spread, and rounding before confirmation. Later, preserve the provider balance movement that contains the actual settlement amount and exchange rate. |
| 2 | |
| 3 | - Never recreate a past quote or settlement using the latest market rate. |
| 4 | - Define whether checkout guarantees a quoted amount, accepts movement, or charges directly in presentment currency. |
| 5 | - Keep refund currency and conversion policy explicit, including who bears rate movement and fees. |
| 6 | - Make retries reuse the accepted quote or fail clearly after expiration instead of silently repricing. |
| 7 | |
| 8 | Verification: Delay capture past quote expiry, settle at another rate, partially refund, and retry the request; confirm the customer promise and actual money movement remain separately explainable. |
Memories
2Presentment, settlement, and functional currency stay distinct/src/ledgerThe customer pays in presentment currency, the provider moves settlement currency, and accounting may report in a third functional currency.
| 1 | Name the currency role of every amount. Presentment currency defines what the customer authorized, settlement currency defines what reaches the processor or bank account, and functional or reporting currency defines how finance measures the event. These values may match, but the data model cannot rely on that coincidence. |
| 2 | |
| 3 | Post the original currency amount and its conversion evidence together, then recognize realized and unrealized differences under the approved accounting policy. Keep processor conversion fees separate from exchange gains or losses. Aggregate only after conversion at the required event date and rate source. See /src/payments for actual provider settlement evidence and /src/money for unit and rounding rules. |
Rounding belongs to named business boundaries/src/moneyConversion, tax, discount, line allocation, invoice total, and ledger posting each use an explicit rounding mode and stage.
| 1 | Rounding after every intermediate operation and rounding only at final display can produce different totals. Define the required precision, mode, and stage for price conversion, tax, discounts, prorations, line allocation, invoice totals, refunds, and ledger postings. Preserve the pre-rounded value or rational inputs where audit or later allocation needs them. |
| 2 | |
| 3 | Do not use formatting output as the source for subsequent arithmetic. When a total must equal the sum of displayed lines, allocate the remainder deterministically and record it. Treat a one-unit difference as explainable data, not permission for a floating tolerance everywhere. See /src/ledger for how rounding entries and exchange differences are classified. |
Why this pattern
Agents store bare decimals, apply today's exchange rate to historical events, or compare presentment amounts directly with settlement deposits and invent unexplained differences.
Built for Payments and finance teams charging, refunding, settling, and reporting in more than one currency.
Keeps your assistant from:
- Interpreting the same integer under two different currencies
- Recomputing historical conversions with a current rate
- Hiding processor conversion and rounding differences in revenue
- License
- Apache-2.0
- Version
- 1.0.0
- Updated
- 2026-08-25