This document describes in example form the XML-based instructions to manage users and accounts in Internet accounting systems.
Before reading this document, you should be familiar with the Core XML-X Requests which explain the model and authentication needs of all requests. Also see the XML-X site. for more precise documents.
The purpose of XML-X is to enable clients to deliver accounts and payment instructions to servers.
For more advanced usage, such as that of an internal interface between a front-end web server and a back-end accounts server, dynamic management of users and accounts is required. This document describes those additional and optional 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 Primary Authors of XML-X are Erwin van der Koogh and Ian Grigg.
Contributors and Influences include
The Author of this document is Ian Grigg, with contributions from all the above.
Parts in italics are optional at some level, for implementation, client or server.
review and tie in with Intro Core
In XML-X, there is a separation between the unit of authentication, the unit of account, and the unit of currency. That is, at the level of the protocol, users are considered to be orthogonal entities to accounts, and currencies are orthogonal to both of them. There are many-to-many mappings possible between these entities.
In each entity, there is the <Entity>, being the full description of the entity, and there is a unique identifier, <EntityId>. For example, <Currency> fully describes the nature of the value, and <CurrencyId> will uniquely define the entity <Currency>.
Each identifier is unique within the system, being the XML-X server, To some extent this is circular, as a system is defined by that group of accounts, users and currencies, for which the identifiers are guarunteed to be unique.
In order to make an entity globally unique, put the attribute system="name" into the tag. The choice of name must make it unique amongst the universe of systems. One possibility is to use the URL of the system, if that is indeed unique.
The user is the unit of authentication to accounts. When the user is created, a method of authentication is established. This method (or methods) should be used in support of each request to access the assets of the user, using the <Auth> tag.
<User>
<UserId> Mermaids </UserId>
<AuthMethods>
<PasswordMethod>
<Password> Fish for Tea </Password>
<Time> 123456789012345678 </Time>
<Memo> secure flipper exchange </Memo>
</PasswordMethod>
</AuthMethods>
<UserProfile>
<Name> Mermaid's </Name>
<FullName> Josephine Mermaid & Daughters </FullName>
<Address> 1 Finance Avenue, Atlantis </Address>
<DisplayName> Mermaid's Water Taxis </DisplayName>
<Email> Mermaids@atlantis.waterworld </Email>
</UserProfile>
<AccountId> C001D00D </AccountId>
<AccountId> WATERWORLD </AccountId>
</User>
The <User> tag consists of its <UserId>, one or more authentication methods in <AuthMethods>, a <UserProfile>, and a list of <AccountId> to which the User has access to.
Note how the characters & and ' are protected.
The <AuthMethods> includes the static authentication details that would apply to this user. The <Auth> tag provided in any request would be matched against one of the methods found within. At least one method must be in <AuthMethods> for authentication to be available.
This is an evolving area!
The <UserProfile> includes the static details that would apply to this user, but can also be changed on user request (excluding authentication information). The <UserProfile> is set in the original <CreateUserRequest>, and can be updated in a <SetUserProfileRequest>.
The optional <DisplayName> indicates the name supplied to other users on request, for example in the act of paying to that user. (It is undefined what a public request would return if there is no <DisplayName>.)
The optional <Address> is a start at fuller non-system details.
The contents of the <UserProfile> are somewhat flexible and evolving. Most tags within are optional, depending on the context.
<Address> will probably be replaced in future versions with an open XML field such as <Details>. The contents of that field would be system dependant, as it is difficult to cover non-system details in any standards document.
The list of <AccountId> indicates the Accounts to which the User has access privileges. The <AccountProfile> for each account can be acquired via a further <LookupRequest>.
Each user might access multiple accounts. For example, in a more sophisticated system, a user can add differently named accounts for different purposes (e.g. "household" and "business"). In many systems, there will only be one account per user. The mapping from users to accounts will therefore be hidden from the user themselves, but the linkage will still exist at the level of XML-X requests.
Any given account is different to the user identified within the <Auth> tag. The precise linkage is undefined in the XMLX specification, and may range from "one-user-one-account" all the way to "many-to-many" linkages that permit users to share accounts.
An account is uniquely identified in the system by the <AccountId> tag. For the details of any such account, a fuller description can be described by the <Account>:
<Account>
<AccountId> C001D00D </AccountId>
<AccountProfile>
<Name> Maint </Name>
<FullName> Maintenance & Repairs </FullName>
<DisplayName> Mermaid's Repairs </DisplayName>
</AccountProfile>
<CurrencyId> Fishbait </CurrencyId>
<CurrencyId> watermiles </CurrencyId>
</Account>
Note that the word "account" here is used in its context of the profession of accounting, as being a list of transactions. There is no implication here as to the semantics or legal status of the account referred to by any given XML-X implementation.
Accounts are further divided into subaccounts where each subaccount holds one currency. The definition of a subaccount is such that a transfer from one account to another is always between the same subaccount.
That is, when Alice transfers USD to Bob, it comes from her USD subaccount and always goes to Bob's USD subaccount.
The subaccount is specified with an additional <CurrencyId> tag. This tag might be added within a request, or within an <Account> tag to describe what currencies are handled by that account.
A Currency is fully described by the <Currency> tag. This tag includes details on displaying the Currency such as how many decimal points pertain, and what symbols to use.
<Currency>
<CurrencyId> SS0001 </CurrencyId>
<Name> Shells </Name>
<Decimal> 2 </Decimal>
<FullName> Pretty Sea Shells </FullName>
<Issuer> Neptune </Issuer>
<Symbol> S </Symbol>
<TLA> PSS </TLA>
<ISO> 999 </ISO>
<Minor> Grains </Minor>
</Currency>
Only the <CurrencyId>, <Name> and <Decimal> are obligatory. After any optional fields, a server is free to return additional fields. For example, see Ricardian Contracts, below.
Move this somewhere else.
Note that some implementations will include some form of Ricardian Contract appended as described above. The Ricardian Contract is the superior form for describing committments to valuable currencies, and is described on Webfunds' Ricardian Contract Page.
In this case, the <Currency> tag will look like:
<Currency>
<CurrencyId> ABC012DEF345 </CurrencyId>
<Name> Shells </Name>
<Decimal> 2 </Decimal>
. . .
<Ricardian>
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
. . .
-----END PGP SIGNATURE-----
</Ricardian>
<Local>
. . .
</Local>
</Currency>
In this case, the <CurrencyId> will be the canonical message digest (aka "hash") defined for the Ricardian Contract form. It will be a 20 byte SHA1 identifier.
A Ricardian Contract will include all relevant information and dominates the <Currency>, as it documents the contract between the users.
In order to create a new User, use a <CreateUserRequest>.
<CreateUserRequest>
<Auth>
<UserId> Merman </UserId>
<Password> FlipFlop </Password>
</Auth>
<User>
<UserId> Merman </UserId>
<AuthMethods>
<PasswordMethod>
<Password> FlipFlop </Password>
<Time> 123456789012345678 </Time>
<Memo> Created with Jo's Coral Wave </Memo>
</PasswordMethod>
</AuthMethods>
<UserProfile>
<Name> Merman's </Name>
<FullName> Joseph Merman & Sons </FullName>
<DisplayName> Merman's Scalers </DisplayName>
<Email> Mermans@atlantis.waterworld </Email>
</UserProfile>
</User>
</CreateUserRequest>
On reply, the server will return the unique identifier for the new user to be used henceforth, or an <ErrorResponse> This <UserId> so returned in the response defines the new user and must then be used for any requests and the packets within.
The server may permit a particular <UserId> to be suggested in the <UserProfile> entity within the <CreateUserRequest> If the request succeeds, then that <UserId> is accepted and is returned as above, in the <CreateUserResponse>. If the <UserId> is not available or out of specification, then an <ErrorResponse> is returned and the user was not created.
Alternatively, the request should leave <UserId> empty. In this case, a unique Id will be allocated by the server.
<CreateUserResponse> <UserId> Mermaid001 </UserId> <Status> pending </Status> </CreateUserResponse>
If the server returns a different name, then the client has the responsibility of managing any mapping; the server will ignore the originally suggested name. Alternatively, the server may fail the request, at its option, with an <ErrorResponse>. This flexibility is there so that servers can allocate user account numbers as their primary identifier.
The optional <Status> status tag indicates whether the user is pending due to some authentication checks (for example, email verification). The contents of the tag are currently undefined.
Then, subsequent requests can supply the <Auth> field and thus set the context of that unique user name.
In the <CreateUserRequest> the authentication tag, <Auth>, should still be supplied, even as it is not currently authenticatable by the server. The receiving implementation generally shares its Request code across all Requests, so prefers to see the Auth present.
Most systems will permit users to be created de novo, from nothing. However, other systems may require a special authentication, or they may offer a feature of introduction. Such a feature are not yet defined.
If a server implementation permits it, a new Account can be created using a <CreateAccountRequest>.
<CreateAccountRequest>
<Auth>
<UserId> Mermaid001 </UserId>
<Password> FlipFlop </Password>
</Auth>
<Account>
<AccountId> </AccountId>
<AccountProfile>
<Name> Takings </Name>
<FullName> Contributions & Revenues </FullName>
<DisplayName> Mermaid's Fairs </DisplayName>
</AccountProfile>
<CurrencyId> Fishbait </CurrencyId>
<CurrencyId> pieces of eight </CurrencyId>
</Account>
</CreateAccountRequest>
<CreateAccountResponse>
<AccountId> WET000123 </AccountId>
<Status> Done! </Status>
</CreateAccountResponse>
Then, subsequent requests can specify the account using the returned <AccountId>, which will be a unique identifier for the whole system.
In order to work out what accounts are available, use the <LookupRequest>, below.
The Currency can be requested from the server in a <GetCurrencyRequest>.
<GetCurrencyRequest>
<Auth>
<UserId> Mermaid001 </UserId>
</Auth>
<CurrencyId> PR001 </CurrencyId>
</GetCurrencyRequest>
<GetCurrencyResponse>
<Currency>
<CurrencyId> PR001 </CurrencyId>
<Name> Prawns </Name>
<FullName> King Neptune's Juicy Prawns </FullName>
<Issuer> King Neptune </Issuer>
<Symbol> P </Symbol>
<Decimal> 1 </Decimal>
<Minor> legs </Minor>
<Status> fresh </Status>
</Currency>
</GetCurrencyResponse>
As a static, rarely changing piece of information, the Currency can be cached locally. Probably, a server may decide to return this static information without needing a fully authenticing Auth tag, but an empty Auth should still be supplied, as above.
A Currency can be added to an Account using the <AddCurrencyRequest>.
<AddCurrencyRequest>
<Auth>
<UserId> Mermaid001 </UserId>
<Password> FloppityFlip </Password>
</Auth>
<AccountId> Flipper Fund </AccountId>
<CurrencyId> PR001 </CurrencyId>
</AddCurrencyRequest>
<AddCurrencyResponse>
<Status> ok! </Status>
</AddCurrencyResponse>
As a server management feature, a new Currency can be sent to enable for future usage in the <NewCurrencyRequest>.
<NewCurrencyRequest>
<Auth>
<UserId> Mermaid001 </UserId>
<Password> Do it, dude! </Password>
</Auth>
<Currency>
<CurrencyId> PR666 </CurrencyId>
<Name> Swordfish </Name>
<FullName> King Neptune's Royal Guards </FullName>
<Issuer> King Neptune </Issuer>
<Symbol> S </Symbol>
</Currency>
</NewCurrencyRequest>
<NewCurrencyResponse>
<Status> pending </Status>
</NewCurrencyResponse>
It is up to the server as to whether to accept any such request. The server can indicate the status of a currency in the <Status> tag.
It is possible to probe details for a user and account information with a <LookupRequest>. For example, the following user lookup:
<LookupRequest>
<Auth>
<UserId> Mermaid001 </UserId>
some auth method...
</Auth>
</LookupRequest>
Might elicit the following:
<LookupResponse>
<User>
<UserId> Mermaid001 </UserId>
<UserProfile>
<Name> Mermaid'apos; </Name>
<FullName> Josephine Mermaid & Daughters </FullName>
<DisplayName> Mermaid's Water Taxis </DisplayName>
<Email> Mermaids@atlantis.waterworld </Email>
</UserProfile>
<AccountId> M1NE001 </AccountId>
<AccountId> EXTR002 </AccountId>
<AccountId> SECR888 </AccountId>
</User>
<Account>
<AccountId> M1NE001 </AccountId>
<FullName> Takings </FullName>
<DisplayName> Mermaid's Fares </DisplayName>
<CurrencyId> Fishbait </CurrencyId>
<CurrencyId> pieces of eight </CurrencyId>
</Account>
. . .
</LookupResponse>
At its option, the server may return a list of <Accounts>.
In the event that the list of Accounts is not included, a more refined Lookup should return the details.
<LookupRequest>
<Auth>
<UserId> Mermaid001 </UserId>
some auth method...
</Auth>
<AccountId> Tips007 </AccountId>
</LookupRequest>
<LookupResponse>
<Account>
<AccountId> Tips007 </AccountId>
<AccountProfile>
<FullName> Tips </FullName>
<DisplayName> Grateful Gratiuities </DisplayName>
</AccountProfile>
<CurrencyId> USD </CurrencyId>
<CurrencyId> YEN </CurrencyId>
<CurrencyId> GG </CurrencyId>
</Account>
</LookupResponse>
It is also possible to probe details for a user or account without the authentication.
<PublicLookupRequest>
<Auth>
<UserId> </UserId>
<!-- null/empty auth method supplied! -->
</Auth>
<UserId> Mermaid001 </UserId>
</PublicLookupRequest>
Might elicit the following:
<PublicLookupResponse>
<User>
<UserId> Mermaid001 </UserId>
<UserProfile>
<DisplayName> Mermaid's Water Taxis </DisplayName>
<!-- details supressed! -->
</UserProfile>
</User>
<Account>
<AccountId> M1NE001 </AccountId>
<DisplayName> Mermaid's Fares </DisplayName>
<CurrencyId> Fishbait </CurrencyId>
<CurrencyId> pieces of eight </CurrencyId>
</Account>
<Account>
<AccountId> EXTR002 </AccountId>
<DisplayName> Service Appreciation </DisplayName>
<CurrencyId> Minnows </CurrencyId>
<CurrencyId> Prawns </CurrencyId>
</Account>
</PublicLookupResponse>
This feature permits Merchant software to display a name to the human so that they can confirm they have the right account, as an error check. A <DisplayName> tag indicates what names are available to an unauthenticated user for that purpose.
There is much more potential in a public lookup than is described above, but this is still a developing field, so is not discussed further here. Specifically, need a public bit for all assets, and need a default setting as well.
To change a profile entry, send the new entry in <Set...> requests.
<SetUserProfileRequest>
<UserProfile>
. . .
</UserProfile>
<Auth> some auth method </Auth>
</SetUserProfileRequest>
<SetUserProfileResponse>
<UserProfile>
. . .
</UserProfile>
</SetUserProfileResponse>
The server will set the entries supplied, and return the whole profile so the client can confirm that the setting worked.
A <GetUserProfileRequest> will also return the <UserProfile> in its response:
<GetUserProfileRequest>
<Auth> some auth method </Auth>
</GetUserProfileRequest>
<GetUserProfileResponse>
<UserProfile>
<Name required="1" public="0" change="1">
Mermaid's
</Name>
<FullName required="1" public="0" change="1">
Josephine Mermaid & Daughters
</FullName>
<Address required="0" public="0" change="1">
1 Finance Avenue, Atlantis
</Address>
<DisplayName required="0" public="1" change="1">
Mermaid's Water Taxis
</DisplayName>
<Email required="1" public="1" change="3">
Mermaids@atlantis.waterworld
</Email>
</UserProfile>
</GetUserProfileResponse>
In this way, a <GetUserProfileResponse> appears the same as a <SetUserProfileResponse>, in content. The difference lies in additional tags that the server may return in the former that explain further what can and can't be set in the Profile.
T B D . . .