ENGINEERING NOTE 35 / 50 · CARD
Keep quoted, billed and settlement currencies distinct
A payment can involve several currencies. Preserve each amount with its currency instead of presenting a single unlabeled number.
Published by OPEN RAMBO. The engineering patterns and pseudocode illustrate designs, not a documented product API. Numerical examples are illustrative.
Model the amounts
Store merchant-presented amount, card-billed amount and any ledger conversion separately when applicable. A currency conversion estimate at checkout is not necessarily the final settled amount. Record the source and time of an exchange quote.
Explain fees separately
A conversion fee should be distinguishable from the exchange-rate effect. Do not label every difference as a hidden merchant fee. Use the actual statement or processor evidence to explain the final difference, and label estimates as estimates.
Keep refund currency context
A refund may follow a later conversion context. Match the original transaction and report the received amount in its actual currency. Do not promise identical converted value unless the product’s documented terms support it.
Illustrative implementation
amount = {"value_minor":1000, "currency":"USD"}
converted = {"value_minor":None, "currency":"EUR", "status":"not_final"}Acceptance check
Test a quote and settlement with different currencies and a later refund. No amount should appear without a currency label.