4.3.3 Block Level
A Block level error indicates a problem with a block or one of its
components in an IOTP message (apart from Transaction Reference or
Signature Blocks). The message has been transported properly, the
overall message structure and the block/component(s) including the
Transaction Reference and Signature Blocks are meaningful but there
is some error related to one of the other blocks.
Block level errors can be either:
o technical errors, or
o business errors
Technical Errors are further divided into:
o Block Level Attribute and Element Checks, and
o Block and Component Consistency Checks
o Transient Technical Errors
If a technical error occurs related to a block or component, then an
Error Component is generated for return.
4.3.3.1 Block Level Attribute and Element Checks
Block Level Attribute and Element Checks occur only within the same
block. Checks which involve cross-checking against other blocks are
covered by Block and Component Consistency Checks.
The Block Level Attribute & Element checks are:
o checking that each attribute value within each element in a block
conforms to any rules contained within this IOTP specification
o checking that the content of each element conforms to any rules
contained within this IOTP specification
o 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
Block and Component Consistency Checks consist of:
o checking that the combination of blocks and/or components present
in the IOTP Message are consistent with the rules contained within
this IOTP specification
o checking for consistency between attributes and element content
within the blocks within the same IOTP message.
o checking for consistency between attributes and elements in blocks
in this IOTP message and 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 is processed
either by the IOTP Aware application or perhaps by some "back-end"
system such as a payment server.
4.3.3.3 Transient Technical Errors
During the processing of the Block some temporary failure may occur
that can potentially be recovered by the other trading role re-
transmitting, at some slightly later time, the original message that
they sent. In this case the other role is informed of the Transient
Error by sending them an Error Component (see section 7.21) with the
Severity Attribute set to TransientError and the MinRetrySecs
attribute set to some value suitable for the Transport Mechanism
and/or payment protocol being used (see appropriate Transport and
payment protocol Supplements).
Note that transient technical errors can be generated by any of the
Trading Roles involved in transaction.
4.3.3.4 Block Level Business Errors
If a business error occurs in a process such as a Payment or a
Delivery, then the appropriate type of response block is returned
containing a Status Component (see section 7.16) with the
ProcessState attribute set to Failed and the CompletionCode
indicating the nature of the problem.
Some business errors may be "transient" in that the Consumer role may
be able to recover and complete the transaction in some other way.
For example if the Credit Card that a consumer provided had
insufficient funds for a purchase, then the Consumer may recover by
using a different credit card.
Recovery from "transient" business errors is dependent on the
CompletionCode. See the definition of the Status Component for what
is possible.
Note that no Error Component or Error Block is generated for business
errors.
4.4 Idempotency, Processing Sequence, and Message Flow
IOTP messages are actually a combination of blocks and components as
described in 3.1.1 IOTP Message Structure. Especially in future
extensions of IOTP, a rich variety of combinations of such blocks and
components can occur. It is important that the multiple
transmission/receipt of the "same" request for an action that will
change state does not result in that action occurring more than once.
This is called idempotency. For example, a customer paying for an
order would want to pay the full amount only once. Most network
transport mechanisms have some probability of delivering a message
more than once or not at all, perhaps requiring retransmission. On
the other hand, a request for status can reasonably be repeated and
should be processed fresh each time it is received.
Correct implementation of IOTP can be modelled by a particular
processing order as detailed below. Any other method that is
indistinguishable in the messages sent between the parties is equally
acceptable.
4.5 Server Role Processing Sequence
"Server roles" are any Trading Role which is not the Consumer role.
They are "Server roles" since they typically receive a request which
they must service and then produce a response. However server roles
can also initiate transactions. More specifically Server Roles must
be able to:
o Initiate a transaction (see section 4.5.1). These are divided
into:
- payment related transactions and
- infrastructure transactions
o 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 that process the
input message are too busy to handle it
- processing the message if it is error free, authorised and, if
appropriate, producing a response to send back to the other
role
o Cancel a current transaction if requested (see section 4.5.3)
o Re-transmit messages if a response was expected but has not been
received in a reasonable time (see section 4.5.4).
4.5.1 Initiating Transactions
Server Roles may initiate a variety of different types of
transaction. Specifically:
o an Inquiry Transaction (see section 9.2.1)
o a Ping Transaction (see section 9.2.2)
o an Authentication Transaction (see section 9.1.6)
o 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:
o checking the structure and identity of the message
o checking for and handling duplicate messages
o 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) within the IOTP message can be successfully identified
since an IotpTransId will be needed to generate a response.
If the input message is not well formed then generate an Error
Component with a Severity of HardError and ErrorCode of
XmlNotWellFrmd.
If the message is well formed but the IotpTransId cannot be
identified then generate an ErrorComponent with:
o a Severity of HardError and an ErrorCode of AttMissing,
o a PackagedContent containing "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 then check to see if an "identical" input message has been
received before. Identical means that all blocks, components,
elements, attribute values and element content in the input message
are the same.
Note: The recommended way of checking for identical messages is to
check for equal values of their [DOM-HASH]
If an identical message has been received before then check to see if
the processing of the previous message has completed.
If processing has not completed then generate an Error Component with
a Severity of Transient Error and an Error Code of MsgBeingProc to
indicate the message is being processed and send it back to the
sender of the Input Message requesting that the original message be
resent after an appropriate period of time.
Otherwise, if processing has completed and resulted in an output
message then retrieve the last message that was sent and send it
again.
If the message is not a duplicate then it should be processed.
4.5.2.3 Processing Non-Duplicate Message
Once it's been established that the message is not a duplicate, then
it can be processed. This involves:
o checking that a server is available to handle the message,
generating a Transient Error if it is not
o checking the Transaction is Not Already in error or cancelled
o validating the input message. This includes:
- checking for message level errors
- checking for block level errors
- checking any encapsulated data
o checking for errors in the sequence that blocks have been received
o generating error components for any errors that result
o 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 of duplicate input messages means, if
absolutely "identical" messages are received then absolutely
"identical" messages are returned. This also applies to Inquiry and
Ping transactions when in reality the state of a transaction or the
processing ability of the servers may have changed. If up-to-date
status of transactions or servers is required, then an IOTP
transaction with a new value for the ID attribute of the MsgId
component must be used.
Each of the above steps is discussed below.
CHECKING A SERVER IS AVAILABLE
The process that is handling the input message should check that the
rest of the system is not so busy that a response in a reasonable
time cannot be produced.
If the server is too busy, then it should generate an Error Component
with a Severity of Transient Error and an Error Code of SystemBusy
and send it back to the sender of the Input Message requesting that
the original message be resent after an appropriate period of time.
Note: Some servers may occasionally become very busy due to
unexpected increases in workload. This approach allows short peaks in
workloads to be handled by delaying the input of messages by asking
the sender of the message to resubmit later.
CHECKING THE TRANSACTION IS NOT ALREADY IN ERROR OR CANCELLED
Check that:
o previous messages received or sent did not contain or result in
Hard Errors, and
o 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
that has been cancelled, cannot be restarted.
CHECK FOR MESSAGE AND BLOCK LEVEL ERRORS
If the transaction is still OK then check for message level errors.
This involves:
o checking the XML is valid
o checking that the elements, attributes and content of the
Transaction Reference Block are without error and conform to this
specification
o checking the digital signature which involves:
- checking that the Signature value is correctly calculated, and
- the hash values in the digests are correctly calculated where
the source of the hash value is available.
Checking for block level errors involves:
o 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
o checking that the combination of blocks are valid
o checking that the values of the attribute, 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 to check
the data where appropriate.
4.5.2.4 Check for Errors in Block Sequence
Note: For reasons of brevity, the following explanations of how to
check for errors in Block sequence, the phrase "refers to an IOTP
transaction" is interpreted as "is contained in an IOTP Message where
the Trans Ref Block contains an IotpTransId that refers to". So, for
example, " If an Error or Cancel Block refers to an IOTP transaction
that is not recognised then ..." should be interpreted as " If an
Error or Cancel Block is contained in an IOTP Message where the Trans
Ref Block contains an IotpTransId that refers to an IOTP transaction
that is not recognised then ...
Errors in the sequence that blocks arrive depends on the block.
Blocks where checking for sequence is required are:
o 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 to avoid looping.
o 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
o Authentication Request Block. If an Authentication Request Block
refers to an IOTP transaction that is recognised it is a Hard
Error
o 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.
o 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
o 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
o Payment Request Block (Payment Handler only). Check as follows:
- if the Payment Request Block refers to an IOTP Transaction that
is not recognised then its OK, otherwise
- if the Payment Request Block refers to IOTP Transaction that
was not for a Payment then it is a Hard Error, otherwise
- if there was a previous payment that failed with a non-
recoverable Completion Code then it is a Hard Error, otherwise
- if a previous payment is still in progress then it is a Hard
Error
o 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
o 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:
o because they did not know the correct response (e.g., a password)
on an authentication or,
o 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:
o Inquiry Requests on Ping Transactions should be ignored
o 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
o if the input message contains a Error Component with a HardError
or 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
o processing of encapsulated messages (e.g., Payment Protocol
Messages) may result in additional transient errors
o 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:
o if the IotpTransId of the transaction to be cancelled is not
recognised, or complete then fail the request, otherwise
o if the IotpTransId refers to a Ping Transaction then fail the
request, otherwise
o 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:
o the Transport Mechanism being used;
o the time required to process encapsulated messages (e.g., Payment
messages) and
o 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:
o TimedOutRcvr if the transaction can potentially recovered later,
or
o TimedOutNoRcvr if 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:
o Initiate a transaction (see section 4.6.1). These are divided
into:
- payment related transactions and
- infrastructure transactions
o 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
o Cancel a current transaction if requested, for example by the User
(see section 4.6.3)
o 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:
o an Inquiry Transaction (see section 9.2.1)
o a Ping Transaction (see section 9.2.2)
o 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
The handling of the following blocks is the same as for an IOTP
Server (see section 4.5.2.4) except that the Consumer Role is
substituted for IOTP Server Role:
o Error and Cancel Blocks,
o Inquiry Request and Response Blocks,
o Authentication Request, Response and Status Blocks.
For the other blocks a Consumer role might receive, the potential
errors in the sequence that blocks arrive depends on the block.
Blocks where checking for sequence is required are:
o TPO Block. Check as follows:
- if the input message also contains an Authentication Request
block and an Offer Response Block then there is a Hard Error,
otherwise
- if the input message also contains an Authentication Request
block and Authentication Status block then there is Hard Error
otherwise,
- if the input message also contains an Authentication Request
block and the IOTP Transaction is recognised by the Consumer
role's system, then there is a Hard Error, otherwise
- if the input message also contains an Authentication Status
block and the IOTP Transaction is not recognised by the
Consumer role's system then there is a Hard Error, otherwise
- if input message also contains an Authentication Status Block
and the Authentication Status Block has not been sent after an
earlier Authentication Response message then there is a hard
error
- if input message also contains an Offer Response Block and the
IOTP Transaction is recognised by the Consumer role's system
then there is a Hard Error, otherwise
- if the TPO Block occurs on its own and the IOTP Transaction is
recognised by the Consumer role's system then there is a Hard
Error
o 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 is no sequence
checking as it is part of the first message received, otherwise
- if the Offer Response Block is not part of an IOTP Transaction
that is recognised by the Consumer role then there is a Hard
Error, otherwise
- if the Offer Response Block does not refer to an IOTP
transaction where a TPO Selection Block was the last message
sent then there is a Hard Error
o 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 there is a Hard Error, otherwise
- if the Payment Exchange doesn't refer to an IOTP Transaction
where either a Payment Request or a Payment Exchange block was
most recently sent then there is a Hard Error
o 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 there is a Hard Error, otherwise
- if the Payment Response doesn't refer to an IOTOP Transaction
where either a Payment Request or a Payment Exchange block was
most recently sent then there is a Hard Error
o 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 there is a Hard Error, otherwise
- If the Delivery Response doesn't refer to an IOTP Transaction
where either a Payment Request or a Payment Exchange block was
most recently sent then there is a Hard Error
4.6.3 Cancelling a Transaction
This process cancels a current transaction on an Consumer role's
system as a result of an external request from the user, or another
system or server in the Consumer's role. The processing is the same
as for an IOTP Server (see section 4.5.3).
4.6.4 Retransmitting Messages
The process of retransmitting messages is the same as for an IOTP
Server (see section 4.5.4).
5. Security Considerations
This section considers, from an IETF perspective how IOTP addresses
security. The next section (see section 6. Digital Signatures and
IOTP) describes how IOTP uses Digital Signatures when these are
needed.
This section covers:
o determining whether to use digital signatures
o data privacy, and
o payment protocol security.
5.1 Determining whether to use digital signatures
The use of digital signatures within IOTP are entirely optional. IOTP
can work successfully entirely without the use of digital signatures.
Ultimately it is up to the Merchant, or other trading role, to decide
whether IOTP Messages will include signatures, and for the Consumer
to decide whether carrying out a transaction without signatures is an
acceptable risk. If Merchants discover that transactions without
signatures are not being accepted, then they will either:
o start using signatures,
o find a method of working which does not need signatures, or
o accept a lower volume and value of business.
A non-exhaustive list of the reasons why digital signatures might be
used follows:
o the Merchant (or other trading role) wants to demonstrate that
they can be trusted. If, for example, a merchant generates an
Offer Response Signature (see section 7.19.2) using a certificate
from a trusted third party, known to the Consumer, then the
Consumer can check the signature and certificate and so more
reasonably rely on the offer being from the actual Organisation
the Merchant claims to be. In this case signatures using
asymmetric cryptography are likely to be required
o the Merchant, or other Trading Role, want to generate a record of
the transaction that is fit for a particular purpose. For example,
with appropriate trust hierarchies, digital signatures could be
checked by the Consumer to determine:
- if it would be accepted by tax authorities as a valid record of
a transaction, or
- if some warranty, for example from a "Better Business Bureau"
orsimilar was being provided
o 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 is sent to the Consumer in the Offer Response
and then forwarded to the Payment Handler in a Payment Request. If
the request is not 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, the Payment Handler cannot be
sure that the data has not been altered. Similarly, if the payment
information is not digitally signed, the Payment Handler cannot be
sure who is the Merchant that is requesting the payment
o 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 the record of the Payment or
Delivery to prove that it occurred. This could be used, for
example, for customer care purposes.
A non-exhaustive list of the reasons why digital signatures might not
be used follows:
o trading roles are combined therefore changes to data made by the
consumer can be detected. One of the reasons for using signatures
is so that one trading role can determine if data has been changed
by the Consumer or some other party. However if the trading roles
have access to the necessary data, then it might be possible to
compare, for example, the payment information in the Payment
Request with the payment information in the Offer Response. Access
to the data necessary could be realised by, for example, the
Merchant and Payment Handler roles being carried out by the same
Organisation on the same system, or the Merchant and Payment
Handler roles being carried out on different systems but the
systems can communicate in some way. (Note this type of
communication is outside the current scope of IOTP)
o the processing cost of the cryptography is too high. For example,
if a payment is being made of only a few cents, the cost of
carrying out all the cryptography associated with generating and
checking 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 need be set up and just the Merchant, Payment Handler
and Delivery Handler need to agree on the shared secrets to use.
However the disadvantage of symmetric cryptography is that the
Consumer cannot easily check the credentials of the Merchant, Payment
Handler, etc. that they are dealing with. This is likely to reduce,
somewhat, the trust that the Consumer will have carrying out the
transaction.
However it should be noted that even if asymmetric cryptography is
being used, the Consumer does not NEED to be provided with any
digital certificates as the integrity of the transaction is
determined by, for example, the Payment Handler checking the Offer
Response Signature copied to the Payment Request.
Note that symmetric, asymmetric or both types of cryptography may be
used in a single transaction.
5.3 Data Privacy
Privacy of information is provided by sending IOTP Messages between
the various Trading Roles using a secure channel such as [SSL/TLS].
Use of a secure channel within IOTP is optional.
5.4 Payment Protocol Security
IOTP is designed to be completely blind to the payment protocol being
used to effect a payment. From the security perspective, this means
that IOTP neither helps, nor hinders, the achievement of payment
security.
If it is necessary to consider payment security from an IOTP
perspective, then this should be included in the payment protocol
supplement which describes how IOTP supports that payment protocol.
However what IOTP is designed to do is to use digital signatures to
bind together the record, contained in a "response" message, of each
trading exchange in a transaction. For example IOTP can bind
together: an Offer, a Payment and a Delivery.
6. Digital Signatures and IOTP
IOTP can work successfully without using any digital signatures
although in an open networking environment it will be less secure -
see 5. Security Considerations for a description of the factors that
need to be considered.
However, this section describes how to use digital signatures in the
many situations when they will be needed. Topics covered are:
o an overview of how IOTP uses digital signatures
o how to check a signature is correctly calculated
o 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
In general, signatures when used with IOTP:
o are always treated as IOTP Components (see section 7)
o 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
o 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 may be associated with digital signatures if
asymmetric cryptography is being used. However if symmetric
cryptography is being used, then the digital certificate will be
replaced by some identifier of the secret key to use.
The way in which Signatures Components digest one or more elements is
illustrated in the figure below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
IOTP MESSAGE SIGNATURE COMPONENT
IOTP Message Signature Id = P1.3
-Trans Ref Block digest TransRefBlk -Manifest
ID=P1.1------------------------------>-Digest of P1.1--
-Trans Id Comp digest TransIdComp
ID = M1.2----------------------------->-Digest of M1.2--
-Msg Id Comp. digest Signature
ID = P1 -------------------->-Digest of M1.5--
digest element
-Signatures Block ------------------>-Digest of M1.7--
ID=P1.2 digest element
-Signature ID=P1.3 ---------------->-Digest of C1.4--
-Signature ID=M1.5----
-Signature ID=P1.4 Points to -RecipientInfo*
-Certificate ID=M1.6<-------------------------CertRef=M1.6
Certs to use Sig.ValueRef=P1.4
-Trading Block. ID=P1.5 v
-Comp. ID=M1.7---------- -Value* ID=P1.4:
JtvwpMdmSfMbhK<--
-Comp. ID=P1.6 r1Ln3vovbMQttbBI
J8pxLjoSRfe1o6k
-Comp. ID=C1.4------------ OGG7nTFzTi+/0<-
-Comp. ID=C1.5
Digital signature of Manifest element
using certificate identified by CertRef
Elements that are digested can be in any IOTP Message
within the same IOTP Transaction
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 10 Signature Digests
Note: The classic example of one signature signing another in IOTP,
is when an Offer is first signed by a Merchant creating an "Offer
Response" signature, which is then later signed by a Payment Handler
together with a record of the payment creating a "Payment Receipt"
signature. In this way, the payment in an IOTP Transaction is bound
to the Merchant's offer.
Note that one Manifest may be associated with multiple signature
"Value" elements where each Value element contains a digital
signature over the same Manifest, perhaps using the same (or
different) signature algorithm but using a different certificate or
shared secret key. Specifically it will allow the Merchant to agree
on different shared secrets keys with their Payment Handler and
Delivery Handler.
The detailed definitions of a Signature component are contained in
section 7.19.
The remainder of this section contains:
o an example of how IOTP uses signatures
o how the OriginatorInfo and RecipientInfo elements within a
Signature Component are used to identify the Organisations
associated with the signature
o how IOTP uses signatures to prove actions complete successfully
6.1.1 IOTP Signature Example
An example of how signatures are used is illustrated in the figure
below which shows how the various components and elements in a
Baseline Purchase relate to one another. Refer to this example in the
later description of how signatures are used to check a payment or
delivery can occur (see section 6.3).
Note: A Baseline Purchase transaction has been used for illustration
purposes. The usage of the elements and attributes is the same for
all types of IOTP Transactions.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
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
PayProtocol 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 contains an Element Reference (see section 3.5)
that points to the Organisation Component of the Organisation which
generated the Signature. In this example its the Merchant.
Note that the value of the content of the Attribute element with a
Type attribute set to IOTP Signature Type must match the Trading Role
of the Organisation which signed it. If it does not, then it is an
error. Valid combinations are given in the table below.
IOTP Signature Type Valid Trading Role
OfferResponse Merchant
PaymentResponse PaymentHandler
DeliveryResponse DeliveryHandler
AuthenticationRequest any role
AuthenticationResponse any role
PingRequest any role
PingResponse any role
The RecipientRefs attribute of the RecipientInfo element in the
Signature Component contains Element References to the Organisation
Components of the Organisations that should use the signature to
verify that:
o they have a pre-existing relationship with the Organisation that
generated the signature,
o the data which is secured by the signature has not been changed,
o the data has been signed correctly, and
o the action they are required to undertake on behalf of the
Merchant is therefore authorised.
Note that if symmetric cryptography is being used then a separate
RecipientInfo and Value elements for each different set of shared
secret keys are likely within the Signature Component.
Alternatively if asymmetric cryptography is being used then the
RecpientRefs attribute of one RecipientInfo element may refer to
multiple Organisation Components if they are all using the same
certificates.
6.1.3 Using signatures to Prove Actions Complete Successfully
Proving an action completed successfully, is achieved by signing data
on Response messages. Specifically:
o on the Offer Response, when a Merchant is making an Offer to the
Consumer which can then be sent to either:
- a Payment Handler to prove that the Merchant authorises
Payment, or
- a Delivery Handler to prove that Merchant authorises Delivery,
provided other necessary authorisations are complete (see
below)
o on the Payment Response, when a Payment Handler is generating a
Payment Receipt which can be sent to either:
- a Delivery Handler, in a Delivery Request Block to authorise
Delivery together with the Offer Response signature, or
- another Payment Handler, in a second Payment Request, to
authorise the second payment in a Value Exchange IOTP
Transaction
o Delivery Response, when a Delivery Handler is generating a
Delivery Note. This can be used to prove after the event what the
Delivery Handler said they would do
o Authentication Response. One method of authenticating another
party to a trade is to send an Authentication Request specifying
that a Digital Signature should be used for authentication
o Transaction Status Inquiry. The Inquiry Response Block may be
digitally signed to attest to the authenticity of the response
o Ping. The Ping Response may be digitally signed so that checks can
be made that the signature can be understood.
This proof of an action may, in future versions of IOTP, also be used
to prove after the event that the IOTP transaction occurred. For
example to a Customer Care Provider.
6.2 Checking a Signature is Correctly Calculated
Checking a signature is correctly calculated is part of checking for
Message Level Errors (see section 4.3.2). It is included here so that
all signature and security related considerations are kept together.
Before a Trading Role can check a signature it must identify which of
the potentially multiple Signature elements should be checked. The
steps involved are as follows:
o check that a Signature Block is present and it contains one or
more Signature Components
o identify the Organisation Component which contains an OrgId
attribute for the Organisation which is carrying out the signature
check. If no or more than one Organisation Component is found then
it is an error
o use the ID attribute of the Organisation Component to find the
RecipientInfo element that contains a RecipientRefs attribute that
refers to that Organisation Component. Note there may be no
signatures to verify
o check the Signature Component that contains the identified
RecipientInfo element as follows:
- use the SignatureValueRef and the SignatureAlgorithmRef
attributes to identify, respectively: the Value element that
contains the signature to be checked and the Signature
Algorithm element that describes the signature algorithm to be
used to verify the Signature, then
- if the Signature Algorithm element indicates that asymmetric
cryptography is being used then use the SignatureCertRef to
identify the Certificate to be used by the signature algorithm
- if Signature Algorithm element indicates that symmetric
cryptography is being used then the content of the
RecipientInfo element is used to identify the correct shared
secret key to use
- use the specified signature algorithm to check that the Value
Element correctly signs the Manifest Element
- check that the Digest Elements in the Manifest Element are
correctly calculated where Components or Blocks referenced by
the Digest have been received by the Organisation checking the
signature.
6.3 Checking a Payment or Delivery can occur
This section describes the processes required for a Payment Handler
or Delivery Handler to check that a payment or delivery can occur.
This may include checking signatures if this is specified by the
Merchant.
In outline the steps are:
o check that the Payment Request or Delivery Request has been sent
to the correct Organisation
o check that correct IOTP components are present in the request, and
o check that the payment or delivery is authorised
For clarity and brevity the following terms or phrases are used in
this section:
o a "Request Block" is used to refer to either a Payment Request
Block (see section 8.7) or a Delivery Request Block (see section
8.10) unless specified to the contrary
o a "Response Block" is used to refer to either a Payment Response
Block (see section 8.9) or a Delivery Response Block (see section
8.11)
o an "Action" is used to refer to an action which occurs on receipt
of a Request Block. Actions can be either a Payment or a Delivery
o an "Action Organisation", is used to refer to the Payment Handler
or Delivery Handler that carries out an Action
o a "Signer of an Action", is used to refer to the Organisations
that sign data about an Action to authorise the Action, either in
whole or in part
o a "Verifier of an Action", is used to refer to the Organisations
that verify data to determine if they are authorised to carry out
the Action
o an ActionOrgRef attribute contains Element References which can be
used to identify the "Action Organisation" that should carry out
an Action
6.3.1 Check Request Block sent Correct Organisation
Checking the Request Block was sent to the correct Organisation
varies depending on whether the request refers to a Payment or a
Delivery.
6.3.1.1 Payment
In outline a Payment Handler checks if it can accept or make a
payment by identifying the Payment Component in the Payment Request
Block it has received, then using the ID of the Payment Component to
track through the Brand List and Brand Selection Components to
identify the Organisation selected by the Consumer and then checking
that this Organisation is itself.
The way data is accessed to do this is illustrated in the figure
below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Start
v
Brand List<--------------------------+-----------Payment
Component BrandListRef Component
-Brand<--------------------------
Element BrandRef
Brand Selection
Protocol Component
AmountRefs
v Protocol
-Protocol Amount<----------------
Element---------- AmountRef
Currency Pay
AmountRefs Protocol
v Ref
-Currency Amount
Element<-------------------------
-PayProtocol<-----
Element---------------------->Organisation
Action Component
OrgRef
-Trading Role
Element
(Payment Handler)
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 12 Checking a Payment Handler can carry out a Payment
The following describes the steps involved and the checks which need
to be made:
o Identify the Payment Component (see section 7.9) in the Payment
Request Block that was received.
o Identify the Brand List and Brand Selection Components for the
Payment Component. This involves:
- identifying the Brand List Component (see section 7.7) where
the value of its ID attribute matches the BrandListRef
attribute of the Payment Component. If no or more than one
Brand List Component is found there is an error.
- identifying the Brand Selection Component (see section 7.8)
where the value of its BrandListRef attribute matches the
BrandListRef of the Payment Component. If no or more than one
matching Brand Selection Component is found there is an error.
o Identify the Brand, Protocol Amount, Pay Protocol and Currency
Amount elements within the Brand List that have been selected by
the Consumer as follows:
- the Brand Element (see section 7.7.1) selected is the element
where the value of its Id attribute matches the value of the
BrandRef attribute in the Brand Selection. If no or more than
one matching Brand Element is found then there is an error.
- the Protocol Amount Element (see section 7.7.3) selected is the
element where the value of its Id attribute matches the value
of the ProtocolAmountRef attribute in the Brand Selection
Component. If no or more than one matching Protocol Amount
Element is found there is an error
- the Pay Protocol Element (see section 7.7.5) selected is the
element where the value of its Id attribute matches the value
of the PayProtocolRef attribute in the identified Protocol
Amount Element. If no or more than one matching Pay Protocol
Element is found there is an error
- the Currency Amount Element (see section 7.7.4) selected is the
element where the value of its Id attribute matches the value
of the CurrencyAmountRef attribute in the Brand Selection
Component. If no or more than one matching Currency Amount
element is found there is an error
o Check the consistency of the references in the Brand List and
Brand Selection Components:
- check that an Element Reference exists in the
ProtocolAmountRefs attribute of the identified Brand Element
that matches the Id attribute of the identified Protocol Amount
Element. If no or more than one matching Element Reference can
be found there is an error
- check that the CurrencyAmountRefs attribute of the identified
Protocol Amount element contains an element reference that
matches the Id attribute of the identified Currency Amount
element. If no or more than one matching Element Reference is
found there is an error.
- check the consistency of the elements in the Brand List.
Specifically, the selected Brand, Protocol Amount, Pay Protocol
and Currency Amount Elements are all child elements of the
identified Brand List Component. If they are not there is an
error.
o Check that the Payment Handler that received the Payment Request
Block is the Payment Handler selected by the Consumer. This
involves:
- identifying the Organisation Component for the Payment Handler.
This is the Organisation Component where its ID attribute
matches the ActionOrgRef attribute in the identified Pay
Protocol Element. If no or more than one matching Organisation
Component is found there is an error
- checking the Organisation Component has a Trading Role Element
with a Role attribute of PaymentHandler. If not there is an
error
- finally, if the identified Organisation Component is not the
same as the Organisation that received the Payment Request
Block, then there is an error.
6.3.1.2 Delivery
The way data is accessed by a Delivery Handler in order to check that
it may carry out a delivery is illustrated in the figure below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Start
v
Delivery
Component
ActionOrgRef
v
Organisation
Component
-Trading Role
Element
(Delivery Handler)
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 13 Checking a Delivery Handler can carry out a Delivery
The steps involved are as follows:
o Identify the Delivery Component in the Delivery Request Block. If
there is no or more than one matching Delivery Component there is
an error
o Use the ActionOrgRef attribute of the Delivery Component to
identify the Organisation Component of the Delivery Handler. If
there is no or more than one matching Organisation Component there
is an error
o If the Organisation Component for the Delivery Handler does not
have a Trading Role Element with a Role attribute of
DeliveryHandler there is an error
o Finally, if the Organisation that received the Delivery Request
Block does not identify the Organisation Component for the
Delivery Handler as itself, then there is an error.
6.3.2 Check Correct Components present in Request Block
Check that the correct components are present in the Payment Request
Block (see section 8.7) or in the Delivery Request Block (see section
8.10).
If components are missing, there is an error.
6.3.3 Check an Action is Authorised
The previous steps identified the Action Organisation and that all
the necessary components are present. This step checks that the
Action Organisation is authorised to carry out the Action.
In outline the Action Organisation will identifies the Merchant,
checks that it has a pre-existing agreement with the Merchant that
allows it carry out the Action and that any constraints implied by
that agreement are being followed, then, if signatures are required,
it checks that they sign the correct data.
The steps involved are as follows:
o Identify the Merchant. This is the Organisation Component with a
Trading Role Element which has a Role attribute with a value of
Merchant. If no or more than one Trading Role Element is found,
there is an error
o Check the Action Organisation's agreements with the Merchant
allows the Action to be carried out. To do this the Action
Organisation must check that:
- the Merchant is known and a pre-existing agreement exists for
the Action Organisation to be their agent for the payment or
delivery
- they are allowed to take part in the type of IOTP transaction
that is occurring. For example a Payment Handler may have
agreed to accept payments as part of a Baseline Purchase, but
not make payments as part of a Baseline Refund
- any constraints in their agreement with the Merchant are being
followed, for example, whether or not an Offer Response
signature is required
o Check the signatures are correct. If signatures are required then
they need to be checked. This involves:
- Identifying the correct signatures to check. This involves the
Action Organisation identifying the Signature Components that
contain references to the Action Organisation (see 6.3.1).
Depending on the IOTP Transaction being carried out (see
section 9) either one or two signatures may be identified
- checking that the Signature Components are correct. This
involves checking that Digest elements exist within the
Manifest Element that refer to the necessary Trading Components
(see section 6.3.3.1).
6.3.3.1 Check the Signatures Digests are correct
All Signature Components contained within IOTP Messages must include
Digest elements that refer to:
o the Transaction Id Component (see section 3.3.1) of the IOTP
message that contains the Signature Component. This binds the
globally unique IotpTransId to other components which make up the
IOTP Transaction
o the Transaction Reference Block (see section 3.3) of the first
IOTP Message that contained the signature. This binds the
IotpTransId with information about the IOTP Message contained
inside the Message Id Component (see section 3.3.2).
Check that each Signature Component contains Digest elements that
refer to the correct data required.
The Digest elements that need to be present depend on the Trading
Role of the Organisation which generated (signed) the signature:
o if the signer of the signature is a Merchant then:
- Digest elements must be present for all the components in the
Request Block apart from the Brand Selection Component which is
optional
o if the signer of the signature is a Payment Handler then Digest
elements must be present for:
- the Signature Component signed by the Merchant, and optionally
- one or more Signature Components signed by the previous Payment
Handler(s) in the Transaction.
7. Trading Components
This section describes the Trading Components used within IOTP.
Trading Components are the child XML elements which occur immediately
below a Trading Block as illustrated in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
IOTP MESSAGE <----------- IOTP Message - an XML Document
which is transported between the
Trading Roles
-Trans Ref Block <----- Trans Ref Block - contains
information which describes the
IOTP Transaction and the IOTP
Message.
--------> -Trans Id Comp. <--- Transaction Id Component -
uniquely identifies the IOTP
Transaction. The Trans Id
Components are the same across
all IOTP messages that comprise
a single IOTP transaction.
-Msg Id Comp. <----- Message Id Component -
identifies and describes an IOTP
Message within an IOTP
Transaction
-Signature Block <----- Signature Block (optional) -
contains one or more Signature
Components and their associated
Certificates
---> -Signature Comp. <-- Signature Component - contains
digital signatures. Signatures
may sign digests of the Trans Ref
Block and any Trading Component
in any IOTP Message in the same
IOTP Transaction.
-Certificate Comp. <- Certificate Component. Used to
check the signature.
Trading -Trading Block <-------- Trading Block - an XML Element
Components -Trading Comp. within an IOTP Message that
-Trading Comp. contains a predefined set of
---> -Trading Comp. Trading Components
-Trading Comp.
-Trading Comp. <----- Trading Components - XML
Elements within a Trading Block
-Trading Block that contain a predefined set of
--------> -Trading Comp. XML elements and attributes
-Trading Comp. containing information required
-Trading Comp. to support a Trading Exchange
-Trading Comp.
-Trading Comp.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 14 Trading Components
The Trading Components described in this section are listed below in
approximately the sequence they are likely to be used:
o Protocol Options Component
o Authentication Request Component
o Authentication Response Component
o Trading Role Information Request Component
o Order Component
o Organisation Component
o Brand List Component
o Brand Selection Component
o Payment Component
o Payment Scheme Component
o Payment Receipt Component
o Delivery Component
o Delivery Data Component
o Delivery Note Component
o Signature Component
o Certificate Component
o Error Component
Note that the following components are listed in other sections of
this specification:
o Transaction Id Component (see section 3.3.1)
o Message Id Component (see section 3.3.2)
7.1 Protocol Options Component
Protocol options are options which apply to the IOTP Transaction as a
whole. Essentially it provides a short description of the entire
transaction and the net location which the Consumer role should
branch to if the IOTP Transaction is successful.
The definition of a Protocol Options Component is as follows.
<!ELEMENT ProtocolOptions EMPTY >
<!ATTLIST ProtocolOptions
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
ShortDesc CDATA #REQUIRED
SenderNetLocn CDATA #IMPLIED
SecureSenderNetLocn CDATA #IMPLIED
SuccessNetLocn CDATA #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Protocol Options Component within the IOTP
Transaction.
Xml:lang Defines the language used by attributes or child
elements within this component, unless
overridden by an xml:lang attribute on a child
element. See section 3.8 Identifying Languages.
ShortDesc This contains a short description of the IOTP
Transaction in the language defined by xml:lang.
Its purpose is to provide an explanation of what
type of IOTP Transaction is being conducted by
the parties involved.
It is used to facilitate selecting an individual
transaction from a list of similar transactions,
for example from a database of IOTP transactions
which has been stored by a Consumer, Merchant,
etc.
SenderNetLocn This contains the non secured net location of
the sender of the TPO Block in which the
Protocol Options Component is contained.
It is the net location to which the recipient of
the TPO block should send a TPO Selection Block
if required.
The content of this attribute is dependent on
the Transport Mechanism see the Transport
Mechanism Supplement.
SecureSenderNetLocn This contains the secured net location of the
sender of the TPO Block in which the Protocol
Options Component is contained.
The content of this attribute is dependent on
the Transport Mechanism see the Transport
Mechanism Supplement.
SuccessNetLocn This contains the net location that should be
displayed after the IOTP Transaction has
successfully completed.
The content of this attribute is dependent on
the Transport Mechanism see the Transport
Mechanism Supplement.
Either SenderNetLocn, SecureSenderNetLocn or both must be present.
7.2 Authentication Request Component
This Trading Component contains parameter data that is used in an
Authentication of one Trading Role by another. Its definition is as
follows.
<!ELEMENT AuthReq (Algorithm, PackagedContent*)>
<!ATTLIST AuthReq
ID ID #REQUIRED
AuthenticationId CDATA #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
If required the Algorithm may use the challenge data, contained in
the Packaged Content elements within the Authentication Request
Component in its calculation. The format of the Packaged Contents are
Algorithm dependent.
Attributes:
ID An identifier which uniquely identifies the
Authentication Request Component within the IOTP
Transaction.
AuthenticationId An identifier specified by the Authenticator
which, if returned by the Organisation that
receives the Authentication Request, will enable
the Authenticator to identify which Authentication
is being referred to.
ContentSoftwareId See section 14.Glossary
Content:
PackagedContent This contains the challenge data as one or more
Packaged Content (see section 3.7) that is to be
responded to using the Algorithm defined by the
Algorithm element.
Algorithm This contains information which describes the
Algorithm (see 7.19 Signature Components) that
must be used to generate the Authentication
Response.
The Algorithms that may be used are identified by
the Name attribute of the Algorithm element. For
valid values see section 12. IANA Considerations.
7.3 Authentication Response Component
The Authentication Response Component contains the results of an
authentication request. It uses the Algorithm contained in the
Authentication Request Component (see section 7.2) selected from the
Authentication Request Block (see section 8.4).
Depending on the Algorithm selected, the results of applying the
algorithm will either be contained in a Signature Component that
signs both the Authentication Response and potentially other data, or
in the Packaged Content elements within the Authentication Response
Component. Its definition is as follows.
<!ELEMENT AuthResp (PackagedContent*) >
<!ATTLIST AuthResp
ID ID #REQUIRED
AuthenticationId CDATA #REQUIRED
SelectedAlgorithmRef NMTOKEN #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Authentication Response Component within the
IOTP Transaction.
AuthenticationId The Authentication identifier specified by the
Authenticator that was included in the
Authentication Request Component(see section
7.2). This will enable the Authenticator to
identify the Authentication that is being
referred to.
SelectedAlgorithmRef An Element Reference that identifies the
Algorithm element used to generate the
Authentication Response.
ContentSoftwareId See section 14.Glossary.
Content:
PackagedContent This may contain the response generated as a
result of applying the Algorithm selected from the
Authentication Request Component see section 7.2.
For example, for a payment specific scheme, it may
contain scheme-specific data. Refer to the scheme-
specific supplemental documentation for
definitions of its content.
7.4 Trading Role Information Request Component
This Trading Component contains a list of Trading Roles (see section
2.1) about which information is being requested. The result of a
Trading Role Request is a set of Organisation Components (see section
7.6) that describe each of the Trading Roles requested.
Example usage includes:
o a Merchant requesting that a Consumer provides Organisation
Components for the Consumer and DelivTo Trading Roles
o a Consumer requesting from a Merchant, information about the
Payment Handlers and Delivery Handlers that the Merchant uses.
Its definition is as follows.
<!ELEMENT TradingRoleInfoReq EMPTY>
<!ATTLIST TradingRoleInfoReq
ID ID #REQUIRED
TradingRoleList NMTOKENS #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the
Trading Role Information Request Component within
the IOTP Transaction.
TradingRoleList Contains a list of one or more Trading Roles (see
the TradingRole attribute of the Trading Role
Element - section 7.6.2) for which information is
being requested.
7.5 Order Component
An Order Component contains information about an order. Its
definition is as follows.
<!ELEMENT Order (PackagedContent*) >
<!ATTLIST Order
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
OrderIdentifier CDATA #REQUIRED
ShortDesc CDATA #REQUIRED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
ApplicableLaw CDATA #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the Order
Component within the IOTP Transaction.
xml:lang Defines the language used by attributes or child
elements within this component, unless overridden
by an xml:lang attribute on a child element. See
section 3.8 Identifying Languages.
OrderIdentifier This is a code, reference number or other
identifier which the creator of the Order may use
to identify the order. It must be unique within an
IOTP Transaction. If it is used in this way, then
it may remove the need to specify any content for
the Order element as the reference can be used to
look up the necessary information in a database.
ShortDesc A short description of the order in the language
defined by xml:lang. It is used to facilitate
selecting an individual order from a list of
orders, for example from a database of orders
which has been stored by a Consumer, Merchant,
etc.
OkFrom The date and time in [UTC] format after which the
offer made by the Merchant lapses.
OkTo The date and time in [UTC] format before which a
Value Acquirer may accept the offer made by the
Merchant is not valid.
ApplicableLaw A phrase in the language defined by xml:lang which
describes the state or country of jurisdiction
which will apply in resolving problems or
disputes.
ContentSoftwareId See section 14.Glossary.
Content:
PackagedContent An optional description of the order information
as one or more Packaged Contents (see section
3.7).
7.5.1 Order Description Content
The Packaged Content element will normally be required, however it
may be omitted where sufficient information about the purchase can be
provided in the ShortDesc attribute. If the full Order Description
requires it several Packaged Content elements may be used.
Although the amount and currency are likely to appear in the Packaged
Content of the Order Description it is the amount and currency
contained in the payment related trading components (Brand List,
Brand Selection and Payment) that is authoritative. This means it is
important that the amount actually being paid (as contained in the
payment related trading components) is prominently displayed to the
Consumer.
For interoperability, implementations must support Plain Text, HTML
and XML as a minimum so that it can be easily displayed.
7.5.2 OkFrom and OkTo Timestamps
Note that:
o the OkFrom date may be later than the OkFrom date on the Payment
Component (see section 7.9) associated with this order, and
o similarly, the OkTo date may be earlier that the OkTo date on the
Payment Component (see section 7.9).
Note: Disclaimer. The following information provided in this note
does not represent formal advice of any of the authors of this
specification. Readers of this specification must form their own
views and seek their own legal counsel on the usefulness and
applicability of this information.
The merchant in the context of Internet commerce with anonymous
consumers initially frames the terms of the offer on the web page,
and in order to obtain the goods or services, the consumer must
accept them.
If there is to be a time-limited offer, it is recommended that
merchants communicate this to the consumer and state in the order
description in a manner which is clear to the consumer that:
o the offer is time limited
o the OkFrom and OkTo timestamps specify the validity of the offer
o the clock, e.g., the merchant's clock, that will be used to
determine the validity of the offer
Also note that although the OkFrom and OkTo dates are likely to
appear in the Packaged Content of the Order Description it is the
dates contained in the Order Component that is authoritative. This
means it is important that the OkFrom and OkTo dates actually being
used is prominently displayed to the Consumer.
7.6 Organisation Component
The Organisation Component provides information about an individual
or an Organisation. This can be used for a variety of purposes. For
example:
o to describe the merchant who is selling the goods,
o to identify who made a purchase,
o to identify who will take delivery of goods,
o to provide a customer care contact,
o to describe who will be the Payment Handler.
Note that the Organisation Components which must be present in an
IOTP Message are dependent on the particular transaction being
carried out. Refer to section 9. Internet Open Trading Protocol
Transactions, for more details.
Its definition is as follows.
<!ELEMENT Org (TradingRole+, ContactInfo?,
PersonName?, PostalAddress?)>
<!ATTLIST Org
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
OrgId CDATA #REQUIRED
LegalName CDATA #IMPLIED
ShortDesc CDATA #IMPLIED
LogoNetLocn CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Organisation Component within the IOTP
Transaction.
xml:lang Defines the language used by attributes or child
elements within this component, unless overridden
by an xml:lang attribute on a child element. See
section 3.8 Identifying Languages.
OrgId A code which identifies the Organisation described
by the Organisation Component. See 7.6.1
Organisation IDs, below.
LegalName For Organisations which are companies this is
their legal name in the language defined by
xml:lang. It is required for Organisations who
have a Trading Role other than Consumer or
DelivTo.
ShortDesc A short description of the Organisation in the
language defined by xml:lang. It is typically the
name by which the Organisation is commonly known.
For example, if the legal name was "Blue Meadows
Financial Services Inc.". Then its short name
would likely be "Blue Meadows".
It is used to facilitate selecting an individual
Organisation from a list of Organisations, for
example from a database of Organisations involved
in IOTP Transactions which has been stored by a
consumer.
LogoNetLocn The net location which can be used to download the
logo for the Organisation.
See section 10 Retrieving Logos.
The content of this attribute must conform to
[RFC1738].
Content:
TradingRole See 7.6.2 Trading Role Element below.
ContactInfo See 7.6.3 Contact Information Element below.
PersonName See 7.6.4 Person Name below.
PostalAddress See 7.6.5 Postal Address below.
7.6.1 Organisation IDs
Organisation IDs are used by one IOTP Trading Role to identify
another. In order to avoid confusion, this means that these IDs must
be globally unique.
In principle this is achieved in the following way:
o the Organisation Id for all trading roles, apart from the Consumer
Trading Role, uses a domain name as their globally unique
identifier,
o the Organisation Id for a Consumer Trading Role is allocated by
one of the other Trading Roles in an IOTP Transaction and is made
unique by concatenating it with that other roles' Organisation Id,
o once a Consumer is allocated an Organisation Id within an IOTP
Transaction the same Organisation Id is used by all the other
trading roles in that IOTP transaction to identify that Consumer.
Specifically, the content of the Organisation ID is defined as
follows:
OrgId ::= NonConsumerOrgId ConsumerOrgId
NonConsumerOrgId ::= DomainName
ConsumerOrgId ::= ConsumerOrgIdPrefix (namechar)+ "/" NonConsumerOrgId
ConsumerOrgIdPrefix ::= "Consumer:"
ConsumerOrgId The Organisation ID for a Consumer consists of:
o a standard prefix to identify that the
Organisation Id is for a consumer, followed by
o one or more characters which conform to the
definition of an XML "namechar". See [XML]
specifications, followed by
o the NonConsumerOrgId for the Organisation
which allocated the ConsumerOrgId. It is
normally the Merchant role.
Use of upper and lower case is not significant.
NonConsumerOrgId If the Role is not Consumer then this contains the
Canonical Name for the non-consumer Organisation
being described by the Organisation Component. See
[DNS] optionally followed by additional
characters, if required, to make the
NonConsumerOrgId unique.
Note that a NonConsumerOrgId may not start with
the ConsumerOrgIdPrefix.
Use of upper and lower case is not significant.
Examples of Organisation Ids follow:
o newjerseybooks.com - a merchant Organisation id
o westernbank.co.uk - a Payment Handler Organisation id
o consumer:1000247ABH/newjerseybooks.com - a consumer Organisation
id allocated by a merchant
7.6.2 Trading Role Element
This identifies the Trading Role of an individual or Organisation in
the IOTP Transaction. Note, an Organisation may have more than one
Trading Role and several roles may be present in one Organisation
element. Its definition is as follows:
<!ELEMENT TradingRole EMPTY >
<!ATTLIST TradingRole
ID ID #REQUIRED
TradingRole NMTOKEN #REQUIRED
IotpMsgIdPrefix NMTOKEN #REQUIRED
CancelNetLocn CDATA #IMPLIED
ErrorNetLocn CDATA #IMPLIED
ErrorLogNetLocn CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Trading Role Element within the IOTP Transaction.
TradingRole The trading role of the Organisation. Valid values
are:
o Consumer. The person or Organisation that is
acting in the role of a consumer in the IOTP
Transaction.
o Merchant. The person or Organisation that is
acting in the role of merchant in the IOTP
Transaction.
o PaymentHandler. The financial institution or
other Organisation which is a Payment Handler
for the IOTP Transaction
o DeliveryHandler. The person or Organisation
that is the delivering the goods or services
for the IOTP Transaction
o DelivTo. The person or Organisation that is
receiving the delivery of goods or services in
the IOTP Transaction
o CustCare. The Organisation and/or individual
who will provide customer care for an IOTP
Transaction.
Values of TradingRole are controlled under the
procedures defined in section 12 IANA
Considerations which also allows user defined
values to be defined.
IotpMsgIdPrefix Contains the prefix which must be used for all
IOTP Messages sent by the Trading Role in this
IOTP Transaction. The values to be used are
defined in 3.4.1 IOTP Message ID Attribute
Definition.
CancelNetLocn This contains the net location of where the
Consumer should go to if the Consumer cancels the
transaction for some reason. It can be used by the
Trading Role to provide a response which is more
tailored to the circumstances of a particular
transaction.
This attribute:
o must not be present when TradingRole is set to
Consumer role or DelivTo,
o must be present when TradingRole is set to
Merchant, PaymentHandler or DeliveryHandler.
The content of this attribute is dependent on the
Transport Mechanism see the Transport Mechanism
Supplement.
ErrorNetLocn This contains the net location that should be
displayed by the Consumer after the Consumer has
either received or generated an Error Block
containing an Error Component with the Severity
attribute set to either:
o HardError,
o Warning but the Consumer decides to not
continue with the transaction
o TransientError and the transaction has
subsequently timed out.
See section 7.21.1 Error Processing Guidelines for
more details.
This attribute:
o must not be present when TradingRole is set to
Consumer or DelivTo,
o must be present when TradingRole is set to
Merchant, PaymentHandler or DeliveryHandler.
The content of this attribute is dependent on the
Transport Mechanism see the Transport Mechanism
Supplement.
ErrorLogNetLocn Optional. This contains the net location that
Consumers should send IOTP Messages that contain
Error Blocks with an Error Component with the
Severity attribute set to either:
o HardError,
o Warning but the Consumer decides to not
continue with the transaction
o TransientError and the transaction has
subsequently timed out.
This attribute:
o must not be present when TradingRole is set to
Consumer role,
o must be present when TradingRole is set to
Merchant, PaymentHandler or DeliveryHandler.
The content of this attribute is dependent on the
Transport Mechanism see the Transport Mechanism
Supplement.
The ErrorLogNetLocn can be used to send error
messages to the software company or some other
Organisation responsible for fixing problems in
the software which sent the incoming message. See
section 7.21.1 Error Processing Guidelines for
more details.
7.6.3 Contact Information Element
This contains information which can be used to contact an
Organisation or an individual. All attributes are optional however at
least one item of contact information should be present. Its
definition is as follows.
<!ELEMENT ContactInfo EMPTY >
<!ATTLIST ContactInfo
xml:lang NMTOKEN #IMPLIED
Tel CDATA #IMPLIED
Fax CDATA #IMPLIED
Email CDATA #IMPLIED
NetLocn CDATA #IMPLIED >
Attributes:
xml:lang Defines the language used by attributes within
this element. See section 3.8 Identifying
Languages.
Tel A telephone number by which the Organisation may
be contacted. Note that this is a text field and
no validation is carried out on it.
Fax A fax number by which the Organisation may be
contacted. Note that this is a text field and no
validation is carried out on it.
Email An email address by which the Organisation may be
contacted. Note that this field should conform to
the conventions for address specifications
contained in [RFC822].
NetLocn A location on the Internet by which information
about the Organisation may be obtained that can be
displayed using a web browser.
The content of this attribute must conform to
[RFC1738].
7.6.4 Person Name Element
This contains the name of an individual person. All fields are
optional however as a minimum either the GivenName or the FamilyName
should be present. Its definition is as follows.
<!ELEMENT PersonName EMPTY >
<!ATTLIST PersonName
xml:lang NMTOKEN #IMPLIED
Title CDATA #IMPLIED
GivenName CDATA #IMPLIED
Initials CDATA #IMPLIED
FamilyName CDATA #IMPLIED >
Attributes:
xml:lang Defines the language used by attributes within
this element. See section 3.8 Identifying
Languages.
Title A distinctive name; personal appellation,
hereditary or not, denoting or implying Office
(e.g., judge, mayor) or nobility (e.g., duke,
duchess, earl), or used in addressing or referring
to a person (e.g., Mr, Mrs, Miss)
GivenName The primary or main name by which a person is
known amongst and identified by their family,
friends and acquaintances. Otherwise known as
first name or Christian Name.
Initials The first letter of the secondary names (other
than the Given Name) by which a person is known
amongst or identified by their family, friends and
acquaintances.
FamilyName The name by which family of related individuals
are known. It is typically the part of an
individual's name which is passed on by parents to
their children.
7.6.5 Postal Address Element
This contains an address which can be used, for example, for the
physical delivery of goods, services or letters. Its definition is as
follows.
<!ELEMENT PostalAddress EMPTY >
<!ATTLIST PostalAddress
xml:lang NMTOKEN #IMPLIED
AddressLine1 CDATA #IMPLIED
AddressLine2 CDATA #IMPLIED
CityOrTown CDATA #IMPLIED
StateOrRegion CDATA #IMPLIED
PostalCode CDATA #IMPLIED
Country CDATA #IMPLIED
LegalLocation (True False) 'False' >
Attributes:
xml:lang Defines the language used by attributes within
this element. See section 3.8 Identifying
Languages.
AddressLine1 The first line of a postal address. e.g., "The
Meadows"
AddressLine2 The second line of a postal address. e.g., "Sandy
Lane"
CityOrTown The city of town of the address. e.g., "Carpham"
StateOrRegion The state or region within a country where the
city or town is placed. e.g., "Surrey"
PostalCode The code known as, for example a post code or zip
code, that is typically used by Postal
Organisations to organise postal deliveries into
efficient sequences. e.g., "KT22 1AA"
Country The country for the address. e.g., "UK"
LegalLocation This identifies whether the address is the
Registered Address for the Organisation. At least
one address for the Organisation must have a value
set to True unless the Trading Role is either
Consumer or DeliverTo.
7.7 Brand List Component
Brand List Components are contained within the Trading Protocol
Options Block (see section 8.1) of the IOTP Transaction. They
contains lists of:
o payment Brands (see also section 11.1 Brand Definitions and Brand
Selection),
o amounts to be paid in the currencies that are accepted or offered
by the Merchant,
o the payment protocols which can be used to make payments with a
Brand, and
o the net locations of the Payment Handlers which accept payment for
a payment protocol
The definition of a Brand List Component is as follows.
<!ELEMENT BrandList (Brand+, ProtocolAmount+,
CurrencyAmount+, PayProtocol+) >
<!ATTLIST BrandList
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
ShortDesc CDATA #REQUIRED
PayDirection (Debit Credit) #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the Brand
List Component within the IOTP Transaction.
xml:lang Defines the language used by attributes or child
elements within this component, unless overridden
by an xml:lang attribute on a child element. See
section 3.8 Identifying Languages.
ShortDesc A text description in the language defined by
xml:Lang giving details of the purpose of the
Brand List. This information must be displayed to
the receiver of the Brand List in order to assist
with making the selection. It is of particular
benefit in allowing a Consumer to distinguish the
purpose of a Brand List when an IOTP Transaction
involves more than one payment.
PayDirection Indicates the direction in which the payment for
which a Brand is being selected is to be made. Its
values may be:
o Debit The sender of the Payment Request Block
(e.g., the Consumer) to which this Brand List
relates will make the payment to the Payment
Handler, or
o Credit The sender of the Payment Request Block
to which this Brand List relates will receive a
payment from the Payment Handler.
Content:
Brand This describes a Brand. The sequence of the Brand
elements (see section 7.7.1) within the Brand List
does not indicate any preference. It is
recommended that software which processes this
Brand List presents Brands in a sequence which the
receiver of the Brand List prefers.
ProtocolAmount This links a particular Brand to:
o the currencies and amounts in CurrencyAmount
elements that can be used with the Brand, and
o the Payment Protocols and Payment Handlers,
which can be used with those currencies and
amounts, and a particular Brand
CurrencyAmount This contains a currency code and an amount.
PayProtocol This contains information about a Payment Protocol
and the Payment Handler which may be used with a
particular Brand.
The relationships between the elements which make up the content of
the Brand List is illustrated in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Brand List Component
ProtocolAmountRefs
-Brand Element-----------------------------
- Protocol Brand Element--------
ProtocolId
-Protocol Amount Element<----------+-------
CurrencyAmountRefs Pay
Protocol
v Ref
-Currency Amount Element
Element
-PayProtocolElement<------<--------
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Figure 15 Brand List Element Relationships
Examples of complete Brand Lists are contained in section 11.2 Brand
List Examples.
7.7.1 Brand Element
A Brand Element describes a brand that can be used for making a
payment. One or more of these elements is carried in each Brand List
Component that has the PayDirection attribute set to Debit. Exactly
one Brand Element may be carried in a Brand List Component that has
the PayDirection attribute set to Credit.
<!ELEMENT Brand (ProtocolBrand*, PackagedContent*) >
<!ATTLIST Brand
ID ID #REQUIRED
xml:lang NMTOKEN #IMPLIED
BrandId CDATA #REQUIRED
BrandName CDATA #REQUIRED
BrandLogoNetLocn CDATA #REQUIRED
BrandNarrative CDATA #IMPLIED
ProtocolAmountRefs IDREFS #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID Element identifier, potentially referenced in a
Brand Selection Component contained in a later
Payment Request message and uniquely identifies
the Brand element within the IOTP Transaction.
xml:lang Defines the language used by attributes and
content of this element. See section 3.8
Identifying Languages.
BrandId This contains a unique identifier for the brand
(or promotional brand). It is used to match
against a list of Payment Instruments which the
Consumer holds to determine whether or not the
Consumer can pay using the Brand.
Values of BrandId are managed under the procedure
described in section 12 IANA Considerations.
As values of BrandId are controlled under the
procedures defined in section 12 IANA
Considerations user defined values may be
defined.
BrandName This contains the name of the brand, for example
MasterCard Credit. This is the description of the
Brand which is displayed to the consumer in the
Consumers language defined by xml:lang. For
example it might be "American Airlines Advantage
Visa". Note that this attribute is not used for
matching against the payment instruments held by
the Consumer.
BrandLogoNetLocn The net location which can be used to download
the logo for the Organisation. See section
Retrieving Logos (see section 10).
The content of this attribute must conform to
[RFC1738].
BrandNarrative This optional attribute is designed to be used by
the Merchant to indicate some special conditions
or benefit which would apply if the Consumer
selected that brand. For example "5% discount",
"free shipping and handling", "free breakage
insurance for 1 year", "double air miles apply",
etc.
ProtocolAmountRefs Identifies the protocols and related currencies
and amounts which can be used with this Brand.
Specified as a list of ID's of Protocol Amount
Elements (see section 7.7.3) contained within the
Brand List.
ContentSoftwareId See section 14.Glossary.
Content:
ProtocolBrand Protocol Brand elements contain brand information
to be used with a specific payment protocol (see
section 7.7.2)
PackagedContent Optional Packaged Content (see section 3.7)
elements containing information about the brand
which may be used by the payment protocol. The
content of this information is defined in the
supplement for a payment protocol which describes
how the payment protocol works with IOTP.
Example Brand Elements are contained in section 11.2 Brand List
Examples.
7.7.2 Protocol Brand Element
The Protocol Brand Element contains information that is specific to
the use of a particular Protocol with a Brand. Its definition is as
follows.
<!ELEMENT ProtocolBrand (PackagedContent*) >
<!ATTLIST ProtocolBrand
ProtocolId CDATA #REQUIRED
ProtocolBrandId CDATA #REQUIRED >
Attributes:
ProtocolId This must match the value of a ProtocolId
attribute in a Pay Protocol Element (see section
7.7.5).
The values of ProtocolId should be unique within a
Brand Element otherwise there is an error.
ProtocolBrandId This is the Payment Brand Id to be used with a
particular payment protocol. For example, SET and
EMV have their own well defined, yet different,
values for the Brand Id to be used with each
protocol.
The valid values of this attribute are defined in
the supplement for the payment protocol identified
by ProtocolId that describes how the payment
protocol works with IOTP.
Content:
PackagedContent Optional Packaged Content (see section 3.7)
elements containing information about the
protocol/brand which may be used by the payment
protocol. The content of this information is
defined in the supplement for a payment protocol
which describes how the payment protocol works
with IOTP.
7.7.3 Protocol Amount Element
The Protocol Amount element links a Brand to:
o the currencies and amounts in Currency Amount Elements (see
section 7.7.4) that can be used with the Brand, and
o the Payment Protocols and Payment Handlers defined in a Pay
Protocol Element (see section 7.7.5), which can be used with those
currencies and amounts.
Its definition is as follows:
<!ELEMENT ProtocolAmount (PackagedContent*) >
<!ATTLIST ProtocolAmount
ID ID #REQUIRED
PayProtocolRef IDREF #REQUIRED
CurrencyAmountRefs IDREFS #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID Element identifier, potentially referenced in a
Brand element; or in a Brand Selection Component
contained in a later Payment Request message
which uniquely identifies the Protocol Amount
element within the IOTP Transaction.
PayProtocolRef Contains an Element Reference (see section 3.5)
that refers to the Pay Protocol Element (see
section 7.7.5) that contains the Payment Protocol
and Payment Handlers that can be used with the
Brand.
CurrencyAmountRefs Contains a list of Element References (see
section 3.5) that refer to the Currency Amount
Element (see section 7.7.4) that describes the
currencies and amounts that can be used with the
Brand.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Optional Packaged Content (see section 3.7)
elements containing information about the protocol
amount which may be used by the payment protocol.
The content of this information is defined in the
supplement for a payment protocol which describes
how the payment protocol works with IOTP.
Examples of Protocol Amount Elements are contained in section 11.2
Brand List Examples.
7.7.4 Currency Amount Element
A Currency Amount element contains:
o a currency code (and its type), and
o an amount.
One or more of these elements is carried in each Brand List
Component. Its definition is as follows:
<!ELEMENT CurrencyAmount EMPTY >
<!ATTLIST CurrencyAmount
ID ID #REQUIRED
Amount CDATA #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED >
Attributes:
ID Element identifier, potentially referenced in a
Brand element; or in a Brand Selection Component
contained in a later Payment Request message which
uniquely identifies the Currency Amount Element
within the IOTP Transaction.
Amount Indicates the amount to be paid in whole and
fractional units of the currency. For example
$245.35 would be expressed "245.35". Note that
values smaller than the smallest denomination are
allowed. For example one tenth of a cent would be
"0.001".
CurrCodeType Indicates the domain of the CurrCode. This
attribute is included so that the currency code
may support non-standard "currencies" such as
frequent flyer points, trading stamps, etc. Its
values may be:
o ISO4217-A (the default) indicates the currency
code is a three character alphabetic currency
code that conforms to [ISO 4217]
o IOTP indicates that values of CurrCode are
managed under the procedure described in
section 12 IANA Considerations
CurrCode A code which identifies the currency to be used in
the payment. The domain of valid currency codes is
defined by CurrCodeType
As values of CurrCodeType are managed under the
procedure described in section 12 IANA
Considerations user defined values of CurrCodeType
may be defined.
Examples of Currency Amount Elements are contained in section 11.2
Brand List Examples.
7.7.5 Pay Protocol Element
A Pay Protocol element specifies details of a Payment Protocol and
the Payment Handler that can be used with a Brand. One or more of
these elements is carried in each Brand List.
<!ELEMENT PayProtocol (PackagedContent*) >
<!ATTLIST PayProtocol
ID ID #REQUIRED
xml:lang NMTOKEN #IMPLIED
ProtocolId NMTOKEN #REQUIRED
ProtocolName CDATA #REQUIRED
ActionOrgRef NMTOKEN #REQUIRED
PayReqNetLocn CDATA #IMPLIED
SecPayReqNetLocn CDATA #IMPLIED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID Element identifier, potentially referenced in a
Brand element; or in a Brand Selection Component
contained in a later Payment Request message which
uniquely identifies the Pay Protocol element
within the IOTP Transaction.
xml:lang Defines the language used by attributes and
content of this element. See section 3.8
Identifying Languages.
ProtocolId Consists of a protocol name and version. For
example "SETv1.0".
The values of ProtocolId are defined by the
payment scheme/method owners in the document that
describes how to encapsulate a payment protocol
within IOTP.
ProtocolName A narrative description of the payment protocol
and its version in the language identified by
xml:lang. For example "Secure Electronic
Transaction Version 1.0". Its purpose is to help
provide information on the payment protocol being
used if problems arise.
ActionOrgRef An Element Reference (see section 3.5) to the
Organisation Component for the Payment Handler for
the Payment Protocol.
PayReqNetLocn The Net Location indicating where an unsecured
Payment Request message should be sent if this
protocol choice is used.
The content of this attribute is dependent on the
Transport Mechanism (such must conform to
[RFC1738].
SecPayReqNetLocn The Net Location indicating where a secured
Payment Request message should be sent if this
protocol choice is used.
A secured payment involves the use of a secure
channel such as [SSL/TLS] in order to communicate
with the Payment Handler.
The content of this attribute must conform to
[RFC1738]. See also See section 3.9 Secure and
Insecure Net Locations.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Optional Packaged Content elements (see section
3.7) containing information about the protocol
which is used by the payment protocol. The content
of this information is defined in the supplement
for a payment protocol which describes how the
payment protocol works with IOTP. An example of
its use could be to include a payment protocol
message.
Examples of Pay Protocol Elements are contained in section 11.2 Brand
List Examples.
7.8 Brand Selection Component
A Brand Selection Component identifies the choice of payment brand,
payment protocol and the Payment Handler. This element is used:
o in Payment Request messages within Baseline Purchase and Baseline
Value Exchange IOTP Transactions to identify the brand, protocol
and payment handler for a payment, or
o to, optionally, inform a merchant in a purchase of the payment
brand being used so that the offer and order details can be
amended accordingly.
In Baseline IOTP, the integrity of Brand Selection Components is not
guaranteed. However, modification of Brand Selection Components can
only cause denial of service if the payment protocol itself is secure
against message modification, duplication, and swapping attacks.
The definition of a Brand Selection Component is as follows.
<!ELEMENT BrandSelection (BrandSelBrandInfo?,
BrandSelProtocolAmountInfo?,
BrandSelCurrencyAmountInfo?) >
<!ATTLIST BrandSelection
ID ID #REQUIRED
BrandListRef NMTOKEN #REQUIRED
BrandRef NMTOKEN #REQUIRED
ProtocolAmountRef NMTOKEN #REQUIRED
CurrencyAmountRef NMTOKEN #REQUIRED >
Attributes:
ID An identifier which uniquely identifies the Brand
Selection Component within the IOTP Transaction.
BrandListRef The Element Reference (see section 3.5) of the
Brand List Component from which a Brand is being
selected
BrandRef The Element Reference of a Brand element within
the Brand List Component that is being selected
that is to be used in the payment.
ProtocolAmountRef The Element Reference of a Protocol Amount element
within the Brand List Component which is to be
used when making the payment.
CurrencyAmountRef The Element Reference of a Currency Amount element
within the Brand List Component which is to be
used when making the payment.
Content:
BrandSelBrandInfo, This contains any additional data that
BrandSelProtocolAmountInfo, may be required by a particular payment
BrandSelCurrencyAmountInfo brand or protocol. See sections 7.8.1,
7.8.2, and 7.8.3.
The following rules apply:
o the BrandListRef must contain the ID of a Brand List Component in
the same IOTP Transaction
o every Brand List Component in the Trading Protocol Options Block
(see section 8.1) must be referenced by one and only one Brand
Selection Component
o the BrandRef must refer to the ID of a Brand contained within the
Brand List Component referred to by BrandListRef
o the ProtocolAmountRef must refer to one of the Element IDs listed
in the ProtocolAmountRefs attribute of the Brand element
identified by BrandRef
o the CurrencyAmountRef must refer to one of the Element IDs listed
in the CurrencyAmountRefs attribute of the Protocol Amount Element
identified by ProtocolAmountRef.
An example of a Brand Selection Component is included in 11.2 Brand
List Examples.
7.8.1 Brand Selection Brand Info Element
The Brand Selection Brand Info Element contains any additional data
that may be required by a particular payment brand. See the IOTP
payment method supplement for a description of how and when it used.
<!ELEMENT BrandSelBrandInfo (PackagedContent+) >
<!ATTLIST BrandSelBrandInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Packaged Content elements (see section 3.7) that
contain additional data that may be required by a
particular payment brand. See the payment method
supplement for IOTP for rules on how this is used.
7.8.2 Brand Selection Protocol Amount Info Element
The Brand Selection Protocol Amount Info Element contains any
additional data that is payment protocol specific that may be
required by a particular payment brand or payment protocol. See the
IOTP payment method supplement for a description of how and when it
used.
<!ELEMENT BrandSelProtocolAmountInfo (PackagedContent+) >
<!ATTLIST BrandSelProtocolAmountInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Packaged Content elements (see section 3.7) that
may contain additional data that may be required
by a particular payment brand. See the payment
method supplement for IOTP for rules on how this
is used.
7.8.3 Brand Selection Currency Amount Info Element
The Brand Selection Currency Amount Info Element contains any
additional data that is payment brand and currency specific that may
be required by a particular payment brand. See the IOTP payment
method supplement for a description of how and when it used.
<!ELEMENT BrandSelCurrencyAmountInfo (PackagedContent+) >
<!ATTLIST BrandSelCurrencyAmountInfo
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Packaged Content elements (see section 3.7) that
contain additional data relating to the payment
brand and currency. See the payment method
supplement for IOTP for rules on how this is used.
7.9 Payment Component
A Payment Component contains information used to control how a
payment is carried out. Its provides information on:
o the times within which a Payment with a Payment Handler may be
started
o a reference to the Brand List (see section 7.7) which identifies
the Brands, protocols, currencies and amounts which can be used to
make a payment
o whether or not a payment receipt will be provided
o whether another payment precedes this payment.
Its definition is as follows.
<!ELEMENT Payment EMPTY >
<!ATTLIST Payment
ID ID #REQUIRED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
BrandListRef NMTOKEN #REQUIRED
SignedPayReceipt (True False) #REQUIRED
StartAfterRefs NMTOKENS #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Payment Component within the IOTP Transaction.
OkFrom The date and time in [UTC] format after which a
Payment Handler may accept for processing a
Payment Request Block (see section 8.7) containing
the Payment Component.
OkTo The date and time in [UTC] format before which a
Payment Handler may accept for processing a
Payment Request Block containing the Payment
Component.
BrandListRef An Element Reference (see section 3.5) of a Brand
List Component (see section 7.7) within the TPO
Trading Block for the IOTP Transaction. The Brand
List identifies the alternative ways in which the
payment can be made.
SignedPayReceipt Indicates whether or not the Payment Response
Block (see section 8.9) generated by the Payment
Handler for the payment must be digitally signed.
StartAfter Contains Element References (see section 3.5) of
other Payment Components which describe payments
which must be complete before this payment can
start. If no StartAfter attribute is present then
there are no dependencies and the payment can
start immediately
7.10 Payment Scheme Component
A Payment Scheme Component contains payment protocol information for
a specific payment scheme which is transferred between the parties
involved in a payment for example a [SET] message. Its definition is
as follows.
<!ELEMENT PaySchemeData (PackagedContent+) >
<!ATTLIST PaySchemeData
ID ID #REQUIRED
PaymentRef NMTOKEN #IMPLIED
ConsumerPaymentId CDATA #IMPLIED
PaymentHandlerPayId CDATA #IMPLIED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Payment Scheme Component within the IOTP
Transaction.
PaymentRef An Element Reference (see section 3.5) to the
Payment Component (see section 7.9) to which
this Payment Scheme Component relates. It is
required unless the Payment Scheme Component is
part of an Transaction Inquiry Status
Transaction (see section 9.2.1).
ConsumerPaymentId An identifier specified by the Consumer which,
if returned by the Payment Handler in another
Payment Scheme Component or by other means, will
enable the Consumer to identify which payment is
being referred to.
PaymentHandlerPayId An identifier specified by the Payment Handler
which, if returned by the Consumer in another
Payment Scheme Component, or by other means,
will enable the Payment Handler to identify
which payment is being referred to. It is
required on every Payment Scheme Component apart
from the one contained in a Payment Request
Block.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Contains payment scheme protocol information as
Packaged Content elements (see section 3.7). See
the payment scheme supplement for the definition
of its content.
Note that:
o the values of the Name attribute of each
packaged content element are defined by the
Payment Protocol Supplement
o 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
A Payment Receipt is a record of a payment which demonstrates how
much money has been paid or received. It is distinct from a purchase
receipt in that it contains no record of what was being purchased.
Typically the content of a Payment Receipt Component will contain
data which describes:
o the amount paid and its currency
o the date and time of the payment
o internal reference numbers which identify the payment to the
payment system
o potentially digital signatures generated by the payment method
which can be used to prove after the event that the payment
occurred.
If the Payment Method being used provides the facility then the
Payment Receipt Component should contain payment protocol messages,
or references to messages, which prove the payment occurred.
The precise definition of the content is Payment Method dependent.
Refer to the supplement for the payment method being used to
determine the rules that apply.
Information contained in the Payment Receipt Component should be
displayed or otherwise made available to the Consumer.
Note: If the Payment Receipt Component contains Payment Protocol
Messages, then the Messages will need to be processed by Payment
Method software to convert it into a format which can be understood
by the Consumer
The definition of a Payment Receipt Component is as follows.
<!ELEMENT PayReceipt (PackagedContent*) >
<!ATTLIST PayReceipt
ID ID #REQUIRED
PaymentRef NMTOKEN #REQUIRED
PayReceiptNameRefs NMTOKENS #IMPLIED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Payment Receipt Component within the IOTP
Transaction.
PaymentRef Contains an Element Reference (see section 3.5)
to the Payment Component (see section 7.9) to
which this payment receipt applies
PayReceiptNameRefs Optionally contains a list of the values of the
Name attributes of Packaged Content elements that
together make up the receipt. The Packaged
Content elements are contained either within:
o Payment Scheme Data components exchanged
between the Payment Handler and the Consumer
roles during the Payment, and/or
o the Payment Receipt component itself.
Note that:
o each payment scheme defines in its supplement
the Names of the Packaged Content elements
that must be listed in this attribute (if
any).
o if a Payment Scheme Component contains
Packaged Content elements with a name that
matches 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 that the payment receipt
can be reconstructed when required.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Optionally contains payment scheme payment receipt
information as Packaged Content elements (see
section 3.7). See the payment scheme supplement
for the definition of its content.
Note that:
o the values of the Name attribute of each
packaged content element are defined by the
Payment Protocol Supplement
o 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.
7.12 Payment Note Component
The Payment Note Component contains additional, non payment related,
information which the Payment Handler wants to provide to the
Consumer. For example, if a withdrawal or deposit were being made
then it could contain information on the remaining balance on the
account after the transfer was complete. The information should
duplicate information contained within the Payment Receipt Component.
Information contained in the Payment Note Component should be
displayed or otherwise made available to the Consumer. For
interoperability, the Payment Note Component should support, as a
minimum, the content types of "Plain Text", HTML and XML. Its
definition is as follows.
<!ELEMENT PaymentNote (PackagedContent+) >
<!ATTLIST PaymentNote
ID ID #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Payment Receipt Component within the IOTP
Transaction.
ContentSoftwareId See section 14. Glossary.
Content:
PackagedContent Contains additional, non payment related,
information which the Payment Handler wants to
provide to the Consumer as one or more Packaged
Content elements (see section 3.7).
7.13 Delivery Component
The Delivery Element contains information required to deliver goods
or services. Its definition is as follows.
<!ELEMENT Delivery (DeliveryData?, PackagedContent*) >
<!ATTLIST Delivery
ID ID #REQUIRED
xml:lang NMTOKEN #REQUIRED
DelivExch (True False) #REQUIRED
DelivAndPayResp (True False) #REQUIRED
ActionOrgRef NMTOKEN #IMPLIED >
Attributes:
ID An identifier which uniquely identifies the
Delivery Component within the IOTP Transaction.
xml:lang Defines the language used by attributes or child
elements within this component, unless overridden
by an xml:lang attribute on a child element. See
section 3.8 Identifying Languages.
DelivExch Indicates if this IOTP Transaction includes the
messages associated with a Delivery Exchange.
Valid values are:
o True indicates it does include a Delivery
Exchange
o False 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 if the Delivery Response Block (see
section 8.11) and the Payment Response Block (see
section 8.9 ) are combined into one IOTP Message.
Valid values are:
o True indicates both blocks will be in the
same IOTP Message, and
o False indicates each block will be in a
different IOTP Message
DelivAndPayResp should not be true if DelivExch
is False.
In practice combining the Delivery Response Block
and Payment Response Block is only likely to be
practical if the Merchant, the Payment Handler
and the Delivery Handler are the same
Organisation since:
o the Payment Handler must have access to Order
Component information so that they know what
to deliver, and
o 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
which is required by the Delivery Handler as one
or more Packaged Content Elements see section 3.7.
7.13.1 Delivery Data Element
The DeliveryData element contains information about where and how
goods are to be delivered. Its definition is as follows.
<!ELEMENT DeliveryData (PackagedContent*) >
<!ATTLIST DeliveryData
xml:lang NMTOKEN #IMPLIED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
DelivMethod NMTOKEN #REQUIRED
DelivToRef NMTOKEN #REQUIRED
DelivReqNetLocn CDATA #REQUIRED
SecDelivReqNetLocn CDATA #REQUIRED
ContentSoftwareId CDATA #IMPLIED >
Attributes:
xml:lang Defines the language used by attributes within
this component. See section 3.8 Identifying
Languages.
OkFrom The date and time in [UTC] format after which the
Delivery Handler may accept for processing a
Delivery Request Block (see section 8.10).
OkTo The date and time in [UTC] format before which
the Delivery Handler may accept for processing a
Delivery Request Block.
DelivMethod Indicates the method by which goods or services
may be delivered. Valid values are:
o Post the goods will be delivered by post or
courier