Note that if symmetric cryptography is being used then a separate
RecipientInfo and Value elements for each different set of shared
secret keys are likely within the Signature Component.
Alternatively if asymmetric cryptography is being used then the
RecpientRefs attribute of one RecipientInfo element may refer to
multiple Organisation Components if they are all using the same
certificates.
6.1.3 Using signatures to Prove Actions Complete Successfully
Proving an action completed successfully, is achieved by signing data
on Response messages. Specifically:
o on the Offer Response, when a Merchant is making an Offer to the
Consumer which can then be sent to either:
- a Payment Handler to prove that the Merchant authorises
Payment, or
- a Delivery Handler to prove that Merchant authorises Delivery,
provided other necessary authorisations are complete (see
below)
o on the Payment Response, when a Payment Handler is generating a
Payment Receipt which can be sent to either:
- a Delivery Handler, in a Delivery Request Block to authorise
Delivery together with the Offer Response signature, or
- another Payment Handler, in a second Payment Request, to
authorise the second payment in a Value Exchange IOTP
Transaction
o Delivery Response, when a Delivery Handler is generating a
Delivery Note. This can be used to prove after the event what the
Delivery Handler said they would do
o Authentication Response. One method of authenticating another
party to a trade is to send an Authentication Request specifying
that a Digital Signature should be used for authentication
o Transaction Status Inquiry. The Inquiry Response Block may be
digitally signed to attest to the authenticity of the response
o Ping. The Ping Response may be digitally signed so that checks can
be made that the signature can be understood.
This proof of an action may, in future versions of IOTP, also be used
to prove after the event that the IOTP transaction occurred. For
example to a Customer Care Provider.
6.2 Checking a Signature is Correctly Calculated
Checking a signature is correctly calculated is part of checking for
Message Level Errors (see section 4.3.2). It is included here so that
all signature and security related considerations are kept together.
Before a Trading Role can check a signature it must identify which of
the potentially multiple Signature elements should be checked. The
steps involved are as follows:
o check that a Signature Block is present and it contains one or
more Signature Components
o identify the Organisation Component which contains an OrgId
attribute for the Organisation which is carrying out the signature
check. If no or more than one Organisation Component is found then
it is an error
o use the ID attribute of the Organisation Component to find the
RecipientInfo element that contains a RecipientRefs attribute that
refers to that Organisation Component. Note there may be no
signatures to verify
o check the Signature Component that contains the identified
RecipientInfo element as follows:
- use the SignatureValueRef and the SignatureAlgorithmRef
attributes to identify, respectively: the Value element that
contains the signature to be checked and the Signature
Algorithm element that describes the signature algorithm to be
used to verify the Signature, then
- if the Signature Algorithm element indicates that asymmetric
cryptography is being used then use the SignatureCertRef to
identify the Certificate to be used by the signature algorithm
- if Signature Algorithm element indicates that symmetric
cryptography is being used then the content of the
RecipientInfo element is used to identify the correct shared
secret key to use
- use the specified signature algorithm to check that the Value
Element correctly signs the Manifest Element
- check that the Digest Elements in the Manifest Element are
correctly calculated where Components or Blocks referenced by
the Digest have been received by the Organisation checking the
signature.
6.3 Checking a Payment or Delivery can occur
This section describes the processes required for a Payment Handler
or Delivery Handler to check that a payment or delivery can occur.
This may include checking signatures if this is specified by the
Merchant.
In outline the steps are:
o check that the Payment Request or Delivery Request has been sent
to the correct Organisation
o check that correct IOTP components are present in the request, and
o check that the payment or delivery is authorised
For clarity and brevity the following terms or phrases are used in
this section:
o a "Request Block" is used to refer to either a Payment Request
Block (see section 8.7) or a Delivery Request Block (see section
8.10) unless specified to the contrary
o a "Response Block" is used to refer to either a Payment Response
Block (see section 8.9) or a Delivery Response Block (see section
8.11)
o an "Action" is used to refer to an action which occurs on receipt
of a Request Block. Actions can be either a Payment or a Delivery
o an "Action Organisation", is used to refer to the Payment Handler
or Delivery Handler that carries out an Action
o a "Signer of an Action", is used to refer to the Organisations
that sign data about an Action to authorise the Action, either in
whole or in part
o a "Verifier of an Action", is used to refer to the Organisations
that verify data to determine if they are authorised to carry out
the Action
o an ActionOrgRef attribute contains Element References which can be
used to identify the "Action Organisation" that should carry out
an Action
6.3.1 Check Request Block sent Correct Organisation
Checking the Request Block was sent to the correct Organisation
varies depending on whether the request refers to a Payment or a
Delivery.
6.3.1.1 Payment
In outline a Payment Handler checks if it can accept or make a
payment by identifying the Payment Component in the Payment Request
Block it has received, then using the ID of the Payment Component to
track through the Brand List and Brand Selection Components to
identify the Organisation selected by the Consumer and then checking
that this Organisation is itself.
The way data is accessed to do this is illustrated in the figure
below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Start
|
v
Brand List<--------------------------+-----------Payment
Component BrandListRef | Component
| |
|-Brand<-------------------------- |
| Element BrandRef | |
| | Brand Selection
| |Protocol Component
| | AmountRefs | |
| v Protocol | |
|-Protocol Amount<---------------- |
| Element---------- AmountRef |
| | | |
| |Currency |Pay |
| | AmountRefs |Protocol |
| v |Ref |
|-Currency Amount | |
| Element<---------|----------------
| |
-PayProtocol<-----
Element---------------------->Organisation
Action Component
OrgRef |
-Trading Role
Element
(Payment Handler)
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 12 Checking a Payment Handler can carry out a Payment
The following describes the steps involved and the checks which need
to be made:
o Identify the Payment Component (see section 7.9) in the Payment
Request Block that was received.
o Identify the Brand List and Brand Selection Components for the
Payment Component. This involves:
- identifying the Brand List Component (see section 7.7) where
the value of its ID attribute matches the BrandListRef
attribute of the Payment Component. If no or more than one
Brand List Component is found there is an error.
- identifying the Brand Selection Component (see section 7.8)
where the value of its BrandListRef attribute matches the
BrandListRef of the Payment Component. If no or more than one
matching Brand Selection Component is found there is an error.
o Identify the Brand, Protocol Amount, Pay Protocol and Currency
Amount elements within the Brand List that have been selected by
the Consumer as follows:
- the Brand Element (see section 7.7.1) selected is the element
where the value of its Id attribute matches the value of the
BrandRef attribute in the Brand Selection. If no or more than
one matching Brand Element is found then there is an error.
- the Protocol Amount Element (see section 7.7.3) selected is the
element where the value of its Id attribute matches the value
of the ProtocolAmountRef attribute in the Brand Selection
Component. If no or more than one matching Protocol Amount
Element is found there is an error
- the Pay Protocol Element (see section 7.7.5) selected is the
element where the value of its Id attribute matches the value
of the PayProtocolRef attribute in the identified Protocol
Amount Element. If no or more than one matching Pay Protocol
Element is found there is an error
- the Currency Amount Element (see section 7.7.4) selected is the
element where the value of its Id attribute matches the value
of the CurrencyAmountRef attribute in the Brand Selection
Component. If no or more than one matching Currency Amount
element is found there is an error
o Check the consistency of the references in the Brand List and
Brand Selection Components:
- check that an Element Reference exists in the
ProtocolAmountRefs attribute of the identified Brand Element
that matches the Id attribute of the identified Protocol Amount
Element. If no or more than one matching Element Reference can
be found there is an error
- check that the CurrencyAmountRefs attribute of the identified
Protocol Amount element contains an element reference that
matches the Id attribute of the identified Currency Amount
element. If no or more than one matching Element Reference is
found there is an error.
- check the consistency of the elements in the Brand List.
Specifically, the selected Brand, Protocol Amount, Pay Protocol
and Currency Amount Elements are all child elements of the
identified Brand List Component. If they are not there is an
error.
o Check that the Payment Handler that received the Payment Request
Block is the Payment Handler selected by the Consumer. This
involves:
- identifying the Organisation Component for the Payment Handler.
This is the Organisation Component where its ID attribute
matches the ActionOrgRef attribute in the identified Pay
Protocol Element. If no or more than one matching Organisation
Component is found there is an error
- checking the Organisation Component has a Trading Role Element
with a Role attribute of PaymentHandler. If not there is an
error
- finally, if the identified Organisation Component is not the
same as the Organisation that received the Payment Request
Block, then there is an error.
6.3.1.2 Delivery
The way data is accessed by a Delivery Handler in order to check that
it may carry out a delivery is illustrated in the figure below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Start
|
v
Delivery
Component
|
|ActionOrgRef
|
v
Organisation
Component
|
-Trading Role
Element
(Delivery Handler)
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 13 Checking a Delivery Handler can carry out a Delivery
The steps involved are as follows:
o Identify the Delivery Component in the Delivery Request Block. If
there is no or more than one matching Delivery Component there is
an error
o Use the ActionOrgRef attribute of the Delivery Component to
identify the Organisation Component of the Delivery Handler. If
there is no or more than one matching Organisation Component there
is an error
o If the Organisation Component for the Delivery Handler does not
have a Trading Role Element with a Role attribute of
DeliveryHandler there is an error
o Finally, if the Organisation that received the Delivery Request
Block does not identify the Organisation Component for the
Delivery Handler as itself, then there is an error.
6.3.2 Check Correct Components present in Request Block
Check that the correct components are present in the Payment Request
Block (see section 8.7) or in the Delivery Request Block (see section
8.10).
If components are missing, there is an error.
6.3.3 Check an Action is Authorised
The previous steps identified the Action Organisation and that all
the necessary components are present. This step checks that the
Action Organisation is authorised to carry out the Action.
In outline the Action Organisation will identifies the Merchant,
checks that it has a pre-existing agreement with the Merchant that
allows it carry out the Action and that any constraints implied by
that agreement are being followed, then, if signatures are required,
it checks that they sign the correct data.
The steps involved are as follows:
o Identify the Merchant. This is the Organisation Component with a
Trading Role Element which has a Role attribute with a value of
Merchant. If no or more than one Trading Role Element is found,
there is an error
o Check the Action Organisation's agreements with the Merchant
allows the Action to be carried out. To do this the Action
Organisation must check that:
- the Merchant is known and a pre-existing agreement exists for
the Action Organisation to be their agent for the payment or
delivery
- they are allowed to take part in the type of IOTP transaction
that is occurring. For example a Payment Handler may have
agreed to accept payments as part of a Baseline Purchase, but
not make payments as part of a Baseline Refund
- any constraints in their agreement with the Merchant are being
followed, for example, whether or not an Offer Response
signature is required
o Check the signatures are correct. If signatures are required then
they need to be checked. This involves:
- Identifying the correct signatures to check. This involves the
Action Organisation identifying the Signature Components that
contain references to the Action Organisation (see 6.3.1).
Depending on the IOTP Transaction being carried out (see
section 9) either one or two signatures may be identified
- checking that the Signature Components are correct. This
involves checking that Digest elements exist within the
Manifest Element that refer to the necessary Trading Components
(see section 6.3.3.1).
6.3.3.1 Check the Signatures Digests are correct
All Signature Components contained within IOTP Messages must include
Digest elements that refer to:
o the Transaction Id Component (see section 3.3.1) of the IOTP
message that contains the Signature Component. This binds the
globally unique IotpTransId to other components which make up the
IOTP Transaction
o the Transaction Reference Block (see section 3.3) of the first
IOTP Message that contained the signature. This binds the
IotpTransId with information about the IOTP Message contained
inside the Message Id Component (see section 3.3.2).
Check that each Signature Component contains Digest elements that
refer to the correct data required.
The Digest elements that need to be present depend on the Trading
Role of the Organisation which generated (signed) the signature:
o if the signer of the signature is a Merchant then:
- Digest elements must be present for all the components in the
Request Block apart from the Brand Selection Component which is
optional
o if the signer of the signature is a Payment Handler then Digest
elements must be present for:
- the Signature Component signed by the Merchant, and optionally
- one or more Signature Components signed by the previous Payment
Handler(s) in the Transaction.
7. Trading Components
This section describes the Trading Components used within IOTP.
Trading Components are the child XML elements which occur immediately
below a Trading Block as illustrated in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
IOTP MESSAGE <----------- IOTP Message - an XML Document
| which is transported between the
| Trading Roles
|-Trans Ref Block <----- Trans Ref Block - contains
| | information which describes the
| | IOTP Transaction and the IOTP
Message.
--------> | |-Trans Id Comp. <--- Transaction Id Component -
| | | uniquely identifies the IOTP
| | | Transaction. The Trans Id
| | | Components are the same across
| | | all IOTP messages that comprise
| | | a single IOTP transaction.
| | |-Msg Id Comp. <----- Message Id Component -
| | identifies and describes an IOTP
| | Message within an IOTP
| | Transaction
| |-Signature Block <----- Signature Block (optional) -
| | | contains one or more Signature
| | | Components and their associated
| | | Certificates
| ---> | |-Signature Comp. <-- Signature Component - contains
| | | | digital signatures. Signatures
| | | | may sign digests of the Trans Ref
| | | | Block and any Trading Component
| | | | in any IOTP Message in the same
| | | | IOTP Transaction.
| | | |-Certificate Comp. <- Certificate Component. Used to
| | | check the signature.
Trading |-Trading Block <-------- Trading Block - an XML Element
Components | |-Trading Comp. within an IOTP Message that
| | | |-Trading Comp. contains a predefined set of
| ---> | |-Trading Comp. Trading Components
| | |-Trading Comp.
| | |-Trading Comp. <----- Trading Components - XML
| | Elements within a Trading Block
| |-Trading Block that contain a predefined set of
--------> | |-Trading Comp. XML elements and attributes
| |-Trading Comp. containing information required
| |-Trading Comp. to support a Trading Exchange
| |-Trading Comp.
| |-Trading Comp.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 14 Trading Components
The Trading Components described in this section are listed below in
approximately the sequence they are likely to be used:
o Protocol Options Component
o Authentication Request Component
o Authentication Response Component
o Trading Role Information Request Component
o Order Component
o Organisation Component
o Brand List Component
o Brand Selection Component
o Payment Component
o Payment Scheme Component
o Payment Receipt Component
o Delivery Component
o Delivery Data Component
o Delivery Note Component
o Signature Component
o Certificate Component
o Error Component
Note that the following components are listed in other sections of
this specification:
o Transaction Id Component (see section 3.3.1)
o Message Id Component (see section 3.3.2)
7.1 Protocol Options Component
Protocol options are options which apply to the IOTP Transaction as a
whole. Essentially it provides a short description of the entire
transaction and the net location which the Consumer role should
branch to if the IOTP Transaction is successful.
The definition of a Protocol Options Component is as follows.
<!ELEMENT ProtocolOptions EMPTY >
<!ATTLIST ProtocolOptions
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
ShortDesc CDATA #REQUIRED
SenderNetLocn CDATA #IMPLIED
SecureSenderNetLocn CDATA #IMPLIED
SuccessNetLocn CDATA #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Protocol Options Component within the IOTP
Transaction.
Xml:lang Defines the language used by attributes or child
elements within this component, unless
overridden by an xml:lang attribute on a child
element. See section 3.8 Identifying Languages.
ShortDesc This contains a short description of the IOTP
Transaction in the language defined by xml:lang.
Its purpose is to provide an explanation of what
type of IOTP Transaction is being conducted by
the parties involved.
It is used to facilitate selecting an individual
transaction from a list of similar transactions,
for example from a database of IOTP transactions
which has been stored by a Consumer, Merchant,
etc.
SenderNetLocn This contains the non secured net location of
the sender of the TPO Block in which the
Protocol Options Component is contained.
It is the net location to which the recipient of
the TPO block should send a TPO Selection Block
if required.
The content of this attribute is dependent on
the Transport Mechanism see the Transport
Mechanism Supplement.
SecureSenderNetLocn This contains the secured net location of the
sender of the TPO Block in which the Protocol
Options Component is contained.
The content of this attribute is dependent on
the Transport Mechanism see the Transport
Mechanism Supplement.
SuccessNetLocn This contains the net location that should be
displayed after the IOTP Transaction has
successfully completed.
The content of this attribute is dependent on
the Transport Mechanism see the Transport
Mechanism Supplement.
Either SenderNetLocn, SecureSenderNetLocn or both must be present.
7.2 Authentication Request Component
This Trading Component contains parameter data that is used in an
Authentication of one Trading Role by another. Its definition is as
follows.
<!ELEMENT AuthReq (Algorithm, PackagedContent*)>
<!ATTLIST AuthReq
ID ID #REQUIRED
AuthenticationId CDATA #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
If required the Algorithm may use the challenge data, contained in
the Packaged Content elements within the Authentication Request
Component in its calculation. The format of the Packaged Contents are
Algorithm dependent.
Attributes:
ID An identifier which uniquely identifies the
Authentication Request Component within the IOTP
Transaction.
AuthenticationId An identifier specified by the Authenticator
which, if returned by the Organisation that
receives the Authentication Request, will enable
the Authenticator to identify which Authentication
is being referred to.
ContentSoftwareId See section 14.Glossary
Content:
PackagedContent This contains the challenge data as one or more
Packaged Content (see section 3.7) that is to be
responded to using the Algorithm defined by the
Algorithm element.
Algorithm This contains information which describes the
Algorithm (see 7.19 Signature Components) that
must be used to generate the Authentication
Response.
The Algorithms that may be used are identified by
the Name attribute of the Algorithm element. For
valid values see section 12. IANA Considerations.
7.3 Authentication Response Component
The Authentication Response Component contains the results of an
authentication request. It uses the Algorithm contained in the
Authentication Request Component (see section 7.2) selected from the
Authentication Request Block (see section 8.4).
Depending on the Algorithm selected, the results of applying the
algorithm will either be contained in a Signature Component that
signs both the Authentication Response and potentially other data, or
in the Packaged Content elements within the Authentication Response
Component. Its definition is as follows.
<!ELEMENT AuthResp (PackagedContent*) >
<!ATTLIST AuthResp
ID ID #REQUIRED
AuthenticationId CDATA #REQUIRED
SelectedAlgorithmRef NMTOKEN #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Authentication Response Component within the
IOTP Transaction.
AuthenticationId The Authentication identifier specified by the
Authenticator that was included in the
Authentication Request Component(see section
7.2). This will enable the Authenticator to
identify the Authentication that is being
referred to.
SelectedAlgorithmRef An Element Reference that identifies the
Algorithm element used to generate the
Authentication Response.
ContentSoftwareId See section 14.Glossary.
Content:
PackagedContent This may contain the response generated as a
result of applying the Algorithm selected from the
Authentication Request Component see section 7.2.
For example, for a payment specific scheme, it may
contain scheme-specific data. Refer to the scheme-
specific supplemental documentation for
definitions of its content.
7.4 Trading Role Information Request Component
This Trading Component contains a list of Trading Roles (see section
2.1) about which information is being requested. The result of a
Trading Role Request is a set of Organisation Components (see section
7.6) that describe each of the Trading Roles requested.
Example usage includes:
o a Merchant requesting that a Consumer provides Organisation
Components for the Consumer and DelivTo Trading Roles
o a Consumer requesting from a Merchant, information about the
Payment Handlers and Delivery Handlers that the Merchant uses.
Its definition is as follows.
<!ELEMENT TradingRoleInfoReq EMPTY>
<!ATTLIST TradingRoleInfoReq
ID ID #REQUIRED
TradingRoleList NMTOKENS #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Trading Role Information Request Component within
the IOTP Transaction.
TradingRoleList Contains a list of one or more Trading Roles (see
the TradingRole attribute of the Trading Role
Element - section 7.6.2) for which information is
being requested.
7.5 Order Component
An Order Component contains information about an order. Its
definition is as follows.
<!ELEMENT Order (PackagedContent*) >
<!ATTLIST Order
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
OrderIdentifier CDATA #REQUIRED
ShortDesc CDATA #REQUIRED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
ApplicableLaw CDATA #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the Order
Component within the IOTP Transaction.
xml:lang Defines the language used by attributes or child
elements within this component, unless overridden
by an xml:lang attribute on a child element. See
section 3.8 Identifying Languages.
OrderIdentifier This is a code, reference number or other
identifier which the creator of the Order may use
to identify the order. It must be unique within an
IOTP Transaction. If it is used in this way, then
it may remove the need to specify any content for
the Order element as the reference can be used to
look up the necessary information in a database.
ShortDesc A short description of the order in the language
defined by xml:lang. It is used to facilitate
selecting an individual order from a list of
orders, for example from a database of orders
which has been stored by a Consumer, Merchant,
etc.
OkFrom The date and time in [UTC] format after which the
offer made by the Merchant lapses.
OkTo The date and time in [UTC] format before which a
Value Acquirer may accept the offer made by the
Merchant is not valid.
ApplicableLaw A phrase in the language defined by xml:lang which
describes the state or country of jurisdiction
which will apply in resolving problems or
disputes.
ContentSoftwareId See section 14.Glossary.
Content:
PackagedContent An optional description of the order information
as one or more Packaged Contents (see section
3.7).
7.5.1 Order Description Content
The Packaged Content element will normally be required, however it
may be omitted where sufficient information about the purchase can be
provided in the ShortDesc attribute. If the full Order Description
requires it several Packaged Content elements may be used.
Although the amount and currency are likely to appear in the Packaged
Content of the Order Description it is the amount and currency
contained in the payment related trading components (Brand List,
Brand Selection and Payment) that is authoritative. This means it is
important that the amount actually being paid (as contained in the
payment related trading components) is prominently displayed to the
Consumer.
For interoperability, implementations must support Plain Text, HTML
and XML as a minimum so that it can be easily displayed.
7.5.2 OkFrom and OkTo Timestamps
Note that:
o the OkFrom date may be later than the OkFrom date on the Payment
Component (see section 7.9) associated with this order, and
o similarly, the OkTo date may be earlier that the OkTo date on the
Payment Component (see section 7.9).
Note: Disclaimer. The following information provided in this note
does not represent formal advice of any of the authors of this
specification. Readers of this specification must form their own
views and seek their own legal counsel on the usefulness and
applicability of this information.
The merchant in the context of Internet commerce with anonymous
consumers initially frames the terms of the offer on the web page,
and in order to obtain the goods or services, the consumer must
accept them.
If there is to be a time-limited offer, it is recommended that
merchants communicate this to the consumer and state in the order
description in a manner which is clear to the consumer that:
o the offer is time limited
o the OkFrom and OkTo timestamps specify the validity of the offer
o the clock, e.g., the merchant's clock, that will be used to
determine the validity of the offer
Also note that although the OkFrom and OkTo dates are likely to
appear in the Packaged Content of the Order Description it is the
dates contained in the Order Component that is authoritative. This
means it is important that the OkFrom and OkTo dates actually being
used is prominently displayed to the Consumer.
7.6 Organisation Component
The Organisation Component provides information about an individual
or an Organisation. This can be used for a variety of purposes. For
example:
o to describe the merchant who is selling the goods,
o to identify who made a purchase,
o to identify who will take delivery of goods,
o to provide a customer care contact,
o to describe who will be the Payment Handler.
Note that the Organisation Components which must be present in an
IOTP Message are dependent on the particular transaction being
carried out. Refer to section 9. Internet Open Trading Protocol
Transactions, for more details.
Its definition is as follows.
<!ELEMENT Org (TradingRole+, ContactInfo?,
PersonName?, PostalAddress?)>
<!ATTLIST Org
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
OrgId CDATA #REQUIRED
LegalName CDATA #IMPLIED
ShortDesc CDATA #IMPLIED
LogoNetLocn CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Organisation Component within the IOTP
Transaction.
xml:lang Defines the language used by attributes or child
elements within this component, unless overridden
by an xml:lang attribute on a child element. See
section 3.8 Identifying Languages.
OrgId A code which identifies the Organisation described
by the Organisation Component. See 7.6.1
Organisation IDs, below.
LegalName For Organisations which are companies this is
their legal name in the language defined by
xml:lang. It is required for Organisations who
have a Trading Role other than Consumer or
DelivTo.
ShortDesc A short description of the Organisation in the
language defined by xml:lang. It is typically the
name by which the Organisation is commonly known.
For example, if the legal name was "Blue Meadows
Financial Services Inc.". Then its short name
would likely be "Blue Meadows".
It is used to facilitate selecting an individual
Organisation from a list of Organisations, for
example from a database of Organisations involved
in IOTP Transactions which has been stored by a
consumer.
LogoNetLocn The net location which can be used to download the
logo for the Organisation.
See section 10 Retrieving Logos.
The content of this attribute must conform to
[RFC1738].
Content:
TradingRole See 7.6.2 Trading Role Element below.
ContactInfo See 7.6.3 Contact Information Element below.
PersonName See 7.6.4 Person Name below.
PostalAddress See 7.6.5 Postal Address below.
7.6.1 Organisation IDs
Organisation IDs are used by one IOTP Trading Role to identify
another. In order to avoid confusion, this means that these IDs must
be globally unique.
In principle this is achieved in the following way:
o the Organisation Id for all trading roles, apart from the Consumer
Trading Role, uses a domain name as their globally unique
identifier,
o the Organisation Id for a Consumer Trading Role is allocated by
one of the other Trading Roles in an IOTP Transaction and is made
unique by concatenating it with that other roles' Organisation Id,
o once a Consumer is allocated an Organisation Id within an IOTP
Transaction the same Organisation Id is used by all the other
trading roles in that IOTP transaction to identify that Consumer.
Specifically, the content of the Organisation ID is defined as
follows:
OrgId ::= NonConsumerOrgId | ConsumerOrgId
NonConsumerOrgId ::= DomainName
ConsumerOrgId ::= ConsumerOrgIdPrefix (namechar)+ "/" NonConsumerOrgId
ConsumerOrgIdPrefix ::= "Consumer:"
ConsumerOrgId The Organisation ID for a Consumer consists of:
o a standard prefix to identify that the
Organisation Id is for a consumer, followed by
o one or more characters which conform to the
definition of an XML "namechar". See [XML]
specifications, followed by
o the NonConsumerOrgId for the Organisation
which allocated the ConsumerOrgId. It is
normally the Merchant role.
Use of upper and lower case is not significant.
NonConsumerOrgId If the Role is not Consumer then this contains the
Canonical Name for the non-consumer Organisation
being described by the Organisation Component. See
[DNS] optionally followed by additional
characters, if required, to make the
NonConsumerOrgId unique.
Note that a NonConsumerOrgId may not start with
the ConsumerOrgIdPrefix.
Use of upper and lower case is not significant.
Examples of Organisation Ids follow:
o newjerseybooks.com - a merchant Organisation id
o westernbank.co.uk - a Payment Handler Organisation id
o consumer:1000247ABH/newjerseybooks.com - a consumer Organisation
id allocated by a merchant
7.6.2 Trading Role Element
This identifies the Trading Role of an individual or Organisation in
the IOTP Transaction. Note, an Organisation may have more than one
Trading Role and several roles may be present in one Organisation
element. Its definition is as follows:
<!ELEMENT TradingRole EMPTY >
<!ATTLIST TradingRole
ID ID #REQUIRED
TradingRole NMTOKEN #REQUIRED
IotpMsgIdPrefix NMTOKEN #REQUIRED
CancelNetLocn CDATA #IMPLIED
ErrorNetLocn CDATA #IMPLIED
ErrorLogNetLocn CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Trading Role Element within the IOTP Transaction.
TradingRole The trading role of the Organisation. Valid values
are:
o Consumer. The person or Organisation that is
acting in the role of a consumer in the IOTP
Transaction.
o Merchant. The person or Organisation that is
acting in the role of merchant in the IOTP
Transaction.
o PaymentHandler. The financial institution or
other Organisation which is a Payment Handler
for the IOTP Transaction
o DeliveryHandler. The person or Organisation
that is the delivering the goods or services
for the IOTP Transaction
o DelivTo. The person or Organisation that is
receiving the delivery of goods or services in
the IOTP Transaction
o CustCare. The Organisation and/or individual
who will provide customer care for an IOTP
Transaction.
Values of TradingRole are controlled under the
procedures defined in section 12 IANA
Considerations which also allows user defined
values to be defined.
IotpMsgIdPrefix Contains the prefix which must be used for all
IOTP Messages sent by the Trading Role in this
IOTP Transaction. The values to be used are
defined in 3.4.1 IOTP Message ID Attribute
Definition.
CancelNetLocn This contains the net location of where the
Consumer should go to if the Consumer cancels the
transaction for some reason. It can be used by the
Trading Role to provide a response which is more
tailored to the circumstances of a particular
transaction.
This attribute:
o must not be present when TradingRole is set to
Consumer role or DelivTo,
o must be present when TradingRole is set to
Merchant, PaymentHandler or DeliveryHandler.
The content of this attribute is dependent on the
Transport Mechanism see the Transport Mechanism
Supplement.
ErrorNetLocn This contains the net location that should be
displayed by the Consumer after the Consumer has
either received or generated an Error Block
containing an Error Component with the Severity
attribute set to either:
o HardError,
o Warning but the Consumer decides to not
continue with the transaction
o TransientError and the transaction has
subsequently timed out.
See section 7.21.1 Error Processing Guidelines for
more details.
This attribute:
o must not be present when TradingRole is set to
Consumer or DelivTo,
o must be present when TradingRole is set to
Merchant, PaymentHandler or DeliveryHandler.
The content of this attribute is dependent on the
Transport Mechanism see the Transport Mechanism
Supplement.
ErrorLogNetLocn Optional. This contains the net location that
Consumers should send IOTP Messages that contain
Error Blocks with an Error Component with the
Severity attribute set to either:
o HardError,
o Warning but the Consumer decides to not
continue with the transaction
o TransientError and the transaction has
subsequently timed out.
This attribute:
o must not be present when TradingRole is set to
Consumer role,
o must be present when TradingRole is set to
Merchant, PaymentHandler or DeliveryHandler.
The content of this attribute is dependent on the
Transport Mechanism see the Transport Mechanism
Supplement.
The ErrorLogNetLocn can be used to send error
messages to the software company or some other
Organisation responsible for fixing problems in
the software which sent the incoming message. See
section 7.21.1 Error Processing Guidelines for
more details.
7.6.3 Contact Information Element
This contains information which can be used to contact an
Organisation or an individual. All attributes are optional however at
least one item of contact information should be present. Its
definition is as follows.
<!ELEMENT ContactInfo EMPTY >
<!ATTLIST ContactInfo
xml:lang NMTOKEN #IMPLIED
Tel CDATA #IMPLIED
Fax CDATA #IMPLIED
Email CDATA #IMPLIED
NetLocn CDATA #IMPLIED >
Attributes:
xml:lang Defines the language used by attributes within
this element. See section 3.8 Identifying
Languages.
Tel A telephone number by which the Organisation may
be contacted. Note that this is a text field and
no validation is carried out on it.
Fax A fax number by which the Organisation may be
contacted. Note that this is a text field and no
validation is carried out on it.
Email An email address by which the Organisation may be
contacted. Note that this field should conform to
the conventions for address specifications
contained in [RFC822].
NetLocn A location on the Internet by which information
about the Organisation may be obtained that can be
displayed using a web browser.
The content of this attribute must conform to
[RFC1738].
7.6.4 Person Name Element
This contains the name of an individual person. All fields are
optional however as a minimum either the GivenName or the FamilyName
should be present. Its definition is as follows.
<!ELEMENT PersonName EMPTY >
<!ATTLIST PersonName
xml:lang NMTOKEN #IMPLIED
Title CDATA #IMPLIED
GivenName CDATA #IMPLIED
Initials CDATA #IMPLIED
FamilyName CDATA #IMPLIED >
Attributes:
xml:lang Defines the language used by attributes within
this element. See section 3.8 Identifying
Languages.
Title A distinctive name; personal appellation,
hereditary or not, denoting or implying office
(e.g., judge, mayor) or nobility (e.g., duke,
duchess, earl), or used in addressing or referring
to a person (e.g., Mr, Mrs, Miss)
GivenName The primary or main name by which a person is
known amongst and identified by their family,
friends and acquaintances. Otherwise known as
first name or Christian Name.
Initials The first letter of the secondary names (other
than the Given Name) by which a person is known
amongst or identified by their family, friends and
acquaintances.
FamilyName The name by which family of related individuals
are known. It is typically the part of an
individual's name which is passed on by parents to
their children.
7.6.5 Postal Address Element
This contains an address which can be used, for example, for the
physical delivery of goods, services or letters. Its definition is as
follows.
<!ELEMENT PostalAddress EMPTY >
<!ATTLIST PostalAddress
xml:lang NMTOKEN #IMPLIED
AddressLine1 CDATA #IMPLIED
AddressLine2 CDATA #IMPLIED
CityOrTown CDATA #IMPLIED
StateOrRegion CDATA #IMPLIED
PostalCode CDATA #IMPLIED
Country CDATA #IMPLIED
LegalLocation (True | False) 'False' >
Attributes:
xml:lang Defines the language used by attributes within
this element. See section 3.8 Identifying
Languages.
AddressLine1 The first line of a postal address. e.g., "The
Meadows"
AddressLine2 The second line of a postal address. e.g., "Sandy
Lane"
CityOrTown The city of town of the address. e.g., "Carpham"
StateOrRegion The state or region within a country where the
city or town is placed. e.g., "Surrey"
PostalCode The code known as, for example a post code or zip
code, that is typically used by Postal
Organisations to organise postal deliveries into
efficient sequences. e.g., "KT22 1AA"
Country The country for the address. e.g., "UK"
LegalLocation This identifies whether the address is the
Registered Address for the Organisation. At least
one address for the Organisation must have a value
set to True unless the Trading Role is either
Consumer or DeliverTo.
7.7 Brand List Component
Brand List Components are contained within the Trading Protocol
Options Block (see section 8.1) of the IOTP Transaction. They
contains lists of:
o payment Brands (see also section 11.1 Brand Definitions and Brand
Selection),
o amounts to be paid in the currencies that are accepted or offered
by the Merchant,
o the payment protocols which can be used to make payments with a
Brand, and
o the net locations of the Payment Handlers which accept payment for
a payment protocol
The definition of a Brand List Component is as follows.
<!ELEMENT BrandList (Brand+, ProtocolAmount+,
CurrencyAmount+, PayProtocol+) >
<!ATTLIST BrandList
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
ShortDesc CDATA #REQUIRED
PayDirection (Debit | Credit) #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the Brand
List Component within the IOTP Transaction.
xml:lang Defines the language used by attributes or child
elements within this component, unless overridden
by an xml:lang attribute on a child element. See
section 3.8 Identifying Languages.
ShortDesc A text description in the language defined by
xml:Lang giving details of the purpose of the
Brand List. This information must be displayed to
the receiver of the Brand List in order to assist
with making the selection. It is of particular
benefit in allowing a Consumer to distinguish the
purpose of a Brand List when an IOTP Transaction
involves more than one payment.
PayDirection Indicates the direction in which the payment for
which a Brand is being selected is to be made. Its
values may be:
o Debit The sender of the Payment Request Block
(e.g., the Consumer) to which this Brand List
relates will make the payment to the Payment
Handler, or
o Credit The sender of the Payment Request Block
to which this Brand List relates will receive a
payment from the Payment Handler.
Content:
Brand This describes a Brand. The sequence of the Brand
elements (see section 7.7.1) within the Brand List
does not indicate any preference. It is
recommended that software which processes this
Brand List presents Brands in a sequence which the
receiver of the Brand List prefers.
ProtocolAmount This links a particular Brand to:
o the currencies and amounts in CurrencyAmount
elements that can be used with the Brand, and
o the Payment Protocols and Payment Handlers,
which can be used with those currencies and
amounts, and a particular Brand
CurrencyAmount This contains a currency code and an amount.
PayProtocol This contains information about a Payment Protocol
and the Payment Handler which may be used with a
particular Brand.
The relationships between the elements which make up the content of
the Brand List is illustrated in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Brand List Component
| ProtocolAmountRefs
|-Brand Element-----------------------------
| | |
| - Protocol Brand Element-------- |
| | |
| ProtocolId| |
| | |
|-Protocol Amount Element<----------+-------
| | | |
| | | |
| |CurrencyAmountRefs |Pay |
| | |Protocol |
| v |Ref |
|-Currency Amount Element | |
| Element | |
| | |
-PayProtocolElement<------<--------
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 15 Brand List Element Relationships
Examples of complete Brand Lists are contained in section 11.2 Brand
List Examples.
7.7.1 Brand Element
A Brand Element describes a brand that can be used for making a
payment. One or more of these elements is carried in each Brand List
Component that has the PayDirection attribute set to Debit. Exactly
one Brand Element may be carried in a Brand List Component that has
the PayDirection attribute set to Credit.
<!ELEMENT Brand (ProtocolBrand*, PackagedContent*) >
<!ATTLIST Brand
ID ID #REQUIRED
xml:lang NMTOKEN #IMPLIED
BrandId CDATA #REQUIRED
BrandName CDATA #REQUIRED
BrandLogoNetLocn CDATA #REQUIRED
BrandNarrative CDATA #IMPLIED
ProtocolAmountRefs IDREFS #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID Element identifier, potentially referenced in a
Brand Selection Component contained in a later
Payment Request message and uniquely identifies
the Brand element within the IOTP Transaction.
xml:lang Defines the language used by attributes and
content of this element. See section 3.8
Identifying Languages.
BrandId This contains a unique identifier for the brand
(or promotional brand). It is used to match
against a list of Payment Instruments which the
Consumer holds to determine whether or not the
Consumer can pay using the Brand.
Values of BrandId are managed under the procedure
described in section 12 IANA Considerations.
As values of BrandId are controlled under the