RFC2801 - Internet Open Trading Protocol - IOTP Version 1.0(3)
o Web the goods will be delivered
electronically in the Delivery Note Component
o Email the goods will be delivered
electronically by e-mail
Values of DelivMethod are managed under the
procedure described in section 12 IANA
Considerations which allows user defined codes to
be defined.
DelivToRef The Element Reference (see section 3.4) of an
Organisation Component within the IOTP
Transaction which has a role of DelivTo. The
information in this block is used to determine
where delivery is to be made. It must be
compatible with DelivMethod. Specifically if the
DelivMethod is:
o Post, then the there must be a Postal Address
Element containing sufficient information for
a postal delivery,
o Web, then there are no specific requirements.
The information will be sent in a web page
back to the Consumer
o Email, then there must be Contact Information
Element with a valid e-mail address
DelivReqNetLocn This contains the Net Location to which an
unsecured Delivery Request Block (see section
8.10) which contains the Delivery Component
should be sent.
The content of this attribute is dependent on the
Transport Mechanism and must conform to
[RFC1738].
SecDelivReqNetLocn This contains the Net Location to which a secured
Delivery Request Block (see section 8.10) which
contains the Delivery Component should be sent.
A secured delivery request involves the use of a
secure channel such as [SSL/TLS] in order to
communicate with the Payment Handler.
The content of this attribute is dependent on the
Transport Mechanism must conform to [RFC1738].
See also Section 3.9 Secure and Insecure Net
Locations.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Additional information about the delivery as one
or more Packaged Content elements (see section
3.7) provided to the Delivery Handler by the
merchant.
7.14 Consumer Delivery Data Component
A Consumer Delivery Data Component is used by a Consumer to specify
an identifier that can be used by the Consumer to identify the
Delivery.
Its definition is as follows:
<!ELEMENT ConsumerDeliveryData EMPTY >
<!ATTLIST ConsumerDeliveryData
ID ID #REQUIRED
ConsumerDeliveryId CDATA #REQUIRED>
Attributes:
ID An identifier which uniquely identifies the
Consumer Delivery Data Component within the IOTP
Transaction.
ConsumerDeliveryId An identifier specified by the Consumer which, if
returned by the Delivery Handler will enable the
Consumer to identify which Delivery is being
referred to.
7.15 Delivery Note Component
A Delivery Note contains delivery instructions about the delivery of
goods or services or potentially the actual Delivery Information
itself. It is information which the person or Organisation receiving
the Delivery Note can use when delivery occurs.
For interoperability, the Delivery Note Component Packaged Content
should support both Plain Text, HTML and XML.
It's definition is as follows.
<!ELEMENT DeliveryNote (PackagedContent+) >
<!ATTLIST DeliveryNote
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
DelivHandlerDelivId CDATA #IMPLIED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Delivery Note 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.
DelivHandlerDelivId An optional identifier specified by the Delivery
Handler which, if returned by the Consumer in
another Delivery Component, or by other means,
will enable the Delivery Handler to identify
which Delivery is being referred to. It is
required on every Delivery Component apart from
the one contained in a Delivery Request Block.
An example use of this attribute is to contain a
delivery tracking number.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Contains actual delivery note information as one
or more Packaged Content elements (see section
3.7).
Note: If the content of the Delivery Message is a Mime message then
the Delivery Note may trigger an application which causes the actual
delivery to occur.
7.16 Status Component
A Status Component contains status information about the business
success or failure (see section 4.2) of a process.
Its definition is as follows.
<!ELEMENT Status EMPTY >
<!ATTLIST Status
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
StatusType NMTOKEN #REQUIRED
ElRef NMTOKEN #IMPLIED
ProcessState (NotYetStarted InProgress
CompletedOk Failed ProcessError) #REQUIRED
CompletionCode NMTOKEN #IMPLIED
ProcessReference CDATA #IMPLIED
StatusDesc CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the Status
Component within the IOTP Transaction.
xml:lang Defines the language used by attributes within
this component. See section 3.8 Identifying
Languages.
StatusType Indicates the type of Document Exchange which the
Status is reporting on. It may be set to either
Offer, Payment, Delivery, Authentication or
Undefined.
Undefined means that the type of document exchange
could not be identified. This is caused by an
error in the initial input message of the
exchange.
Values of StatusType are managed under the
procedure described in section 12 IANA
Considerations which also allows user defined
values of StatusType to be defined.
ElRef If the StatusType is not set to Undefined then
ElRef contains an Element Reference (see section
3.5) to the Component for which the Status is
being described. It must refer to either:
o an Order Component (see section 7.5), if the
StatusType is Offer,
o a Payment Component (see section 7.9), if the
StatusType is Payment, or
o a Delivery Component (see section 7.13), if
the StatusType is Delivery
o an Authentication Request Component (see
section 7.2) if the StatusType is
Authentication.
ProcessState Contains a State Code which indicates the current
state of the process being carried out. Valid
values for ProcessState are:
o NotYetStarted. A Request Block has been
received but the process has not yet started
o InProgress. Processing of the Request Block
has started but it is not yet complete
o CompletedOk. The processing of the Request
Block has completed successfully without any
errors
o Failed. The processing of the Request Block
has failed because of a Business Error (see
section 4.2)
o ProcessError. This value is only used when the
Status Component is being used in connection
with an Inquiry Request Trading Block (see
section 8.12). It indicates there was a
Technical Error (see section 4.1) in the
Request Block which is being processed or some
internal processing error.
Note that this code reports on the processing of a
Request Block. Further, asynchronous processing
may occur after the Response Block associated with
the Process has been sent.
CompletionCode Indicates how the process completed. Valid values
for the CompletionCode are given below together
with the conditions when it must be present and
indications on when recovery from failures are
possible.
A CompletionCode is a maximum of 14 characters
long.
ProcessReference This optional attribute holds a reference for the
process whose status is being reported. It may
hold the following values:
o when StatusType is set to Offer, it should
contain the OrderIdentifier from the Order
Component
o when StatusType is set to Payment, it should
contain the PaymentHandlerPayId from the
Payment Scheme Data Component
o when StatusType is set to Delivery, it should
contain the DelivHandlerDelivId from the
Delivery Note Component
o when StatusType is set to Authentication, it
should contain the AuthenticationId from the
Authentication Request Component
This attribute should be absent in the Inquiry
Request message when the Consumer has not been
given such a reference number by the IOTP Service
Provider.
This attribute can be used inside an Inquiry
Response Block (see section 8.13) to give the
reference number for a transaction which has
previously been unavailable.
For example, the package tracking number might not
be assigned at the time a delivery response was
received. However, if the Consumer issues a
Baseline Transaction Status Inquiry later, the
Delivery Handler can put the package tracking
number into this attribute in the Inquiry Response
message and send it back to the Consumer.
StatusDesc An optional textual description of the current
status of the process in the language identified
by xml:lang.
7.16.1 Offer Completion Codes
The Completion Code is only required if the ProcessState attribute is
set to Failed. The following table contains the valid values for the
CompletionCode that may be used and indicates whether or not recovery
might be possible. It is recommended that the StatusDesc attribute is
used to provide further explanation where appropriate.
Value Description
AuthError Authentication Error. The check of the
Authentication Response which was carried out has
failed.
Recovery may be possible by the Consumer re-
submitting a new Authentication Response Block with
corrected information.
ConsCancelled Consumer Cancelled. The Consumer decides to cancel
the transaction for some reason. This code is only
valid in a Status Component contained in a Cancel
Block or an Inquiry Response Block.
No recovery possible.
MerchCancelled Offer Cancelled. The Merchant declines to generate
an offer for some reason and cancels the
transaction. This code is only valid in a Status
Component contained in a Cancel Block or an Inquiry
Response Block.
No recovery possible.
Unspecified Unspecified error. There is some unknown problem or
error which does not fall into one of the other
CompletionCodes.
No recovery possible.
TimedOutRcvr Recoverable Time Out. Messages were resent but no
response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
Recovery is possible if the last message from the
other Trading Role is received again.
TimedOutNoRcvr Non Recoverable Time Out. Messages were resent but
no response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
No recovery possible.
7.16.2 Payment Completion Codes
The CompletionCode is only required if the ProcessState attribute is
set to Failed. The following table contains the valid values for the
CompletionCode that may be used and indicates where recovery may be
possible. It is recommended that the StatusDesc attribute is used by
individual payment schemes to provide further explanation where
appropriate.
Value Description
BrandNotSupp Brand not supported. The payment brand is not
supported by the Payment Handler.
See below for recovery options.
CurrNotSupp Currency not supported. The currency in which the
payment is to be made is not supported by either
the Payment Instrument or the Payment Handler.
If the payment is Brand Independent, then the
Consumer may recover by selecting a different
currency, if available, or a different brand. Note
that this may involve a different Payment Handler.
ConsCancelled Consumer Cancelled. The Consumer decides to cancel
the payment for some reason. This code is only
valid in a Status Component contained in a Cancel
Block or an Inquiry Response Block.
Recovery is not possible.
PaymtCancelled Payment Cancelled. The Payment Handler declines to
complete the payment for some reason and cancels
the transaction. This code is only valid in a
Status Component contained in a Cancel Block or an
Inquiry Response Block.
See below for recovery options.
AuthError Authentication Error. The Payment Scheme specific
authentication check which was carried out has
failed.
Recovery may be possible. See the payment scheme
supplement to determine what is allowed.
InsuffFunds Insufficient funds. There are insufficient funds
available for the payment to be made.
See below for recovery options.
InstBrandInvalid Payment Instrument not valid for Brand. A Payment
Instrument is being used which does not correspond
with the Brand selected. For example a Visa credit
card is being used when MasterCard was selected as
the Brand.
See below for recovery options.
InstNotValid Payment instrument not valid for trade. The
Payment Instrument cannot be used for the proposed
type of trade, for some reason.
See below for recovery options.
BadInstrument Bad instrument. There is a problem with the
Payment Instrument being used which means that it
is unable to be used for the payment.
See below for recovery options.
Unspecified Unspecified error. There is some unknown problem
or error which does not fall into one of the other
CompletionCodes. The StatusDesc attribute should
provide the explanation of the cause.
See below for recovery options.
TimedOutRcvr Recoverable Time Out. Messages were resent but no
response received. The document exchange has
therefore "Timed Out". This code is only valid on
a Transaction Inquiry.
Recovery is possible if the last message from the
other Trading Role is received again.
TimedOutNoRcvr Non Recoverable Time Out. Messages were resent but
no response received. The document exchange has
therefore "Timed Out". This code is only valid on
a Transaction Inquiry.
No recovery possible.
If the Payment is Brand Independent, then recovery may be possible
for some values of the Completion Code, by the Consumer selecting
either a different payment brand or a different payment instrument
for the same brand. Note that this might involve a different Payment
Handler. The codes to which this applies are: BrandNotSupp,
PaymtCancelled, InsuffFunds, InstBrandInvalid, InstNotValid,
BadInstrument and Unspecified.
Recovery from Payments associated with Brand Dependent purchases is
only possible, if the Brand Selection component sent by the Merchant
to the Consumer does not change. In practice this means that the same
Brand, Protocol Amount and PayProtocol elements must be used. All
that can change is the Payment Instrument. Any other change will
invalidate the Merchant's Offer as a changed selection will
invalidate the Offer Response.
7.16.3 Delivery Completion Codes
The following table contains the valid values for the CompletionCode
attribute for a Delivery. It is recommended that the StatusDesc
attribute is used to provide further explanation where appropriate.
Value Description
BackOrdered Back Ordered. The goods to be delivered are on order
but they have not yet been received. Shipping will be
arranged when they are received. This is only valid
if ProcessState is CompletedOk.
Recovery is not possible.
PermNotAvail Permanently Not Available. The goods are permanently
unavailable and cannot be re-ordered. This is only
valid if ProcessState is Failed.
Recovery is not possible.
TempNotAvail Temporarily Not Available. The goods are temporarily
unavailable and may become available if they can be
ordered. This is only valid if ProcessState is
CompletedOk.
Recovery is not possible.
ShipPending Shipping Pending. The goods are available and are
scheduled for shipping but they have not yet been
shipped. This is only valid if ProcessState is
CompletedOk.
Recovery is not possible.
Shipped Goods Shipped. The goods have been shipped.
Confirmation of delivery is awaited. This is only
valid if ProcessState is CompletedOk.
Recovery is not possible.
ShippedNoConf Shipped - No Delivery Confirmation. The goods have
been shipped but it is not possible to confirm
delivery of the goods. This is only valid if
ProcessState is CompletedOk.
Recovery is not possible.
ConsCancelled Consumer Cancelled. The Consumer decides to cancel
the delivery for some reason. This code is only valid
in a Status Component contained in a Cancel Block or
an Inquiry Response Block.
Recovery is not possible.
DelivCancelled Delivery Cancelled. The Delivery Handler declines to
complete the Delivery for some reason and cancels the
transaction. This code is only valid in a Status
Component contained in a Cancel Block or an Inquiry
Response Block.
Recovery is not possible.
Confirmed Confirmed. All goods have been delivered and
confirmation of their delivery has been received.
This is only valid if ProcessState is CompletedOk.
Recovery is not possible.
Unspecified Unspecified error. There is some unknown problem or
error which does not fall into one of the other
CompletionCodes. The StatusDesc attribute should
provide the explanation of the cause.
Recovery is not possible.
TimedOutRcvr Recoverable Time Out. Messages were resent but no
response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
Recovery is possible if the last message from the
other Trading Role is received again.
TimedOutNoRcvr Non Recoverable Time Out. Messages were resent but no
response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
No recovery possible.
Note: Recovery from failed, or partially completed deliveries is not
possible. The Consumer should use the Transaction Status Inquiry
Transaction (see section 9.2.1) to determine up-to- date information
on the current state.
7.16.4 Authentication Completion Codes
The Completion Code is only required if the ProcessState attribute is
set to Failed. The following table contains the valid values for the
CompletionCode that may be used. It is recommended that the
StatusDesc attribute is used to provide further explanation where
appropriate.
Value Description
AutEeCancel Authenticatee Cancel. The Organisation being
authenticated declines to be authenticated for some
reason. This could be, for example because the
signature on an Authentication Request was invalid or
the Authenticator was not known or acceptable to the
Authenticatee.
Recovery is not possible.
AutOrCancel Authenticator Cancel. The Organisation requesting
authentication declines to validate the
Authentication Response received for some reason and
cancels the transaction.
Recovery is not possible.
NoAuthReq Authentication Request Not Available. The
Authenticatee does not have the data that must be
provided so that they may be successfully
authenticated. For example a password may have been
forgotten, the Authenticatee has not yet become a
member, or a smart card token is not present.
Recovery is not possible
AuthFailed Authentication Failed. The Authenticator checked the
Authentication Response but the authentication failed
for some reason. For example a password may have been
incorrect.
Recovery may be possible by the Authenticatee re-
sending a revised Authentication Response with
corrected data.
TradRolesIncon Trading Roles Inconsistent. The Trading Roles
contained within the TradingRoleList attribute of the
Trading Role Information Request Component (see
section 7.4) are inconsistent with the Trading Role
which the Authenticatee is taking in the IOTP
Transaction or is able to take. Examples of
inconsistencies include:
o asking a PaymentHandler for DeliveryHandler
information
o asking a Consumer for Merchant information
Recovery may be possible by the Authenticator re-
sending a revised Authentication Request Block with
corrected information.
Unspecified Unspecified error. There is some unknown problem or
error which does not fall into one of the other
CompletionCodes.
Recovery is not possible.
TimedOutRcvr Recoverable Time Out. Messages were resent but no
response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
Recovery is possible if the last message from the
other Trading Role is received again.
TimedOutNoRcvr Non Recoverable Time Out. Messages were resent but no
response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
No recovery possible.
7.16.5 Undefined Completion Codes
The Completion Code is only required if the ProcessState attribute is
set to Failed. The following table contains the valid values for the
CompletionCode that may be used. It is recommended that the
StatusDesc attribute is used to provide further explanation where
appropriate.
Value Description
InMsgHardError Input Message Hard Error. The type of Request Block
could not be identified or was inconsistent.
Therefore no single Document Exchange could be
identified. This will cause a Hard Error in the
transaction
7.16.6 Transaction Inquiry Completion Codes
The Completion Code is only required if the ProcessState attribute is
set to Failed. The following table contains the valid values for the
CompletionCode that may be used. It is recommended that the
StatusDesc attribute is used to provide further explanation where
appropriate.
Value Description
UnAuthReq Unauthorised Request. The recipient of the
Transaction Status Request declines to respond to the
request.
7.17 Trading Role Data Component
The Trading Role Data Component contains opaque data which needs to
be communicated between the Trading Roles involved in an IOTP
Transaction.
Trading Role Components identify:
o the Organisation that generated the component, and
o the Organisation that is to receive it.
They are first generated and included in a "Response" Block, and then
copied to the appropriate "Request" Block. For example a Payment
Handler might need to inform a Delivery Handler that a credit card
payment had been authorised but not captured. There may also be other
information that the Payment Handler has generated where the format
is privately agreed with the Delivery Handler which needs to be
communicated. In another example a Merchant might need to provide a
Payment Handler with some specific information about a Consumer so
that consumer can acquire double loyalty points with the payment.
Its definition is as follows.
<!ELEMENT TradingRoleData (PackagedContent+) >
<!ATTLIST TradingRoleData
ID ID #REQUIRED
OriginatorElRef NMTOKEN #REQUIRED
DestinationElRefs NMTOKENS #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Trading Role Data Component within the IOTP
Transaction.
OrginatorElRef Contains an element reference to the Organisation
Component of the Organisation that created the
Trading Role Data Component and included it in a
"Response" Block (e.g., an Offer Response or a
Payment Response Block).
DestinationElRefs Contains element references to the Organisation
Components of the Organisations that are to
receive the Trading Role Data Component in a
"Request" Block (e.g., either a Payment Request or
a Delivery Request Block).
Content:
PackagedContent This contains the data which is to be sent between
the various Trading Roles as one or more
PackagedContent elements see section 3.7.
7.17.1 Who Receives a Trading Role Data Component
The rules for deciding what to do with Trading Role Data Components
are described below.
o whenever a Trading Role Data Component is received in a "Response"
block identify the Organisation Components of the Organisations
that are to receive it as identified by the DestinationElRefs
attribute.
o whenever a "Request" Block is being sent, check to see if it is
being sent to one of the Organisations identified by the
DestinationElRefs attribute. If it is then include in the
"Request" block:
- the Trading Role Data Component as well as,
- the Organisation Component of the Organisation identified by
the OriginatorElRef attribute (if not already present)
7.18 Inquiry Type Component
The Inquiry Type Component contains the information which indicates
the type of process that is being inquired upon. Its definition is as
follows.
<!ELEMENT InquiryType EMPTY >
<!ATTLIST InquiryType
ID ID #REQUIRED
Type NMTOKEN #REQUIRED
ElRef NMTOKEN #IMPLIED
ProcessReference CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Inquiry Type Component within the IOTP
Transaction.
Type Contains the type of inquiry. Valid values for
Type are:
o Offer. The inquiry is about the status of an
offer and is addressed to the Merchant.
o Payment. The inquiry is about the status of a
payment and is addressed to the Payment
Handler.
o Delivery. The inquiry is about the status of a
delivery and addressed to the Delivery Handler.
ElRef Contains an Element Reference (see section 3.5) to
the component to which this Inquiry Type Component
applies. That is,
o TPO Block when Type is Offer
o Payment Component when Type is Payment
o Delivery Component when Type is Delivery
ProcessReference Optionally contains a reference to the process
being inquired upon. It should be set if the
information is available. For the definition of
the values it may contain, see the
ProcessReference attribute of the Status Component
(see section 7.16).
7.19 Signature Component
Note: Definitions of the XML structures for signatures and
certificates are described in the document titled "Digital Signatures
for the Internet Open Trading Protocol" by Kent Davidson and Yoshiaki
Kawatsura published at the same time as this document - see
[IOTPDSIG].
In the future it is anticipated that future versions of IOTP will
adopt a whatever method for digitally signing XML becomes the
standard.
Each Signature Component digitally signs one or more Blocks or
Components including other Signature Components.
The Signature Component:
o contains digests of one or more Blocks or Components in one or
more IOTP Messages within the same IOTP Transaction and places the
result in a Digest Element
o concatenates these Digest elements with other information on the
type of signature, the originator and potential recipients of the
signature and details of the signature algorithms being used and
places them in a Manifest element, and
o signs the Manifest element using the optional certificate
identified in the Certificate element within the Signature Block
placing the result in a Value element within a Signature Component
Note that there may be multiple Value elements that contain
signatures of a Manifest Element.
A Signature Component can be one of four types either:
o an Offer Response Signature,
o a Payment Response Signature,
o a Delivery Response Signature, or
o an Authentication Response Signature.
For a general explanation of signatures see section 6 Digital
Signatures.
7.19.1 IOTP usage of signature elements and attributes
Definitions of the elements and attributes are contained in
[IOTPDSIG]. The following contains additional information that
describes how these elements and attributes are used by IOTP.
SIGNATURE ELEMENT
The ID attribute is mandatory.
MANIFEST ELEMENT
The optional LocatorHrefBase attribute contains text which should be
concatenated before the text contained in the LocatorHREF attribute
of all Digest elements within the Manifest.
Its purpose is to reduce the size of LocatorHREF attribute values
since the first part of the LocatorHREF attributes in the same
signature are likely to be the same.
Typically, within IOTP, it will contain all the characters in a
LocatorHref attribute up to the sharp ("#") character (see
immediately below).
ALGORITHM AND PARAMETER ELEMENTS
The algorithm element identifies the algorithms used in generating
the signature. The type of the algorithm is defined by the value of
the Type attribute which indicates if it is to be used as a Digest
algorithm, a Signature algorithm or a Key Agreement algorithm.
The following Digest algorithms must be implemented:
o a [DOM-HASH] algorithm. This is identified by setting the Name
attribute of the Algorithm element to "urn:ibm:dom-hash"
o a [SHA1] algorithm. This is identified by setting the Name
attribute of the Algorithm element to "urn:fips:sha1", and
o a [MD5] algorithm. This is identified by setting the Name
attribute of the Algorithm element to "urn:rsa:md5"
o The following Signature algorithms must be implemented:
o a [DSA] algorithm. This is identified by setting the Name
attribute of the Algorithm element to "urn:us.gov:dsa"
o a [HMAC] algorithm. This is identified by setting the Name
attribute of the Algorithm element to "urn:ibm:hmac"
It is recommended that the following Signature algorithm is also
implemented:
o a [RSA] algorithm. This is identified by setting the Name
attribute of the Algorithm element to "urn:rsa:rsa"
In addition other payment scheme specific algorithms may be used. In
this case the value of the name attribute to use is specified in the
payment scheme supplement for that algorithm.
One algorithm may make use of other algorithms by use of the
Parameter element, for example:
<Algorithm ID=A1 type="digest" name="urn:ibm:dom-hash">
<Parameter type='AlgorithmRef'>A2</Parameter>
</Algorithm>
<Algorithm ID=A2 type="digest" name="urn:fips:sha1">
</Algorithm>
<Algorithm ID=A3 type="signature" name="urn:ibm:hmac">
<Parameter type='AlgorithmRef'>A1</Parameter>
</Algorithm>
DIGEST ELEMENT
The LocatorHREF attribute identifies the IOTP element which is being
digitally signed. Specifically it consists of:
o the value of the IotpTransId attribute of the Transaction ID
Component, followed by:
o a sharp character, i.e. "#", followed by
o an Element Reference (see section 3.5) to the element within the
IOTP Transaction which is the subject of the digest.
Before analysing the structure of the LocatorHREF attribute, it must
be concatenated with the value of the LocatorHrefBase attribute of
the Manifest element (see immediately above).
ATTRIBUTE ELEMENT
There must be one and only one Attribute Element that contains a Type
attribute with a value of IOTP Signature Type and with content set to
either: OfferResponse, PaymentResponse, DeliveryResponse,
AuthenticationRequest, AuthenticationResponse, PingRequest or
PingResponse; depending on the type of the signature.
Values of the content of the Attribute element are controlled under
the procedures defined in section 12 IANA Considerations which also
allows user defined values to be defined.
The Critical attribute must be set to true.
ORIGINATORINFO ELEMENT
The OriginatorRef attribute of the OriginatorInfo element must always
be present and contain an Element Reference (see section 3.5) to the
Organisation Component of the Organisation that generated the
Signature Component.
RECIPIENTINFO ELEMENT
The RecipientRefs attribute contains a list of Element References
(see section 3.5), that point to the Organisations that might need to
validate the signature. For details see below.
7.19.2 Offer Response Signature Component
The Manifest Element of a signature which has a type of OfferResponse
should contain Digest elements for the following Components:
o the Transaction Id Component (see section 3.3.1) of the IOTP
message that contains the Offer Response Signature
o the Transaction Reference Block (see section 3.3) of the IOTP
Message that contains the Offer Response Signature
o from the TPO Block:
- the Protocol Options Component
- each of the Organisation Components
- each of the Brand List Components
o optionally, all the Brand Selection Components if they were sent
to the Merchant in a TPO Selection Block
o from the Offer Response Block:
- the Order Component
- each of the Payment Components
- the Delivery Component
- each of the Authentication Request Components
- any Trading Role Data Components
The Offer Response Signature should also contain Digest elements for
the components that describe each of the Organisations that may or
will need to verify the signature. This involves:
o if the Merchant has received a TPO Selection Block containing
Brand Selection Components, then generate a Digest element for the
Payment Handler identified by the Brand Selection Component and
the Delivery Handler identified by the Delivery Component. See
section 6.3.1 Check Request Block sent Correct Organisation for a
description of how this can be done.
o if the Merchant is not expecting to receive a TPO Selection Block
then generate a Digest element for the Delivery Handler and all
the Payment Handlers that are involved.
7.19.3 Payment Receipt Signature Component
The Manifest Element of the Payment Receipt Signature Component
should contain Digest Elements for the following Components:
o the Transaction Id Component (see section 3.3.1) of the IOTP
message that contains the Payment Receipt Signature
o the Transaction Reference Block (see section 3.3) of the IOTP
Message that contains the Payment Receipt Signature
o the Offer Response Signature Component
o the Payment Receipt Component
o the Payment Note Component
o the Status Component
o the Brand Selection Component.
o any Trading Role Data Components
7.19.4 Delivery Response Signature Component
The Manifest Element of the Delivery Response Signature Component
should contain Digest Elements for the following Components:
o the Transaction Id Component (see section 3.3.1) of the IOTP
message that contains the Delivery Response Signature
o the Transaction Reference Block (see section 3.3) of the IOTP
Message that contains the Delivery Response Signature
o the Consumer Delivery Data component contained in the preceding
Delivery Request (if any)
o the Signature Components contained in the preceding Delivery
Request (if any)
o the Status Component
o the Delivery Note Component
7.19.5 Authentication Request Signature Component
The Manifest Element of the Authentication Request Signature
Component should contain Digest Elements for the following
Components:
o the Transaction Reference Block (see section 3.3) for the IOTP
Message that contains information that describes the IOTP Message
and IOTP Transaction
o the Transaction Id Component (see section 3.3.1) which globally
uniquely identifies the IOTP Transaction
o the following components of the TPO Block :
- the Protocol Options Component
- the Organisation Component
o the following components of the Authentication Request Block:
- the Authentication Request Component(s) (if present)
- the Trading Role Information Request Component (if present)
7.19.6 Authentication Response Signature Component
The Manifest Element of the Authentication Response Signature
Component should contain Digest Elements for the following
Components:
o the Transaction Reference Block (see section 3.3) for the IOTP
Message that contains information that describes the IOTP Message
and IOTP Transaction
o the Transaction Id Component (see section 3.3.1) which globally
uniquely identifies the IOTP Transaction
o the following components of the Authentication Request Block:
- the Authentication Request Component that was used in the
Authentication (if present)
- the Trading Role Information Request Component (if present)
o the Organisation Components contained in the Authentication
Response Block
7.19.7 Inquiry Request Signature Component
If the Inquiry Request is being signed (see section 9.2.1) the
Manifest Element of the Inquiry Request Signature Component should
contain Digest elements of the Inquiry Type Component, and if
present, the Payment Scheme Component.
7.19.8 Inquiry Response Signature Component
If the Inquiry Response is being signed (see section 9.2.1) the
Manifest Element of the Inquiry Response Signature Component should
contain Digest elements of the Trading Response Block and the Status
Component.
7.19.9 Ping Request Signature Component
If the Ping Request is being singed (see section 9.2.2), the Manifest
Element of the Ping Request Signature Component should contain Digest
elements for all the Organisation Components.
7.19.10 Ping Response Signature Component
If the Ping Response is being singed (see section 9.2.2), the
Manifest Element of the Ping Response Signature Component should
contain Digest elements fir all the Organisation Components.
7.20 Certificate Component
Note: Definitions of the XML structures for signatures and
certificates are described in the paper "Digital Signatures for the
Internet Open Trading Protocol", see [IOTPDSIG].
See note at the start of section 7.19 Signature Component for more
details.
A Certificate Component contains a Digital Certificate. They are used
only when required, for example, when asymmetric cryptography is
being used and the recipient of the signature that needs to check has
not already received the Public Key.
The structure of a Certificate Component is defined in [IOTPDSIG].
7.20.1 IOTP usage of signature elements and attributes
Detailed definitions of the above elements and attributes are
contained in [IOTPDSIG]. The following contains additional
information that describes how these elements and attributes are used
by IOTP.
CERTIFICATE COMPONENT
The ID attribute is mandatory.
VALUE ELEMENT
The ID attribute is mandatory.
7.21 Error Component
The Error Component contains information about Technical Errors (see
section 4.1) in an IOTP Message which has been received by one of the
Trading Roles involved in the trade.
For clarity two phrases are defined which are used in the description
of an Error Component:
o message in error. An IOTP message which contains or causes an
error of some kind
o message reporting the error. An IOTP message that contains an
Error Component that describes the error found in a message in
error.
The definition of the Error Component is as follows.
<!ELEMENT ErrorComp (ErrorLocation+, PackagedContent*) >
<!ATTLIST ErrorComp
ID NMTOKEN #REQUIRED
xml:lang NMTOKEN #REQUIRED
ErrorCode NMTOKEN #REQUIRED
ErrorDesc CDATA #REQUIRED
Severity (WarningTransientErrorHardError) #REQUIRED
MinRetrySecs CDATA #IMPLIED
SwVendorErrorRef CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the Error
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.
ErrorCode Contains an error code which indicates the nature
of the error in the message in error. Valid values
for the ErrorCode are given in section 7.21.2
Error Codes.
ErrorDesc Contains a narrative description of the error in
the language defined by xml:lang. The content of
this attribute is defined by the vendor/developer
of the software which generated the Error
Component
Severity Indicates the severity of the error. Valid values
are:
o Warning. This indicates that although there is
a message in error the IOTP Transaction can
still continue.
o TransientError. This indicates that the error
in the message in error may be recovered if the
message in error that is referred to by the
ErrorLocation element is resent
o HardError. This indicates that there is an
unrecoverable error in the message in error and
the IOTP Transaction must stop.
MinRetrySecs This attribute should be present if Severity is
set to TransientError. It is the minimum number of
whole seconds which the IOTP aware application
which received the message reporting the error
should wait before re-sending the message in error
identified by the ErrorLocation element.
If Severity is not set to TransientError then the
value of this attribute is ignored.
SwVendorErrorRef This attribute is a reference whose value is set
by the vendor/developer of the software which
generated the Error Component. It should contain
data which enables the vendor to identify the
precise location in their software and the set of
circumstances which caused the software to
generate a message reporting the error. See also
the SoftwareId attribute of the Message Id element
in the Transaction Reference Block (section 3.3).
Content:
ErrorLocation This identifies the IOTP Transaction Id of the
message in error and, where possible, the element
and attribute in the message in error that caused
the Error Component to be generated.
If the Severity of the error is not
TransientError, more than one ErrorLocation may be
specified as appropriate depending on the nature
of the error (see section 7.21.2 Error Codes) and
at the discretion of the vendor/developer of the
IOTP Aware Application.
PackagedContent This contains additional data which can be used to
understand the error. Its content may vary as
appropriate depending on the nature of the error
(see section 7.21.2 Error Codes) and at the
discretion of the vendor/developer of the IOTP
Aware Application. For a definition of
PackagedContent see section 3.7.
7.21.1 Error Processing Guidelines
If there is more than one Error Component in a message reporting the
error, carry out the actions appropriate for the Error Component with
the highest severity. In this context, HardError has a higher
severity than TransientError, which has a higher severity than
Warning.
7.21.1.1 Severity - Warning
If an IOTP aware application is generating a message reporting the
error with an Error Component where the Severity attribute is set to
Warning, then if the message reporting the error does not contain
another Error Component with a severity higher than Warning, the IOTP
Message must also include the Trading Blocks and Trading Components
that would have been included if no error was being reported.
If a message reporting the error is received with an Error Component
where Severity is set to Warning, then:
o it is recommended that information about the error is either
logged, or otherwise reported to the user,
o the implementer of the IOTP aware application must either, at
their or the user's discretion:
- continue the IOTP transaction as normal, or
- fail the IOTP transaction by generating a message reporting the
error with an Error Component with Severity set to HardError
(see section 7.21.1.3).
If the intention is to continue the IOTP transaction then, if there
are no other Error Components with a higher severity, check that the
necessary Trading Blocks and Trading Components for normal processing
of the transaction to continue are present. If they are not then
generate a message reporting the error with an Error Component with
Severity set to HardError.
7.21.1.2 Severity - Transient Error
If an IOTP Aware Application is generating a message reporting the
error with an Error Component where the Severity attribute is set to
TransientError, then there should be only one Error Component in the
message reporting the error. In addition, the MinRetrySecs attribute
should be present.
If a message reporting the error is received with an Error Component
where Severity is set to TransientError then:
o if the MinRetrySecs attribute is present and a valid number, then
use the MinRetrySecs value given. Otherwise if MinRetrySecs is
missing or is invalid, then:
- generate a message reporting the error containing an Error
Component with a Severity of Warning and send it on the next
IOTP message (if any) to be sent to the Trading Role which sent
the message reporting the error with the invalid MinRetrySecs,
and
- use a value for MinRetrySecs which is set by the
vendor/developer of the IOTP Aware Application.
o check that only one ErrorLocation element is contained within the
Error Component and that it refers to an IOTP Message which was
sent by the recipient of the Error Component with a Severity of
TransientError. If more than one ErrorLocation is present then
generate a message reporting the error with a Severity of
HardError.
7.21.1.3 Severity - Hard Error
If an IOTP Aware Application is generating a message reporting the
error with an Error Component where the Severity attribute set to
HardError, then there should be only one Error Component in the
message reporting the error.
If a message reporting the error is received with an Error Component
where Severity is set to HardError then terminate the IOTP
Transaction.
7.21.2 Error Codes
The following table contains the valid values for the ErrorCode
attribute of the Error Component. The first sentence of the
description contains the text that should be used to describe the
error when displayed or otherwise reported. Individual
implementations may translate this into alternative languages at
their discretion.
An Error Code must not be more that 14 characters long.
Value Description
Reserved Reserved. This error is reserved by the
vendor/developer of the software. Contact the
vendor/developer of the software for more information
See the SoftwareId attribute of the Message Id
element in the Transaction Reference Block(section
3.3).
XmlNotWellFrmd XML not well formed. The XML document is not well
formed. See [XML] for the meaning of "well formed".
Even if the XML is not well formed, it should still
be scanned to find the Transaction Reference Block so
that a properly formed Error Response may be
generated.
XmlNotValid XML not valid. The XML document is well formed but
the document is not valid. See [XML] for the meaning
of "valid". Specifically:
o the XML document does not comply with the
constraints defined in the IOTP document type
declaration (DTD) (see section 13 Internet Open
Trading Protocol Data Type Definition), and
o the XML document does not comply with the
constraints defined in the document type
declaration of any additional [XML Namespace] that
are declared.
As for XML not well formed, attempts should still be
made to extract the Transaction Reference Block so
that a properly formed Error Response may be
generated.
ElUnexpected Unexpected element. Although the XML document is well
formed and valid, an element is present that is not
expected in the particular context according to the
rules and constraints contained in this
specification.
ElNotSupp Element not supported. Although the document is well
formed and valid, an element is present that:
o is consistent with the rules and constraints
contained in this specification, but
o is not supported by the IOTP Aware Application
which is processing the IOTP Message.
ElMissing Element missing. Although the document is well formed
and valid, an element is missing that should have
been present if the rules and constraints contained
in this specification are followed.
In this case set the PackagedContent of the Error
Component to the type of the missing element.
ElContIllegal Element content illegal. Although the document is
well formed and valid, the element Content contains
values which do not conform to the rules and
constraints contained in this specification.
EncapProtErr Encapsulated protocol error. Although the document is
well formed and valid, the PackagedContent of an
element contains data from an encapsulated protocol
which contains errors.
AttUnexpected Unexpected attribute. Although the XML document is
well formed and valid, the presence of the attribute
is not expected in the particular context according
to the rules and constraints contained in this
specification.
AttNotSupp Attribute not supported. Although the XML document is
well formed and valid, and the presence of the
attribute in an element is consistent with the rules
and constraints contained in this specification, it
is not supported by the IOTP Aware Application which
is processing the IOTP Message.
AttMissing Attribute missing. Although the document is well
formed and valid, an attribute is missing that should
have been present if the rules and constraints
contained in this specification are followed.
In this case set the PackagedContent of the Error
Component to the type of the missing attribute.
AttValIllegal Attribute value illegal. The attribute contains a
value which does not conform to the rules and
constraints contained in this specification.
AttValNotRecog Attribute Value Not Recognised. The attribute
contains a value which the IOTP Aware Application
generating the message reporting the error could not
recognise.
MsgTooLarge Message too large. The message is too large to be
processed by the IOTP Aware Application.
ElTooLarge Element too large. The element is too large to be
processed by the IOTP Aware Application
ValueTooSmall Value too small or early. The value of all or part of
the Content of an element or an attribute, although
valid, is too small.
ValueTooLarge Value too large or in the future. The value of all or
part of the Content of an element or an attribute,
although valid, is too large.
ElInconsistent Element Inconsistent. Although the document is well
formed and valid, according to the rules and
constraints contained in this specification:
o the content of an element is inconsistent with the
content of other elements or their attributes, or
o the value of an attribute is inconsistent with the
value of one or more other attributes.
In this case create ErrorLocation elements which
identify all the attributes or elements which are
inconsistent.
TransportError Transport Error. This error code is used to indicate
that there is a problem with the Transport Mechanism
which is preventing the message from being received.
It is typically associated with a Transient Error.
Explanation of the Transport Error is contained
within the ErrorDesc attribute. The values which can
be used inside ErrorDesc with a TransportError is
specified in the IOTP supplement for the Transport
mechanism.
MsgBeingProc Message Being Processed. This error code is only used
with a Severity of Transient Error. It indicates that
the previous message, which may be an exchange
message or a request message, is being processed and,
if no response is received by the time indicated by
the MinRetrySecs attribute, then the original message
should be resent.
SystemBusy System Busy. This error code is only used with a
Severity of Transient Error. It indicates that the
server that received a message is currently too busy
to handle the message. If no response is received by
the time indicated by the MinRetrySecs attribute,
then the original message should be resent.
Note: If the server/system handling the Transport Mechanism (e.g.,
HTTP) is busy then a Transport Specific error message should be used
instead of an IOTP Error message. This code should be used in
association with IOTP servers/systems or other servers/systems to
which the IOTP server is connected.
UnknownError Unknown Error. Indicates that the transaction cannot
complete for some reason that is not covered
explicitly by any of the other errors. The ErrorDesc
attribute should be used to indicate the nature of
the problem.
This could be used to indicate, for example, an
internal error in a backend server or client process
of some kind.
7.21.3 Error Location Element
An Error Location Element identifies an element and optionally an
attribute in the message in error which is associated with the error.
It contains a reference to the IOTP Message, Trading Block, Trading
Component, element and attribute, which is in error.
<!ELEMENT ErrorLocation EMPTY >
<!ATTLIST ErrorLocation
ElementType NMTOKEN #REQUIRED
IotpMsgRef NMTOKEN #IMPLIED
BlkRef NMTOKEN #IMPLIED
CompRef NMTOKEN #IMPLIED
ElementRef NMTOKEN #IMPLIED
AttName NMTOKEN #IMPLIED >
Attributes:
ElementType This is the name of the type of the element where
the error is located. For example if the element
was declared as <!ELEMENT Org ... then its name is
"Org".
IotpMsgRef This is the value of the ID attribute of the of
the Message Id Component (see section 3.3.2) of
the message in error to which this Error Component
applies.
BlkRef If the error is associated with a specific Trading
Block, then this is the value of the ID attribute
of the Trading Block where the error is located.
CompRef If the error is associated with a specific Trading
Component, then this is the value of the ID
attribute of the Trading Component where the error
is located.
ElementRef If the error is associated with a specific element
within a Trading Component then, if the element
has an attribute with an "attribute type" (see
[XML]) of "ID", then this is the value of that
attribute.
AttName If the error is associated with the value of an
attribute, then this is the name of that
attribute. In this case the PackagedContent of the
Error Component should contain the value of the
attribute.
Note that as many as the attributes as possible should be included.
For example if an attribute in a child element of a Trading Component
contains an incorrect value, then all the attributes of ErrorLocation
should be present.
8. Trading Blocks
Trading Blocks are child elements of the top level IOTP Messages that
are sent in the form of [XML] documents directly between the
different Trading Roles that are taking part in a trade.
Each Trading Blocks consist of one or more Trading Components (see
section 7). This is 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. (Optional)
------> -Trading Block <--------Trading Block - an XML Element
-Trading Comp. within an IOTP Message that
Trading -Trading Comp. contains a predefined set of
Blocks -Trading Comp. Trading Components
-Trading Comp.
-Trading Comp. <-----Trading Components - XML Elements
within a Trading Block that
------> -Trading Block contain a predefined set of XML
-Trading Comp. elements and attributes
-Trading Comp. containing information required
-Trading Comp. to support a Trading Exchange
-Trading Comp.
-Trading Comp.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 16 Trading Blocks
Trading Blocks are defined as part of the definition of an IOTP
Message (see section 3.1.1). The definition of an IOTP Message
element is repeated here:
<!ELEMENT IotpMessage
( TransRefBlk,
SigBlk?,
ErrorBlk?,
( AuthReqBlk
AuthRespBlk
AuthStatusBlk
CancelBlk
DeliveryReqBlk
DeliveryRespBlk
InquiryReqBlk
InquiryRespBlk
OfferRespBlk
PayExchBlk
PayReqBlk
PayRespBlk
PingReqBlk
PingRespBlk
TpoBlk
TpoSelectionBlk
)*
) >
The remainder of this section defines the Trading Blocks in this
version of IOTP. They are:
o Authentication Request Block
o Authentication Response Block
o Authentication Status Block
o Cancel Block
o Delivery Request Block
o Delivery Response Block
o Error Block
o Inquiry Request Block
o Inquiry Response Block
o Offer Response Block
o Payment Exchange Block
o Payment Request Block
o Payment Response Block
o Signature Block
o Trading Protocol Options Block
o TPO Selection Block
The Transaction Reference Block is described in section 3.3.
8.1 Trading Protocol Options Block
The TPO Trading Block contains options which apply to the IOTP
Transaction. The definition of a TPO Trading Block is as follows.
<!ELEMENT TpoBlk ( ProtocolOptions, BrandList*, Org* ) >
<!ATTLIST TpoBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Trading Protocol Options Block within the IOTP
Transaction (see section 3.4 ID Attributes).
Content:
ProtocolOptions The Protocol Options Component (see section
7.1)defines the options which apply to the whole
IOTP Transaction (see section 9).
BrandList This Brand List Component contains one or more
payment brands and protocols which may be selected
(see section 7.7).
Org The Organisation Components (see section 7.6)
identify the Organisations and their roles in the
IOTP Transaction. The roles and Organisations
which must be present will depend on the
particular type of IOTP Transaction. See the
definition of each transaction in section 9.
Internet Open Trading Protocol Transactions.
The TPO Block should contain:
o the Protocol Options Component
o the Organisation Component with the Trading Role of Merchant
o the Organisation Component with the Trading Role of Consumer
o optionally, the Organisation Component with the Trading Role of
DeliverTo, if there is a Delivery included in the IOTP Transaction
o Brand List Components for each payment in the IOTP Transaction
o Organisation Components for all the Payment Handlers involved
o optionally, Organisation Components for the Delivery Handler (if
any) for the transaction
o additional Organisation Components that the Merchant may want to
include. For example
- a Customer Care Provider
- an Certificate Authority that offers Merchant "Credentials" or
some other warranty on the goods or services being offered.
8.2 TPO Selection Block
The TPO Selection Block contains the results of selections made from
the options contained in the Trading Protocol Options Block (see
section 8.1).The definition of a TPO Selection Block is as follows.
<!ELEMENT TpoSelectionBlk (BrandSelection+) >
<!ATTLIST TpoSelectionBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the TPO
Selection Block within the IOTP Transaction.
Content:
BrandSelection This identifies the choice of payment brand and
payment protocol to be used in a payment within
the IOTP Transaction. There is one Brand Selection
Component (see section 7.8) for each payment to be
made in the IOTP Transaction.
The TPO Selection Block should contain one Brand Selection Component
for each Brand List in the TPO Block.
8.3 Offer Response Block
The Offer Response Block contains details of the goods, services,
amount, delivery instructions or financial transaction which is to
take place. Its definition is as follows.
<!ELEMENT OfferRespBlk (Status, Order?, Payment*,
Delivery?, TradingRoleData*) >
<!ATTLIST OfferRespBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the Offer
Response Block within the IOTP Transaction.
Content:
Status Contains status information about the business
success (see section 4.2) or failure of the
generation of the Offer. Note that in an Offer
Response Block, a ProcessState of NotYetStarted or
InProgress are illegal values.
Order The Order Component contains details about the
goods, services or financial transaction which is
taking place see section 7.5.
The Order Component must be present unless the
ProcessState attribute of the Status Component is
set to Failed.
Payment The Payment Components contain information about
the payments which are to be made see section 7.9.
Delivery The Delivery Component contains details of the
delivery to be made (see section 7.13).
TradingRoleData The Trading Role Data Component contains opaque
data which is needs to be communicated between the
Trading Roles involved in an IOTP Transaction (see
section 7.17).
The Offer Response Block should contain:
o the Order Component for the IOTP Transaction
o Payment Components for each Payment in the IOTP Transaction
o the Delivery Component the IOTP Transaction requires (if any).
8.4 Authentication Request Block
The Authentication Request Block contains the data which is used by
one Trading Role to obtain information about and optionally
authenticate another Trading Role.
In outline it contains:
o information about how the authentication itself will be carried
out, and/or
o a request for additional information about the Organisation being
authenticated.
Its definition is as follows.
<!ELEMENT AuthReqBlk (AuthReq*, TradingRoleInfoReq?) >
<!ATTLIST AuthReqBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Authentication Request Block within the IOTP
Transaction.
Content:
AuthReq Each Authentication Request (see section 7.2)
component describes an alternative way in which
the recipient of the Authentication Request may
authenticate themselves by generating an
Authentication Response Component (see section
7.3).
If one Authentication Request Component is
present then that Authentication Request
Component should be used.
If more than one Authentication Request Component
is present then the recipient should choose one
of the components based on personal preference of
the recipient or their software.
If no Authentication Request Component is present
it means that the Authentication Request Block is
requesting the return of Organisation Components
as specified in the Trading Role Information
Request Component.
TradingRoleInfoReq The Trading Role Information Request Component
(see section 7.4) contains a list of Trading
Roles about which information is being requested
There must be at least one Component (either an Authentication
Request or a Trading Role Information Request) within the
Authentication Block otherwise it is an error.
8.5 Authentication Response Block
The Authentication Response Block contains the response which results
from processing the Authentication Request Block. Its definition is
as follows.
<!ELEMENT AuthRespBlk (AuthResp?, Org*) >
<!ATTLIST AuthRespBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Authentication Response Block within the IOTP
Transaction.
Content:
AuthResp The optional Authentication Response Component
which contains the results of processing the
Authentication Request Component - see section
7.3.
Org Optional Organisation Components that contain
information corresponding to the Trading Roles as
requested by the TradingRoleList attribute of the
Trading Role Information Request component.
The components present in the Authentication Response Block must
match the requirement of the corresponding Authentication Request
Block otherwise it is an error.
8.6 Authentication Status Block
The Authentication Status Block indicates the success or failure of
the validation of an Authentication Response Block by an
Authenticator. Its definition is as follows.
<!ELEMENT AuthStatusBlk (Status) >
<!ATTLIST AuthStatusBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Authentication Status Block within the IOTP
Transaction.
Content:
Status Contains status information about the business
success (see section 4.2) or failure of the
authentication
8.7 Payment Request Block
The Payment Request Block contains information which requests that a
payment is started. Its definition is as follows.
<!ELEMENT PayReqBlk (Status+, BrandList, BrandSelection,
Payment, PaySchemeData?, Org*, TradingRoleData*) >
<!ATTLIST PayReqBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Payment Request Block within the IOTP Transaction.
Content:
Status Contains the Status Components (see section 7.13)
of the responses of the steps (e.g., an Offer
Response and/or a Payment Response) on which this
step depends. It is used to indicate the success
or failure of those steps. Payment should only
occur if the previous steps were successful.
BrandList The Brand List Component contains a list of one or
more payment brands and protocols which may be
selected (see section 7.7).
BrandSelection This identifies the choice of payment brand, the
payment protocol and the Payment Handler to be
used in a payment within the IOTP Transaction.
There is one Brand Selection Component (see
section 7.8) for each payment to be made in the
IOTP Transaction.
Payment The Payment Components contain information about
the payment which is being made see section 7.9.
PaySchemeData The Payment Scheme Component contains payment
scheme specific data see section 7.10.
Org The Organisation Component contains details of
Organisations involved in the payment (see section
7.6). The Organisations present are dependent on
the IOTP Transaction and the data which is to be
signed. See section 6 Digital Signatures for more
details.
TradingRoleData The Trading Role Data Component contains opaque
data which is needs to be communicated between the
Trading Roles involved in an IOTP Transaction (see
section 7.17).
The Payment Request Block should contain:
o the Organisation Component with a Trading Role of Merchant
o the Organisation Component with the Trading Role of Consumer
o the Payment Component for the Payment
o the Brand List Component for the Payment
o the Brand Selection Component for the Brand List
o the Organisation Component for the Payment Handler of the Payment
o the Organisation Component (if any) for the Organisation which
carried out the previous step, for example another Payment Handler
o the Organisation Component for the Organisation which is to carry
out the next step, if any. This may be, for example, either a
Delivery Handler or a Payment Handler.
o the Organisation Components for any additional Organisations that
the Merchant has included in the Offer Response Block
o an Optional Payment Scheme Data Component, if required by the
Payment Method as defined in the IOTP supplement for the payment
method
o any Trading Role Data Components that may be required (see section
7.17.1).
8.8 Payment Exchange Block
The Payment Exchange Block contains payment scheme specific data
which is exchanged between two of the roles in a trade. Its
definition is as follows.
<!ELEMENT PayExchBlk (PaySchemeData+) >
<!ATTLIST PayExchBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Payment Exchange Block within the IOTP
Transaction.
Content:
PaySchemeData This Trading Component contains payment scheme
specific data see section 7.10 Payment Scheme
Component.
8.9 Payment Response Block
This Payment Response Block contains a information about the Payment
Status, an optional Payment Receipt, and an optional payment protocol
message. Its definition is as follows.
<!ELEMENT PayRespBlk (Status, PayReceipt?, PaySchemeData?,
PaymentNote?, TradingRoleData*) >
<!ATTLIST PayRespBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Payment Response Block within the IOTP
Transaction.
Content:
Status Contains status information about the business
success (see section 4.2) or failure of the
payment. Note that in a Pay Response Block, a
ProcessState of NotYetStarted or InProgress are
illegal values.
PayReceipt Contains payment scheme specific data which can be
used to verify the payment occurred. See section
7.11 Payment Receipt Component. It must be present
if the ProcessState attribute of the Status
Component is set to CompletedOk. PayReceipt is
optional for other values as specified by the
appropriate Payment Scheme supplement.
PaySchemeData Contains payment scheme specific data see section,
for example a payment protocol message. See 7.10
Payment Scheme Component.
PaymentNote Contains additional, non payment related,
information which the Payment Handler wants to
provide to the Consumer. For example, if a
withdrawal or deposit were being made then it
could contain information on the remaining balance
on the account after the transfer was complete.
See section 7.12 Payment Note Component.
TradingRoleData The Trading Role Data Component contains opaque
data which is needs to be communicated between the
Trading Roles involved in an IOTP Transaction (see
section 7.17).
8.10 Delivery Request Block
The Delivery Request Block contains details of the goods or services
which are to be delivered together with a signature which can be used
to check that delivery is authorised. Its definition is as follows.
<!ELEMENT DeliveryReqBlk (Status+, Order, Org*, Delivery,
ConsumerDeliveryData?, TradingRoleData*) >
<!ATTLIST DeliveryReqBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Delivery Request Block within the IOTP
Transaction.
Content:
Status Contains the Status Components (see section
7.13) of the responses of the steps (e.g., a
Payment Response) on which this step is
dependent. It is used to indicate the success
or failure of those steps. Delivery should only
occur if the previous steps were successful.
Order The Order Component contains details about the
goods, services or financial transaction which
is taking place see section 7.5.
The Organisation Components (see section 7.6)
identify the Organisations and their roles in
Org the IOTP Transaction. The roles and
Organisations which must be present will depend
on the particular type of IOTP Transaction. See
the definition of each transaction in section
9. Internet Open Trading Protocol Transactions.
Delivery The Delivery Component contains details of the
delivery to be made (see section 7.13).
ConsumerDeliveryData Optional. Contains an identifier specified by
the Consumer which, if returned by the Delivery
Handler will enable the Consumer to identify
which Delivery is being referred to.
TradingRoleData The Trading Role Data Component contains opaque
data which is needs to be communicated between
the Trading Roles involved in an IOTP
Transaction (see section 7.17).
The Delivery Request Block contains:
o the Organisation Component with a Trading Role of Merchant
o the Organisation Component for the Consumer and DeliverTo Trading
Roles
o the Delivery Component for the Delivery
o the Organisation Component for the Delivery Handler. Specifically
the Organisation Component identified by the ActionOrgRef
attribute on the Delivery Component
o the Organisation Component (if any) for the Organisation which
carried out the previous step, for example a Payment Handler
o the Organisation Components for any additional Organisations that
the Merchant has included in the Offer Response Block
o any Trading Role Data Components that may be required (see section
7.17.1).
8.11 Delivery Response Block
The Delivery Response Block contains a Delivery Note containing
details on how the goods will be delivered. Its definition is as
follows. Note that in a Delivery Response Block a Delivery Status
Element with a DeliveryStatusCode of NotYetStarted or InProgress is
invalid.
<!ELEMENT DeliveryRespBlk (Status, DeliveryNote) >
<!ATTLIST DeliveryRespBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Delivery Response Block within the IOTP
Transaction.
Content:
Status Contains status information about the business
success (see section 4.2) or failure of the
delivery. Note that in a Delivery Response Block,
a ProcessState of NotYetStarted or InProgress are
illegal values.
DeliveryNote The Delivery Note Component contains details about
how the goods or services will be delivered (see
section 7.15).
8.12 Inquiry Request Trading Block
The Inquiry Request Trading Block contains an Inquiry Type Component
and an optional Payment Scheme Component to contain payment scheme
specific inquiry messages.
<!ELEMENT InquiryReqBlk ( InquiryType, PaySchemeData? ) >
<!ATTLIST InquiryReqBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Inquiry Request Trading Block within the IOTP
Transaction.
Content:
InquiryType Inquiry Type Component (see section 7.18) that
contains the type of inquiry.
PaySchemeData Payment Scheme Component (see section 7.10) that
contains payment scheme specific inquiry messages
for inquiries on payments. This is present when
the Type attribute of Inquiry Type Component is
Payment.
8.13 Inquiry Response Trading Block
The Inquiry Response Trading Block contains a Status Component and an
optional Payment Scheme Component to contain payment scheme specific
inquiry messages. Its purpose is to enquire on the current status of
an IOTP transaction at a server.
<!ELEMENT InquiryRespBlk (Status, PaySchemeData?) >
<!ATTLIST InquiryRespBlk
ID ID #REQUIRED
LastReceivedIotpMsgRef NMTOKEN #IMPLIED
LastSentIotpMsgRef NMTOKEN #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Inquiry Response Trading Block within the
IOTP Transaction.
LastReceivedIotpMsgRef Contains an Element Reference (see section
3.5) to the Message Id Component (see section
3.3.2) of the last message this server has
received from the Consumer. If there is no
previously received message from the Consumer
in the pertinent transaction, this attribute
should be contain the value Null. This
attribute exists for debugging purposes.
LastSentIotpMsgRef Contains an Element Reference (see section
3.5) to the Message Id Component (see section
3.3.2) of the last message this server has
sent to the Consumer. If there is no
previously sent message to the Consumer in
the pertinent transaction, this attribute
should contain the value Null. This attribute
exists for debugging purposes.
Content:
Status Contains status information about the business
success (see section 4.2) or failure of a certain
trading exchange (i.e., Offer, Payment, or
Delivery).
PaySchemeData Payment Scheme Component (see section 7.10) that
contains payment scheme specific inquiry messages
for inquiries on payments. This is present when
the Type attribute of StatusType attribute of the
Status Component is set to Payment.
8.14 Ping Request Block
The Ping Request Block is used to determine if a Server is operating
and whether or not cryptography is compatible.
The definition of a Ping Request Block is as follows.
<!ELEMENT PingReqBlk (Org*)>
<!ATTLIST PingReqBlk
ID ID #REQUIRED>
Attributes:
ID An identifier which uniquely identifies the Ping
Request Trading Block within the IOTP Transaction.
Content:
Org Optional Organisation Components (see section
7.6).
If no Organisation Component is present then the
Ping Request is anonymous and simply determines if
the server is operating.
However if Organisation Components are present,
then it indicates that the sender of the Ping
Request wants to verify that digital signatures
can be handled.
In this case the sender includes:
o an Organisation Component that identifies
itself specifying the Trading Role(s) it is
taking in IOTP transactions (Merchant, Payment
Handler, etc.)
o an Organisation Component that identifies the
intended recipient of the message.
These are then used to generate a signature over
the Ping Response Block.
8.15 Ping Response Block
The Ping Response Trading Block provides the result of a Ping
Request.
It contains an Organisation Component that identifies the sender of
the Ping Response.
If the Ping Request to which this block is a response contained
Organisation Components, then it also contains those Organisation
Components.
<!ELEMENT PingRespBlk (Org+)>
<!ATTLIST PingRespBlk
ID ID #REQUIRED
PingStatusCode (Ok Busy Down) #REQUIRED
SigVerifyStatusCode (Ok NotSupported Fail) #IMPLIED
xml:lang NMTOKEN #IMPLIED
PingStatusDesc CDATA #IMPLIED>
Attributes:
ID An identifier which uniquely identifies the Ping
Request Trading Block within the IOTP
Transaction.
PingStatusCode Contains a code which shows the status of the
sender software which processes IOTP messages.
Valid values are:
o Ok. Everything with the service is working
normally, including the signature
verification.
o Busy. Things are working normally but there
may be some delays.
o Down. The server is not functioning fully but
can still provide a Ping response.
SigVerifyStatusCode Contains a code which shows the status of
signature verification. This is present only
when the message containing the Ping Request
Block also contains a Signature Block. Valid
values are:
o Ok. The signature has successfully been
verified and proved compatible.
o NotSupported The receiver of this Ping
Request Block does not support validation of
signatures.
o Fail. Signature verification failed.
Xml:lang Defines the language used in PingStatusDesc.
This is present when PingStatusDesc is present.
PingStatusDesc Contains a short description of the status of
the server which sends this Ping Response Block.
Servers, if their designers want, can use this
attribute to send more refined status
information than PingStatusCode which can be
used for debugging purposes, for example.
Content:
Org These are Organisation Components (see section
7.6).
The Organisation Components of the sender of the
Ping Response is always included in addition to
the Organisation Components sent in the Ping
Request.
Note: Ping Status Code values do not include a value such as Fail,
since, when the software receiving the Ping Request message is not
working at all, no Ping Response message will be sent back.
8.16 Signature Block
The Signature Block contains one or more Signature Components and
associated Certificates (if required) which sign data associated with
the IOTP Transaction. For a general discussion and introduction to
how IOTP uses signatures, see section 6 Digital Signatures. The
definition of the Signature Component and certificates is contained
in the paper "Digital Signatures for the Internet Open Trading
Protocol", see [IOTPDSIG]. Descriptions of how these are used by
IOTP is contained in sections 7.19 and 7.20.
The definition of a Signature Block is as follows:
<!ELEMENT IotpSignatures (Signature+, Certificate*) >
<!ATTLIST IotpSignatures
ID ID #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Signature Block within the IOTP Transaction.
Content:
Signature A Signature Component. See section 7.19.
Certificate A Certificate Component. See section 7.20.
The contents of a Signature Block depends on the Trading Block that
is contained in the same IOTP Message as the Signature Block.
8.16.1 Signature Block with Offer Response
A Signature Block which is in the same message as an Offer Response
Block contains just an Offer Response Signature Component (see
section 7.19.2).
8.16.2 Signature Block with Payment Request
A Signature Block which is in the same message as a Payment Request
Block contains:
o an Offer Response Signature Component (see section 7.19.2), and
o if the Payment is dependent on an earlier step (as indicated by
the StartAfter attribute on the Payment Component), then the
Payment Receipt Signature Component (see section 7.19.3) generated
by the previous step
8.16.3 Signature Block with Payment Response
A Signature Block which is in the same message as a Payment
Response Block contains just a Payment Receipt Signature Component
(see section 7.19.3) generated by the step.
8.16.4 Signature Block with Delivery Request
A Signature Block which is in the same message as a Delivery
Request Block contains:
o an Offer Response Signature Component (see section 7.19.2), and
o the Payment Receipt Signature Component (see section 7.19.3)
generated by the previous step.
8.16.5 Signature Block with Delivery Response
A Signature Block which is in the same message as a Delivery Response
Block contains just a Delivery Response Signature component (see
section 7.19.4) generated by the step.
8.17 Error Block
The Error Trading Block contains one or more Error Components (see
section 7.21) which contain information about Technical Errors (see
section 4.1) in an IOTP Message which has been received by one of the
Trading Roles involved in the trade.
For clarity two phrases are defined which are used in the description
of an Error Trading Block:
o message in error. An IOTP message which contains or causes an
error of some kind
o message reporting the error. An IOTP message that contains an
Error Trading Block that describes the error found in a message in
error.
An Error Trading Block may be contained in any message reporting the
error. The action which then follows depends on the severity of the
error. See the definition of an Error Component, for an explanation
of the different types of severity and the actions which can then
occur.
in3 Note: Although, an Error Trading Block can report multiple
different errors using multiple Error Components, there is no
obligation on a developer of an IOTP Aware Application to do so.
The structure of an Error Trading Block is as follows.
<!ELEMENT ErrorBlk (ErrorComp+, PaySchemeData*) >
<!ATTLIST ErrorBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the Error
Trading Block within the IOTP Transaction.
Content:
ErrorComp An Error Components (see section 7.21) that
contains information about an individual Technical
Error.
PaySchemeData An optional Payment Scheme Component (see section
7.10) which contains a Payment Scheme Message. See
the appropriate payment scheme supplement to
determine whether or not this component needs to
be present and for the definition of what it must
contain.
8.18 Cancel Block
The Cancel Block is used by one Trading Role to inform any other that
a transaction has been cancelled. Example usage includes:
o a Consumer Role informing a non-Consumer role that it no longer
plans to continue with the transaction. This will allow the server
to close down the transaction tidily without a waiting for a
time-out to occur
o a non-Consumer Role to inform a Consumer role that the Transaction
is being stopped. In this case, the Consumer is then unlikely to
re-send the previous message that was sent in the mistaken
understanding that the original was not received.
Its definition is as follows.
<!ELEMENT CancelBlk (Status) >
<!ATTLIST CancelBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the Cancel
Block within the IOTP Transaction.
Content:
Status Contains status information indicating that the
IOTP transaction has been cancelled.
9. Internet Open Trading Protocol Transactions
The Baseline Internet Open Trading Protocol supports three types of
transactions for different purposes. These are
o an Authentication IOTP transaction which supports authentication
of one party in a trade by another and/or requests information
about another Trading Role
o IOTP Transactions that involve one or more payments. Specifically:
- Deposit
- Purchase
- Refund
- Withdrawal, and
- Value Exchange
o IOTP Transactions designed to check the correct function of the
IOTP infrastructure. Specifically:
- Transaction Status Inquiry, and
- Ping
Although the Authentication IOTP Transaction can operate on its own,
authentication can optionally precede any of the "payment"
transactions. Therefore, the rest of this section is divided into
two parts covering:
o Authentication and Payment transactions (Authentication, Deposit,
Purchase, Refund, Withdrawal and Value Exchange)
o Infrastructure Transactions (Transaction Status Inquiry and Ping)
that are designed to support inquiries on whether or not a
transaction has succeeded or a Trading Role's servers are
operating correctly, and
9.1 Authentication and Payment Related IOTP Transactions
The Authentication and Payment related IOTP Transactions consist
of six Document Exchanges which are then combined in sequence to
implement a specific transaction.
Generally, there is a close, but not exact, correspondence between
a Document Exchange and a Trading Exchange. The main difference is
that some Document Exchanges implement part or all of two Trading
Exchanges simultaneously in order to minimise the number of actual
IOTP Messages which must be sent over the Internet.
The six Document Exchanges are:
o Authentication. This is a direct implementation of the
Authentication Trading Exchange
o Brand Dependent Offer. This is the Offer Trading Exchange combined
with the Brand Selection part of the Payment Trading Exchange. Its
purpose is to provide the Merchant with information on the Brand
selected so that the content of the Offer Response may be adapted
accordingly
o Brand Independent Offer. This is also an Offer Trading Exchange.
However, in this instance, the content of the Offer Response does
not depend on the Brand selected.
o Payment. This is a direct implementation of the Payment part of a
Payment Trading Exchange
o Delivery. This is a direct implementation of the Delivery Exchange
o Delivery with Payment. This is an implementation of combined
Payment and Delivery Trading Exchanges
These Document Exchanges are combined together in different sequences
to implement each IOTP Transaction. The way in which they may be
combined is illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
START -----------------------------------------------------
v
----------------
AUTHENTICATION
----------------
--------------------------------------
-------------- -------------
v v v v
------------------- -----------------
BRAND INDEPENDENT BRAND DEPENDENT
OFFER OFFER
------------------- -----------------
---------------
-------------- --
v v v v
--------- --------------
PAYMENT PAYMENT WITH
(first) DELIVERY
--------- --------------
-----------------------------
v v
---------- ---------
DELIVERY PAYMENT
{second)
---------- ---------
v
----------------------------------------------> STOP
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 17 Payment and Authentication Message Flow Combinations
The combinations of Document Exchanges that are valid depend on the
particular IOTP transaction.
The remainder of this sub-section describes:
o each Document Exchange in more detail including descriptions of
the content of each Trading Block in the Document Exchanges, and
o descriptions of how each IOTP Transaction uses the Document
Exchanges to effect the desired result.
Note: The descriptions of the Document Exchanges which follow
describe the ways in which various Business Errors (see section 4.2)
are handled. No reference is made however to the handling of
Technical Errors (see section 4.1) in any of the messages since these
are handled the same way irrespective of the context in which the
message is being sent. See section 4 for more details.
9.1.1 Authentication Document Exchange
The Authentication Document Exchange is a direct implementation of
the Authentication Trading Exchange (see section 2.2.4). It involves:
o an Authenticator - the Organisation which is requesting the
authentication, and
o an Authenticatee - the Organisation being authenticated.
The authentication consists of:
o an Authentication Request being sent by the Authenticator to the
Authenticatee,
o an Authentication Response being sent in return by the
Authenticatee to the Authenticator which is then checked, and
o an Authentication Status being sent by the Authenticator to the
Authenticatee to provide an indication of the success or failure
of the authentication.
An Authentication Document Exchange also:
o provides an Authenticatee with an Organisation Component which
describes the Authenticator, and
o optionally provides the Authenticator with Organisation Components
which describe the Authenticatee.
The Authentication Request may also be digitally signed which allows
the Authenticatee to verify the credentials of the Authenticator.
The IOTP Messages which are involved are illustrated by the diagram
below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Organisation 1
(Authenticatee)
Organisation 2
(Authenticator)
STEP
1. First Organisation takes an action (for example by
pressing a button on an HTML page) which requires that
the Organisation is authenticated
1 --> 2 Authentication Need (outside scope of IOTP)
2. The second Organisation generates: an Authentication
Request Block containing one or more Authentication
Request Components and/or a Trading Role Information
Request Component, then sends it to the first
Organisation
1 <-- 2 TPO & AUTHENTICATION REQUEST. IotpMsg: Trans Ref Block;
Signature Block (optional); TPO Block; Auth Request Block
3. IOTP aware application started. If a Signature Block is
present, the first Organisation may use this to check the
credentials of the second Organisation. If credentials are
OK, the first Organisation selects an Authentication
Request to use (if present and more than one), then uses
the authentication algorithm selected to generate an
Authentication Response Block. If present, the Trading
Role Information Request Component is used to generate
Organisation Components. Finally a Signature Component is
created if required and all components are then sent back
to the second Organisation for validation.
1 --> 2 AUTHENTICATION RESPONSE. IotpMsg; Trans Ref Block;
Signature Block (optional) ; Auth Response Block
4. The second Organisation checks the Authentication
Response against the data in the Authentication Request
Block to check that the first Organisation is who they
appear to be, and sends an Authentication Status Block to
the first Organisation to indicate the result then
stops.
1 <-- 2 AUTHENTICATION STATUS. IotpMsg: Trans Ref Block;
Signature Block (optional); Auth Response Block
5. The first Organisation checks the authentication Status
Block and optionally keeps information on the IOTP
transaction for record keeping purposes and stops.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 18 Authentication Document Exchange
9.1.1.1 Message Processing Guidelines
On receiving a TPO & Authentication Request IOTP Message (see below),
an Authenticatee may either:
o generate and send an Authentication Response IOTP Message back to
the Authenticator, or
o indicate failure to comply with the Authentication Request by
sending a Cancel Block back to the Authenticator containing a
Status Component with a StatusType of Authentication a
ProcessState of Failed and the CompletionCode (see section 7.16.4)
set to either: AutEeCancel, NoAuthReq, TradRolesIncon or
Unspecified.
On receiving an Authentication Response IOTP Message (see below), an
Authenticator should send in return, an Authentication Status IOTP
Message (see below) containing a Status Block with a Status Component
where the StatusType is set to Authentication, and:
o the ProcessState attribute of the Status Component is set to
CompletedOk which indicates a successful completion, or
o the ProcessState attribute is set to Failed and the CompletionCode
attribute is set to either: AutOrCancel, AuthFailed or Unspecified
which indicates a failed authentication,
On receiving an Authentication Status IOTP Message (see below), the
Authenticatee should check the Status Component in the Status Block.
If this indicates:
o a successful authentication, then the Authenticatee should either:
- continue with the next step in the IOTP Transaction of which
the Authentication Document Exchange is part (if any), or
- indicate a failure to continue with the rest of the IOTP
Transaction, by sending back to the Authenticator a Cancel
Block containing a Status Component with a StatusType of
Authentication, a ProcessState of Failed and the CompletionCode
(see section 7.16.4) set to AutEeCancel.
o a failed authentication, then the failure should be reported to
the Authenticatee and any further processing stopped.
If the Authenticator receives an IOTP Message containing a Cancel
block from a Consumer, then the Authenticatee may go to the
CancelNetLocn specified on the Trading Role Element in the
Organisation Component for the Authenticator contained in the Trading
Protocol Options Block.
9.1.1.2 TPO & Authentication Request IOTP Message
Apart from a Transaction Reference Block (see section 3.3), this
message consists of:
o a Trading Protocol Options Block (see section 8.1)
o an Authentication Request Block (see section 8.4), and
o an optional Signature Block (see section 8.16).
Each of these are described below.
TRADING PROTOCOL OPTIONS BLOCK
The Trading Protocol Options Block (see section 8.1) must contain the
following Trading Components:
o one Protocol Options Component (see Section 7.1) which defines the
options which apply to the whole Authentication Document Exchange.
o one Organisation Component (see section 7.6) which describes the
Authenticator. The Trading Role on the Organisation Component
should indicate the role which the Authenticator is taking in the
Trade, for example a Merchant or a Consumer.
AUTHENTICATION REQUEST BLOCK
The Authentication Request Block (see section 8.4) must contain the
following Trading Components:
o one Authentication Request Component (see section 7.2), and
SIGNATURE BLOCK (AUTHENTICATION REQUEST)
If the Authentication Request is being digitally signed then a
Signature Block must be included. It contains Digests of the
following XML elements:
o the Transaction Reference Block (see section 3.3) for the IOTP
Message that contains information that describes the IOTP Message
and IOTP Transaction
o the Transaction Id Component (see section 3.3.1) which globally
uniquely identifies the IOTP Transaction
o the following components of the TPO Block :
- the Protocol Options Component
- the Organisation Component
o the following components of the Authentication Request Block:
- the Authentication Request Component
- the Trading Role Information Request Component
9.1.1.3 Authentication Response IOTP Message
Apart from a Transaction Reference Block (see section 3.3), this
message consists of:
o an Authentication Response Block (see section 8.5), and
o an optional Signature Block (see section 8.16).
Each of these are described below.
AUTHENTICATION RESPONSE BLOCK
The Authentication Response Block must contain the following Trading
Component:
o one Authentication Response Component (see section 7.3)
o one Organisation Component for every Trading Role identified in
the TradingRoleList attribute of the Trading Role Information
Request Component contained in the Authentication Request Block.
SIGNATURE BLOCK (AUTHENTICATION RESPONSE)
If the Algorithm element (see section 12. IANA Considerations) within
the Authentication Request Component contained in the Authentication
Request Block indicates that the Authentication Response should
consist of a digital signature then a Signature Block must be
included in the same IOTP message that contains an Authentication
Response Block. The Signature Component contains Digest Elements for
the following XML elements:
o the Transaction Reference Block (see section 3.3) for the IOTP
Message that contains information that describes the IOTP Message
and IOTP Transaction
o the Transaction Id Component (see section 3.3.1) which globally
uniquely identifies the IOTP Transaction
o the following components of the Authentication Request Block:
- the Authentication Request Component
- the Trading Role Information Request Component
o the Organisation Components contained in the Authentication
Response Block
Note: It should not be assumed that all trading roles can support the
signing of data. Particularly it should not be assumed that Consumers
support the signing of data.
9.1.1.4 Authentication Status IOTP Message
Apart from a Transaction Reference Block (see section 3.3), this
message consists of:
o an Authentication Status Block (see section 8.5), and
o an optional Signature Block (see section 8.16).
Each of these are described below.
AUTHENTICATION STATUS BLOCK
The Authentication Status Block (see section 8.6) must contain the
following Trading Components:
o one Status Component (see section 7.16) with a ProcessState
attribute set to CompletedOk.
SIGNATURE BLOCK (AUTHENTICATION STATUS)
If the Authentication Status Block is being digitally signed then
a Signature Block must be included that contains a Signature
Component with Digest elements for the following XML elements:
o the Transaction Reference Block (see section 3.3) for the IOTP
Message that contains information that describes the IOTP Message
and IOTP Transaction
o the Transaction Id Component (see section 3.3.1) which globally
uniquely identifies the IOTP Transaction
o the following components of the Authentication Status Block:
- the Status Component (see section 7.16).
Note: If the Authentication Document Exchange is followed by an Offer
Document Exchange (see section 9.1.2) then the Authentication Status
Block and the Signature Block (Authentication Status) may be combined
with either:
o a TPO IOTP Message (see section 9.1.2.3), or
o a TPO and Offer Response IOTP Message (see section 9.1.2.6)
9.1.2 Offer Document Exchange
The Offer Document Exchange occurs in two basic forms:
o Brand Dependent Offer Exchange. Where the content of the offer,
e.g., the order details, amount, delivery details, etc., are
dependent on the payment brand and protocol selected by the
consumer, and
o Brand Independent Offer Exchange. Where the content of the offer
is not dependent on the payment brand and protocol selected.
Each of these types of Offer Document Exchange may be preceded by
an Authentication Document Exchange (see section 9.1.1).
9.1.2.1 Brand Dependent Offer Document Exchange
In a Brand Dependent Offer Document Exchange the TPO Block and the
Offer Response Block are sent separately by the Merchant to the
Consumer, i.e.:
o the Brand List Component is sent to the Consumer in a TPO Block,
o the Consumer selects a Payment Brand, Payment Protocol and
optionally a Currency and amount from the Brand List Component
o the Consumer sends the selected brand, protocol and
currency/amount back to the Merchant in a TPO Selection Block, and
o the Merchant uses the information received to define the content
of and then send the Offer Response Block to the Consumer.
This is illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
Merchant
STEP
1. Consumer decides to trade and sends to the Merchant
information (e.g., using HTML) that enables the Merchant
to create an offer,
C --> M Offer information - outside scope of IOTP
2. Merchant decides which payment brand protocols,
currencies and amounts apply, places then in a Brand List
Component inside a TPO Block and sends to Consumer
C <-- M TPO. IotpMsg: Trans Ref Block; TPO Block
3. IOTP aware application started. Consumer selects the
payment brand, payment protocol and currency/amount to
use. Records selection in a Brand Selection Component and
sends back to Merchant.
C --> M TPO SELECTION. IotpMsg: Trans Ref Block; TPO Selection
Block
4. Merchant uses selected payment brand, payment protocol,
currency/amount and the offer information to create an
Offer Response Block containing details about the IOTP
Transaction including price, etc. Optionally signs it and
sends to the Consumer
C <-- M OFFER RESPONSE. IotpMsg: Trans Ref Block; Signature Block
(optional); Offer Response Block
5. Consumer checks the Offer is OK, then combines components
from the TPO Block, the TPO Selection Block and the Offer
Response Block to create the next IOTP Message for the
Transaction and sends it together with the Signature
block if present to the required Trading Role
CONTINUED ...
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 19 Brand Dependent Offer Document Exchange
Note, a Consumer identifies a Brand Dependent Offer Document
Exchange, by the absence of an Offer Response Block in the first IOTP
Message.
MESSAGE PROCESSING GUIDELINES
On receiving a TPO IOTP Message (see below), the Consumer may either:
o generate and send a TPO Selection IOTP Message back to the
Merchant, or
o indicate failure to continue with the IOTP Transaction by sending
a Cancel Block back to the Merchant containing a Status Component
with a StatusType of Offer, a ProcessState of Failed and the
CompletionCode (see section 7.16.4) set to either: ConsCancelled
or Unspecified.
On receiving a TPO Selection IOTP Message (see below) the Merchant
may either:
o generate and send an Offer Response IOTP Message back to the
Consumer, or
o indicate failure to continue with the IOTP Transaction by sending
a Cancel Block back to the Consumer containing a Status Component
with a StatusType of Offer, a ProcessState of Failed and the
CompletionCode (see section 7.16.4) set to either: MerchCancelled
or Unspecified.
On receiving an Offer Response IOTP Message (see below) the Consumer
may either:
o generate and send the next IOTP Message in the IOTP transaction
and send it to the required Trading Role. This is dependent on the
IOTP Transaction, or
o indicate failure to continue with the IOTP Transaction by sending
a Cancel Block back to the Merchant containing a Status Component
with a StatusType of Offer, a ProcessState of Failed and the
CompletionCode (see section 7.16.4) set to either: ConsCancelled
or Unspecified.