This document describes in example form the XML-based instructions to achieve payments and other requests to web-based accounting systems.
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. There are two major use scenarios for XML-X, being
For the first usage, the merchant scenario, only the transfer request is strictly necessary. This request is the described in this document. Merchants will be interested in other requests, such as History/Balance requests, which are described in the longer Core XML-X Requests.
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.
The benefit will be obtained when merchants only have to implement one and only one interface method to access many different web based accounting systems. As the cost of implementing methods is very high, no merchant implements more than a few of the available systems. By implementing XML-X as a standard interface, any given web based accounting system can quickly acquire many merchants, thus ensuring the success of both the system and the merchant.
The basic process is to send the <Transfer> to the server, wrapped in its <TransferRequest>, then receive back the <Receipt>, wrapped in its <TransferResponse>. The <Receipt> is a wrapper around the <Transfer>, which adds in the server details of time of transaction, and server's transaction id.
A <Transfer> includes all the details needed to complete the transfer, except the authentication requirements (that part is deferred to a higher layer, the request, as many possible mechanisms are possible).
<Transfer> <TransferId> P9348235 </TransferId> <Payee> E3491 </Payee> <Payer> 34201-543 </Payer> <Amount> 4523 </Amount> <CurrencyId> USD </CurrencyId> <Memo> Blahdieblah </Memo> </Transfer>
The format and content of many of the tags is open, as most systems have different ways of describing such entities as accounts and currencies. (In general, XML characters such as < and & are not permitted, and whitespace at the beginning and end of the text is stripped.)
One above that is more defined is <Amount>. In this case, the amount is defined to be in Cents, and the specification of this is derived from the <Currency>. See the more advanced documentation to see how that is done.
In response to each <Transfer>, the accounting server returns a <Receipt> that includes the entire contents of the <Transfer>, along with the server's transaction identifier, the date/time of effect, and any signature elements.
<Receipt version="1">
<ReceiptId> R20349143 </ReceiptId> <!-- server's Id -->
<Time> 12345678901234567 </Time> <!-- win32 time -->
<Transfer> all of the above </Transfer>
<UserId> Erwin </UserId>
<Signature type="DSA">
Blob
</Signature>
</Receipt>
The reasons for returning the entire <Transfer>, encapsulated in the <Receipt> include,
The authenticating user is recorded in <UserId>.
Having defined the contents of the transaction, we can wrap that up in a request and receive the return message from the server.
<TransferRequest> <Transfer> all of the above </Transfer> <Auth> one of the below </Auth> </TransferRequest> <TransferResponse> <Receipt> All of the above </Receipt> </TransferResponse>
The intent is to achieve a single request - response cycle to achieve a payment. In order to assist matching up a response to a request, the client can add a request identifier in the rid attribute which the server must return in the response; this becomes useful in sessions, discussed below.
It remains to define the authentication tag. In order to authenticate a request such as that described in the <Transfer>, above, an <Auth> tag adds authentication methods. Here are some examples:
<Auth>
<UserId> Erwin </UserId>
<Password>
TestTest
</Password>
</Auth>
The <Auth> includes a <UserId> and a method of authentication. The more normal one might be the password, above, but there are other possibilities, below.
<Auth>
<UserId> Erwin </UserId>
<Signature>
Blob
</Signature>
</Auth>
<Auth>
<UserId> Erwin </UserId>
<Token>
Magic String
</Token>
</Auth>
This document does not really describe them in detail as they can vary amongst implementations. Likewise, it is assumed that the various signature types includes sufficient information to establish the credibility of claims.
Issues such as confidentiality are not dealt with at this layer, it is assumed that SSL or the like is used.
As a rule (encouraged by XML), each packet has its own request and reply. One exception to this rule is if there is an error.
On error, the server returns an <ErrorResponse> which includes an error number taken from standard list of numbers, and, optionally, a short text description and a longer help definition.
<ErrorResponse errno="666" rid="token">
<Text> Wrong Password </Text>
<Additional> Check the Postit note on your monitor </Additional>
</ErrorResponse>
Thus, the receiver needs to check the first tags coming in and determine if the matching response is being returned, or an <ErrorResponse>.
The Primary Authors of XML-X are Erwin van der Koogh and Ian Grigg. The Author of this document is Ian Grigg. See Contributors for more influences.