|
Network Working Group Request for Comments: 2801 Category: Informational |
D. Burdett Commerce One April 2000 |
This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited.
Copyright © The Internet Society (2000). All Rights Reserved.
The Internet Open Trading Protocol (IOTP) provides an interoperable
framework for Internet commerce. It is payment system independent and
encapsulates payment systems such as SET, Secure Channel
Credit/Debit, Mondex, CyberCoin, GeldKarte, etc. IOTP is able to
handle cases where such merchant roles as the shopping site, the
Payment Handler, the Delivery Handler of goods or services, and the
provider of customer support are performed by different parties or by
one party.
1. Background
1.1 Commerce on the Internet, a Different Model
1.2 Benefits of IOTP
1.3 Baseline IOTP
1.4 Objectives of Document
1.5 Scope of Document
1.6 Document Structure
1.7 Intended Readership
1.7.1 Reading Guidelines
2. Introduction
2.1 Trading Roles
2.2 Trading Exchanges
2.2.1 Offer Exchange
2.2.2 Payment Exchange
2.2.3 Delivery Exchange
2.2.4 Authentication Exchange
2.3 Scope of Baseline IOTP
3. Protocol Structure
3.1 Overview
3.1.1 IOTP Message Structure
3.1.2 IOTP Transactions
3.2 IOTP Message
3.2.1 XML Document Prolog
3.3 Transaction Reference Block
3.3.1 Transaction Id Component
3.3.2 Message Id Component
3.3.3 Related To Component
3.4 ID Attributes
3.4.1 IOTP Message ID Attribute Definition
3.4.2 Block and Component ID Attribute Definitions
3.4.3 Example of use of ID Attributes
3.5 Element References
3.6 Extending IOTP
3.6.1 Extra XML Elements
3.6.2 Opaque Embedded Data
3.7 Packaged Content Element
3.7.1 Packaging HTML
3.7.2 Packaging XML
3.8 Identifying Languages
3.9 Secure and Insecure Net Locations
3.10 Cancelled Transactions
3.10.1 Cancelling Transactions
3.10.2 Handling Cancelled Transactions
4. IOTP Error Handling
4.1 Technical Errors
4.2 Business Errors
4.3 Error Depth
4.3.1 Transport Level
4.3.2 Message Level
4.3.3 Block Level
4.4 Idempotency, Processing Sequence, and Message Flow
4.5 Server Role Processing Sequence
4.5.1 Initiating Transactions
4.5.2 Processing Input Messages
4.5.3 Cancelling a Transaction
4.5.4 Retransmitting Messages
4.6 Client Role Processing Sequence
4.6.1 Initiating Transactions
4.6.2 Processing Input Messages
4.6.3 Cancelling a Transaction
4.6.4 Retransmitting Messages
5. Security Considerations
5.1 Determining whether to use digital signatures
5.2 Symmetric and Asymmetric Cryptography
5.3 Data Privacy
5.4 Payment Protocol Security
6. Digital Signatures and IOTP
6.1 How IOTP uses Digital Signatures
6.1.1 IOTP Signature Example
6.1.2 OriginatorInfo and RecipientInfo Elements
6.1.3 Using signatures to Prove Actions Complete
Successfully
6.2 Checking a Signature is Correctly Calculated
6.3 Checking a Payment or Delivery can occur
6.3.1 Check Request Block sent Correct Organisation
6.3.2 Check Correct Components present in Request Block
6.3.3 Check an Action is Authorised
7. Trading Components
7.1 Protocol Options Component
7.2 Authentication Request Component
7.3 Authentication Response Component
7.4 Trading Role Information Request Component
7.5 Order Component
7.5.1 Order Description Content
7.5.2 OkFrom and OkTo Timestamps
7.6 Organisation Component
7.6.1 Organisation IDs
7.6.2 Trading Role Element
7.6.3 Contact Information Element
7.6.4 Person Name Element
7.6.5 Postal Address Element
7.7 Brand List Component
7.7.1 Brand Element
7.7.2 Protocol Brand Element
7.7.3 Protocol Amount Element
7.7.4 Currency Amount Element
7.7.5 Pay Protocol Element
7.8 Brand Selection Component
7.8.1 Brand Selection Brand Info Element
7.8.2 Brand Selection Protocol Amount Info Element
7.8.3 Brand Selection Currency Amount Info Element
7.9 Payment Component
7.10 Payment Scheme Component
7.11 Payment Receipt Component
7.12 Payment Note Component
7.13 Delivery Component
7.13.1 Delivery Data Element
7.14 Consumer Delivery Data Component
7.15 Delivery Note Component
7.16 Status Component
7.16.1 Offer Completion Codes
7.16.2 Payment Completion Codes
7.16.3 Delivery Completion Codes
7.16.4 Authentication Completion Codes
7.16.5 Undefined Completion Codes
7.16.6 Transaction Inquiry Completion Codes
7.17 Trading Role Data Component
7.17.1 Who Receives a Trading Role Data Component
7.18 Inquiry Type Component
7.19 Signature Component
7.19.1 IOTP usage of signature elements and attributes
7.19.2 Offer Response Signature Component
7.19.3 Payment Receipt Signature Component
7.19.4 Delivery Response Signature Component
7.19.5 Authentication Request Signature Component
7.19.6 Authentication Response Signature Component
7.19.7 Inquiry Request Signature Component
7.19.8 Inquiry Response Signature Component
7.19.9 Ping Request Signature Component
7.19.10 Ping Response Signature Component
7.20 Certificate Component
7.20.1 IOTP usage of signature elements and attributes
7.21 Error Component
7.21.1 Error Processing Guidelines
7.21.2 Error Codes
7.21.3 Error Location Element
8. Trading Blocks
8.1 Trading Protocol Options Block
8.2 TPO Selection Block
8.3 Offer Response Block
8.4 Authentication Request Block
8.5 Authentication Response Block
8.6 Authentication Status Block
8.7 Payment Request Block
8.8 Payment Exchange Block
8.9 Payment Response Block
8.10 Delivery Request Block
8.11 Delivery Response Block
8.12 Inquiry Request Trading Block
8.13 Inquiry Response Trading Block
8.14 Ping Request Block
8.15 Ping Response Block
8.16 Signature Block
8.16.1 Signature Block with Offer Response
8.16.2 Signature Block with Payment Request
8.16.3 Signature Block with Payment Response
8.16.4 Signature Block with Delivery Request
8.16.5 Signature Block with Delivery Response
8.17 Error Block
8.18 Cancel Block
9. Internet Open Trading Protocol Transactions
9.1 Authentication and Payment Related IOTP Transactions
9.1.1 Authentication Document Exchange
9.1.2 Offer Document Exchange
9.1.3 Payment Document Exchange
9.1.4 Delivery Document Exchange
9.1.5 Payment and Delivery Document Exchange
9.1.6 Baseline Authentication IOTP Transaction
9.1.7 Baseline Deposit IOTP Transaction
9.1.8 Baseline Purchase IOTP Transaction
9.1.9 Baseline Refund IOTP Transaction
9.1.10 Baseline Withdrawal IOTP Transaction
9.1.11 Baseline Value Exchange IOTP Transaction
9.1.12 Valid Combinations of Document Exchanges
9.1.13 Combining Authentication Transactions with other
Transactions
9.2 Infrastructure Transactions
9.2.1 Baseline Transaction Status Inquiry IOTP Transaction 235
9.2.2 Baseline Ping IOTP Transaction
10. Retrieving Logos
10.1 Logo Size
10.2 Logo Color Depth
10.3 Logo Net Location Examples
11. Brands
11.1 Brand Definitions and Brand Selection
11.1.1 Definition of Payment Instrument
11.1.2 Definition of Brand
11.1.3 Definition of Dual Brand
11.1.4 Definition of Promotional Brand
11.1.5 Identifying Promotional Brands
11.2 Brand List Examples
11.2.1 Simple Credit Card Based Example
11.2.2 Credit Card Brand List Including Promotional Brands..253
11.2.3 Brand Selection Example
11.2.4 Complex Electronic Cash Based Brand List
12. IANA Considerations
12.1 Codes Controlled by IANA
12.2 Codes not controlled by IANA
13. Internet Open Trading Protocol Data Type Definition
14. Glossary
15. References
16. Author's Address
17. Full Copyright Statement
Figure 1 IOTP Trading Roles 16 Figure 2 Offer Exchange 19 Figure 3 Payment Exchange 22 Figure 4 Delivery Exchange 25 Figure 5 Authentication Exchange 27 Figure 6 IOTP Message Structure 33 Figure 7 An IOTP Transaction 34 Figure 8 Example use of ID attributes 46 Figure 9 Element References 48 Figure 10 Signature Digests 79 Figure 11 Example use of Signatures for Baseline Purchase 81 Figure 12 Checking a Payment Handler can carry out a Payment 87 Figure 13 Checking a Delivery Handler can carry out a Delivery 90 Figure 14 Trading Components 94 Figure 15 Brand List Element Relationships 113 Figure 16 Trading Blocks 164 Figure 17 Payment and Authentication Message Flow Combinations 187 Figure 18 Authentication Document Exchange 190 Figure 19 Brand Dependent Offer Document Exchange 196 Figure 20 Brand Independent Offer Exchange 198 Figure 21 Payment Document Exchange 204 Figure 22 Delivery Document Exchange 210 Figure 23 Payment and Delivery Document Exchange 214 Figure 24 Baseline Authentication IOTP Transaction 217 Figure 25 Baseline Deposit IOTP Transaction 219 Figure 26 Baseline Purchase IOTP Transaction 221 Figure 27 Baseline Refund IOTP Transaction 223 Figure 28 Baseline Withdrawal IOTP Transaction 225 Figure 29 Baseline Value Exchange IOTP Transaction 228 Figure 30 Baseline Value Exchange Signatures 230 Figure 31 Valid Combinations of Document Exchanges 231 Figure 32 Baseline Transaction Status Inquiry 238 Figure 33 Baseline Ping Messages 242
The Internet Open Trading Protocol (IOTP) provides an interoperable framework for Internet commerce. It is payment system independent and encapsulates payment systems such as SET, Mondex, CyberCash, DigiCash, GeldKarte, etc. IOTP is able to handle cases where such merchant roles as the shopping site, the Payment Handler, the Delivery Handler of goods or services, and the provider of customer support are performed by different parties or by one party.
The developers of IOTP seek to provide a virtual capability that safely replicates the real world, the paper based, traditional, understood, accepted methods of trading, buying, selling, value exchanging that has existed for many hundreds of years. The negotiation of who will be the parties to the trade, how it will be conducted, the presentment of an offer, the method of payment, the provision of a payment receipt, the delivery of goods and the receipt of goods. These are events that are taken for granted in the course of real world trade. IOTP has been produced to provide the same for the virtual world, and to prepare and provide for the introduction of new models of trading made possible by the expanding presence of the virtual world.
The other fundamental ideal of the IOTP effort is to produce a definition of these trading events in such a way that no matter where produced, two unfamiliar parties using electronic commerce capabilities to buy and sell that conform to the IOTP specifications will be able to complete the business safely and successfully.
In summary, IOTP supports:
The remainder of this section provides background to why IOTP was developed. The specification itself starts in the next chapter.
The growth of the Internet and the advent of electronic commerce are bringing about enormous changes around the world in society, politics and government, and in business. The ways in which trading partners communicate, conduct commerce, are governed have been enriched and changed forever.
One of the very fundamental changes about which IOTP is concerned is
taking place in the way consumers and merchants trade.
Characteristics of trading that have changed markedly include:
ELECTRONIC COMMERCE SOFTWARE VENDORS
Electronic Commerce Software Vendors will be able to develop e- commerce products which are more attractive as they will inter- operate with any other vendors' software. However, since IOTP focuses on how these solutions communicate, there is still plenty of opportunity for product differentiation.
PAYMENT BRANDS
IOTP provides a standard framework for encapsulating payment protocols. This means that it is easier for payment products to be incorporated into IOTP solutions. As a result the payment brands will be more widely distributed and available on a wider variety of platforms.
MERCHANTS
There are several benefits for Merchants:
BANKS AND FINANCIAL INSTITUTIONS
There are also several benefits for Banks and Financial Institutions:
- providing customer care for merchants
- fees from processing new payments and deposits
CUSTOMERS
For Customers there are several benefits:
This specification is Baseline IOTP. It is a Baseline in that it contains ways of doing trades on the Internet which are the most common, for example purchases and refunds.
The group that has worked on the IOTP see an extended version being developed over time but feel a need to focus on a limited function but completely usable specification in order that implementers can develop solutions that work now.
During this period it is anticipated that there will be no changes to the scope of this specification with the only changes made being limited to corrections where problems are found. Software solutions have been developed based on earlier versions of this specification (for example version 0.9 published in early 1998 and earlier revisions of version 1.0 published during 1999) which prove that the IOTP works.
The objectives of this document are to provide a specification of version 1.0 of the Internet Open Trading Protocols which can be used to design and implement systems which support electronic trading on the Internet using the Internet Open Trading Protocols.
The purpose of the document is:
The protocol describes the content, format and sequences of messages that pass among the participants in an electronic trade - consumers, merchants and banks or other financial institutions, and customer care providers. These are required to support the electronic commerce transactions outlined in the objectives above.
The protocol is designed to be applicable to any electronic payment scheme since it targets the complete purchase process where the movement of electronic value from the payer to the payee is only one, but important, step of many that may be involved to complete the trade.
Payment Scheme which IOTP could support include MasterCard Credit, Visa Credit, Mondex Cash, Visa Cash, GeldKarte, eCash, CyberCoin, Millicent, Proton, etc.
Each payment scheme contains some message flows which are specific to
that scheme. These scheme-specific parts of the protocol are
contained in a set of payment scheme supplements to this
specification.
The document does not prescribe the software and processes that will need to be implemented by each participant. It does describe the framework necessary for trading to take place.
This document also does not address any legal or regulatory issues surrounding the implementation of the protocol or the information systems which use them.
The document consists of the following sections:
Software and hardware developers; development analysts; business and technical planners; industry analysts; merchants; bank and other payment handlers; owners, custodians, and users of payment protocols.
This IOTP specification is structured primarily in a sequence targeted at people who want to understand the principles of IOTP. However from practical implementation experience by implementers of earlier of versions of the protocol new readers who plan to implement IOTP may prefer to read the document in a different sequence as described below.
Review the transport independent parts of the specification. This covers:
Review the detailed XML definitions:
The Internet Open Trading Protocols (IOTP) define a number of different types of IOTP Transactions:
These IOTP Transactions are "Baseline" transactions since they have been identified as a minimum useful set of transactions. Later versions of IOTP may include additional types of transactions.
Each of the IOTP Transactions above involve:
Trading Roles, Trading Exchanges and Trading Components are described below.
The Trading Roles identify the different parts which organisations can take in a trade. The five Trading Roles used within IOTP are illustrated in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Merchant Customer Care Provider resolves ----------
---------------------------------------------->| Merchant |
| Consumer disputes and problems |Cust.Care.|
| | Provider |
| ----------
|
Payment Handler accepts or makes ----------
| ------------------------------------------>| Payment |
| | Payment for Merchant | Handler |
| | ----------
v v
---------- Consumer makes purchases or obtains ----------
| Consumer |<--------------------------------------->| Merchant |
---------- refund from Merchant ----------
^
| Delivery Handler supplies goods or ----------
|---------------------------------------------->|Deliverer |
services for Merchant | Handler |
----------
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 1 IOTP Trading Roles
The roles are:
Roles may be carried out by the same organisation or different organisations. For example:
Note that in this specification, unless stated to the contrary, when the words Consumer, Merchant, Payment Handler, Delivery Handler or Customer Care Provider are used, they refer to the Trading Role rather than an actual organisation.
An individual organisation may take multiple roles. For example a company which is selling goods and services on the Internet could take the role of Merchant when selling goods or services and the role of Consumer when the company is buying goods or services itself.
As roles occur in different places there is a need for the organisations involved in the trade to exchange data, i.e. to carry out Trading Exchanges, so that the trade can be completed.
The Internet Open Trading Protocols identify four Trading Exchanges which involve the exchange of data between the Trading Roles. The Trading Exchanges are:
IOTP Transactions are composed of various combinations of these Trading Exchanges. For example, an IOTP Purchase transaction includes Offer, Payment, and Delivery Trading Exchanges. As another example, an IOTP Value Exchange transaction is composed of an Offer Trading Exchange and two Payment Trading Exchanges.
Trading Exchanges consist of Trading Components that are transmitted between the various Trading Roles. Where possible, the number of round-trip delays in an IOTP Transaction is minimised by packing the Components from several Trading Exchanges into combination IOTP Messages. For example, the IOTP Purchase transaction combines a Delivery Organisation Component with an Offer Response Component in order to avoid an extra Consumer request and response.
Each of the IOTP Trading Exchanges is described in more detail below. For clarity of description, these describe the Trading Exchanges as though they were standalone operations. For performance reasons, the Trading Exchanges are intermingled in the actual IOTP Transaction definitions.
The goal of the Offer Exchange is for the Merchant to provide the Consumer with information about the trade so that the Consumer can decide whether to continue with the trade. This is illustrated in the figure below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Merchant
1. Consumer decides to trade and sends information about the
transaction (requests an offer) to the Merchant e.g.,
using HTML.
C --> M Data: Information on what is being purchased (Offer Request)
- outside scope of IOTP
C <-- M OFFER RESPONSE. Components: Status; Organisation(s) (Consumer, DelivTo, Merchant, Payment Handler, Customer Care); Order; Payment; Delivery; TradingRoleData (optional) Offer Response Signature (optional) that signs other components
3. Consumer checks the information from the Merchant and
decides whether to continue.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 2 Offer Exchange
An Offer Exchange uses the following Trading Components that are passed between the Consumer and the Merchant:
- the consumer provides information, about who the consumer is
and, if goods or services are being delivered, where the goods
or services are to be delivered to
- the merchant augments this information by providing information
about the merchant, the Payment Handler, the customer care
provider and, if goods or services are being delivered, the
Delivery Handler
The exact content of the information provided by the Merchant to the Consumer will vary depending on the type of IOTP Transaction. For example:
Information provided by the consumer to the merchant is provided using a variety of methods, for example, it could be provided:
The goal of the Payment Exchange is for a payment to be made from the Consumer to a Payment Handler or vice versa using a payment brand and payment protocol selected by the Consumer. A secondary goal is to optionally provide the Consumer with a digitally signed Payment Receipt which can be used to link the payment to the reason for the payment as described in the Offer Exchange.
Payment Exchanges can work in a variety of ways. The most general case where the trade is dependent on the payment brand and protocol used is illustrated in the diagram below. Simpler payment exchanges are possible.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer Pay Handler
| Merchant |
1. Consumer decides to trade and sends information
about the transaction (requests an offer) to the
Merchant e.g., using HTML.
C --> M Information on what is being paid for (outside
scope of IOTP
4. Merchant checks Brand Selection, creates a Payment
Amount information, optionally signs it to
authorise payment and sends it to the Consumer
C <-- M Component: Payment; Organisation(s) (Merchant and
Payment Handler); Optional Offer Response Signature
that signs other components
C --------> P PAYMENT REQUEST. Components: Status, Payment; Organisations (Merchant and Payment Handler); Trading Role Data (optional); Optional Offer Response Signature that signs other components; Pay Scheme Data
6. Payment Handler checks information including
optional signature and if OK starts exchanging Pay
Scheme Data components for selected payment brand
and payment protocol
C <-------> P PAYMENT EXCHANGE. Component: Pay Scheme Data
7. Eventually payment protocol messages finish so
Payment Handler sends Pay Receipt and optional
signature to the Consumer as proof of payment
C <-------> P PAYMENT RESPONSE. Components: Status, Pay Receipt; Payment Note; Trading Role Data (optional); Optional Offer Response Signature; Optional Payment Receipt Signature that binds the payment to the Offer
8. Consumer checks Payment Receipt is OK *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 3 Payment Exchange
A Payment Exchange uses the following Trading Components that are passed between the Consumer, the Merchant and the Payment Handler:
unauthorised access to account information is prevented through use of secure channel transport mechanisms such as SSL/TLS) as well as currencies/amounts that apply. The Merchant sends the Brand List to the Consumer. The consumer compares the payment brands, protocols and currencies/amounts on offer with those that the Consumer supports and makes a selection.
- the Merchant role is required so that the Payment Handler can
identify which Merchant initiated the payment. Typically, the
result of the Payment Handler accepting (or making) a payment
on behalf of the Merchant will be a credit or debit transaction
to the Merchant's account held by the Payment Handler. These
transactions are outside the scope of this version of IOTP
- the Payment Handler role is required so that the Payment
Handler can check that it is the correct Payment Handler to be
used for the payment
Scheme Component is defined in the supplements that describe how IOTP works with various payment protocols.
The example of a Payment Exchange above is the most general case. Simpler cases are also possible. For example, if the amount paid is not dependent on the payment brand and protocol selected then the payment information generated by step 3 can be sent to the Consumer at the same time as the Brand List Component generated by step 1. These and other variations are described in the Baseline Purchase IOTP Transaction (see section 9.1.8).
The goal of the Delivery Exchange is to cause purchased goods to be delivered to the consumer either online or via physical delivery. A second goal is to provide a "delivery note" to the consumer, providing details about the delivery, such as shipping tracking number. The result of the delivery may also be signed so that it can be used for customer care in the case of problems with physical delivery. The message flow is illustrated in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
CONSUMER DELIVERY
| HANDLER
| Merchant |
1. Consumer decides to trade and sends information
about what to deliver and who is to take delivery,
to the Merchant e.g., using HTML.
C --> M Information on what is being delivered (outside
scope of IOTP)
C <-- M Components: Delivery; Organisations (Delivery
Handler, Deliver To); Order, Optional Offer
Response Signature
C --------> D DELIVERY REQUEST. Components: Status; Delivery, Organisations: (Merchant, Delivery Handler, DelivTo); Order, Trading Role Data (optional); Optional Offer Response Signature, Optional Payment Receipt Signature (from Payment Exchange)
4. Delivery Handler checks information and
authorisation. Starts or schedules delivery and
creates and then sends a delivery not tot the
Consumer which can optionally be signed.
C <-------- D DELIVERY RESPONSE. Components: Status; Delivery Note, Trading Role Data (optional); Optional Delivery Response Signature
5. Consumer checks delivery note is OK and accepts or
waits for delivery as described in the the Delivery
Note.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 4 Delivery Exchange
- the Deliver To role indicates where the goods or services are
to be delivered to
- the Delivery Handler role is required so that the Delivery
Handler can check that she is the correct Delivery Handler to
do the delivery
- the Merchant role is required so that the Delivery Handler can
identify which Merchant initiated the delivery
The goal of the Authentication Exchange is to allow one Organisation, for example a financial institution, to be able to check that another Organisation, for example a consumer, is who they appear to be.
An Authentication Exchange involves:
This is illustrated in the diagram below.
+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Organisation 1
(Authenticatee)
| Organisation 2
| (Authenticator)
1. First Organisation, e.g., a Consumer, takes an action (for
example by pressing a button on an HTML page) which
requires that the Organisation is authenticated
1 --> 2 Need for Authentication (outside scope of IOTP)
2. The second Organisation generates an Authentication
Request - including challenge data, and a list of the
algorithms that may be used for the authentication -
and/or a request for the Organisation information then
sends it to the first Organisation
1 <-- 2 AUTHENTICATION REQUEST. Components: Authentication Request, Trading Role Information Request
3. The first Organisation optionally checks any signature
associated with the Authentication Request then uses the
specified authentication algorithm to generate an
Authentication Response which is sent back to the second
Organisation together with details of any Organisation
information requested
1 --> 2 AUTHENTICATION RESPONSE. Component: Authentication Response, Organisation(s)
4. The Authentication Response is checked against the
challenge data to check that the first Organisation is
who they appear to be and the result recorded in a Status
Component which is then sent back to the first
Organisation.
1 <-- 2 AUTHENTICATION STATUS. Component: Status
5. The first Organisation then optionally checks the results
indicated by the Status and any associated signature and
takes the appropriate action or stops.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 5 Authentication Exchange
An Authentication Exchange uses the following Trading Components that are passed between the two Organisations:
This specification describes the IOTP Transactions which make up Baseline IOTP. As described in the preface, IOTP will evolve over time. This section defines the initial conformance criteria for implementations that claim to "support IOTP."
The main determinant on the scope of an IOTP implementation is the roles which the solution is designed to support. The roles within IOTP are described in more detail in section 2.1 Trading Roles. To summarise the roles are: Merchant, Consumer, Payment Handler, Delivery Handler and Customer Care Provider.
Payment Handlers who can be of three types:
The following table defines, for each role, the IOTP Transactions and Trading Blocks which must be supported for that role.
Merchants
ECash ECash
Store Value Value Consumer Payment Delivery
Issuer Acquirer Handler Handler
TRANSACTIONS
Merchants
ECash ECash
Store Value Value Consumer Payment Delivery
Issuer Acquirer Handler Handler
Depends Depends Depends
Depends Depends Depends
Merchants
ECash ECash
Store Value Value Consumer Payment Delivery
Issuer Acquirer Handler Handler
In the above table:
- if Baseline Authentication IOTP Transaction is supported;
- if required by a Payment Method as defined in its IOTP
Supplement document.
An IOTP solution must support all the IOTP Transactions and Trading Blocks required by at least one role (column) as described in the above table for that solution to be described as "supporting IOTP".
The previous section provided an introduction which explained:
This section describes:
The structure of an IOTP Message and its relationship with Trading Blocks and Trading Components is illustrated in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
| 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 (Optional) Used to check | the signature. |-Trading Block <------- Trading Block - an XML Element within an IOTP | |-Trading Comp. Message that contains a predefined set of | |-Trading Comp. Trading Components | |-Trading Comp. | |-Trading Comp. <--- Trading Components - XML Elements within a | Trading Block that contain a predefined set |-Trading Block of XML elements and attributes containing | |-Trading Comp. information required to support a Trading | |-Trading Comp. Exchange | |-Trading Comp. | |-Trading Comp. | |-Trading Comp. *-*-*-*-*-*--*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 6 IOTP Message Structure
The diagram also introduces the concept of a Transaction Reference Block. This block contains, amongst other things, a globally unique identifier for the IOTP Transaction. Also each block and component is given an ID Attribute (see section 3.4) which is unique within an IOTP Transaction. Therefore the combination of the ID attribute and
the globally unique identifier in the Transaction Reference Block is sufficient to uniquely identify any Trading Block or Trading Component.
A predefined set of IOTP Messages exchanged between the Trading Roles constitute an IOTP Transaction. This is illustrated in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
CONSUMER MERCHANT
Generate first
IOTP Message
--- |
| | v
Process incoming | I | -------------
IOTP Message & <------------- | | ------------ | IOTP Message |
Message | N |
| | |
v | |
------------- | T | Process incoming
| IOTP Message | -------------- | | -----------> IOTP Message &
------------- | | generate next
| E | IOTP Message
| | |
| | v
Process incoming | R | -------------
IOTP Message <------------- | | ------------ | IOTP Message |
Message & stop | N |
| | |
v | |
------------- | E | Process last
| IOTP Message | -------------- | | -------------> incoming IOTP
------------- | | Message & stop
| | T | |
v | | v
STOP --- STOP
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-
Figure 7 An IOTP Transaction
In the above diagram the Internet is shown as the transport mechanism. This is not necessarily the case. IOTP Messages can be transported using a variety of transport mechanisms.
The IOTP Transactions (see section 9) in this version of IOTP are specifically:
As described earlier, IOTP Messages are [XML] documents which are physically sent between the different Trading Roles that are taking part in a trade.
The XML definition of an IOTP Message is as follows.
<!ELEMENT IotpMessage
( TransRefBlk,
SigBlk?,
ErrorBlk?,
( AuthReqBlk |
AuthRespBlk |
AuthStatusBlk |
CancelBlk |
DeliveryReqBlk |
DeliveryRespBlk |
InquiryReqBlk |
InquiryRespBlk |
OfferRespBlk |
PayExchBlk |
PayReqBlk |
PayRespBlk |
PingReqBlk |
PingRespBlk |
TpoBlk |
TpoSelectionBlk
)*
) >
<!ATTLIST IotpMessage
xmlns CDATA
'iotp:ietf.org/iotp-v1.0'
Content:
TransRefBlk This contains information which describes an IOTP
Message within an IOTP Transaction (see section
3.3 immediately below)
AuthReqBlk, These are the Trading Blocks.
AuthRespBlk,
DeliveryReqBlk, The Trading Blocks present within an IOTP Message,
DeliveryRespBlk and the content of a Trading Block itself is
ErrorBlk dependent on the type of IOTP Transaction being
InquiryReqBlk, carried out - see the definition of each
InquiryRespBlk, transaction in section 9 Internet Open Trading
OfferRespBlk, Protocol Transactions.
PayExchBlk,
PayReqBlk, Full definitions of each Trading Block are
PayRespBlk, described in section 8.
PingReqBlk,
PingRespBlk,
SigBlk,
TpoBlk,
TpoSelectionBlk
Attributes:
xmlns The [XML Namespace] definition for IOTP messages.
The IOTP Message is the root element of the XML document. It therefore needs to be preceded by an appropriate XML Document Prolog. For example:
<?XML Version='1.0'?>
<!DOCTYPE IotpMessage >
<IotpMessage>
...
</IotpMessage>
A Transaction Reference Block contains information which identifies the IOTP Transaction and IOTP Message. The Transaction Reference Block contains:
The definition of a Transaction Reference Block is as follows:
<!ELEMENT TransRefBlk (TransId, MsgId, RelatedTo*) >
<!ATTLIST TransRefBlk
ID ID #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Transaction Reference Block within the IOTP
Transaction (see section 3.4 ID Attributes).
Content:
TransId See 3.3.1 Transaction Id Component immediately
below.
MsgId See 3.3.2 Message Id Component immediately below.
RelatedTo See 3.3.3 Related To Component immediately below.
This contains information which globally uniquely identifies the IOTP Transaction. Its definition is as follows:
<!ELEMENT TransId EMPTY >
<!ATTLIST TransId
ID ID #REQUIRED
Version NMTOKEN #FIXED '1.0'
IotpTransId CDATA #REQUIRED
IotpTransType CDATA #REQUIRED
TransTimeStamp CDATA #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Transaction Id Component within the IOTP
Transaction.
Version This identifies the version of IOTP, and therefore
the structure of the IOTP Messages, which the IOTP
Transaction is using.
IotpTransId Contains data which uniquely identifies the IOTP
Transaction. It must conform to the rules for
Message Ids in [RFC 822].
IotpTransTyp This is the type of IOTP Transaction being carried
out. For Baseline IOTP it identifies a "standard"
IOTP Transaction and implies the sequence and
content of the IOTP Messages exchanged between the
Trading Roles. The valid values for Baseline IOTP
are:
Values of IotpTransType are managed under the procedure described in section 12 IANA Considerations which also allows user defined values of IotpTransType to be defined.
In later versions of IOTP, this list will be extended to support different types of standard IOTP Transaction. It is also likely to support the type Dynamic which indicates that the sequence of steps within the transaction are non-standard.
TransTimeStamp Where the system initiating the IOTP Transaction
has an internal clock, it is set to the time at
which the IOTP Transaction started in [UTC]
format.
The main purpose of this attribute is to provide an alternative way of identifying a transaction by specifying the time at which it started.
Some systems, for example, hand held devices may not be able to generate a time stamp. In this case this attribute should contain the value "NA" for Not Available.
The Message Id Component provides control information about the IOTP Message as well as uniquely identifying the IOTP Message within an IOTP Transaction. Its definition is as follows.
<!ELEMENT MsgId EMPTY >
<!ATTLIST MsgId
ID ID #REQUIRED
RespIotpMsg NMTOKEN #IMPLIED
xml:lang NMTOKEN #REQUIRED
LangPrefList NMTOKENS #IMPLIED
CharSetPrefList NMTOKENS #IMPLIED
SenderTradingRoleRef NMTOKEN #IMPLIED
SoftwareId CDATA #REQUIRED
TimeStamp CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
IOTP Message within the IOTP Transaction (see
section 3.4 ID Attributes). Note that if an
IOTP Message is resent then the value of this
attribute remains the same.
RespIotpMsg This contains the ID attribute of the Message
Id Component of the IOTP Message to which this
IOTP Message is a response. In this way all
the IOTP Messages in an IOTP Transaction are unambiguously linked together. This field is required on every IOTP Message except the first IOTP Message in an IOTP Transaction.
SenderTradingRoleRef The Element Reference (see section 3.5) of the
Trading Role which has generated the IOTP
message. It is used to identify the Net
Locations (see section 3.9) of the Trading
Role to which problems Technical Errors (see
section 4.1) with any of Trading Blocks should
be reported.
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.
LangPrefList Optional list of Language codes that conform
to [XML] Language Identification. It is used
by the sender to indicate, in preference
sequence, the languages that the receiver of
the message ideally should use when generating
a response. There is no obligation on the
receiver to respond using one of the indicated
languages, but using one of the languages is
likely to provide an improved user experience.
CharSetPrefList Optional list of Character Set identifiers
that conform to [XML] Characters. It is used
by the sender to indicate, in preference
sequence, the character sets that the receiver
of the message ideally should use when
generating a response. There is no obligation
on the receiver to respond using one of the
character sets indicated, but using one of the
character sets is likely to provide an
improved user experience.
SoftwareId This contains information which identifies the
software which generated the IOTP Message. Its
purpose is to help resolve interoperability
problems that might occur as a result of
incompatibilities between messages produced by
different software. It is a single text string
in the language defined by xml:lang. It must
contain, as a minimum:
TimeStamp Where the device sending the message has an
internal clock, it is set to the time at which
the IOTP Message was created in [UTC] format.
The Related To Component links IOTP Transactions to either other IOTP Transactions or other events using the identifiers of those events. Its definition is as follows.
<!ELEMENT RelatedTo (PackagedContent) >
<!ATTLIST RelatedTo
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
RelationshipType NMTOKEN #REQUIRED
Relation CDATA #REQUIRED
RelnKeyWords NMTOKENS #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Related To 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.
RelationshipType Defines the type of the relationship. Valid values
are:
Values of RelationshipType are controlled under the procedures defined in section 12 IANA Considerations which also allows user defined values to be defined.
Relation The Relation attribute contains a phrase in the
language defined by xml:lang which describes the
nature of the relationship between the IOTP
transaction that contains this component and
another IOTP Transaction or other event. The exact
words to be used are left to the implementers of
the IOTP software.
The purpose of the attribute is to provide the Trading Roles involved in an IOTP Transaction with an explanation of the nature of the relationship between the transactions.
Care should be taken that the words used to in the Relation attribute indicate the "direction" of the relationship correctly. For example: one transaction might be a refund for another earlier transaction. In this case the transaction which is a refund should contain in the Relation attribute words such as "refund for" rather than "refund to" or just "refund".
RelnKeyWords This attribute contains keywords which could be
used to help identify similar relationships, for
example all refunds. It is anticipated that
recommended keywords will be developed through
examination of actual usage. In this version of
the specification there are no specific
recommendations and the keywords used are at the
discretion of implementers.
Content:
PackagedContent The Packaged Content (see section 3.7) contains
data which identifies the related transaction. Its
format varies depending on the value of the
RelationshipType.
IOTP Messages, Blocks (i.e. Transaction Reference Blocks and Trading Blocks), Trading Components (including the Transaction Id Component and the Signature Component) and some of their child elements are each given an XML "ID" attribute which is used to identify an instance of these XML elements. These identifiers are used so that one element can be referenced by another. All these attributes are given the attribute name ID.
The values of each ID attribute are unique within an IOTP transaction i.e. the set of IOTP Messages which have the same globally unique Transaction ID Component. Also, once the ID attribute of an element has been assigned a value it is never changed. This means that whenever an element is copied, the value of the ID attribute remains the same.
As a result it is possible to use these IDs to refer to and locate the content of any IOTP Message, Block or Component from any other IOTP Message, Block or Component in the same IOTP Transaction using Element References (see section 3.5).
This section defines the rules for setting the values for the ID attributes of IOTP Messages, Blocks and Components.
The ID attribute of the Message Id Component of an IOTP Message must be unique within an IOTP Transaction. It's definition is as follows:
IotpMsgId_value ::= IotpMsgIdPrefix IotpMsgIdSuffix
IotpMsgIdPrefix ::= NameChar (NameChar)*
IotpMsgIdSuffix ::= Digit (Digit)*
IotpMsgIdPrefix Apart from messages which contain: an Inquiry
Request Trading Block, an Inquiry Response Trading
Block, a Ping Request Trading Block or a Ping
Response Trading Block; then the same prefix is
used for all messages sent by the Merchant or
Consumer role as follows:
For messages which contain an Inquiry Request Trading Block or a Ping Request Trading Block, the prefix is set to "I" for Inquiry.
For messages which contain an Inquiry Response Trading Block or a Ping Response Trading Block, the prefix is set to "Q".
The prefix for the other roles in a trade is contained within the Organisation Component for the role and are typically set by the Merchant. The following is recommended as a guideline and must not be relied upon:
As a guideline, prefixes should be limited to one character.
NameChar has the same definition as the [XML] definition of NameChar.
IotpMsgIdSuffix The suffix consists of one or more digits. The
suffix must be unique within a Trading Role within
an IOTP Transaction. The following is recommended
as a guideline and must not be relied upon:
Put more simply the Message Id Component of the first IOTP Message sent by a Consumer would have an ID attribute of, "C1", the second "C2", the third "C3" etc.
Digit has the same definition as the [XML] definition of Digit.
The ID Attribute of Blocks and Components must also be unique within an IOTP Transaction. Their definition is as follows:
BlkOrCompId_value ::= IotpMsgId_value "." IdSuffix
IdSuffix ::= Digit (Digit)*
IotpMsgId_value The ID attribute of the Message ID Component of
the IOTP Message where the Block or Component is
first used.
In IOTP, Trading Components and Trading Blocks are copied from one IOTP Message to another. The ID attribute does not change when an existing Trading Block or Component is copied to another IOTP Message.
IdSuffix The suffix consists of one or more digits. The
suffix must be unique within the ID attribute of
the Message ID Component used to generate the ID
attribute. The following is recommended as a
guideline and must not be relied upon:
Put more simply, the first new Block or Component added to the second IOTP Message sent, for example, by a consumer would have a an ID attribute of "C2.1", the second "C2.2", the third "C2.3" etc.
Digit has the same definition as the [XML] definition of Digit.
The diagram below illustrates how ID attribute values are used.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
1st IOTP MESSAGE 2nd IOTP MESSAGE
(e.g., from Merchant to (e.g., from Consumer to
Consumer Payment Handler)
|-Trans Ref Block. ID=M1.1 |-Trans Ref Block.ID=C1.1*
| |-Trans Id Comp. ID = M1.2 ------------>| |-Trans Id Comp.
| | Copy Element | | ID=M1.2
| |-Msg Id Comp. ID = M1 | |-Msg Id Comp. ID=C1 *
| |
|-Signature Block. ID=M1.8 |-Signature Block.ID=C1.5*
| |-Sig Comp. ID=M1.15 ------------------>| |-Comp. ID=M1.15
| Copy Element |
|-Trading Block. ID=M1.3 |-Trading Block.ID=C1.2 *
| |-Comp. ID=M1.4 -------------------------->|-Comp. ID=M1.4
| | Copy Element |
| |-Comp. ID=M1.5 -------------------------->|-Comp. ID=M1.5
| | Copy Element |
| |-Comp. ID=M1.6 |-Comp. ID=C1.3 *
| |-Comp. ID=M1.7 |-Comp. ID=C1.4 *
|
|-Trading Block. ID=M1.9
|-Comp. ID=M1.10 * = new elements
|-Comp. ID=M1.11
|-Comp. ID=M1.12
|-Comp. ID=M1.13
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-
Figure 8 Example use of ID attributes
A Trading Component or one of its child XML elements, may contain an XML attribute that refers to another Block (i.e. a Transaction Reference Block or a Trading Block) or Trading Component (including a Transaction Id and Signature Component). These Element References are used for many purposes, a few examples include:
An Element Reference always contains the value of an ID attribute of a Block or Component.
Identifying the IOTP Message, Trading Block or Trading Component which is referred to by an Element Reference, involves finding the XML element which:
Note: The term "match" in this specification has the same definition as the [XML] definition of match.
An example of "matching" an Element Reference is illustrated in the example below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
1st IOTP MESSAGE 2nd IOTP MESSAGE
(e.g., from Merchant to (e.g., from Consumer to
Consumer Payment Handler)
IOTP MESSAGE IOTP MESSAGE
|-Trans Ref Block. ID=M1.1 Trans ID |-Trans RefBlock. ID=C1.1
| |-Trans Id Comp. ID = M1.2 <-Components-|->|-TransId Comp.ID=M1.2
| | must be | |
| |-Msg Id Comp. ID = M1 Identical | |-Msg Id Comp. ID=C1
| ^ |
|-Signature Block. ID=M1.8 | |-Signature Block.ID=C1.5
| |-Sig Comp. ID=M1.15 | | |-Comp. ID=M1.15
| AND |
|-Trading Block. ID=M1.3 | |-Trading Block. ID=C1.2
| |-Comp. ID=M1.4 | |-Comp. ID=M1.4
| | v |
| |-Comp. ID=M1.5 <-------- -ID Attribute |-Comp. ID=M1.5
| | and El Ref |
| |-Comp. ID=M1.6 values must |-Comp. ID=C1.3
| | match--------|--> El Ref=M1.5
| |-Comp. ID=M1.7 |-Comp. ID=C1.4
|
|-Trading Block. ID=M1.9
|-Comp. ID=M1.10
|-Comp. ID=M1.11
|-Comp. ID=M1.12
|-Comp. ID=M1.13
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-
Figure 9 Element References
Note: Element Reference attributes are defined as "NMTOKEN" rather than "IDREF" (see [XML]). This is because an IDREF requires that the XML element referred to is in the same XML Document. With IOTP this is not necessarily the case.
Baseline IOTP defines a minimum protocol which systems supporting IOTP must be able to accept. As new versions of IOTP are developed, additional types of IOTP Transactions will be defined. In addition to this, Baseline and future versions of IOTP will support user extensions to IOTP through two mechanisms:
The XML element and attribute names used within IOTP constitute an [XML Namespace] as identified by the xmlns attribute on the IotpMessage element. This allows IOTP to support the inclusion of additional XML elements within IOTP messages through the use of [XML Namespaces].
Using XML Namespaces, extra XML elements may be included at any level within an IOTP message including:
The following rules apply:
In order to make sure that extra XML elements can be processed
properly, IOTP reserves the use of a special attribute,
IOTP:Critical, which takes the values True or False and may appear in
extra elements added to an IOTP message.
The purpose of this attribute is to allow an IOTP aware application to determine if the IOTP transaction can safely continue. Specifically:
- any extra XML elements contained within an XML element defined
within the IOTP namespace, must be included with that element
whenever the IOTP XML element is used or copied by IOTP
- the content of the extra element must be ignored except that it
must be included when it is used in the creation of a digest as
part of the generation of a signature
In order to ensure that documents containing "IOTP:Critical" are valid, it is declared as part of the DTD for the extra element as:
IOTP:Critical (True | False ) 'True'
If IOTP is to be extended using Opaque Embedded Data then a Packaged Content Element (see section 3.7) should be used to encapsulate the data.
The Packaged Content element supports the concept of an embedded data stream, transformed to both protect it against misinterpretation by transporting systems and to ensure XML compatibility. Examples of its use in IOTP include:
In general it is used to encapsulate one or more data streams.
This data stream has three standardised attributes that allow for identification, decoding and interpretation of the contents. Its definition is as follows.
<!ELEMENT PackagedContent (#PCDATA) >
<!ATTLIST PackagedContent
Name CDATA #IMPLIED
Content NMTOKEN "PCDATA"
Transform (NONE|BASE64) "NONE" >
Attributes:
Name Optional. Distinguishes between multiple
occurrences of Packaged Content Elements at the
same point in IOTP. For example:
<ABCD>
<PackagedContent Name='FirstPiece'>
snroasdfnas934k
</PackagedContent>
<PackagedContent Name='SecondPiece'>
dvdsjnl5poidsdsflkjnw45
</PackagedContent>
</ABCD>
The name attribute may be omitted, for example if there is only one Packaged Content element.
Content This identifies what type of data is contained
within the Content of the Packaged Content
Element. The valid values for the Content
attribute are as follows:
Values of the Content attribute are controlled under the procedures defined in section 12 IANA Considerations which also allows user defined values to be defined.
Transform This identifies the transformation that has been
done to the data before it was placed in the
content. Valid values are:
Content:
PCDATA This is the actual data which has been embedded.
The format of the data and rules on how to decode
it are contained in the Content and the Transform
attributes
Note that any special details, especially custom attributes, must be represented at a higher level.
The packaged content may contain HTML. In this case the following conventions are followed:
If the above conventions are not followed by, for example, including external references which must be resolved, then the recipient of the HTML should be informed.
Note: As an implementation guideline the values of the Name Attributes allocated to Packaged Content elements should make it possible to extract each Packaged Content into a directory and then display the HTML directly
Support for XML is recommended. When XML needs to be displayed, for example to display the content of an Order Description to a Consumer, then implementers should follow the latest recommendations of the World Wide Web Consortium.
Note: At the time of writing this specification, standards are under development that specify XML style sheets that show how XML documents should be displayed. See:
Once these standards become W3C "Recommendations", then it is anticipated that this specification will be amended if practical.
IOTP uses [XML] Language Identification to specify which languages are used within the content and attributes of IOTP Messages.
The following principles have been used in order to determine which XML elements contain an xml:lang Attributes:
xml:lang attributes which follow these principles are included in the Trading Components and their child XML elements defined in section 7.
A sender of a message, typically a Consumer can indicate a preference for a language, and a character set by specifying a list of preferred languages/character sets in a Message Id Component (see section 3.3.2). Note that there is no obligation on the receiver of such a message to respond using one of the listed languages/character sets as they may not have the technology to be able to do it. It also means that the ability to handle these lists is not a requirement for conformance to this specification. However the ability to respond, for example using one of the stated languages/character sets is likely to provide a better user experience.
IOTP contains several "Net Locations" which identify places where, typically, IOTP Messages may be sent. Net Locations come in two types:
Note that either a Secure Net Location or an Insecure Net Location or both must be present.
If only one of the two Net Locations is present, then the one present must be used.
Where both types of net location are present then either may be used depending on the preference of the sender of the message.
Any Trading Role involved in an IOTP transaction may cancel that transaction at any time.
IOTP Transactions are cancelled by sending an IOTP message containing just a Cancel Block with an appropriate Status Component to the other Trading Role involved in the Trading Exchange.
Note: The Cancel Block can be sent asynchronously of any other IOTP Message. Specifically it can be sent either before sending or after receiving an IOTP Message from the other Trading Role
If an IOTP Transaction is cancelled during a Trading Exchange (i.e. the interval between sending a "request" block and receiving the matching "response" block) then the Cancel Block is sent to the same location as the next IOTP Message in the Trading Exchange would have been sent.
If a Consumer cancels a transaction after a Trading Exchange has
completed (i.e. the "response" block for the Trading Exchange has
been received), but before the IOTP Transaction has finished then the
Consumer sends a Cancel Block with an appropriate Status Component to
the net location identified by the SenderNetLocn or
SecureSenderNetLocn contained in the Protocol Options Component (see
section 7.1) contained in the TPO Block (see section 8.1) for the
transaction. This is normally the Merchant Trading Role.
A Consumer should not send a Cancel Block after the IOTP Transaction has completed. Cancelling a complete transaction should be treated as a technical error.
After cancelling the IOTP Transaction, the Consumer should go to the net location specified by the CancelNetLocn attribute contained in the Trading Role Element for the Organisation that was sent the Cancel Block.
A non-Consumer Trading Role should only cancel a transaction:
If a non-Consumer Trading Role cancels a transaction at any other time it should be treated by the recipient as an error.
If a Cancel Block is received by a Consumer at a point in the IOTP Transaction when cancellation is allowed, then the Consumer should stop the transaction.
If a Cancel Block is received by a non-Consumer role, then the Trading Role should anticipate that the Consumer may go to the location specified by the CancelNetLocn attribute contained in the Trading Role Element for the Trading Role.
IOTP is designed as a request/response protocol where each message is composed of a number of Trading Blocks which contain a number of Trading Components. There are several interrelated considerations in handling errors, re-transmissions, duplicates, and the like. These factors mean IOTP aware applications must manage message flows more complex than the simple request/response model. Also a wide variety of errors can occur in messages as well as at the transport level or in Trading Blocks or Components.
This section describes at a high level how IOTP handles errors, retries and idempotency. It covers:
- "technical errors" which are independent of the purpose of the
IOTP Message,
- "business errors" which indicate that there is a problem
specific to the process (e.g., payment or delivery) which is
being carried out, and
Technical Errors are those which are independent of the meaning of the message. This means, they can affect any attempt at IOTP communication. Typically they are handled in a standard fashion with a limited number of standard options for the user. Specifically these are:
When communications are operating sufficiently well, a technical error is indicated by an Error Component (see section 7.21) in an Error Block (see section 8.17) sent by the party which detected the error in an IOTP message to the party which sent the erroneous message.
If communications are too poor, a message which was sent may not reach its destination. In this case a time-out might occur.
The Error Codes associated with Technical Errors are recorded in the Error Component which lists all the different technical errors which can be set.
Business Errors may occur when the IOTP messages are "technically" correct. They are connected with a particular process, for example, an offer, payment, delivery or authentication, where each process has a different set of possible business errors.
For example, "Insufficient funds" is a reasonable payment error but makes no sense for a delivery while "Back ordered" is a reasonable delivery error but not meaningful for a payment. Business errors are indicated in the Status Component (see section 7.16) of a "response block" of the appropriate type, for example a Payment Response Block or a Delivery Response Block. This allows whatever additional response related information is needed to accompany the error indication.
Business errors must usually be presented to the user so that they can decide what to do next. For example, if the error is insufficient funds in a Brand Independent Offer (see section 9.1.2.2), the user might wish to choose a different payment instrument/account of the same brand or a different brand or payment system. Alternatively, if
the IOTP based implementation allows it and it makes sense for that instrument, the user might want to put more funds into the instrument/account and try again.
The three levels at which IOTP errors can occur are the transport level, the message level, and the block level. Each is described below.
This level of error indicates a fundamental problem in the transport mechanism over which the IOTP communication is taking place.
All transport level errors are technical errors and are indicated by either an explicit transport level error indication, such as a "No route to destination" error from TCP/IP, or by a time out where no response has been received to a request.
The only reasonable automatic action when faced with transport level errors is to retry and, after some number of automatic retries, to inform the user.
The explicit error indications that can be received are transport dependent and the documentation for the appropriate IOTP Transport supplement should be consulted for errors and appropriate actions.
Appropriate time outs to use are a function of both the transport being used and of the payment system if the request encapsulates payment information. The transport and payment system specific documentation should be consulted for time out and automatic retry parameters. Frequently there is no way to directly inform the other party of transport level errors but they should generally be logged and if automatic recovery is unsuccessful and there is a human user, the user should be informed.
This level of error indicates a fundamental technical problem with an entire IOTP message. For example, the XML is not "Well Formed", or the message is too large for the receiver to handle or there are errors in the Transaction Reference Block (see section 3.3) so it is not possible to figure out what transaction the message relates to.
All message level errors are technical errors and are indicated by Error Components (see section 7.21) sent to the other party. The Error Component includes a Severity attribute which indicates whether
the error is a Warning and may be ignored, a TransientError which indicates that a retry may resolve the problem or a HardError in which case the transaction must fail.
The Technical Errors (see section 7.21.2 Error Codes) that are Message Level errors are:
Note that checks on the Signature Block include checking, where possible, that each Signature Component is correctly calculated. If the Signature is incorrectly calculated then the data that should have been covered by the signature can not be trusted and must be treated as erroneous. A description of how to check a signature is correctly calculated is contained in section 6.2.
A Block level error indicates a problem with a block or one of its components in an IOTP message (apart from Transaction Reference or Signature Blocks). The message has been transported properly, the overall message structure and the block/component(s) including the Transaction Reference and Signature Blocks are meaningful but there is some error related to one of the other blocks.
Block level errors can be either:
Technical Errors are further divided into:
If a technical error occurs related to a block or component, then an Error Component is generated for return.
Block Level Attribute and Element Checks occur only within the same block. Checks which involve cross-checking against other blocks are covered by Block and Component Consistency Checks.
The Block Level Attribute & Element checks are:
Block and Component Consistency Checks consist of:
If the block passes the "Block Level Attribute and Element Checks" and the "Block and Component Consistency Checks" then it is processed either by the IOTP Aware application or perhaps by some "back-end" system such as a payment server.
During the processing of the Block some temporary failure may occur that can potentially be recovered by the other trading role re- transmitting, at some slightly later time, the original message that they sent. In this case the other role is informed of the Transient
Error by sending them an Error Component (see section 7.21) with the Severity Attribute set to TransientError and the MinRetrySecs attribute set to some value suitable for the Transport Mechanism and/or payment protocol being used (see appropriate Transport and payment protocol Supplements).
Note that transient technical errors can be generated by any of the Trading Roles involved in transaction.
If a business error occurs in a process such as a Payment or a Delivery, then the appropriate type of response block is returned containing a Status Component (see section 7.16) with the ProcessState attribute set to Failed and the CompletionCode indicating the nature of the problem.
Some business errors may be "transient" in that the Consumer role may be able to recover and complete the transaction in some other way. For example if the Credit Card that a consumer provided had insufficient funds for a purchase, then the Consumer may recover by using a different credit card.
Recovery from "transient" business errors is dependent on the CompletionCode. See the definition of the Status Component for what is possible.
Note that no Error Component or Error Block is generated for business errors.
IOTP messages are actually a combination of blocks and components as
described in 3.1.1 IOTP Message Structure. Especially in future
extensions of IOTP, a rich variety of combinations of such blocks and
components can occur. It is important that the multiple
transmission/receipt of the "same" request for an action that will
change state does not result in that action occurring more than once.
This is called idempotency. For example, a customer paying for an
order would want to pay the full amount only once. Most network
transport mechanisms have some probability of delivering a message
more than once or not at all, perhaps requiring retransmission. On
the other hand, a request for status can reasonably be repeated and
should be processed fresh each time it is received.
Correct implementation of IOTP can be modelled by a particular processing order as detailed below. Any other method that is indistinguishable in the messages sent between the parties is equally acceptable.
"Server roles" are any Trading Role which is not the Consumer role. They are "Server roles" since they typically receive a request which they must service and then produce a response. However server roles can also initiate transactions. More specifically Server Roles must be able to:
- payment related transactions and
- infrastructure transactions
- identifying if the message belongs to a transaction that has
been received before
- handling duplicate messages
- generating Transient errors if the servers that process the
input message are too busy to handle it
- processing the message if it is error free, authorised and, if
appropriate, producing a response to send back to the other
role
Server Roles may initiate a variety of different types of transaction. Specifically:
- a Deposit (see section 9.1.7)
- a Purchase (see section 9.1.8)
- a Refund (see section 9.1.9)
- a Withdrawal (see section 9.1.10)
- a Value Exchange (see section 9.1.11)
Processing input messages involves the following:
- checking for errors, then if no errors are found
- processing the message to produce an output message if
appropriate
Each of these is discussed in more detail below.
It is critical to check that the message is "well formed" XML and that the transaction identifier (IotpTransId attribute on the TransId Component) within the IOTP message can be successfully identified since an IotpTransId will be needed to generate a response.
If the input message is not well formed then generate an Error
Component with a Severity of HardError and ErrorCode of
XmlNotWellFrmd.
If the message is well formed but the IotpTransId cannot be identified then generate an ErrorComponent with:
Insert the Error Component inside an Error Block with a new TransactionId component with a new IotpTransId and return it to the sender of the original message.
If the input message can be identified as potentially a valid input message then check to see if an "identical" input message has been received before. Identical means that all blocks, components, elements, attribute values and element content in the input message are the same.
Note: The recommended way of checking for identical messages is to check for equal values of their [DOM-HASH]
If an identical message has been received before then check to see if the processing of the previous message has completed.
If processing has not completed then generate an Error Component with a Severity of Transient Error and an Error Code of MsgBeingProc to indicate the message is being processed and send it back to the sender of the Input Message requesting that the original message be resent after an appropriate period of time.
Otherwise, if processing has completed and resulted in an output message then retrieve the last message that was sent and send it again.
If the message is not a duplicate then it should be processed.
Once it's been established that the message is not a duplicate, then it can be processed. This involves:
- checking for message level errors
- checking for block level errors
- checking any encapsulated data
Note: This approach to handling of duplicate input messages means, if absolutely "identical" messages are received then absolutely "identical" messages are returned. This also applies to Inquiry and Ping transactions when in reality the state of a transaction or the processing ability of the servers may have changed. If up-to-date status of transactions or servers is required, then an IOTP transaction with a new value for the ID attribute of the MsgId component must be used.
Each of the above steps is discussed below.
CHECKING A SERVER IS AVAILABLE
The process that is handling the input message should check that the rest of the system is not so busy that a response in a reasonable time cannot be produced.
If the server is too busy, then it should generate an Error Component with a Severity of Transient Error and an Error Code of SystemBusy and send it back to the sender of the Input Message requesting that the original message be resent after an appropriate period of time.
Note: Some servers may occasionally become very busy due to unexpected increases in workload. This approach allows short peaks in workloads to be handled by delaying the input of messages by asking the sender of the message to resubmit later.
CHECKING THE TRANSACTION IS NOT ALREADY IN ERROR OR CANCELLED
Check that:
If it has then, ignore the message. A transaction with hard errors or that has been cancelled, cannot be restarted.
CHECK FOR MESSAGE AND BLOCK LEVEL ERRORS
If the transaction is still OK then check for message level errors. This involves:
- checking that the Signature value is correctly calculated, and
- the hash values in the digests are correctly calculated where
the source of the hash value is available.
Checking for block level errors involves:
- the attributes, elements and element contents are valid
- the values of the attributes, elements and element contents are
consistent within the block
If the message contains any encapsulated data, then if possible check the encapsulated data for errors using additional software to check the data where appropriate.
Note: For reasons of brevity, the following explanations of how to check for errors in Block sequence, the phrase "refers to an IOTP transaction" is interpreted as "is contained in an IOTP Message where
the Trans Ref Block contains an IotpTransId that refers to". So, for example, " If an Error or Cancel Block refers to an IOTP transaction that is not recognised then ..." should be interpreted as " If an Error or Cancel Block is contained in an IOTP Message where the Trans Ref Block contains an IotpTransId that refers to an IOTP transaction that is not recognised then ...
Errors in the sequence that blocks arrive depends on the block. Blocks where checking for sequence is required are:
- if an Authentication Response Block does not refer to an IOTP
transaction that is recognised it is a Hard Error, otherwise
- if the Authentication Response Block doesn't refer to an
Authentication Request that had been previously sent then it is
a Hard Error, otherwise
- if an Authentication Response for the same IOTP transaction has
been received before and the Authentication was successful then
it is a Hard Error.
- if an Authentication Status Block does not refer to an IOTP
transaction that is recognised it is a Hard Error, otherwise
- if the Authentication Status Block doesn't refer to an
Authentication Response that had been previously sent then it
is a Hard Error, otherwise
- if an Authentication Status for the same IOTP transaction has
been received before then it is a Warning Error
- if the TPO Selection Block doesn't refer to an IOTP Transaction
that is recognised then it is a Hard Error, otherwise
- if the TPO Selection Block refers to an IOTP Transaction where
a TPO Block and Offer Response (in one message) had previously
been sent then it is a Hard Error, otherwise
- if the TPO Selection Block does not refer to an IOTP
Transaction where a TPO Block only (i.e. without an Offer
Response) had previously been sent then it is a Hard Error,
otherwise
- if a TPO Selection Block for the same TPO Block has been
received before then it is a Hard Error
- if the Payment Request Block refers to an IOTP Transaction that
is not recognised then its OK, otherwise
- if the Payment Request Block refers to IOTP Transaction that
was not for a Payment then it is a Hard Error, otherwise
- if there was a previous payment that failed with a non-
recoverable Completion Code then it is a Hard Error, otherwise
- if a previous payment is still in progress then it is a Hard
Error
- if the Payment Exchange Block doesn't refer to an IOTP
Transaction that is recognised then it is a Hard Error,
otherwise
- if the Payment Exchange doesn't refer to an IOTP Transaction
where a Payment Exchange had previously been sent then it a
Hard Error
If any Error Components have been generated then collect them into an Error Block for sending to the sender of the Input message. Note that Error Blocks should be sent back to the sender of the message and to the ErrorLogNetLocn for the Trading Role of the sender if one is specified.
Note: The above checking on the sequence of Authentication Responses and Payment Requests supports the Consumer re-submitting a repeat action request since the previous one failed, for example:
PROCESS THE ERROR FREE INPUT MESSAGE
If the input message passes the previous checks then it can be processed to produce an output message if required. Note that:
If an output message is generated then it should be saved so that it can be resent as required if an identical input message is received again. Note that output messages that contain transient errors are not saved so that they can be processed afresh when the input message is received again.
This process is used to cancel a transaction running on an IOTP server. It is initiated by some other process as a result of an external request from another system or server that is being run by the same Trading Role. The processing required is as follows:
Note: Cancelling a transaction on an IOTP server typically arises for a business reason. For example a merchant may have attempted authentication several times without success and as a result decides to cancel the transaction. Therefore the process that decides to take this action needs to send a message from the process/server that made the business decision to the IOTP server with the instruction that the IOTP transaction should be cancelled.
The server should periodically check for transactions where a message is expected in return but none has been received after a time that is dependent on factors such as:
If no message has been received the original message should be resent. This should occur up to a maximum number of times dependent on the reliability of the Transport Mechanism being used.
If no response is received after the required time then the Transaction should be "timed out". In this case, set the process state of the transaction to Failed, and a completion code of either:
The "Client role" in IOTP is the Consumer Trading Role.
Note: A company or Organisation that is a Merchant, for example, may take on the Trading Role of a Consumer when making purchases or downloading or withdrawing electronic cash.
More specifically the Consumer Role must be able to:
- payment related transactions and
- infrastructure transactions
- identifying if the message belongs to a transaction that has
been received before
- handling duplicate messages
- generating Transient errors if the servers that process the
input message are too busy to handle it
- processing the message if it is error free and, if appropriate,
producing a response to send back to the other role
The Consumer Role may initiate a number of different types of transaction. Specifically:
Processing of Input Messages for a Consumer Role is the same as for an IOTP Server (see section 4.5.2) except in the area of checking for Errors in Block Sequence (for an IOTP Server see section 4.5.2.4). This is described below
Note: The description of the processing for an IOTP Server includes consideration of multi-threading of input messages and multi-tasking of requests. For the Consumer Role - particularly if running on a stand-alone system such as a PC - use of multi-threading is a decision of the implementer of the consumer role IOTP solution.
The handling of the following blocks is the same as for an IOTP Server (see section 4.5.2.4) except that the Consumer Role is substituted for IOTP Server Role:
For the other blocks a Consumer role might receive, the potential errors in the sequence that blocks arrive depends on the block. Blocks where checking for sequence is required are:
- if the input message also contains an Authentication Request
block and an Offer Response Block then there is a Hard Error,
otherwise
- if the input message also contains an Authentication Request
block and Authentication Status block then there is Hard Error
otherwise,
- if the input message also contains an Authentication Request
block and the IOTP Transaction is recognised by the Consumer
role's system, then there is a Hard Error, otherwise
- if the input message also contains an Authentication Status
block and the IOTP Transaction is not recognised by the
Consumer role's system then there is a Hard Error, otherwise
- if input message also contains an Authentication Status Block
and the Authentication Status Block has not been sent after an
earlier Authentication Response message then there is a hard
error
- if input message also contains an Offer Response Block and the
IOTP Transaction is recognised by the Consumer role's system
then there is a Hard Error, otherwise
- if the TPO Block occurs on its own and the IOTP Transaction is
recognised by the Consumer role's system then there is a Hard
Error
- if the Offer Response Block is part of a Brand Independent
Offer Exchange (see section 9.1.2.2) then there is no sequence
checking as it is part of the first message received, otherwise
- if the Offer Response Block is not part of an IOTP Transaction
that is recognised by the Consumer role then there is a Hard
Error, otherwise
- if the Offer Response Block does not refer to an IOTP
transaction where a TPO Selection Block was the last message
sent then there is a Hard Error
- if the Payment Exchange Block doesn't refer to an IOTP
Transaction that is recognised by the Consumer role's system
then there is a Hard Error, otherwise
- if the Payment Exchange doesn't refer to an IOTP Transaction
where either a Payment Request or a Payment Exchange block was
most recently sent then there is a Hard Error
- if the Payment Response Block doesn't refer to an IOTP
Transaction that is recognised by the Consumer role's system
then there is a Hard Error, otherwise
- if the Payment Response doesn't refer to an IOTOP Transaction
where either a Payment Request or a Payment Exchange block was
most recently sent then there is a Hard Error
- if the Delivery Response Block doesn't refer to an IOTP
Transaction that is recognised by the Consumer role's system
then there is a Hard Error, otherwise
- If the Delivery Response doesn't refer to an IOTP Transaction
where either a Payment Request or a Payment Exchange block was
most recently sent then there is a Hard Error
This process cancels a current transaction on an Consumer role's system as a result of an external request from the user, or another system or server in the Consumer's role. The processing is the same as for an IOTP Server (see section 4.5.3).
The process of retransmitting messages is the same as for an IOTP Server (see section 4.5.4).
This section considers, from an IETF perspective how IOTP addresses security. The next section (see section 6. Digital Signatures and IOTP) describes how IOTP uses Digital Signatures when these are needed.
This section covers:
The use of digital signatures within IOTP are entirely optional. IOTP can work successfully entirely without the use of digital signatures.
Ultimately it is up to the Merchant, or other trading role, to decide whether IOTP Messages will include signatures, and for the Consumer
to decide whether carrying out a transaction without signatures is an acceptable risk. If Merchants discover that transactions without signatures are not being accepted, then they will either:
A non-exhaustive list of the reasons why digital signatures might be used follows:
- if it would be accepted by tax authorities as a valid record of
a transaction, or
- if some warranty, for example from a "Better Business Bureau"
orsimilar was being provided
then the Consumer can later use the record of the Payment or Delivery to prove that it occurred. This could be used, for example, for customer care purposes.
A non-exhaustive list of the reasons why digital signatures might not be used follows:
The advantage of using symmetric keys with IOTP is that no Public Key Infrastructure need be set up and just the Merchant, Payment Handler and Delivery Handler need to agree on the shared secrets to use.
However the disadvantage of symmetric cryptography is that the Consumer cannot easily check the credentials of the Merchant, Payment Handler, etc. that they are dealing with. This is likely to reduce, somewhat, the trust that the Consumer will have carrying out the transaction.
However it should be noted that even if asymmetric cryptography is being used, the Consumer does not NEED to be provided with any digital certificates as the integrity of the transaction is determined by, for example, the Payment Handler checking the Offer Response Signature copied to the Payment Request.
Note that symmetric, asymmetric or both types of cryptography may be used in a single transaction.
Privacy of information is provided by sending IOTP Messages between the various Trading Roles using a secure channel such as [SSL/TLS]. Use of a secure channel within IOTP is optional.
IOTP is designed to be completely blind to the payment protocol being used to effect a payment. From the security perspective, this means that IOTP neither helps, nor hinders, the achievement of payment security.
If it is necessary to consider payment security from an IOTP perspective, then this should be included in the payment protocol supplement which describes how IOTP supports that payment protocol.
However what IOTP is designed to do is to use digital signatures to bind together the record, contained in a "response" message, of each trading exchange in a transaction. For example IOTP can bind together: an Offer, a Payment and a Delivery.
IOTP can work successfully without using any digital signatures although in an open networking environment it will be less secure - see 5. Security Considerations for a description of the factors that need to be considered.
However, this section describes how to use digital signatures in the many situations when they will be needed. Topics covered are:
In general, signatures when used with IOTP:
- which Organisation signed (originated) the signature, and
- which Organisation(s) should process the signature in order to
check that the Action the Organisation should take can occur.
Digital certificates may be associated with digital signatures if asymmetric cryptography is being used. However if symmetric cryptography is being used, then the digital certificate will be replaced by some identifier of the secret key to use.
The way in which Signatures Components digest one or more elements is illustrated in the figure below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
IOTP MESSAGE SIGNATURE COMPONENT
IOTP Message Signature Id = P1.3
|-Trans Ref Block digest TransRefBlk |-Manifest
| | ID=P1.1-----------------------------|->|-Digest of P1.1--
| |-Trans Id Comp digest TransIdComp | | |
| | ID = M1.2----------------------------|->|-Digest of M1.2--|
| |-Msg Id Comp. digest Signature | | |
| | ID = P1 -------------------|->|-Digest of M1.5--|
| | digest element | | |
|-Signatures Block | -----------------|->|-Digest of M1.7--|
| | ID=P1.2 | | digest element | | |
| |-Signature ID=P1.3 | | ---------------|->|-Digest of C1.4--|
| |-Signature ID=M1.5---- | | | | |
| |-Signature ID=P1.4 | | Points to | -RecipientInfo* |
| |-Certificate ID=M1.6<---|-|---------------|------CertRef=M1.6 |
| | | | Certs to use | Sig.ValueRef=P1.4 |
| | | | | | |
| | | | | | |
|-Trading Block. ID=P1.5 | | | v |
| |-Comp. ID=M1.7---------- | -Value* ID=P1.4: |
| | | JtvwpMdmSfMbhK<--
| |-Comp. ID=P1.6 | r1Ln3vovbMQttbBI
| | | J8pxLjoSRfe1o6k
| |-Comp. ID=C1.4------------ OGG7nTFzTi+/0<-
| |-Comp. ID=C1.5
Digital signature of Manifest element
using certificate identified by CertRef
Elements that are digested can be in any IOTP Message
within the same IOTP Transaction
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 10 Signature Digests
Note: The classic example of one signature signing another in IOTP, is when an Offer is first signed by a Merchant creating an "Offer Response" signature, which is then later signed by a Payment Handler together with a record of the payment creating a "Payment Receipt" signature. In this way, the payment in an IOTP Transaction is bound to the Merchant's offer.
Note that one Manifest may be associated with multiple signature "Value" elements where each Value element contains a digital signature over the same Manifest, perhaps using the same (or different) signature algorithm but using a different certificate or shared secret key. Specifically it will allow the Merchant to agree on different shared secrets keys with their Payment Handler and Delivery Handler.
The detailed definitions of a Signature component are contained in section 7.19.
The remainder of this section contains:
An example of how signatures are used is illustrated in the figure below which shows how the various components and elements in a Baseline Purchase relate to one another. Refer to this example in the later description of how signatures are used to check a payment or delivery can occur (see section 6.3).
Note: A Baseline Purchase transaction has been used for illustration purposes. The usage of the elements and attributes is the same for all types of IOTP Transactions.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
| (Offer Response)
Brand Selection Organisation<--- |------Signature
Component Component | | Component
| | | -Manifest
|BrandList -Trading Role | |
| Ref Element | Originator |-Orig.
v (Merchant) ------------|--Info
Brand List Ref |
>Component |
| |-Protocol ------> Organisation Recipient |-Recipient
| | Amount Elem | Component <------------------|--Info
| | | | | Refs |
| |Pay|Protocol |Action -Trading Role |
| | | Ref |OrgRef Element |
| | v | (Payment Handler) |
| -PayProtocol-- |
| Elem ->Organisation Recipient |-Recipient
| | Component <--------------------Info
| | | Refs
| | -Trading Role
| | Element
| | (Delivery Handler
|
| OFFER RESPONSE BLOCK
| |
|BrandListRef |ActionOrgRef
| |
--Payment ---Delivery
Component Component
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 11 Example use of Signatures for Baseline Purchase
The OriginatorRef attribute of the OriginatorInfo element in the Signature Component contains an Element Reference (see section 3.5) that points to the Organisation Component of the Organisation which generated the Signature. In this example its the Merchant.
Note that the value of the content of the Attribute element with a Type attribute set to IOTP Signature Type must match the Trading Role of the Organisation which signed it. If it does not, then it is an error. Valid combinations are given in the table below.
IOTP Signature Type Valid Trading Role
OfferResponse Merchant
PaymentResponse PaymentHandler
DeliveryResponse DeliveryHandler
AuthenticationRequest any role
AuthenticationResponse any role
PingRequest any role
PingResponse any role
The RecipientRefs attribute of the RecipientInfo element in the Signature Component contains Element References to the Organisation Components of the Organisations that should use the signature to verify that:
Note that if symmetric cryptography is being used then a separate RecipientInfo and Value elements for each different set of shared secret keys are likely within the Signature Component.
Alternatively if asymmetric cryptography is being used then the RecpientRefs attribute of one RecipientInfo element may refer to multiple Organisation Components if they are all using the same certificates.
Proving an action completed successfully, is achieved by signing data on Response messages. Specifically:
- a Payment Handler to prove that the Merchant authorises
Payment, or
- a Delivery Handler to prove that Merchant authorises Delivery,
provided other necessary authorisations are complete (see
below)
- a Delivery Handler, in a Delivery Request Block to authorise
Delivery together with the Offer Response signature, or
- another Payment Handler, in a second Payment Request, to
authorise the second payment in a Value Exchange IOTP
Transaction
This proof of an action may, in future versions of IOTP, also be used to prove after the event that the IOTP transaction occurred. For example to a Customer Care Provider.
Checking a signature is correctly calculated is part of checking for Message Level Errors (see section 4.3.2). It is included here so that all signature and security related considerations are kept together.
Before a Trading Role can check a signature it must identify which of the potentially multiple Signature elements should be checked. The steps involved are as follows:
- use the SignatureValueRef and the SignatureAlgorithmRef
attributes to identify, respectively: the Value element that
contains the signature to be checked and the Signature
Algorithm element that describes the signature algorithm to be
used to verify the Signature, then
- if the Signature Algorithm element indicates that asymmetric
cryptography is being used then use the SignatureCertRef to
identify the Certificate to be used by the signature algorithm
- if Signature Algorithm element indicates that symmetric
cryptography is being used then the content of the
RecipientInfo element is used to identify the correct shared
secret key to use
- use the specified signature algorithm to check that the Value
Element correctly signs the Manifest Element
- check that the Digest Elements in the Manifest Element are
correctly calculated where Components or Blocks referenced by
the Digest have been received by the Organisation checking the
signature.
This section describes the processes required for a Payment Handler or Delivery Handler to check that a payment or delivery can occur. This may include checking signatures if this is specified by the Merchant.
In outline the steps are:
For clarity and brevity the following terms or phrases are used in this section:
Checking the Request Block was sent to the correct Organisation varies depending on whether the request refers to a Payment or a Delivery.
In outline a Payment Handler checks if it can accept or make a payment by identifying the Payment Component in the Payment Request Block it has received, then using the ID of the Payment Component to track through the Brand List and Brand Selection Components to identify the Organisation selected by the Consumer and then checking that this Organisation is itself.
The way data is accessed to do this is illustrated in the figure below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Start
|
v
Brand List<--------------------------+-----------Payment
Component BrandListRef | Component
| |
|-Brand<-------------------------- |
| Element BrandRef | |
| | Brand Selection
| |Protocol Component
| | AmountRefs | |
| v Protocol | |
|-Protocol Amount<---------------- |
| Element---------- AmountRef |
| | | |
| |Currency |Pay |
| | AmountRefs |Protocol |
| v |Ref |
|-Currency Amount | |
| Element<---------|----------------
| |
-PayProtocol<-----
Element---------------------->Organisation
Action Component
OrgRef |
-Trading Role
Element
(Payment Handler)
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 12 Checking a Payment Handler can carry out a Payment
The following describes the steps involved and the checks which need to be made:
- identifying the Brand List Component (see section 7.7) where
the value of its ID attribute matches the BrandListRef
attribute of the Payment Component. If no or more than one
Brand List Component is found there is an error.
- identifying the Brand Selection Component (see section 7.8)
where the value of its BrandListRef attribute matches the
BrandListRef of the Payment Component. If no or more than one
matching Brand Selection Component is found there is an error.
- the Brand Element (see section 7.7.1) selected is the element
where the value of its Id attribute matches the value of the
BrandRef attribute in the Brand Selection. If no or more than
one matching Brand Element is found then there is an error.
- the Protocol Amount Element (see section 7.7.3) selected is the
element where the value of its Id attribute matches the value
of the ProtocolAmountRef attribute in the Brand Selection
Component. If no or more than one matching Protocol Amount
Element is found there is an error
- the Pay Protocol Element (see section 7.7.5) selected is the
element where the value of its Id attribute matches the value
of the PayProtocolRef attribute in the identified Protocol
Amount Element. If no or more than one matching Pay Protocol
Element is found there is an error
- the Currency Amount Element (see section 7.7.4) selected is the
element where the value of its Id attribute matches the value
of the CurrencyAmountRef attribute in the Brand Selection
Component. If no or more than one matching Currency Amount
element is found there is an error
- check that an Element Reference exists in the
ProtocolAmountRefs attribute of the identified Brand Element
that matches the Id attribute of the identified Protocol Amount
Element. If no or more than one matching Element Reference can
be found there is an error
- check that the CurrencyAmountRefs attribute of the identified
Protocol Amount element contains an element reference that
matches the Id attribute of the identified Currency Amount
element. If no or more than one matching Element Reference is
found there is an error.
- check the consistency of the elements in the Brand List.
Specifically, the selected Brand, Protocol Amount, Pay Protocol
and Currency Amount Elements are all child elements of the
identified Brand List Component. If they are not there is an
error.
- identifying the Organisation Component for the Payment Handler.
This is the Organisation Component where its ID attribute
matches the ActionOrgRef attribute in the identified Pay
Protocol Element. If no or more than one matching Organisation
Component is found there is an error
- checking the Organisation Component has a Trading Role Element
with a Role attribute of PaymentHandler. If not there is an
error
- finally, if the identified Organisation Component is not the
same as the Organisation that received the Payment Request
Block, then there is an error.
The way data is accessed by a Delivery Handler in order to check that it may carry out a delivery is illustrated in the figure below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Start
|
v
Delivery
Component
|
|ActionOrgRef
|
v
Organisation
Component
|
-Trading Role
Element
(Delivery Handler)
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 13 Checking a Delivery Handler can carry out a Delivery
The steps involved are as follows:
Check that the correct components are present in the Payment Request Block (see section 8.7) or in the Delivery Request Block (see section 8.10).
If components are missing, there is an error.
The previous steps identified the Action Organisation and that all the necessary components are present. This step checks that the Action Organisation is authorised to carry out the Action.
In outline the Action Organisation will identifies the Merchant, checks that it has a pre-existing agreement with the Merchant that allows it carry out the Action and that any constraints implied by that agreement are being followed, then, if signatures are required, it checks that they sign the correct data.
The steps involved are as follows:
- the Merchant is known and a pre-existing agreement exists for
the Action Organisation to be their agent for the payment or
delivery
- they are allowed to take part in the type of IOTP transaction
that is occurring. For example a Payment Handler may have
agreed to accept payments as part of a Baseline Purchase, but
not make payments as part of a Baseline Refund
- any constraints in their agreement with the Merchant are being
followed, for example, whether or not an Offer Response
signature is required
- Identifying the correct signatures to check. This involves the
Action Organisation identifying the Signature Components that
contain references to the Action Organisation (see 6.3.1).
Depending on the IOTP Transaction being carried out (see
section 9) either one or two signatures may be identified
- checking that the Signature Components are correct. This
involves checking that Digest elements exist within the
Manifest Element that refer to the necessary Trading Components
(see section 6.3.3.1).
All Signature Components contained within IOTP Messages must include Digest elements that refer to:
Check that each Signature Component contains Digest elements that refer to the correct data required.
The Digest elements that need to be present depend on the Trading Role of the Organisation which generated (signed) the signature:
- Digest elements must be present for all the components in the
Request Block apart from the Brand Selection Component which is
optional
- the Signature Component signed by the Merchant, and optionally
- one or more Signature Components signed by the previous Payment
Handler(s) in the Transaction.
This section describes the Trading Components used within IOTP. Trading Components are the child XML elements which occur immediately below a Trading Block as illustrated in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
IOTP MESSAGE <----------- IOTP Message - an XML Document
| which is transported between the
| Trading Roles
|-Trans Ref Block <----- Trans Ref Block - contains
| | information which describes the
| | IOTP Transaction and the IOTP
Message.
--------> | |-Trans Id Comp. <--- Transaction Id Component -
| | | uniquely identifies the IOTP
| | | Transaction. The Trans Id
| | | Components are the same across
| | | all IOTP messages that comprise
| | | a single IOTP transaction.
| | |-Msg Id Comp. <----- Message Id Component -
| | identifies and describes an IOTP
| | Message within an IOTP
| | Transaction
| |-Signature Block <----- Signature Block (optional) -
| | | contains one or more Signature
| | | Components and their associated
| | | Certificates
| ---> | |-Signature Comp. <-- Signature Component - contains
| | | | digital signatures. Signatures
| | | | may sign digests of the Trans Ref
| | | | Block and any Trading Component
| | | | in any IOTP Message in the same
| | | | IOTP Transaction.
| | | |-Certificate Comp. <- Certificate Component. Used to
| | | check the signature.
Trading |-Trading Block <-------- Trading Block - an XML Element
Components | |-Trading Comp. within an IOTP Message that
| | | |-Trading Comp. contains a predefined set of
| ---> | |-Trading Comp. Trading Components
| | |-Trading Comp.
| | |-Trading Comp. <----- Trading Components - XML
| | Elements within a Trading Block
| |-Trading Block that contain a predefined set of
--------> | |-Trading Comp. XML elements and attributes
| |-Trading Comp. containing information required
| |-Trading Comp. to support a Trading Exchange
| |-Trading Comp.
| |-Trading Comp.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 14 Trading Components
The Trading Components described in this section are listed below in approximately the sequence they are likely to be used:
Note that the following components are listed in other sections of this specification:
Protocol options are options which apply to the IOTP Transaction as a whole. Essentially it provides a short description of the entire transaction and the net location which the Consumer role should branch to if the IOTP Transaction is successful.
The definition of a Protocol Options Component is as follows.
<!ELEMENT ProtocolOptions EMPTY >
<!ATTLIST ProtocolOptions
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
ShortDesc CDATA #REQUIRED
SenderNetLocn CDATA #IMPLIED
SecureSenderNetLocn CDATA #IMPLIED
SuccessNetLocn CDATA #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Protocol Options Component within the IOTP
Transaction.
Xml:lang Defines the language used by attributes or child
elements within this component, unless
overridden by an xml:lang attribute on a child
element. See section 3.8 Identifying Languages.
ShortDesc This contains a short description of the IOTP
Transaction in the language defined by xml:lang.
Its purpose is to provide an explanation of what
type of IOTP Transaction is being conducted by
the parties involved.
It is used to facilitate selecting an individual transaction from a list of similar transactions, for example from a database of IOTP transactions which has been stored by a Consumer, Merchant, etc.
SenderNetLocn This contains the non secured net location of
the sender of the TPO Block in which the
Protocol Options Component is contained.
It is the net location to which the recipient of the TPO block should send a TPO Selection Block if required.
The content of this attribute is dependent on the Transport Mechanism see the Transport Mechanism Supplement.
SecureSenderNetLocn This contains the secured net location of the sender of the TPO Block in which the Protocol Options Component is contained.
The content of this attribute is dependent on the Transport Mechanism see the Transport Mechanism Supplement.
SuccessNetLocn This contains the net location that should be
displayed after the IOTP Transaction has
successfully completed.
The content of this attribute is dependent on the Transport Mechanism see the Transport Mechanism Supplement.
Either SenderNetLocn, SecureSenderNetLocn or both must be present.
This Trading Component contains parameter data that is used in an Authentication of one Trading Role by another. Its definition is as follows.
<!ELEMENT AuthReq (Algorithm, PackagedContent*)>
<!ATTLIST AuthReq
ID ID #REQUIRED
AuthenticationId CDATA #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
If required the Algorithm may use the challenge data, contained in the Packaged Content elements within the Authentication Request Component in its calculation. The format of the Packaged Contents are Algorithm dependent.
Attributes:
ID An identifier which uniquely identifies the
Authentication Request Component within the IOTP
Transaction.
AuthenticationId An identifier specified by the Authenticator
which, if returned by the Organisation that
receives the Authentication Request, will enable
the Authenticator to identify which Authentication is being referred to.
ContentSoftwareId See section 14.Glossary
Content:
PackagedContent This contains the challenge data as one or more
Packaged Content (see section 3.7) that is to be
responded to using the Algorithm defined by the
Algorithm element.
Algorithm This contains information which describes the
Algorithm (see 7.19 Signature Components) that
must be used to generate the Authentication
Response.
The Algorithms that may be used are identified by the Name attribute of the Algorithm element. For valid values see section 12. IANA Considerations.
The Authentication Response Component contains the results of an authentication request. It uses the Algorithm contained in the Authentication Request Component (see section 7.2) selected from the Authentication Request Block (see section 8.4).
Depending on the Algorithm selected, the results of applying the algorithm will either be contained in a Signature Component that signs both the Authentication Response and potentially other data, or in the Packaged Content elements within the Authentication Response Component. Its definition is as follows.
<!ELEMENT AuthResp (PackagedContent*) >
<!ATTLIST AuthResp
ID ID #REQUIRED
AuthenticationId CDATA #REQUIRED
SelectedAlgorithmRef NMTOKEN #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Authentication Response Component within the
IOTP Transaction.
AuthenticationId The Authentication identifier specified by the
Authenticator that was included in the
Authentication Request Component(see section
7.2). This will enable the Authenticator to
identify the Authentication that is being
referred to.
SelectedAlgorithmRef An Element Reference that identifies the
Algorithm element used to generate the
Authentication Response.
ContentSoftwareId See section 14.Glossary.
Content:
PackagedContent This may contain the response generated as a
result of applying the Algorithm selected from the
Authentication Request Component see section 7.2.
For example, for a payment specific scheme, it may contain scheme-specific data. Refer to the scheme- specific supplemental documentation for definitions of its content.
This Trading Component contains a list of Trading Roles (see section 2.1) about which information is being requested. The result of a Trading Role Request is a set of Organisation Components (see section 7.6) that describe each of the Trading Roles requested.
Example usage includes:
Its definition is as follows.
<!ELEMENT TradingRoleInfoReq EMPTY>
<!ATTLIST TradingRoleInfoReq
ID ID #REQUIRED
TradingRoleList NMTOKENS #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Trading Role Information Request Component within
the IOTP Transaction.
TradingRoleList Contains a list of one or more Trading Roles (see
the TradingRole attribute of the Trading Role
Element - section 7.6.2) for which information is
being requested.
An Order Component contains information about an order. Its definition is as follows.
<!ELEMENT Order (PackagedContent*) >
<!ATTLIST Order
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
OrderIdentifier CDATA #REQUIRED
ShortDesc CDATA #REQUIRED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
ApplicableLaw CDATA #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the Order
Component within the IOTP Transaction.
xml:lang Defines the language used by attributes or child
elements within this component, unless overridden
by an xml:lang attribute on a child element. See
section 3.8 Identifying Languages.
OrderIdentifier This is a code, reference number or other
identifier which the creator of the Order may use
to identify the order. It must be unique within an
IOTP Transaction. If it is used in this way, then
it may remove the need to specify any content for
the Order element as the reference can be used to
look up the necessary information in a database.
ShortDesc A short description of the order in the language
defined by xml:lang. It is used to facilitate
selecting an individual order from a list of
orders, for example from a database of orders which has been stored by a Consumer, Merchant, etc.
OkFrom The date and time in [UTC] format after which the
offer made by the Merchant lapses.
OkTo The date and time in [UTC] format before which a
Value Acquirer may accept the offer made by the
Merchant is not valid.
ApplicableLaw A phrase in the language defined by xml:lang which
describes the state or country of jurisdiction
which will apply in resolving problems or
disputes.
ContentSoftwareId See section 14.Glossary.
Content:
PackagedContent An optional description of the order information
as one or more Packaged Contents (see section
3.7).
The Packaged Content element will normally be required, however it may be omitted where sufficient information about the purchase can be provided in the ShortDesc attribute. If the full Order Description requires it several Packaged Content elements may be used.
Although the amount and currency are likely to appear in the Packaged Content of the Order Description it is the amount and currency contained in the payment related trading components (Brand List, Brand Selection and Payment) that is authoritative. This means it is important that the amount actually being paid (as contained in the payment related trading components) is prominently displayed to the Consumer.
For interoperability, implementations must support Plain Text, HTML and XML as a minimum so that it can be easily displayed.
Note that:
Note: Disclaimer. The following information provided in this note does not represent formal advice of any of the authors of this specification. Readers of this specification must form their own views and seek their own legal counsel on the usefulness and applicability of this information.
The merchant in the context of Internet commerce with anonymous consumers initially frames the terms of the offer on the web page, and in order to obtain the goods or services, the consumer must accept them.
If there is to be a time-limited offer, it is recommended that merchants communicate this to the consumer and state in the order description in a manner which is clear to the consumer that:
Also note that although the OkFrom and OkTo dates are likely to appear in the Packaged Content of the Order Description it is the dates contained in the Order Component that is authoritative. This means it is important that the OkFrom and OkTo dates actually being used is prominently displayed to the Consumer.
The Organisation Component provides information about an individual or an Organisation. This can be used for a variety of purposes. For example:
Note that the Organisation Components which must be present in an IOTP Message are dependent on the particular transaction being carried out. Refer to section 9. Internet Open Trading Protocol Transactions, for more details.
Its definition is as follows.
<!ELEMENT Org (TradingRole+, ContactInfo?,
PersonName?, PostalAddress?)>
<!ATTLIST Org
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
OrgId CDATA #REQUIRED
LegalName CDATA #IMPLIED
ShortDesc CDATA #IMPLIED
LogoNetLocn CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Organisation Component within the IOTP
Transaction.
xml:lang Defines the language used by attributes or child
elements within this component, unless overridden
by an xml:lang attribute on a child element. See
section 3.8 Identifying Languages.
OrgId A code which identifies the Organisation described
by the Organisation Component. See 7.6.1
Organisation IDs, below.
LegalName For Organisations which are companies this is
their legal name in the language defined by
xml:lang. It is required for Organisations who
have a Trading Role other than Consumer or
DelivTo.
ShortDesc A short description of the Organisation in the
language defined by xml:lang. It is typically the
name by which the Organisation is commonly known.
For example, if the legal name was "Blue Meadows
Financial Services Inc.". Then its short name
would likely be "Blue Meadows".
It is used to facilitate selecting an individual Organisation from a list of Organisations, for example from a database of Organisations involved
in IOTP Transactions which has been stored by a consumer.
LogoNetLocn The net location which can be used to download the
logo for the Organisation.
See section 10 Retrieving Logos.
The content of this attribute must conform to [RFC1738].
Content:
TradingRole See 7.6.2 Trading Role Element below. ContactInfo See 7.6.3 Contact Information Element below. PersonName See 7.6.4 Person Name below. PostalAddress See 7.6.5 Postal Address below.
Organisation IDs are used by one IOTP Trading Role to identify another. In order to avoid confusion, this means that these IDs must be globally unique.
In principle this is achieved in the following way:
Specifically, the content of the Organisation ID is defined as follows:
OrgId ::= NonConsumerOrgId | ConsumerOrgId NonConsumerOrgId ::= DomainName ConsumerOrgId ::= ConsumerOrgIdPrefix (namechar)+ "/" NonConsumerOrgId ConsumerOrgIdPrefix ::= "Consumer:"
ConsumerOrgId The Organisation ID for a Consumer consists of:
Use of upper and lower case is not significant.
NonConsumerOrgId If the Role is not Consumer then this contains the
Canonical Name for the non-consumer Organisation
being described by the Organisation Component. See
[DNS] optionally followed by additional
characters, if required, to make the
NonConsumerOrgId unique.
Note that a NonConsumerOrgId may not start with the ConsumerOrgIdPrefix.
Use of upper and lower case is not significant.
Examples of Organisation Ids follow:
This identifies the Trading Role of an individual or Organisation in the IOTP Transaction. Note, an Organisation may have more than one Trading Role and several roles may be present in one Organisation element. Its definition is as follows:
<!ELEMENT TradingRole EMPTY >
<!ATTLIST TradingRole
ID ID #REQUIRED
TradingRole NMTOKEN #REQUIRED
IotpMsgIdPrefix NMTOKEN #REQUIRED
CancelNetLocn CDATA #IMPLIED
ErrorNetLocn CDATA #IMPLIED
ErrorLogNetLocn CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Trading Role Element within the IOTP Transaction.
TradingRole The trading role of the Organisation. Valid values
are:
Values of TradingRole are controlled under the
procedures defined in section 12 IANA
Considerations which also allows user defined
values to be defined.
IotpMsgIdPrefix Contains the prefix which must be used for all
IOTP Messages sent by the Trading Role in this
IOTP Transaction. The values to be used are
defined in 3.4.1 IOTP Message ID Attribute
Definition.
CancelNetLocn This contains the net location of where the
Consumer should go to if the Consumer cancels the
transaction for some reason. It can be used by the
Trading Role to provide a response which is more
tailored to the circumstances of a particular
transaction.
This attribute:
The content of this attribute is dependent on the Transport Mechanism see the Transport Mechanism Supplement.
ErrorNetLocn This contains the net location that should be
displayed by the Consumer after the Consumer has
either received or generated an Error Block
containing an Error Component with the Severity
attribute set to either:
See section 7.21.1 Error Processing Guidelines for more details.
This attribute:
The content of this attribute is dependent on the Transport Mechanism see the Transport Mechanism Supplement.
ErrorLogNetLocn Optional. This contains the net location that
Consumers should send IOTP Messages that contain
Error Blocks with an Error Component with the
Severity attribute set to either:
This attribute:
The content of this attribute is dependent on the Transport Mechanism see the Transport Mechanism Supplement.
The ErrorLogNetLocn can be used to send error messages to the software company or some other Organisation responsible for fixing problems in the software which sent the incoming message. See section 7.21.1 Error Processing Guidelines for more details.
This contains information which can be used to contact an Organisation or an individual. All attributes are optional however at least one item of contact information should be present. Its definition is as follows.
<!ELEMENT ContactInfo EMPTY >
<!ATTLIST ContactInfo
xml:lang NMTOKEN #IMPLIED
Tel CDATA #IMPLIED
Fax CDATA #IMPLIED
Email CDATA #IMPLIED
NetLocn CDATA #IMPLIED >
Attributes:
xml:lang Defines the language used by attributes within
this element. See section 3.8 Identifying
Languages.
Tel A telephone number by which the Organisation may
be contacted. Note that this is a text field and
no validation is carried out on it.
Fax A fax number by which the Organisation may be
contacted. Note that this is a text field and no
validation is carried out on it.
Email An email address by which the Organisation may be
contacted. Note that this field should conform to
the conventions for address specifications
contained in [RFC822].
NetLocn A location on the Internet by which information
about the Organisation may be obtained that can be
displayed using a web browser.
The content of this attribute must conform to [RFC1738].
This contains the name of an individual person. All fields are optional however as a minimum either the GivenName or the FamilyName should be present. Its definition is as follows.
<!ELEMENT PersonName EMPTY >
<!ATTLIST PersonName
xml:lang NMTOKEN #IMPLIED
Title CDATA #IMPLIED
GivenName CDATA #IMPLIED
Initials CDATA #IMPLIED
FamilyName CDATA #IMPLIED >
Attributes:
xml:lang Defines the language used by attributes within
this element. See section 3.8 Identifying
Languages.
Title A distinctive name; personal appellation,
hereditary or not, denoting or implying office
(e.g., judge, mayor) or nobility (e.g., duke,
duchess, earl), or used in addressing or referring
to a person (e.g., Mr, Mrs, Miss)
GivenName The primary or main name by which a person is
known amongst and identified by their family,
friends and acquaintances. Otherwise known as
first name or Christian Name.
Initials The first letter of the secondary names (other
than the Given Name) by which a person is known
amongst or identified by their family, friends and
acquaintances.
FamilyName The name by which family of related individuals
are known. It is typically the part of an
individual's name which is passed on by parents to
their children.
This contains an address which can be used, for example, for the physical delivery of goods, services or letters. Its definition is as follows.
<!ELEMENT PostalAddress EMPTY >
<!ATTLIST PostalAddress
xml:lang NMTOKEN #IMPLIED
AddressLine1 CDATA #IMPLIED
AddressLine2 CDATA #IMPLIED
CityOrTown CDATA #IMPLIED
StateOrRegion CDATA #IMPLIED
PostalCode CDATA #IMPLIED
Country CDATA #IMPLIED
LegalLocation (True | False) 'False' >
Attributes:
xml:lang Defines the language used by attributes within
this element. See section 3.8 Identifying
Languages.
AddressLine1 The first line of a postal address. e.g., "The
Meadows"
AddressLine2 The second line of a postal address. e.g., "Sandy
Lane"
CityOrTown The city of town of the address. e.g., "Carpham"
StateOrRegion The state or region within a country where the
city or town is placed. e.g., "Surrey"
PostalCode The code known as, for example a post code or zip
code, that is typically used by Postal
Organisations to organise postal deliveries into
efficient sequences. e.g., "KT22 1AA"
Country The country for the address. e.g., "UK"
LegalLocation This identifies whether the address is the
Registered Address for the Organisation. At least
one address for the Organisation must have a value
set to True unless the Trading Role is either
Consumer or DeliverTo.
Brand List Components are contained within the Trading Protocol Options Block (see section 8.1) of the IOTP Transaction. They contains lists of:
The definition of a Brand List Component is as follows.
<!ELEMENT BrandList (Brand+, ProtocolAmount+,
CurrencyAmount+, PayProtocol+) >
<!ATTLIST BrandList
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
ShortDesc CDATA #REQUIRED
PayDirection (Debit | Credit) #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the Brand
List Component within the IOTP Transaction.
xml:lang Defines the language used by attributes or child
elements within this component, unless overridden
by an xml:lang attribute on a child element. See
section 3.8 Identifying Languages.
ShortDesc A text description in the language defined by
xml:Lang giving details of the purpose of the
Brand List. This information must be displayed to
the receiver of the Brand List in order to assist
with making the selection. It is of particular
benefit in allowing a Consumer to distinguish the
purpose of a Brand List when an IOTP Transaction
involves more than one payment.
PayDirection Indicates the direction in which the payment for
which a Brand is being selected is to be made. Its
values may be:
Content:
Brand This describes a Brand. The sequence of the Brand
elements (see section 7.7.1) within the Brand List
does not indicate any preference. It is
recommended that software which processes this
Brand List presents Brands in a sequence which the
receiver of the Brand List prefers.
ProtocolAmount This links a particular Brand to:
CurrencyAmount This contains a currency code and an amount.
PayProtocol This contains information about a Payment Protocol
and the Payment Handler which may be used with a
particular Brand.
The relationships between the elements which make up the content of the Brand List is illustrated in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Brand List Component
| ProtocolAmountRefs
|-Brand Element-----------------------------
| | |
| - Protocol Brand Element-------- |
| | |
| ProtocolId| |
| | |
|-Protocol Amount Element<----------+-------
| | | |
| | | |
| |CurrencyAmountRefs |Pay |
| | |Protocol |
| v |Ref |
|-Currency Amount Element | |
| Element | |
| | |
-PayProtocolElement<------<--------
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 15 Brand List Element Relationships
Examples of complete Brand Lists are contained in section 11.2 Brand List Examples.
A Brand Element describes a brand that can be used for making a payment. One or more of these elements is carried in each Brand List Component that has the PayDirection attribute set to Debit. Exactly one Brand Element may be carried in a Brand List Component that has the PayDirection attribute set to Credit.
<!ELEMENT Brand (ProtocolBrand*, PackagedContent*) >
<!ATTLIST Brand
ID ID #REQUIRED
xml:lang NMTOKEN #IMPLIED
BrandId CDATA #REQUIRED
BrandName CDATA #REQUIRED
BrandLogoNetLocn CDATA #REQUIRED
BrandNarrative CDATA #IMPLIED
ProtocolAmountRefs IDREFS #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID Element identifier, potentially referenced in a
Brand Selection Component contained in a later
Payment Request message and uniquely identifies
the Brand element within the IOTP Transaction.
xml:lang Defines the language used by attributes and
content of this element. See section 3.8
Identifying Languages.
BrandId This contains a unique identifier for the brand
(or promotional brand). It is used to match
against a list of Payment Instruments which the
Consumer holds to determine whether or not the
Consumer can pay using the Brand.
Values of BrandId are managed under the procedure described in section 12 IANA Considerations.
As values of BrandId are controlled under the procedures defined in section 12 IANA Considerations user defined values may be defined.
BrandName This contains the name of the brand, for example
MasterCard Credit. This is the description of the
Brand which is displayed to the consumer in the
Consumers language defined by xml:lang. For
example it might be "American Airlines Advantage
Visa". Note that this attribute is not used for
matching against the payment instruments held by
the Consumer.
BrandLogoNetLocn The net location which can be used to download
the logo for the Organisation. See section
Retrieving Logos (see section 10).
The content of this attribute must conform to [RFC1738].
BrandNarrative This optional attribute is designed to be used by
the Merchant to indicate some special conditions
or benefit which would apply if the Consumer
selected that brand. For example "5% discount",
"free shipping and handling", "free breakage
insurance for 1 year", "double air miles apply",
etc.
ProtocolAmountRefs Identifies the protocols and related currencies and amounts which can be used with this Brand. Specified as a list of ID's of Protocol Amount Elements (see section 7.7.3) contained within the Brand List.
ContentSoftwareId See section 14.Glossary.
Content:
ProtocolBrand Protocol Brand elements contain brand information
to be used with a specific payment protocol (see
section 7.7.2)
PackagedContent Optional Packaged Content (see section 3.7)
elements containing information about the brand
which may be used by the payment protocol. The
content of this information is defined in the
supplement for a payment protocol which describes
how the payment protocol works with IOTP.
Example Brand Elements are contained in section 11.2 Brand List Examples.
The Protocol Brand Element contains information that is specific to the use of a particular Protocol with a Brand. Its definition is as follows.
<!ELEMENT ProtocolBrand (PackagedContent*) >
<!ATTLIST ProtocolBrand
ProtocolId CDATA #REQUIRED
ProtocolBrandId CDATA #REQUIRED >
Attributes:
ProtocolId This must match the value of a ProtocolId
attribute in a Pay Protocol Element (see section
7.7.5).
The values of ProtocolId should be unique within a Brand Element otherwise there is an error.
ProtocolBrandId This is the Payment Brand Id to be used with a
particular payment protocol. For example, SET and
EMV have their own well defined, yet different,
values for the Brand Id to be used with each
protocol.
The valid values of this attribute are defined in the supplement for the payment protocol identified by ProtocolId that describes how the payment protocol works with IOTP.
Content:
PackagedContent Optional Packaged Content (see section 3.7)
elements containing information about the
protocol/brand which may be used by the payment
protocol. The content of this information is
defined in the supplement for a payment protocol
which describes how the payment protocol works
with IOTP.
The Protocol Amount element links a Brand to:
Its definition is as follows:
<!ELEMENT ProtocolAmount (PackagedContent*) >
<!ATTLIST ProtocolAmount
ID ID #REQUIRED
PayProtocolRef IDREF #REQUIRED
CurrencyAmountRefs IDREFS #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID Element identifier, potentially referenced in a
Brand element; or in a Brand Selection Component
contained in a later Payment Request message
which uniquely identifies the Protocol Amount
element within the IOTP Transaction.
PayProtocolRef Contains an Element Reference (see section 3.5)
that refers to the Pay Protocol Element (see
section 7.7.5) that contains the Payment Protocol
and Payment Handlers that can be used with the
Brand.
CurrencyAmountRefs Contains a list of Element References (see section 3.5) that refer to the Currency Amount Element (see section 7.7.4) that describes the currencies and amounts that can be used with the Brand.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Optional Packaged Content (see section 3.7)
elements containing information about the protocol
amount which may be used by the payment protocol.
The content of this information is defined in the
supplement for a payment protocol which describes
how the payment protocol works with IOTP.
Examples of Protocol Amount Elements are contained in section 11.2 Brand List Examples.
A Currency Amount element contains:
One or more of these elements is carried in each Brand List Component. Its definition is as follows:
<!ELEMENT CurrencyAmount EMPTY >
<!ATTLIST CurrencyAmount
ID ID #REQUIRED
Amount CDATA #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED >
Attributes:
ID Element identifier, potentially referenced in a
Brand element; or in a Brand Selection Component
contained in a later Payment Request message which uniquely identifies the Currency Amount Element within the IOTP Transaction.
Amount Indicates the amount to be paid in whole and
fractional units of the currency. For example
$245.35 would be expressed "245.35". Note that
values smaller than the smallest denomination are
allowed. For example one tenth of a cent would be
"0.001".
CurrCodeType Indicates the domain of the CurrCode. This
attribute is included so that the currency code
may support non-standard "currencies" such as
frequent flyer points, trading stamps, etc. Its
values may be:
CurrCode A code which identifies the currency to be used in
the payment. The domain of valid currency codes is
defined by CurrCodeType
As values of CurrCodeType are managed under the procedure described in section 12 IANA Considerations user defined values of CurrCodeType may be defined.
Examples of Currency Amount Elements are contained in section 11.2 Brand List Examples.
A Pay Protocol element specifies details of a Payment Protocol and the Payment Handler that can be used with a Brand. One or more of these elements is carried in each Brand List.
<!ELEMENT PayProtocol (PackagedContent*) >
<!ATTLIST PayProtocol
ID ID #REQUIRED
xml:lang NMTOKEN #IMPLIED
ProtocolId NMTOKEN #REQUIRED
ProtocolName CDATA #REQUIRED
ActionOrgRef NMTOKEN #REQUIRED
PayReqNetLocn CDATA #IMPLIED
SecPayReqNetLocn CDATA #IMPLIED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID Element identifier, potentially referenced in a
Brand element; or in a Brand Selection Component
contained in a later Payment Request message which
uniquely identifies the Pay Protocol element
within the IOTP Transaction.
xml:lang Defines the language used by attributes and
content of this element. See section 3.8
Identifying Languages.
ProtocolId Consists of a protocol name and version. For
example "SETv1.0".
The values of ProtocolId are defined by the payment scheme/method owners in the document that describes how to encapsulate a payment protocol within IOTP.
ProtocolName A narrative description of the payment protocol
and its version in the language identified by
xml:lang. For example "Secure Electronic
Transaction Version 1.0". Its purpose is to help
provide information on the payment protocol being
used if problems arise.
ActionOrgRef An Element Reference (see section 3.5) to the
Organisation Component for the Payment Handler for
the Payment Protocol.
PayReqNetLocn The Net Location indicating where an unsecured
Payment Request message should be sent if this
protocol choice is used.
The content of this attribute is dependent on the Transport Mechanism (such must conform to [RFC1738].
SecPayReqNetLocn The Net Location indicating where a secured
Payment Request message should be sent if this
protocol choice is used.
A secured payment involves the use of a secure channel such as [SSL/TLS] in order to communicate with the Payment Handler.
The content of this attribute must conform to [RFC1738]. See also See section 3.9 Secure and Insecure Net Locations.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Optional Packaged Content elements (see section
3.7) containing information about the protocol
which is used by the payment protocol. The content
of this information is defined in the supplement
for a payment protocol which describes how the
payment protocol works with IOTP. An example of
its use could be to include a payment protocol
message.
Examples of Pay Protocol Elements are contained in section 11.2 Brand List Examples.
A Brand Selection Component identifies the choice of payment brand, payment protocol and the Payment Handler. This element is used:
In Baseline IOTP, the integrity of Brand Selection Components is not guaranteed. However, modification of Brand Selection Components can only cause denial of service if the payment protocol itself is secure against message modification, duplication, and swapping attacks.
The definition of a Brand Selection Component is as follows.
<!ELEMENT BrandSelection (BrandSelBrandInfo?,
BrandSelProtocolAmountInfo?,
BrandSelCurrencyAmountInfo?) >
<!ATTLIST BrandSelection
ID ID #REQUIRED
BrandListRef NMTOKEN #REQUIRED
BrandRef NMTOKEN #REQUIRED
ProtocolAmountRef NMTOKEN #REQUIRED
CurrencyAmountRef NMTOKEN #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the Brand
Selection Component within the IOTP Transaction.
BrandListRef The Element Reference (see section 3.5) of the
Brand List Component from which a Brand is being
selected
BrandRef The Element Reference of a Brand element within
the Brand List Component that is being selected
that is to be used in the payment.
ProtocolAmountRef The Element Reference of a Protocol Amount element within the Brand List Component which is to be used when making the payment.
CurrencyAmountRef The Element Reference of a Currency Amount element within the Brand List Component which is to be used when making the payment.
Content:
BrandSelBrandInfo, This contains any additional data that
BrandSelProtocolAmountInfo, may be required by a particular payment
BrandSelCurrencyAmountInfo brand or protocol. See sections 7.8.1,
7.8.2, and 7.8.3.
The following rules apply:
An example of a Brand Selection Component is included in 11.2 Brand List Examples.
The Brand Selection Brand Info Element contains any additional data that may be required by a particular payment brand. See the IOTP payment method supplement for a description of how and when it used.
<!ELEMENT BrandSelBrandInfo (PackagedContent+) >
<!ATTLIST BrandSelBrandInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Packaged Content elements (see section 3.7) that
contain additional data that may be required by a
particular payment brand. See the payment method
supplement for IOTP for rules on how this is used.
The Brand Selection Protocol Amount Info Element contains any additional data that is payment protocol specific that may be required by a particular payment brand or payment protocol. See the IOTP payment method supplement for a description of how and when it used.
<!ELEMENT BrandSelProtocolAmountInfo (PackagedContent+) >
<!ATTLIST BrandSelProtocolAmountInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Packaged Content elements (see section 3.7) that
may contain additional data that may be required
by a particular payment brand. See the payment
method supplement for IOTP for rules on how this
is used.
The Brand Selection Currency Amount Info Element contains any additional data that is payment brand and currency specific that may be required by a particular payment brand. See the IOTP payment method supplement for a description of how and when it used.
<!ELEMENT BrandSelCurrencyAmountInfo (PackagedContent+) >
<!ATTLIST BrandSelCurrencyAmountInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Packaged Content elements (see section 3.7) that
contain additional data relating to the payment
brand and currency. See the payment method
supplement for IOTP for rules on how this is used.
A Payment Component contains information used to control how a payment is carried out. Its provides information on:
Its definition is as follows.
<!ELEMENT Payment EMPTY >
<!ATTLIST Payment
ID ID #REQUIRED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
BrandListRef NMTOKEN #REQUIRED
SignedPayReceipt (True | False) #REQUIRED
StartAfterRefs NMTOKENS #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Payment Component within the IOTP Transaction.
OkFrom The date and time in [UTC] format after which a
Payment Handler may accept for processing a
Payment Request Block (see section 8.7) containing
the Payment Component.
OkTo The date and time in [UTC] format before which a
Payment Handler may accept for processing a
Payment Request Block containing the Payment
Component.
BrandListRef An Element Reference (see section 3.5) of a Brand
List Component (see section 7.7) within the TPO
Trading Block for the IOTP Transaction. The Brand
List identifies the alternative ways in which the
payment can be made.
SignedPayReceipt Indicates whether or not the Payment Response
Block (see section 8.9) generated by the Payment
Handler for the payment must be digitally signed.
StartAfter Contains Element References (see section 3.5) of
other Payment Components which describe payments
which must be complete before this payment can
start. If no StartAfter attribute is present then
there are no dependencies and the payment can
start immediately
A Payment Scheme Component contains payment protocol information for a specific payment scheme which is transferred between the parties involved in a payment for example a [SET] message. Its definition is as follows.
<!ELEMENT PaySchemeData (PackagedContent+) >
<!ATTLIST PaySchemeData
ID ID #REQUIRED
PaymentRef NMTOKEN #IMPLIED
ConsumerPaymentId CDATA #IMPLIED
PaymentHandlerPayId CDATA #IMPLIED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Payment Scheme Component within the IOTP
Transaction.
PaymentRef An Element Reference (see section 3.5) to the
Payment Component (see section 7.9) to which
this Payment Scheme Component relates. It is
required unless the Payment Scheme Component is
part of an Transaction Inquiry Status
Transaction (see section 9.2.1).
ConsumerPaymentId An identifier specified by the Consumer which,
if returned by the Payment Handler in another
Payment Scheme Component or by other means, will
enable the Consumer to identify which payment is
being referred to.
PaymentHandlerPayId An identifier specified by the Payment Handler which, if returned by the Consumer in another Payment Scheme Component, or by other means, will enable the Payment Handler to identify which payment is being referred to. It is required on every Payment Scheme Component apart from the one contained in a Payment Request Block.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Contains payment scheme protocol information as
Packaged Content elements (see section 3.7). See
the payment scheme supplement for the definition
of its content.
Note that:
A Payment Receipt is a record of a payment which demonstrates how much money has been paid or received. It is distinct from a purchase receipt in that it contains no record of what was being purchased.
Typically the content of a Payment Receipt Component will contain data which describes:
If the Payment Method being used provides the facility then the Payment Receipt Component should contain payment protocol messages, or references to messages, which prove the payment occurred.
The precise definition of the content is Payment Method dependent. Refer to the supplement for the payment method being used to determine the rules that apply.
Information contained in the Payment Receipt Component should be displayed or otherwise made available to the Consumer.
Note: If the Payment Receipt Component contains Payment Protocol Messages, then the Messages will need to be processed by Payment Method software to convert it into a format which can be understood by the Consumer
The definition of a Payment Receipt Component is as follows.
<!ELEMENT PayReceipt (PackagedContent*) >
<!ATTLIST PayReceipt
ID ID #REQUIRED
PaymentRef NMTOKEN #REQUIRED
PayReceiptNameRefs NMTOKENS #IMPLIED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Payment Receipt Component within the IOTP
Transaction.
PaymentRef Contains an Element Reference (see section 3.5)
to the Payment Component (see section 7.9) to
which this payment receipt applies
PayReceiptNameRefs Optionally contains a list of the values of the Name attributes of Packaged Content elements that together make up the receipt. The Packaged Content elements are contained either within:
The client software should save all the components referenced so that the payment receipt can be reconstructed when required.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Optionally contains payment scheme payment receipt
information as Packaged Content elements (see
section 3.7). See the payment scheme supplement
for the definition of its content.
Note that:
Note that either the PayReceiptNameRefs attribute, the
PackagedContent element, or both must be present.
The Payment Note Component 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. The information should duplicate information contained within the Payment Receipt Component.
Information contained in the Payment Note Component should be displayed or otherwise made available to the Consumer. For interoperability, the Payment Note Component should support, as a minimum, the content types of "Plain Text", HTML and XML. Its definition is as follows.
<!ELEMENT PaymentNote (PackagedContent+) >
<!ATTLIST PaymentNote
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Payment Receipt Component within the IOTP
Transaction.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Contains additional, non payment related,
information which the Payment Handler wants to
provide to the Consumer as one or more Packaged
Content elements (see section 3.7).
The Delivery Element contains information required to deliver goods or services. Its definition is as follows.
<!ELEMENT Delivery (DeliveryData?, PackagedContent*) >
<!ATTLIST Delivery
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
DelivExch (True | False) #REQUIRED
DelivAndPayResp (True | False) #REQUIRED
ActionOrgRef NMTOKEN #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Delivery 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.
DelivExch Indicates if this IOTP Transaction includes the
messages associated with a Delivery Exchange.
Valid values are:
If set to true then a DeliveryData element must be present. If set to false it may be absent.
DelivAndPayResp Indicates if the Delivery Response Block (see
section 8.11) and the Payment Response Block (see
section 8.9 ) are combined into one IOTP Message.
Valid values are:
DelivAndPayResp should not be true if DelivExch is False.
In practice combining the Delivery Response Block
and Payment Response Block is only likely to be
practical if the Merchant, the Payment Handler
and the Delivery Handler are the same
Organisation since:
ActionOrgRef An Element Reference to the Organisation
Component of the Delivery Handler for this
delivery.
Content:
DeliveryData Contains details about how the delivery will be
carried out. See 7.13.1 Delivery Data Element
below.
PackagedContent Contains "user" data defined for the Merchant
which is required by the Delivery Handler as one
or more Packaged Content Elements see section 3.7.
The DeliveryData element contains information about where and how goods are to be delivered. Its definition is as follows.
<!ELEMENT DeliveryData (PackagedContent*) >
<!ATTLIST DeliveryData
xml:lang NMTOKEN #IMPLIED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
DelivMethod NMTOKEN #REQUIRED
DelivToRef NMTOKEN #REQUIRED
DelivReqNetLocn CDATA #REQUIRED
SecDelivReqNetLocn CDATA #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
xml:lang Defines the language used by attributes within
this component. See section 3.8 Identifying
Languages.
OkFrom The date and time in [UTC] format after which the
Delivery Handler may accept for processing a
Delivery Request Block (see section 8.10).
OkTo The date and time in [UTC] format before which
the Delivery Handler may accept for processing a
Delivery Request Block.
DelivMethod Indicates the method by which goods or services
may be delivered. Valid values are:
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:
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.
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.
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.
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:
ProcessState Contains a State Code which indicates the current
state of the process being carried out. Valid
values for ProcessState are:
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:
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.
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.
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.
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.
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:
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.
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
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.
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:
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.
The rules for deciding what to do with Trading Role Data Components are described below.
- the Trading Role Data Component as well as,
- the Organisation Component of the Organisation identified by
the OriginatorElRef attribute (if not already present)
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:
ElRef Contains an Element Reference (see section 3.5) to
the component to which this Inquiry Type Component
applies. That is,
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).
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:
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:
For a general explanation of signatures see section 6 Digital Signatures.
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:
It is recommended that the following Signature algorithm is also implemented:
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:
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.
The Manifest Element of a signature which has a type of OfferResponse should contain Digest elements for the following Components:
- the Protocol Options Component
- each of the Organisation Components
- each of the Brand List Components
- 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:
The Manifest Element of the Payment Receipt Signature Component should contain Digest Elements for the following Components:
The Manifest Element of the Delivery Response Signature Component should contain Digest Elements for the following Components:
The Manifest Element of the Authentication Request Signature Component should contain Digest Elements for the following Components:
- the Protocol Options Component
- the Organisation Component
- the Authentication Request Component(s) (if present)
- the Trading Role Information Request Component (if present)
The Manifest Element of the Authentication Response Signature Component should contain Digest Elements for the following Components:
- the Authentication Request Component that was used in the
Authentication (if present)
- the Trading Role Information Request Component (if present)
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.
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.
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.
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.
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].
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.
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:
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 (Warning|TransientError|HardError) #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:
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.
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.
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:
- 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.
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:
- 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.
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.
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:
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:
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:
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.
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.
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:
The Transaction Reference Block is described in section 3.3.
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:
- a Customer Care Provider
- an Certificate Authority that offers Merchant "Credentials" or
some other warranty on the goods or services being offered.
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.
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:
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:
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.
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.
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
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:
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.
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).
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:
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).
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.
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.
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:
These are then used to generate a signature over the 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:
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:
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.
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.
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).
A Signature Block which is in the same message as a Payment Request Block contains:
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.
A Signature Block which is in the same message as a Delivery Request Block contains:
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.
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:
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.
The Cancel Block is used by one Trading Role to inform any other that a transaction has been cancelled. Example usage includes:
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.
The Baseline Internet Open Trading Protocol supports three types of transactions for different purposes. These are
- Deposit
- Purchase
- Refund
- Withdrawal, and
- Value Exchange
- 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:
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:
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:
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.
The Authentication Document Exchange is a direct implementation of the Authentication Trading Exchange (see section 2.2.4). It involves:
The authentication consists of:
An Authentication Document Exchange also:
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)
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
On receiving a TPO & Authentication Request IOTP Message (see below), an Authenticatee may either:
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:
On receiving an Authentication Status IOTP Message (see below), the Authenticatee should check the Status Component in the Status Block. If this indicates:
- 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.
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.
Apart from a Transaction Reference Block (see section 3.3), this message consists of:
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:
AUTHENTICATION REQUEST BLOCK
The Authentication Request Block (see section 8.4) must contain the following Trading Components:
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:
- the Protocol Options Component
- the Organisation Component
- the Authentication Request Component
- the Trading Role Information Request Component
Apart from a Transaction Reference Block (see section 3.3), this message consists of:
Each of these are described below.
AUTHENTICATION RESPONSE BLOCK
The Authentication Response Block must contain the following Trading Component:
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:
- the Authentication Request Component
- the Trading Role Information Request Component
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.
Apart from a Transaction Reference Block (see section 3.3), this message consists of:
Each of these are described below.
AUTHENTICATION STATUS BLOCK
The Authentication Status Block (see section 8.6) must contain the following Trading Components:
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:
- 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:
The Offer Document Exchange occurs in two basic forms:
Each of these types of Offer Document Exchange may be preceded by an Authentication Document Exchange (see section 9.1.1).
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.:
This is illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Merchant
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:
On receiving a TPO Selection IOTP Message (see below) the Merchant may either:
On receiving an Offer Response IOTP Message (see below) the Consumer may either:
If the Merchant receives an IOTP Message containing a Cancel block, then the Consumer is likely to go to the CancelNetLocn specified on the Trading Role Element in the Organisation Component for the Merchant.
If the Consumer receives an IOTP Message containing a Cancel block, then the information contained in the IOTP Message should be reported to the Consumer but no further action taken.
In a Brand Independent Offer Document Exchange the TPO Block and the Offer Response Block are sent together by the Merchant to the Consumer, i.e. there is one IOTP Message that contains both a TPO Block, and an Offer Response Block.
The message flow is illustrated by the diagram below:
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Merchant
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, creates an Offer Response
containing details about the IOTP Transaction including
price, etc., optionally signs it and sends to Consumer
C <-- M TPO & OFFER RESPONSE. IotpMsg: Trans Ref Block; Signature Block; TPO Block; Offer Response 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,
checks offer is OK, combines the Brand Selection
Component with information from the TPO Block and 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 20 Brand Independent Offer Exchange
Note that a Brand Independent Offer Document Exchange always occurs when only one payment brand, protocol and currency/amount is being offered to the Consumer by the Merchant. It is also likely to, but will not necessarily, occur when multiple brands are being offered, the Payment Handler is the same, and all brands use the same set of protocols.
Note that the TPO Block and the Offer Response Block can be sent in separate IOTP messages (see Brand Dependent Offer Document Exchange) even if the Offer Response Block does not change. However this increases the number of messages in the transaction and is therefore likely to increase transaction response times.
IOTP aware applications supporting the Consumer Trading Role must check for the existence of an Offer Response Block in the first IOTP Message to determine whether the Offer Document Exchange is brand dependent or not.
MESSAGE PROCESSING GUIDELINES
On receiving a TPO and Offer Response IOTP Message (see below), the Consumer may either:
If the Merchant receives an IOTP Message containing a Cancel block, then the Consumer is likely to go to the CancelNetLocn specified on the Trading Role Element in the Organisation Component for the Merchant.
The TPO IOTP Message is only used with a Brand Dependent Offer Document Exchange. Apart from a Transaction Reference Block (see section 3.3), this message consists of just a Trading Protocol Options Block (see section 8.1) which is described below.
TPO (TRADING PROTOCOL OPTIONS) BLOCK
The Trading Protocol Options Block (see section 8.1) must contain the following Trading Components:
- Merchant who is making the offer
- Consumer who is carrying out the transaction
- the PaymentHandler(s) for the payment. The "ID" of the Payment
Handler Organisation Component is contained within the PhOrgRef
attribute of the Payment Component
If the IOTP Transaction includes a Delivery then the TPO Block must also contain:
- DeliveryHandler who will be delivering the goods or services
- DelivTo i.e. the person or Organisation which is to take
delivery
AUTHENTICATION STATUS AND SIGNATURE BLOCKS
If the Offer Document Exchange was preceded by an Authentication Document Exchange, then the TPO IOTP Message may also contain:
See section 9.1.1.4 Authentication Status IOTP Message for more details.
The TPO Selection IOTP Message is only used with a Brand Dependent Offer Document Exchange. Apart from a Transaction Reference Block (see section 3.3), this message consists of just a TPO Selection Block (see section 8.1) which is described below.
TPO SELECTION BLOCK
The TPO Selection Block (see section 8.2) contains:
The Offer Response IOTP Message is only used with a Brand Dependent Offer Document Exchange. Apart from a Transaction Reference Block (see section 3.3), this message consists of:
OFFER RESPONSE BLOCK
The Offer Response Block (see section 8.3) contains the following components:
SIGNATURE BLOCK (OFFER RESPONSE)
If the Authentication Status Block is being digitally signed then a Signature Block must be included that contains a Signature Component (see section 7.19) with Digest Elements for the following XML elements:
If the Offer Response is being digitally signed then a Signature Block must be included that contains a Signature Component (see section 7.19) with Digest Elements for the following XML elements:
- the Protocol Options Component, and
- the Brand List Component
- all the Organisation Components present
- the Order Component
- all the Payment Components present
- the Delivery Component if present
- any Trading Role Data Components present
The TPO and Offer Response IOTP Message is only used with a Brand Independent Offer Document Exchange. Apart from a Transaction Reference Block (see section 3.3), this message consists of:
TPO (TRADING PROTOCOL OPTIONS) BLOCK
This is the same as the Trading Protocol Options Block described in TPO IOTP Message (see section 9.1.2.3).
OFFER RESPONSE BLOCK
This the same as the Offer Response Block in the Offer Response IOTP Message (see section 9.1.2.5).
AUTHENTICATION STATUS
If the Offer Document Exchange was preceded by an Authentication Document Exchange, then the TPO and Offer Response IOTP Message may also contain an Authentication Status Block (see section 8.6).
SIGNATURE BLOCK
This is the same as the Signature Block in the Offer Response IOTP Message (see section 9.1.2.5) with the addition that:
The Payment Document Exchange is a direct implementation of the last part of a Payment Trading Exchange (see section 2.2.2) after the Brand has been selected by the Consumer. A Payment Exchange consists of:
The IOTP Messages which are involved are illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Payment
| Handler
1. Consumer generates Pay Request Block encapsulating a
payment protocol message if required and sends to Payment
Handler with the Signature Block if present
C --> P PAYMENT REQUEST. IotpMsg: Trans Ref Block; Signature Block (optional); Pay Request Block
2. Payment Handler processes Pay Request Block, checks
optional signature and starts exchanging payment protocol
messages encapsulated in a Pay Exchange Block, with the
Consumer
C <-> P PAYMENT EXCHANGE. IotpMsg: Trans Ref Block; Pay Exchange Block
3. Consumer and Payment Handler keep on exchanging Payment
Exchange blocks until eventually payment protocol
messages finish so Payment Handler creates a Pay Receipt
Component inside a Pay Response Block, and an optional
Signature Component inside a Signature Block, sends them
to the Consumer and stops.
C <-- P PAYMENT RESPONSE. IotpMsg: Trans Ref Block; Signature Block (optional); Pay Response Block
4. Consumer checks Payment Response is OK. Optionally keeps
information on IOTP Transaction for record keeping
purposes and either stops or creates the next IOTP
message for the Transaction and sends it together with
the Signature Block, if present, to the required Trading
Role
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 21 Payment Document Exchange
On receiving a Payment Request IOTP Message, the Payment Handler should check that they are authorised to carry out the Payment (see section 6 Digital Signatures). They may then either:
On receiving a Payment Exchange IOTP Message, the Consumer may either:
On receiving a Payment Exchange IOTP Message, the Payment Handler may either:
On receiving a Payment Response IOTP Message, the Consumer may either:
If the Consumer receives an IOTP Message containing a Cancel block, then the information contained in the IOTP Message should be reported to the Consumer but no further action taken.
If the Payment Handler receives an IOTP Message containing a Cancel block, then the Consumer is likely to go to the CancelNetLocn specified on the Trading Role Element in the Organisation Component for the Payment Handler from which any further action may take place.
If the Merchant receives an IOTP Message containing a Cancel block, then the Consumer should have completed the payment but not continuing with the transaction for some reason. In this case the Consumer is likely to go to the CancelNetLocn specified on the Trading Role Element in the Organisation Component for the Merchant from which any further action may take place.
Apart from a Transaction Reference Block (see section 3.3), this message consists of:
PAYMENT REQUEST BLOCK
The Payment Request Block (see section 8.7) contains:
- the Status Component
- the Payment Component for the payment which is being carried
out
- the Organisation Components with the roles of Merchant and for
the PaymentHandler that is being sent the Payment Request Block
- the Brand List Component for the payment, i.e. the Brand List
referred to by the BrandListRef attribute on the Payment
Component
- copied from the TPO Selection Block if the payment was preceded
by a Brand Dependent Offer Document Exchange (see section
9.1.2.1), or
- created by the Consumer, containing the payment brand, payment
protocol and currency/amount selected from the Brand List, if
the payment was preceded by a Brand Independent Offer Document
Exchange (see section 9.1.2.2)
Note that:
SIGNATURE BLOCK (PAYMENT REQUEST)
If the either the preceding Offer Document Exchange included an Offer Response Signature (see section 9.1.2.5 Offer Response IOTP Message), or a preceding Payment Exchange included a Payment Response Signature
(see section 9.1.3.4 Payment Response IOTP Message) then they should both be copied to the Signature Block in the Payment Request IOTP Message.
Apart from a Transaction Reference Block (see section 3.3), this message consists of just a Payment Exchange Block.
PAYMENT EXCHANGE BLOCK
The Payment Exchange Block (see section 8.8) contains:
Apart from a Transaction Reference Block (see section 3.3), this message consists of:
PAYMENT RESPONSE BLOCK
The Payment Response Block (see section 8.9) contains:
SIGNATURE BLOCK (PAYMENT RESPONSE)
If a signed Payment Receipt is being provided, indicated by the SignedPayReceipt attribute of the Payment Component being set to True, then the Signature Block should contain a Signature Component which contains Digest Elements for the following:
The Delivery Document Exchange is a direct implementation of a Delivery Trading Exchange (see section 2.2.3). It consists of:
The message flow is illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Delivery
| Handler
1. Consumer generates Delivery Request Block and sends it to
the Delivery Handler with the Signature Block if present
C --> D DELIVERY REQUEST. IotpMsg: Trans Ref Block; Signature Block; Delivery Request Block
2. Delivery Handler checks the Status and Order Components
in the Delivery Request and the optional Signatures,
creates a Delivery Response Block, sends to the Consumer
and stops.
C <-- D DELIVERY RESPONSE. IotpMsg: Trans Ref Block; Signature Block; Delivery Response Block
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 22 Delivery Document Exchange
On receiving a Delivery Request IOTP Message, the Delivery Handler should check that they are authorised to carry out the Delivery (see section 6 Digital Signatures). They may then either:
On receiving a Delivery Response IOTP Message, the Consumer should just stop since the IOTP Transaction is complete.
If the Consumer receives an IOTP Message containing a Cancel block, then the information contained in the IOTP Message should be reported to the Consumer but no further action taken.
The Delivery Request IOTP Message consists of:
DELIVERY REQUEST BLOCK
The Delivery Request Block (see section 8.10) contains:
- the Status Component (see section 7.16)
- the Order Component (see section 7.5)
- the Organisation Component (see section 7.6) with the roles of:
Merchant, DeliveryHandler and DeliverTo
- the Delivery Component (see section 7.13)
- the Status Component (see section 7.16).
SIGNATURE BLOCK (DELIVERY REQUEST)
If the preceding Offer Document Exchange included an Offer Response Signature or the Payment Document Exchange included a Payment Response Signature, then they should both be copied to the Signature Block.
The Delivery Response IOTP Message contains a Delivery Response Block and an optional Signature Block.
DELIVERY RESPONSE BLOCK
The Delivery Response Block contains:
in3 SIGNATURE BLOCK (DELIVERY RESPONSE)
The Signature Block should contain one Signature Component that contains Digest elements that refer to
The Payment and Delivery Document Exchange is a combination of the last part of the Payment Trading Exchange (see section 2.2.2) and a Delivery Trading Exchange (see section 2.2.3). It consists of:
- a Payment Response Block containing a receipt for the payment,
and
- a Delivery Response Block containing details of the goods or
services to be delivered
The IOTP Messages which are involved are illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Payment
| Handler
1. Consumer generates Pay Request Block encapsulating a
payment protocol message if required and sends to Payment
Handler with the Signature Block if present
C --> P PAYMENT REQUEST. IotpMsg: Trans Ref Block; Signature Block; Pay Request Block
2. Payment Handler processes Pay Request Block, checks
optional signature and starts exchanging payment protocol
messages encapsulated in a Pay Exchange Block, with the
Consumer
C <-> P PAYMENT EXCHANGE. IotpMsg: Trans Ref Block; Pay Exchange Block
3. Consumer and Payment Handler keep on exchanging Payment
Exchange blocks until eventually payment protocol
messages finish so Payment Handler creates a Pay Receipt
Component inside a Pay Response Block, and an optional
Signature Component inside a Signature Block, then uses
information from the Offer Response Bock to create a
Delivery Response Block and sends both to the Consumer
and stops.
C <-- P PAYMENT RESPONSE & DELIVERY RESPONSE. IotpMsg: Trans Ref Block; Signature Block; Pay Response Block; Delivery Response Block
4. Consumer checks Payment Response and Delivery Response
Blocks are OK. Optionally keeps information on IOTP
Transaction for record keeping purposes and either stops
or creates the next IOTP message for the Transaction and
sends it together with the Signature Block, if present,
to the required Trading Role
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 23 Payment and Delivery Document Exchange
The Delivery Response Block and the Payment Response Block may be combined into the same IOTP Message only if the Payment Handler has the information available so that she can send the Delivery Response Block. This is likely to, but will not necessarily, occur when the Merchant, the Payment Handler and the Delivery Handler Roles are combined.
The DelivAndPayResp attribute of the Delivery Component (see section 7.13) contained within the Offer Response Block (see section 8.3) is set to True if the Delivery Response Block and the Payment Response Block are combined into the same IOTP Message and is set to False if the Delivery Response Block and the Payment Response Block are sent in separate IOTP Messages.
On receiving a Payment Request IOTP Message or a Payment Exchange IOTP Message, the Payment Handler should carry out the same actions as for a Payment Document Exchange (see section 9.1.3.1).
On receiving a Payment Exchange IOTP Message, the Consumer should also carry out the same actions as for a Payment Document Exchange (see section 9.1.3.1).
On receiving a Payment Response and Delivery Response IOTP Message then the IOTP Transaction is complete and should take no further action.
If the Consumer receives an IOTP Message containing a Cancel block, then the information contained in the IOTP Message should be reported to the Consumer but no further action taken.
If the Payment Handler receives an IOTP Message containing a Cancel block, then the Consumer is likely to go to the CancelNetLocn specified on the Trading Role Element in the Organisation Component for the Payment Handler from which any further action may take place.
If the Merchant receives an IOTP Message containing a Cancel block, then the Consumer should have completed the payment but not continuing with the transaction for some reason. In this case the Consumer is likely to go to the CancelNetLocn specified on the Trading Role Element in the Organisation Component for the Merchant from which any further action may take place.
The content of this message is the same as for a Payment Request IOTP Message in a Payment Document Exchange (see section 9.1.3.2).
The content of this message is the same as for a Payment Exchange IOTP Message in a Payment Document Exchange (see section 9.1.3.3).
The content of this message consists of:
PAYMENT RESPONSE BLOCK
The content of this block is the same as the Payment Response Block in the Payment Response IOTP Message associated with a Payment Document Exchange (see section 9.1.3.4).
SIGNATURE BLOCK (PAYMENT RESPONSE)
The content of this block is the same as the Signature Block (Payment Response) in the Payment Response IOTP Message associated with a Payment Document Exchange (see section 9.1.3.4).
DELIVERY RESPONSE BLOCK
The content of this block is the same as the Delivery Response Block in the Delivery Response IOTP Message associated with a Delivery Document Exchange (see section 9.1.4.3).
A Baseline Authentication IOTP Transaction may occur at any time between any of the Trading Roles involved in IOTP Transactions. This means it could occur:
The Baseline Authentication IOTP Transaction consists of just an Authentication Document Exchange (see section 9.1.1) as illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
START ------------------------------------------------------- v
----------------
| AUTHENTICATION |
----------------
|
|
|
|
------------------- ----------------- |
| BRAND INDEPENDENT | | BRAND DEPENDENT | |
| OFFER | | OFFER | |
------------------- ----------------- |
|
|
|
|
|
--------- -------------- |
| PAYMENT | | PAYMENT WITH | |
| (first) | | DELIVERY | |
--------- -------------- |
|
|
|
---------- --------- |
| DELIVERY | | PAYMENT | |
| | | {second)| |
---------- --------- |
v
STOP
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 24 Baseline Authentication IOTP Transaction
Example uses of the Baseline Authentication IOTP Transaction include:
- set up a secure channel (e.g., using [SSL/TLS]) with a customer
- authenticate the customer using the Baseline Authentication
IOTP Transaction, and then
- provide the customer with access to account information and
other services with the confidence that they are communicating
with a bona fide customer.
The Baseline Deposit IOTP Transaction supports the deposit of electronic cash with a Financial Institution.
Note: The Financial Institution has, in IOTP terminology, a role of merchant in that a service (i.e. a deposit of electronic cash) is being offered in return for a fee, for example bank charges of some kind. The term "Financial Institution" is used in the diagrams and in the text for clarity.
The Baseline Deposit IOTP Transaction consists of the following Document Exchanges:
The way in which these Document Exchanges may be combined together is illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
START -----------------------------------------------------
| v
| ----------------
| | AUTHENTICATION |
| ----------------
-------------------------------------- |
| | |
| -------------- | -------------
v v v v
------------------- -----------------
| BRAND INDEPENDENT | | BRAND DEPENDENT |
| OFFER | | OFFER |
------------------- -----------------
| |
| |
| |
| -------------------
v v
--------- --------------
| PAYMENT | | PAYMENT WITH |
| (first) | | DELIVERY |
--------- --------------
|
----------------
|
---------- --------- |
| DELIVERY | | PAYMENT | |
| | | {second)| |
---------- --------- |
|
-----------------> STOP
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 25 Baseline Deposit IOTP Transaction
See section 9.1.12 "Valid Combinations of Document Exchanges" to determine which combination of document exchanges apply to a particular instance of an IOTP Transaction
Note that:
in practice to only one type. However, there may be several different protocols which may be used for the same "brand" of electronic cash. In this case a Brand Dependent Offer may be appropriate to negotiate the protocol to be used.
- the consumer could specify the account number prior to the
Baseline Deposit IOTP Transaction starting, or
- the consumer could have been identified earlier, for example
using a Baseline Authentication IOTP Transaction, and an
account selected from a list provided by the Financial
Institution.
- if a previous IOTP transaction, for example a Baseline
Withdrawal or a Baseline Authentication, authenticated the
consumer, and a secure channel has been maintained, therefore
the authenticity of the consumer is known
- if authentication is achieved as part of a proprietary payment
protocol and is therefore included in the Payment Document
Exchange
- if authentication of the consumer has been achieved by some
other means outside of the scope of IOTP, for example, by using
a pass phrase, or a proprietary banking software solution.
The Baseline Purchase IOTP Transaction supports the purchase of goods or services using any payment method. It consists of the following Document Exchanges:
- a Payment Document Exchange (see section 9.1.3) followed by
- a Delivery Document Exchange (see section 9.1.4)
The ways in which these Document Exchanges are 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 | | |
---------- --------- | | |
| DELIVERY | | PAYMENT | | | |
| | | {second)| | | |
---------- --------- | | |
| | | v
----------------------------------------------> STOP
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 26 Baseline Purchase IOTP Transaction
See section 9.1.12 "Valid Combinations of Document Exchanges" to determine which combination of document exchanges apply to a particular instance of an IOTP Transaction.
In business terms the refund process typically consists of:
- the original trade took place, for example by providing a
receipt for the original transaction
- using some type of authentication, that the consumer requesting
the refund is the consumer, or a representative of the
consumer, who carried out the original trade
- the reason why the merchant should make the refund
The Baseline Refund IOTP Transaction supports a subset of the above, specifically it supports:
- an optional Authentication Document Exchange (see section
9.1.1)
- an Offer Document Exchange (see section 9.1.2), and
- a Payment Document Exchange (see section 9.1.3).
The ways in which these Document Exchanges are combined is illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
START -----------------------------------------------------
| v
| ----------------
| | AUTHENTICATION |
| ----------------
-------------------------------------- |
| | |
| -------------- | -------------
v v v v
------------------- -----------------
| BRAND INDEPENDENT | | BRAND DEPENDENT |
| OFFER | | OFFER |
------------------- -----------------
| |
| |
| |
| -------------------
v v
--------- --------------
| PAYMENT | | PAYMENT WITH |
| (first) | | DELIVERY |
--------- --------------
|
----------------
|
---------- --------- |
| DELIVERY | | PAYMENT | |
| | | {second)| |
---------- --------- |
|
-----------------> STOP
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 27 Baseline Refund IOTP Transaction
A Baseline Refund IOTP Transaction without an Authentication Document Exchange might be used:
The Baseline Withdrawal IOTP Transaction supports the withdrawal of electronic cash from a Financial Institution.
Note: The Financial Institution has, in IOTP terminology, a role of merchant in that a service (i.e. a withdrawal of electronic cash) is being offered in return for a fee, for example bank charges of some kind. The term "Financial Institution" is used in the diagrams and in the text for clarity.
The Baseline Withdrawal IOTP Transaction consists of the following Document Exchanges:
The way in which these Document Exchanges may be combined together is illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
START -----------------------------------------------------
| v
| ----------------
| | AUTHENTICATION |
| ----------------
-------------------------------------- |
| | |
| -------------- | -------------
v v v v
------------------- -----------------
| BRAND INDEPENDENT | | BRAND DEPENDENT |
| OFFER | | OFFER |
------------------- -----------------
| |
| |
| |
| -------------------
v v
--------- --------------
| PAYMENT | | PAYMENT WITH |
| (first) | | DELIVERY |
--------- --------------
|
----------------
|
---------- --------- |
| DELIVERY | | PAYMENT | |
| | | {second)| |
---------- --------- |
|
-----------------> STOP
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 28 Baseline Withdrawal IOTP Transaction
Note that:
- the consumer could specify the account number prior to the
Baseline Withdrawal IOTP Transaction starting, or
- the consumer could have been identified earlier, for example
using a Baseline Authentication IOTP Transaction, and an
account selected from a list provided by the Financial
Institution.
- if a previous IOTP transaction, for example a Baseline Deposit
or a Baseline Authentication, authenticated the consumer, and a
secure channel has been maintained, therefore the authenticity
of the consumer is known
- if authentication is achieved as part of a proprietary payment
protocol and is therefore included in the Payment Document
Exchange
- if authentication of the consumer has been achieved by some
other means, for example, by using a pass phrase, or a
proprietary banking software solution.
The Baseline Value Exchange Transaction uses Payment Document Exchanges to support the exchange of value in one currency obtained using one payment method with value in the same or another currency using the same or another payment method. Examples of its use include:
The Baseline Value Exchange uses the following Document Exchanges:
The way in which these Document Exchanges may be combined together is illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
START -----------------------------------------------------
| v
| ----------------
| | AUTHENTICATION |
| ----------------
-------------------------------------- |
| | |
| -------------- | -------------
v v v v
------------------- -----------------
| BRAND INDEPENDENT | | BRAND DEPENDENT |
| OFFER | | OFFER |
------------------- -----------------
| |
| |
| |
| -------------------
v v
--------- --------------
| PAYMENT | | PAYMENT WITH |
| (first) | | DELIVERY |
--------- --------------
|
----
v
---------- ---------
| DELIVERY | | PAYMENT |
| | | {second)|
---------- ---------
|
-----------------------------> STOP
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 29 Baseline Value Exchange IOTP Transaction
The Baseline Value Exchange IOTP Transaction occurs in two basic forms:
Note: In the above the role is a Merchant even though the Organisation carrying out the Value Exchange may be a Bank or some other Financial Institution. This is because the Bank is acting as a merchant in that they are making an offer which the Consumer can either accept or decline.
The TPO Block and Offer Response Block may only be combined into the same IOTP Message if the content of the Offer Response Block does not change as a result of selecting the payment brands and payment protocols to be used in the Value Exchange.
BASELINE VALUE EXCHANGE SIGNATURES
The use of signatures to ensure the integrity of a Baseline Value Exchange is illustrated by the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
| - TPO Block MERCHANT
| - Offer Response Block
|
|
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 30 Baseline Value Exchange Signatures
The following diagram illustrates the data conditions in the various IOTP messages which can be used by a Consumer Trading Role to determine whether the combination of Document Exchanges are valid.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
START
|
v
Auth Request Block in =TRUE
first IOTP Message ? ---------------------------------------
| = FALSE |
v v
Offer Response Block in ----------------
first IOTP Message ? | AUTHENTICATION |
|=TRUE |=FALSE ----------------
| | |
| | v
| ---------------------- TPO & Offer Response
------------- | Blocks in last IOTP Msg
| | |=TRUE |=FALSE
| | | v
| ------------- | ---- TPO Block only if
| | | last IOTP Message
| | | of Authentication
| | | |=TRUE |=FALSE
v v v v |
------------------- ----------------- |
| BRAND INDEPENDENT | | BRAND DEPENDENT | |
| OFFER | | OFFER | |
------------------- ----------------- |
| | |
v v |
Offer Response Block contains |
Delivery Component ? |
|=FALSE |=TRUE |
--- v |
| Value of DelivAndPayResp |
| attribute of Delivery Component ? |
| |=FALSE |=TRUE |
| | | |
v v v |
--------- -------------- |
| PAYMENT | | PAYMENT WITH | |
| (first) | | DELIVERY | |
--------- -------------- |
| | |
v | |
Offer and Response Block contains -------------->|
Delivery Component ? |
|=TRUE |=FALSE |
| v |
| Two Payment Components |
| present in Offer Response Block? |
| |=TRUE |=FALSE |
v v | |
---------- --------- | |
| DELIVERY | | PAYMENT | | |
| | | {second)| | |
---------- --------- | |
| | | v
----------------------------------------------> STOP
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 31 Valid Combinations of Document Exchanges
1) If first IOTP Message of an IOTP Transaction contains an Authentication Request then:
a) IOTP Transaction includes an Authentication Document Exchange (see section 9.1.1). (Note 1)
b) If the last IOTP Message of the Authentication Document Exchange includes a TPO Block and an Offer Response Block then:
i) IOTP Transaction includes a Brand Independent Offer Document Exchange (see section 9.1.2.2). (Note 2)
c) Otherwise, if the last IOTP Message of the Authentication Exchange includes a TPO Block but NO Offer Response Block, then:
i) IOTP Transaction includes a Brand Dependent Offer Document Exchange (see section 9.1.2.1). (Note 2)
d) Otherwise (Authentication Status IOTP Message of the Authentication Document Exchange contains neither a TPO Block but nor an Offer Response Block)
i) IOTP Transaction consists of just an Authentication Document Exchange. (Note 3)
2) Otherwise (no Authentication Request in first IOTP Message):
e) IOTP Transaction does not include an Authentication Document Exchange (Note 2)
f) If first IOTP Message contains an Offer Response Block, then:
i) the IOTP Transaction contains a Brand Independent Offer Document Exchange (Note 2)
g) Otherwise (no Offer Response Block in first IOTP Message):
i) the IOTP Transaction includes a Brand Dependent Offer Document Exchange (Note 2)
3) If an Offer Response Block exists in any IOTP message then:
h) If the Offer Response Block contains a Delivery Component then:
i) If the DelivAndPayResp attribute of the Delivery Component is set to True, then:
(1) the IOTP Transaction consists of a Payment And Delivery Document Exchange (see section 9.1.5) (Note 4)
ii) otherwise (the DelivAndPayResp attribute of the Delivery Component is set to False)
(1) the IOTP Transaction consists of a Payment Document Exchange (see section 9.1.3) followed by a Delivery Document Exchange (see section 9.1.4) (Note 4)
i) otherwise (the Offer Response Block does not contain a Delivery Component)
i) if the Offer Response Block contains just one Payment Component, then:
(1) the IOTP Transaction contains just one Payment Document Exchange (Note 5)
ii) if the Offer Response Block contains two Payment Components, then:
(1) the IOTP Transaction contains two Payment Document Exchanges. The StartAfter attribute of the Payment Components is used to indicate which payment occurs first (Note 6)
iii) if the Offer Response Block contains no or more than two Payment Components, then there is an error
4) Otherwise (no Offer Response Block) there is an error.
The following table indicates the types of IOTP Transactions which can validly have the conditions indicated above.
Note IOTP Transaction Validity
In the previous sections an Authentication Document Exchange is shown preceding an Offer Document Exchange as part of a single IOTP Transaction with the same IOTP Transaction Id.
It is also possible to run a separate Authentication Transaction at any point, even in parallel with another IOTP Transaction. Typically this will be used:
In outline the basic process consists of:
For example, a Consumer could:
A Payment Handler could authenticate a Consumer after receiving the Payment Request and before sending the next Payment related message.
A Delivery Handler could authenticate a Consumer after receiving the Delivery Request and before sending the Delivery Response.
Note: Some Payment Methods may carry out an authentication within the Payment Exchange. In this case the information required to carry out the authentication will be included in Payment Scheme Components.
In this instance IOTP aware application will not be aware that an authentication has occurred since the Payment Scheme Components that contain authentication request information will be indistinguishable from other Payment Scheme Components.
Infrastructure Transactions are designed to support inquiries about whether or not a transaction has succeeded or a Trading Role's servers are operating correctly. There are two types of transaction:
Each of these is described below
The Baseline IOTP Transaction Status Inquiry provides information on the status of an existing or complete IOTP transaction.
The Trading Blocks used by the Baseline Transaction Status Inquiry Transaction are:
The Inquiry IOTP Transaction can be used for a variety of reasons. For example:
Note: Inquiries on Baseline Ping IOTP Transactions (see section 9.2.2) are ignored.
MAKING INQUIRIES OF ANOTHER TRADING ROLE
One Trading Role may make an inquiry of any other Trading Role at any point in time.
IOTP aware software that supports the Consumer Trading Role may not:
As a guideline:
- to the Merchant, after sending a TPO Selection Block,
- to the Payment Handler, after sending a Payment Request Block,
- to the Delivery Handler, after sending a Delivery Request Block,
TRANSACTION STATUS INQUIRY TRANSPORT SESSION
For a Transaction Status Inquiry on an ongoing transaction a different transport session from the ongoing transaction is used. For a Transaction Status Inquiry on a past transaction, how the IOTP
module on the software at the Trading Role is started upon the receipt of Inquiry Request message is defined in each Mapping to Transport supplement for IOTP.
TRANSACTION STATUS INQUIRY ERROR HANDLING
Errors in a Transaction Status Inquiry can be categorised into one of the following three cases:
The following outlines what the software should do in each case
BUSINESS ERRORS IN THE ORIGINAL MESSAGES
Return an Inquiry Response Block containing the Status Component which was last sent to the Consumer Role.
TECHNICAL ERRORS IN THE ORIGINAL MESSAGES
Return an Inquiry Response Block containing a Status Component. The Status Component should contain a ProcessState attribute set to ProcessError. In this case send back an Error Block indicating where the error was found in the original message.
TECHNICAL ERRORS IN THE INQUIRY REQUEST BLOCK
Return an Error message. That is, send back an Error Block containing the Error Code (see section 7.21.2) which describes the nature of the error in the Inquiry Request message.
INQUIRY TRANSACTION MESSAGES
The following Figure outlines the Baseline IOTP Transaction Status Inquiry process.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
1st Role
| 2nd Role
1. The first role decides to inquire on an IOTP Transaction
by, for example, clicking on the inquiry button of an
IOTP Aware Application. This will then generate an
Inquiry Request Block and send it to the appropriate
Trading Role.
1 --> 2 INQUIRY REQUEST. IotpMsg: TransRef Block; Signature Block (optional); Inquiry Request Block
2. The Trading Role checks the digital signature (if
present). If the recipient wants to respond, then the
Trading Role checks the transaction status of the
transaction that is being inquired upon by using the
IotpTransId in the Transaction ID Component of the
Transaction Reference Block, then generates the
appropriate Inquiry Response Block, sends the message
back to the 1st Role and stops
1 <-- 2 INQUIRY RESPONSE. IotpMsg: TransRef Block; Inquiry Response Block; Signature Block (Optional)
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 32 Baseline Transaction Status Inquiry
The remainder of this sub-section on the Baseline Transaction Status Inquiry IOTP Transaction defines the contents of each Trading Block. Note that the term "original transaction" is the transaction which a trading role wants to discover some information about.
TRANSACTION REFERENCE BLOCK
A Trading Role making an inquiry must use a Transaction Id Component (see section 3.3.1) where both the IotpTransId and TransTimeStamp attributes are the same as in the Transaction Id Component of the original transaction that is being inquired upon. The IotpTransId attribute in this component serves as the key in querying the
transaction logs maintained at the Trading Role's site. The value of the ID attribute of the Message Id Component should be different from those of any in the original transaction (see section 3.4.1).
If up-to-date status information is required then the MsgId Component, and in particular the ID attribute for the MsgId Component must be different from any other IOTP Message that has been sent by the Trading Role. This is required because of the way that Idempotency is handled by IOTP (see section 4.5.2.2 Checking/Handling Duplicate Messages).
INQUIRY REQUEST BLOCK
The Inquiry Request Block (see section 8.12) contains the following components:
SIGNATURE BLOCK (INQUIRY REQUEST)
If a signature block is present on the message containing the Inquiry Request Block then it may be checked to determine if the Inquiry Request is authorised.
If present, the Inquiry Request Signature Block (see section 8.12) contains the following components:
Inquiry Response Blocks should only be generated if the Transaction is authorised.
Note: Digital signatures on an Inquiry Request is only likely to occur if the recipient of the request expects the Inquiry Request to be signed. In this version of IOTP this will require some kind of pre-existing agreement. This means that:
On the other hand if the original transaction to which the Inquiry relates was carried out over a secure channel (e.g., [SSL]) then it is probably reasonable to presume that if the sender of the Inquiry knows the Transaction Id component of the original message (including for example the timestamp) then the inquiry is likely to be genuine.
INQUIRY RESPONSE BLOCK
The Inquiry Response Block (see section 8.13) contains the following components:
SIGNATURE BLOCK (INQUIRY RESPONSE)
If a signature block is present on the message containing the Inquiry Response Block then it may be checked by the receiver of the block to determine if the Inquiry Response is valid.
If present, the Inquiry Response Signature Block (see section 8.13) contains the following components:
Note: Digital signatures on an Inquiry Response is only likely to occur if the recipient of the response expects the Inquiry Request to be signed. In this version of IOTP this will require some kind of pre-existing agreement. This means that:
The purpose of the Baseline IOTP Ping Transaction is to test basic connectivity between the Trading Roles that may take part in an IOTP Transaction.
It enables IOTP aware application software to:
For example it can be used by a Merchant to determine if a Payment Handler or Delivery Handler is up and running prior to starting a Purchase transaction that uses those trading roles.
The Trading Blocks used by the Baseline Ping IOTP Transaction are:
PING MESSAGES
The following figure outlines the message flows in the Baseline IOTP Ping Transaction.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
1st Role
| 2nd Role
1. The IOTP Aware Application in the first Trading Role
decides to check whether the counterparty IOTP
application is up and running. It generates a Ping
Request Block and optional Signature Block and sends them
to the second trading role.
1 --> 2 PING REQUEST. IotpMsg: Trans Ref Block; Signature Block (Optional); Ping Request Block
2. The second Trading Role which receives the Ping Request
Block generates a Ping Response Block and sends it back
to the sender of the original Ping Request with a
signature block if required.
1 <-- 2 PING Response. IotpMsg: Trans Ref Block; Signature Block (Optional); Ping Response Block
3. The first Trading Role checks the Ping Response Block and
takes appropriate action, if necessary
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 33 Baseline Ping Messages
The verification that signatures can be handled is indicated by the sender of the Ping Request Block including:
In this way the receiver of the Ping Request:
Note that a Ping Request:
All IOTP aware applications must return a Ping Response message to the sender of a Ping Request message when it is received.
A Baseline IOTP Ping request can also contain an optional Signature Block. IOTP aware applications can, for example, use the Signature Block to check the recipient of a Ping Request can successfully process and check signatures it has received.
For each Baseline Ping IOTP Transaction, each IOTP role shall establish a different transport session from other IOTP transactions.
Any IOTP Trading Role can send a Ping request to any other IOTP Trading Role at any time it wants. A Ping message has its own IotpTransId, which is different from other IOTP transactions.
The remainder of this sub-section on the Baseline Ping IOTP Transaction defines the contents of each Trading Block.
TRANSACTION REFERENCE BLOCK
The IotpTransId of a Ping transaction should be different from any other IOTP transaction.
PING REQUEST BLOCK
If the Ping Transaction is anonymous then no Organisation Components are included in the Ping Request Block (see section 8.7).
If the Ping Transaction is not anonymous then the Ping Request Block contains Organisation Components for:
If Organisation Components are present, then it indicates that the sender of the Ping Request message has generated a Signature Block. The signature block must be verified by the Trading Role that receives the Ping Request Block.
SIGNATURE BLOCK (PING REQUEST)
The Ping Request Signature Block (see section 8.16) contains the following components:
PING RESPONSE BLOCK
The Ping Response Block (see section 8.15) contains the following component: