PROPOSAL: Use strings to represent currency and amount per ISO20022

[adrianhopebailie]

This proposal addresses the question in #40.

The ISO20022 dictionary defines a CurrencyAndAmount [1] data type for passing currencies and amounts in payment messages (as well as some updated version thereof with looser restrictions on the number of digits allowed).

In ISO20022 currencies are represented using the ISO 4217 [2] three-letter alpha code.

The decimal separator is a dot.

An example of an ISO 20022 currency and amount in XML:

<Amt>
<InstdAmt Ccy="EUR">1.00</InstdAmt>
</Amt>

PROPOSAL:

Use formatting rules for the Web Payments WG specifications as follows:

1. Amounts MUST be represented as an object.
2. The amount object MUST have at least two named properties: "currency" and "amount".
3. The value of the amount property MUST be a string consisting only of numeric digits.
4. The value of the amount property MAY contain a single dot to denote separation of the fractional suffix from the rest of the amount.
5. If present, the dot MUST NOT be the first character of the amount.
6. The value of the currency property MUST be expressed as a string of 3 characters.
7. If the currency is listed in the ISO 4217 Current Currency and Funds list the appropriate alpha currency code MUST be used.
8. If the currency is not listed in the ISO 4217 Current Currency and Funds list an appropriate and universally understood code SHOULD be used if available.

Example:

{
  "amount" : "0.12345678"
  "currency" : "XBT"
}

[1] http://www.iso20022.org/standardsrepository/public/wqt/Description/mx/dico/datatypes/_L8ZcEp0gEeOo48XfssNw8w
[2] https://en.wikipedia.org/wiki/ISO_4217

[bifurcation]

Using strings for amounts seems pretty developer-hostile. In practice, people are just going to use amount.toString().

The use of ISO 4217 codes for currencies seems like a no-brainer, though.

[adrianhopebailie]

Using strings for amounts seems pretty developer-hostile. In practice, people are just going to use amount.toString().

The alternative is fraught with issues as discussed in the original question (#40)

[adrianhopebailie]

There wasn't enough time to discuss this proposal in the 21 January meeting.
Postponed to January 28 meeting.

[adrianhopebailie]

The group resolved to adopt this format for amounts but with the following amends:

• Drop points 7 and 8 (processing instructions)
• Amend 6 to remove length restriction (and therefor allow other currency identifiers such as URLs)

RESOLVED as follows:

Use formatting rules for amounts in the Web Payments WG specifications as follows:

1. Amounts MUST be represented as an object.
2. The amount object MUST have at least two named properties: "currency" and "amount".
3. The value of the amount property MUST be a string consisting only of numeric digits.
4. The value of the amount property MAY contain a single dot to denote separation of the fractional suffix from the rest of the amount.
5. If present, the dot MUST NOT be the first character of the amount.
6. The value of the currency property MUST be expressed as a string

[vkuntz]

UNfortunately, I could not participate in the 28 Jan call.
I fully support this proposal with following comments:

• 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).

[adrianhopebailie]

@vkuntz - thanks for this additional input.
This proposal is resolved but I think as we get into the design of the specifications and messages there will be an opportunity to point out use cases where, for example, currency is not required.
We have good guidelines to work from now so this is one less issue of contention in developing the specs 😄