This document describes how amounts of value are described in XML-X.
This is not a reference document, nor a draft for a standard. For such documents, see the XML-X site.
The purpose of XML-X is to enable clients to deliver accounts and payment instructions to servers.
Amounts of currency or other value are often complicated. XML-X chooses a simplified path, that of Ricardo, and strongly suggests using integer amounts of the lowest order unit everywhere, and defers conversion to readable formats for other layers.
The problems of amounts are especially acute with financial transactions. XML-X delivers receipts that could be considered in a court of law.
Disputes over payments cannot be eliminated with mere code. But, they can be minimised, and they can be simplified. XML-X has a responsibility to all developers and operators to make the data as clear and as accurate and as unambiguous as possible.
The mission of this project is
to create a protocol for spend interfaces and front-end/back-end interfaces that can be the standard for all web based accounting systems.
Within the above context, a single integer amount describing the number of the lowest order units is chosen to represent all amounts.
For example, in a dollar currency, the Amount would be the number of cents.
An <Amount> includes a single integer amount.
<Amount> 1234567890 </Amount>
Amount is an integer amount.
Aliases include ...
The amount describes the number of lowest order units, such as the cent in a dollar currency.
The currency would describe how many decimal points were applicable. See <Currency> for details.
In the event that Currency is not implemented, a potential fix would be to add an attribute of dp="2" to indicate the number of decimal points to imply.
Transaction amounts can only be positive, or zero. That is, if a receipt is implied, then any negative sign would render the amount illegal. (XML-X does not implement a double entry concept in its protocol.)
All balances are generally be positive. However, there are systems that work work with negative balances, based on credit situations ("overdrafts") or on accounting failures or for minting purposes. These systems may deliver balance numbers hence:
<Total negative="true"> 987654 </Total>
The negative attribute is illegal except in the context of the <Total> within the <Balance> (or a similar case).
XML-X packet recovery code must reject anything but a positive value, except where it makes sense, as above. Servers will also be obliged to check amounts and take drastic action if such things as negative transactions are tried.
Amount is an integer amount. It may be limited in implementations to 32 bits, at least until 64 bit integers are widespread.
Motives for the choice of integer amount are discussed in this section.
Subject: [xml-api] what's in a number? 1/2
Date: Fri, 27 Sep 2002 17:32:55 -0400
From: IanG <iang@systemics.com>
To: XML API <xml-api@intertrader.com>
One of the most pervasive errors that is made
in payments is to ascribe higher powers to the
amount of a payment than it really has.
For a lot of reasons, a payment is always in
an integral amount. These reasons include,
needing to write it down simply, needing to
pass the actual value across from hand to hand,
and needing to add them up without strange
errors creeping in (a.k.a. accounting).
For such reasons, accounting is done in integers.
There is one common variant of this, which is
to list the unit of account, and a number of
smaller units: the dollar has 100 cents, for
example. We write 1234.50 when we mean 123450
cents.
People talk about dollars, but underneath the
maths (adding, subtracting) is all done in
cents. Humans are taught from a very early
age to move seamlessly between the maths of
integers and the common lingo of dollars.
(Except in those countries that eliminated the
two units. Turkish Lira for example; Italy
and Spain recently took on the boat anchor of
the Euro so they got their cents back. If not
their sense.)
Computers have the same problem, but are less
seamless, mostly because of failings in the
programming sphere to keep the two methods of
dealing in amounts carefully separated.
In Ricardo (as embodied in the Ricardian
Contract form) there are only integer amounts.
In the contract, there are a few little fields
that tell the reader (WebFunds) how to move
from maths form to display form. Literally,
how many decimal places to impose on the
integer.
In Ricardo, the rule is, there is only an
integral amount; there are only cents, and
if the user wants to see dollars displayed,
that's a GUI problem. This eliminates the
human temptation to write down 1234.55 as
a number and then "easily" read it into a
'double' or other non-integer which then
invades the code and the mind with rounding
errors and the like.
We in XML-X cannot impose the integral view on
the world (however much we'd like). The trick
then, I believe, is to come up with a middle
ground: one that suggests the best way to
deal with this, but permits flexibility so
as to accept usage by those that ... don't
have their numbers so well arranged.
And, also, we hold out the remote possibility
that we're totally and absolutely wrong and
<ahem> others are right :-)
My next post will propose a more complete way
to resolve this area. This post was just the
background.
--
iang
The Primary Authors of XML-X are Erwin van der Koogh and Ian Grigg. The Author of this document is Ian Grigg, with contributions from all the above. See Contributors for more influences.