RFC 2801
Internet Open Trading Protocol - IOTP Version 1.0
RFC 2801: Internet Open Trading Protocol - IOTP Version 1.0 🛍️✨
okay bestie, let's start with the basics 💖 this is RFC 2801, titled "Internet Open Trading Protocol - IOTP Version 1.0." It's written by D. Burdett from Commerce One, and it's marked as Informational 🎀. The date is April 2000. The header doesn't list anything it obsoletes or updates, so there's no older version it's replacing. 🌸
Status of this Memo 🫶
so this memo is just here to give information to the Internet community 💅 it is not a standard of any kind, and it doesn't specify one. Distribution is unlimited, so share it with everyone 🦋
Copyright Notice 🌈
Copyright (C) The Internet Society (2000). All Rights Reserved. 💜
Abstract ✨
IOTP is the Internet Open Trading Protocol, and it's giving interoperable framework for Internet commerce 🔥 The big win is that it's payment system independent. It doesn't pick one payment method and marry it. Instead it encapsulates other payment systems, including SET, Secure Channel Credit/Debit, Mondex, CyberCoin, GeldKarte, and more 👑
IOTP also handles the different roles in a shopping transaction 🧚 Those roles are the shopping site, the Payment Handler, the Delivery Handler for goods or services, and the provider of customer support. Sometimes each role is run by a different party, and sometimes one party does all of them. IOTP works either way 💀✨
Table of Contents 🍓
1. Background .....................................................7
1.1 Commerce on the Internet, a Different Model .................7
1.2 Benefits of IOTP ............................................9
1.3 Baseline IOTP ..............................................10
1.4 Objectives of Document .....................................10
1.5 Scope of Document ..........................................11
1.6 Document Structure .........................................11
1.7 Intended Readership ........................................13
1.7.1 Reading Guidelines ...................................13
2. Introduction ..................................................14
2.1 Trading Roles ..............................................16
2.2 Trading Exchanges ..........................................18
2.2.1 Offer Exchange .......................................19
2.2.2 Payment Exchange .....................................21
2.2.3 Delivery Exchange ....................................24
2.2.4 Authentication Exchange ..............................26
2.3 Scope of Baseline IOTP .....................................28Part 1 of 54 is done! 🎀 The Background and Introduction sections are coming up next, and they get into the good stuff 🔥
okay bestie, the table of contents keeps going and it's giving a lot 💅✨ here's the rest of the map, every section and page number exactly where it lives 🗺️🎀
3. Protocol Structure ............................................31
3.1 Overview ...................................................32
3.1.1 IOTP Message Structure ...............................32
3.1.2 IOTP Transactions ....................................34
3.2 IOTP Message ...............................................35
3.2.1 XML Document Prolog ..................................37
3.3 Transaction Reference Block ................................37
3.3.1 Transaction Id Component .............................38
3.3.2 Message Id Component .................................39
3.3.3 Related To Component .................................41
3.4 ID Attributes ..............................................42
3.4.1 IOTP Message ID Attribute Definition .................43
3.4.2 Block and Component ID Attribute Definitions .........44
3.4.3 Example of use of ID Attributes ......................46
3.5 Element References .........................................46
3.6 Extending IOTP .............................................48
3.6.1 Extra XML Elements ...................................49
3.6.2 Opaque Embedded Data .................................50
3.7 Packaged Content Element ...................................50
3.7.1 Packaging HTML .......................................52
3.7.2 Packaging XML ........................................53
3.8 Identifying Languages ......................................54
3.9 Secure and Insecure Net Locations ..........................54
3.10 Cancelled Transactions .....................................55
3.10.1 Cancelling Transactions ..............................55
3.10.2 Handling Cancelled Transactions ......................56
4. IOTP Error Handling ...........................................56
4.1 Technical Errors ...........................................57
4.2 Business Errors ............................................57
4.3 Error Depth ................................................58
4.3.1 Transport Level ......................................58
4.3.2 Message Level ........................................58
4.3.3 Block Level ..........................................59
4.4 Idempotency, Processing Sequence, and Message Flow .........61
4.5 Server Role Processing Sequence ............................62
4.5.1 Initiating Transactions ..............................62
4.5.2 Processing Input Messages ............................63
4.5.3 Cancelling a Transaction .............................70
4.5.4 Retransmitting Messages ..............................70
4.6 Client Role Processing Sequence ............................71
4.6.1 Initiating Transactions ..............................71
4.6.2 Processing Input Messages ............................72
4.6.3 Cancelling a Transaction .............................74
4.6.4 Retransmitting Messages ..............................74
5. Security Considerations .......................................74
5.1 Determining whether to use digital signatures ..............74
5.2 Symmetric and Asymmetric Cryptography ......................76
5.3 Data Privacy ...............................................77
5.4 Payment Protocol Security ..................................77
6. Digital Signatures and IOTP ...................................77
6.1 How IOTP uses Digital Signatures ...........................77
6.1.1 IOTP Signature Example ...............................80
6.1.2 OriginatorInfo and RecipientInfo Elements ............82
6.1.3 Using signatures to Prove Actions Complete
Successfully .........................................83
6.2 Checking a Signature is Correctly Calculated ...............84
6.3 Checking a Payment or Delivery can occur ...................85
6.3.1 Check Request Block sent Correct Organisation ........86
6.3.2 Check Correct Components present in Request Block ....91
6.3.3 Check an Action is Authorised ........................91
7. Trading Components ............................................93
7.1 Protocol Options Component .................................96
7.2 Authentication Request Component ...........................97
7.3 Authentication Response Component ..........................98
7.4 Trading Role Information Request Component .................99
7.5 Order Component ...........................................100
7.5.1 Order Description Content ...........................101
7.5.2 OkFrom and OkTo Timestamps ..........................101
7.6 Organisation Component ....................................102
7.6.1 Organisation IDs ....................................104
7.6.2 Trading Role Element ................................105
7.6.3 Contact Information Element .........................108
7.6.4 Person Name Element .................................109
7.6.5 Postal Address Element ..............................110
7.7 Brand List Component ......................................111
7.7.1 Brand Element .......................................113
7.7.2 Protocol Brand Element ..............................115
7.7.3 Protocol Amount Element .............................116
7.7.4 Currency Amount Element .............................117
7.7.5 Pay Protocol Element ................................118
7.8 Brand Selection Component .................................120
7.8.1 Brand Selection Brand Info Element ..................122
7.8.2 Brand Selection Protocol Amount Info Element ........122
7.8.3 Brand Selection Currency Amount Info Element ........123
7.9 Payment Component .........................................123
7.10 Payment Scheme Component ..................................125
7.11 Payment Receipt Component .................................126
7.12 Payment Note Component ....................................128
7.13 Delivery Component ........................................129
7.13.1 Delivery Data Element ...............................130
7.14 Consumer Delivery Data Component ..........................132
7.15 Delivery Note Component ...................................133
7.16 Status Component ..........................................134
7.16.1 Offer Completion Codes ..............................137
7.16.2 Payment Completion Codes ............................138
7.16.3 Delivery Completion Codes ...........................140
7.16.4 Authentication Completion Codes .....................142
7.16.5 Undefined Completion Codes ..........................144
7.16.6 Transaction Inquiry Completion Codes ................144
7.17 Trading Role Data Component ...............................144
7.17.1 Who Receives a Trading Role Data Component ..........145
7.18 Inquiry Type Component ....................................146
7.19 Signature Component .......................................147
7.19.1 IOTP usage of signature elements and attributes .....148
7.19.2 Offer Response Signature Component ..................150
7.19.3 Payment Receipt Signature Component .................151
7.19.4 Delivery Response Signature Component ...............152
7.19.5 Authentication Request Signature Component ..........152
7.19.6 Authentication Response Signature Component .........153
7.19.7 Inquiry Request Signature Component .................153
7.19.8 Inquiry Response Signature Component ................153
7.19.9 Ping Request Signature Component ....................153
7.19.10 Ping Response Signature Component...................154
7.20 Certificate Component .....................................154
7.20.1 IOTP usage of signature elements and attributes .....154
7.21 Error Component ...........................................154
7.21.1 Error Processing Guidelines .........................157
7.21.2 Error Codes .........................................158
7.21.3 Error Location Element ..............................162
8. Trading Blocks ...............................................163
8.1 Trading Protocol Options Block ............................166
8.2 TPO Selection Block .......................................167
8.3 Offer Response Block ......................................168
8.4 Authentication Request Block ..............................169
8.5 Authentication Response Block .............................170
8.6 Authentication Status Block ...............................171
8.7 Payment Request Block .....................................171
8.8 Payment Exchange Block ....................................173
8.9 Payment Response Block ....................................173
8.10 Delivery Request Block ....................................175
8.11 Delivery Response Block ...................................176
8.12 Inquiry Request Trading Block .............................177
8.13 Inquiry Response Trading Block ............................177
8.14 Ping Request Block ........................................179
8.15 Ping Response Block .......................................179
8.16 Signature Block ...........................................181
8.16.1 Signature Block with Offer Response .................182
8.16.2 Signature Block with Payment Request ................182
8.16.3 Signature Block with Payment Response ...............182
8.16.4 Signature Block with Delivery Request ...............182
8.16.5 Signature Block with Delivery Response ..............182
8.17 Error Block ...............................................183
8.18 Cancel Block ..............................................184
9. Internet Open Trading Protocol Transactions ..................184 9.1 Authentication and Payment Related IOTP Transactions ......185
9.1.1 Authentication Document Exchange ....................188
9.1.2 Offer Document Exchange .............................194
9.1.3 Payment Document Exchange ...........................203
9.1.4 Delivery Document Exchange ..........................209
9.1.5 Payment and Delivery Document Exchange ..............212
9.1.6 Baseline Authentication IOTP Transaction ............216
9.1.7 Baseline Deposit IOTP Transaction ...................218
9.1.8 Baseline Purchase IOTP Transaction ..................220
9.1.9 Baseline Refund IOTP Transaction ....................222
9.1.10 Baseline Withdrawal IOTP Transaction ................224
9.1.11 Baseline Value Exchange IOTP Transaction ............226
9.1.12 Valid Combinations of Document Exchanges ............230
9.1.13 Combining Authentication Transactions with other
Transactions ........................................234
9.2 Infrastructure Transactions ...............................235
9.2.1 Baseline Transaction Status Inquiry IOTP Transaction 235
9.2.2 Baseline Ping IOTP Transaction ......................241
10. Retrieving Logos .............................................244
10.1 Logo Size .................................................245
10.2 Logo Color Depth ..........................................245
10.3 Logo Net Location Examples ................................246
11. Brands .......................................................246
11.1 Brand Definitions and Brand Selection .....................246
11.1.1 Definition of Payment Instrument ....................247
11.1.2 Definition of Brand .................................247
11.1.3 Definition of Dual Brand ............................248
11.1.4 Definition of Promotional Brand .....................248
11.1.5 Identifying Promotional Brands ......................249
11.2 Brand List Examples .......................................251
11.2.1 Simple Credit Card Based Example ....................252
11.2.2 Credit Card Brand List Including Promotional Brands..253
11.2.3 Brand Selection Example .............................254
11.2.4 Complex Electronic Cash Based Brand List ............255
12. IANA Considerations ..........................................257
12.1 Codes Controlled by IANA ..................................257
12.2 Codes not controlled by IANA ..............................263
13. Internet Open Trading Protocol Data Type Definition ..........263
14. Glossary .....................................................277
15. References ...................................................284
16. Author's Address .............................................287
17. Full Copyright Statement .....................................290
Table of Figures
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 2421. Background 🛍️
Okay so, the Internet Open Trading Protocol (IOTP) is basically an interoperable framework for Internet commerce 💖. It's payment system independent, which means it wraps up payment systems like SET, Mondex, CyberCash, DigiCash, GeldKarte, etc. ✨ IOTP can handle cases where the merchant roles (the shopping site, the Payment Handler, the Delivery Handler of goods or services, and the provider of customer support) are played by different parties, or by just one party. That's giving flexibility 💅.
The developers of IOTP were chasing a virtual version of the real world 🌍. They wanted something that safely replicates the paper based, traditional, totally understood ways of trading, buying, selling, and exchanging value that have existed for many hundreds of years 📜. Think about everything we just take for granted: negotiating who the parties to the trade are, how it'll go down, presenting an offer, the method of payment, getting a payment receipt, delivery of goods, and receiving the goods. IOTP is here to bring all of that to the virtual world 🌸, and to get ready for brand new models of trading that the expanding virtual world makes possible 🚀.
The other fundamental ideal of IOTP is defining these trading events so that, no matter where a product is made, two complete strangers using e-commerce capabilities that conform to the IOTP specifications can finish their business safely and successfully 🤝 iconic, honestly.
In summary, IOTP supports:
- Familiar trading models 🧁
- New trading models 🦋
- Global interoperability 🌈
This section is just the backstory 📖. The actual specification starts in the next chapter, bestie 🫶.
1.1 Commerce on the Internet, a Different Model 🌐
The growth of the Internet and the rise of electronic commerce are causing huge changes all over the world 🌏. They're changing society, politics, government, and business. The way trading partners communicate, do commerce, and get governed has been enriched and changed forever 💜.
One of the really fundamental changes IOTP cares about is how consumers and merchants trade 🛒. A few characteristics of trading have changed a lot:
- Presence: Face-to-face transactions are becoming the exception, not the rule 🙈. This was already happening with mail order and telephone order placement in western commerce, and electronic commerce over the Internet is going to expand the scope and volume of transactions done without ever seeing the people behind the business.
- Authentication: A big part of personal presence is being able to use familiar objects and dialogue to confirm you are who you claim to be 🪪. A seller shows off well known financial logos to say they accept widely used credit and debit instruments during the payment part of a purchase. The buyer brings government or financial institution ID to assure the seller they'll get paid. People also lean on intangibles like personal appearance and conduct, the location of the store, apparent quality, familiarity with merchandise brands, and a good clear look in the eye to back up the formal means of authentication 👀.
- Payment Instruments: Even with the enormous size of bank card payment associations and their members, most of the world's trade still happens using the coin of the realm or barter 🪙. The current payments infrastructure can't economically support low value transactions, and it couldn't survive the resulting volumes of transactions if it did accept them 😭.
- Transaction Values: Low value transactions mean something totally new on the Internet 💸, where sellers might offer things like pages of information for fractions of a currency that don't even exist in the real world 🤯.
- Delivery: New modes of delivery have to be accommodated, like direct electronic delivery 💻. How receipt is confirmed and how payment gets executed changes dramatically when goods or services have extremely low delivery cost but might still be super high value 👑. Or maybe the value isn't high, but once delivery happens the value is irretrievably delivered, so payment has to be final and non-refundable, and yet delivery still has to be confirmed before payment 🙃. Incremental delivery, like listening time, viewing time, or playing time, is another model that works a bit differently in the virtual world 🎧✨.
1.2 Benefits of IOTP ✨
ELECTRONIC COMMERCE SOFTWARE VENDORS 🛍️
Okay so, e-commerce software vendors get to build products that are way more attractive because they'll interoperate with any other vendor's software 🫶 That's a huge glow-up. But since IOTP is all about how these solutions communicate, there's still so much room for product differentiation. Main character energy for everyone 💅
PAYMENT BRANDS 💳
IOTP gives everyone a standard framework for encapsulating payment protocols 🎀 That makes it way easier for payment products to get plugged into IOTP solutions. The result? Payment brands end up more widely distributed and available on a wider variety of platforms. Iconic 👑
MERCHANTS 🍓
Merchants get a bunch of perks, bestie:
- they will be able to offer a wider variety of payment brands 💖
- they can be more certain that the customer will have the software needed to complete the purchase 🧚
- through receiving payment and delivery receipts from their customers, they will be able to provide customer care knowing that they are dealing with the individual or organisation with which they originally traded 🫶
- new merchants will be able to enter this new (Internet) market-place with new products and services, using the new trading opportunities which IOTP presents 🚀
BANKS AND FINANCIAL INSTITUTIONS 🏦
Banks and financial institutions get perks too:
- they will be able to provide IOTP support for merchants 💜
- they will find new opportunities for IOTP related services:
- providing customer care for merchants 🫶
- fees from processing new payments and deposits 💸
- they have an opportunity to build relationships with new types of merchants ✨
CUSTOMERS 🌸
Customers, this one's for you:
- they will have a larger selection of merchants with whom they can trade 🛒
- there is a more consistent interface when making the purchase 🦋
- there are ways in which they can get their problems fixed through the merchant (rather than the bank!) 🙈
- there is a record of their transaction which can be used, for example, to feed into accounting systems or, potentially, to present to the tax authorities 📒
1.3 Baseline IOTP
Okay, so this specification is Baseline IOTP 🎀 It's called "Baseline" because it covers the ways of doing trades on the Internet that are the most common, like purchases and refunds.
The group that has worked on IOTP sees an extended version being developed over time 🔮 But they feel the need to focus on a limited function that is still completely usable, so implementers can build solutions that work right now. Practical bestie energy 💅
During this period, no changes to the scope of this specification are anticipated. The only changes made will be limited to corrections where problems are found 🛠️ Software solutions have already 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), and those prove that IOTP works 🔥
1.4 Objectives of Document
The main goal of this document is to provide a specification of version 1.0 of the Internet Open Trading Protocols, so you can design and implement systems that support electronic trading on the Internet using IOTP 🧚
The purpose of the document is:
- to allow potential developers of products based on the protocol to develop software/hardware solutions which use the protocol 💻
- to allow the financial services industry to understand a developing electronic commerce trading protocol that encapsulates (without modification) any of the current or developing payment schemes now being used or considered by their merchant customer base 🏦✨
1.5 Scope of Document
The protocol describes the content, format and sequences of messages that pass among the participants in an electronic trade: consumers, merchants, 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 💖 That's because it targets the whole purchase process. Moving electronic value from the payer to the payee is only one step of many that might be involved in completing the trade, even though it's an important one.
Payment schemes 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 that 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 each participant will need to implement. 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 ⚖️
1.6 Document Structure
The document consists of the following sections:
- Section 1 - Background: This section gives a brief background on electronic commerce and the benefits IOTP offers. 🌈
- Section 2 - Introduction: This section describes the various Trading Exchanges and shows how these trading exchanges are used to construct the IOTP Transactions. This section also explains various Trading Roles that would participate in electronic trade. 🎀
- Section 3 - Protocol Structure: This section summarises how various IOTP transactions are constructed using the Trading Blocks and Trading Components that are the fundamental building blocks for IOTP transactions. All IOTP transaction messages are well formed XML documents. 🧱
- Section 4 - IOTP Error Handling: This section describes how to process exceptions and errors during the protocol message exchange and trading exchange processing. This section provides a generic overview of the exception handling. This section should be read carefully. 🚨
- Section 5 - Security Considerations: This section considers from an IETF perspective how IOTP addresses security. It includes: how to determine whether to use digital signatures with IOTP, how IOTP address data privacy, and how security built into payment protocols relate to IOTP security. 🔐
- Section 6 - Digital Signatures and IOTP: This section provides an overview of how IOTP uses digital signatures; how to check a signature is correctly calculated and how the various Trading Roles that participate in trade should check signatures when required. ✍️
- Section 7 - Trading Components: This section defines the XML elements required by Trading Components. 🧩
- Section 8 - Trading Blocks: This section describes how Trading Blocks are constructed from Trading Components. 🏗️
- Section 9 - Internet Open Trading Protocol Transactions: This section describes all the IOTP Baseline transactions. It refers to Trading Blocks and Trading Components and Signatures. This section doesn't directly link error handling during the protocol exchanges, so the reader is advised to understand Error Handling as defined in section before reading this section. 📖
- Section 10 - Retrieving Logos: This section describes how IOTP specific logos can be retrieved. 🖼️
- Section 11 - Brands: This section provides an overview of Brand Definitions and Brand Selection, which describe how a Consumer can select a Brand from a list provided by the Merchant, as well as some examples of Brand Lists. 🏷️
- Section 12 - IANA Considerations: This section describes how new values for codes used by IOTP are co-ordinated. 📋
- Section 13 - Internet Open Trading Protocol Data Type Definition: This section contains the XML Data Type Definitions for IOTP. 🗂️
- Section 14 - Glossary: This describes all the major terminology used by IOTP. 📘
- Section 15 - A list of the other documents referenced by the IOTP specification. 🔗
- Section 16 - The Author's Address 💌
- Section 17 - Full Copyright Statement ©️
1.7 Intended Readership
This one's for software and hardware developers, development analysts, business and technical planners, industry analysts, merchants, bank and other payment handlers, and owners, custodians, and users of payment protocols 💼✨
1.7.1 Reading Guidelines
Okay, this IOTP specification is mostly structured as a sequence aimed at people who want to understand the principles of IOTP 🧠 But if you're a new reader who plans to implement IOTP, implementers of earlier versions of the protocol have found that reading in a different sequence can work better, so here's how:
Review the transport independent parts of the specification. This covers:
- Section 14 - Glossary
- Section 1 - Background
- Section 2 - Introduction
- Section 3 - Protocol Structure
- Section 4 - IOTP Error Handling
- Section 5 - Security Considerations
- Section 9 - Internet Open Trading Protocol Transactions
- Section 11 - Brands
- Section 12 - IANA Considerations
- Section 10 - Retrieving Logos
Review the detailed XML definitions:
- Section 8 - Trading Blocks
- Section 7 - Trading Components
- Section 6 - Digital Signatures and IOTP
2. Introduction 🌟
The Internet Open Trading Protocols (IOTP) define a number of different types of IOTP Transactions:
- Purchase. This supports a purchase involving an offer, a payment and optionally a delivery 🛍️
- Refund. This supports the refund of a payment as a result of, typically, an earlier purchase 💸
- Value Exchange. This involves two payments which result in the exchange of value from one combination of currency and payment method to another 🔄
- Authentication. This supports one organisation or individual to check that another organisation or individual are who they appear to be 🕵️♀️
- Withdrawal. This supports the withdrawal of electronic cash from a financial institution 🏧
- Deposit. This supports the deposit of electronic cash at a financial institution 🪙
- Inquiry. This supports inquiries on the status of an IOTP transaction which is either in progress or is complete 🔍
- Ping. This supports a simple query which enables one IOTP aware application to determine whether another IOTP application running elsewhere is working or not. 🏓
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 involves:
- a number of organisations playing a Trading Role, and
- a set of Trading Exchanges. Each Trading Exchange involves the exchange of data, between Trading Roles, in the form of a set of Trading Components. 🧾
Trading Roles, Trading Exchanges and Trading Components are described below. 👀
2.1 Trading Roles ✨
okay so the Trading Roles are basically the different jobs organisations can have in a trade 💼💖 the diagram below shows the five IOTP Trading Roles and how they connect bestie, it's so pretty 🦋
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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
here are the roles, periodt 💅
- Consumer. The person or organisation which is to receive and pay for the goods or services 🛍️
- Merchant. The person or organisation from whom the purchase is being made and who is legally responsible for providing the goods or services and receives the benefit of the payment made 👑
- Payment Handler. The entity that physically receives the payment from the Consumer on behalf of the Merchant 💸
- Delivery Handler. The entity that physically delivers the goods or services to the Consumer on behalf of the Merchant 📦
- Merchant Customer Care Provider. The entity that is involved with customer dispute negotiation and resolution on behalf of the Merchant 🫶
Roles may be carried out by the same organisation or different organisations. For example:
- in the simplest case one physical organisation (e.g., a merchant) could handle the purchase, accept the payment, deliver the goods and provide merchant customer care 🧚
- at the other extreme, a merchant could handle the purchase but instruct the consumer to pay a bank or financial institution, request that delivery be made by an overnight courier firm and to contact an organisation which provides 24x7 service if problems arise 🌈
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. Trading Role, not a real company, got it? 🙈
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. Main character energy, literally 👑✨
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. That's where the next bit comes in 🦋
2.2 Trading Exchanges 💌
The Internet Open Trading Protocols identify four Trading Exchanges which involve the exchange of data between the Trading Roles. The Trading Exchanges are:
- Offer. The Offer Exchange results in the Merchant providing the Consumer with the reason why the trade is taking place. It is called an Offer since the Consumer must accept the Offer if a trade is to continue 🎀
- Payment. The Payment Exchange results in a payment of some kind between the Consumer and the Payment Handler. This may occur in either direction 💸
- Delivery. The Delivery Exchange transmits either the on-line goods, or delivery information about physical goods from the Delivery Handler to the Consumer, and 📦
- Authentication. The Authentication Exchange can be used by any Trading Role to authenticate another Trading Role to check that they are who they appear to be. No catfishing allowed 🕵️♀️💀
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. Mix and match, bestie 🍓
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. Efficiency is iconic 🔥
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. Lowkey tricky, but it makes sense once you see it 🌸
2.2.1 Offer Exchange 🎀
okay the goal of the Offer Exchange is for the Merchant to give the Consumer info about the trade so the Consumer can decide whether to continue. Here's the flow 👀
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Merchant
STEP | |
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
2. Merchant checks the information provided by the Consumer,
creates an Offer optionally signs it and sends it to the
Consumer.
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 Status component is used to indicate to other parties that a valid Offer Response has been generated 🚦
- the Organisation Component contains information which describes the Organisations which are taking a role in the trade:
- 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 Order Component contains descriptions of the goods or services which will result from the trade if the consumer agrees to the offer. This information is sent by the Merchant to the consumer who should verify it 🛒
- the Payment Component generated by the Merchant, contains details of how much to pay, the currency and the payment direction, for example the consumer could be asking for a refund. Note that there may be more than one payment in a trade 💰
- the Delivery Component, also generated by the Merchant, is used if goods or services are being delivered. This contains information about how delivery will occur, for example by post or using e-mail 📬
- the Trading Role Data component contains data the Merchant wants to forward to another Trading Role such as a Payment Handler or Delivery Handler 🧾
- the "Offer Response" Signature Component, if present, digitally signs all of the above components to ensure their integrity. Signed, sealed, delivered 🔏
The exact content of the information provided by the Merchant to the Consumer will vary depending on the type of IOTP Transaction. For example:
- low value purchases may not need a signature 🪙
- the amount to be paid may vary depending on the payment brand and payment protocol used 💳
- some offers may not involve the delivery of any goods 🌙
- a value exchange will involve two payments 🔁
- a merchant may not offer customer care 🙈
Information provided by the consumer to the merchant is provided using a variety of methods, for example, it could be provided:
- using [HTML] pages as part of the "shopping experience" of the consumer. 🛍️
- Using the Open Profiling Standard [OPS] which has recently been proposed, 🧁
- in the form of Organisation Components associated with an authentication of a Consumer by a Merchant 🔐
- as Order Components in a later version of IOTP. ⭐
2.2.2 Payment Exchange 💸
okay so the Payment Exchange is where the money actually moves 🤑 The main goal is a payment going from the Consumer to a Payment Handler (or the other way round) using a payment brand and payment protocol the Consumer picked. A secondary goal is optionally giving the Consumer a digitally signed Payment Receipt, which can link the payment back to the reason for paying, as described in the Offer Exchange. that receipt glow-up is everything 🧾✨
Payment Exchanges can work in a bunch of different ways. The most general case, where the trade depends on the payment brand and protocol used, is in the diagram below. Simpler payment exchanges are possible too 🌸
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer Pay Handler
| Merchant |
STEP | | |
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
2. Merchant decides which payment brand, payment
protocols and currencies/amounts to offer,
places then in a Brand List Component and sends
them to the Consumer
C <-- M Components: Brand List
3. Consumer selects the payment brand, protocol and
currency/amount to use, creates a Brand Selection
component and sends it to the Merchant
C --> M Component: Brand List Selection
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
5. Consumer checks the Payment Amount information and
if OK requests that the payment starts by sending
information to the Payment Handler
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 ExchangeA Payment Exchange uses these Trading Components, which get passed between the Consumer, the Merchant and the Payment Handler 🔁
- The Brand List Component holds a list of payment brands (for example, MasterCard, Visa, Mondex, GeldKarte), payment protocols (for example SET Version 1.0, Secure Channel Credit Debit (SCCD - the name used for a credit or debit card payment where unauthorised access to account information is prevented through use of secure channel transport mechanisms such as SSL/TLS)) and the 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 the ones the Consumer supports and makes a selection 💅
- The Brand Selection Component contains the Consumer's selection. The payment brand, protocol, currency/amount and possibly protocol-specific information get sent back to the Merchant. This information may be used to change information in the Offer Exchange. For example, a merchant could choose to offer a discount to encourage the use of a store card 🏷️
- The Status component is used to tell the Payment Handler that an earlier exchange (e.g., an Offer Exchange) has successfully completed, and the Payment Handler uses it to show the completion status of the Payment Exchange ✅
- The Organisation Components are generated by the Merchant. They contain details of the Merchant and Payment Handler Roles:
- 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 🔍
- The Payment Component has the details of how much to pay, the currency and the payment direction 💸
- The "Offer Response" Signature Component, if present, digitally signs all of the above components to keep their integrity intact. Heads up: the Brand List and Brand Selection Components aren't signed until the payment information gets created (step 4 in the diagram) ⚠️
- The Trading Role Data component holds stuff from other roles (e.g., a Merchant) that needs to be forwarded to the Payment Handler 📦
- The Payment Scheme Component contains messages from the payment protocol used in the Trade. For example, they could be SET messages, Mondex messages, GeldKarte messages or one of the other payment methods supported by IOTP. The content of the Payment Scheme Component is defined in the supplements that describe how IOTP works with the various payment protocols 🧩
- The Payment Receipt Component contains a record of the payment. The content depends on the payment protocol used 🧾
- The "Payment Receipt" Signature Component proves the payment happened by digitally signing both the Payment Receipt Component and the Offer Response Signature. The signature on the offer digitally signs the Order, Organisation and Delivery Components contained in the Offer. This signature effectively binds the payment to the offer, which is iconic behaviour honestly 👑
The Payment Exchange example above is the most general case. Simpler cases are also possible! For example, if the amount paid doesn't depend 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) 🦋
2.2.3 Delivery Exchange 🚚
so the Delivery Exchange is all about getting the purchased goods into the Consumer's hands, either online or through physical delivery 📬 A second goal is giving the consumer a "delivery note" with details about the delivery, like a shipping tracking number 🔎 The result of the delivery can also be signed, so it can be used for customer care if the physical delivery goes sideways 🫶 The message flow is in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
CONSUMER DELIVERY
| HANDLER
| Merchant |
STEP | | |
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)
2. Merchant checks the information provided by the
Consumer, adds information about how the delivery
will occur, information about the Organisations
involved in the delivery and optionally sings it
and sends it to the Consumer
C <-- M Components: Delivery; Organisations (Delivery
Handler, Deliver To); Order, Optional Offer
Response Signature
3. Consumer checks delivery information is OK,
obtains authorisation for the delivery, for
example by making a payment, and sends the
delivery information to the Delivery Handler
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 ExchangeOkay and a Delivery Exchange uses the following Trading Components that are
okay so these get passed between the Consumer, the Merchant and the Delivery Handler 💖
- the Status component is used to indicate to the Delivery Handler that an earlier exchange (e.g., an Offer Exchange or Payment Exchange) has successfully completed, and by the Delivery Handler to indicate the completion status of the Delivery Exchange ✨
- The Organisation Component(s) contain details of the Deliver To, Delivery Handler and Merchant Roles:
- 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 Order Component contains information about the goods or services to be delivered 🛍️
- The Delivery Component contains information about how delivery will occur, for example by post or using e-mail 📬
- The "Offer Response" Signature Component, if present, digitally signs all of the above components to ensure their integrity 🔐
- The "Payment Receipt" Signature Component provides proof of payment by digitally signing the Payment Receipt Component and the Offer Signature. This is used by the Delivery Handler to check that delivery is authorised 🧾
- The Delivery Note Component contains customer care information related to a physical delivery, or alternatively the actual "electronic goods". The Consumer's software does not interpret information about a physical delivery but should have the ability to display the information, both at the time of the delivery and later if the Consumer selects the Trade to which this delivery relates from a transaction list 🌸
- The "Delivery Response" Signature Component, if present, provides proof of the results of the Delivery by digitally signing the Delivery Note and any Offer Response or Payment Response signatures that the Delivery Handler received 👑
2.2.4 ✨ Authentication Exchange
The goal of the Authentication Exchange is to let one Organisation, for example a financial institution, check that another Organisation, for example a consumer, is who they appear to be 🦋
An Authentication Exchange involves:
- an Authenticator, which is the Organisation requesting the authentication, and
- an Authenticatee, which is the Organisation being authenticated 🫶
This is illustrated in the diagram below 👇
+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Organisation 1
(Authenticatee)
| Organisation 2
| (Authenticator)
STEP | |
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 ExchangeAn Authentication Exchange uses the following Trading Components that are passed between the two Organisations:
- the Authentication Request Component, which requests an Authentication and indicates the authentication algorithm and optional challenge data to be used 🔑
- a Trading Role Information Request Component, which requests information about an Organisation, for example a ship to address 📍
- the Authentication Response Component, which contains the challenge response generated by the recipient of the Authentication Request Component 💜
- Organisation Components that contain the result of the Trading Role Information Request 🗂️
- the Status Component, which contains the results of the second party's verification of the Authentication Response ✅
2.3 Scope of Baseline IOTP
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 can be of three types:
- those who accept a payment as part of a purchase or make a payment as part of a refund,
- those who accept value as part of a deposit transaction, or
- those that issue value a withdrawal transaction
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
Purchase Must Must
Merchants
ECash ECash
Store Value Value Consumer Payment Delivery
Issuer Acquirer Handler Handler
Refund Must b)
Depends
Authentication May Must May b)
Depends
Value Exchange May Must
Withdrawal Must b)
Depends
Deposit Must b)
Depends
Inquiry Must Must Must May Must Must
Ping Must Must Must May Must Must
TRADING BLOCKS
TPO Must Must Must Must
TPO Selection Must Must Must Must
Auth-Request a) a) a)
Depends Depends Depends
Auth-Reply a) a) a)
Depends Depends Depends
Offer Response Must Must Must Must
Payment Must Must
Request
Payment Must Must
Exchange
Payment Must Must
Response
Delivery Must Must
Request
Delivery Must Must
Response
Merchants
ECash ECash
Store Value Value Consumer Payment Delivery
Issuer Acquirer Handler Handler
Inquiry Must Must Must Must Must Must
Request
Inquiry Must Must Must Must Must Must
Response
Ping Request Must Must Must Must Must Must
Ping Response Must Must Must Must Must Must
Signature Must Must Must Limited Must Must
Error Must Must Must Must Must MustIn the above table:
- "Must" means that a Trading Role must support the Transaction or Trading Block.
- "May" means that an implementation may support the Transaction or Trading Block at the option of the developer.
- "Depends" means implementation of the Transaction or Trading Block depends on one of the following conditions:
- if Baseline Authentication IOTP Transaction is supported;
- if required by a Payment Method as defined in its IOTP Supplement document.
- "Limited" means the Trading Block must be understood and its content manipulated but not in every respect. Specifically, on the Signature Block, Consumers do not have to be able to validate digital signatures. 🫧
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" 👑
3. Protocol Structure ✨
The previous section provided an introduction which explained:
- Trading Roles, which are the different roles Organisations can take in a trade: Consumer, Merchant, Payment Handler, Delivery Handler and Customer Care Provider, and
- Trading Exchanges, where each Trading Exchange involves the exchange of data, between Trading Roles, in the form of a set of Trading Components 🎀
This section describes:
- how Trading Components are constructed into Trading Blocks and the IOTP Messages which are physically sent in the form of [XML] documents between the different Trading Roles,
- how IOTP Messages are exchanged between Trading Roles to create an IOTP Transaction,
- the XML definitions of an IOTP Message, including a Transaction Reference Block, an XML element which identifies an IOTP Transaction and the IOTP Message within it,
- the definitions of the XML ID Attributes which are used to identify IOTP Messages, Trading Blocks and Trading Components, and how these are referred to using Element References from other XML elements,
- how extra XML Elements and new user defined values for existing IOTP codes can be used when Extending IOTP,
- how IOTP uses the Packaged Content Element to embed data such as payment protocol messages or detailed order definitions within an IOTP Message,
- how IOTP Identifies Languages so that different languages can be used within IOTP Messages,
- how IOTP handles both Secure and Insecure Net Locations when sending messages, and
- how an IOTP Transaction can be cancelled. 🦋
3.1 Overview
3.1.1 IOTP Message Structure 💖
The structure of an IOTP Message and its relationship with Trading Blocks and Trading Components is illustrated in the diagram below 👇
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*3.1.2 IOTP Transactions ✨
CONSUMER MERCHANT
Generate first
IOTP Message
--- |
| | v
Process incoming | I | -------------
IOTP Message & <------------- | | ------------ | IOTP Message |
generate next IOTP | | -------------
Message | N |
| | |
v | |
------------- | T | Process incoming
| IOTP Message | -------------- | | -----------> IOTP Message &
------------- | | generate next
| E | IOTP Message
| | |
| | v
Process incoming | R | -------------
IOTP Message <------------- | | ------------ | IOTP Message |
generate last IOTP | | -------------
Message & stop | N |
| | |
v | |
------------- | E | Process last
| IOTP Message | -------------- | | -------------> incoming IOTP
------------- | | Message & stop
| | T | |
v | | v
STOP --- STOPFigure 7 An IOTP Transaction 🦋
Okay so in the diagram above, the Internet is drawn as the transport mechanism, but that's just the example, bestie. It's not necessarily the case 🙈 IOTP Messages can be sent over a whole bunch of different transport mechanisms, so don't lock yourself into one.
The IOTP Transactions (see section 9) in this version of IOTP are specifically:
- Purchase. This one supports a purchase that involves an offer, a payment and, optionally, a delivery 🛍️
- Refund. This supports refunding a payment, typically as a result of an earlier purchase 💸
- Value Exchange. This one involves two payments that swap value from one combination of currency and payment method to another 🔁
- Authentication. This supports the remote authentication of one Trading Role by another Trading Role, using a variety of authentication algorithms. It also provides Organisation Information about the Trading Role being authenticated, for use in things like creating an offer 🔐
- Withdrawal. This supports withdrawing electronic cash from a financial institution 🏦
- Deposit. This supports depositing electronic cash at a financial institution 💰
- Inquiry. This supports inquiries on the status of an IOTP transaction that is either still in progress or already complete 🔍
- Ping. This is a simple query that lets one IOTP aware application find out whether another IOTP application running elsewhere is working or not 🏓
3.2 IOTP Message ✨
As described earlier, IOTP Messages are [XML] documents that get physically sent between the different Trading Roles 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.3.2.1 XML Document Prolog 📜
The IOTP Message is the root element of the XML document, so it needs to be preceded by an appropriate XML Document Prolog. For example:
<?XML Version='1.0'?>
<!DOCTYPE IotpMessage >
<IotpMessage>
...
</IotpMessage>3.3 Transaction Reference Block 🌸
A Transaction Reference Block contains information which identifies the IOTP Transaction and the IOTP Message. The Transaction Reference Block contains:
- a Transaction Id Component which globally uniquely identifies the IOTP Transaction. The Transaction Id Components are the same across all IOTP messages that comprise a single IOTP transaction,
- a Message Id Component which provides control information about the IOTP Message, as well as uniquely identifying the IOTP Message within an IOTP Transaction, and
- zero or more Related To Components which link this IOTP Transaction to either other IOTP Transactions or other events, using the identifiers of those events.
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.3.3.1 Transaction Id Component ✨
Okay, bestie, this is the ID card for the whole IOTP Transaction 🪪💖 It globally, uniquely identifies the transaction, so it's kind of a big deal. Here's the layout:
<!ELEMENT TransId EMPTY >
<!ATTLIST TransId
ID ID #REQUIRED
Version NMTOKEN #FIXED '1.0'
IotpTransId CDATA #REQUIRED
IotpTransType CDATA #REQUIRED
TransTimeStamp CDATA #REQUIRED >ID This is an identifier that uniquely identifies the Transaction Id Component inside the IOTP Transaction. Main character energy 🦋
Version This tells you which version of IOTP is being used, and that decides the structure of the IOTP Messages in the transaction. It's giving version control 🎀
IotpTransId This holds data that uniquely identifies the IOTP Transaction. It must conform to the rules for Message Ids in [RFC 822]. No cap, it has to be legit 💅
IotpTransType (the RFC's table spells this IotpTransTyp, so I'm keeping that spelling in mind) This is the type of IOTP Transaction being carried out. For Baseline IOTP it names 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:
BaselineAuthenticationBaselineDepositBaselinePurchaseBaselineRefundBaselineWithdrawalBaselineValueExchangeBaselineInquiryBaselinePing
Values of IotpTransType are managed under the procedure described in section 12 IANA Considerations, which also lets people define their own user defined values of IotpTransType 🌈
In later versions of IOTP this list will get extended to cover different types of standard IOTP Transaction. It's also likely to support the type Dynamic, which means the steps in the transaction aren't standard. Ooh, so mysterious 🧚
TransTimeStamp If the system starting the IOTP Transaction has an internal clock, this is set to the time the transaction started, in [UTC] format ⏰
The main purpose of this attribute is to give you an alternative way to identify a transaction, by saying when it started.
Some systems, like hand held devices, may not be able to make a time stamp. In that case this attribute should contain the value "NA", for Not Available. Totally valid, no judgment 🫶
3.3.2 Message Id Component 💜
The Message Id Component gives control information about the IOTP Message, and it also uniquely identifies that IOTP Message within an IOTP Transaction. It's serious business, so here's the definition:
<!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 >ID An identifier that uniquely identifies the IOTP Message inside the IOTP Transaction (see section 3.4 ID Attributes). Here's the tea: if an IOTP Message gets resent, the value of this attribute stays the same 🍓
RespIotpMsg This contains the ID attribute of the Message Id Component of the IOTP Message that this IOTP Message is responding to. That's how all the IOTP Messages in an IOTP Transaction get unambiguously linked together, bestie 🔗 This field is required on every IOTP Message except the first IOTP Message in an IOTP Transaction.
SenderTradingRoleRef This is the Element Reference (see section 3.5) of the Trading Role that generated the IOTP message. It's used to figure out the Net Locations (see section 3.9) of that Trading Role, which is where problems Technical Errors (see section 4.1) with any of Trading Blocks should be reported. Someone has to get the complaints, iykyk 📬
xml:lang This defines the language used by attributes or child elements inside this component, unless a child element overrides it with its own xml:lang attribute. See section 3.8 Identifying Languages 🌸
LangPrefList This is an optional list of Language codes that conform to [XML] Language Identification. The sender uses it to say, in preference order, which languages the receiver ideally should use when making a response. The receiver isn't obligated to answer in one of the listed languages, but using one of them is likely to give a better user experience ✨
CharSetPrefList This is an optional list of Character Set identifiers that conform to [XML] Characters. The sender uses it to say, in preference order, which character sets the receiver ideally should use when generating a response. Same deal as before: the receiver has no obligation to pick one of them, but using one is likely to give an improved user experience 💅
SoftwareId This contains information that identifies the software that generated the IOTP Message. Its purpose is to help resolve interoperability problems that might happen because of incompatibilities between messages made by different software. It's a single text string in the language defined by xml:lang, and it must contain, as a minimum:
- the name of the software manufacturer
- the name of the software
- the version of the software, and
- the build of the software
Receipts, babe. Literally the whole point 🧾
TimeStamp If the device sending the message has an internal clock, this is set to the time the IOTP Message was created, in [UTC] format 🕰️
3.3.3 Related To Component 🦋
The Related To Component links IOTP Transactions to either other IOTP Transactions or to 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 >ID An identifier that uniquely identifies the Related To Component inside the IOTP Transaction.
xml:lang This defines the language used by attributes or child elements inside this component, unless a child element overrides it with its own xml:lang attribute. See section 3.8 Identifying Languages.
RelationshipType This defines the type of the relationship. The valid values are:
IotpTransaction.In this case the Packaged Content Element contains anIotpTransIdof another IOTP Transaction.ReferenceIn this case the Packaged Content Element contains the reference of some other, non-IOTP document.
Values of RelationshipType are controlled under the procedures defined in section 12 IANA Considerations, which also lets people define user defined values 🌷
Relation The Relation attribute contains a phrase, in the language defined by xml:lang, that describes the nature of the relationship between the IOTP transaction containing this component and another IOTP Transaction or other event. The exact words to use are left to the implementers of the IOTP software 🤌
The purpose of this attribute is to give the Trading Roles involved in an IOTP Transaction an explanation of how the transactions relate to each other.
Be careful with direction! The words in theRelationattribute should show the "direction" of the relationship correctly. For example, one transaction might be a refund for another earlier transaction. In that case, the transaction that is the refund should put words like "refund for" in theRelationattribute, not "refund to" or just "refund". Direction matters, bestie 🙈
RelnKeyWords This attribute contains keywords that could help identify similar relationships, for example all refunds. It's expected that recommended keywords will be developed by looking at actual usage. In this version of the specification there are no specific recommendations, and the keywords used are up to the discretion of implementers 🍭
Content:
PackagedContent The Packaged Content (see section 3.7) contains data that identifies the related transaction. Its format changes depending on the value of the RelationshipType 🎁
3.4 ID Attributes ✨
okay so IOTP Messages, Blocks (that's Transaction Reference Blocks and Trading Blocks), Trading Components (including the Transaction Id Component and the Signature Component) and some of their child elements each get an XML "ID" attribute 🆔 so each one can be pointed at. Every single one of them uses the attribute name ID, no cap.
The ID values have to be unique within an IOTP transaction 💜, which means the set of IOTP Messages that share the same globally unique Transaction ID Component. And once an element's ID attribute has a value, it never changes. So when an element gets copied, its ID stays exactly the same, periodt 💅
Because of that, you can use these IDs to refer to and locate the content of any Message, Block or Component from any other Message, Block or Component in the same IOTP Transaction, using Element References (see section 3.5) 🦋
This section lays out the rules for setting the ID attribute values of IOTP Messages, Blocks and Components. Let's gooo 🎀
3.4.1 IOTP Message ID Attribute Definition
The ID attribute of the Message Id Component of an IOTP Message must be unique within an IOTP Transaction. Here's the grammar:
IotpMsgId_value ::= IotpMsgIdPrefix IotpMsgIdSuffix
IotpMsgIdPrefix ::= NameChar (NameChar)*
IotpMsgIdSuffix ::= Digit (Digit)*Okay, the prefix 🌸 Apart from messages that contain an Inquiry Request Trading Block, an Inquiry Response Trading Block, a Ping Request Trading Block or a Ping Response Trading Block, every message sent by the Merchant or Consumer role uses the same prefix:
- "M" - Merchant
- "C" - Consumer
For messages with an Inquiry Request Trading Block or a Ping Request Trading Block, the prefix is "I" (for Inquiry) ✨
For messages with an Inquiry Response Trading Block or a Ping Response Trading Block, the prefix is "Q" 🧚
The prefix for the other roles in a trade lives in the Organisation Component for that role, and it's typically set by the Merchant. The following is a recommended guideline, but it must not be relied upon 🙈
- "P" - First (only) Payment Handler
- "R" - Second Payment Handler
- "D" - Delivery Handler
- "C" - Deliver To
As a guideline, prefixes should be limited to one character. And NameChar has the same definition as the [XML] definition of NameChar.
Now the suffix 🍓 It's one or more digits, and it must be unique within a Trading Role within an IOTP Transaction. Again, this next bit is a recommended guideline that must not be relied upon:
- the first IOTP Message sent by a trading role gets the suffix "1"
- the second and later IOTP Messages sent by the same trading role go up by one for each message
- no leading zeroes in the suffix
Put more simply, the Message Id Component of the first IOTP Message a Consumer sends would have an ID attribute of "C1", the second "C2", the third "C3", and so on 💖 Digit has the same definition as the [XML] definition of Digit.
3.4.2 Block and Component ID Attribute Definitions
The ID Attribute of Blocks and Components must also be unique within an IOTP Transaction. Their definition looks like this 👀
BlkOrCompId_value ::= IotpMsgId_value "." IdSuffix
IdSuffix ::= Digit (Digit)*For IotpMsgId_value, it's 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 get copied from one IOTP Message to another, and the ID attribute does not change when an existing Trading Block or Component is copied to another IOTP Message 🫶
For IdSuffix, it's one or more digits, and it must be unique within the ID attribute of the Message ID Component that was used to generate the ID attribute. Here's the recommended guideline (again, must not be relied upon) 🌈
- the first Block or Component sent by a trading role gets the suffix "1"
- the ID attributes of the second and later Blocks or Components go up by one for each new Block or Component added to an IOTP Message
- no leading zeroes in the suffix
Simply put, the first new Block or Component added to the second IOTP Message sent by, for example, a consumer would have an ID attribute of "C2.1", the second "C2.2", the third "C2.3", and so on ✨ Digit has the same definition as the [XML] definition of Digit.
3.4.3 Example of use of ID Attributes
Here's a diagram showing how ID attribute values get used in practice 🎀
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 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 attributes3.5 Element References
A Trading Component, or one of its child XML elements, may contain an XML attribute that refers to another Block (a Transaction Reference Block or a Trading Block) or another Trading Component (including a Transaction Id or Signature Component). These Element References get used for lots of things 🔥 A few examples:
- identifying an XML element whose Digest is included in a Signature Component
- referring to the Payment Handler Organisation Component that's used when making a Payment
An Element Reference always contains the value of an ID attribute of a Block or Component 💜
Finding the IOTP Message, Trading Block or Trading Component that an Element Reference points to means finding the XML element which:
- belongs to the same IOTP Transaction (meaning the Transaction Id Components of the IOTP Messages match), and
- has an ID attribute value that matches the value of the Element Reference
Note: the word "match" in this specification has the same definition as the [XML] definition of match 🧐
Here's an example of "matching" an Element Reference 🦋
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 ReferencesNote: Element Reference attributes are defined as "NMTOKEN" rather than "IDREF" (see [XML]). That's because an IDREF requires the XML element being referred to to be in the same XML Document, and with IOTP that isn't necessarily the case 🙈
3.6 Extending IOTP
Baseline IOTP defines a minimum protocol that systems supporting IOTP must be able to accept 🌸 As new versions of IOTP get developed, additional types of IOTP Transactions will be defined too. On top of that, Baseline and future versions of IOTP will support user extensions to IOTP through two mechanisms:
- extra XML elements, and
- new values for existing IOTP codes
that's the vibe for this part, bestie 🌈💖
3.6.1 Extra XML Elements ✨
okay bestie, so the XML element and attribute names in IOTP count as an [XML Namespace], the one identified by the xmlns attribute on the IotpMessage element 💅 that's what lets IOTP support extra XML elements inside messages through [XML Namespaces] 🦋
Using XML Namespaces, extra XML elements MAY be included at any level within an IOTP message, including:
- new Trading Blocks
- new Trading Components
- new XML elements within a Trading Component.
the rules are lowkey strict here 😭 👑 :
- any new XML element MUST be declared according to the rules for [XML Namespaces]
- new XML elements which are either Trading Blocks or Trading Components MUST contain an ID attributes with an attribute name of ID.
so IOTP can process extra elements properly, it reserves a special attribute called IOTP:Critical 🎀 it takes the values True or False and MAY appear in extra elements added to an IOTP message.
the whole point of this attribute is to let an IOTP aware app figure out if the transaction can safely keep going 🧚 here's how it plays out:
- if an extra XML element has an "IOTP:Critical" attribute with a value of "True" and an IOTP aware application does not know how to process the element and its child elements, then the IOTP transaction has a Technical Error (see section 4.1) and MUST fail. 💀
- if an extra XML element has an "IOTP:Critical" attribute with a value of "False" then the IOTP transaction MAY continue if the IOTP aware application does not know how to process it. In this case:
- 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 🌸
- if an extra XML element has no "IOTP:Critical" attribute then it MUST be treated as if it had an "IOTP:Critical" attribute with a value of "True" 🙈
- if an XML element contains an "IOTP:Critical" attribute, then the value of that attribute is assumed to apply to all the child elements within that element.
to keep documents with "IOTP:Critical" valid, it gets declared in the DTD for the extra element like this 🍓
IOTP:Critical (True | False ) 'True'3.6.2 Opaque Embedded Data 🦋
if IOTP is getting extended with Opaque Embedded Data, a Packaged Content Element (see section 3.7) SHOULD be used to encapsulate the data 🫶
3.7 Packaged Content Element 🎀
the Packaged Content element is all about embedded data streams 🌈 it gets transformed so transporting systems can't misread it, and it stays XML friendly too ✨ some examples in IOTP:
- to encapsulate payment scheme messages, such as SET messages,
- to encapsulate a description of an order, a payment note, or a delivery note.
generally speaking, it's used to wrap up one or more data streams 💜 this data stream has three standardised attributes so you can identify, decode and interpret the contents. here's the definition 👑
<!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:
o PCDATA. The content of the Packaged Content
Element can be treated as PCDATA with no
further processing.
o MIME. The content of the Packaged Content
Element is a complete MIME item. Processing
should include looking for MIME headers inside
the Packaged Content Element.
o MIME:mimetype. The content of the Packaged Content
Element is MIME content, with the
following header "Content-Type: mimetype".
Although it is possible to have MIME:mimetype
with the Transform attribute set to NONE, it is
far more likely to have Transform attribute set
to BASE64. Note that if Transform is NONE is
used, then the entire content must still
conform to PCDATA. Some characters will need to
be encoded either as the XML default entities,
or as numeric character entities.
o XML. The content of the Packaged Content
Element can be treated as an XML document.
Entities and CDATA sections, or Transform set
to BASE64, must be used to ensure that the
Packaged Content Element contents are
legitimate PCDATA.
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:
o NONE. The PCDATA content of the Packaged
Content Element is the correct representation
of the data. Note that entity expansion must
occur first (i.e. replacement of & and
	) before the data is examined. CDATA
sections may legitimately occur in a Packaged
Content Element where the Transform attribute
is set to NONE.
o BASE64. The PCDATA content of the Packaged
Content Element represents a BASE64 encoding of
the actual content.
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
attributesnote that any special details, especially custom attributes, MUST be represented at a higher level 🌟
3.7.1 Packaging HTML 🌸
the packaged content MAY contain HTML 💖 when it does, these conventions apply:
- references to any documents, images or other things, such as sounds or web pages, which can affect the recipient's understanding of the data which is being packaged MUST refer to other Packaged Elements contained within the same parent element, e.g., an Order Description
- if more than one Packaged Content element is included within a parent element in order to meet the previous requirement, then the Name attribute of the top level Packaged Content from which references to all other Packaged Elements can be determined, SHOULD have a value of Main
- relative references to other documents, images, etc. from one Packaged Content element to another are realised by setting the value of the relative reference to the Name attribute of another Packaged Content element at the same level and within the same parent element
- no external references that require the reference to be resolved immediately SHOULD NOT be used, as this could make the HTML difficult or impossible to display completely 🙃
- [MIME] is used to encapsulate the data inside each Packaged Element. This means that the information in the MIME header used to identify the type of data which has been encapsulated and therefore how it should be displayed.
if the above conventions aren't followed, like by 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 ✨
3.7.2 Packaging XML 💅
support for XML is RECOMMENDED 🫶 when XML needs to be displayed, like showing the content of an Order Description to a Consumer, 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:
- "Extensible Stylesheet Language (XSL) Specification" at
http://www.w3.org/TR/WD-xsl, and - "Associating stylesheets with XML documents" at
http://www.w3.org/TR/xml-stylesheet.
once these standards become W3C "Recommendations", it's anticipated that this specification will be amended if practical 🦋
3.8 Identifying Languages 🌍
IOTP uses [XML] Language Identification to specify which languages are used within the content and attributes of IOTP Messages 💜
these principles decide which XML elements contain an xml:lang Attributes 🎀
- a mandatory xml:lang attribute is contained on every Trading Component which contains attributes or content which may need to be displayed or printed in a particular language
- an optional xml:lang attribute is included on child elements of these Trading Components. In this case the value of xml:lang, if present, overrides the value for the Trading Component.
xml:lang attributes that follow these principles get 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 listing preferred languages/character sets in a Message Id Component (see section 3.3.2). the receiver is not obligated to respond using one of the listed languages/character sets, since they may not have the technology to do it 🙈 handling these lists is also not a requirement for conformance to this specification 💅 but responding with one of the stated languages/character sets is likely to give a much better user experience 🌸
3.9 Secure and Insecure Net Locations ✨
okay so IOTP has a bunch of "Net Locations," which are basically the spots where IOTP Messages can get sent 📬 There are two flavours 🍓
- "Secure" Net Locations, where privacy is locked down with something like encryption, for example [SSL/TLS] 🔐
- "Insecure" Net Locations, where privacy is not guaranteed 🙈
Here's the rule, bestie: a Secure Net Location or an Insecure Net Location or both must be present. If only one of them is there, then that one must be used. If both are there, either one can be used, depending on what the sender of the message prefers 💅
3.10 Cancelled Transactions 🛑
Any Trading Role that's involved in an IOTP transaction can cancel that transaction at any time. Main character energy, literally 👑
3.10.1 Cancelling Transactions 🙅♀️
So to cancel an IOTP Transaction, you send an IOTP message that contains just a Cancel Block with a suitable Status Component, sent to the other Trading Role 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. No cap, it's super flexible 🦋
If you cancel during a Trading Exchange (aka the time between sending a "request" block and getting the matching "response" block), the Cancel Block goes to the same location where the next IOTP Message in that Trading Exchange would have gone 🧚
If a Consumer cancels after the Trading Exchange is done (so the "response" block has already been received), but before the IOTP Transaction has finished, then the Consumer sends a Cancel Block with a suitable Status Component to the net location identified by the SenderNetLocn or SecureSenderNetLocn inside the Protocol Options Component (see section 7.1). That Component lives 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. Not it 💀
After cancelling the IOTP Transaction, the Consumer should go to the net location specified by the CancelNetLocn attribute, which sits in the Trading Role Element for the Organisation that got the Cancel Block 🏃♀️
A non-Consumer Trading Role should only cancel a transaction:
- after a request block has been received, and
- before the response block has been sent
If a non-Consumer Trading Role cancels a transaction at any other time, the recipient should treat it as an error 🚨
3.10.2 Handling Cancelled Transactions 🫶
If a Consumer gets a Cancel Block at a point in the IOTP Transaction where cancelling is allowed, then the Consumer should stop the transaction. Simple as that ✨
If a non-Consumer role gets a Cancel Block, then that Trading Role should expect that the Consumer may go to the location specified by the CancelNetLocn attribute in the Trading Role Element for the Trading Role. Plan ahead, babe 🧠
4. IOTP Error Handling 💀✨
IOTP is designed as a request/response protocol, where each message is made up of a bunch of Trading Blocks, and those Trading Blocks hold a bunch of Trading Components 🧩 There are a few interrelated things to think about when handling errors, re-transmissions, duplicates, and so on. Because of all that, IOTP aware applications have to manage message flows that are way more complex than a simple request/response model 😭 Also, a wide variety of errors can happen in messages, at the transport level, or in Trading Blocks or Components.
This section explains at a high level how IOTP handles errors, retries and idempotency. It covers:
- the different types of errors that can happen, which are split into:
- "technical errors," which are independent of the purpose of the IOTP Message, and
- "business errors," which point to a problem specific to the process (e.g., payment or delivery) being carried out
- the depth of the error, which tells you whether it's at the transport, message or block/component level
- how the different trading roles should handle the different types of messages they may receive
4.1 Technical Errors 🔧
Technical Errors are the ones that have nothing to do with what the message means. They can affect any attempt at IOTP communication 📡 They're usually handled in a standard way, with a small number of standard options for the user. Specifically, those options are:
- retrying the transmission, or
- cancelling the transaction.
When communications are working well enough, a technical error is flagged with an Error Component (see section 7.21) inside an Error Block (see section 8.17). That Error Block is sent by the party that detected the error, back to the party that sent the erroneous message 💌
If communications are too poor, a message that was sent may never reach its destination. In that case, a time-out might happen ⏰
The Error Codes for Technical Errors are recorded in the Error Component, which lists all the different technical errors that can be set 📝
4.2 Business Errors 💼
Business Errors can happen when the IOTP messages are "technically" correct. They're tied to a particular process, like an offer, payment, delivery or authentication, and each process has its own set of possible business errors 🛍️
For example, "Insufficient funds" is a reasonable payment error, but it makes zero sense for a delivery 😂 Meanwhile, "Back ordered" is a reasonable delivery error but isn't meaningful for a payment. Business errors are indicated in the Status Component (see section 7.16) of a "response block" of the appropriate type, like a Payment Response Block or a Delivery Response Block. That lets whatever extra response-related information is needed come along with the error indication 🎀
Business errors usually have to be shown to the user so 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 want to pick a different payment instrument/account of the same brand, or a different brand or payment system. Or, 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 💖
4.3 Error Depth 🌊
IOTP errors can happen at three levels: the transport level, the message level, and the block level. Each one is described below 🦋
4.3.1 Transport Level 🚚
This level of error means there's a fundamental problem with the transport mechanism that the IOTP communication is running over 🛣️
All transport level errors are technical errors. They're indicated either by an explicit transport level error indication, like 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 for transport level errors is to retry and, after some number of automatic retries, to inform the user 🔁
The explicit error indications you can receive depend on the transport. You should check the documentation for the appropriate IOTP Transport supplement for the errors and the right actions 📚
The right time outs depend on both the transport being used and, if the request carries payment information, the payment system. The transport and payment system specific documentation should be checked for time out and automatic retry parameters 💅 Often there's no way to tell the other party directly about transport level errors. They should generally be logged, though, and if automatic recovery doesn't work and there's a human user, the user should be informed 🫶
4.3.2 Message Level 📨
This level of error means there's a fundamental technical problem with an entire IOTP message 😬 For example, the XML isn't "Well Formed," or the message is too big for the receiver to handle, or there are errors in the Transaction Reference Block (see section 3.3), so it's impossible to figure out which transaction the message relates to 🧐
All message level errors are technical errors, and they're indicated by Error Components (see section 7.21) sent to the other party. The Error Component has a Severity attribute, which says whether the error is a Warning that may be ignored, a TransientError which means a retry may fix the problem, or a HardError, in which case the transaction must fail 💥
The Technical Errors (see section 7.21.2 Error Codes) that count as Message Level errors are:
- XML not well formed. The document is not well formed XML (see [XML])
- XML not valid. The document is not valid XML (see [XML])
- block level technical errors (see section 4.3.3) on the Transaction Reference Block (see section 3.3) and the Signature Block only. Checks on these blocks should only be carried out if the XML is valid ✅
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 cannot 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. Security stuff is serious, bestie 🔐😤
4.3.3 Block Level 🧱
A Block level error means there's a problem with a block, or one of its components, in an IOTP message (apart from Transaction Reference or Signature Blocks). The message was transported properly, and the overall message structure and the block/component(s), including the Transaction Reference and Signature Blocks, are meaningful. But there's some error related to one of the other blocks 🤔
Block level errors can be either:
- technical errors, or
- business errors
Technical Errors are further divided into:
- Block Level Attribute and Element Checks, and
- Block and Component Consistency Checks
- Transient Technical Errors
If a technical error happens related to a block or component, then an Error Component is generated to be returned 📤
4.3.3.1 Block Level Attribute and Element Checks 🔍
Block Level Attribute and Element Checks only happen within the same block. Checks that cross-check against other blocks are covered by Block and Component Consistency Checks 🧩
The Block Level Attribute & Element checks are:
- checking that each attribute value within each element in a block conforms to any rules contained within this IOTP specification
- checking that the content of each element conforms to any rules contained within this IOTP specification
- if the previous checks are OK, then checking the consistency of attribute values and element content against other attribute values or element content within any other components in the same block 💖
4.3.3.2 Block and Component Consistency Checks ✨
okay bestie, this is the consistency check round 💅 Block and Component Consistency Checks are made of three things:
- checking that the combo of blocks and/or components in the IOTP Message follows the rules in this IOTP spec 🎀
- checking that the attributes and element content inside the blocks of the same IOTP message agree with each other 🦋
- checking that the attributes and elements in these blocks agree with blocks received in earlier IOTP messages for the same IOTP transaction 🧚
If the block passes the "Block Level Attribute and Element Checks" and the "Block and Component Consistency Checks," then it gets processed by either the IOTP Aware application or some "back-end" system, like a payment server 💖
4.3.3.3 Transient Technical Errors 😭
okay so sometimes a temporary failure pops up while the Block is being processed. It can potentially be recovered if the other trading role re-transmits the original message they sent, a little bit later 🔁
In that case the other role gets told about the Transient Error by an Error Component (see section 7.21), with the Severity Attribute set to TransientError and the MinRetrySecs attribute set to some value that suits the Transport Mechanism and/or payment protocol being used (see the appropriate Transport and payment protocol Supplements) 🌸
Note that transient technical errors can be generated by any of the Trading Roles involved in the transaction 🫶
4.3.3.4 Block Level Business Errors 💸
If a business error happens in a process like a Payment or a Delivery, the appropriate type of response block comes back with a Status Component (see section 7.16). Its ProcessState is set to Failed, and the CompletionCode tells you what the problem was 🙈
Some business errors are "transient," meaning the Consumer role might be able to recover and finish the transaction some other way 🌈 For example, if the Credit Card a consumer gave had insufficient funds for a purchase, the Consumer can recover by using a different credit card 💳
Recovery from "transient" business errors depends on the CompletionCode. Check the definition of the Status Component to see what's possible 👑
Note that no Error Component or Error Block is generated for business errors. Not a single one! 🙅♀️
4.4 Idempotency, Processing Sequence, and Message Flow 🔁
IOTP messages are actually a mix of blocks and components (see 3.1.1 IOTP Message Structure). Especially in future extensions of IOTP, a rich variety of combinations can show up, and that's so iconic 🤩 It's super important that sending or receiving the "same" request for an action that changes state does not make that action happen 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, which might mean retransmission 😬 On the other hand, a request for status can totally be repeated and should be processed fresh every time it's received ✨
Correct implementation of IOTP can be modelled by a particular processing order, detailed below. Any other method that's indistinguishable in the messages sent between the parties is equally acceptable 🦋
4.5 Server Role Processing Sequence 🖥️
"Server roles" are any Trading Role that isn't the Consumer role. They're called that because they typically receive a request they must service and then produce a response. But server roles can also start transactions themselves 🎀 More specifically, Server Roles must be able to:
- Initiate a transaction (see section 4.5.1). These are divided into:
- payment related transactions and
- infrastructure transactions
- Accept and process a message received from another role (see section 4.5.2). This includes:
- identifying if the message belongs to a transaction that has been received before
- handling duplicate messages
- generating Transient errors if the servers processing 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
- Cancel a current transaction if requested (see section 4.5.3)
- Re-transmit messages if a response was expected but hasn't been received in a reasonable time (see section 4.5.4)
4.5.1 Initiating Transactions 🚀
Server Roles can start a variety of different transaction types. Specifically:
- an Inquiry Transaction (see section 9.2.1)
- a Ping Transaction (see section 9.2.2)
- an Authentication Transaction (see section 9.1.6)
- a Payment Related Transaction, such as:
- 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)
4.5.2 Processing Input Messages 📥
Processing input messages involves the following:
- checking the structure and identity of the message
- checking for and handling duplicate messages
- processing non-duplicate original messages, which includes:
- 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 🫶
4.5.2.1 Checking Structure and Message Identity 🔍
It is critical to check that the message is "well formed" XML, and that the transaction identifier (IotpTransId attribute on the TransId Component) can be successfully identified, since an IotpTransId is needed to generate a response 💖
If the input message is not well formed, generate an Error Component with a Severity of HardError and an ErrorCode of XmlNotWellFrmd 💀
If the message is well formed but the IotpTransId can't be identified, generate an ErrorComponent with:
- a
SeverityofHardErrorand anErrorCodeofAttMissing, - a
PackagedContentcontaining "IotpTransId", the missing attribute.
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 🎀
4.5.2.2 Checking/Handling Duplicate Messages 👯
If the input message can be identified as potentially a valid input message, check whether 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 compare their [DOM-HASH] values ✨
If an identical message has been received before, check whether the processing of the previous message has completed 🧐
If processing has not completed, generate an Error Component with a Severity of Transient Error and an ErrorCode of MsgBeingProc to indicate the message is being processed. Send it back to the sender of the Input Message, asking that the original message be resent after an appropriate period of time ⏳
Otherwise, if processing has completed and resulted in an output message, retrieve the last message that was sent and send it again 📨
If the message is not a duplicate, it should be processed 🙌
4.5.2.3 Processing Non-Duplicate Message 🧩
Once it's been established that the message is not a duplicate, it can be processed. This involves:
- checking that a server is available to handle the message, generating a Transient Error if it is not
- checking the Transaction is Not Already in error or cancelled
- validating the input message. This includes:
- checking for message level errors
- checking for block level errors
- checking any encapsulated data
- checking for errors in the sequence that blocks have been received
- generating error components for any errors that result
- if neither hard errors nor transient errors result, then processing the message and generating an output message, if required, for return to the sender of the Input Message
Note: This approach to handling duplicate input messages means that if absolutely "identical" messages are received, then absolutely "identical" messages are returned. This also applies to Inquiry and Ping transactions, even 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 isn't so busy that a response can't be produced in a reasonable time ⏰
If the server is too busy, it should generate an Error Component with a Severity of Transient Error and an ErrorCode of SystemBusy, then send it back to the sender of the Input Message, asking 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 lets short peaks be handled by delaying the input of messages and asking the sender of the message to resubmit later 🫶
Checking the Transaction Is Not Already in Error or Cancelled 🚫
Check that:
- previous messages received or sent did not contain or result in Hard Errors, and
- the Transaction has not been cancelled by either the Consumer or the Server Trading Role
If it has, then ignore the message. A transaction with hard errors, or one that has been cancelled, cannot be restarted 🙅♀️
Check for Message and Block Level Errors 🔎
If the transaction is still OK, check for message level errors. This involves:
- checking the XML is valid
- checking that the elements, attributes and content of the Transaction Reference Block are without error and conform to this specification
- checking the digital signature, which involves:
- checking that the Signature value is correctly calculated, and
- checking that the hash values in the digests are correctly calculated where the source of the hash value is available
Checking for block level errors involves:
- checking within each block (apart from the Transaction Reference Block) that:
- the attributes, elements and element contents are valid
- the values of the attributes, elements and element contents are consistent within the block
- checking that the combination of blocks is valid
- checking that the values of the attributes, elements and element contents are consistent between the blocks in the input message and blocks in earlier messages, either sent or received. This includes checking that the presence of a block is valid for a particular transaction type 🧠
If the message contains any encapsulated data, then, if possible, check the encapsulated data for errors using additional software, where appropriate 💜
4.5.2.4. Check for Errors in Block Sequence ✨
Okay bestie, quick heads up before we start 💅 For brevity, "refers to an IOTP transaction" really means "is contained in an IOTP Message where the Trans Ref Block contains an IotpTransId that refers to". So when you see something like "If an Error or Cancel Block refers to an IOTP transaction that is not recognised then ...", read it 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 ..." 🧚
The order blocks show up in depends on the block type 🫶 These are the blocks that need a sequence check:
- Error and Cancel Blocks. If an Error or Cancel Block refers to an IOTP transaction that is not recognised then it is a Hard Error. Do not return an error if Error or Cancel Blocks have been received for the IOTP Transaction before, so we don't end up looping 🔁
- Inquiry Request and Response Blocks. If an Inquiry Request or an Inquiry Response Block refers to an IOTP transaction that is not recognised then it is a Hard Error
- Authentication Request Block. If an Authentication Request Block refers to an IOTP transaction that is recognised it is a Hard Error.
- Authentication Response Block. Check as follows:
- 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.
- Authentication Status Block. Check as follows:
- 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
- TPO Selection Block (Merchant only). Check as follows:
- 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
- Payment Request Block (Payment Handler only). Check as follows:
- if the Payment Request Block refers to an IOTP Transaction that is not recognised then it's 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
- Payment Exchange Block (Payment Handler only). Check as follows:
- 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
- Delivery Request (Delivery Handler Only). If the Delivery Request Block refers to an IOTP Transaction that is recognised by the Server then it is 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:
- because they did not know the correct response (e.g., a password) on an authentication or,
- they were unable to pay as there were insufficient funds on a credit card
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:
- Inquiry Requests on Ping Transactions should be ignored
- if the Input message contains an Error Block with a Transient Error then wait for the required time then resend the previous message, if a response to the earlier message has not been received
- if the input message contains a Error Component with a
HardErroror a Cancel Block then stop all further processing of the transaction. This includes suppressing the sending of any messages currently being generated or responding to any new non-duplicate messages that are received 🛑 - processing of encapsulated messages (e.g., Payment Protocol Messages) may result in additional transient errors
- a digital signature can only safely be generated once all the blocks and components have been generated and it is known which elements in the message need to be signed ✍️
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. 💾
4.5.3 Cancelling a Transaction
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:
- if the IotpTransId of the transaction to be cancelled is not recognised, or complete then fail the request, otherwise
- if the IotpTransId refers to a Ping Transaction then fail the request, otherwise
- determine which Document Exchange to cancel and generate a Cancel Block and send it to the other party
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. 🙅♀️
4.5.4 Retransmitting Messages
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:
- the Transport Mechanism being used;
- the time required to process encapsulated messages (e.g., Payment messages) and
- whether or not human input is required.
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:
TimedOutRcvrif the transaction can potentially recovered later, orTimedOutNoRcvrif the transaction is non-recoverable
4.6 Client Role Processing Sequence 🎀
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:
- Initiate a transaction (see section 4.6.1). These are divided into:
- payment related transactions and
- infrastructure transactions
- Accept and process a message received from another role (see section 4.6.2). This includes:
- 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
- Cancel a current transaction if requested, for example by the User (see section 4.6.3)
- Re-transmit messages if a response was expected but has not been received in a reasonable time (see section 4.6.4). ⏰
4.6.1 Initiating Transactions
The Consumer Role may initiate a number of different types of transaction. Specifically:
- an Inquiry Transaction (see section 9.2.1)
- a Ping Transaction (see section 9.2.2)
- an Authentication Transaction (see section 9.1.6)
4.6.2 Processing Input Messages
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. 💜
4.6.2.1 Check for Errors in Block Sequence ✨
okay so for the Error and Cancel Blocks, the Inquiry Request and Response Blocks, and the Authentication Request, Response and Status Blocks, the handling is literally the same as for an IOTP Server (see section 4.5.2.4). The only difference is that the Consumer Role gets swapped in for the IOTP Server Role 💅
- Error and Cancel Blocks,
- Inquiry Request and Response Blocks,
- Authentication Request, Response and Status Blocks.
For the other blocks a Consumer role might receive, whether there's a sequence error depends on the block. These are the blocks that need a sequence check 👀
- TPO Block. Check as follows:
- if the input message also contains an Authentication Request block and an Offer Response Block, then it's a Hard Error, otherwise
- if the input message also contains an Authentication Request block and an Authentication Status block, then it's a 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 it's 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 it's a Hard Error, otherwise
- if the input message also contains an Authentication Status Block and the Authentication Status Block has not been sent after an earlier Authentication Response message, then it's a hard error, otherwise
- if the input message also contains an Offer Response Block and the IOTP Transaction is recognised by the Consumer role's system, then it's 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 it's a Hard Error
- Offer Response Block. Check as follows:
- if the Offer Response Block is part of a Brand Independent Offer Exchange (see section 9.1.2.2), then there's no sequence checking, because it's 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 it's 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 it's a Hard Error
- Payment Exchange Block. Check as follows:
- if the Payment Exchange Block doesn't refer to an IOTP Transaction that is recognised by the Consumer role's system, then it's 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 it's a Hard Error
- Payment Response Block. Check as follows:
- if the Payment Response Block doesn't refer to an IOTP Transaction that is recognised by the Consumer role's system, then it's a Hard Error, otherwise
- if the Payment Response doesn't refer to an IOTP Transaction where either a Payment Request or a Payment Exchange block was most recently sent, then it's a Hard Error
- Delivery Response Block. Check as follows:
- if the Delivery Response Block doesn't refer to an IOTP Transaction that is recognised by the Consumer role's system, then it's 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 it's a Hard Error
4.6.3 Cancelling a Transaction 🛑
This process cancels a current transaction on a Consumer role's system. It happens because of an external request from the user, or from another system or server in the Consumer's role. The processing is the same as for an IOTP Server (see section 4.5.3).
4.6.4 Retransmitting Messages 🔁
Retransmitting messages works the same way as it does for an IOTP Server (see section 4.5.4). no thinking required 🧠✨
5. Security Considerations 🔐
This section looks at how IOTP handles security, from an IETF point of view. The next section (see section 6. Digital Signatures and IOTP) explains how IOTP uses Digital Signatures when they're needed.
This section covers:
- determining whether to use digital signatures
- data privacy, and
- payment protocol security.
5.1 Determining whether to use digital signatures ✍️
Using digital signatures within IOTP is entirely optional 🫶 IOTP can work perfectly well with no signatures at all.
It's ultimately up to the Merchant, or other trading role, to decide whether IOTP Messages will include signatures. The Consumer decides whether doing a transaction without signatures is an acceptable risk. If Merchants find that transactions without signatures aren't being accepted, they'll either:
- start using signatures,
- find a method of working that doesn't need signatures, or
- accept a lower volume and value of business.
Here's a non-exhaustive list of reasons digital signatures might be used 💭
- the Merchant (or other trading role) wants to show that they can be trusted. For example, if a merchant generates an Offer Response Signature (see section 7.19.2) using a certificate from a trusted third party that the Consumer knows, then the Consumer can check the signature and certificate. That means the Consumer can more reasonably rely on the offer coming from the actual Organisation the Merchant claims to be. In this case, signatures using asymmetric cryptography are likely to be required.
- the Merchant, or other Trading Role, wants to generate a record of the transaction that's fit for a particular purpose. For example, with appropriate trust hierarchies, digital signatures could be checked by the Consumer to determine:
- whether it would be accepted by tax authorities as a valid record of a transaction, or
- whether some warranty was being provided, for example from a "Better Business Bureau" or similar.
- the Payment Handler, or Delivery Handler, needs to know that the request is unaltered and authorised. For example, in IOTP, details of how much to pay are sent to the Consumer in the Offer Response and then forwarded to the Payment Handler in a Payment Request. If the request isn't signed, the Consumer could change the amount due by, for example, removing a digit 😱 If the Payment Handler has no access to the original payment information in the Offer Response, then without signatures it can't be sure the data hasn't been altered. Similarly, if the payment information isn't digitally signed, the Payment Handler can't be sure who the Merchant is that's requesting the payment.
- a Payment Handler or Delivery Handler wants to provide a non-refutable record of the completion status of a Payment or Delivery. If a Payment Response or Delivery Response is signed, then the Consumer can later use that record to prove the Payment or Delivery happened. This could be used, for example, for customer care purposes. 🎀
Here's a non-exhaustive list of reasons digital signatures might NOT be used 🙅♀️
- trading roles are combined, so changes made to data by the Consumer can be detected. One reason for using signatures is so that one trading role can tell whether data has been changed by the Consumer or by some other party. However, if the trading roles have access to the necessary data, it might be possible to compare, for example, the payment information in the Payment Request with the payment information in the Offer Response. That access could come from, for example, the Merchant and Payment Handler roles being carried out by the same Organisation on the same system. It could also come from the Merchant and Payment Handler roles being carried out on different systems that can communicate in some way. (Note this type of communication is outside the current scope of IOTP.)
- the processing cost of the cryptography is too high. For example, if a payment is only a few cents, the cost of carrying out all the cryptography needed to generate and check digital signatures might make the whole transaction uneconomic. Co-locating trading roles could help avoid this problem.
5.2 Symmetric and Asymmetric Cryptography 🗝️
The advantage of using symmetric keys with IOTP is that no Public Key Infrastructure needs to be set up. Only the Merchant, Payment Handler and Delivery Handler need to agree on the shared secrets to use.
The downside of symmetric cryptography is that the Consumer can't easily check the credentials of the Merchant, Payment Handler, and so on, that they're dealing with. This is likely to reduce, somewhat, the trust the Consumer has when carrying out the transaction 🥺
It should be noted, though, that even when asymmetric cryptography is being used, the Consumer does not NEED to be given any digital certificates. 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. 🌈
5.3 Data Privacy 🤫
Privacy of information is provided by sending IOTP Messages between the various Trading Roles over a secure channel such as [SSL/TLS]. Using a secure channel within IOTP is optional.
5.4 Payment Protocol Security 💳
IOTP is designed to be completely blind to the payment protocol being used to make a payment. From a security perspective, this means IOTP neither helps nor hinders the achievement of payment security 🙈
If payment security needs to be considered from an IOTP perspective, then this should be included in the payment protocol supplement that describes how IOTP supports that payment protocol.
What IOTP is designed to do is use digital signatures to bind together the record of each trading exchange in a transaction. The record is contained in a "response" message. For example, IOTP can bind together an Offer, a Payment and a Delivery. 🎁
6. Digital Signatures and IOTP 🖋️
IOTP can work successfully without any digital signatures. However, 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 ⚠️
This section, though, describes how to use digital signatures in the many situations where they'll be needed. Topics covered are:
- an overview of how IOTP uses digital signatures
- how to check a signature is correctly calculated
- how Payment Handlers and Delivery Handlers check they can carry out payments or deliveries on behalf of a Merchant.
6.1 How IOTP uses Digital Signatures ✨
okay so, in general, signatures in IOTP are giving main character energy 💅 they:
- are always treated as IOTP Components (see section 7)
- contain digests of one or more IOTP Components or Trading Blocks, possibly including other Signature Components, in any IOTP message within the same IOTP Transaction
- identify:
- 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 can hang out with digital signatures when asymmetric cryptography is being used 🔐 but if symmetric cryptography is being used, the certificate gets swapped out for some identifier of the secret key to use 🗝️
here's how a Signature Component digests one or more elements 👀🫶
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 a Merchant signs an Offer first, creating an "Offer Response" signature 🛍️ and then a Payment Handler signs that together with a record of the payment, creating a "Payment Receipt" signature 💸 that's how the payment in an IOTP Transaction gets bound to the Merchant's offer 🎀
also, one Manifest can have multiple signature "Value" elements, where each Value element holds a digital signature over the same Manifest 🌈 maybe using the same signature algorithm, maybe a different one, but with a different certificate or shared secret key. this is how the Merchant can agree on different shared secret keys with their Payment Handler and Delivery Handler 🔑✨
the detailed definitions of a Signature component live in section 7.19 📖
the rest of this section covers:
- an example of how IOTP uses signatures
- how the OriginatorInfo and RecipientInfo elements within a Signature Component are used to identify the Organisations associated with the signature
- how IOTP uses signatures to prove actions complete successfully
6.1.1 IOTP Signature Example 🧚
okay, here's a visual of how the bits of a Baseline Purchase relate to each other 🍓 you'll want to remember this one later when we get into how signatures are used to check a payment or delivery can occur (see section 6.3)
Note: a Baseline Purchase transaction is used for illustration here 💅 but the elements and attributes work the same way for every type of IOTP Transaction.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
TPO SELECTION BLOCK TPO BLOCK IOTPSIGNATURE BLOCK
| (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
The Manifest element in the Signature Component contains digests of:
the Trans Ref Block (not shown); the Transaction ID Component (not
shown); Organisation Components (Merchant, Payment Handler, Delivery
Handler); the Brand List Component; the Order Component, the Payment
Component the Delivery Component and the Brand Selection Component (if a
Brand Dependent Purchase).
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*Figure 11 Example use of Signatures for Baseline Purchase 💜
6.1.2 OriginatorInfo and RecipientInfo Elements 🎀
the OriginatorRef attribute of the OriginatorInfo element in the Signature Component holds an Element Reference (see section 3.5) that points to the Organisation Component of whoever generated the Signature. in this example, that's the Merchant 🛍️
Note: the content of the Attribute element with a Type attribute set to IOTP Signature Type must match the Trading Role of the Organisation that signed it. if it doesn't, that's an error 🚨 the valid combinations are 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 rolethe RecipientRefs attribute of the RecipientInfo element in the Signature Component holds Element References to the Organisation Components of the Organisations that should use the signature to verify that:
- they have a pre-existing relationship with the Organisation that generated the signature,
- the data secured by the signature hasn't been changed,
- the data has been signed correctly, and
- the action they need to take on behalf of the Merchant is therefore authorised ✅
Note: if symmetric cryptography is being used, a separate RecipientInfo and Value element for each different set of shared secret keys is likely within the Signature Component 🔑
alternatively, if asymmetric cryptography is being used, the RecpientRefs attribute of one RecipientInfo element can point to multiple Organisation Components, as long as they're all using the same certificates 📜
6.1.3 Using signatures to Prove Actions Complete Successfully 🏆
proving an action completed successfully is done by signing data on Response messages. the specifics:
- on the Offer Response, when a Merchant makes an Offer to the Consumer, which can then be sent to either:
- a Payment Handler to prove that the Merchant authorises Payment, or
- a Delivery Handler to prove that Merchant authorises Delivery, provided other necessary authorisations are complete (see below)
- on the Payment Response, when a Payment Handler generates a Payment Receipt, which can be sent to either:
- a Delivery Handler, in a Delivery Request Block to authorise Delivery together with the Offer Response signature, or
- another Payment Handler, in a second Payment Request, to authorise the second payment in a Value Exchange IOTP Transaction
- Delivery Response, when a Delivery Handler generates a Delivery Note. this can prove, after the event, what the Delivery Handler said they would do 📦
- Authentication Response. one method of authenticating another party to a trade is to send an Authentication Request specifying that a Digital Signature should be used for authentication 🪪
- Transaction Status Inquiry. the Inquiry Response Block may be digitally signed to attest to the authenticity of the response 🔍
- Ping. the Ping Response may be digitally signed so that checks can be made that the signature can be understood 🏓
this proof of an action may, in future versions of IOTP, also be used to prove after the event that the IOTP transaction occurred, for example to a Customer Care Provider 💖 the receipts are coming for everyone, bestie 🧾✨
6.2. Checking a Signature is Correctly Calculated 💅
Okay bestie, checking that a signature is correctly calculated is part of checking for Message Level Errors (see section 4.3.2) 🔐. We're putting it here so all the signature and security stuff lives in one cute place ✨
Before a Trading Role can check a signature, it has to figure out which of the potentially multiple Signature elements to check 👀 Here's how it goes:
- check that a Signature Block is present and it contains one or more Signature Components
- identify the Organisation Component which contains an
OrgIdattribute for the Organisation which is carrying out the signature check. If no or more than one Organisation Component is found then it is an error 🙅♀️ - use the
IDattribute of the Organisation Component to find the RecipientInfo element that contains aRecipientRefsattribute that refers to that Organisation Component. Note there may be no signatures to verify 🫠 - check the Signature Component that contains the identified RecipientInfo element as follows:
- use the
SignatureValueRefand theSignatureAlgorithmRefattributes 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
SignatureCertRefto 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 🧾
- use the
6.3. Checking a Payment or Delivery can occur 🎀
This section is all about the processes a Payment Handler or Delivery Handler needs to follow to check that a payment or delivery can actually happen 💖 It may also include checking signatures, if the Merchant has specified that 🫶
In outline, the steps are:
- check that the Payment Request or Delivery Request has been sent to the correct Organisation
- check that correct IOTP components are present in the request, and
- check that the payment or delivery is authorised
For clarity and brevity, these terms are used in this section 📝
- a "Request Block" is used to refer to either a Payment Request Block (see section 8.7) or a Delivery Request Block (see section 8.10) unless specified to the contrary
- a "Response Block" is used to refer to either a Payment Response Block (see section 8.9) or a Delivery Response Block (see section 8.11)
- an "Action" is used to refer to an action which occurs on receipt of a Request Block. Actions can be either a Payment or a Delivery 💸
- an "Action Organisation", is used to refer to the Payment Handler or Delivery Handler that carries out an Action
- a "Signer of an Action", is used to refer to the Organisations that sign data about an Action to authorise the Action, either in whole or in part ✍️
- a "Verifier of an Action", is used to refer to the Organisations that verify data to determine if they are authorised to carry out the Action 🕵️♀️
- an
ActionOrgRefattribute contains Element References which can be used to identify the "Action Organisation" that should carry out an Action
6.3.1. Check Request Block sent Correct Organisation 📬
Checking the Request Block was sent to the correct Organisation depends on whether the request is for a Payment or a Delivery, so the two get their own little routines 🧚
6.3.1.1. Payment 💳
In outline, a Payment Handler checks if it can accept or make a payment by finding the Payment Component in the Payment Request Block it received 📦. Then it uses the ID of the Payment Component to trace through the Brand List and Brand Selection Components, works out which Organisation the Consumer picked, and checks that this Organisation is itself 🪞
Here's how the data is accessed, drawn out for you 🦋
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 🌈
Here are the steps and checks you need to make 🫧
- Identify the Payment Component (see section 7.9) in the Payment Request Block that was received.
- Identify the Brand List and Brand Selection Components for the Payment Component. This involves:
- identifying the Brand List Component (see section 7.7) where the value of its ID attribute matches the
BrandListRefattribute 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
BrandListRefattribute matches theBrandListRefof the Payment Component. If no or more than one matching Brand Selection Component is found there is an error.
- identifying the Brand List Component (see section 7.7) where the value of its ID attribute matches the
- Identify the Brand, Protocol Amount, Pay Protocol and Currency Amount elements within the Brand List that have been selected by the Consumer as follows:
- the Brand Element (see section 7.7.1) selected is the element where the value of its Id attribute matches the value of the
BrandRefattribute 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
ProtocolAmountRefattribute 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
PayProtocolRefattribute 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
CurrencyAmountRefattribute in the Brand Selection Component. If no or more than one matching Currency Amount element 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
- Check the consistency of the references in the Brand List and Brand Selection Components:
- check that an Element Reference exists in the
ProtocolAmountRefsattribute 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
CurrencyAmountRefsattribute 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.
- check that an Element Reference exists in the
- Check that the Payment Handler that received the Payment Request Block is the Payment Handler selected by the Consumer. This involves:
- identifying the Organisation Component for the Payment Handler. This is the Organisation Component where its ID attribute matches the
ActionOrgRefattribute 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
Roleattribute ofPaymentHandler. 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. 🚨
- identifying the Organisation Component for the Payment Handler. This is the Organisation Component where its ID attribute matches the
6.3.1.2. Delivery 🚚
The way a Delivery Handler accesses data to check that it may carry out a delivery is shown 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 🫶
- Identify the Delivery Component in the Delivery Request Block. If there is no or more than one matching Delivery Component there is an error
- Use the
ActionOrgRefattribute of the Delivery Component to identify the Organisation Component of the Delivery Handler. If there is no or more than one matching Organisation Component there is an error - If the Organisation Component for the Delivery Handler does not have a Trading Role Element with a
Roleattribute ofDeliveryHandlerthere is an error - Finally, if the Organisation that received the Delivery Request Block does not identify the Organisation Component for the Delivery Handler as itself, then there is an error. 🙅♀️
6.3.2 Check Correct Components present in Request Block ✨
Next up, bestie: check that the right components are actually in the Payment Request Block (see section 8.7) or the Delivery Request Block (see section 8.10). 🎀
If any components are missing, that's an error. 🙈
6.3.3 Check an Action is Authorised 💅
The earlier steps already figured out who the Action Organisation is and confirmed that all the necessary components are there. Now we check that this Action Organisation is actually allowed to do the Action. 👑
The big picture: the Action Organisation finds the Merchant, checks that it has a pre-existing agreement with that Merchant that lets it carry out the Action, and makes sure any constraints from that agreement are being followed. Then, if signatures are required, it checks that they sign the correct data. It's giving very methodical energy 🧚
The steps go like this:
- Identify the Merchant. This is the Organisation Component with a Trading Role Element whose Role attribute has a value of
Merchant. If no Trading Role Element is found, or more than one is found, that's an error. 💀 - Check that the Action Organisation's agreements with the Merchant allow the Action to be carried out. To do this, the Action Organisation must check that:
- the Merchant is known, and a pre-existing agreement exists for the Action Organisation to be their agent for the payment or delivery 🦋
- the Action Organisation is allowed to take part in the type of IOTP transaction that's happening. 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. Not the same thing at all! 🙅♀️
- any constraints in the agreement with the Merchant are being followed. For example, whether or not an Offer Response signature is required. 📝
- Check that the signatures are correct. If signatures are required, they need to be checked. This involves:
- Identifying the correct signatures to check. The Action Organisation finds 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 means checking that Digest elements exist within the Manifest Element that refer to the necessary Trading Components (see section 6.3.3.1). 🫶
6.3.3.1 Check the Signatures Digests are correct 🌸
Every Signature Component inside an IOTP Message must include Digest elements that refer to:
- the Transaction Id Component (see section 3.3.1) of the IOTP message that contains the Signature Component. This is what binds the globally unique IotpTransId to the other components that make up the IOTP Transaction. Very important, very iconic. 💜
- the Transaction Reference Block (see section 3.3) of the first IOTP Message that contained the signature. This binds the IotpTransId to info about the IOTP Message inside the Message Id Component (see section 3.3.2). 🔗
So check that each Signature Component has Digest elements that refer to the correct data. 🔥
Which Digest elements need to be there depends on the Trading Role of the Organisation that generated (signed) the signature:
- if the signer of the signature is a Merchant, then:
- Digest elements must be present for all the components in the Request Block, apart from the Brand Selection Component, which is optional 🍓
- if the signer of the signature is a Payment Handler, then Digest elements must be present for:
- the Signature Component signed by the Merchant, and optionally
- one or more Signature Components signed by the previous Payment Handler(s) in the Transaction. 🌈
7. Trading Components ⭐
This section is all about the Trading Components used within IOTP. These are the child XML elements that sit immediately below a Trading Block, as shown in the diagram below. Picture a little family tree, it's so cute 🌸
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 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 ComponentsThe Trading Components in this section are listed below, roughly in the order you'd probably use them: 🦋
- Protocol Options Component
- Authentication Request Component
- Authentication Response Component
- Trading Role Information Request Component
- Order Component
- Organisation Component
- Brand List Component
- Brand Selection Component
- Payment Component
- Payment Scheme Component
- Payment Receipt Component
- Delivery Component
- Delivery Data Component
- Delivery Note Component
- Signature Component
- Certificate Component
- Error Component
Heads up, some components live in other sections of this spec: 👀
- Transaction Id Component (see section 3.3.1)
- Message Id Component (see section 3.3.2)
7.1 Protocol Options Component 🎀
Protocol options are the options that apply to the IOTP Transaction as a whole. Basically, it gives a short description of the entire transaction, plus the net location that the Consumer role should branch to if the IOTP Transaction is successful. ✨
Here's the definition of a Protocol Options Component: 💖
<!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.One rule to remember: either SenderNetLocn, SecureSenderNetLocn or both must be present. 🫶 Okay, that's the whole vibe for this bit! 🌈
7.2 Authentication Request Component
okay so this Trading Component carries the parameter data that one Trading Role uses to authenticate another Trading Role 🔐✨ here's the definition:
<!ELEMENT AuthReq (Algorithm, PackagedContent*)>
<!ATTLIST AuthReq
ID ID #REQUIRED
AuthenticationId CDATA #REQUIRED
ContentSoftwareId CDATA #IMPLIED >if it's required, the Algorithm may use the challenge data sitting in the Packaged Content elements inside the Authentication Request Component as part of its calculation 🧮 the format of the Packaged Contents is Algorithm dependent, so it depends on which Algorithm you picked 💅
Attributes:
ID: the identifier that uniquely identifies this Authentication Request Component within the IOTP Transaction 🆔AuthenticationId: an identifier set by the Authenticator. If the Organisation that receives the Authentication Request sends it back, the Authenticator can tell which Authentication is being referred to 🔁ContentSoftwareId: see section 14.Glossary 📚
Content:
PackagedContent: this holds the challenge data as one or more Packaged Content (see section 3.7), which is the stuff you have to respond to using the Algorithm named in the Algorithm element 🧩Algorithm: this describes the Algorithm (see 7.19 Signature Components) that must be used to generate the Authentication Response. The Algorithms that may be used are identified by the Name attribute of the Algorithm element. For valid values see section 12. IANA Considerations 🌸
7.3 Authentication Response Component
okay bestie, the Authentication Response Component is where the results of an authentication request live 🦋 it uses the Algorithm from the Authentication Request Component (see section 7.2), which was picked out of the Authentication Request Block (see section 8.4) 💜
depending on which Algorithm got selected, the results land in one of two places ✨ either in a Signature Component that signs the Authentication Response (and maybe other data too), or in the Packaged Content elements inside the Authentication Response Component itself 🫶 here's the definition:
<!ELEMENT AuthResp (PackagedContent*) >
<!ATTLIST AuthResp
ID ID #REQUIRED
AuthenticationId CDATA #REQUIRED
SelectedAlgorithmRef NMTOKEN #REQUIRED
ContentSoftwareId CDATA #IMPLIED >Attributes:
ID: the identifier that uniquely identifies this Authentication Response Component within the IOTP Transaction 🆔AuthenticationId: the Authentication identifier set by the Authenticator, which was included in the Authentication Request Component (see section 7.2). This lets the Authenticator figure out which Authentication is being referred to 🔁SelectedAlgorithmRef: an Element Reference pointing at the Algorithm element that was used to generate the Authentication Response 🎯ContentSoftwareId: see section 14.Glossary. 📚
Content:
PackagedContent: this may contain the response generated by applying the Algorithm selected from the Authentication Request Component (see section 7.2) 💅
for example, for a payment specific scheme, it may contain scheme-specific data. Refer to the scheme-specific supplemental documentation for definitions of its content 📖
7.4 Trading Role Information Request Component
this Trading Component holds a list of Trading Roles (see section 2.1) that you're asking for info about 👀 the result of a Trading Role Request is a set of Organisation Components (see section 7.6), each one describing one of the Trading Roles you asked for 🧁
example usage includes:
- a Merchant asking a Consumer to provide Organisation Components for the Consumer and DelivTo Trading Roles 🛍️
- a Consumer asking a Merchant for info about the Payment Handlers and Delivery Handlers that the Merchant uses 💖
here's the definition:
<!ELEMENT TradingRoleInfoReq EMPTY>
<!ATTLIST TradingRoleInfoReq
ID ID #REQUIRED
TradingRoleList NMTOKENS #REQUIRED >Attributes:
ID: the identifier that uniquely identifies this Trading Role Information Request Component within the IOTP Transaction 🆔TradingRoleList: a list of one or more Trading Roles (see the TradingRole attribute of the Trading Role Element, section 7.6.2) that info is being requested for 🌈
7.5 Order Component
an Order Component holds info about an order 🛒✨ here's the definition:
<!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: the identifier that uniquely identifies the Order Component within the IOTP Transaction 🆔xml:lang: sets the language used by attributes or child elements in this component, unless a child element overrides it with its own xml:lang attribute. See section 3.8 Identifying Languages 🗣️OrderIdentifier: a code, reference number or other identifier that the creator of the Order can use to identify the order. It must be unique within an IOTP Transaction. If it's used this way, it may remove the need to specify any content for the Order element, because the reference can be used to look up the necessary info in a database 🗂️ShortDesc: a short description of the order, written in the language set by xml:lang. It helps you pick one order out of a list, like from a database of orders 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 set by xml:lang, that describes the state or country of jurisdiction that will apply when resolving problems or disputes ⚖️ContentSoftwareId: see section 14.Glossary. 📚
Content:
PackagedContent: an optional description of the order info, as one or more Packaged Contents (see section 3.7) 🎀
7.5.1 Order Description Content
the Packaged Content element will normally be required 💅 but it can be left out if the ShortDesc attribute can give enough info about the purchase. If the full Order Description needs it, you can use several Packaged Content elements 📦
the amount and currency will probably show up in the Packaged Content of the Order Description too 👀 BUT the amount and currency in the payment related trading components (Brand List, Brand Selection and Payment) are the ones that count as authoritative 👑 so it's super important that the amount actually being paid (as in the payment related trading components) gets prominently displayed to the Consumer 💸
for interoperability, implementations must support Plain Text, HTML and XML as a minimum so that it can be easily displayed 🌸
7.5.2 OkFrom and OkTo Timestamps
note that:
- the OkFrom date may be later than the OkFrom date on the Payment Component (see section 7.9) associated with this order, and 🕰️
- similarly, the OkTo date may be earlier that the OkTo date on the Payment Component (see section 7.9). ⏳
Note: Disclaimer. The following info 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, first frames the terms of the offer on the web page 🛍️ and in order to get the goods or services, the consumer must accept them 🫶
if there's a time-limited offer, it is recommended that merchants tell the consumer and state in the order description, in a way that's clear to the consumer, that:
- the offer is time limited ⏳
- the OkFrom and OkTo timestamps specify the validity of the offer 📅
- the clock (for example, the merchant's clock) that will be used to determine the validity of the offer 🕐
also, although the OkFrom and OkTo dates will probably show up in the Packaged Content of the Order Description, it's the dates in the Order Component that are authoritative 👑 so it's important that the OkFrom and OkTo dates actually being used get prominently displayed to the Consumer 🌈
7.6 Organisation Component ✨
okay so the Organisation Component is basically the "who's who" 💅 It tells you about an individual or an Organisation, and it's super useful because it can do a bunch of jobs:
- describe the merchant who's selling the goods 🛍️
- identify who made the purchase 🧾
- identify who's going to take delivery of the goods 📦
- give a customer care contact 🫶
- describe who'll be the Payment Handler 💳
Heads up, the Organisation Components that have to show up in an IOTP Message depend on which transaction is happening. Check section 9. Internet Open Trading Protocol Transactions for the details 🔍
Here's the definition:
<!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 that uniquely identifies this Organisation Component within the IOTP Transaction 🆔
- xml:lang: sets the language used by the attributes or child elements in this component, unless a child element overrides it with its own xml:lang attribute. See section 3.8 Identifying Languages 🌍
- OrgId: a code that identifies the Organisation this component describes. See 7.6.1 Organisation IDs, below 🔑
- LegalName: for Organisations that are companies, this is their legal name in the language set 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 set by xml:lang. It's usually the name people actually call the Organisation. For example, if the legal name was "Blue Meadows Financial Services Inc.", its short name would likely be "Blue Meadows" ✨
This one is handy for picking a single Organisation out of a list, like a database of Organisations involved in IOTP Transactions that a consumer has stored 📚
- LogoNetLocn: the net location you can use to download the Organisation's logo 🖼️
See section 10 Retrieving Logos.
The content of this attribute must conform to [RFC1738].
Content:
- TradingRole: see 7.6.2 Trading Role Element below 🎭
- ContactInfo: see 7.6.3 Contact Information Element below 📞
- PersonName: see 7.6.4 Person Name below 🙋
- PostalAddress: see 7.6.5 Postal Address below 🏠
7.6.1 Organisation IDs
Okay bestie, Organisation IDs are how one IOTP Trading Role tells another Trading Role who's who 👀 Because of that, these IDs have to be globally unique, or things get super confusing 💀
Here's how that's pulled off in principle:
- the Organisation Id for every trading role, apart from the Consumer Trading Role, uses a domain name as its globally unique identifier 🌐
- the Organisation Id for a Consumer Trading Role is allocated by one of the other Trading Roles in an IOTP Transaction, and it's made unique by sticking it together with that other role's Organisation Id 🧩
- once a Consumer has been allocated an Organisation Id within an IOTP Transaction, every other trading role in that transaction uses that same Organisation Id to identify the Consumer 🤝
Here's the exact grammar for the Organisation ID:
OrgId ::= NonConsumerOrgId | ConsumerOrgId
NonConsumerOrgId ::= DomainName
ConsumerOrgId ::= ConsumerOrgIdPrefix (namechar)+ "/" NonConsumerOrgId
ConsumerOrgIdPrefix ::= "Consumer:"ConsumerOrgId: the Organisation ID for a Consumer is made of three parts 🎀
- a standard prefix that says the Organisation Id is for a consumer, followed by
- one or more characters that conform to the definition of an XML "namechar". See [XML] specifications, followed by
- the NonConsumerOrgId for the Organisation that allocated the ConsumerOrgId. This is normally the Merchant role.
Upper and lower case don't matter here 🙈
NonConsumerOrgId: if the Role isn't Consumer, this contains the Canonical Name for the non-consumer Organisation being described by the Organisation Component. See [DNS], optionally followed by extra characters, if they're needed to make the NonConsumerOrgId unique.
Note that a NonConsumerOrgId may not start with the ConsumerOrgIdPrefix. Don't mix those up!! 🚫
Upper and lower case don't matter for this one either 💜
Here are some examples of Organisation Ids:
newjerseybooks.com: a merchant Organisation id 📚westernbank.co.uk: a Payment Handler Organisation id 🏦consumer:1000247ABH/newjerseybooks.com: a consumer Organisation id allocated by a merchant 🧑💻
7.6.2 Trading Role Element
This element tells you the Trading Role of an individual or Organisation in the IOTP Transaction 🎭 Quick note: an Organisation can have more than one Trading Role, and several roles can show up in one Organisation element. Here's the definition:
<!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 that uniquely identifies this Trading Role Element within the IOTP Transaction 🆔
- TradingRole: the trading role of the Organisation. The valid values are:
Consumer: the person or Organisation acting as a consumer in the IOTP Transaction 🛒Merchant: the person or Organisation acting as merchant in the IOTP Transaction 🏪PaymentHandler: the financial institution or other Organisation that is a Payment Handler for the IOTP Transaction 💸DeliveryHandler: the person or Organisation that is delivering the goods or services for the IOTP Transaction 🚚DelivTo: the person or Organisation that is receiving the delivery of goods or services in the IOTP Transaction 🎁CustCare: the Organisation and/or individual who will provide customer care for an IOTP Transaction 🫶
Values of TradingRole are controlled under the procedures defined in section 12 IANA Considerations, which also lets people define their own user defined values 🌈
- IotpMsgIdPrefix: contains the prefix that must be used for all IOTP Messages sent by this Trading Role in this IOTP Transaction. The values to use are defined in 3.4.1 IOTP Message ID Attribute Definition 🔤
- CancelNetLocn: the net location the Consumer should go to if they cancel the transaction for some reason. The Trading Role can use it to give a response that fits the situation better 🙅♀️
This attribute:
- must not be present when TradingRole is set to Consumer role or DelivTo,
- must be present when TradingRole is set to Merchant, PaymentHandler or DeliveryHandler.
The content of this attribute depends on the Transport Mechanism. See the Transport Mechanism Supplement 🚛
- ErrorNetLocn: the net location the Consumer should display after they've either received or generated an Error Block containing an Error Component with the Severity attribute set to either:
- HardError,
- Warning, but the Consumer decides not to continue with the transaction,
- TransientError, and the transaction has subsequently timed out.
See section 7.21.1 Error Processing Guidelines for more details 🚨
This attribute:
- must not be present when TradingRole is set to Consumer or DelivTo,
- must be present when TradingRole is set to Merchant, PaymentHandler or DeliveryHandler.
The content of this attribute depends on the Transport Mechanism. See the Transport Mechanism Supplement 🛠️
- ErrorLogNetLocn: optional. This is the net location Consumers should send IOTP Messages to when those messages contain Error Blocks with an Error Component whose Severity attribute is set to either:
- HardError,
- Warning, but the Consumer decides not to continue with the transaction,
- TransientError, and the transaction has subsequently timed out.
This attribute:
- must not be present when TradingRole is set to Consumer role,
- must be present when TradingRole is set to Merchant, PaymentHandler or DeliveryHandler.
The content of this attribute depends on the Transport Mechanism. See the Transport Mechanism Supplement 📮
The ErrorLogNetLocn can be used to send error messages to the software company, or to some other Organisation, that's responsible for fixing problems in the software which sent the incoming message. See section 7.21.1 Error Processing Guidelines for more details 🐛
7.6.3 Contact Information Element 📞
okay so this one is the contact card 💌 for an Organisation or an individual. every attribute is optional ✨ but you need at least ONE bit of contact info in there, bestie. here's the definition:
<!ELEMENT ContactInfo EMPTY >
<!ATTLIST ContactInfo
xml:lang NMTOKEN #IMPLIED
Tel CDATA #IMPLIED
Fax CDATA #IMPLIED
Email CDATA #IMPLIED
NetLocn CDATA #IMPLIED >Attributes:
xml:langtells you which language the attributes in this element are written in. see section 3.8 Identifying Languages 🌍Telis a phone number the Organisation can be reached on. it's a text field, so nothing gets validated 🤷♀️Faxis the same vibe but for a fax number. text field, zero validation 📠Emailis an email address. this one should follow the address conventions in [RFC822] 💌NetLocnis a spot on the Internet where you can find out about the Organisation, and it's viewable in a web browser 🌐 the content must conform to [RFC1738] 🔗
7.6.4 Person Name Element 🧑🎤
this is the name of an individual person 🫶 every field is optional, but at minimum you should have either the GivenName or the FamilyName. the definition goes like this:
<!ELEMENT PersonName EMPTY >
<!ATTLIST PersonName
xml:lang NMTOKEN #IMPLIED
Title CDATA #IMPLIED
GivenName CDATA #IMPLIED
Initials CDATA #IMPLIED
FamilyName CDATA #IMPLIED >Attributes:
xml:langis the language used by the attributes in this element. see section 3.8 Identifying Languages 🌍Titleis a distinctive name or personal appellation, hereditary or not. it shows office (like judge or mayor) or nobility (like duke, duchess or earl), or it's the thing you put in front of someone's name when you're addressing them (like Mr, Mrs or Miss) 👑GivenNameis the main name a person goes by, the one their family, friends and acquaintances know them by. it's also called the first name or Christian Name 💖Initialsare the first letters of the secondary names (so, not the Given Name) that a person is known by amongst their family, friends and acquaintances 🔤FamilyNameis the name shared by a family of related people. it's usually the bit of your name that gets passed down from your parents to their kids 🌳
7.6.5 Postal Address Element 📮
this is an address you can use for physical delivery of goods, services or letters. no cap, it's giving snail mail 💌 here's the definition:
<!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:langis the language used by the attributes in this element. see section 3.8 Identifying Languages 🌍AddressLine1is the first line of the postal address, like"The Meadows"🌸AddressLine2is the second line of the postal address, like"Sandy Lane"🌷CityOrTownis the city or town of the address, like"Carpham"🏘️StateOrRegionis the state or region within a country where the city or town sits, like"Surrey"🗺️PostalCodeis the code that postal organisations use to sort deliveries into efficient sequences. think post code or zip code, like"KT22 1AA"📬Countryis the country for the address, like"UK"🇬🇧LegalLocationtells you whether this address is the Registered Address for the Organisation. at least one address for the Organisation must have this set toTrue, unless the Trading Role is eitherConsumerorDeliverTo🔐
7.7 Brand List Component 🧃
okay this is the fun one ✨ Brand List Components live inside the Trading Protocol Options Block (see section 8.1) of the IOTP Transaction. they hold lists of:
- payment Brands (see also section 11.1 Brand Definitions and Brand Selection),
- amounts to be paid in the currencies that the Merchant accepts or offers,
- the payment protocols that can be used to pay with a Brand, and
- the net locations of the Payment Handlers that accept payment for a payment protocol
here's the definition:
<!ELEMENT BrandList (Brand+, ProtocolAmount+,
CurrencyAmount+, PayProtocol+) >
<!ATTLIST BrandList
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
ShortDesc CDATA #REQUIRED
PayDirection (Debit | Credit) #REQUIRED >Attributes:
IDis an identifier that uniquely identifies this Brand List Component within the IOTP Transaction 🆔xml:langis the language used by the attributes or child elements in this component, unless a child element overrides it with its ownxml:langattribute. see section 3.8 Identifying Languages 🌍ShortDescis a text description, written in the language set byxml:Lang, that explains what the Brand List is for. this must be displayed to the receiver of the Brand List so they can pick a Brand 👀 it's super helpful for a Consumer who needs to tell apart the Brand Lists when a transaction involves more than one payment 🧠PayDirectionsays which way the payment for the selected Brand is going. it can be:Debit: the sender of the Payment Request Block (e.g., the Consumer) that this Brand List relates to will pay the Payment Handler, orCredit: the sender of the Payment Request Block that this Brand List relates to will receive a payment from the Payment Handler 💸
Content:
Branddescribes a Brand. the order of the Brand elements (see section 7.7.1) in the Brand List doesn't mean anything preference-wise. it's recommended that software processing the Brand List shows the Brands in whatever order the receiver prefers ✨ProtocolAmountlinks a particular Brand to:- the currencies and amounts in
CurrencyAmountelements that can be used with that Brand, and - the Payment Protocols and Payment Handlers that can be used with those currencies and amounts, and that particular Brand 🎀
- the currencies and amounts in
CurrencyAmountholds a currency code and an amount 💰PayProtocolholds info about a Payment Protocol and the Payment Handler that can be used with a particular Brand 🔥
the relationships between the elements in the Brand List content are shown in the diagram below. it's a lot, but it's iconic 💅
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 Relationshipsexamples of complete Brand Lists are in section 11.2 Brand List Examples 🧁
7.7.1 Brand Element 🎀
Okay so a Brand Element describes a brand a Consumer can use to make a payment 💳. You get one or more of these in every Brand List Component that has the PayDirection attribute set to Debit. For Credit, exactly one Brand Element may be carried in the Brand List Component. 🦋
<!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: the element identifier. It can be referenced from a Brand Selection Component in a later Payment Request message, and it uniquely identifies the Brand element within the IOTP Transaction 🔑xml:lang: defines the language used by the attributes and content of this element. See section 3.8 Identifying Languages. 🌸BrandId: a unique identifier for the brand (or promotional brand). It gets matched against the list of Payment Instruments the Consumer holds, which is how it's decided whether or not the Consumer can pay using the Brand. 💅- Values of
BrandIdare managed under the procedure described in section 12 IANA Considerations. - Because values of
BrandIdare controlled under the procedures defined in section 12 IANA Considerations, user defined values may be defined. ✨
- Values of
BrandName: the name of the brand, for example MasterCard Credit. This is the description displayed to the Consumer in the language set byxml: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 that 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 for the Merchant to show any special conditions or benefits that would apply if the Consumer selected that brand. Examples include "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 that can be used with this Brand. It's 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 that the payment protocol may use. The content of this information is defined in the supplement for a payment protocol, which describes how that payment protocol works with IOTP. 🔥
Example Brand Elements are contained in section 11.2 Brand List Examples. 🙈
7.7.2 Protocol Brand Element 🌸
The Protocol Brand Element holds information that's specific to using one particular Protocol with a Brand. Here's how it's defined 🧚
<!ELEMENT ProtocolBrand (PackagedContent*) >
<!ATTLIST ProtocolBrand
ProtocolId CDATA #REQUIRED
ProtocolBrandId CDATA #REQUIRED >Attributes:
ProtocolId: this must match the value of aProtocolIdattribute in a Pay Protocol Element (see section 7.7.5). 💖- The values of
ProtocolIdshould be unique within a Brand Element. Otherwise there is an error. ⚠️
- The values of
ProtocolBrandId: the Payment Brand Id to be used with a particular payment protocol. For example, SET and EMV each have their own well defined, yet different, values for the Brand Id they use. 🦋- The valid values of this attribute are defined in the supplement for the payment protocol identified by
ProtocolId, which describes how that payment protocol works with IOTP.
- The valid values of this attribute are defined in the supplement for the payment protocol identified by
Content:
PackagedContent: optional Packaged Content (see section 3.7) elements containing information about the protocol/brand that the payment protocol may use. The content of this information is defined in the supplement for a payment protocol, which describes how that payment protocol works with IOTP. ✨
7.7.3 Protocol Amount Element 🪄
The Protocol Amount element links a Brand to two things 👑
- the currencies and amounts in Currency Amount Elements (see section 7.7.4) that can be used with the Brand, and
- the Payment Protocols and Payment Handlers defined in a Pay Protocol Element (see section 7.7.5), which can be used with those currencies and amounts.
Its definition is as follows:
<!ELEMENT ProtocolAmount (PackagedContent*) >
<!ATTLIST ProtocolAmount
ID ID #REQUIRED
PayProtocolRef IDREF #REQUIRED
CurrencyAmountRefs IDREFS #REQUIRED
ContentSoftwareId CDATA #IMPLIED >Attributes:
ID: the element identifier. It can be referenced from a Brand element, or from a Brand Selection Component in a later Payment Request message, and it uniquely identifies the Protocol Amount element within the IOTP Transaction. 🔑PayProtocolRef: contains an Element Reference (see section 3.5) pointing at the Pay Protocol Element (see section 7.7.5) that holds the Payment Protocol and Payment Handlers that can be used with the Brand. 🌈CurrencyAmountRefs: a list of Element References (see section 3.5) pointing at the Currency Amount Elements (see section 7.7.4) that describe 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 that the payment protocol may use. The content of this information is defined in the supplement for a payment protocol, which describes how that payment protocol works with IOTP. 🧚
Examples of Protocol Amount Elements are contained in section 11.2 Brand List Examples. 🫶
7.7.4 Currency Amount Element 💅
A Currency Amount element contains two things 💰
- a currency code (and its type), and
- an amount.
One or more of these elements is carried in each Brand List Component. Its definition is as follows:
<!ELEMENT CurrencyAmount EMPTY >
<!ATTLIST CurrencyAmount
ID ID #REQUIRED
Amount CDATA #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED >Attributes:
ID: the element identifier. It can be referenced from a Brand element, or from a Brand Selection Component in a later Payment Request message, and it 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 as "245.35". Values smaller than the smallest denomination are allowed. For example, one tenth of a cent would be "0.001". 💖CurrCodeType: indicates the domain of theCurrCode. This attribute is included so that the currency code can support non-standard "currencies" such as frequent flyer points, trading stamps, etc. Its values may be: 🪙ISO4217-A(the default) indicates the currency code is a three character alphabetic currency code that conforms to [ISO 4217]IOTPindicates that values ofCurrCodeare managed under the procedure described in section 12 IANA Considerations
CurrCode: a code that identifies the currency to be used in the payment. The domain of valid currency codes is defined byCurrCodeType.- As values of
CurrCodeTypeare managed under the procedure described in section 12 IANA Considerations, user defined values ofCurrCodeTypemay be defined. 🦄
- As values of
Examples of Currency Amount Elements are contained in section 11.2 Brand List Examples. 🎀
7.7.5 Pay Protocol Element ✨
okay so the Pay Protocol element is where you spell out a Payment Protocol and the Payment Handler that can be used with a Brand 💖 every Brand List carries one or more of these, no cap 🎀
<!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🆔 is the element identifier. It can be referenced in a Brand element, or in a Brand Selection Component that's sitting inside a later Payment Request message. Either way, it uniquely identifies this Pay Protocol element within the IOTP Transaction.xml:lang🌍 sets the language used by the attributes and content of this element. See section 3.8 Identifying Languages.ProtocolId🔖 is a protocol name and version put together, like "SETv1.0". The payment scheme or method owners define the values ofProtocolId, in the document that explains how to wrap a payment protocol up inside IOTP.ProtocolName📝 is a narrative description of the payment protocol and its version, written in the language named byxml:lang. For example, "Secure Electronic Transaction Version 1.0". Its whole job is to help people figure out which payment protocol is being used if things go sideways 😭ActionOrgRef🏦 is an Element Reference (see section 3.5) pointing at the Organisation Component for the Payment Handler of this Payment Protocol.PayReqNetLocn📮 is the Net Location where an unsecured Payment Request message should be sent if this protocol choice gets picked. What goes in here depends on the Transport Mechanism (such must conform to [RFC1738].SecPayReqNetLocn🔐 is the Net Location where a secured Payment Request message should be sent if this protocol choice gets picked. A secured payment uses a secure channel, such as [SSL/TLS], to talk to 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🎁 is optional. These Packaged Content elements (see section 3.7) hold information about the protocol that the payment protocol uses. The details of that information are defined in the supplement for the payment protocol, which explains how the payment protocol works with IOTP. An example of how it could be used is including a payment protocol message 🧚
Examples of Pay Protocol Elements are in section 11.2 Brand List Examples 🌸
7.8 Brand Selection Component 💅
okay so a Brand Selection Component picks out the payment brand, the payment protocol, and the Payment Handler 🎀 it gets used:
- in Payment Request messages inside Baseline Purchase and Baseline Value Exchange IOTP Transactions, to identify the brand, protocol and payment handler for a payment, or
- to, optionally, tell a merchant during a purchase which payment brand is being used, so the offer and order details can get amended to match 🛍️
In Baseline IOTP, the integrity of Brand Selection Components is not guaranteed 🙈 BUT modifying them can only cause denial of service if the payment protocol itself is secure against message modification, duplication, and swapping attacks. So that's the safety net 🫶
The definition of a Brand Selection Component looks like this:
<!ELEMENT BrandSelection (BrandSelBrandInfo?,
BrandSelProtocolAmountInfo?,
BrandSelCurrencyAmountInfo?) >
<!ATTLIST BrandSelection
ID ID #REQUIRED
BrandListRef NMTOKEN #REQUIRED
BrandRef NMTOKEN #REQUIRED
ProtocolAmountRef NMTOKEN #REQUIRED
CurrencyAmountRef NMTOKEN #REQUIRED >Attributes:
ID🆔 is an identifier that uniquely identifies the Brand Selection Component within the IOTP Transaction.BrandListRef📋 is the Element Reference (see section 3.5) of the Brand List Component that a Brand is being selected from.BrandRef🏷️ is the Element Reference of a Brand element inside the Brand List Component being selected from. It's the Brand that gets used in the payment.ProtocolAmountRef💳 is the Element Reference of a Protocol Amount element inside the Brand List Component, the one that's going to be used when making the payment.CurrencyAmountRef💵 is the Element Reference of a Currency Amount element inside the Brand List Component, the one that's going 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 📜
- the
BrandListRefmust contain the ID of a Brand List Component in the same IOTP Transaction - every Brand List Component in the Trading Protocol Options Block (see section 8.1) must be referenced by one and only one Brand Selection Component
- the
BrandRefmust refer to the ID of a Brand contained within the Brand List Component referred to byBrandListRef - the
ProtocolAmountRefmust refer to one of the Element IDs listed in theProtocolAmountRefsattribute of the Brand element identified byBrandRef - the
CurrencyAmountRefmust refer to one of the Element IDs listed in theCurrencyAmountRefsattribute of the Protocol Amount Element identified byProtocolAmountRef.
An example of a Brand Selection Component is included in 11.2 Brand List Examples 🌈
7.8.1 Brand Selection Brand Info Element 🎀
The Brand Selection Brand Info Element holds any extra data that a particular payment brand might need 💖 check the IOTP payment method supplement to see how and when it gets used.
<!ELEMENT BrandSelBrandInfo (PackagedContent+) >
<!ATTLIST BrandSelBrandInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >Attributes:
ContentSoftwareId💾 See section 14. Glossary.
Content:
PackagedContent🎁 are Packaged Content elements (see section 3.7) holding extra data that a particular payment brand may need. The payment method supplement for IOTP has the rules for how this is used.
7.8.2 Brand Selection Protocol Amount Info Element 🦋
The Brand Selection Protocol Amount Info Element holds any extra data that's specific to the payment protocol, which a particular payment brand or payment protocol might need. Again, the IOTP payment method supplement explains how and when it gets used 📖
<!ELEMENT BrandSelProtocolAmountInfo (PackagedContent+) >
<!ATTLIST BrandSelProtocolAmountInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >Attributes:
ContentSoftwareId💾 See section 14. Glossary.
Content:
PackagedContent🎁 are Packaged Content elements (see section 3.7) that may contain extra data that a particular payment brand may need. The payment method supplement for IOTP has the rules for how this is used.
7.8.3 Brand Selection Currency Amount Info Element 💵
The Brand Selection Currency Amount Info Element holds any extra data that's specific to both the payment brand and the currency, which a particular payment brand might need 🌷 see the IOTP payment method supplement for how and when it gets used.
<!ELEMENT BrandSelCurrencyAmountInfo (PackagedContent+) >
<!ATTLIST BrandSelCurrencyAmountInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >Attributes:
ContentSoftwareId💾 See section 14. Glossary.
Content:
PackagedContent🎁 are Packaged Content elements (see section 3.7) holding extra data about the payment brand and currency. The payment method supplement for IOTP has the rules for how this is used.
7.9 Payment Component 💸
okay so a Payment Component holds the info that controls how a payment gets carried out 🧚 it gives you the details on:
- the times within which a Payment with a Payment Handler may be started
- a reference to the Brand List (see section 7.7), which lists the Brands, protocols, currencies and amounts that can be used to make a payment
- whether or not a payment receipt will be provided
- whether another payment comes before this payment
Here's the definition 👑
<!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🆔 is an identifier that uniquely identifies the Payment Component within the IOTP Transaction.OkFrom🕐 is the date and time in [UTC] format after which a Payment Handler may accept a Payment Request Block (see section 8.7) containing the Payment Component for processing.OkTo🕓 is the date and time in [UTC] format before which a Payment Handler may accept a Payment Request Block containing the Payment Component for processing.BrandListRef📋 is 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 lays out the alternative ways 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 that describe payments which must be complete before this payment can start. If noStartAfterattribute is present, there are no dependencies and the payment can start immediately ✨
7.10 Payment Scheme Component ✨
okay so the Payment Scheme Component is where the actual payment protocol stuff lives 💳 It carries the info for one specific payment scheme between the parties in a payment, like a [SET] message 🎀 Here's how it's defined:
<!ELEMENT PaySchemeData (PackagedContent+) >
<!ATTLIST PaySchemeData
ID ID #REQUIRED
PaymentRef NMTOKEN #IMPLIED
ConsumerPaymentId CDATA #IMPLIED
PaymentHandlerPayId CDATA #IMPLIED
ContentSoftwareId CDATA #IMPLIED >Attributes:
ID🆔 This is the identifier that uniquely identifies the Payment Scheme Component within the IOTP Transaction. It's the component's main-character tag, so it has to be unique 👑PaymentRef🔗 This is an Element Reference (see section 3.5) pointing at the Payment Component (see section 7.9) that this Payment Scheme Component relates to. It's required unless the Payment Scheme Component is part of a Transaction Inquiry Status Transaction (see section 9.2.1). So noPaymentRef, no party, unless it's an inquiry status one 🙈ConsumerPaymentId🛍️ This is an identifier the Consumer specifies. If the Payment Handler sends it back in another Payment Scheme Component, or somehow by other means, the Consumer can figure out which payment is being talked about. Iconic recall energy 🧠PaymentHandlerPayId🏦 This one's an identifier the Payment Handler specifies. If the Consumer returns it in another Payment Scheme Component, or by other means, the Payment Handler can tell which payment is meant. It's required on every Payment Scheme Component apart from the one contained in a Payment Request Block 💅ContentSoftwareId🧩 See section 14. Glossary.
Content:
PackagedContent📦 This holds the payment scheme protocol info as Packaged Content elements (see section 3.7). For the definition of what goes inside, check the payment scheme supplement 📚
Note that:
- the values of the Name attribute of each packaged content element are defined by the Payment Protocol Supplement
- the value of each Name must be unique within a Payment, where a Payment is defined as all Payment Scheme or Payment Receipt Components with the same value of the PaymentRef attribute 🌸
7.11 Payment Receipt Component
okay this one's the receipt 🧾 A Payment Receipt is a record of a payment that shows how much money has been paid or received. It's different from a purchase receipt because it has zero record of what was actually bought. Private shopping, no cap 🫣
Typically, a Payment Receipt Component's content will describe:
- the amount paid and its currency 💰
- the date and time of the payment 🕰️
- internal reference numbers that identify the payment to the payment system 🔢
- potentially digital signatures made by the payment method, which can be used to prove after the fact that the payment happened ✍️
If the Payment Method being used provides the facility, then the Payment Receipt Component should contain payment protocol messages, or references to messages, that prove the payment occurred 🦋
The exact definition of the content depends on the Payment Method. Check the supplement for the payment method being used to find out which rules apply 📖
Information 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 those Messages will need to be processed by Payment Method software to convert them into a format the Consumer can actually understand 🙏
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 that 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) that this payment receipt applies to. It's required, so don't skip it 🫶PayReceiptNameRefs📝 Optionally contains a list of the values of the Name attributes of Packaged Content elements that together make up the receipt. Those Packaged Content elements are contained either within:- Payment Scheme Data components exchanged between the Payment Handler and the Consumer roles during the Payment, and/or
- the Payment Receipt component itself.
Note that:
- each payment scheme defines, in its supplement, the Names of the Packaged Content elements that must be listed in this attribute (if any) 🗂️
- if a Payment Scheme Component contains Packaged Content elements with a name matching a name within PayReceiptNameRefs, then those Payment Scheme Components must be referenced by Digests in the Payment Response signature component (if such a signature is being used) 🔏
The client software should save all the components referenced so the payment receipt can be rebuilt when needed 💾
ContentSoftwareId🧩 See section 14. Glossary.
Content:
PackagedContent🎁 Optionally contains payment scheme payment receipt info as Packaged Content elements (see section 3.7). Check the payment scheme supplement for the definition of its content 📚
Note that:
- the values of the Name attribute of each packaged content element are defined by the Payment Protocol Supplement
- the value of each Name must be unique within a Payment, where a Payment is defined as all Payment Scheme or Payment Receipt Components with the same value of the PaymentRef attribute 🌈
Note that either the PayReceiptNameRefs attribute, the PackagedContent element, or both must be present. Don't forget at least one of them! ⭐
7.12 Payment Note Component
the Payment Note Component is the extra, non-payment stuff the Payment Handler wants to tell the Consumer 📝 Like, if a withdrawal or deposit happened, it could include the remaining balance on the account after the transfer. The info should duplicate what's already in the Payment Receipt Component 🔁
Information 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 "Plain Text", HTML and XML 🌸 Here's its definition:
<!ELEMENT PaymentNote (PackagedContent+) >
<!ATTLIST PaymentNote
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >Attributes:
ID🆔 An identifier that uniquely identifies the Payment Receipt Component within the IOTP Transaction. (Yes, the original says Payment Receipt Component here, so that's what we're keeping 🙈)ContentSoftwareId🧩 See section 14. Glossary.
Content:
PackagedContent💌 Contains additional, non-payment-related info the Payment Handler wants to give the Consumer, as one or more Packaged Content elements (see section 3.7) 🧚
7.13 Delivery Component
the Delivery Element holds the info needed to deliver goods or services 🚚 Here's the definition:
<!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 that 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 anxml:langattribute on a child element. See section 3.8 Identifying Languages 💬DelivExch🚪 Indicates whether this IOTP Transaction includes the messages associated with a Delivery Exchange. Valid values are:True✅ indicates it does include a Delivery ExchangeFalse❌ indicates it does not include a Delivery Exchange
If set to true, then a DeliveryData element must be present. If set to false, it may be absent 🫠
DelivAndPayResp🎀 Indicates whether 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:True✨ indicates both blocks will be in the same IOTP Message, andFalse🌙 indicates each block will be in a different IOTP Message
DelivAndPayResp should not be true if DelivExch is False 🙅♀️
Realistically, 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:
- the Payment Handler must have access to Order Component information so they know what to deliver, and
- the Payment Handler must be able to carry out the delivery 🚀
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 that the Delivery Handler needs, as one or more Packaged Content Elements (see section 3.7) 💖
7.13.1 Delivery Data Element ✨
okay so the DeliveryData element is basically where the goods are going and how they're getting there 🚚 its definition is below:
<!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:langdefines the language used by attributes within this component. See section 3.8 Identifying Languages. 🌍OkFromis the date and time in [UTC] format after which the Delivery Handler may accept a Delivery Request Block for processing (see section 8.10). 🕰️OkTois the date and time in [UTC] format before which the Delivery Handler may accept a Delivery Request Block for processing. ⏳DelivMethodtells you how the goods or services can be delivered. The valid values are:Post: the goods will be delivered by post or courier 📮Web: the goods will be delivered electronically in the Delivery Note Component 💻Email: the goods will be delivered electronically by e-mail 📧
The values of DelivMethod are managed under the procedure in section 12 IANA Considerations, which lets people define their own codes. 🧁
DelivToRefis the Element Reference (see section 3.4) of an Organisation Component inside the IOTP Transaction that has the role of DelivTo. This is the info used to figure out where the delivery goes, and it must be compatible withDelivMethod. Specifically:- If the
DelivMethodisPost, then there must be a Postal Address Element with enough info for a postal delivery 📬 - If the
DelivMethodisWeb, there are no specific requirements. The info gets sent in a web page back to the Consumer 🌸 - If the
DelivMethodisEmail, there must be a Contact Information Element with a valid e-mail address 💌
- If the
DelivReqNetLocnis the Net Location that an unsecured Delivery Request Block (see section 8.10) containing the Delivery Component should be sent to. 🛣️
The content of this attribute depends on the Transport Mechanism and must conform to [RFC1738].
SecDelivReqNetLocnis the Net Location that a secured Delivery Request Block (see section 8.10) containing the Delivery Component should be sent to. 🔐
A secured delivery request uses a secure channel such as [SSL/TLS] to talk to the Payment Handler.
The content of this attribute depends on the Transport Mechanism and must conform to [RFC1738].
See also Section 3.9 Secure and Insecure Net Locations. 👀
ContentSoftwareIdis explained in section 14. Glossary. 🫶
Content:
PackagedContentis extra info about the delivery, given as one or more Packaged Content elements (see section 3.7), which the merchant provides to the Delivery Handler. 🎁
7.14 Consumer Delivery Data Component 🎀
A Consumer Delivery Data Component is how a Consumer gives an identifier that they can use to recognise the Delivery. 🫧
Its definition is as follows:
<!ELEMENT ConsumerDeliveryData EMPTY >
<!ATTLIST ConsumerDeliveryData
ID ID #REQUIRED
ConsumerDeliveryId CDATA #REQUIRED>Attributes:
IDis an identifier that uniquely identifies the Consumer Delivery Data Component within the IOTP Transaction. 🆔ConsumerDeliveryIdis an identifier the Consumer picks. If the Delivery Handler sends it back, the Consumer can tell which Delivery is being talked about. 📦✨
7.15 Delivery Note Component 📝
A Delivery Note holds delivery instructions about the goods or services, or sometimes the actual Delivery Information itself. 💅 It's info the person or Organisation receiving the Delivery Note can use when the delivery happens. 🚪
For interoperability, the Delivery Note Component's Packaged Content should support Plain Text, HTML and XML. 🌈
Its definition is as follows.
<!ELEMENT DeliveryNote (PackagedContent+) >
<!ATTLIST DeliveryNote
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
DelivHandlerDelivId CDATA #IMPLIED
ContentSoftwareId CDATA #IMPLIED >Attributes:
IDis an identifier that uniquely identifies the Delivery Note Component within the IOTP Transaction. 🔑xml:langdefines the language used by attributes or child elements within this component, unless a child element overrides it with its ownxml:langattribute. See section 3.8 Identifying Languages. 🗣️DelivHandlerDelivIdis an optional identifier set by the Delivery Handler. If the Consumer sends it back in another Delivery Component, or it gets passed along some other way, the Delivery Handler can tell which Delivery is being referred to. It is required on every Delivery Component apart from the one inside a Delivery Request Block. 🕵️
An example use of this attribute is a delivery tracking number. 🚚💨
ContentSoftwareIdis explained in section 14. Glossary. 🫧
Content:
PackagedContentholds the 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 that causes the actual delivery to occur. 🚨
7.16 Status Component ✨
okay bestie, the Status Component is where you find out how a process went: did it slay 💅, did it flop 💀, or is it still cooking 🍳. It's all about the business success or failure (see section 4.2) of a process. 🦋
Here's the official definition, no cap:
<!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 that 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 eitherOffer,Payment,Delivery,AuthenticationorUndefined. 📦
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 toUndefined, 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:- an Order Component (see section 7.5), if the StatusType is
Offer, - a Payment Component (see section 7.9), if the StatusType is
Payment, or - a Delivery Component (see section 7.13), if the StatusType is
Delivery - an Authentication Request Component (see section 7.2) if the StatusType is
Authentication.
- an Order Component (see section 7.5), if the StatusType is
ProcessState: contains a State Code which indicates the current state of the process being carried out. Valid values for ProcessState are:NotYetStarted. A Request Block has been received but the process has not yet started. 🌱InProgress. Processing of the Request Block has started but it is not yet complete. ⏳CompletedOk. The processing of the Request Block has completed successfully without any errors. 👑Failed. The processing of the Request Block has failed because of a Business Error (see section 4.2). 💔ProcessError. This value is only used when the Status Component is being used in connection with an Inquiry Request Trading Block (see section 8.12). It indicates there was a Technical Error (see section 4.1) in the Request Block which is being processed, or some internal processing error. 🙈
Note that this code reports on the processing of a Request Block. Further, asynchronous processing may occur after the Response Block associated with the Process has been sent. ✨
CompletionCode: indicates how the process completed. Valid values for the CompletionCode are given below, together with the conditions when it must be present and indications on when recovery from failures are possible. 🧩
A CompletionCode is a maximum of 14 characters long.
ProcessReference: this optional attribute holds a reference for the process whose status is being reported. It may hold the following values:- when StatusType is set to
Offer, it should contain the OrderIdentifier from the Order Component - when StatusType is set to
Payment, it should contain the PaymentHandlerPayId from the Payment Scheme Data Component - when StatusType is set to
Delivery, it should contain the DelivHandlerDelivId from the Delivery Note Component - when StatusType is set to
Authentication, it should contain the AuthenticationId from the Authentication Request Component
- when StatusType is set to
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 byxml:lang. 💬
7.16.1 Offer Completion Codes 🎟️
The Completion Code is only required if the ProcessState attribute is set to Failed. The following table contains the valid values for the CompletionCode that may be used, and indicates whether or not recovery might be possible. It is recommended that the StatusDesc attribute is used to provide further explanation where appropriate. 🌸
Value Description
AuthError Authentication Error. The check of the
Authentication Response which was carried out has
failed.
Recovery may be possible by the Consumer re-
submitting a new Authentication Response Block with
corrected information.
ConsCancelled Consumer Cancelled. The Consumer decides to cancel
the transaction for some reason. This code is only
valid in a Status Component contained in a Cancel
Block or an Inquiry Response Block.
No recovery possible.
MerchCancelled Offer Cancelled. The Merchant declines to generate
an offer for some reason and cancels the
transaction. This code is only valid in a Status
Component contained in a Cancel Block or an Inquiry
Response Block.
No recovery possible.
Unspecified Unspecified error. There is some unknown problem or
error which does not fall into one of the other
CompletionCodes.
No recovery possible.
TimedOutRcvr Recoverable Time Out. Messages were resent but no
response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
Recovery is possible if the last message from the
other Trading Role is received again.
TimedOutNoRcvr Non Recoverable Time Out. Messages were resent but
no response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
No recovery possible.7.16.2 Payment Completion Codes 💳✨
okay so the CompletionCode only matters when the ProcessState is Failed 🫶 this table has all the valid values you can use, and it tells you where recovery might still be possible 🦋 also, the StatusDesc attribute is recommended for individual payment schemes to add extra explanation where it makes sense 💅
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 🌈 the Consumer can pick either a different payment brand or a different payment instrument for the same brand. Heads up, this might involve a different Payment Handler 👀 the codes that this applies to are BrandNotSupp, PaymtCancelled, InsuffFunds, InstBrandInvalid, InstNotValid, BadInstrument and Unspecified 🎀
Recovery from Payments tied to Brand Dependent purchases is only possible if the Brand Selection component the Merchant sent to the Consumer does not change 😭 in practice that means the same Brand, Protocol Amount and PayProtocol elements must be used. Only the Payment Instrument is allowed to change. Any other change will invalidate the Merchant's Offer, because a changed selection will invalidate the Offer Response 🙈
7.16.3 Delivery Completion Codes 🚚🌸
this table is the lineup of valid CompletionCode values for a Delivery 💖 the StatusDesc attribute is recommended for giving extra explanation where it's helpful 🧚
Value Description
BackOrdered Back Ordered. The goods to be delivered are on order
but they have not yet been received. Shipping will be
arranged when they are received. This is only valid
if ProcessState is CompletedOk.
Recovery is not possible.
PermNotAvail Permanently Not Available. The goods are permanently
unavailable and cannot be re-ordered. This is only
valid if ProcessState is Failed.
Recovery is not possible.
TempNotAvail Temporarily Not Available. The goods are temporarily
unavailable and may become available if they can be
ordered. This is only valid if ProcessState is
CompletedOk.
Recovery is not possible.
ShipPending Shipping Pending. The goods are available and are
scheduled for shipping but they have not yet been
shipped. This is only valid if ProcessState is
CompletedOk.
Recovery is not possible.
Shipped Goods Shipped. The goods have been shipped.
Confirmation of delivery is awaited. This is only
valid if ProcessState is CompletedOk.
Recovery is not possible.
ShippedNoConf Shipped - No Delivery Confirmation. The goods have
been shipped but it is not possible to confirm
delivery of the goods. This is only valid if
ProcessState is CompletedOk.
Recovery is not possible.
ConsCancelled Consumer Cancelled. The Consumer decides to cancel
the delivery for some reason. This code is only valid
in a Status Component contained in a Cancel Block or
an Inquiry Response Block.
Recovery is not possible.
DelivCancelled Delivery Cancelled. The Delivery Handler declines to
complete the Delivery for some reason and cancels the
transaction. This code is only valid in a Status
Component contained in a Cancel Block or an Inquiry
Response Block.
Recovery is not possible.
Confirmed Confirmed. All goods have been delivered and
confirmation of their delivery has been received.
This is only valid if ProcessState is CompletedOk.
Recovery is not possible.
Unspecified Unspecified error. There is some unknown problem or
error which does not fall into one of the other
CompletionCodes. The StatusDesc attribute should
provide the explanation of the cause.
Recovery is not possible.
TimedOutRcvr Recoverable Time Out. Messages were resent but no
response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
Recovery is possible if the last message from the
other Trading Role is received again.
TimedOutNoRcvr Non Recoverable Time Out. Messages were resent but no
response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
No recovery possible.Note: Recovery from failed, or partially completed deliveries is not possible. The Consumer should use the Transaction Status Inquiry Transaction (see section 9.2.1) to determine up-to- date information on the current state. 🫶💀
7.16.4 Authentication Completion Codes ✨
okay so the Completion Code only comes into play when the ProcessState attribute is set to Failed 🙈 it's recommended that you use StatusDesc to explain what happened where it makes sense. here's the full list of valid CompletionCode values you can use 💅
Value Description
AutEeCancel Authenticatee Cancel. The Organisation being
authenticated declines to be authenticated for some
reason. This could be, for example because the
signature on an Authentication Request was invalid or
the Authenticator was not known or acceptable to the
Authenticatee.
Recovery is not possible.
AutOrCancel Authenticator Cancel. The Organisation requesting
authentication declines to validate the
Authentication Response received for some reason and
cancels the transaction.
Recovery is not possible.
NoAuthReq Authentication Request Not Available. The
Authenticatee does not have the data that must be
provided so that they may be successfully
authenticated. For example a password may have been
forgotten, the Authenticatee has not yet become a
member, or a smart card token is not present.
Recovery is not possible
AuthFailed Authentication Failed. The Authenticator checked the
Authentication Response but the authentication failed
for some reason. For example a password may have been
incorrect.
Recovery may be possible by the Authenticatee re-
sending a revised Authentication Response with
corrected data.
TradRolesIncon Trading Roles Inconsistent. The Trading Roles
contained within the TradingRoleList attribute of the
Trading Role Information Request Component (see
section 7.4) are inconsistent with the Trading Role
which the Authenticatee is taking in the IOTP
Transaction or is able to take. Examples of
inconsistencies include:
o asking a PaymentHandler for DeliveryHandler
information
o asking a Consumer for Merchant information
Recovery may be possible by the Authenticator re-
sending a revised Authentication Request Block with
corrected information.
Unspecified Unspecified error. There is some unknown problem or
error which does not fall into one of the other
CompletionCodes.
Recovery is not possible.
TimedOutRcvr Recoverable Time Out. Messages were resent but no
response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
Recovery is possible if the last message from the
other Trading Role is received again.
TimedOutNoRcvr Non Recoverable Time Out. Messages were resent but no
response received. The document exchange has
therefore "Timed Out". This code is only valid on a
Transaction Inquiry.
No recovery possible.7.16.5 Undefined Completion Codes 🦋
the Completion Code is only needed if ProcessState is set to Failed, same as before 🌸 it's recommended to use StatusDesc for extra explanation. the only valid value here is:
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
transaction7.16.6 Transaction Inquiry Completion Codes 🧚
same deal again: Completion Code only matters when ProcessState is Failed, and StatusDesc is recommended for the deets ✨ the valid value is:
Value Description
UnAuthReq Unauthorised Request. The recipient of the
Transaction Status Request declines to respond to the
request.7.17 Trading Role Data Component 🎀
okay this one is giving secret messages 🤫 the Trading Role Data Component carries opaque data that the Trading Roles in an IOTP Transaction need to pass between each other. the Trading Role Components keep track of two things:
- the Organisation that generated the component, and
- the Organisation that is supposed to receive it.
they get made first and tucked into a "Response" Block, then copied over to the right "Request" Block 💌 for example, a Payment Handler might need to tell a Delivery Handler that a credit card payment was authorised but not captured. the Payment Handler could also have its own info, in a format it privately agreed on with the Delivery Handler, that needs to go across too. another example: a Merchant might want to give a Payment Handler some specific info about a Consumer so that consumer can rack up double loyalty points with the payment 💅
here's the definition 👑
<!ELEMENT TradingRoleData (PackagedContent+) >
<!ATTLIST TradingRoleData
ID ID #REQUIRED
OriginatorElRef NMTOKEN #REQUIRED
DestinationElRefs NMTOKENS #REQUIRED >Attributes:
ID An identifier which uniquely identifies the
Trading Role Data Component within the IOTP
Transaction.
OrginatorElRef Contains an element reference to the Organisation
Component of the Organisation that created the
Trading Role Data Component and included it in a
"Response" Block (e.g., an Offer Response or a
Payment Response Block).
DestinationElRefs Contains element references to the Organisation
Components of the Organisations that are to
receive the Trading Role Data Component in a
"Request" Block (e.g., either a Payment Request or
a Delivery Request Block).Content:
PackagedContent This contains the data which is to be sent between
the various Trading Roles as one or more
PackagedContent elements see section 3.7.7.17.1 Who Receives a Trading Role Data Component 📬
so here's the rulebook for what to do with these components 📖
- whenever a Trading Role Data Component shows up in a "Response" block, look at the DestinationElRefs attribute and identify the Organisation Components of the Organisations that are meant to receive it.
- whenever a "Request" Block is being sent, check if it's going to one of the Organisations listed in DestinationElRefs. if it is, include in that "Request" block:
- the Trading Role Data Component, and
- the Organisation Component of the Organisation named in the OriginatorElRef attribute (if it's not already there) 🫶
7.18 Inquiry Type Component 🔍
this one tells you what kind of process is being asked about ✨ here's how it's defined:
<!ELEMENT InquiryType EMPTY >
<!ATTLIST InquiryType
ID ID #REQUIRED
Type NMTOKEN #REQUIRED
ElRef NMTOKEN #IMPLIED
ProcessReference CDATA #IMPLIED >Attributes:
ID An identifier which uniquely identifies the
Inquiry Type Component within the IOTP
Transaction.
Type Contains the type of inquiry. Valid values for
Type are:
o Offer. The inquiry is about the status of an
offer and is addressed to the Merchant.
o Payment. The inquiry is about the status of a
payment and is addressed to the Payment
Handler.
o Delivery. The inquiry is about the status of a
delivery and addressed to the Delivery Handler.
ElRef Contains an Element Reference (see section 3.5) to
the component to which this Inquiry Type Component
applies. That is,
o TPO Block when Type is Offer
o Payment Component when Type is Payment
o Delivery Component when Type is Delivery
ProcessReference Optionally contains a reference to the process
being inquired upon. It should be set if the
information is available. For the definition of
the values it may contain, see the
ProcessReference attribute of the Status Component
(see section 7.16).7.19 Signature Component ✍️
note: the XML structures for signatures and certificates are described in the document "Digital Signatures for the Internet Open Trading Protocol" by Kent Davidson and Yoshiaki Kawatsura, which was published at the same time as this one - see [IOTPDSIG].
future IOTP versions are expected to adopt whatever method for digitally signing XML becomes the standard 🌈
each Signature Component digitally signs one or more Blocks or Components, and that includes other Signature Components too 💜 here's what it does:
- it contains digests of one or more Blocks or Components in one or more IOTP Messages within the same IOTP Transaction, and puts the result in a Digest Element
- it concatenates those Digest elements with other info about the type of signature, the originator and potential recipients of the signature, and the signature algorithms being used, and puts them in a Manifest element
- it signs the Manifest element using the optional certificate named in the Certificate element within the Signature Block, and puts the result in a Value element within a Signature Component
note that there can be multiple Value elements holding signatures of a Manifest Element 🫧
a Signature Component can be one of four types:
- an Offer Response Signature,
- a Payment Response Signature,
- a Delivery Response Signature, or
- an Authentication Response Signature.
for a general explanation of signatures, see section 6 Digital Signatures 🔐
7.19.1 IOTP usage of signature elements and attributes ✨
okay so the actual definitions of these elements and attributes live over in [IOTPDSIG] 🤓 this part is the extra info on how IOTP actually uses them 💅
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 whole purpose is to shrink the LocatorHREF values 🧚 since the first part of those attributes in the same signature is probably going to be the same every time.
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 whether it is to be used as a Digest algorithm, a Signature algorithm or a Key Agreement algorithm.
The following Digest algorithms must be implemented:
- a [DOM-HASH] algorithm. This is identified by setting the
Nameattribute of the Algorithm element tourn:ibm:dom-hash - a [SHA1] algorithm. This is identified by setting the
Nameattribute of the Algorithm element tourn:fips:sha1, and - a [MD5] algorithm. This is identified by setting the
Nameattribute of the Algorithm element tourn:rsa:md5 - The following Signature algorithms must be implemented:
- a [DSA] algorithm. This is identified by setting the
Nameattribute of the Algorithm element tourn:us.gov:dsa - a [HMAC] algorithm. This is identified by setting the
Nameattribute of the Algorithm element tourn:ibm:hmac
It is recommended that the following Signature algorithm is also implemented:
- a [RSA] algorithm. This is identified by setting the
Nameattribute of the Algorithm element tourn:rsa:rsa
In addition, other payment scheme specific algorithms may be used. In this case, the value of the name attribute to use is specified in the payment scheme supplement for that algorithm.
One algorithm may make use of other algorithms by using 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:
- the value of the
IotpTransIdattribute of the Transaction ID Component, followed by: - a sharp character, i.e. "#", followed by
- an Element Reference (see section 3.5) to the element within the IOTP Transaction which is the subject of the digest.
Before analysing the structure of the LocatorHREF attribute, it must be concatenated with the value of the LocatorHrefBase attribute of the Manifest element (see immediately above).
ATTRIBUTE ELEMENT
There must be one and only one Attribute Element that contains a Type attribute with a value of IOTP Signature Type and with content set to either OfferResponse, PaymentResponse, DeliveryResponse, AuthenticationRequest, AuthenticationResponse, PingRequest or PingResponse, depending on the type of the signature.
Values of the content of the Attribute element are controlled under the procedures defined in section 12 IANA Considerations, which also allows user defined values to be defined.
The Critical attribute must be set to true.
ORIGINATORINFO ELEMENT
The OriginatorRef attribute of the OriginatorInfo element must always be present and contain an Element Reference (see section 3.5) to the Organisation Component of the Organisation that generated the Signature Component.
RECIPIENTINFO ELEMENT
The RecipientRefs attribute contains a list of Element References (see section 3.5) that point to the Organisations that might need to validate the signature. For details, see below.
7.19.2 Offer Response Signature Component 💌
The Manifest Element of a signature which has a type of OfferResponse should contain Digest elements for the following Components:
- the Transaction Id Component (see section 3.3.1) of the IOTP message that contains the Offer Response Signature
- the Transaction Reference Block (see section 3.3) of the IOTP Message that contains the Offer Response Signature
- from the TPO Block:
- the Protocol Options Component
- each of the Organisation Components
- each of the Brand List Components
- optionally, all the Brand Selection Components if they were sent to the Merchant in a TPO Selection Block
- from the Offer Response Block:
- the Order Component
- each of the Payment Components
- the Delivery Component
- each of the Authentication Request Components
- any Trading Role Data Components
The Offer Response Signature should also contain Digest elements for the components that describe each of the Organisations that may or will need to verify the signature. This involves:
- if the Merchant has received a TPO Selection Block containing Brand Selection Components, then generate a Digest element for the Payment Handler identified by the Brand Selection Component and the Delivery Handler identified by the Delivery Component. See section 6.3.1 Check Request Block sent Correct Organisation for a description of how this can be done.
- if the Merchant is not expecting to receive a TPO Selection Block, then generate a Digest element for the Delivery Handler and all the Payment Handlers that are involved.
7.19.3 Payment Receipt Signature Component 🧾
The Manifest Element of the Payment Receipt Signature Component should contain Digest Elements for the following Components:
- the Transaction Id Component (see section 3.3.1) of the IOTP message that contains the Payment Receipt Signature
- the Transaction Reference Block (see section 3.3) of the IOTP Message that contains the Payment Receipt Signature
- the Offer Response Signature Component
- the Payment Receipt Component
- the Payment Note Component
- the Status Component
- the Brand Selection Component.
- any Trading Role Data Components
7.19.4 Delivery Response Signature Component 📦
The Manifest Element of the Delivery Response Signature Component should contain Digest Elements for the following Components:
- the Transaction Id Component (see section 3.3.1) of the IOTP message that contains the Delivery Response Signature
- the Transaction Reference Block (see section 3.3) of the IOTP Message that contains the Delivery Response Signature
- the Consumer Delivery Data component contained in the preceding Delivery Request (if any)
- the Signature Components contained in the preceding Delivery Request (if any)
- the Status Component
- the Delivery Note Component
7.19.5 Authentication Request Signature Component 🔐
The Manifest Element of the Authentication Request Signature Component should contain Digest Elements for the following Components:
- the Transaction Reference Block (see section 3.3) for the IOTP Message that contains information that describes the IOTP Message and IOTP Transaction
- the Transaction Id Component (see section 3.3.1) which globally uniquely identifies the IOTP Transaction
- the following components of the TPO Block:
- the Protocol Options Component
- the Organisation Component
- the following components of the Authentication Request Block:
- the Authentication Request Component(s) (if present)
- the Trading Role Information Request Component (if present)
7.19.6 Authentication Response Signature Component 🔓
The Manifest Element of the Authentication Response Signature Component should contain Digest Elements for the following Components:
- the Transaction Reference Block (see section 3.3) for the IOTP Message that contains information that describes the IOTP Message and IOTP Transaction
- the Transaction Id Component (see section 3.3.1) which globally uniquely identifies the IOTP Transaction
- the following components of the Authentication Request Block:
- the Authentication Request Component that was used in the Authentication (if present)
- the Trading Role Information Request Component (if present)
- the Organisation Components contained in the Authentication Response Block
7.19.7 Inquiry Request Signature Component 🔍
If the Inquiry Request is being signed (see section 9.2.1), the Manifest Element of the Inquiry Request Signature Component should contain Digest elements of the Inquiry Type Component and, if present, the Payment Scheme Component.
7.19.8 Inquiry Response Signature Component 💁
If the Inquiry Response is being signed (see section 9.2.1), the Manifest Element of the Inquiry Response Signature Component should contain Digest elements of the Trading Response Block and the Status Component.
7.19.9 Ping Request Signature Component 🏓
If the Ping Request is being signed (see section 9.2.2), the Manifest Element of the Ping Request Signature Component should contain Digest elements for all the Organisation Components.
7.19.10 Ping Response Signature Component 🏓
If the Ping Response is being signed (see section 9.2.2), the Manifest Element of the Ping Response Signature Component should contain Digest elements for all the Organisation Components.
7.20 Certificate Component 📜
Note: Definitions of the XML structures for signatures and certificates are described in the paper "Digital Signatures for the Internet Open Trading Protocol", see [IOTPDSIG].
See the note at the start of section 7.19 Signature Component for more details.
A Certificate Component contains a Digital Certificate. They are used only when required, for example, when asymmetric cryptography is being used and the recipient of the signature that needs to check has not already received the Public Key.
The structure of a Certificate Component is defined in [IOTPDSIG].
7.20.1 IOTP usage of signature elements and attributes 🎀
Detailed definitions of the above elements and attributes are contained in [IOTPDSIG]. The following contains additional information that describes how these elements and attributes are used by IOTP.
CERTIFICATE COMPONENT
The ID attribute is mandatory.
VALUE ELEMENT
The ID attribute is mandatory.
7.21 Error Component ✨
Okay bestie, the Error Component is where the drama lives 💅 It carries info about Technical Errors (see section 4.1) inside an IOTP Message that one of the Trading Roles in the trade received. Lowkey the most dramatic component in the whole spec 😭
For clarity, there are two phrases we use when talking about an Error Component 🎀
- message in error: an IOTP message that contains or causes an error of some kind 🙈
- message reporting the error: an IOTP message that contains an Error Component describing the error found in a message in error 🦋
Here's how the Error Component is defined 🧚
<!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: a unique identifier for the Error Component within the IOTP Transaction 🔑xml:lang: sets the language used by attributes or child elements in this component, unless a child element overrides it with its ownxml:langattribute. See section 3.8 Identifying Languages 🌈ErrorCode: an error code showing what kind of error is in the message in error. Valid values are listed in section 7.21.2 Error Codes 💀ErrorDesc: a narrative description of the error, written in the language set byxml:lang. The content is up to the vendor/developer of the software that made the Error Component ✍️Severity: how bad the error is. Valid values are:- Warning: there's a message in error, but the IOTP Transaction can still continue 🌸
- TransientError: the error in the message in error may be recovered if the message in error (the one the ErrorLocation element points to) gets resent 🔁
- HardError: there's an unrecoverable error in the message in error and the IOTP Transaction MUST stop 🚨
MinRetrySecs: this attribute SHOULD be present if Severity is set to TransientError. It's the minimum number of whole seconds the IOTP aware application that 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: a reference whose value is set by the vendor/developer of the software that made the Error Component. It SHOULD contain data that lets the vendor pinpoint the exact spot in their software, and the circumstances that made the software 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: identifies the IOTP Transaction Id of the message in error and, where possible, the element and attribute in that message that caused the Error Component to be generated 📍
If the Severity is not TransientError, more than one ErrorLocation MAY be specified, 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: extra data that helps you understand the error. Its content MAY vary depending on the nature of the error (see section 7.21.2 Error Codes) and at the discretion of the vendor/developer of the IOTP Aware Application. For a definition of PackagedContent, see section 3.7 📦
7.21.1 Error Processing Guidelines 🧠
If a message reporting the error has more than one Error Component, carry out the actions for the Error Component with the highest severity. Here the pecking order is HardError, then TransientError, then Warning 👑
7.21.1.1 Severity - Warning ⚠️
If an IOTP aware application is generating a message reporting the error with an Error Component whose Severity is set to Warning, then, as long as the message reporting the error doesn't 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 whose Severity is set to Warning, then:
- it is RECOMMENDED that information about the error is either logged or otherwise reported to the user 📝
- the implementer of the IOTP aware application MUST either, at their or the user's discretion:
- continue the IOTP transaction as normal, or
- fail the IOTP transaction by generating a message reporting the error with an Error Component whose Severity is set to HardError (see section 7.21.1.3) 💀
If the plan is to continue the IOTP transaction, then, if there are no other Error Components with a higher severity, check that the Trading Blocks and Trading Components needed for normal processing are present. If they aren't, generate a message reporting the error with an Error Component whose Severity is set to HardError 🙈
7.21.1.2 Severity - Transient Error 🔁
If an IOTP Aware Application is generating a message reporting the error with an Error Component whose Severity attribute is set to TransientError, then there SHOULD be only one Error Component in that message reporting the error. On top of that, the MinRetrySecs attribute SHOULD be present ✨
If a message reporting the error is received with an Error Component whose Severity is set to TransientError, then:
- if the MinRetrySecs attribute is present and a valid number, use the MinRetrySecs value given. Otherwise, if MinRetrySecs is missing or invalid, then:
- generate a message reporting the error containing an Error Component with a Severity of Warning, and send it on the next IOTP message (if any) to be sent to the Trading Role that sent the message reporting the error with the invalid MinRetrySecs, and
- use a value for MinRetrySecs that is set by the vendor/developer of the IOTP Aware Application 🎀
- check that only one ErrorLocation element is contained within the Error Component, and that it refers to an IOTP Message that was sent by the recipient of the Error Component with a Severity of TransientError. If more than one ErrorLocation is present, generate a message reporting the error with a Severity of HardError 🕵️♀️
7.21.1.3 Severity - Hard Error 🛑
If an IOTP Aware Application is generating a message reporting the error with an Error Component whose Severity attribute is set to HardError, then there SHOULD be only one Error Component in that message reporting the error 💅
If a message reporting the error is received with an Error Component whose Severity is set to HardError, then terminate the IOTP Transaction 🥀
7.21.2 Error Codes ✨
Okay bestie, here's the full list of Error Codes 💅 Each one is a possible value for the ErrorCode attribute of the Error Component. The first sentence of every description is the text you show (or report) when the error pops up, and implementations can translate it into other languages if they want 🌍 An Error Code MUST NOT be more than 14 characters long 🙅♀️
Value Description
Reserved Reserved. This error is reserved by the
vendor/developer of the software. Contact the
vendor/developer of the software for more information
See the SoftwareId attribute of the Message Id
element in the Transaction Reference Block(section
3.3).
XmlNotWellFrmd XML not well formed. The XML document is not well
formed. See [XML] for the meaning of "well formed".
Even if the XML is not well formed, it should still
be scanned to find the Transaction Reference Block so
that a properly formed Error Response may be
generated.
XmlNotValid XML not valid. The XML document is well formed but
the document is not valid. See [XML] for the meaning
of "valid". Specifically:
o the XML document does not comply with the
constraints defined in the IOTP document type
declaration (DTD) (see section 13 Internet Open
Trading Protocol Data Type Definition), and
o the XML document does not comply with the
constraints defined in the document type
declaration of any additional [XML Namespace] that
are declared.
As for XML not well formed, attempts should still be
made to extract the Transaction Reference Block so
that a properly formed Error Response may be
generated.
ElUnexpected Unexpected element. Although the XML document is well
formed and valid, an element is present that is not
expected in the particular context according to the
rules and constraints contained in this
specification.
ElNotSupp Element not supported. Although the document is well
formed and valid, an element is present that:
o is consistent with the rules and constraints
contained in this specification, but
o is not supported by the IOTP Aware Application
which is processing the IOTP Message.
ElMissing Element missing. Although the document is well formed
and valid, an element is missing that should have
been present if the rules and constraints contained
in this specification are followed.
In this case set the PackagedContent of the Error
Component to the type of the missing element.
ElContIllegal Element content illegal. Although the document is
well formed and valid, the element Content contains
values which do not conform to the rules and
constraints contained in this specification.
EncapProtErr Encapsulated protocol error. Although the document is
well formed and valid, the PackagedContent of an
element contains data from an encapsulated protocol
which contains errors.
AttUnexpected Unexpected attribute. Although the XML document is
well formed and valid, the presence of the attribute
is not expected in the particular context according
to the rules and constraints contained in this
specification.
AttNotSupp Attribute not supported. Although the XML document is
well formed and valid, and the presence of the
attribute in an element is consistent with the rules
and constraints contained in this specification, it
is not supported by the IOTP Aware Application which
is processing the IOTP Message.
AttMissing Attribute missing. Although the document is well
formed and valid, an attribute is missing that should
have been present if the rules and constraints
contained in this specification are followed.
In this case set the PackagedContent of the Error
Component to the type of the missing attribute.
AttValIllegal Attribute value illegal. The attribute contains a
value which does not conform to the rules and
constraints contained in this specification.
AttValNotRecog Attribute Value Not Recognised. The attribute
contains a value which the IOTP Aware Application
generating the message reporting the error could not
recognise.
MsgTooLarge Message too large. The message is too large to be
processed by the IOTP Aware Application.
ElTooLarge Element too large. The element is too large to be
processed by the IOTP Aware Application
ValueTooSmall Value too small or early. The value of all or part of
the Content of an element or an attribute, although
valid, is too small.
ValueTooLarge Value too large or in the future. The value of all or
part of the Content of an element or an attribute,
although valid, is too large.
ElInconsistent Element Inconsistent. Although the document is well
formed and valid, according to the rules and
constraints contained in this specification:
o the content of an element is inconsistent with the
content of other elements or their attributes, or
o the value of an attribute is inconsistent with the
value of one or more other attributes.
In this case create ErrorLocation elements which
identify all the attributes or elements which are
inconsistent.
TransportError Transport Error. This error code is used to indicate
that there is a problem with the Transport Mechanism
which is preventing the message from being received.
It is typically associated with a Transient Error.
Explanation of the Transport Error is contained
within the ErrorDesc attribute. The values which can
be used inside ErrorDesc with a TransportError is
specified in the IOTP supplement for the Transport
mechanism.
MsgBeingProc Message Being Processed. This error code is only used
with a Severity of Transient Error. It indicates that
the previous message, which may be an exchange
message or a request message, is being processed and,
if no response is received by the time indicated by
the MinRetrySecs attribute, then the original message
should be resent.
SystemBusy System Busy. This error code is only used with a
Severity of Transient Error. It indicates that the
server that received a message is currently too busy
to handle the message. If no response is received by
the time indicated by the MinRetrySecs attribute,
then the original message should be resent.
Note: If the server/system handling the Transport Mechanism (e.g.,
HTTP) is busy then a Transport Specific error message should be used
instead of an IOTP Error message. This code should be used in
association with IOTP servers/systems or other servers/systems to
which the IOTP server is connected.
UnknownError Unknown Error. Indicates that the transaction cannot
complete for some reason that is not covered
explicitly by any of the other errors. The ErrorDesc
attribute should be used to indicate the nature of
the problem.
This could be used to indicate, for example, an
internal error in a backend server or client process
of some kind.💖 Here's the vibe check on the table above: the codes are grouped by what went wrong, and a few of them come with a Severity hint (like Transient Error) that tells you how to respond. Those SHOULD be used exactly as written, so don't go changing them 🫶
7.21.3 Error Location Element 🧚
An Error Location Element is basically a pin on the map 📍 It tells you which element in the message is in error and, if you're lucky, which attribute too. It points at the IOTP Message, Trading Block, Trading Component, element and attribute that caused the trouble.
<!ELEMENT ErrorLocation EMPTY >
<!ATTLIST ErrorLocation
ElementType NMTOKEN #REQUIRED
IotpMsgRef NMTOKEN #IMPLIED
BlkRef NMTOKEN #IMPLIED
CompRef NMTOKEN #IMPLIED
ElementRef NMTOKEN #IMPLIED
AttName NMTOKEN #IMPLIED >Here's what each attribute does 🎀
ElementType: 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: the value of the ID attribute of the Message Id Component (see section 3.3.2) of the message in error that this Error Component applies to.BlkRef: if the error is tied to a specific Trading Block, this is the value of the ID attribute of the Trading Block where the error is located.CompRef: if the error is tied to a specific Trading Component, this is the value of the ID attribute of the Trading Component where the error is located.ElementRef: if the error is tied to a specific element within a Trading Component, then, if that element has an attribute with an "attribute type" (see [XML]) of "ID", this is the value of that attribute.AttName: if the error is tied to the value of an attribute, this is the name of that attribute. In this case, the PackagedContent of the Error Component SHOULD contain the value of the attribute 👀
🙌 Main character rule: as many as the attributes as possible SHOULD be included. Like, if an attribute in a child element of a Trading Component has a wrong value, then every attribute of ErrorLocation SHOULD be present so nobody has to play detective 🕵️♀️
8. Trading Blocks 🎀
okay so Trading Blocks are the child elements of the top level IOTP Messages 💖 they get sent as [XML] documents directly between the different Trading Roles taking part in a trade ✨
each Trading Block is made of one or more Trading Components (see section 7) 🧩 here's the picture, bestie 🦋
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 IOTP Message definition (see section 3.1.1) 🌸 here's the IOTP Message element again, just so we're all on the same page:
<!ELEMENT IotpMessage
( TransRefBlk,
SigBlk?,
ErrorBlk?,
( AuthReqBlk |
AuthRespBlk |
AuthStatusBlk |
CancelBlk |
DeliveryReqBlk |
DeliveryRespBlk |
InquiryReqBlk |
InquiryRespBlk |
OfferRespBlk |
PayExchBlk |
PayReqBlk |
PayRespBlk |
PingReqBlk |
PingRespBlk |
TpoBlk |
TpoSelectionBlk
)*
) >the rest of this section defines the Trading Blocks in this version of IOTP 🦋 they are:
- Authentication Request Block
- Authentication Response Block
- Authentication Status Block
- Cancel Block
- Delivery Request Block
- Delivery Response Block
- Error Block
- Inquiry Request Block
- Inquiry Response Block
- Offer Response Block
- Payment Exchange Block
- Payment Request Block
- Payment Response Block
- Signature Block
- Trading Protocol Options Block
- TPO Selection Block
and the Transaction Reference Block is described in section 3.3 💜
8.1 Trading Protocol Options Block 💅
the TPO Trading Block holds the options that apply to the IOTP Transaction 🍓 here's how it's defined:
<!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:
- the Protocol Options Component
- the Organisation Component with the Trading Role of Merchant
- the Organisation Component with the Trading Role of Consumer
- optionally, the Organisation Component with the Trading Role of DeliverTo, if there is a Delivery included in the IOTP Transaction
- Brand List Components for each payment in the IOTP Transaction
- Organisation Components for all the Payment Handlers involved
- optionally, Organisation Components for the Delivery Handler (if any) for the transaction
- additional Organisation Components that the Merchant may want to include. For example:
- a Customer Care Provider
- an Certificate Authority that offers Merchant "Credentials" or some other warranty on the goods or services being offered 🫶
8.2 TPO Selection Block 🌸
the TPO Selection Block holds the results of the choices made from the options in the Trading Protocol Options Block (see section 8.1) 💖 here's the definition:
<!ELEMENT TpoSelectionBlk (BrandSelection+) >
<!ATTLIST TpoSelectionBlk
ID ID #REQUIRED >Attributes:
ID: an identifier which uniquely identifies the TPO Selection Block within the IOTP Transaction 🔑
Content:
BrandSelection: this identifies the choice of payment brand and payment protocol to be used in a payment within the IOTP Transaction. There is one Brand Selection Component (see section 7.8) for each payment to be made in the IOTP Transaction 💸
the TPO Selection Block should contain one Brand Selection Component for each Brand List in the TPO Block 🦋
8.3 Offer Response Block 👑
the Offer Response Block has the details of the goods, services, amount, delivery instructions or financial transaction that's about to happen 🛍️ its definition is:
<!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, aProcessStateofNotYetStartedorInProgressare 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 needs to be communicated between the Trading Roles involved in an IOTP Transaction (see section 7.17) 🔐
the Offer Response Block should contain:
- the Order Component for the IOTP Transaction
- Payment Components for each Payment in the IOTP Transaction
- the Delivery Component the IOTP Transaction requires (if any) 🚚
8.4. Authentication Request Block ✨
The Authentication Request Block is where one Trading Role asks another one to show who they are, and/or asks for details about the Organisation being authenticated 🎀 It's giving "can you prove you're legit, and also tell me about yourself?" 💅
In outline it contains:
- information about how the authentication itself will be carried out, and/or
- a request for additional information about the Organisation being authenticated.
Here's its definition:
<!ELEMENT AuthReqBlk (AuthReq*, TradingRoleInfoReq?) >
<!ATTLIST AuthReqBlk
ID ID #REQUIRED >Attributes:
ID: an identifier that uniquely identifies the Authentication Request Block within the IOTP Transaction 🔖
Content:
AuthReq: each Authentication Request (see section 7.2) component describes one alternative way the recipient of the Authentication Request can 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 them based on the recipient's personal preference or their software's. Main character choice energy 👑
If no Authentication Request Component is present, it means that the Authentication Request Block is asking for 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) holds a list of the Trading Roles that information is being requested about 🧚
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. No empty blocks allowed bestie 🙅♀️
8.5. Authentication Response Block 🌸
The Authentication Response Block holds the response that comes out of processing the Authentication Request Block. Here's its definition:
<!ELEMENT AuthRespBlk (AuthResp?, Org*) >
<!ATTLIST AuthRespBlk
ID ID #REQUIRED >Attributes:
ID: an identifier that 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 hold information matching the Trading Roles requested by the TradingRoleList attribute of the Trading Role Information Request component 🫶
The components in the Authentication Response Block must match the requirements of the corresponding Authentication Request Block, otherwise it is an error. Matching is everything, periodt 💅
8.6. Authentication Status Block 🎀
The Authentication Status Block tells you whether an Authenticator's check of an Authentication Response Block passed or failed. Here's its definition:
<!ELEMENT AuthStatusBlk (Status) >
<!ATTLIST AuthStatusBlk
ID ID #REQUIRED >Attributes:
ID: an identifier that uniquely identifies the Authentication Status Block within the IOTP Transaction 🔖
Content:
Status: contains status information about whether the authentication was a business success (see section 4.2) or a failure 🚦
8.7. Payment Request Block 💸
The Payment Request Block holds information that asks for a payment to be started. Lowkey the most important block for the money part, so pay attention 👀 Here's its definition:
<!ELEMENT PayReqBlk (Status+, BrandList, BrandSelection,
Payment, PaySchemeData?, Org*, TradingRoleData*) >
<!ATTLIST PayReqBlk
ID ID #REQUIRED >Attributes:
ID: an identifier that uniquely identifies the Payment Request Block within the IOTP Transaction 🌈
Content:
Status: contains the Status Components (see section 7.13) from the responses of the steps this one depends on, like an Offer Response and/or a Payment Response. They tell you whether those steps went well or badly. Payment should only occur if the previous steps were successful. Don't pay for something that already flopped 💀
BrandList: the Brand List Component holds a list of one or more payment brands and protocols that can be selected (see section 7.7) 🍓
BrandSelection: this picks the payment brand, the payment protocol and the Payment Handler to use for 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 hold information about the payment being made. See section 7.9. 💖
PaySchemeData: the Payment Scheme Component holds payment scheme specific data. See section 7.10. 🧾
Org: the Organisation Component holds details of the Organisations involved in the payment (see section 7.6). Which Organisations show up depends on the IOTP Transaction and on the data that is going to be signed. See section 6 Digital Signatures for more details. 🔏
TradingRoleData: the Trading Role Data Component holds opaque data that the Trading Roles in an IOTP Transaction need to pass between each other (see section 7.17) 🧚
The Payment Request Block should contain:
- the Organisation Component with a Trading Role of Merchant
- the Organisation Component with the Trading Role of Consumer
- the Payment Component for the Payment
- the Brand List Component for the Payment
- the Brand Selection Component for the Brand List
- the Organisation Component for the Payment Handler of the Payment
- the Organisation Component (if any) for the Organisation which carried out the previous step, for example another Payment Handler
- the Organisation Component for the Organisation which is to carry out the next step, if any. This may be, for example, either a Delivery Handler or a Payment Handler.
- the Organisation Components for any additional Organisations that the Merchant has included in the Offer Response Block
- an Optional Payment Scheme Data Component, if required by the Payment Method as defined in the IOTP supplement for the payment method
- any Trading Role Data Components that may be required (see section 7.17.1).
8.8. Payment Exchange Block 🦋
The Payment Exchange Block carries payment scheme specific data that gets exchanged between two of the roles in a trade. Here's its definition:
<!ELEMENT PayExchBlk (PaySchemeData+) >
<!ATTLIST PayExchBlk
ID ID #REQUIRED >Attributes:
ID: an identifier that uniquely identifies the Payment Exchange Block within the IOTP Transaction 🪪
Content:
PaySchemeData: this Trading Component holds payment scheme specific data. See section 7.10 Payment Scheme Component. 💅
8.9. Payment Response Block 🧾
This Payment Response Block contains information about the Payment Status, an optional Payment Receipt, and an optional payment protocol message. Here's its definition:
<!ELEMENT PayRespBlk (Status, PayReceipt?, PaySchemeData?,
PaymentNote?, TradingRoleData*) >
<!ATTLIST PayRespBlk
ID ID #REQUIRED >Attributes:
ID: an identifier that uniquely identifies the Payment Response Block within the IOTP Transaction 🔖
Content:
Status: contains status information about whether the payment was a business success (see section 4.2) or a failure. Note that in a Pay Response Block, a ProcessState of NotYetStarted or InProgress are illegal values. ⚠️
Heads up: in a Pay Response Block, a ProcessState of NotYetStarted or InProgress is illegal. Don't send those! 🙅♀️
PayReceipt: contains payment scheme specific data that can be used to verify the payment happened. 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 information that isn't about the payment itself, which the Payment Handler wants to give the Consumer. For example, if a withdrawal or deposit were being made, 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 holds opaque data that the Trading Roles in an IOTP Transaction need to pass between each other (see section 7.17). 💜
8.10. Delivery Request Block
okay bestie 📦✨ this block is the one that carries the goodies (goods or services!) to be delivered, and it comes with a signature so everyone can check that the delivery is authorised 🔐💅 here's the shape:
<!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 🛍️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 🏢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 needs to be communicated between the Trading Roles involved in an IOTP Transaction (see section 7.17) 🤐
The Delivery Request Block contains:
- the Organisation Component with a Trading Role of Merchant
- the Organisation Component for the Consumer and DeliverTo Trading Roles
- the Delivery Component for the Delivery
- the Organisation Component for the Delivery Handler. Specifically, the Organisation Component identified by the ActionOrgRef attribute on the Delivery Component
- the Organisation Component (if any) for the Organisation which carried out the previous step, for example a Payment Handler
- the Organisation Components for any additional Organisations that the Merchant has included in the Offer Response Block
- any Trading Role Data Components that may be required (see section 7.17.1) ✨
8.11. Delivery Response Block
the Delivery Response Block contains a Delivery Note with details on how the goods will be delivered 📝🚀 one thing to watch: in a Delivery Response Block, a Delivery Status Element with a DeliveryStatusCode of NotYetStarted or InProgress is invalid 🙅♀️ here's the definition:
<!ELEMENT DeliveryRespBlk (Status, DeliveryNote) >
<!ATTLIST DeliveryRespBlk
ID ID #REQUIRED >Attributes:
ID: an identifier which uniquely identifies the Delivery Response Block within the IOTP Transaction 🆔
Content:
Status: contains status information about the business success (see section 4.2) or failure of the delivery. Note that in a Delivery Response Block, a ProcessState of NotYetStarted or InProgress are illegal values 💀DeliveryNote: the Delivery Note Component contains details about how the goods or services will be delivered (see section 7.15) 📦
8.12. Inquiry Request Trading Block
the Inquiry Request Trading Block contains an Inquiry Type Component and an optional Payment Scheme Component, which holds payment scheme specific inquiry messages 🔍💖
<!ELEMENT InquiryReqBlk ( InquiryType, PaySchemeData? ) >
<!ATTLIST InquiryReqBlk
ID ID #REQUIRED >Attributes:
ID: an identifier which uniquely identifies the Inquiry Request Trading Block within the IOTP Transaction 🆔
Content:
InquiryType: Inquiry Type Component (see section 7.18) that contains the type of inquiry 🧐PaySchemeData: Payment Scheme Component (see section 7.10) that contains payment scheme specific inquiry messages for inquiries on payments. This is present when the Type attribute of Inquiry Type Component is Payment 💳
8.13. Inquiry Response Trading Block
the Inquiry Response Trading Block contains a Status Component and an optional Payment Scheme Component, which holds 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 contain the valueNull. 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 valueNull. This attribute exists for debugging purposes 🐛
Content:
Status: contains status information about the business success (see section 4.2) or failure of a certain trading exchange (i.e., Offer, Payment, or Delivery) 📊PaySchemeData: Payment Scheme Component (see section 7.10) that contains payment scheme specific inquiry messages for inquiries on payments. This is present when the Type attribute of StatusType attribute of the Status Component is set to Payment 💅
8.14. Ping Request Block
the Ping Request Block is used to determine if a Server is operating and whether or not cryptography is compatible 🏓🔐 here's the definition:
<!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:
- an Organisation Component that identifies itself, specifying the Trading Role(s) it is taking in IOTP transactions (Merchant, Payment Handler, etc.)
- an Organisation Component that identifies the intended recipient of the message
These are then used to generate a signature over the Ping Response Block 🫶
8.15 Ping Response Block 🎀
Okay so the Ping Response Trading Block is the answer to a Ping Request, bestie 💅 It tells you how the ping went. It has an Organisation Component that says who sent the Ping Response.
If the Ping Request this block answers had Organisation Components, the Ping Response carries those too 🫶
<!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 that uniquely identifies the Ping Request Trading Block within the IOTP Transaction ✨PingStatusCode: a code that shows the status of the sender software which processes IOTP messages. The valid values are:Ok. Everything with the service is working normally, including the signature verification 💖Busy. Things are working normally but there may be some delays ⏳Down. The server is not functioning fully but can still provide a Ping response 💀
SigVerifyStatusCode: a code that shows the status of signature verification. This is only present when the message containing the Ping Request Block also contains a Signature Block. The valid values are:Ok. The signature has successfully been verified and proved compatible 🔥NotSupported. The receiver of this Ping Request Block does not support validation of signatures 🙈Fail. Signature verification failed 😭
Xml:lang: defines the language used inPingStatusDesc. This is present whenPingStatusDescis present 🌈PingStatusDesc: a short description of the status of the server which sends this Ping Response Block. Servers can use this attribute, if their designers want, to send more refined status information thanPingStatusCode. It 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 are 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. Not me being dramatic but this is the whole vibe 💀
8.16 Signature Block 🦋
The Signature Block contains one or more Signature Components and associated Certificates (if required), which sign data associated with the IOTP Transaction. For a general discussion and introduction to how IOTP uses signatures, see section 6 Digital Signatures. The definition of the Signature Component and certificates is in the paper "Digital Signatures for the Internet Open Trading Protocol", see [IOTPDSIG]. Descriptions of how these are used by IOTP are 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 that 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 depend on the Trading Block that is contained in the same IOTP Message as the Signature Block. So it's giving "it depends on your friends" energy 👑
8.16.1 Signature Block with Offer Response
A Signature Block which is in the same message as an Offer Response Block contains just an Offer Response Signature Component (see section 7.19.2) 💅
8.16.2 Signature Block with Payment Request
A Signature Block which is in the same message as a Payment Request Block contains:
- an Offer Response Signature Component (see section 7.19.2), and
- if the Payment is dependent on an earlier step (as indicated by the
StartAfterattribute on the Payment Component), then the Payment Receipt Signature Component (see section 7.19.3) generated by the previous step 🎀
8.16.3 Signature Block with Payment Response
A Signature Block which is in the same message as a Payment Response Block contains just a Payment Receipt Signature Component (see section 7.19.3) generated by the step 🧾
8.16.4 Signature Block with Delivery Request
A Signature Block which is in the same message as a Delivery Request Block contains:
- an Offer Response Signature Component (see section 7.19.2), and
- the Payment Receipt Signature Component (see section 7.19.3) generated by the previous step 🚚
8.16.5 Signature Block with Delivery Response
A Signature Block which is in the same message as a Delivery Response Block contains just a Delivery Response Signature component (see section 7.19.4) generated by the step 🌈
8.17 Error Block 🚨
The Error Trading Block contains one or more Error Components (see section 7.21). These 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. Lowkey the most important block when things go sideways 🙈
For clarity, two phrases are defined which are used in the description of an Error Trading Block:
- message in error. An IOTP message which contains or causes an error of some kind 🫠
- message reporting the error. An IOTP message that contains an Error Trading Block that describes the error found in a message in error 📣
An Error Trading Block may be contained in any message reporting the error. The action which then follows depends on the severity of the error. See the definition of an Error Component for an explanation of the different types of severity and the actions which can then occur 🧚
in3 Note: Although an Error Trading Block can report multiple different errors using multiple Error Components, there is no obligation on a developer of an IOTP Aware Application to do so.
The structure of an Error Trading Block is as follows:
<!ELEMENT ErrorBlk (ErrorComp+, PaySchemeData*) >
<!ATTLIST ErrorBlk
ID ID #REQUIRED >Attributes:
ID: an identifier that uniquely identifies the Error Trading Block within the IOTP Transaction 🎟️
Content:
ErrorComp: an Error Component (see section 7.21) that contains information about an individual Technical Error 🐛PaySchemeData: an optional Payment Scheme Component (see section 7.10) which contains a Payment Scheme Message. See the appropriate payment scheme supplement to determine whether or not this component needs to be present, and for the definition of what it must contain 💳
8.18 Cancel Block 🛑
The Cancel Block is used by one Trading Role to tell any other that a transaction has been cancelled. Example usage includes:
- a Consumer Role informing a non-Consumer Role that it no longer plans to continue with the transaction. This lets the server close down the transaction tidily without waiting for a time-out to occur 🧹
- a non-Consumer Role informing a Consumer Role that the Transaction is being stopped. In this case, the Consumer is then unlikely to re-send the previous message, which was sent in the mistaken understanding that the original was not received 🙅♀️
Its definition is as follows:
<!ELEMENT CancelBlk (Status) >
<!ATTLIST CancelBlk
ID ID #REQUIRED >Attributes:
ID: an identifier that uniquely identifies the Cancel Block within the IOTP Transaction 🔖
Content:
Status: contains status information indicating that the IOTP transaction has been cancelled 🪦
9. Internet Open Trading Protocol Transactions 🛍️
The Baseline Internet Open Trading Protocol supports three types of transactions, each for a different purpose. These are:
- an Authentication IOTP transaction, which supports authentication of one party in a trade by another and/or requests information about another Trading Role 🔐
- IOTP Transactions that involve one or more payments. Specifically:
- Deposit
- Purchase
- Refund
- Withdrawal, and
- Value Exchange 💸
- IOTP Transactions designed to check the correct function of the IOTP infrastructure. Specifically:
- Transaction Status Inquiry, and
- Ping 🏓
Although the Authentication IOTP Transaction can operate on its own, authentication can optionally precede any of the "payment" transactions. Therefore, the rest of this section is divided into two parts covering:
- Authentication and Payment transactions (Authentication, Deposit, Purchase, Refund, Withdrawal and Value Exchange) 🎀
- Infrastructure Transactions (Transaction Status Inquiry and Ping) that are designed to support inquiries on whether or not a transaction has succeeded, or whether a Trading Role's servers are operating correctly, and
9.1 Authentication and Payment Related IOTP Transactions ✨
okay so the Authentication and Payment related IOTP Transactions are built from six Document Exchanges 💅 you chain them together in sequence and boom, you've got a full transaction 🎀
generally there's a close (but not exact!) match between a Document Exchange and a Trading Exchange 🦋 the big difference is that some Document Exchanges cover part or all of two Trading Exchanges at once. they do this so fewer actual IOTP Messages have to go over the Internet. efficiency is giving main character energy 👑
the six Document Exchanges are:
- Authentication. This is a direct implementation of the Authentication Trading Exchange ✨
- Brand Dependent Offer. This is the Offer Trading Exchange combined with the Brand Selection part of the Payment Trading Exchange. Its purpose is to give the Merchant info on the Brand selected so the content of the Offer Response can be adapted to match 🌸
- Brand Independent Offer. This is also an Offer Trading Exchange. However, here the content of the Offer Response does not depend on the Brand selected 🍓
- Payment. This is a direct implementation of the Payment part of a Payment Trading Exchange 💜
- Delivery. This is a direct implementation of the Delivery Exchange 🧚
- Delivery with Payment. This is an implementation of combined Payment and Delivery Trading Exchanges 🔥
these Document Exchanges get combined in different sequences to make each IOTP Transaction happen. the diagram below shows which combos are possible 🫶
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 🎀
which combos are valid depends on the particular IOTP transaction 💖
the rest of this sub-section covers:
- each Document Exchange in more detail, including what's in each Trading Block inside the Document Exchanges, and
- how each IOTP Transaction uses the Document Exchanges to get the result it wants ✨
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 those are handled the same way no matter what context the message is sent in. See section 4 for more details. 🙈
9.1.1 Authentication Document Exchange
the Authentication Document Exchange is a direct implementation of the Authentication Trading Exchange (see section 2.2.4) 🦋 it involves:
- an Authenticator, which is the Organisation requesting the authentication, and
- an Authenticatee, which is the Organisation being authenticated.
the authentication itself is made of:
- an Authentication Request being sent by the Authenticator to the Authenticatee,
- an Authentication Response being sent back by the Authenticatee to the Authenticator, which then gets checked, and
- an Authentication Status being sent by the Authenticator to the Authenticatee to show whether the authentication worked or flopped 💀
an Authentication Document Exchange also:
- gives an Authenticatee an Organisation Component that describes the Authenticator, and
- optionally gives the Authenticator Organisation Components that describe the Authenticatee 🌈
the Authentication Request may also be digitally signed, which lets the Authenticatee verify the Authenticator's credentials. super important, bestie 🔐
the IOTP Messages involved are shown in the diagram below 🧚
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Organisation 1
(Authenticatee)
| Organisation 2
| (Authenticator)
STEP | |
1. First Organisation takes an action (for example by
pressing a button on an HTML page) which requires that
the Organisation is authenticated
1 --> 2 Authentication Need (outside scope of IOTP)
2. The second Organisation generates: an Authentication
Request Block containing one or more Authentication
Request Components and/or a Trading Role Information
Request Component, then sends it to the first
Organisation
1 <-- 2 TPO & AUTHENTICATION REQUEST. IotpMsg: Trans Ref Block;
Signature Block (optional); TPO Block; Auth Request Block
3. IOTP aware application started. If a Signature Block is
present, the first Organisation may use this to check the
credentials of the second Organisation. If credentials are
OK, the first Organisation selects an Authentication
Request to use (if present and more than one), then uses
the authentication algorithm selected to generate an
Authentication Response Block. If present, the Trading
Role Information Request Component is used to generate
Organisation Components. Finally a Signature Component is
created if required and all components are then sent back
to the second Organisation for validation.
1 --> 2 AUTHENTICATION RESPONSE. IotpMsg; Trans Ref Block;
Signature Block (optional) ; Auth Response Block
4. The second Organisation checks the Authentication
Response against the data in the Authentication Request
Block to check that the first Organisation is who they
appear to be, and sends an Authentication Status Block to
the first Organisation to indicate the result then
stops.
1 <-- 2 AUTHENTICATION STATUS. IotpMsg: Trans Ref Block;
Signature Block (optional); Auth Response Block
5. The first Organisation checks the authentication Status
Block and optionally keeps information on the IOTP
transaction for record keeping purposes and stops.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 18 Authentication Document Exchange9.1.1.1 Message Processing Guidelines
okay this part is the rulebook for what each side does when a message lands 📜 first up, when a TPO & Authentication Request IOTP Message comes in (see below), an Authenticatee can either:
- generate and send an Authentication Response IOTP Message back to the Authenticator, or
- say "nope, not complying with that Authentication Request" by sending a Cancel Block back to the Authenticator. That Cancel Block holds a Status Component with a StatusType of Authentication a ProcessState of Failed and the CompletionCode (see section 7.16.4) set to either:
AutEeCancel,NoAuthReq,TradRolesInconorUnspecified. 🙅♀️
when an Authentication Response IOTP Message comes in (see below), an Authenticator should send back an Authentication Status IOTP Message (see below). That message has a Status Block with a Status Component where the StatusType is set to Authentication, and:
- the ProcessState attribute of the Status Component is set to
CompletedOk, which means a successful completion, or - the ProcessState attribute is set to Failed and the CompletionCode attribute is set to either:
AutOrCancel,AuthFailedorUnspecified, which means the authentication failed 💔
when an Authentication Status IOTP Message comes in (see below), the Authenticatee should check the Status Component in the Status Block. If that shows:
- a successful authentication, then the Authenticatee should either:
- continue with the next step in the IOTP Transaction that the Authentication Document Exchange is part of (if there is one), or
- flag a failure to continue with the rest of the IOTP Transaction by sending a Cancel Block back to the Authenticator. That Cancel Block contains a Status Component with a StatusType of Authentication, a ProcessState of Failed and the CompletionCode (see section 7.16.4) set to
AutEeCancel. 🛑
- a failed authentication, then the failure should be reported to the Authenticatee and any further processing stopped 🥺
lastly, if the Authenticator gets an IOTP Message containing a Cancel block from a Consumer, the Authenticatee may go to the CancelNetLocn specified on the Trading Role Element in the Organisation Component for the Authenticator contained in the Trading Protocol Options Block. 🌸
9.1.1.2 TPO & Authentication Request IOTP Message ✨
okay bestie, this is the TPO & Authentication Request message and it's giving main character energy 💅 Apart from a Transaction Reference Block (see section 3.3), it's made of:
- a Trading Protocol Options Block (see section 8.1)
- an Authentication Request Block (see section 8.4), and
- an optional Signature Block (see section 8.16).
Each of these are described below. 🦋
TRADING PROTOCOL OPTIONS BLOCK 🎀
The Trading Protocol Options Block (see section 8.1) MUST contain the following Trading Components:
- one Protocol Options Component (see Section 7.1) which defines the options which apply to the whole Authentication Document Exchange.
- one Organisation Component (see section 7.6) which describes the Authenticator. The Trading Role on the Organisation Component SHOULD indicate the role which the Authenticator is taking in the Trade, for example a Merchant or a Consumer.
AUTHENTICATION REQUEST BLOCK 🌸
The Authentication Request Block (see section 8.4) MUST contain the following Trading Components:
- one Authentication Request Component (see section 7.2), and
SIGNATURE BLOCK (AUTHENTICATION REQUEST) 🔥
If the Authentication Request is being digitally signed then a Signature Block MUST be included. It contains Digests of the following XML elements:
- the Transaction Reference Block (see section 3.3) for the IOTP Message that contains information that describes the IOTP Message and IOTP Transaction
- the Transaction Id Component (see section 3.3.1) which globally uniquely identifies the IOTP Transaction
- the following components of the TPO Block :
- the Protocol Options Component
- the Organisation Component
- the following components of the Authentication Request Block:
- the Authentication Request Component
- the Trading Role Information Request Component
9.1.1.3 Authentication Response IOTP Message 🧚
ok so this one is the Authentication Response message. Apart from a Transaction Reference Block (see section 3.3), it consists of:
- an Authentication Response Block (see section 8.5), and
- an optional Signature Block (see section 8.16).
Each of these are described below. 💜
AUTHENTICATION RESPONSE BLOCK ✨
The Authentication Response Block MUST contain the following Trading Component:
- one Authentication Response Component (see section 7.3)
- one Organisation Component for every Trading Role identified in the
TradingRoleListattribute of the Trading Role Information Request Component contained in the Authentication Request Block.
SIGNATURE BLOCK (AUTHENTICATION RESPONSE) 🍓
If the Algorithm element (see section 12. IANA Considerations) within the Authentication Request Component contained in the Authentication Request Block indicates that the Authentication Response SHOULD consist of a digital signature then a Signature Block MUST be included in the same IOTP message that contains an Authentication Response Block. The Signature Component contains Digest Elements for the following XML elements:
- the Transaction Reference Block (see section 3.3) for the IOTP Message that contains information that describes the IOTP Message and IOTP Transaction
- the Transaction Id Component (see section 3.3.1) which globally uniquely identifies the IOTP Transaction
- the following components of the Authentication Request Block:
- the Authentication Request Component
- the Trading Role Information Request Component
- the Organisation Components contained in the Authentication Response Block
Note: It SHOULD NOT be assumed that all trading roles can support the signing of data. Particularly it SHOULD NOT be assumed that Consumers support the signing of data. not me being the one to say it, but please don't assume that everyone can sign stuff 🙈
9.1.1.4 Authentication Status IOTP Message 💅
and now the Authentication Status message. Apart from a Transaction Reference Block (see section 3.3), it consists of:
- an Authentication Status Block (see section 8.5), and
- an optional Signature Block (see section 8.16).
Each of these are described below. 🌈
AUTHENTICATION STATUS BLOCK 👑
The Authentication Status Block (see section 8.6) MUST contain the following Trading Components:
- one Status Component (see section 7.16) with a
ProcessStateattribute set toCompletedOk.
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 Transaction Reference Block (see section 3.3) for the IOTP Message that contains information that describes the IOTP Message and IOTP Transaction
- the Transaction Id Component (see section 3.3.1) which globally uniquely identifies the IOTP Transaction
- the following components of the Authentication Status Block:
- the Status Component (see section 7.16).
Note: If the Authentication Document Exchange is followed by an Offer Document Exchange (see section 9.1.2) then the Authentication Status Block and the Signature Block (Authentication Status) MAY be combined with either:
- a TPO IOTP Message (see section 9.1.2.3), or
- a TPO and Offer Response IOTP Message (see section 9.1.2.6)
9.1.2 Offer Document Exchange 🛍️
the Offer Document Exchange comes in two basic flavours:
- Brand Dependent Offer Exchange. Where the content of the offer, e.g., the order details, amount, delivery details, etc., are dependent on the payment brand and protocol selected by the consumer, and
- Brand Independent Offer Exchange. Where the content of the offer is not dependent on the payment brand and protocol selected.
Each of these types of Offer Document Exchange MAY be preceded by an Authentication Document Exchange (see section 9.1.1). 🫶
9.1.2.1 Brand Dependent Offer Document Exchange 🌸
in a Brand Dependent Offer Document Exchange, the TPO Block and the Offer Response Block are sent separately by the Merchant to the Consumer, i.e.:
- the Brand List Component is sent to the Consumer in a TPO Block,
- the Consumer selects a Payment Brand, Payment Protocol and optionally a Currency and amount from the Brand List Component
- the Consumer sends the selected brand, protocol and currency/amount back to the Merchant in a TPO Selection Block, and
- the Merchant uses the information received to define the content of and then send the Offer Response Block to the Consumer.
This is illustrated by the diagram below. 🦋
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Merchant
STEP | |
1. Consumer decides to trade and sends to the Merchant
information (e.g., using HTML) that enables the Merchant
to create an offer,
C --> M Offer information - outside scope of IOTP
2. Merchant decides which payment brand protocols,
currencies and amounts apply, places then in a Brand List
Component inside a TPO Block and sends to Consumer
C <-- M TPO. IotpMsg: Trans Ref Block; TPO Block
3. IOTP aware application started. Consumer selects the
payment brand, payment protocol and currency/amount to
use. Records selection in a Brand Selection Component and
sends back to Merchant.
C --> M TPO SELECTION. IotpMsg: Trans Ref Block; TPO Selection
Block
4. Merchant uses selected payment brand, payment protocol,
currency/amount and the offer information to create an
Offer Response Block containing details about the IOTP
Transaction including price, etc. Optionally signs it and
sends to the Consumer
C <-- M OFFER RESPONSE. IotpMsg: Trans Ref Block; Signature Block
(optional); Offer Response Block
5. Consumer checks the Offer is OK, then combines components
from the TPO Block, the TPO Selection Block and the Offer
Response Block to create the next IOTP Message for the
Transaction and sends it together with the Signature
block if present to the required Trading Role
CONTINUED ...
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 19 Brand Dependent Offer Document ExchangeNote, 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:
- generate and send a TPO Selection IOTP Message back to the Merchant, or
- indicate failure to continue with the IOTP Transaction by sending a Cancel Block back to the Merchant containing a Status Component with a
StatusTypeofOffer, aProcessStateofFailedand theCompletionCode(see section 7.16.4) set to either:ConsCancelledorUnspecified.
On receiving a TPO Selection IOTP Message (see below) the Merchant MAY either:
- generate and send an Offer Response IOTP Message back to the Consumer, or
- indicate failure to continue with the IOTP Transaction by sending a Cancel Block back to the Consumer containing a Status Component with a
StatusTypeofOffer, aProcessStateofFailedand theCompletionCode(see section 7.16.4) set to either:MerchCancelledorUnspecified.
On receiving an Offer Response IOTP Message (see below) the Consumer MAY either:
- generate and send the next IOTP Message in the IOTP transaction and send it to the required Trading Role. This is dependent on the IOTP Transaction, or
- indicate failure to continue with the IOTP Transaction by sending a Cancel Block back to the Merchant containing a Status Component with a
StatusTypeofOffer, aProcessStateofFailedand theCompletionCode(see section 7.16.4) set to either:ConsCancelledorUnspecified.
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. that's the vibe: report it, don't touch it 💅
9.1.2.2 Brand Independent Offer Document Exchange ✨
okay bestie, so in a Brand Independent Offer Document Exchange the Merchant sends the TPO Block and the Offer Response Block to the Consumer together 🎀 like, one IOTP Message carries both a TPO Block and an Offer Response Block. no splitting it up, just one delivery 📦✨
here's the message flow 👇
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Merchant
STEP | |
1. Consumer decides to trade and sends to the Merchant
information (e.g., using HTML) that enables the Merchant
to create an offer,
C --> M Offer information - outside scope of IOTP
2. Merchant decides which payment brand protocols,
currencies and amounts apply, places then in a Brand List
Component inside a TPO Block, 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 Exchangengl this one is the main event when only one payment brand, protocol and currency/amount is on the table for the Consumer. it's also likely (but not guaranteed 🙈) when several brands are offered, the Payment Handler is the same, and all the brands use the same set of protocols. 💅
heads up: the TPO Block and the Offer Response Block can go in separate IOTP messages (see Brand Dependent Offer Document Exchange) even when the Offer Response Block hasn't changed. but that adds more messages to the transaction, so it's likely to make response times slower 🐢 not it.
IOTP aware applications supporting the Consumer Trading Role must check for the existence of an Offer Response Block in the first IOTP Message to figure out whether the Offer Document Exchange is brand dependent or not. 🧚
MESSAGE PROCESSING GUIDELINES 📝
when a TPO and Offer Response IOTP Message comes in (see below), the Consumer can either:
- generate and send the next IOTP Message in the IOTP transaction and send it to the required Trading Role. this depends on the IOTP Transaction, or
- bail on the IOTP Transaction by sending a Cancel Block back to the Merchant. the Cancel Block holds a Status Component with a StatusType of Offer, a ProcessState of Failed, and the CompletionCode (see section 7.16.1) set to either: ConsCancelled or Unspecified. 🙅♀️
if the Merchant gets an IOTP Message containing a Cancel block, the Consumer is likely to head over to the CancelNetLocn listed on the Trading Role Element in the Organisation Component for the Merchant. 🌸
9.1.2.3 TPO IOTP Message 🎀
the TPO IOTP Message is only used with a Brand Dependent Offer Document Exchange. apart from a Transaction Reference Block (see section 3.3), it's just a Trading Protocol Options Block (see section 8.1), which we'll get into below.
TPO (TRADING PROTOCOL OPTIONS) BLOCK 💖
the Trading Protocol Options Block (see section 8.1) must contain these Trading Components:
- one Protocol Options Component that defines the options for the whole IOTP Transaction. see Section 7.1.
- one Brand List Component (see section 7.7) for each Payment in the IOTP Transaction, holding one or more payment brands and protocols that can be picked for that payment
- Organisation Components (see section 7.6) with these roles:
- 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 lives in the PhOrgRef attribute of the Payment Component
if the IOTP Transaction includes a Delivery, the TPO Block also has to include:
- Organisation Components with these roles:
- DeliveryHandler, who will be delivering the goods or services
- DelivTo, i.e. the person or Organisation that's taking delivery
AUTHENTICATION STATUS AND SIGNATURE BLOCKS 🔐
if the Offer Document Exchange was preceded by an Authentication Document Exchange, the TPO IOTP Message may also contain:
- an Authentication Status Block (see section 8.6), and
- an optional Signature Block (Authentication Status) Signature Block
for all the deets, check out section 9.1.1.4 Authentication Status IOTP Message. 🫶
9.1.2.4 TPO Selection IOTP Message 🦋
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), it's just a TPO Selection Block (see section 8.1), described below.
TPO SELECTION BLOCK 💜
the TPO Selection Block (see section 8.2) contains:
- one Brand Selection Component (see section 7.8) for use in a later Payment Exchange. it holds the results of the Consumer picking a Payment Brand, Payment Protocol and currency/amount from the list in the Brand List Component. this is the Consumer's choice moment, iconic ✨
9.1.2.5 Offer Response IOTP Message 🌈
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), it consists of:
- an Offer Response Block (see section 8.1), and
- an optional Signature Block (see section 8.16).
OFFER RESPONSE BLOCK 🍓
the Offer Response Block (see section 8.3) contains these components:
- one Status Component (see section 7.16) that shows the status of the Offer Response. the ProcessState attribute should be set to CompletedOk
- one Order Component (see section 7.5) with details about the goods and services being bought, or the financial transaction taking place
- one or more Payment Component(s) (see section 7.9) for each payment that's going to be made
- zero or one Delivery Components (see section 7.13) with the details of the delivery, if the IOTP Transaction includes a delivery
- zero or more Trading Role Data Components (see section 7.17) if the Merchant needs them
SIGNATURE BLOCK (OFFER RESPONSE) 🔏
if the Authentication Status Block is being digitally signed, 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, a Signature Block must be included that contains a Signature Component (see section 7.19) with Digest Elements for the following XML elements:
- the Transaction Reference Block (see section 3.3) for the IOTP Message, which contains the info that describes the IOTP Message and IOTP Transaction
- the Transaction Id Component (see section 3.3.1), which globally and uniquely identifies the IOTP Transaction
- the following components of the TPO Block:
- the Protocol Options Component, and
- the Brand List Component
- all the Organisation Components present
- the following components of the Offer Response Block:
- the Order Component
- all the Payment Components present
- the Delivery Component if present
- any Trading Role Data Components present
9.1.2.6 TPO and Offer Response IOTP Message 👑
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), it consists of:
- a Trading Protocol Options Block (see section 8.1)
- an Offer Response Block (see section 8.1), and
- an optional Signature Block (see section 8.16).
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). no need to reinvent the wheel 🛞
OFFER RESPONSE BLOCK 🍓
this is the same as the Offer Response Block in the Offer Response IOTP Message (see section 9.1.2.5). iconic consistency 💅
AUTHENTICATION STATUS 🔐
if the Offer Document Exchange was preceded by an Authentication Document Exchange, 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 these additions:
- if the Offer Document Exchange is Brand Dependent, the Signature Component in the Signature Block also contains a Digest Element for the Brand Selection Component contained in the TPO Selection Block
- if the Offer Document Exchange was preceded by an Authentication Document Exchange, the Signature Component in the Signature Block also contains a Digest Element for the Authentication Status Block.
and that's the brand independent exchange, periodt 🌈✨
9.1.3 Payment Document Exchange 💸
okay bestie, this is the last stretch of a Payment Trading Exchange 💖 (see section 2.2.2), and it only kicks off once the Consumer has picked their Brand 👑. A Payment Exchange goes like this:
- the Consumer asks for a payment to start by making a Payment Request IOTP Message, using info from earlier IOTP Messages in the Transaction, and sending it to the Payment Handler 🚀
- the Payment Handler and the Consumer then keep swapping Payment Exchange IOTP Messages, each carrying payment protocol messages, until the payment is done, and finally
- the Payment Handler sends a Payment Response IOTP Message to the Consumer with a receipt for the payment 🧾
Here's the picture of all the IOTP Messages involved 🦋
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Payment
| Handler
STEP | |
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 Exchange9.1.3.1 Message Processing Guidelines
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:
- generate and send a Payment Exchange IOTP Message back to the Consumer, if more payment protocol messages need to be exchanged, or
- generate and send a Payment Response IOTP Message if the exchange of payment protocol messages is complete, or
- indicate failure to continue with the Payment by sending a Cancel Block back to the Consumer containing a Status Component with a StatusType of
Payment, a ProcessState ofFailedand the CompletionCode (see section 7.16.4) set to either:BrandNotSupp,CurrNotSupp,PaymtCancelled,AuthError,InsuffFunds,InstBrandInvalid,InstNotValid,BadInstrumentorUnspecified.
On receiving a Payment Exchange IOTP Message, the Consumer MAY either:
- generate and send a Payment Exchange Message back to the Payment Handler or
- indicate failure to continue with the Payment by sending a Cancel Block back to the Payment Handler containing a Status Component with a StatusType of
Payment, a ProcessState ofFailedand the CompletionCode (see section 7.16.2) set to either:ConsCancelledorUnspecified.
On receiving a Payment Exchange IOTP Message, the Payment Handler MAY either:
- generate and send a Payment Exchange IOTP Message back to the Consumer, if more payment protocol messages need to be exchanged, or
- generate and send a Payment Response IOTP Message if the exchange of payment protocol messages is complete, or
- indicate failure to continue with the Payment by sending a Cancel Block back to the Consumer containing a Status Component with a StatusType of
Payment, a ProcessState ofFailedand the CompletionCode (see section 7.16.2) set to either:PaymtCancelledorUnspecified.
On receiving a Payment Response IOTP Message, the Consumer MAY either:
- generate and send the next IOTP Message in the IOTP transaction and send it to the required Trading Role. This is dependent on the IOTP Transaction,
- stop, since the IOTP Transaction has ended, or
- indicate failure to continue with the IOTP Transaction by sending a Cancel Block back to the Merchant containing a Status Component with a StatusType of
Payment, a ProcessState ofFailedand the CompletionCode (see section 7.16.1) set to either:ConsCancelledorUnspecified.
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. 🙈
9.1.3.2 Payment Request IOTP Message
Apart from a Transaction Reference Block (see section 3.3), this message consists of:
- a Payment Request Block, and
- an OPTIONAL Signature Block
PAYMENT REQUEST BLOCK
The Payment Request Block (see section 8.7) contains:
- the following components copied from the Offer Response Block from the preceding Offer Document Exchange:
- the Status Component
- the Payment Component for the payment which is being carried out
- the following components from the TPO Block:
- 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
- one Brand Selection Component for the Brand List, i.e. the Brand Selection Component where BrandListRef attribute points to the Brand List. This component can be either:
- 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)
- an OPTIONAL Payment Scheme Component (see section 7.10) if REQUIRED by the payment method used (see the Payment Method supplement to determine if this is needed).
- zero or more Trading Role Data Components (see section 7.17).
Note that:
- if there is more than one Payment Components in an Offer Response Block, then the second payment is the one within the Offer Response Block that contains a StartAfter attribute (see section 7.9) that identifies the Payment Component for the first payment
- the Payment Handler to include is identified by the Brand Selection Component (see section 7.8) for the payment. Also see section 6.3.1 Check Request Block sent Correct Organisation for an explanation on how Payment Handlers are identified
- the Brand List Component to include is the one identified by the BrandListRef attribute of the Payment Component for the identified payment
- the Brand Selection Component to include from the Offer Response Block is the one that contains an BrandListRef attribute (see section 3.5) which identifies the Brand List Component for the second payment.
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. 🫶
9.1.3.3 Payment Exchange 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:
- one Payment Scheme Component (see section 7.10) which contains payment method specific data. See the Payment Method supplement for the payment method being used to determine what this SHOULD contain.
9.1.3.4 Payment Response IOTP Message
Apart from a Transaction Reference Block (see section 3.3), this message consists of:
- a Payment Response Block, and
- an OPTIONAL Signature Block
PAYMENT RESPONSE BLOCK
The Payment Response Block (see section 8.9) contains:
- one Payment Receipt Component (see section 7.11) which contains scheme specific data which can be used to verify the payment occurred
- one Payment Scheme Component (see section 7.10) if REQUIRED which contains payment method specific data. See the Payment Method supplement for the payment method being used to determine what this SHOULD contain
- an OPTIONAL Payment Note Component (see section 7.12)
- zero or more Trading Role Data Components (see section 7.17).
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 Transaction Reference Block (see section 3.3) for the IOTP Message which contains the first usage of the Payment Response Block,
- the Transaction Id Component (see section 3.3.1) within the Transaction Reference Block that globally uniquely identifies the IOTP Transaction,
- the Payment Receipt Component from the Payment Response Block,
- the Payment Note Component from the Payment Response Block,
- the other Components referenced by the PayReceiptNameRefs attribute (if present) of the Payment Receipt Component,
- the Status Component from the Payment Response Block,
- any Trading Role Data Components in the Payment Response Block, and
- all the Signature Components contained in the Payment Request Block if present.
Ngl that's a lot of moving parts, but the whole thing just clicks once you see the flow 🌈✨
9.1.4 Delivery Document Exchange 🚚✨
Okay bestie, the Delivery Document Exchange is a direct implementation of a Delivery Trading Exchange (see section 2.2.3) 💅 It's basically a two-step back-and-forth:
- the Consumer requests a Delivery by generating a Delivery Request IOTP Message, using info from earlier IOTP Messages in the Transaction, and sends it to the Delivery Handler 📦
- the Delivery Handler sends a Delivery Response IOTP Message back to the Consumer with details about how it responded to the request, plus an optional signature 🫶
Here's the flow, it's giving clean 🦋
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Delivery
| Handler
STEP | |
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
3. Consumer checks Delivery Response Block and optional
Signature Block are OK. Optionally keeps information on
IOTP Transaction for record keeping purposes and stops.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*Figure 22 Delivery Document Exchange 🌸
9.1.4.1 Message Processing Guidelines 💌
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). Then they can do one of two things:
- generate and send a Delivery Response IOTP Message to the Consumer, or
- indicate failure to continue with the Delivery by sending a Cancel Block back to the Consumer. This Cancel Block contains a Status Component with a
StatusTypeofDelivery, aProcessStateofFailed, and theCompletionCode(see section 7.16.4) set to eitherDelivCanceledorUnspecified🙈
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 in that IOTP Message should be reported to the Consumer, but no further action taken 💅
9.1.4.2 Delivery Request IOTP Message 📦
The Delivery Request IOTP Message consists of:
- a Delivery Request Block, and
- an optional Signature Block
DELIVERY REQUEST BLOCK 🎀
The Delivery Request Block (see section 8.10) contains:
- the following components copied from the Offer Response Block:
- 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 following Component from the Payment Response Block:
- the Status Component (see section 7.16).
- zero or more Trading Role Data Components (see section 7.17).
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 🫶
9.1.4.3 Delivery Response IOTP Message 🧚
The Delivery Response IOTP Message contains a Delivery Response Block and an optional Signature Block.
DELIVERY RESPONSE BLOCK 🌈
The Delivery Response Block contains:
- one Delivery Note Component (see section 7.15), which contains delivery instructions about the delivery of goods or services
in3 SIGNATURE BLOCK (DELIVERY RESPONSE)
The Signature Block should contain one Signature Component that contains Digest elements that refer to:
- the Transaction Id Component (see section 3.3.1) of the IOTP message that contains the Delivery Response Signature
- the Transaction Reference Block (see section 3.3) of the IOTP Message that contains the Delivery Response Signature
- the Consumer Delivery Data component contained in the Delivery Request Block (if any)
- the Signature Components contained in the Delivery Request Block (if any)
- the Status Component
- the Delivery Note Component
9.1.5 Payment and Delivery Document Exchange 💖
The Payment and Delivery Document Exchange is a combo 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 goes like this:
- the Consumer requests that a payment starts by generating a Payment Request IOTP Message, using info from earlier IOTP Messages in the Transaction, and sends it to the Payment Handler 💸
- the Payment Handler and the Consumer then swap Payment Exchange IOTP Messages, which encapsulate payment protocol messages, until the payment is complete, and finally
- the Payment Handler sends the Consumer one IOTP Message containing:
- a Payment Response Block with a receipt for the payment, and
- a Delivery Response Block with details of the goods or services to be delivered 🎁
The IOTP Messages involved are shown in the diagram below 👑
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer
| Payment
| Handler
STEP | |
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 occur, but won't necessarily, 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. It's set to False if the Delivery Response Block and the Payment Response Block are sent in separate IOTP Messages 🦋
9.1.5.1 Message Processing Guidelines 💅
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, 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 in that 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 is 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 💜
9.1.5.2 Payment Request IOTP Message 💸
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) ✨
9.1.5.3 Payment Exchange IOTP Message 🌈
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) 🫶
9.1.5.4 Payment Response and Delivery Response IOTP Message 🎀
The content of this message consists of:
- a Payment Response Block,
- an optional Signature Block (Payment Response), and
- a Delivery Response Block.
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) 🦋
9.1.6 Baseline Authentication IOTP Transaction 🔐
okay so a Baseline Authentication IOTP Transaction can happen any time between any of the Trading Roles involved in IOTP Transactions 💖 it's giving total flexibility, no cap. It could happen:
- before another IOTP Transaction
- at the same time as another IOTP Transaction
- independently of any other IOTP Transaction
bestie, the whole thing is just an Authentication Document Exchange (see section 9.1.1) 🦋 that's it, that's the transaction. Here's the flow:
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 🎀
okay now the fun part, when is this actually useful? ✨ Here are the example uses:
- early in a session with strong continuity 🌸 imagine a Financial Institution that:
- sets up a secure channel (e.g., using [SSL/TLS]) with a customer
- authenticates the customer using the Baseline Authentication IOTP Transaction, and then
- gives the customer access to account information and other services, totally confident they're talking to a bona fide customer 💅
- giving a Merchant role Organisation Components that contain information about Consumer and DelivTo Trading Roles 🧚
- so a Consumer can check a Payment Handler before starting a payment 🫶
9.1.7 Baseline Deposit IOTP Transaction 🍓
the Baseline Deposit IOTP Transaction is all about depositing electronic cash with a Financial Institution 💰
ngl this one's a little plot twist: in IOTP terminology, the Financial Institution is technically playing the merchant role 💀 because a service (a deposit of electronic cash) is being offered in return for a fee, like bank charges of some kind. The term "Financial Institution" is only used in the diagrams and text so it's clearer for us humans 🙈
it's made up of these Document Exchanges:
- 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).
here's how those can be combined 🌈
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 🦋
for which combos actually apply to a given IOTP Transaction, peek at section 9.1.12 "Valid Combinations of Document Exchanges" 👑
now some extra tea 🫖 📝
- a Merchant (Financial Institution) might accept a deposit in several types of electronic cash. BUT the Consumer depositing the cash usually already knows which type they want, so in practice it's usually stuck to just one 💅 also, several different protocols might be used for the same "brand" of electronic cash. In that case a Brand Dependent Offer may be a good way to negotiate which protocol to use ✨
- the Merchant (Financial Institution) can use the authentication results to figure out not just the consumer but also the account the payment goes into 🌸 if no single account can be identified, it must be obtained by other means. For example:
- the consumer could specify the account number before the Baseline Deposit IOTP Transaction starts, or
- the consumer could have been identified earlier (for example using a Baseline Authentication IOTP Transaction), and an account picked from a list provided by the Financial Institution 🧚
- a Baseline Deposit IOTP Transaction without an Authentication Document Exchange might be used:
- if a previous IOTP transaction (for example a Baseline Withdrawal or a Baseline Authentication) already authenticated the consumer, and a secure channel has been maintained, so the consumer's authenticity 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 the scope of IOTP, for example using a pass phrase, or a proprietary banking software solution 🌈
9.1.8 Baseline Purchase IOTP Transaction 🛍️
the Baseline Purchase IOTP Transaction is the one for buying goods or services using any payment method 💖 it's built from these Document Exchanges:
- an optional Authentication Document Exchange (see section 9.1.1)
- an Offer Document Exchange (see section 9.1.2)
- either:
- a Payment Document Exchange (see section 9.1.3) followed by
- a Delivery Document Exchange (see section 9.1.4)
- a Payment Document Exchange only, or
- a combined Payment and Delivery Document Exchange (see section 9.1.5).
and here's how those get combined 🦋
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 ✨
as always, to check which combination applies to a particular instance of an IOTP Transaction, head to section 9.1.12 "Valid Combinations of Document Exchanges" 💅
9.1.9. Baseline Refund IOTP Transaction 🧾💖
okay bestie, so in real business terms a refund usually goes like this 💅
- a request for a refund being made by the Consumer to the Merchant, typically supported by evidence to demonstrate:
- 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 merchant agreeing (or not) to the refund. This may involve some negotiation between the Consumer and the Merchant, and, if the merchant agrees,
- a refund payment by the Merchant to the Consumer.
the Baseline Refund IOTP Transaction only supports a subset of that list 🥺 specifically, it supports:
- stand alone authentication of the Consumer using a separate Baseline Authentication IOTP Transaction (see section 9.1.6)
- a refund payment by the Merchant to the Consumer using the following two Trading Exchanges:
- 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 way these Document Exchanges fit together is shown in 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 TransactionA Baseline Refund IOTP Transaction without an Authentication Document Exchange might be used:
- when authentication of the consumer has been achieved by some other means, for example, the consumer has entered some previously supplied code in order to identify herself and the refund to which the code applies. The code could be supplied, for example on a web page or by e-mail.
- when a previous IOTP transaction, for example a Baseline Authentication, authenticated the consumer, and a secure channel has been maintained, therefore the authenticity of the consumer is known and therefore the previously agreed refund can be identified.
- when the authentication of the consumer is carried out by the Payment Handler using a payment scheme authentication algorithm.
9.1.10. Baseline Withdrawal IOTP Transaction 🏧✨
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 is made up of these Document Exchanges:
- 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 way these Document Exchanges may be combined is shown in 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 TransactionNote that:
- a Merchant (Financial Institution) may be able to offer withdrawal of several different types of electronic cash. In practice usually only one form of electronic cash may be offered. However, there may be several different protocols which may be used for the same "brand" of electronic cash.
- the Merchant (Financial Institution) may use the results of the authentication to identify not only the consumer but also the account from which the withdrawal is to be made. If no single account can be identified, then it must be obtained by other means. For example:
- 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.
- a Baseline Withdrawal without an authentication might be used:
- 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.
9.1.11. Baseline Value Exchange IOTP Transaction ✨
okay so this is the Baseline Value Exchange, and bestie, it's giving currency swap energy 💸🦋 It uses Payment Document Exchanges to trade value in one currency, paid for with one payment method, for value in the same or a different currency using the same or a different payment method. Some examples of how it gets used:
- 💳 electronic cash advance on a credit card: like, the first payment could be a "dollar SET Payment" on a credit card, and then the second payment is a download of Visa Cash e-cash in dollars.
- 🇬🇧 foreign exchange using the same payment method: the first payment could be an upload of Mondex value in British Pounds, and the second a download of Mondex value in Euros.
- 🌍 foreign exchange using different payment methods: the first payment could be a SET payment in Canadian Dollars, followed by a download of GeldKarte in Deutchmarks.
The Baseline Value Exchange uses these Document Exchanges:
- an optional Authentication Document Exchange (see section 9.1.1)
- an Offer Document Exchange (see section 9.1.2), which provides details of what values and currencies will be exchanged, and
- two Payment Document Exchanges (see section 9.1.3) which carry out the two payments involved.
The way these Document Exchanges can be put together is shown in the diagram below. Main character energy 🎀
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 comes in two basic forms, and they're both iconic 👑
- Brand Dependent Value Exchange: the content of the offer, for example the rate at which one form of value is exchanged for another, depends on the payment brands and protocols the consumer picks, and
- Brand Independent Value Exchange: the content of the offer doesn't depend on the payment brands and protocols selected.
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, since it's 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 🔐
Okay, signatures time 🌸 The diagram below shows how signatures keep a Baseline Value Exchange safe and sound.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Signature generated IotpMsg (TPO)
by Merchant ensures - Trans Ref Block
integrity of the Offer --------> - - Signature Block
| - TPO Block MERCHANT
| - Offer Response Block
|
Signature generated by |
the Payment Handler of | IotpMsg (Pay Resp 1)
the first payment binds | - Trans Ref Block PAYMENT
Pay Receipt for the first -----> -> - Signature Block ----- HANDLER
payment to the Offer - Pay Response Block 1 | 1
|
Signature generated by |
the Payment Handler of IotpMsg (Pay Resp 2) | PAYMENT
the second payment binds - Trans Ref Block | HANDLER
the second payment to the -----> - Signature Block <------ 2
first payment and therefore - Pay Response Block 2
to the Offer
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*Figure 30 Baseline Value Exchange Signatures
9.1.12 Valid Combinations of Document Exchanges 🎀
okay bestie, this diagram is literally the cheat sheet for figuring out which combos of Document Exchanges are valid 💅 A Consumer Trading Role uses the data in its IOTP messages to check whether the exchanges it's running actually fit together ✨
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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 🦋
Now the rules, and they're giving very "if this, then that" 🧚
- 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) If the DelivAndPayResp attribute of the Delivery Component is set to True, then:
- 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
- i) if the Offer Response Block contains just one Payment Component, then:
- h) If the Offer Response Block contains a Delivery Component then:
- 4) Otherwise (no Offer Response Block) there is an error.
Here's the notes table, kept exactly as it is 💖
The following table indicates the types of IOTP Transactions which
can validly have the conditions indicated above.
Note IOTP Transaction Validity
1. Any Payment and Authentication IOTP Transaction
2. Any Payment and Authentication IOTP Transaction except Baseline
Authentication
3. Either Baseline Authentication, or a Baseline Purchase, Refund,
Deposit, Withdrawal or Value Exchange with a failed Authentication
4. Baseline Purchase only
5. Baseline Purchase, Refund, Deposit or Withdrawal
6. Baseline Value Exchange only9.1.13 Combining Authentication Transactions with other Transactions 🌈
okay so this one is about running an Authentication Transaction on its own, even while another IOTP Transaction is going 🙈 The first sections showed an Authentication Document Exchange sitting right before an Offer Document Exchange inside a single IOTP Transaction with the same IOTP Transaction Id, but it's not the only way 💜
Authentication can happen at any point, even in parallel with another IOTP Transaction. It's typically used:
- by a Consumer to authenticate a Merchant, Payment Handler or a Delivery Handler, or
- by a Payment Handler or Delivery Handler to authenticate a Consumer.
Here's the basic flow, in outline ✨
- the Trading Role that decides it wants to carry out an authentication of another role suspends the current IOTP transaction being carried out
- a stand-alone Authentication transaction is then carried out. This may, at implementer's option, be linked to the original IOTP Transaction using a Related To Component (see section 3.3.3) in the Transaction Reference Block.
- if the Authentication transaction is successful, then the original IOTP Transaction is restarted
- if the Authentication fails then the original IOTP Transaction is cancelled.
For example, a Consumer could:
- authenticate the Payment Handler for a Payment between receiving an Offer Response from a Merchant and before sending the Payment Request to that Payment Handler
- authenticate a Delivery Handler for a Delivery between receiving the Payment Response from a Payment Handler and before sending the Delivery Request
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.
So in that case, the 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. 👑
9.2 Infrastructure Transactions ⭐
Infrastructure Transactions are for checking in on things 🧚 They support inquiries about whether or not a transaction has succeeded, or whether a Trading Role's servers are operating correctly. There are two types of transaction:
- a Transaction Status Inquiry Transaction which provides information on the status of an existing or complete IOTP transaction, and
- Ping Transaction that enables one IOTP aware application to determine if the IOTP aware application at another Trading Role is operating and verify whether or not signatures can be handled.
Each of these is described below 🦋
9.2.1 Baseline Transaction Status Inquiry IOTP Transaction ✨
The Baseline IOTP Transaction Status Inquiry is how you check the status of an existing or complete IOTP transaction. It's giving "where's my order??" energy 📦💅
The Trading Blocks used by the Baseline Transaction Status Inquiry Transaction are:
- an Inquiry Request Trading Block (see section 8.12),
- an Inquiry Response Trading Block (see section 8.13)
- an optional Signature Block (see section 8.16).
Okay so the Inquiry IOTP Transaction can be used for a bunch of reasons 🎀, for example:
- to help resume a suspended transaction by figuring out the current state of processing of one of the other roles,
- for a merchant to find out if a payment, delivery, etc., was completed. Like, a Consumer might say "I paid!!" but have no signed IOTP payment receipt to prove it 😭. If the Merchant asks the Payment Handler, the Merchant can find out whether or not payment was made 🫶.
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. Main character energy 🦋
IOTP aware software that supports the Consumer Trading Role may not:
- digitally sign a response if requested, since it may not have the capability, or
- respond to an Inquiry Request at all since it may not be on-line, or may consider that the request is not reasonable since, for example, the Request was not digitally signed.
As a guideline (bestie, pay attention 💖):
- the Consumer should send a Transaction Status Inquiry Block to a Trading Role only after the following events have occurred:
- 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,
- other Trading Roles should send a Transaction Status Inquiry Block to the Consumer only after receiving a message from the Consumer and before sending the final "Response" message to the Consumer
- there are no restrictions on non-Consumer Trading Roles sending Inquiries to other trading roles.
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. Each transport has its own rules, so check the supplement 🧚
TRANSACTION STATUS INQUIRY ERROR HANDLING ⚠️
Errors in a Transaction Status Inquiry can be sorted into one of the following three cases:
- Business errors (see section 4.2) in the original (inquired) messages
- Technical errors (see section 4.1) - both IOTP and payment scheme specific ones - in the original IOTP (inquired) messages
- Technical errors in the message containing the Inquiry Request Block itself
Here's 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
STEP | |
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)
3. First role checks the Inquiry Response Block and optional
signature, takes whatever action is appropriate or
perhaps stops. This may include displaying status
information to the end user.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 32 Baseline Transaction Status InquiryThe rest of this sub-section on the Baseline Transaction Status Inquiry IOTP Transaction defines the contents of each Trading Block. Quick note: the term "original transaction" means the transaction 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:
- one Inquiry Type Component (see section 7.18). This identifies whether the inquiry is on an offer, payment, or delivery.
- zero or one Payment Scheme Components (see section 7.10). This is for encapsulating payment scheme specific inquiry messages for inquiries on a payment.
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:
- one Signature Component (see section 7.19)
- one or more Certificate Components, if required.
Inquiry Response Blocks should only be generated if the Transaction is authorised 🔐
Note: Digital signatures on an Inquiry Request are 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:
- Consumers are unlikely to generate requests with signatures, although it is not an error if they do
- the other trading roles may agree that digital signatures are required. For example, a Payment Handler may require that an Inquiry Request is digitally signed by the Merchant so that they can check that the request is valid.
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:
- one Status Component (see section 7.16). This component holds the status information on the inquired transaction,
- zero or one Payment Scheme Components. These contain encapsulated payment scheme specific inquiry messages for inquiries on payment.
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:
- one Signature Component (see section 7.19)
- one or more Certificate Components, if required.
Note: Digital signatures on an Inquiry Response are 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:
- Consumers are unlikely to generate responses with signatures, although it is not an error if they do
- the other trading roles may agree that digital signatures are required. For example, a Merchant may require that an Inquiry Response is digitally signed by the Payment Handler so that they can check that the request response is valid 💜
9.2.2 Baseline Ping IOTP Transaction
okay so the Baseline Ping is basically the "u up?" text of IOTP 💬🦋 its whole purpose is checking that the other Trading Roles are actually reachable before anyone commits to a transaction. no cap, it's giving very responsible energy 💅
It lets IOTP aware application software do two things:
- figure out if the IOTP aware application at another Trading Role is operating, and
- check whether the two trading roles' signatures can actually be processed 🔥
For example, a Merchant can use it to see if a Payment Handler or Delivery Handler is up and running before it starts a Purchase transaction with those trading roles. lowkey the most iconic "check before you wreck" move 🫶
The Trading Blocks used by the Baseline Ping IOTP Transaction are:
- a Ping Request Block (see section 8.14)
- a Ping Response Block (see section 8.15), and
- a Signature Block (see section 8.16).
PING MESSAGES ✨
Here's the message flow for the Baseline IOTP Ping Transaction, in all its glory:
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
1st Role
| 2nd Role
STEP | |
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 MessagesSo the first Trading Role starts by sending a PING REQUEST (with a Trans Ref Block, an optional Signature Block, and the Ping Request Block) 🎀 the second Trading Role answers with a PING Response, and the first one checks that response and does whatever it needs to 💖
The verification that signatures can be handled is shown by the sender of the Ping Request Block including:
- Organisation Components that identify itself and the intended recipient of the Ping Request Block, and
- a Signature Block that signs data in the Ping Request.
This way, the receiver of the Ping Request:
- knows who is sending the Ping Request, so it can verify the Signature on the Request, and
- knows who to generate a signature for on the Ping Response 🧚
Note that a Ping Request:
- does not affect any on-going transaction
- does NOT initiate an IOTP transaction, unlike other IOTP transaction messages such as TPO or Transaction Status Inquiry.
the Ping is a total lurker, it never starts a transaction. just vibes and a reply 🙈
All IOTP aware applications MUST return a Ping Response message to the sender of a Ping Request message when it is received. no ghosting allowed 💀
A Baseline IOTP Ping request can also contain an optional Signature Block. IOTP aware applications can use that Signature Block to check that the recipient of a Ping Request can successfully process and check the signatures it has received 🍓
For each Baseline Ping IOTP Transaction, each IOTP role SHALL establish a different transport session from other IOTP transactions. every ping gets its own little session, very main character 👑
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 rest of this sub-section on the Baseline Ping IOTP Transaction defines the contents of each Trading Block. let's go 🌸
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). anonymous pings are giving mysterious stranger 🙈
If the Ping Transaction is not anonymous, then the Ping Request Block contains Organisation Components for:
- the sender of the Ping Request Block, and
- the verifier of the Signature Component
If Organisation Components are present, then it shows 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. verify it bestie, no skipping 🔥
SIGNATURE BLOCK (PING REQUEST) 🎀
The Ping Request Signature Block (see section 8.16) contains the following components:
- one Signature Component (see section 7.19)
- one or more Certificate Components, if required.
PING RESPONSE BLOCK 🌈
The Ping Response Block (see section 8.15) contains the following component:
- the Organisation Component of the sender of the Ping Response message
If the Ping Transaction is not anonymous, then the Ping Response additionally contains:
- copies of the Organisation Components contained in the Ping Request Block.
SIGNATURE BLOCK (PING RESPONSE) 🧚
The Ping Response Signature Block (see section 8.16) contains the following components:
- one Signature Component (see section 7.19)
- one or more Certificate Components, if required.
10. Retrieving Logos 🖼️
okay this section is all about grabbing logos so IOTP aware software can show them off 💅 it uses the Logo Net Locations attribute in the Brand Element (see section 7.7.1) and the Organisation Component (see section 7.6).
The full address of a logo is defined like this:
Logo_address ::= Logo_net_location "/" Logo_size Logo_color_depth ".gif"Where:
- Logo_net_location comes from the LogoNetLocn attribute in the Brand Element (see section 7.7.1) or the Organisation Component. Note that:
- the content of this attribute depends on the Transport Mechanism (such as HTTP) that is used. See the Transport Mechanism supplement,
- implementers SHOULD check that if the rightmost character of Logo Net Location is set to right-slash "/" then another, right slash SHOULD NOT be included when generating the Logo Address,
- Logo_size identifies the size of the logo,
- Logo_color_depth identifies the colour depth of the logo
- "gif" indicates that the logos are in "gif" format
Logo_size and Logo_color_depth are specified by the implementer of the IOTP software that is retrieving the logo, depending on the size and colour they want to use 🌸
10.1 Logo Size 📐
There are five standard sizes for logos. The sizes in pixels and the corresponding values for Logo Size are in the table below.
Size in Logo Size
Pixels Value
32 x 32 or exsmall
32 x 20
53 x 33 small
103 x 65 medium
180 x 114 large
263 x 166 exlarge10.2 Logo Color Depth 🌈
There are three standard colour depths. The colour depth (including bits per pixel) and the corresponding value for Logo_Color_Depth are in the table below.
Color Depth Logo Color
(bits per pixel) Depth Value
4 (16 colors) 4
8 (256 colors) nothing
24 (16 million colors) 24Note that if Logo Color Depth is omitted, then a logo with the default colour depth of 256 colours will be retrieved. the default is giving basic but it works 🫶
10.3 Logo Net Location Examples 🧚
If Logo Net Location is set to "ftp://logos.xzpay.com", then:
- "ftp://logos.xzpay.com/medium.gif" would retrieve a medium size 256 colour logo
- "http://logos.xzpay.com/small4.gif" would retrieve a small size 16 colour logo
Note: Organisations which make logos available for use with IOTP SHOULD always make available "small" and "medium" size logos and use the "gif" format. bestie, please offer those sizes 🙏
11. Brands 🛍️
this section covers:
- a definition of Brands and an outline of Brand Selection using Brand Lists, and
- some XML examples of Brand Lists 💖
11.1 Brand Definitions and Brand Selection 👑
One of the key features of IOTP is that a merchant can offer a list of Brands for a consumer to pick from. this section gives an overview of what's involved and guidance on how a Consumer can select a brand and its payment instrument. It covers:
- definitions of Payment Instruments and Brands, so what they actually are in an IOTP context. It also further categorises Brands as optionally a "Dual Brand" or a "Promotional Brand", and
- identification and selection of Promotional Brands. Promotional Brands give a Consumer some extra benefit, like loyalty points or a discount. This means that both Consumers and the Merchant MUST be able to correctly identify that a valid Promotional Brand is being used. no mix-ups, periodt 💅
Also see the following sections:
- Brand List Component (section 7.7), which has the definitions of the XML elements holding the list of Brands a Merchant offers a Consumer, and
- Brand Selection Component (section 7.8) for details on how a Consumer records the Brand, currency, amount and payment protocol they selected 🎀
11.1.1 Definition of Payment Instrument 💳
A Payment Instrument is the means by which a Consumer pays for goods or services offered by a Merchant. It can be, for example:
- a credit card such as MasterCard or Visa;
- a debit card such as MasterCard's Maestro;
- a smart card based electronic cash payment instrument such as a Mondex Card, a GeldKarte card or a Visa Cash card
- a software based electronic payment account such as a CyberCash or DigiCash account.
Most Payment Instruments have a number, typically an account number, by which the Payment Instrument can be identified. 🔢
11.1.2 Definition of Brand 🏷️
A Brand is the mark that identifies a particular type of Payment Instrument. A list of Brands is the set of payment options the Merchant presents to the Consumer, who then makes a selection from them. Each Brand may have a different Payment Handler. Examples of Brands include:
- payment association and proprietary Brands, for example MasterCard, Visa, American Express, Diners Club, Mondex, GeldKarte, CyberCash, etc.
- promotional brands (see below). These include:
- store brands, where the Payment Instrument is issued to a Consumer by a particular Merchant, for example Walmart, Sears, or Marks and Spencer (UK)
- cobrands, for example American Advantage Visa, where an Organisation uses their own brand in conjunction with, typically, a payment association Brand. ✨
11.1.3 Definition of Dual Brand 🦋
okay so a Dual Brand means one payment instrument can be used as if it were two separate Brands 💅 for example, there could be a single Japanese "UC" MasterCard that works as either a UC card or a regular MasterCard ✨ the UC card Brand and the MasterCard Brand could each have their own Payment Handlers. so basically:
- the merchant treats, for example, "UC" and "MasterCard" as two separate Brands when it shows the Consumer a list of Brands 🌸
- the consumer picks a Brand, for example either "UC" or "MasterCard"
- the consumer IOTP aware application figures out which Payment Instrument(s) match the chosen Brand, then picks the right Payment Instrument to use, maybe with a little help from the user 🫶
Note: Dual Brands don't need any special treatment from the Merchant, so the DTD doesn't mention them explicitly 🙈 from the Merchant's point of view, each Brand in a Dual Brand is just a separate Brand. the matching of a Brand to a Dual Brand Payment Instrument happens at the Consumer's end.
11.1.4 Definition of Promotional Brand 🎀
a Promotional Brand means that if the Consumer pays with that Brand, they get some extra benefit 🤑 and that benefit can show up in two ways:
- at the time of purchase 🛍️ for example, if a Consumer pays with a "Walmart MasterCard" at a Walmart web site, a 5% discount might apply, so they actually end up paying less
- later, from their Payment Instrument (card) issuer, when the payment shows up on their statement 📜 for example, loyalty points in a frequent flyer scheme could be awarded based on the total payments made with the Payment Instrument since the last statement was issued
Note that:
- the first example (getting the benefit at the time of purchase) requires that:
- the Consumer is told about the benefits that come with selecting that Brand 👀
- if the Brand is selected, the Merchant changes the relevant IOTP Components in the Offer Response so the correct amount gets paid 💖
- the second one (getting a benefit through the Payment Instrument issuer) does not require that the Offer Response is changed 🧚
- each Promotional Brand should be identified as a separate Brand in the list of Brands the Merchant offers ✨ for example, "Walmart", "Sears", "Marks and Spencer" and "American Advantage Visa" would each be a separate Brand 👑
11.1.5 Identifying Promotional Brands 🔍
okay there are two problems we need to handle when identifying Promotional Brands 😭
- how does the Merchant, or their Payment Handler, positively identify the promotional brand being used at the time of purchase?
- how does the Consumer reliably identify the correct promotional brand from the Brand List the Merchant presents?
here's a description of how this could be done.
Note: this approach is a model approach that solves the problem 💜 other equivalent methods may be used.
11.1.5.1 Merchant/Payment Handler Identification of Promotional Brands 🕵️♀️
it's really important to correctly identify that the Consumer is paying with a Promotional Brand 🚨 because a Consumer might fraudulently claim to have a Promotional Brand that gives a reduced payment amount when they really don't 💀
two approaches seem possible:
- use some feature of the Payment Instrument or the payment method to positively identify the Brand being used 🔐 for example, the SET certificate for the Brand could be used, if one is available
- use the Payment Instrument (card) number to look up information about the Payment Instrument in a Payment Instrument issuer database, to figure out whether it's a promotional brand 🗂️
Note that:
- the first one assumes that SET is available
- the second one is only possible if the Merchant, or alternatively the Payment Handler, has access to card issuer information
IOTP doesn't give the Merchant any Payment Instrument information (for example, a card or account number) 🙅♀️ that only gets sent as part of the encapsulated payment protocol to a Payment Handler. this means that:
- the Merchant would have to assume the Payment Instrument selected really was a valid Promotional Brand, or
- the Payment Handler would have to check that the Payment Instrument was for the valid Promotional Brand, and fail the payment if it wasn't 🙃
a Payment Handler checking that a brand is a valid Promotional Brand is most likely if the Payment Handler is also the Card Issuer 🏦✨
11.1.5.2 Consumer Selection of Promotional Brands 🛒
there are two ways a Consumer can correctly select a Promotional Brand 🎯
- the Consumer visually matches a logo for the Promotional Brand that the Merchant gave them 👀
- the Consumer's IOTP aware application matches a code for the Promotional Brand, which the application has registered against a similar code in the list of Brands the Merchant offers 🤖
in the second case, the code in the Consumer wallet has to match the code in the Merchant's list exactly, otherwise no match gets found 🥲 here are some ways the Consumer's IOTP Aware Application could get hold of such a code:
- the Consumer types the code in directly 😬 this is error prone and not user friendly, and the consumer also needs to be given the code. this approach is not recommended
- using one of the Brand Identifiers defined by IOTP, pre-loaded into the Consumer's IOTP Aware application or wallet by the wallet's developer 🌈
- using some information contained in the software or other data associated with the Payment Instrument, which could be:
- a SET certificate for Brands that use this payment method
- a code provided by the payment software that handles the particular payment method 💳 this could apply to, for example, GeldKarte, Mondex, CyberCash and DigiCash
- the consumer makes an initial "manual" link between a Promotional Brand in the Merchant's list and an individual Payment Instrument, the first time the promotional brand is used 🧠 the IOTP Aware application then "remembers" the code for that Promotional Brand for future purchases 💖
11.1.5.3 Consumer Software Brand Id recommendation 📣
new Brand Ids get allocated under IANA procedures (see section 12 IANA Considerations), which also contains an initial list of Brand Identifiers 📋
it is recommended that implementers of consumer IOTP aware applications (for example, software wallets) pre-load their software with the then current set of Brand Ids, and provide a method for updating them, for example by going to the software developer's web site 🌸
11.2 Brand List Examples 💎
this example has three examples of the XML for a Brand List Component 🧁 it covers:
- a simple credit card based example
- a credit card based brand list including promotional credit card brands, and
- a complex electronic cash based brand list
Note that:
- brand lists can be as complex or as simple as needed 💅
- all the example techniques described in this appendix can be put into one brand list 🌈
11.2.1 Simple Credit Card Based Example 💳
this is a simple example involving:
- only major credit card payment brands
- a single price in a single currency
- a single Payment Handler, and
- a single payment protocol
<BrandList ID='M1.2'
XML:Lang='us-en'
ShortDesc='Purchase book including s&h'
PayDirection='Debit' >
<Brand ID ='M1.30'
BrandId='MasterCard'
BrandName='MasterCard Credit'
BrandLogoNetLocn='ftp://otplogos.mastercard.com/mastercardcredit'
ProtocolAmountRefs='M1.33'>
</Brand>
<Brand ID ='M.31'
BrandId='Visa'
BrandName='Visa Credit'
BrandLogoNetLocn='ftp://otplogos.visa.com/visacredit'
ProtocolAmountRefs='M1.33'>
</Brand>
<Brand ID ='M1.32'
BrandId='AmericanExpress'
BrandName='American Express'
BrandLogoNetLocn='ftp://otplogos.amex.com'
ProtocolAmountRefs ='M1.33' >
</Brand >
<ProtocolAmount ID ='M1.33'
PayProtocolRef='M1.35'
CurrencyAmountRefs='M1.34'>
</ProtocolAmount>
<CurrencyAmount ID ='M1.34'
Amount='10.95'
CurrCode='USD'/>
<PayProtocol ID ='M1.35'
ProtocolId='SCCD1.0'
ProtocolName='Secure Channel Credit/Debit'
PayReqNetLocn='http://www.example.com/etill/sccd1' >
</PayProtocol>
</BrandList>11.2.2 Credit Card Brand List Including Promotional Brands 🎀
here's a credit card based Brand List 🛍️ it includes:
- two ordinary card association brands and two promotional credit card brands. the promotional brands are one loyalty based one (British Airways MasterCard), which offers additional loyalty points, and one store based one (Walmart), which offers a discount on purchases over a certain amount
- two payment protocols:
- SET (Secure Electronic Transactions), see [SET], and
- SCCD (Secure Channel Credit Debit), see [SCCD]
<BrandList ID='M1.2'
XML:Lang='us-en'
ShortDesc='Purchase ladies coat'
PayDirection='Debit' >
<Brand ID ='M1.3'
BrandId='MasterCard'
BrandName='MasterCard Credit'
BrandLogoNetLocn='ftp://otplogos.mastercard.com'
ProtocolAmountRefs='M1.7 M1.8'>
<ProtocolBrand ProtocolId='SET1.0' ProtocolBrandId='MasterCard:'>
</ProtocolBrand>
</Brand>
<Brand ID ='M1.4'
BrandId='Visa'
BrandName='Visa Credit'
BrandLogoNetLocn='ftp://otplogos.visa.com'
ProtocolAmountRefs='M1.7 M1.8'>
<ProtocolBrand ProtocolId='SET1.0' ProtocolBrandId='Visa:'>
</ProtocolBrand>
</Brand>
<Brand ID ='M1.5'
BrandId='BritishAirwaysMC'
BrandName='British Airways MasterCard'
BrandLogoNetLocn='ftp://otplogos.britishairways.co.uk'
BrandNarrative='Double air miles with British Airways MasterCard'
ProtocolAmountRefs ='M1.7 M1.8' >
<ProtocolBrand ProtocolId='SET1.0' ProtocolBrandId='MasterCard:BA'>
</ProtocolBrand>
</Brand >
<Brand ID ='M1.6'
BrandId='Walmart'
BrandName='Walmart Store Card'
BrandLogoNetLocn='ftp://otplogos.walmart.com'
BrandNarrative='5% off with your Walmart Card
on purchases over $150'
ProtocolAmountRefs='M1.8'>
</Brand>
<ProtocolAmount ID ='M1.7'
PayProtocolRef='M1.10'
CurrencyAmountRefs='M1.9' >
<PackagedContent Transform="BASE64">
238djqw1298erh18dhoire
</PackagedContent>
</ProtocolAmount>
<ProtocolAmount ID ='M1.8'
PayProtocolRef='M1.11'
CurrencyAmountRefs='M1.9' >
<PackagedContent Transform="BASE64">
238djqw1298erh18dhoire
</PackagedContent>
</ProtocolAmount>
<CurrencyAmount ID ='M1.9'
Amount='157.53'
CurrCode='USD'/>
<PayProtocol ID ='M1.10'
ProtocolId='SET1.0'
ProtocolName='Secure Electronic Transaction Version 1.0'
PayReqNetLocn='http://www.example.com/etill/set1' >
<PackagedContent Transform="BASE64">
8ueu26e482hd82he82
</PackagedContent>
</PayProtocol>
<PayProtocol ID ='M1.11'
ProtocolId='SCCD1.0'
ProtocolName='Secure Channel Credit/Debit'
PayReqNetLocn='http://www.example.com/etill/sccd1' >
<PackagedContent Transform="BASE64">
82hd82he8226e48ueu
</PackagedContent>
</PayProtocol>
</BrandList>11.2.3 Brand Selection Example
okay so this one is my favourite 🦋 If you want to pay with the 'British Airways' MasterCard from the example above, using SET, so you rack up double air miles, your Brand Selection looks like this:
<BrandSelection ID='C1.2'
BrandListRef='M1.3'
BrandRef='M1.5'
ProtocolAmountRef='M1.7'
CurrencyAmountRef='M1.9' >
</BrandSelection>11.2.4 Complex Electronic Cash Based Brand List
this one is a bit of a lot 😭 but it's giving main character energy 👑 It covers:
- payments using Mondex, GeldKarte, CyberCash or DigiCash 💸
- currencies including US dollars, British Pounds, Italian Lira, German Marks and Canadian Dollars 🌍
- a discount on the price if the payment is made in Mondex using British pounds or US dollars, and 🏷️
- more than one Payment Handler being used for payments involving Mondex or CyberCash 🧚
- support for more than one version of the CyberCash CyberCoin payment protocol. 🔥
<BrandList ID='M1.2'
XML:Lang='us-en'
ShortDesc='Company report on XYZ Co'
PayDirection='Debit' >
<Brand ID ='M1.13'
BrandId='Mondex'
BrandName='Mondex Electronic Cash'
BrandLogoNetLocn='ftp://otplogos.mondex.com'
ProtocolAmountRefs='M1.17 M1.18'>
</Brand>
<Brand ID ='M1.14'
BrandId='GeldKarte'
BrandName='GeldKarte Electronic Cash'
BrandLogoNetLocn='ftp://otplogos.geldkarte.co.de'
ProtocolAmountRefs='M1.19'>
</Brand>
<Brand ID ='M1.15'
BrandId='CyberCoin'
BrandName='CyberCoin Eletronic Cash'
BrandLogoNetLocn='http://otplogos.cybercash.com'
ProtocolAmountRefs ='M1.20' >
</Brand >
<Brand ID ='M1.16'
BrandId='DigiCash'
BrandName='DigiCash Electronic Cash'
BrandLogoNetLocn='http://otplogos.digicash.com'
BrandNarrative='5% off with your Walmart Card
on purchases over $150'
ProtocolAmountRefs='M1.22'>
</Brand>
<ProtocolAmount ID ='M1.17'
PayProtocolRef='M1.31'
CurrencyAmountRefs='M1.25 M1.29'>
</ProtocolAmount>
<ProtocolAmount ID ='M1.18'
PayProtocolRef='M1.32'
CurrencyAmountRefs='M1.26 M1.27 M1.28 M1.30'>
</ProtocolAmount>
<ProtocolAmount ID ='M1.19'
PayProtocolRef='M1.35'
CurrencyAmountRefs='M1.28'>
</ProtocolAmount>
<ProtocolAmount ID ='M1.20'
PayProtocolRef='M1.34 M1.33'
CurrencyAmountRefs='M1.23 M1.24 M1.27 M1.28 M1.29 M1.30'>
</ProtocolAmount>
<ProtocolAmount ID ='M1.21'
PayProtocolRef='M1.36'
CurrencyAmountRefs='M1.23 M1.24 M1.27 M1.28 M1.29 M1.30'>
</ProtocolAmount>
<CurrencyAmount ID ='M1.23'
Amount='20.00'
CurrCode='USD'/>
<CurrencyAmount ID ='M1.24'
Amount='12.00'
CurrCode='GBP'/>
<CurrencyAmount ID ='M1.25'
Amount='19.50'
CurrCode='USD'/>
<CurrencyAmount ID ='M1.26'
Amount='11.75'
CurrCode='GBP'/>
<CurrencyAmount ID ='M1.27'
Amount='36.00'
CurrCode='DEM'/>
<CurrencyAmount ID ='M1.28'
Amount='100.00'
CurrCode='FFR'/>
<CurrencyAmount ID ='M1.29'
Amount='22.00'
CurrCode='CAD'/>
<CurrencyAmount ID ='M1.30'
Amount='15000'
CurrCode='ITL'/>
<PayProtocol ID ='M1.31'
ProtocolId='MXv1.0'
ProtocolName='Mondex IOTP Protocol Version 1.0'
PayReqNetLocn='http://www.mxbankus.com/etill/mx' >
</PayProtocol>
<PayProtocol ID ='M1.32'
ProtocolId='MXv1.0'
ProtocolName='Mondex IOTP Protocol Version 1.0'
PayReqNetLocn='http://www.mxbankuk.com/vserver' >
</PayProtocol>
<PayProtocol ID ='M1.33'
ProtocolId='Ccashv1.0'
ProtocolName='CyberCoin Version 1.0'
PayReqNetLocn='http://www.cybercash.com/ccoin' >
</PayProtocol>
<PayProtocol ID ='M1.34'
ProtocolId='CCashv2.0'
ProtocolName='CyberCoin Version 2.0'
PayReqNetLocn='http://www.cybercash.com/ccoin' >
</PayProtocol>
<PayProtocol ID ='M1.35'
ProtocolId='GKv1.0'
ProtocolName='GeldKarte Version 1.0'
PayReqNetLocn='http://www.example.com/pgway' >
</PayProtocol>
<PayProtocol ID ='M1.36'
ProtocolId='DCashv1.0'
ProtocolName='DigiCash Protocol Version 1.0'
PayReqNetLocn='http://www.example.com/digicash' >
</PayProtocol>
</BrandList>12. IANA Considerations
bestie, this section is the paperwork part 📋✨ It explains which codes are controlled by IANA, and also how you can make up new codes for testing purposes that IANA doesn't control 🧪💖
12.1. Codes Controlled by IANA 💅
okay bestie, so IOTP needs its codes to stay in a controlled environment, otherwise things get messy fast 🙈 Clear meanings and no duplicate codes keep everyone interoperable ✨ [IANA] is the mechanism for this, as described in RFC 2434 💖
The element types and attribute names this procedure covers are in the table below, along with the initial values that are valid for each attribute 🎀 Here are a few things to keep in mind:
- the IETF Trade mailing list's email address is
ietf-trade@elistx.com - "Designated Experts" (see [IANA]) are appointed by the IESG 👑
Element Type/ Attribute Values
Attribute Name
Algorithm/ "sha1" - indicates that a [SHA1] authentication
Name will apply
(When Algorithm
is a child of an "signature" - indicates that authentication
AuthReq consists of the generation of a digital signature.
Component)
"Pay:ppp" where "ppp" may be set to any valid
value for "iotpbrand" (see below)
With the exception of Algorithms that begin with
"pay:", new values are allocated following review
on the IETF Trade mailing list and by the
Designated Expert.Note: the Algorithm element is likely to be eventually defined within the [DSIG] name space 🌸 The maintenance procedure here may need to vary over time, as the DSIG proposals become more widely adopted 🦋
Element Type/ Attribute Values
Attribute Name
Brand/BrandId The following list of initial BrandIds have been
taken from those Organisations that have applied
for SET certificates as at 1st June 1999:
"Amex" - American Express
"Dankort" - Dankort
"JCB" - JCB
"Maestro" - Maestro
"MasterCard" - MasterCard
"NICOS" - NICOS
"VISA" - Visa
In addition the following Brand Id values are
defined:
"Mondex"
"GeldKarte"
New values of BrandId must be announced to the
IETF Trade mailing list and, if there are no
objections within three weeks, are allocated on a
"first come first served" basis.
CurrencyAmount/ Currency codes are dependent on CurrCodeType (see
CurrCode below).
If CurrCodeType is "ISO4217-A" then the currency
code is an alphabetic currency code as defined by
[ISO4217].
If CurrCodeType is "IOTP" then new values must be
announced to the IETF Trade mailing list and, if
there are no objections within three weeks, are
allocated on a "first come first served" basis.Note: the Currency Code Type of IOTP is designed to allow the support of "new" psuedo currencies, such as loyalty or frequent flyer points ✈️ At the time of writing this specification, no currency codes of this type have been defined 🙈
Element Type/ Attribute Values
Attribute Name
CurrencyAmount/ "ISO4217-A"
CurrCodeType
"IOTP"
New values of CurrCodeType attribute are allocated
following review on the IETF Trade mailing list
and by the Designated Expert.
DeliveryData/ "Post"
DelivMethod
"Web"
"Email"
New values of Delivery Method attribute are
allocated following review on the IETF Trade
mailing list and by the Designated Expert. This
may require the publication of additional
documentation to describe how the delivery method
is used.
PackagedContent/ "PCDATA"
Content
"MIME"
"MIME:mimetype" (where mimetype must be the same
as content-type as defined by [MIME] )
"XML"
If the Content attribute is of the form
"MIME"mimetype", then control of new values for
"mimetype" is as defined in [MIME].
Otherwise, new values of the Content attribute are
allocated following review on the IETF Trade
mailing list and by the Designated Expert. This
may require the publication of additional
documentation to describe how the new attribute is
used within a Packaged Content element.
RelatedTo/ "IotpTransaction"
RelationshipType
"Reference"
New values of the RelationshipType attribute are
allocated following review on the IETF Trade
Working Group mailing list and by the Designated
Expert. This may require the publication of
additional documentation to describe how the
Element Type/ Attribute Values
Attribute Name
delivery method is used.
Status/ Offer
StatusType
Payment
Delivery
Authentication
Unidentified
New values of the Status Type attribute are
allocated following:
o publication to the IETF Trade Working Group,
of an RFC describing the Trading Exchange,
Trading Roles and associated components that
relate to the Status, and
o review of the document on the IETF Trade
mailing list and by the Designated Expert.Note: the document describing new values for the Status Type attribute may be combined with documents that describe new Trading Roles and types of signatures (see below) 🫶
TradingRole/ "Consumer"
TradingRole
"Merchant"
"PaymentHandler"
"DeliveryHandler"
"DelivTo"
"CustCare"
New values of the Trading Role attribute are
allocated following:
o publication to the IETF Trade Working Group,
of an RFC describing the Trading Exchange,
Trading Roles and associated components that
relate to the Trading Role, and
o review of the document on the IETF Trade
mailing list and by the Designated Expert.
Note: The document describing new values for the Trading Role
attribute may be
Element Type/ Attribute Values
Attribute Name
combined with documents that describe
new Status Types (see above) and
types of signatures (see below).
TransId/ "BaselineAuthentication"
IotpTransType
"BaselineDeposit"
"BaselinePurchase"
"BaselineRefund"
"BaselineWithdrawal"
"BaselineValueExchange"
"BaselineInquiry"
"BaselinePing"
New values of the IotpTransType attribute are
allocated following:
o publication to the IETF Trade mailing list, of
an RFC describing the new IOTP Transaction, and
o review of the document on the IETF Trade
Working Group mailing list and by the
Designated Expert.
Attribute/ Content
(see Signature
Component) "OfferResponse"
"PaymentResponse"
"DeliveryResponse"
"AuthenticationRequest"
"AuthenticationResponse"
"PingRequest"
"PingResponse"
New values of the code that define the type of a
signature are allocated following:
o publication to the IETF Trade Working Group,
of an RFC describing the Trading Exchange where
the signature is being used, and
o review of the document on the IETF Trade
mailing list and by the Designated Expert.
Element Type/ Attribute Values
Attribute Name
Note: The document describing new values for the types of signatures
may be combined with documents that describe new Status Types and
Trading Roles (see above).12.2. Codes not controlled by IANA 🎀
okay so even with all that formal registration, developers still need room to experiment with new IOTP codes 🧪 That's why "user defined codes" exist: they can identify extra values for the codes in this specification without being registered with IANA 🌈
A user defined code is defined like this:
user_defined_code ::= ( "x-" | "X-" ) NameChar (NameChar)*NameChar has the same definition as the [XML] definition of NameChar 💜
Using domain names (see [DNS]) to make user defined codes unique is recommended, although this method cannot be relied upon 🙈
13. Internet Open Trading Protocol Data Type Definition 🧚
This section contains the XML DTD for the Internet Open Trading Protocols 💖
<!--
******************************************************
* *
* INTERNET OPEN TRADING PROTOCOL VERSION 1.0 DTD *
* Filename: ietf.org/rfc/rfc2801.dtd *
* *
* Changes from version 07 (iotp-v1.0-protocol-07.dtd)*
* - NO CHANGES *
* *
* *
* *
* *
* Copyright Internet Engineering Task Force 1998-2000*
* *
******************************************************
******************************************************
* IOTP MESSAGE DEFINITION *
******************************************************
-->
<!ELEMENT IotpMessage
( TransRefBlk,
IotpSignatures?,
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' >okay the DTD is back bestie 💅 this part is all element and attribute definitions, so the whole vibe is pure structure 🎀
Starting with the Transaction Reference Block and its friends 🦋
<!--
******************************************************
* TRANSACTION REFERENCE BLOCK DEFINITION *
******************************************************
-->
<!ELEMENT TransRefBlk (TransId, MsgId, RelatedTo*) >
<!ATTLIST TransRefBlk
ID ID #REQUIRED >
<!ELEMENT TransId EMPTY >
<!ATTLIST TransId
ID ID #REQUIRED
Version NMTOKEN #FIXED '1.0'
IotpTransId CDATA #REQUIRED
IotpTransType CDATA #REQUIRED
TransTimeStamp CDATA #REQUIRED >
<!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 >
<!ELEMENT RelatedTo (PackagedContent) >
<!ATTLIST RelatedTo
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
RelationshipType NMTOKEN #REQUIRED
Relation CDATA #REQUIRED
RelnKeyWords NMTOKENS #IMPLIED >
<!--
******************************************************
* Packaged Content Common Element *
******************************************************
-->
<!ELEMENT PackagedContent (#PCDATA) >
<!ATTLIST PackagedContent
Name CDATA #IMPLIED
Content NMTOKEN "PCDATA"
Transform (NONE|BASE64) "NONE" >
<!--
******************************************************
* TRADING COMPONENTS *
******************************************************
-->the trading components are next and they're giving main character energy 🌸
<!-- PROTOCOL OPTIONS COMPONENT -->
<!ELEMENT ProtocolOptions EMPTY >
<!ATTLIST ProtocolOptions
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
ShortDesc CDATA #REQUIRED
SenderNetLocn CDATA #IMPLIED
SecureSenderNetLocn CDATA #IMPLIED
SuccessNetLocn CDATA #REQUIRED >
<!-- AUTHENTICATION DATA COMPONENT -->
<!ELEMENT AuthReq (Algorithm, PackagedContent*)>
<!ATTLIST AuthReq
ID ID #REQUIRED
AuthenticationId CDATA #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
<!-- AUTHENTICATION RESPONSE COMPONENT -->
<!ELEMENT AuthResp (PackagedContent*) >
<!ATTLIST AuthResp
ID ID #REQUIRED
AuthenticationId CDATA #REQUIRED
SelectedAlgorithmRef NMTOKEN #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
<!-- TRADING ROLE INFO REQUEST COMPONENT -->
<!ELEMENT TradingRoleInfoReq EMPTY>
<!ATTLIST TradingRoleInfoReq
ID ID #REQUIRED
TradingRoleList NMTOKENS #REQUIRED >
<!-- ORDER COMPONENT -->
<!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 >
<!-- ORGANISATION COMPONENT -->
<!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 >
<!ELEMENT TradingRole EMPTY >
<!ATTLIST TradingRole
ID ID#REQUIRED
TradingRole NMTOKEN #REQUIRED
IotpMsgIdPrefix NMTOKEN #REQUIRED
CancelNetLocn CDATA #IMPLIED
ErrorNetLocn CDATA #IMPLIED
ErrorLogNetLocn CDATA #IMPLIED >
<!ELEMENT ContactInfo EMPTY >
<!ATTLIST ContactInfo
xml:lang NMTOKEN #IMPLIED
Tel CDATA #IMPLIED
Fax CDATA #IMPLIED
Email CDATA #IMPLIED
NetLocn CDATA #IMPLIED >
<!ELEMENT PersonName EMPTY >
<!ATTLIST PersonName
xml:lang NMTOKEN #IMPLIED
Title CDATA #IMPLIED
GivenName CDATA #IMPLIED
Initials CDATA #IMPLIED
FamilyName CDATA #IMPLIED >
<!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' >the brand list is where the money stuff starts and it's sooo iconic 💖
<!-- BRAND LIST COMPONENT -->
<!ELEMENT BrandList (Brand+, ProtocolAmount+,
CurrencyAmount+, PayProtocol+) >
<!ATTLIST BrandList
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
ShortDesc CDATA #REQUIRED
PayDirection (Debit | Credit) #REQUIRED >
<!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 >
<!ELEMENT ProtocolBrand (PackagedContent*) >
<!ATTLIST ProtocolBrand
ProtocolId CDATA #REQUIRED
ProtocolBrandId CDATA #REQUIRED >
<!ELEMENT ProtocolAmount (PackagedContent*) >
<!ATTLIST ProtocolAmount
ID ID #REQUIRED
PayProtocolRef IDREF #REQUIRED
CurrencyAmountRefs IDREFS #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
<!ELEMENT CurrencyAmount EMPTY >
<!ATTLIST CurrencyAmount
ID ID #REQUIRED
Amount CDATA #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED >
<!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 >
<!-- BRAND SELECTION COMPONENT -->
<!ELEMENT BrandSelection (BrandSelBrandInfo?,
BrandSelProtocolAmountInfo?,
BrandSelCurrencyAmountInfo?) >
<!ATTLIST BrandSelection
ID ID #REQUIRED
BrandListRef NMTOKEN #REQUIRED
BrandRef NMTOKEN #REQUIRED
ProtocolAmountRef NMTOKEN #REQUIRED
CurrencyAmountRef NMTOKEN #REQUIRED >
<!ELEMENT BrandSelBrandInfo (PackagedContent+) >
<!ATTLIST BrandSelBrandInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
<!ELEMENT BrandSelProtocolAmountInfo (PackagedContent+) >
<!ATTLIST BrandSelProtocolAmountInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
<!ELEMENT BrandSelCurrencyAmountInfo (PackagedContent+) >
<!ATTLIST BrandSelCurrencyAmountInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >payment, receipts, and delivery next, and ngl the naming is so consistent it's almost a vibe 🦋
<!-- PAYMENT COMPONENT -->
<!ELEMENT Payment EMPTY >
<!ATTLIST Payment
ID ID #REQUIRED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
BrandListRef NMTOKEN #REQUIRED
SignedPayReceipt (True | False) #REQUIRED
StartAfterRefs NMTOKENS #IMPLIED >
<!-- PAYMENT SCHEME COMPONENT -->
<!ELEMENT PaySchemeData (PackagedContent+) >
<!ATTLIST PaySchemeData
ID ID #REQUIRED
PaymentRef NMTOKEN #IMPLIED
ConsumerPaymentId CDATA #IMPLIED
PaymentHandlerPayId CDATA #IMPLIED
ContentSoftwareId CDATA #IMPLIED >
<!-- PAYMENT RECEIPT COMPONENT -->
<!ELEMENT PayReceipt (PackagedContent*) >
<!ATTLIST PayReceipt
ID ID #REQUIRED
PaymentRef NMTOKEN #REQUIRED
PayReceiptNameRefs NMTOKENS #IMPLIED
ContentSoftwareId CDATA #IMPLIED >
<!-- PAYMENT NOTE COMPONENT -->
<!ELEMENT PaymentNote (PackagedContent+) >
<!ATTLIST PaymentNote
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
<!-- DELIVERY COMPONENT -->
<!ELEMENT Delivery (DeliveryData?, PackagedContent*) >
<!ATTLIST Delivery
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
DelivExch (True | False) #REQUIRED
DelivAndPayResp (True | False) #REQUIRED
ActionOrgRef NMTOKEN #IMPLIED >
<!ELEMENT DeliveryData (PackagedContent*) >
<!ATTLIST DeliveryData
xml:lang NMTOKEN #IMPLIED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
DelivMethod NMTOKEN #REQUIRED
DelivToRef NMTOKEN #REQUIRED
DelivReqNetLocn CDATA #IMPLIED
SecDelivReqNetLocn CDATA #IMPLIED
ContentSoftwareId CDATA #IMPLIED >
<!-- CONSUMER DELIVERY DATA COMPONENT -->
<!ELEMENT ConsumerDeliveryData EMPTY >
<!ATTLIST ConsumerDeliveryData
ID ID #REQUIRED
ConsumerDeliveryId CDATA #REQUIRED >
<!-- DELIVERY NOTE COMPONENT -->
<!ELEMENT DeliveryNote (PackagedContent+) >
<!ATTLIST DeliveryNote
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
DelivHandlerDelivId CDATA #IMPLIED
ContentSoftwareId CDATA #IMPLIED >status, trading role data, inquiries, and errors are up next, and the error section is giving dramatic 😭
<!-- STATUS COMPONENT -->
<!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 >
<!-- TRADING ROLE DATA COMPONENT -->
<!ELEMENT TradingRoleData (PackagedContent+) >
<!ATTLIST TradingRoleData
ID ID #REQUIRED
OriginatorElRef NMTOKEN #REQUIRED
DestinationElRefs NMTOKENS #REQUIRED >
<!-- INQUIRY TYPE COMPONENT -->
<!ELEMENT InquiryType EMPTY >
<!ATTLIST InquiryType
ID ID #REQUIRED
Type NMTOKEN #REQUIRED
ElRef NMTOKEN #IMPLIED
ProcessReference CDATA #IMPLIED >
<!-- ERROR COMPONENT -->
<!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 >
<!ELEMENT ErrorLocation EMPTY >
<!ATTLIST ErrorLocation
ElementType NMTOKEN #REQUIRED
IotpMsgRef NMTOKEN #IMPLIED
BlkRef NMTOKEN #IMPLIED
CompRef NMTOKEN #IMPLIED
ElementRef NMTOKEN #IMPLIED
AttName NMTOKEN #IMPLIED >last bit for this part: the trading blocks section 🌈✨
<!--
******************************************************
* TRADING BLOCKS *
******************************************************
-->
<!-- TRADING PROTOCOL OPTIONS BLOCK -->
<!ELEMENT TpoBlk ( ProtocolOptions, BrandList*, Org* ) >
<!ATTLIST TpoBlk
ID ID #REQUIRED >that's the whole chunk, the DTD keeps going in the next part 🧚💜
<!-- TPO SELECTION BLOCK -->
<!ELEMENT TpoSelectionBlk (BrandSelection+) >
<!ATTLIST TpoSelectionBlk
ID ID #REQUIRED >
<!-- OFFER RESPONSE BLOCK -->
<!ELEMENT OfferRespBlk (Status, Order?, Payment*,
Delivery?, TradingRoleData*) >
<!ATTLIST OfferRespBlk
ID ID #REQUIRED >
<!-- AUTHENTICATION REQUEST BLOCK -->
<!ELEMENT AuthReqBlk (AuthReq*, TradingRoleInfoReq?) >
<!ATTLIST AuthReqBlk
ID ID #REQUIRED >
<!-- AUTHENTICATION RESPONSE BLOCK -->
<!ELEMENT AuthRespBlk (AuthResp?, Org*) >
<!ATTLIST AuthRespBlk
ID ID #REQUIRED >
<!-- AUTHENTICATION STATUS BLOCK -->
<!ELEMENT AuthStatusBlk (Status) >
<!ATTLIST AuthStatusBlk
ID ID #REQUIRED >
<!-- PAYMENT REQUEST BLOCK -->
<!ELEMENT PayReqBlk (Status+, BrandList, BrandSelection,
Payment, PaySchemeData?, Org*, TradingRoleData*) >
<!ATTLIST PayReqBlk
ID ID #REQUIRED >
<!-- PAYMENT EXCHANGE BLOCK -->
<!ELEMENT PayExchBlk (PaySchemeData) >
<!ATTLIST PayExchBlk
ID ID #REQUIRED >
<!-- PAYMENT RESPONSE BLOCK -->
<!ELEMENT PayRespBlk (Status, PayReceipt?, PaySchemeData?,
PaymentNote?, TradingRoleData*) >
<!ATTLIST PayRespBlk
ID ID #REQUIRED >
<!-- DELIVERY REQUEST BLOCK -->
<!ELEMENT DeliveryReqBlk (Status+, Order, Org*, Delivery,
ConsumerDeliveryData?, TradingRoleData*) >
<!ATTLIST DeliveryReqBlk
ID ID #REQUIRED >
<!-- DELIVERY RESPONSE BLOCK -->
<!ELEMENT DeliveryRespBlk (Status, DeliveryNote) >
<!ATTLIST DeliveryRespBlk
ID ID #REQUIRED >
<!-- INQUIRY REQUEST BLOCK -->
<!ELEMENT InquiryReqBlk ( InquiryType, PaySchemeData? ) >
<!ATTLIST InquiryReqBlk
ID ID #REQUIRED >
<!-- INQUIRY RESPONSE BLOCK -->
<!ELEMENT InquiryRespBlk (Status, PaySchemeData?) >
<!ATTLIST InquiryRespBlk
ID ID #REQUIRED
LastReceivedIotpMsgRef NMTOKEN #IMPLIED
LastSentIotpMsgRef NMTOKEN #IMPLIED >
<!-- PING REQUEST BLOCK -->
<!ELEMENT PingReqBlk (Org*)>
<!ATTLIST PingReqBlk
ID ID #REQUIRED>
<!-- PING RESPONSE BLOCK -->
<!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>
<!-- ERROR BLOCK -->
<!ELEMENT ErrorBlk (ErrorComp+, PaySchemeData*) >
<!ATTLIST ErrorBlk
ID ID #REQUIRED >
<!-- CANCEL BLOCK -->
<!ELEMENT CancelBlk (Status) >
<!ATTLIST CancelBlk
ID ID #REQUIRED >
<!--
******************************************************
* IOTP SIGNATURES BLOCK DEFINITION *
******************************************************
-->
<!ELEMENT IotpSignatures (Signature+ ,Certificate*) >
<!ATTLIST IotpSignatures
ID ID #IMPLIED
>
<!--
******************************************************
* IOTP SIGNATURE COMPONENT DEFINITION *
******************************************************
-->
<!ELEMENT Signature (Manifest, Value+) >
<!ATTLIST Signature
ID ID #IMPLIED
>
<!ELEMENT Manifest
( Algorithm+,
Digest+,
Attribute*,
OriginatorInfo,
RecipientInfo+
)
>
<!ATTLIST Manifest
LocatorHRefBase CDATA #IMPLIED
>
<!ELEMENT Algorithm (Parameter*) >
<!ATTLIST Algorithm
ID ID #REQUIRED
type (digest|signature) #IMPLIED
name NMTOKEN #REQUIRED
>
<!ELEMENT Digest (Locator, Value) >
<!ATTLIST Digest
DigestAlgorithmRef IDREF #REQUIRED
>
<!ELEMENT Attribute ( ANY ) >
<!ATTLIST Attribute
type NMTOKEN #REQUIRED
critical ( true | false ) #REQUIRED
>
<!ELEMENT OriginatorInfo ANY >
<!ATTLIST OriginatorInfo
OriginatorRef NMTOKEN #IMPLIED
>
<!ELEMENT RecipientInfo ANY >
<!ATTLIST RecipientInfo
SignatureAlgorithmRef IDREF #REQUIRED
SignatureValueRef IDREF #IMPLIED
SignatureCertRef IDREF #IMPLIED
RecipientRefs NMTOKENS #IMPLIED
>
<!ELEMENT KeyIdentifier EMPTY>
<!ATTLIST KeyIdentifier
value CDATA #REQUIRED
>
<!ELEMENT Parameter ANY >
<!ATTLIST Parameter
type CDATA #REQUIRED
>
<!--
******************************************************
* IOTP CERTIFICATE COMPONENT DEFINITION *
******************************************************
-->
<!ELEMENT Certificate
( IssuerAndSerialNumber, ( Value | Locator ) )
>
<!ATTLIST Certificate
ID ID #IMPLIED
type NMTOKEN #REQUIRED
>
<!ELEMENT IssuerAndSerialNumber EMPTY >
<!ATTLIST IssuerAndSerialNumber
issuer CDATA #REQUIRED
number CDATA #REQUIRED
>
<!--
******************************************************
* IOTP SHARED COMPONENT DEFINITION *
******************************************************
-->
<!ELEMENT Value ( #PCDATA ) >
<!ATTLIST Value
ID ID #IMPLIED
encoding (base64|none) 'base64'
>
<!ELEMENT Locator EMPTY>
<!ATTLIST Locator
xml:link CDATA #FIXED 'simple'
href CDATA #REQUIRED
>14. Glossary ✨
okay so the glossary is basically our little cheat sheet 📖 for the words used all through this spec, sorted alphabetically so you can find things fast 💅
- Authenticator 🔐: the Organisation that asks for another Organisation to be authenticated
- Authenticatee 🪪: the Organisation being authenticated by an Authenticator
- Business Error 🙈: see Status Component
- Brand 🏷️: a Brand is the mark that identifies a particular type of Payment Instrument. A list of Brands is the set of payment options the Merchant shows the Consumer, and the Consumer picks one from that list. Each Brand may have a different Payment Handler. Examples include:
- payment association and proprietary Brands, like MasterCard, Visa, American Express, Diners Club, American Express, Mondex, GeldKarte, CyberCash, etc. 💳
- Promotional Brands (see below). These include:
- store Brands, where the Payment Instrument is issued to a Consumer by a particular Merchant, like Walmart, Sears, or Marks and Spencer (UK) 🛍️
- coBrands, like American Advantage Visa, where a company uses its own Brand together with, typically, a payment association Brand 🤝
- Consumer 🛒: the Organisation that is to receive the benefit of the goods or services and typically pays for them 💖
- ContentSoftwareId 🧾: this contains information that identifies the software which generated the content of the element. Its whole purpose is to help sort out interoperability problems that can happen when messages from different software don't match up 🔧. It is a single text string in the language defined by xml:lang. It must contain, as a minimum:
- the name of the software manufacturer
- the name of the software
- the version of the software, and
- the build of the software
It is recommended that this attribute is included whenever the software which generated the content cannot be identified from the SoftwareId attribute on the Message Id Component (see section 3.3.2) ✨
- Customer Care Provider 🎧: an Organisation that provides customer care, typically on behalf of a Merchant. Examples of customer care include responding to problems raised by a Consumer that arise from an IOTP Transaction the Consumer took part in 🫶
- Delivery Handler 📦: the Organisation that directly delivers the goods or services to the Consumer on behalf of the Merchant. Delivery can be digital goods (for example, a [MIME] message) or physical, sent by post or courier 🚚
- Document Exchange 📨: a Document Exchange is a set of IOTP Messages exchanged between two parties that implement part or all of two Trading Exchanges at the same time, so that fewer actual IOTP Messages have to be sent over the Internet 🦋
Document Exchanges are chained together in sequence to implement a particular IOTP Transaction 🧚
- Dual Brand 👑: a Dual Brand means that a single Payment Instrument may be used as if it were two separate Brands. For example, there could be a single Japanese "UC" MasterCard that can be used as either a UC card or a regular MasterCard. The UC card Brand and the MasterCard Brand could each have their own separate Payment Handlers. This means that:
- the Merchant treats, for example, "UC" and "MasterCard" as two separate Brands when offering a list of Brands to the Consumer,
- the Consumer chooses a Brand, for example either "UC" or "MasterCard", and
- the Consumer IOTP aware application determines which Payment Instrument(s) match the chosen Brand, and selects, perhaps with user assistance, the correct Payment Instrument to use 💅
Okay bestie, let's finish off the glossary 💅✨
Error Block 🚨 An Error Block reports that a Technical Error was found in an IOTP Message that was previously received. Usually, Technical Errors come from XML that got mangled in transit or from some technical failure while the IOTP Message was being processed. Generating or receiving an Error Block often ends in the IOTP Transaction failing 💀. Error Blocks are totally different from Business Errors, which get reported in a Status Component and can also make an IOTP Transaction fail.
Exchange Block 🦋 An Exchange Block gets sent between the two Trading Roles taking part in a Trading Exchange. It holds one or more Trading Components. Exchange Blocks are always sent after a Request Block and before a Response Block in a Trading Exchange. What's inside an Exchange Block depends on the type of Trading Exchange happening.
IOTP Message 💌 An IOTP Message is the outermost wrapper for the documents passed between the Trading Roles in a trade. It's a well formed XML document. The documents it can contain are:
- a Transaction Reference Block, which uniquely identifies the IOTP Transaction the IOTP Message belongs to,
- an optional Signature Block, which digitally signs the Trading Blocks or Trading Components associated with the IOTP Transaction,
- an optional Error Block, which reports technical errors in a previously received IOTP Message, and
- a collection of IOTP Trading Blocks, which carries the data needed to carry out an IOTP Transaction.
IOTP Transaction 🛍️ An IOTP Transaction is one instance of an Internet Open Trading Protocol Transaction. It's made up of a set of IOTP Messages passed between Trading Roles. The rules for what can go in those IOTP Messages are set by the IOTP Transaction's Transaction Type.
IOTP Transaction Type 🎀 A Transaction Type tells you what kind of IOTP Transaction it is. Examples of Transaction Type include: Purchase, Refund, Authentication, Withdrawal, and Deposit (of electronic cash). For an IOTP Transaction, the Transaction Type specifies:
- which Trading Exchanges may be included in the transaction,
- how those Trading Exchanges may be combined to meet the business needs of the transaction,
- which Trading Blocks may be included in the IOTP Messages that make up the transaction.
Consult this specification for the rules that apply to each Transaction Type 📖.
Merchant 🏪 The Organisation the service or goods are being obtained from. It's legally responsible for providing the goods or services and receives the benefit of any payment made.
Merchant Customer Care Provider 🫶 The Organisation involved in negotiating and resolving customer disputes on behalf of the Merchant.
Organisation 🌸 A company or individual that takes part in a Trade as a Trading Role. An Organisation may take on one or more of the roles involved in the Trade.
Payment Handler 💜 The Organisation that physically receives the payment from the Consumer on behalf of the Merchant.
Payment Instrument 💳 A Payment Instrument is the means by which a Consumer pays for goods or services offered by a Merchant. Examples include:
- a credit card such as MasterCard or Visa;
- a debit card such as MasterCard's Maestro;
- a smart card based electronic cash Payment Instrument such as a Mondex Card, a GeldKarte card or a Visa Cash card;
- a software based electronic payment account such as a CyberCash's CyberCoin or DigiCash account.
All Payment Instruments have a number, typically an account number, that identifies the Payment Instrument.
Promotional Brand 🎁 A Promotional Brand means that if the Consumer pays with that Brand, they get some extra benefit. That benefit can come in two ways:
- at the time of purchase. For example, if a Consumer pays with a "Walmart MasterCard" at a Walmart web site, a 5% discount might apply, so the Consumer actually pays less,
- from their Payment Instrument (card) issuer when the payment shows up on their statement. For example, loyalty points in a frequent flyer scheme could be awarded based on the total payments made with the Payment Instrument since the last statement was issued.
Each Promotional Brand should be identified as a separate Brand in the list of Brands offered by the Merchant. 👑
Receipt Component 🧾 A Receipt Component is a record of the successful completion of a Trading Exchange. Examples include Payment Receipts and Delivery Notes. Its content may depend on the technology used to perform the Trading Exchange. For example, a Secure Electronic Transaction (SET) payment receipt consists of SET payment messages that record the result of the payment.
Request Block 📨 A Request Block is a Trading Block that contains a request for a Trading Exchange to start. The Trading Components in a Request Block may be signed by a Signature Block, so their authenticity can be checked and it can be determined that the requested Trading Exchange is authorised. Authorisation for a Trading Exchange to start can be provided by the signatures on Receipt Components contained in Response Blocks from previously completed Trading Exchanges. Examples of Request Blocks are Payment Request and Delivery Request.
Response Block 📬 A Response Block is a Trading Block that indicates a Trading Exchange is complete. It's sent by the Trading Role that received a Request Block back to the Trading Role that sent it. The Response Block contains a Status Component with information about how the Trading Exchange completed, for example whether it finished successfully. For some Trading Exchanges, the Response Block also contains a Receipt Component that forms a record of the Trading Exchange. Receipt Components may be digitally signed using a Signature Block to make completion non-refutable. Examples of Response Blocks include Offer Response, Payment Response and Delivery Response.
Signature Block ✍️ A Signature Block is a Trading Block that contains one or more digital signatures in the form of Signature Components. A Signature Component may digitally sign any Block or Component in any IOTP Message in the same IOTP Transaction.
Status Component 🔍 A Status Component contains information describing the state of a Trading Exchange.
Before the Trading Exchange is complete, the Status Component can indicate how the Trading Exchange is progressing.
Once a Trading Exchange is complete, the Status Component can only indicate that the Trading Exchange succeeded or that a Business Error has occurred.
A Business Error means continuing the Trading Exchange wasn't possible because of some business rule or logic, for example "insufficient funds available". It's not a Technical Error related to the content or format of the IOTP Messages in the IOTP Transaction. 🙅♀️
Technical Error 🔧 See Error Block.
Trading Block 🧩 A Trading Block consists of one or more Trading Components. One or more Trading Blocks may be contained within the IOTP Messages that get physically sent as [XML] documents between the different Trading Roles taking part in a trade. There are three main types of Trading Block:
- a Request Block,
- an Exchange Block, or
- a Response Block.
Trading Component 🌈 A Trading Component is a collection of XML elements and attributes. Trading Components are the child elements of Trading Blocks. Examples of Trading Components are: Offer, Brand List, Payment Receipt, Delivery [information], and Payment Amount [information].
Okay bestie, the glossary is still going, so let's finish it off 💅✨
Trading Exchange 🦋 A Trading Exchange is when two Trading Roles pass a sequence of documents back and forth. Those documents can be Trading Blocks, or they can move some other way, like typing data into a web page. Every Trading Exchange has three main parts:
- one Trading Role (the initiator) sends a Request Block to another Trading Role (the recipient),
- then the recipient and the initiator can optionally swap one or more Exchange Blocks, until eventually,
- the Trading Role that got the Request Block sends a Response Block back to the initiator.
A Trading Exchange is built to power some kind of useful service 🎀 Some examples are:
- Offer, where a Consumer gets an offer from a Merchant to do some kind of business transaction,
- Payment, where a Consumer pays a Payment Handler,
- Delivery, where a Consumer asks for delivery of goods or services from a Delivery Handler and can optionally get them, and
- Authentication, where any Trading Role can ask for and receive info about another Trading Role.
Trading Role 👑 A Trading Role describes the different ways Organisations can take part in a trade. There are five of them: Consumer, Merchant, Payment Handler, Delivery Handler, and Merchant Customer Care Provider. Five main characters, no cap 💜
Transaction Reference Block 🧚 A Transaction Reference Block identifies an IOTP Transaction. It holds data that identifies:
- the Transaction Type,
- the IOTP Transaction uniquely, through a globally unique transaction identifier,
- the IOTP Message uniquely within the IOTP Transaction, through a message identifier.
It can also hold references to other transactions, which may or may not be IOTP Transactions. Iconic 😭
15. References ✨
This section is where we list all the related documents this specification points to 📚
[Base64] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996.
[DOM-HASH] Maruyama, H., Tamura, K. and N. Uramoto, "Digest Values for DOM (DOMHASH)", RFC 2803, April 2000.
[DNS] Mockapetris, P., "Domain names - concepts and facilities", STD 13, RFC 1034, November 1987.
[DNS] Mockapetris, P., "Domain names - implementation and specification", STD 13, RFC 1035, November 1987.
[DSA] The Digital Signature Algorithm (DSA) published by the National Institute of Standards and Technology (NIST) in the Digital Signature Standard (DSS), which is a part of the US government's Capstone project. 🔥
[ECCDSA] Elliptic Curve Cryptosystems Digital Signature Algorithm (ECCDSA). Elliptic curve cryptosystems are analogues of public-key cryptosystems such as RSA in which modular multiplication is replaced by the elliptic curve addition operation. See: V. S. Miller. Use of elliptic curves in cryptography. In Advances in Cryptology - Crypto '85, pages 417-426, Springer-Verlag, 1986.
[HMAC] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997.
[HTML] Berners-Lee, T. and D. Connolly, "Hypertext Markup Language - 2.0", RFC 1866, November 1995.
[HTML] Hyper Text Mark Up Language. The Hypertext Mark-up Language (HTML) is a simple mark-up language used to create hypertext documents that are platform independent. See the World Wide Web (W3C) consortium web site at: http://www.w3.org/MarkUp/ 🌸
[HTTP] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996.
[HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, T. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1.", RFC 2616, June 1999.
[IANA] The Internet Assigned Numbers Authority. The organisation responsible for co-ordinating the names and numbers associated with the Internet. See http://www.iana.org/ 🌈
[ISO4217] ISO 4217: Codes for the Representation of Currencies. Available from ANSI or ISO. 💰
[IOTPDSIG] Davidson, K. and Y. Kawatsura, "Digital Signatures for the v1.0 Internet Open Trading Protocol (IOTP)", RFC 2802, April 2000.
[MD5] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April 1992.
[MIME] Crocker, D., "Standard for the Format of ARPA Internet Text Messages", STD 11, RFC 822, August 1982.
[MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996.
[MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, November 1996.
[MIME] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text" RFC 2047, November 1996.
[MIME] Freed, N., Klensin, J. and J. Postel, "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures", RFC 2048, November 1996.
[MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples" RFC 2049, November 1996.
[OPS] Open Profiling Standard. A proposed standard which provides a framework with built-in privacy safeguards for the trusted exchange of profile information between individuals and web sites. Being developed by Netscape and Microsoft amongst others. 🫶
[RFC1738] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, December 1994.
[RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 1998.
[RSA] RSA is a public-key cryptosystem for both encryption and authentication supported by RSA Data Security Inc. See: R. L. Rivest, A. Shamir, and L.M. Adleman. A method for obtaining digital signatures and public-key cryptosystems. Communications of the ACM, 21(2): 120-126, February 1978. 🔐
[SCCD] Secure Channel Credit Debit. A method of conducting a credit or debit card payment where unauthorised access to account information is prevented through use of secure channel transport mechanisms such as SSL/TLS. An IOTP supplement describing how SCCD works is under development. 💳
[SET] Secure Electronic Transaction Specification, Version 1.0, May 31, 1997. Supports credit and debit card payments using certificates at the Consumer and Merchant to help ensure authenticity. Download from: <http://www.setco.org>.
[SSL/TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999.
[SHA1] [FIPS-180-1]"Secure Hash Standard", National Institute of Standards and Technology, US Department Of Commerce, April 1995. Also known as: 59 Fed Reg. 35317 (1994). See http://www.itl.nist.gov/div897/pubs/fip180-1.htm
[UTC] Universal Time Co-ordinated. A method of defining time absolutely relative to Greenwich Mean Time (GMT). Typically of the form: "CCYY-MM-DDTHH:MM:SS.sssZ+n" where the "+n" defines the number of hours from GMT. See ISO DIS8601. ⏰
[UTF16] The Unicode Standard, Version 2.0. The Unicode Consortium, Reading, Massachusetts. See ISO/IEC 10646 1 Proposed Draft Amendment 1
[X.509] ITU Recommendation X.509 1993 | ISO/IEC 9594-8: 1995, Including Draft Amendment 1: Certificate Extensions (Version 3 Certificate)
[XML Namespace] Recommendation for Namespaces in XML, World Wide Web Consortium, 14 January 1999, "http://www.w3.org/TR/REC-xml-names"
[XML] Extensible Mark Up Language. A W3C recommendation. See http://www.w3.org/TR/1998/REC-xml-19980210 for the 10 February 1998 version. That's the reference list wrapped up, and there's a lot of good stuff in it 🦋
16. Author's Address ✨
okay so this is the part where the author gets their flowers 💐 and I'm obsessed with how many people they thanked 🫶
The author of this document is:
David Burdett Commerce One 4440 Rosewood Drive, Bldg 4 Pleasanton California 94588 USA
Phone: +1 (925) 520 4422 EMail: david.burdett@commerceone.com
The author of this document particularly wants to thank Mondex International Limited (www.mondex.com) for the tremendous support provided in the formative stages of the development of this specification. 🌸 Mondex really showed up early on, bestie, and that absolutely matters.
In addition the author appreciates the following contributors to this protocol (in alphabetic order of company) without which it could not have been developed. 💖 Literally a whole crew of legends:
- Phillip Mullarkey, British Telecom plc
- Andrew Marchewka, Canadian Imperial Bank of Commerce
- Brian Boesch, CyberCash Inc.
- Tom Arnold, CyberSource
- Terry Allen, Commerce One (formally Veo Systems)
- Richard Brown, GlobeSet Inc.
- Peter Chang, Hewlett Packard
- Masaaki Hiroya, Hitachi Ltd
- Yoshiaki Kawatsura, Hitachi Ltd
- Mark Linehan, International Business Machines
- Jonathan Sowler, JCP Computer Services Ltd
- John Wankmueller, MasterCard International
- Steve Fabes, Mondex International Ltd
- Donald Eastlake 3rd, Motorola Inc (formerly International Business Machines Inc)
- Surendra Reddy, Oracle Corporation
- Akihiro Nakano, Plat Home, Inc. (ex Hitachi Ltd)
- Chris Smith, Royal Bank of Canada
- Hans Bernhard-Beykirch, SIZ (IT Development and Coordination Centre of the German Savings Banks Organisation)
- W. Reid Carlisle, Spyrus (ex Citibank Universal Card Services, formally AT&T Universal Card Services)
- Efrem Lipkin, Sun Microsystems
- Tony Lewis, Visa International
The author would also like to thank the following organisations for their support: 🎀
- Amino Communications
- DigiCash
- Fujitsu
- General Information Systems
- Globe Id Software
- Hyperion
- InterTrader
- Nobil I T Corp
- Mercantec
- Netscape
- Nippon Telegraph and Telephone Corporation
- Oracle Corporation
- Smart Card Integrations Ltd.
- Spyrus
- Verifone
- Unisource nv
- Wells Fargo Bank
17. Full Copyright Statement 🦋
Copyright (C) The Internet Society (2000). All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement 🌈
Funding for the RFC Editor function is currently provided by the Internet Society. 💜 That's the whole document, bestie, you finished the glow-up! 👑
📦 where this page comes from
- ietf: rfc2801 2000-04
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms