Expression of monetary amounts

[msporny]

The paymentRequest API currently suggests that we express monetary amounts using a mantissa and exponent:

http://wicg.github.io/paymentrequest/specs/paymentrequest.html#currencyamount

"amount": { "currencyCode": "USD", "mantissa": 5500, "exponent": 2 }, // US$55.00

The Web Payments CG Browser API suggests that we use strings for the amounts with a currency code:

http://wicg.github.io/web-payments-browser-api/#processing-a-payment-request

transfer: {
  amount: '4.35',
  currency: 'USD'
},

How should monetary amounts be expressed in the API?

[msporny]

How should monetary amounts be expressed in the API?

Expressing monetary amounts using a mantissa and exponent is going to feel foreign to most Web developers. I couldn't find a popular API that uses mantissa and exponent.

[adrianhopebailie]

There should be enough payment related APIs already in wide use for us to establish the "standard" way of expressing amounts. Any volunteers to do this research and come back with findings?

[dlongley]

The use of mantissa is likely to confuse some people. Sometimes it is used interchangeably with significand by computer scientists when talking about floating point numbers, but with respect to mathematics, it is understood to be the fractional component of a number:

For example, for x=3.14159, the mantissa is 0.14159.

Furthermore, using significand does not remove the possibility that people will try to use decimal points in its value. I realize the IDL has specified that it is a long long, however, as it is perfectly valid to use a decimal point in a significand; I can see people trying to use one. As one other point, perhaps we're not concerned about values this large (or small), but we could start seeing problems with JSON parsers if we're using numbers and not strings for precise values.

In my view, it would be better to just use a string that represents an arbitrary precision number that may contain a decimal point.

[davidlehn]

Also see: https://github.com/WICG/paymentrequest/issues/18

[dezell]

I'm 100% in agreement with dlongley's comment above - use a string that represents an arbitrary precision...

If we want to constrain the string in our spec, we could consider using a RegEx (in the spec) to be unequivocal.
See: http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#decimal
i.e. (+|-)?([0-9]+(.[0-9]*)?|.[0-9]+)

Or something simpler :-).

Discussion of binary formats (long, double, etc.) is a very slippery slope.

[adrianhopebailie]

The standard for dealing with amounts in older payment protocols such as ISO8583 is to always use the minor currency and express amounts as integers.

One may argue this is not very developer friendly but it has worked for the card industry for a few decades. Is this a viable solution?

See the following related issues for the paymentRequest proposal:

• https://github.com/WICG/paymentrequest/issues/18
• https://github.com/WICG/paymentrequest/issues/39
• https://github.com/WICG/paymentrequest/issues/40

[dlongley]

@adrianhopebailie,

One may argue this is not very developer friendly but it has worked for the card industry for a few decades. Is this a viable solution?

I think using a JSON number (which is how an integer would be represented) is problematic; different parsers may interpret certain values in different ways. In my view, the best way to protect integrity (with respect to parsing) is to use a string. Whether we express the value using the minor currency is another matter -- but I do think that if we use a currency code such as "USD", people will be confused if the amount is meant to be interpreted as cents.

[adrianhopebailie]

different parsers may interpret certain values in different ways

I'm not sure how this could be true. Do different JSON parsers interpret integers differently? There is no precision problem that I foresee or am I missing the obvious?

but I do think that if we use a currency code such as "USD", people will be confused if the amount is meant to be interpreted as cents

Developers using ISO8583 have managed for some decades as I say. There is a finite set of global currencies and knowing how to convert them from minor currency to a decimal if required is pretty easy to accomplish. Any new currencies like Bitcoin have to define what their minimum unit of account is and anyone using that currency can fairly be expected to need to know that.

This approach's appeal is in it's simplicity and yet interoperability and flexibility.

[dlongley]

I'm not sure how this could be true. Do different JSON parsers interpret integers differently?

If they are large enough, sure.

node.js/Chrome/Firefox:

console.log(JSON.parse('{"key": 123456789123456789}').key);

Result:

123456789123456780

Python:

import json
print(json.loads('{"key": 123456789123456789}')['key'])

Result:

123456789123456789

PHP:

<?php
echo json_decode('{"key": 123456789123456789}')->key;
?>

