[A-Z]{1,16}(\/\d{1,6})
asset in your ledger transactions, it is encouraged to always use UMN, especially if you’re dealing with any of the standardized ISO-4217 currencies.
ASSET
is a string of 1 to 16 uppercase letters, representing the currency code of the asset, either standardized or fictional.SCALE
represents the negative power of ten to multiply the amount with to obtain the decimal value in the given assetAMOUNT
is an unsigned integer.[USD/2 30]
is equivalent to USD 30*1E-2
, i.e USD 0.30
, i.e 30 USD cents.
[JPY 100]
.UMN | Human Readable | ISO-4217 code |
---|---|---|
[USD/2 30] | $0.30 | USD |
[JPY 100] | ¥100 | JPY |
[BTC/8 100000000] | 1 BTC | BTC |
[GBP/2 100] | £1.00 | GBP |
[EUR/2 100] | €1.00 | EUR |
[INR/2 100] | ₹1.00 | INR |
[CNY/2 100] | ¥1.00 | CNY |
[CAD/2 100] | CA$1.00 | CAD |
USD/2
is a reasonable notation for most USD-handling use-cases, nothing prevents you from using USD/4
or USD/6
if you need to represent smaller amounts and subdivisions of USD in your system. The same applies to other currencies, e.g. JPY/2
or JPY/4
for Japanese Yen and while such a coin is not in circulation, it is still a valid notation when these amounts are used in a context where they will end up being floored or ceiled to the nearest whole unit later down the line.USD
is inherently ambiguous, with interpretation of the scale left as an exercise to the reader.
If you receive from a payment processor an API response as follows:
100
, and 100.30
are happily parsed, leaving the door open to catastrophic consequences.
As you start to scale your business and deal with multiple and specialized payment services providers, the risk of different formats making their way to your internal representation increases along with the risk of misinterpreting the amount.
As Formance components are designed to be used in a variety of contexts and find themselves dealing with a variety formats from different providers, we decided to explicitly specify the scale of the amount in the notation, making UMN really hard to misinterpret by design.