RFC 2801
Internet Open Trading Protocol - IOTP Version 1.0
Pages: 290
Informational
Informational
Part 4 of 9 – Pages 93 to 124
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
procedures defined in section 12 IANA
Considerations user defined values may be
defined.
BrandName This contains the name of the brand, for example
MasterCard Credit. This is the description of the
Brand which is displayed to the consumer in the
Consumers language defined by xml:lang. For
example it might be "American Airlines Advantage
Visa". Note that this attribute is not used for
matching against the payment instruments held by
the Consumer.
BrandLogoNetLocn The net location which can be used to download
the logo for the Organisation. See section
Retrieving Logos (see section 10).
The content of this attribute must conform to
[RFC1738].
BrandNarrative This optional attribute is designed to be used by
the Merchant to indicate some special conditions
or benefit which would apply if the Consumer
selected that brand. For example "5% discount",
"free shipping and handling", "free breakage
insurance for 1 year", "double air miles apply",
etc.
ProtocolAmountRefs Identifies the protocols and related currencies
and amounts which can be used with this Brand.
Specified as a list of ID's of Protocol Amount
Elements (see section 7.7.3) contained within the
Brand List.
ContentSoftwareId See section 14.Glossary.
Content:
ProtocolBrand Protocol Brand elements contain brand information
to be used with a specific payment protocol (see
section 7.7.2)
PackagedContent Optional Packaged Content (see section 3.7)
elements containing information about the brand
which may be used by the payment protocol. The
content of this information is defined in the
supplement for a payment protocol which describes
how the payment protocol works with IOTP.
Example Brand Elements are contained in section 11.2 Brand List
Examples.
7.7.2 Protocol Brand Element
The Protocol Brand Element contains information that is specific to
the use of a particular Protocol with a Brand. Its definition is as
follows.
<!ELEMENT ProtocolBrand (PackagedContent*) >
<!ATTLIST ProtocolBrand
ProtocolId CDATA #REQUIRED
ProtocolBrandId CDATA #REQUIRED >
Attributes:
ProtocolId This must match the value of a ProtocolId
attribute in a Pay Protocol Element (see section
7.7.5).
The values of ProtocolId should be unique within a
Brand Element otherwise there is an error.
ProtocolBrandId This is the Payment Brand Id to be used with a
particular payment protocol. For example, SET and
EMV have their own well defined, yet different,
values for the Brand Id to be used with each
protocol.
The valid values of this attribute are defined in
the supplement for the payment protocol identified
by ProtocolId that describes how the payment
protocol works with IOTP.
Content:
PackagedContent Optional Packaged Content (see section 3.7)
elements containing information about the
protocol/brand which may be used by the payment
protocol. The content of this information is
defined in the supplement for a payment protocol
which describes how the payment protocol works
with IOTP.
7.7.3 Protocol Amount Element
The Protocol Amount element links a Brand to:
o the currencies and amounts in Currency Amount Elements (see
section 7.7.4) that can be used with the Brand, and
o the Payment Protocols and Payment Handlers defined in a Pay
Protocol Element (see section 7.7.5), which can be used with those
currencies and amounts.
Its definition is as follows:
<!ELEMENT ProtocolAmount (PackagedContent*) >
<!ATTLIST ProtocolAmount
ID ID #REQUIRED
PayProtocolRef IDREF #REQUIRED
CurrencyAmountRefs IDREFS #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID Element identifier, potentially referenced in a
Brand element; or in a Brand Selection Component
contained in a later Payment Request message
which uniquely identifies the Protocol Amount
element within the IOTP Transaction.
PayProtocolRef Contains an Element Reference (see section 3.5) that refers to the Pay Protocol Element (see section 7.7.5) that contains the Payment Protocol and Payment Handlers that can be used with the Brand. CurrencyAmountRefs Contains a list of Element References (see section 3.5) that refer to the Currency Amount Element (see section 7.7.4) that describes the currencies and amounts that can be used with the Brand. ContentSoftwareId See section 14. Glossary. Content: PackagedContent Optional Packaged Content (see section 3.7) elements containing information about the protocol amount which may be used by the payment protocol. The content of this information is defined in the supplement for a payment protocol which describes how the payment protocol works with IOTP. Examples of Protocol Amount Elements are contained in section 11.2 Brand List Examples.7.7.4 Currency Amount Element
A Currency Amount element contains: o a currency code (and its type), and o an amount. One or more of these elements is carried in each Brand List Component. Its definition is as follows: <!ELEMENT CurrencyAmount EMPTY > <!ATTLIST CurrencyAmount ID ID #REQUIRED Amount CDATA #REQUIRED CurrCodeType NMTOKEN 'ISO4217-A' CurrCode CDATA #REQUIRED > Attributes: ID Element identifier, potentially referenced in a Brand element; or in a Brand Selection Component
contained in a later Payment Request message which
uniquely identifies the Currency Amount Element
within the IOTP Transaction.
Amount Indicates the amount to be paid in whole and
fractional units of the currency. For example
$245.35 would be expressed "245.35". Note that
values smaller than the smallest denomination are
allowed. For example one tenth of a cent would be
"0.001".
CurrCodeType Indicates the domain of the CurrCode. This
attribute is included so that the currency code
may support non-standard "currencies" such as
frequent flyer points, trading stamps, etc. Its
values may be:
o ISO4217-A (the default) indicates the currency
code is a three character alphabetic currency
code that conforms to [ISO 4217]
o IOTP indicates that values of CurrCode are
managed under the procedure described in
section 12 IANA Considerations
CurrCode A code which identifies the currency to be used in
the payment. The domain of valid currency codes is
defined by CurrCodeType
As values of CurrCodeType are managed under the
procedure described in section 12 IANA
Considerations user defined values of CurrCodeType
may be defined.
Examples of Currency Amount Elements are contained in section 11.2
Brand List Examples.
7.7.5 Pay Protocol Element
A Pay Protocol element specifies details of a Payment Protocol and
the Payment Handler that can be used with a Brand. One or more of
these elements is carried in each Brand List.
<!ELEMENT PayProtocol (PackagedContent*) >
<!ATTLIST PayProtocol
ID ID #REQUIRED
xml:lang NMTOKEN #IMPLIED
ProtocolId NMTOKEN #REQUIRED
ProtocolName CDATA #REQUIRED
ActionOrgRef NMTOKEN #REQUIRED
PayReqNetLocn CDATA #IMPLIED
SecPayReqNetLocn CDATA #IMPLIED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID Element identifier, potentially referenced in a
Brand element; or in a Brand Selection Component
contained in a later Payment Request message which
uniquely identifies the Pay Protocol element
within the IOTP Transaction.
xml:lang Defines the language used by attributes and
content of this element. See section 3.8
Identifying Languages.
ProtocolId Consists of a protocol name and version. For
example "SETv1.0".
The values of ProtocolId are defined by the
payment scheme/method owners in the document that
describes how to encapsulate a payment protocol
within IOTP.
ProtocolName A narrative description of the payment protocol
and its version in the language identified by
xml:lang. For example "Secure Electronic
Transaction Version 1.0". Its purpose is to help
provide information on the payment protocol being
used if problems arise.
ActionOrgRef An Element Reference (see section 3.5) to the
Organisation Component for the Payment Handler for
the Payment Protocol.
PayReqNetLocn The Net Location indicating where an unsecured
Payment Request message should be sent if this
protocol choice is used.
The content of this attribute is dependent on the
Transport Mechanism (such must conform to
[RFC1738].
SecPayReqNetLocn The Net Location indicating where a secured
Payment Request message should be sent if this
protocol choice is used.
A secured payment involves the use of a secure
channel such as [SSL/TLS] in order to communicate
with the Payment Handler.
The content of this attribute must conform to
[RFC1738]. See also See section 3.9 Secure and
Insecure Net Locations.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Optional Packaged Content elements (see section
3.7) containing information about the protocol
which is used by the payment protocol. The content
of this information is defined in the supplement
for a payment protocol which describes how the
payment protocol works with IOTP. An example of
its use could be to include a payment protocol
message.
Examples of Pay Protocol Elements are contained in section 11.2 Brand
List Examples.
7.8 Brand Selection Component
A Brand Selection Component identifies the choice of payment brand,
payment protocol and the Payment Handler. This element is used:
o in Payment Request messages within Baseline Purchase and Baseline
Value Exchange IOTP Transactions to identify the brand, protocol
and payment handler for a payment, or
o to, optionally, inform a merchant in a purchase of the payment
brand being used so that the offer and order details can be
amended accordingly.
In Baseline IOTP, the integrity of Brand Selection Components is not
guaranteed. However, modification of Brand Selection Components can
only cause denial of service if the payment protocol itself is secure
against message modification, duplication, and swapping attacks.
The definition of a Brand Selection Component is as follows.
<!ELEMENT BrandSelection (BrandSelBrandInfo?,
BrandSelProtocolAmountInfo?,
BrandSelCurrencyAmountInfo?) >
<!ATTLIST BrandSelection
ID ID #REQUIRED
BrandListRef NMTOKEN #REQUIRED
BrandRef NMTOKEN #REQUIRED
ProtocolAmountRef NMTOKEN #REQUIRED
CurrencyAmountRef NMTOKEN #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the Brand
Selection Component within the IOTP Transaction.
BrandListRef The Element Reference (see section 3.5) of the
Brand List Component from which a Brand is being
selected
BrandRef The Element Reference of a Brand element within
the Brand List Component that is being selected
that is to be used in the payment.
ProtocolAmountRef The Element Reference of a Protocol Amount element
within the Brand List Component which is to be
used when making the payment.
CurrencyAmountRef The Element Reference of a Currency Amount element
within the Brand List Component which is to be
used when making the payment.
Content:
BrandSelBrandInfo, This contains any additional data that
BrandSelProtocolAmountInfo, may be required by a particular payment
BrandSelCurrencyAmountInfo brand or protocol. See sections 7.8.1,
7.8.2, and 7.8.3.
The following rules apply:
o the BrandListRef must contain the ID of a Brand List Component in
the same IOTP Transaction
o every Brand List Component in the Trading Protocol Options Block
(see section 8.1) must be referenced by one and only one Brand
Selection Component
o the BrandRef must refer to the ID of a Brand contained within the
Brand List Component referred to by BrandListRef
o the ProtocolAmountRef must refer to one of the Element IDs listed
in the ProtocolAmountRefs attribute of the Brand element
identified by BrandRef
o the CurrencyAmountRef must refer to one of the Element IDs listed
in the CurrencyAmountRefs attribute of the Protocol Amount Element
identified by ProtocolAmountRef.
An example of a Brand Selection Component is included in 11.2 Brand
List Examples.
7.8.1 Brand Selection Brand Info Element
The Brand Selection Brand Info Element contains any additional data
that may be required by a particular payment brand. See the IOTP
payment method supplement for a description of how and when it used.
<!ELEMENT BrandSelBrandInfo (PackagedContent+) >
<!ATTLIST BrandSelBrandInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Packaged Content elements (see section 3.7) that
contain additional data that may be required by a
particular payment brand. See the payment method
supplement for IOTP for rules on how this is used.
7.8.2 Brand Selection Protocol Amount Info Element
The Brand Selection Protocol Amount Info Element contains any
additional data that is payment protocol specific that may be
required by a particular payment brand or payment protocol. See the
IOTP payment method supplement for a description of how and when it
used.
<!ELEMENT BrandSelProtocolAmountInfo (PackagedContent+) >
<!ATTLIST BrandSelProtocolAmountInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes: ContentSoftwareId See section 14. Glossary. Content: PackagedContent Packaged Content elements (see section 3.7) that may contain additional data that may be required by a particular payment brand. See the payment method supplement for IOTP for rules on how this is used.7.8.3 Brand Selection Currency Amount Info Element
The Brand Selection Currency Amount Info Element contains any additional data that is payment brand and currency specific that may be required by a particular payment brand. See the IOTP payment method supplement for a description of how and when it used. <!ELEMENT BrandSelCurrencyAmountInfo (PackagedContent+) > <!ATTLIST BrandSelCurrencyAmountInfo ID ID #REQUIRED ContentSoftwareId CDATA #IMPLIED > Attributes: ContentSoftwareId See section 14. Glossary. Content: PackagedContent Packaged Content elements (see section 3.7) that contain additional data relating to the payment brand and currency. See the payment method supplement for IOTP for rules on how this is used.7.9 Payment Component
A Payment Component contains information used to control how a payment is carried out. Its provides information on: o the times within which a Payment with a Payment Handler may be started o a reference to the Brand List (see section 7.7) which identifies the Brands, protocols, currencies and amounts which can be used to make a payment o whether or not a payment receipt will be provided
o whether another payment precedes this payment.
Its definition is as follows.
<!ELEMENT Payment EMPTY >
<!ATTLIST Payment
ID ID #REQUIRED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
BrandListRef NMTOKEN #REQUIRED
SignedPayReceipt (True | False) #REQUIRED
StartAfterRefs NMTOKENS #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Payment Component within the IOTP Transaction.
OkFrom The date and time in [UTC] format after which a
Payment Handler may accept for processing a
Payment Request Block (see section 8.7) containing
the Payment Component.
OkTo The date and time in [UTC] format before which a
Payment Handler may accept for processing a
Payment Request Block containing the Payment
Component.
BrandListRef An Element Reference (see section 3.5) of a Brand
List Component (see section 7.7) within the TPO
Trading Block for the IOTP Transaction. The Brand
List identifies the alternative ways in which the
payment can be made.
SignedPayReceipt Indicates whether or not the Payment Response
Block (see section 8.9) generated by the Payment
Handler for the payment must be digitally signed.
StartAfter Contains Element References (see section 3.5) of
other Payment Components which describe payments
which must be complete before this payment can
start. If no StartAfter attribute is present then
there are no dependencies and the payment can
start immediately
(next page on part 5)