Result:

123456789123456789

Increase the number enough and Python will work just fine but PHP with start throwing integer overflow errors. I didn't test any other parsers. I think we should serialize these numbers in a way that is guaranteed not to lose any precision. We could declare "X bits should be enough for any currency" or we could use a string and avoid that (potentially incorrect) assumption.

Developers using ISO8583 have managed for some decades as I say.

Will they be the only developers using this new API?

[davidlehn]

Developers using ISO8583 have managed for some decades as I say. There is a finite set of global currencies and knowing how to convert them from minor currency to a decimal if required is pretty easy to accomplish. Any new currencies like Bitcoin have to define what their minimum unit of account is and anyone using that currency can fairly be expected to need to know that.

Can ISO8583 support payments with a fractional part of the standard minimum unit of account? For instance USD $0.0005 or USD $1.005. Such a feature would be useful for micropayments or other exact precision payments. This may not be a common use case, but would be nice to to make it possible at the protocol level.

[mattsaxon]

I would suggest using ISO20022 instead of ISO8583 as 20022 is newer. Currencies should be defined using ISO4217.

See http://www.iso20022.org/standardsrepository/public/wqt/Description/mx/dico/rules/_YYB_8dp-Ed-ak6NoX_4Aeg_1337619430

ISO20022 differentiates between a fractional digit portion and further states that the separator is a dot (addressing concerns of non standard separators somewhat)

So in short, a string type, using a dot as the separator would be compliant and I would support this approach from both a standardisation and an ease of use perspective.

One complication is that is doesn't appear to allow micro-payments as ISO20022 states the "number of fractional digits must comply with ISO 4217". This implies to me that, for example in USD an amount of "100.001" would be non-compliant as the fractional part is smaller that the ISO4217 exponent for USD which is 2.

Furthermore ISO20022 states the fractional part can only be 5 digits, so even if we relaxed the ISO4217 limitation, the smallest micro-payment that could be made would be "0.00001" or 1/1000th of a cent if using USD as the currency.

I'm not expert on these standards, so would appreciate Vincent or Kris's view of my interpretation of the standards and how they might feel about some revisions to them to support micro-payments.

[vkuntz]

I fully support the proposal from Matt to use ISO 20022 instead of ISO 8583, for 2 reasons: ISO 8583 is cards industry specific and does not support all payments flows and the cards industry in Europe is in the process to convert all existing ISO 8583 messages to ISO 20022: several sets of messages have already been converted and published as ISO 20022 messages.

Coming back to the question from Matt on the fractional digits, ISO 20022 provides for some flexibility. The CurrencyAmount is actually the validation rule of the CurrencyAndAmount, which is the "normal" data type used for in most of the ISO 20022 Payments messages, and follows the ISO 4217 standards on currencies.
However, exceptions may be defined and implemented, when justified by the underlying business requirements, the number of fractional digits may be extended, such as the CurrencyAnd30Amount: http://www.iso20022.org/standardsrepository/public/wqt/Description/mx/dico/datatypes/_L8ZcEp0gEeOo48XfssNw8w, which does not validate the number of digits against ISO 4217. This is currently used in corporate action events, where the split of stocks may results in up to 10 fractional digits.

Finally I fully support the use of the dot, only to ensure the interoperability with ISO 20022.

[adrianhopebailie]

Closing as the related proposal was resolved on 28 Jan.

Note the following comments from @vkuntz as we develop our specs:

• In some implementations of Payments messages, the currency is implied through the system currency, which defines the default currency for all exchanges, therefore the currency should be an attribute, but not mandated (e.g. the ECB only allows for Euros in the payments settlement on the TARGET2 platform, and the exchanged messages do nto contain any currencies).
• The implementation of the ISO 20022 Currency And Amount allows as well for Active or ActiveOrHistoric currencies, when used - for web payments I would strongly recommend that only Active currencies are used (i.e. USD, EUR, but no DEM, FRF which are still defined, but as non active historic currencies)
• Amounts in ISO 20022 do not provide for negative amounts, and require that an additional attribute is provided, such as the Debit/Credit indicator (mostly used in payments) or a sign (only in securities transactions).