RFC 3867
Payment Application Programmers Interface (API) for v1.0 Internet Open Trading Protocol (IOTP)
Pages: 106
Informational
Informational
Part 3 of 4 – Pages 34 to 66
3. Mutuality
The Payment API is formalized using the eXtensible Markup Language (XML). It defines wrapper elements for both the input parameters and the API function's response. In particular, the response wrapper provides common locations for Error Codes and Error Descriptions. It is anticipated that this description reflects the logical structure of the API parameter and might be used to derive implementation language specific API definitions. XML definition: <!ELEMENT IotpPaymentApiRequest ( FindAcceptedPaymentBrand | FindAcceptedPaymentProtocol | GetPaymentInitializationData | FindPaymentInstrument | CheckPaymentPossiblity | StartPaymentConsumer | StartPaymentPaymentHandler | ResumePaymentConsumer | ResumePaymentPaymentHandler | ContinueProcess | InquireProcessState | ChangeProcessState | InquireAuthChallenge | Authenticate |
CheckAuthResponse |
CheckPaymentReceipt |
ExpandPaymentReceipt |
RemovePaymentLog |
PaymentInstrumentInquiry |
InquirePendingPayment |
ManagePaymentSoftware |
StartPaymentInquiry |
InquirePaymentStatus |
CallBack )>
<!ATTLIST IotpPaymentApi
xml:lang NMTOKEN #IMPLIED
ContentSoftwareID CDATA #IMPLIED
xmlns CDATA #FIXED
"http://www.iotp.org/2000/08/PaymentAPI" >
<!ELEMENT IotpPaymentApiResponse (ErrorResponse?, (
FindAcceptedPaymentBrandResponse |
FindAcceptedPaymentProtocolResponse |
GetPaymentInitializationDataResponse |
FindPaymentInstrumentResponse |
CheckPaymentPossiblityResponse |
StartPaymentConsumerResponse |
StartPaymentPaymentHandlerResponse |
ResumePaymentConsumerResponse |
ResumePaymentPaymentHandlerResponse |
ContinueProcessResponse |
InquireProcessStateResponse |
ChangeProcessStateResponse |
InquireAuthChallengeResponse |
AuthenticateResponse |
CheckAuthResponseResponse |
CheckPaymentReceiptResponse |
ExpandPaymentReceiptResponse |
RemovePaymentLogResponse |
PaymentInstrumentInquiryResponse |
InquirePendingPaymentResponse |
ManagePaymentSoftwareResponse |
StartPaymentInquiryResponse |
InquirePaymentStatusResponse |
CallBackResponse )?)>
<!ATTLIST IotpPaymentApiResponse
xml:lang NMTOKEN #IMPLIED
ContentSoftwareID CDATA #IMPLIED
xmlns CDATA #FIXED
"http://www.iotp.org/2000/08/PaymentAPI" >
<!ELEMENT ErrorResponse (ErrorLocation+,PaySchemePackagedContent*) >
<!ATTLIST ErrorResponse
xml:lang NMTOKEN #IMPLIED
ErrorCode NMTOKEN #REQUIRED
ErrorDesc CDATA #REQUIRED
Severity(Warning |
TransientError |
HardError) #REQUIRED
MinRetrySecs CDATA #IMPLIED
SwVendorErrorRef CDATA #IMPLIED >
Most of the attribute items are intended for immediate insertion in
the IOTP Error Block. The attribute values of the Error Location
elements attribute have to enriched and transformed into Error
Location Elements of the Error Component (cf. IOTP Specification).
Attributes (cf. IOTP Specification):
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.
ContentSoftwareId Contains information which identifies the
software that generated the content of the
element. Its purpose is to help resolve
interoperability problems that might occur as
a result of incompatibilities between messages
produced by different software. It is a single
text string in the language defined by
"xml:lang". It must contain, as a minimum
problems that might occur as a result of
o the name of the software manufacturer,
o the name of the software,
o the version of the software, and
o the build of the software.
ErrorCode Contains an error code which indicates the
nature of the error in the message in error.
Valid values for the Error Code are given in
the following section. This mnemonic enables
the automatic failure resolution of the IOTP
Application Core which analyzes the error code
value in order to determine the continuation
alternatives.
ErrorDesc Contains a description of the error in the
language defined by xml:lang. The content of
this attribute is defined by the
vendor/developer of the software that
generated the Error Response Element.
It is intended for user display and provides
detailed explanations about the failure and
its (out-of-band) resolution alternatives.
Severity Indicates the severity of the error. Valid
values are:
o Warning. This indicates that although there
is a message in error the IOTP Transaction
can still continue.
o TransientError. This indicates that the
error in the message in error may be
recovered if the message in error that is
referred to by the "Names" attribute is
resent.
o HardError. This indicates that there is an
unrecoverable error in the message in error
and the IOTP Transaction must stop.
MinRetrySecs This attribute should be present if "Severity"
is set to "TransientError". It is the minimum
number of whole seconds which the IOTP aware
application which received the message
reporting the error should wait before
resending the message in error identified by
the "ErrorLocation" attribute.
If Severity is not set to
"TransientError" then the value of this
attribute is ignored.
SwVendorErrorRef This attribute is a reference whose value is
set by the vendor/developer of the software
that generated the Error Element. It should
contain data that enables the vendor to
identify the precise location in their
software and the set of circumstances that
caused the software to generate a message
reporting the error.
Content:
ErrorLocation This identifies, where possible, the
element and attribute in the message
in error that caused the Error
Element to be generated. If the
"Severity" of the error is not
"TransientError", more that one
"ErrorLocation" may be specified as
appropriate depending on the nature
of the error and at the discretion of
the vendor/developer of the IOTP
Payment Bridge.
Its definition coincides with the
IOTP specification whereby the
attributes "IotpMsgRef", "BlkRef" and
"CompRef" are left blank,
intentionally.
PaySchemePackagedContent cf. Table 5
3.1. Error Codes
The following table lists the valid values for the ErrorCode
attribute of the Error Response Element. The first sentence of the
error description contains the default text that can be used to
describe the error when displayed or otherwise reported. Individual
implementations may translate this into alternative languages at
their discretion. However, not every error code may apply to every
API call. An Error Code must not be more than 14 characters long.
The Error Codes have been taken from the IOTP Specification and
extended by some additional codes which are highlighted by a
preceding asterisk.
Generally, if the corrupt values have been user supplied, the IOTP
Application Core might prompt for their correction. If the renewal
fails or if the IOTP Application Core skips any renewals and some
notification has to be send to the counter-party, the error code is
encapsulated within an IOTP Error Block.
However, the IOTP server application reports business errors -
visible at the IOTP layer - in the Status Component of the respective
Response Block.
The IOTP Application Core may add the attributes (and values) within
the ErrorLocation elements that are omitted by the IOTP Payment
Bridge.
The following table mentions any modification from this general
processing for particular error values. Furthermore, it contains
hints for developers of IOTP Application Core software components
about the processing of error codes. Conversely, developers of IOTP
Payment Bridges get impressions about the expected behavior of the
IOTP Application Core.
The IOTP Payment API assumes that the IOTP Application Core
implements the dialog boxes needed for error resolution. But it does
not assume, that the IOTP Payment Bridge actually relies on them.
Instead, the IOTP Payment Bridge may try resolution on its own, may
implement specific dialog boxes, and may signal only final failures.
Note: This abstract document assumes that the API parameters are
exchanged XML encoded. Therefore, several error values might
disappear in lower level language specific derivations.
Error Value Error Description
----------- -----------------
Reserved Reserved. This error is reserved by the
vendor/developer of the software. Contact
the vendor/developer of the software for
more information (see the SoftwareId
attribute of the Message Id element in the
Transaction Reference Block [IOTP]).
XmlNotWellFrmd XML not well formed. The XML document is not
well formed. See [XML] for the meaning of
"well formed".
XmlNotValid XML not valid. The XML document is well
formed but the document is not valid. See
[XML] for the meaning of "valid".
Specifically:
o the XML document does not comply with the
constraints defined in the IOTP document
type declaration, and
o the XML document does not comply with the
constraints defined in the document type
declaration of any additional [XML-NS]
that are declared.
The Names attribute might refer some
attributes and elements of the input
parameter list.
(*)ElNotValid Element not valid. Invalid element in terms
of prescribed syntactical characteristics.
The ElementRef attributes of ErrorLocation
elements might refer to the corresponding
elements (if they have ID attributes).
The IOTP Application Core has to replace the
error code with "XmlNotValid" before
transmission to the counterparty.
ElUnexpected Unexpected element. Although the XML
document is well formed and valid, an
element is present that is not expected in
the particular context according to the
rules and constraints contained in this
specification.
The ElementRef attributes of ErrorLocation
elements might refer to the corresponding
elements (if they have ID attributes).
ElNotSupp Element not supported. Although the document
is well formed and valid, an element is
present that
o is consistent with the rules and
constraints contained in this
specification, but
o is not supported by the IOTP Aware
Application which is processing the IOTP
Message.
The ElementRef attributes of ErrorLocation
elements might refer to the corresponding
elements (if they have ID attributes).
ElMissing Element missing. Although the document is
well formed and valid, an element is missing
that should have been present if the rules
and constraints contained in this
specification are followed.
The ElementRef attributes of ErrorLocation
elements might refer to the corresponding
elements (if they have ID attributes).
ElContIllegal Element content illegal. Although the
document is well formed and valid, the
element contains values which do not conform
the rules and constraints contained in this
specification.
The ElementRef attributes of ErrorLocation
elements might refer to the corresponding
element (if they have ID attributes).
The IOTP Application Core has to replace the
Error Code with "ElNotSupp" before
transmission to the counter party, if the
ErrorLocation elements refer to
non-PackagedContent element.
EncapProtErr Encapsulated protocol error. Although the
document is well formed and valid, the
Packaged Content of an element contains data
from an encapsulated protocol which contains
errors.
The ElementRef attributes of ErrorLocation
elements might refer to the corresponding
element (if they have ID attributes).
AttUnexpected Unexpected attribute. Although the XML
document is well formed and valid, the
presence of the attribute is not expected in
the particular context according to the
rules and constraints contained in this
specification.
The AttName attributes of ErrorLocation
elements might refer to the corresponding
attribute tags.
(*)AttNotValid Attribute not valid. Invalid attribute value
in terms of prescribed syntactical
characteristics.
The AttName attributes of ErrorLocation
elements might refer to the corresponding
attribute tags.
The IOTP Application Core has to replace the
error code with "XmlNotValid" before
transmission to the counter party.
AttNotSupp Attribute not supported. Although the XML
document is well formed and valid, and the
presence of the attribute in an element is
consistent with the rules and constraints
contained in this specification, it is not
supported by the IOTP Aware Application
which is processing the IOTP Message.
AttMissing Attribute missing. Although the document is
well formed and valid, an attribute is
missing that should have been present if the
rules and constraints contained in this
specification are followed.
The AttName attributes of ErrorLocation
elements might refer to the corresponding
attribute tags.
If the attribute is required by the IOTP
Document Type Declaration (#REQUIRED) the
hints for non-valid attributes should be
adopted, otherwise these for illegal
attribute values.
AttValIllegal Attribute value illegal. The attribute
contains a value which does not conform to
the rules and constraints contained in this
specification.
The AttName attributes of ErrorLocation
elements might refer to the corresponding
attribute tags - valid values are:
BrandId: illegal/unknown Brand Identifier -
If the brand is not recognized/known by any
IOTP Payment Bridge, the IOTP Application
Core may offer the registration of a new
Payment Instrument.
PaymentInstrumentId: illegal/unknown
Payment Instrument Identifier - This
indicates a serious communication problem if
the attribute value has been reported by the
same "wallet" on a previous inquiry
requests. The IOTP Application Core has to
replace the error code with
"UnknownError" before transmission to the
counter party.
WalletId: illegal/unknown Wallet Identifier
- It is assumed that the wallet identifier
is checked before the pass phrase. On
invalid wallet identifiers, the IOTP
Application Core may open the dialog in
order to request the correct wallet
identifier. In addition, any pass phrase may
be supplied by the user. The dialog should
indicate the respective payment brand(s).
The IOTP Application Core has to replace the
error code with "UnknownError" before
transmission to the counter party.
Passphrase: illegal/unknown Pass Phrase -
The IOTP Application Core may open the
dialog in order to request the correct pass
phrase. If the pass phrase is wallet
identifier specific the dialog should
display the wallet identifier. The IOTP
Application Core has to replace the error
code with "TransportError" before
transmission to the counter party.
Action: illegal / unknown / unsupported
Action
PropertyTypeList: lists contains illegal /
unknown / unsupported Property Types - The
IOTP Application Core tries only the local
resolution but does never transmit any IOTP
Error Block to the counter party.
CurrCode: illegal/unknown/unsupported
Currency Code
CurrCodeType: illegal/unknown/unsupported
Currency Code Type
Amount: illegal/unknown/unsupported Payment
Amount
PayDirection: illegal/unknown/unsupported
Payment Direction
ProtocolId: illegal/unknown/unsupported
Protocol Identifier
OkFrom: illegal/unknown/unsupported OkFrom
Timestamp
OkTo: illegal/unknown/unsupported OkTo
Timestamp
ConsumerPayId: illegal/unknown Consumer
Payment Identifier
PaymentHandlerPayId: illegal/unknown Payment
Handler Payment Identifier
PayId: illegal/unknown Payment Identifier
AttValNotRecog Attribute Value Not Recognized. The
attribute contains a value which the IOTP
Aware Application generating the message
reporting the error could not recognize.
The AttName attributes of ErrorLocation
elements might refer to the corresponding
attribute tags.
MsgTooLarge Message too large. The message is too large
to be processed by the IOTP Payment Bridge
(or IOTP Application Core).
ElTooLarge Element too large. The element is too large
to be processed by the IOTP Payment Bridge
(or IOTP Application Core).
The ElementRef attributes of ErrorLocation
elements might refer to the corresponding
elements.
ValueTooSmall Value too small or early. The value of all
or part of an element content or an
attribute, although valid, is too small.
The ErrorLocation elements might refer to
the corresponding attribute tags or
elements.
ValueTooLarge Value too large or in the future. The value
of all or part of an element content or an
attribute, although valid, is too large.
The ErrorLocation elements might refer to
the corresponding attribute tags or
elements.
ElInconsistent Element Inconsistent. Although the document
is well formed and valid, according to the
rules and constraints contained in this
specification:
o the content of an element is inconsistent
with the content of other elements or
their attributes, or
o the value of an attribute is inconsistent
with the value of one or more other
attributes.
The Error Description may contain further
explanations.
The ErrorLocation elements might refer to
the corresponding attribute tags or elements
that are inconsistent.
TransportError Transport Error. This error code is used to
indicate that there is a problem with the
transport mechanism that is preventing the
message from being received. It is typically
associated with a "Transient Error".
The connection to some periphery or the
counter party could not be established,
is erroneous, or has been lost.
The Error Description may contain further
narrative explanations, e.g., "chip card
does not respond", "remote account manager
unreachable", "Internet connection to xyz
lost", "no Internet connection available",
"no modem connected", or "serial port to
modem used by another application". This
text should be shown to the end user. If
timeout has occurred at the Consumer this
text should be shown and the Consumer may
decide how to proceed - alternatives are
retry, payment transaction suspension, and
cancellation.
MsgBeingProc Message Being Processed. This error code is
only used with a Severity of Transient
Error. It indicates that the previous
message, which may be an exchange message or
a request message, is being processed and,
if no response is received by the time
indicated by the "MinRetrySecs" attribute,
then the original message should be resent.
SystemBusy System Busy. This error code is only used
with a Severity of Transient Error. It
indicates that the IOTP Payment Bridge or
Existing Payment Software that received the
API request is currently too busy to handle
it. If no response is received by the time
indicated by the "MinRetrySecs" attribute,
then the original message should be resent.
The Error Description may provide further
explanations, e.g., "wallet / chip card
reader is unavailable or locked by another
payment transaction", "payment gateway is
overloaded", "unknown chip card reader", or
"unrecognized chip card inserted, change
chip card".
The Consumer's IOTP Application Core may
display the error description and ask the
Consumer about the continuation -
alternatives are retry, payment transaction
suspension, and cancellation.
UnknownError Unknown Error. Indicates that the
transaction cannot complete for some reason
that is not covered explicitly by any of the
other errors. The Error description
attribute should be used to indicate the
nature of the problem.
The ErrorLocation elements might refer to
the corresponding attribute tags or elements
that are inconsistent.
(*)SyntaxError Syntax Error. An (unknown) syntax error has
occurred.
The ErrorLocation elements might refer to
the corresponding attribute tags or elements
that are inconsistent.
The IOTP Application Core has to replace the
error code with "XmlNotValid" or
"UnknownError" before transmission to the
counter party.
(*)ReqRefused Request refused. The API request is
(currently) refused by the IOTP Payment
Bridge. The error description may provide
further explanations, e.g., "wallet / chip
card reader is unavailable or locked by
another payment transaction", "payment
gateway is overloaded", "unknown chip card
reader", or "unrecognized chip card
inserted, change chip card".
The Consumer's IOTP Application Core may
display the error description and ask the
Consumer about the continuation -
alternatives are retry, payment transaction
suspension, and cancellation. Denials due to
invalid Process States should be signaled by
"BusinessError". Typically, this kind of
error is not passed to the counter party's
IOTP Application Core. Otherwise, it maps to
"TransportError" or "UnknownError".
(*)ReqNotSupp Request not supported. The API
function(ality) has not been implemented in
the IOTP Payment Bridge. Typically, this
kind of error is not passed to the
counter party's IOTP Application Core.
Otherwise, it maps to "TransportError" or
"UnknownError".
(*)BusError Business Error. The API request has been
rejected because some payment transaction
has an illegal payment status.
Particularly, this error code is used to
signal any raise of payment business layered
failures.
The ErrorLocation elements may refer to
payment transactions using the party's
Payment Identifier - it defaults to the
current transaction or might contain the
current payment transaction party's Payment
Identifier - identified by the ElementRef
attribute while the AttName attribute is
fixed with "PayId".
The IOTP Application Core must inquire the
IOTP Payment Bridge about the actual Process
State which actually encodes the business
error ("Inquire Process State").
This error code must not be
passed to the counter party's IOTP
Application Core.
Table 2: Common Error Codes
The IOTP Payment Bridge may also use the error description in order
to notify the Consumer about further necessary steps for failure
resolution, e.g., "Sorry, your payment transaction failed.
Unfortunately, you have been charged, please contact your issuer."
3.2. Attributes and Elements
The following table explains the XML attributes in alphabetical order
- any parenthesized number after the attribute tag is a recommended
maximal length of the attribute value in characters:
Attribute Description
--------- -----------
Amount (11) Indicates the payment amount to be paid in
AmountFrom(11) whole and fractional units of the currency.
AmountTo (11) 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".
AuthenticationId An identifier specified by the
authenticator which, if returned by the
organization that receives the
authentication request, will enable the
authenticator to identify which
authentication is being referred to.
BrandId (128) 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 with the
Brand.
Values of BrandId are managed under
procedure being described in the IOTP
protocol specification.
BrandLogoNetLocn The net location which can be used to
download the logo for the organization (cf.
IOTP Specification).
The content of this attribute must conform
to [URL].
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 Consumer's 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.
BrandNarrative This optional attribute is
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.
CallBackFunction A function which is called whenever there is
a change of Process State or payment
progress, e.g., for display updates. However,
the IOTP Payment Bridge may use its own
mechanisms and dialog boxes.
CallBackLanguageList
A list of language codes which contain, in
order of preference, the languages in which
the text passed to the Call Back function
will be encoded.
CompletionCode (14) Indicates how the process completed.
It is required if ProcessState is set to
"Failed" otherwise it is ignored. Valid
values as well as recovery options are given
in the IOTP specification.
The IOTP Payment Bridge may also use the
Status Description to notify the Consumer
about further necessary steps in order to
resolve some kind of business failures,
e.g.,
o "sorry, your payment transaction failed.
Unfortunately, you have been charged,
please contact your issuer."
o "insufficient capacity left (on your
stored value card) for refund",
o "payment failed/chip card error/internal
error, please contact your payment
instrument's issuer"
ConsumerDesc A narrative description of the Consumer.
ConsumerPayId (14) An unique identifier specified by the
Consumer that, if returned by the Payment
Handler in another Payment Scheme Component
or by other means, enables the Consumer to
identify which payment is being referred to.
This unique identifier is generated by the
IOTP Application Core and submitted to the
IOTP Payment Bridge on every API call. It
may equal the Payment Handler Payment
Identifiers but need not necessarily be so.
The uniqueness extends to multiple payment
instruments, payment brands, payment
protocols, wallet identifiers, and even
multiple IOTP Payment Bridges.
ContStatus During payment progress, this status value
indicates whether the payment needs to be
continued with further IOTP Payment Scheme
Component exchanges with the remote party.
"End" indicates that the reported payment
scheme data is the last data to be exchanged
with the counter party.
ContentSoftwareId This contains information that identifies
the software that generated the content of
the element. Its purpose is to help resolve
interoperability problems that might occur
as a result of incompatibilities between
messages produced by different software. It
is a single text string in the language
defined by xml:lang. It must contain, as a
minimum:
o the name of the software manufacturer,
o the name of the software,
o the version of the software, and
o the build of the software.
CurrCodeType (14) Indicates the domain of the CurrCode. This
attribute is included so that the currency
code may support nonstandard currencies
such as frequent flyer point, trading
stamps, etc. Its values may be
o ISO-4217-A, the default, indicates the
currency code is the three-letter
alphabetic code that conform to ISO-4217
[ISO4217].
o IOTP indicates that the values of
CurrCode are managed under the procedure
described in [IOTP].
CurrCode (14) A code which identifies the currency to be
used in the payment. The domain of valid
currency codes is defined by "CurrCodeType"
MerchantPayId (14) An private identifier specified by the
Merchant which will enable the Merchant to
identify which payment is being referred to.
It is a pure private item and is never sent
to any other party. It is provided by the
IOTP Payment Bridge on payment preparation
during brand compilation.
Cf. To "ConsumerPayId" for note about
uniqueness.
MerchantOrgId (64) A local item that might refer to some
specific shop in a multi shop environment.
This item is optional and might enrich the
Wallet Identifier which itself can be used
for the same purpose.
Name Distinguishes between multiple occurrences
of Packaged Content Elements at the same
point in IOTP. For example:
<ABCD>
<PackagedContent Name='FirstPiece'>
snroasdfnas934k
</PackagedContent>
<PackagedContent Name='SecondPiece'>
dvdsjnl5poidsdsflkjnw45
</PackagedContent>
</ABCD>
The "Name" attribute may be omitted, for
example if there is only one Packaged
Content element.
OkFrom (30) The date and time in UTC Format range
OkTo (30) indicated by the merchant in which the
Payment Handler may accept the payment.
For more information, see [UTC].
Passphrase (32) Payment wallets may use pass phrase
protection for transaction data and payment
instruments' data. However, it is assumed
that there exists a public and customizable
payment instrument identifier such that
these identifiers together with their
relationship to payment brands, payment
protocols, payment directions, and currency
amounts can be queried by the IOTP
application without any pass phrase
knowledge.
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.
PayId (14) This attribute is introduced for API
simplification:
o The Consumer has to identify PayId and
ConsumerPayId.
o The Merchant has to identify PayId and
MerchantPayId.
o The Payment Handler has to identify PayId
and Payment Handler Pay Id.
PayInstId This contains the unique identifier used
internally by the IOTP Payment
Bridge/Existing Payment Software.
PayInstName This contains the user-defined name of the
payment instrument. There exist no
(technical) constraints like uniqueness. The
"xml:lang" attribute denotes the language
encoding of its value.
PaymentHandlerDesc A narrative description of the Payment
Handler.
PaymentHandlerPayId An unique identifier specified by the
(14) Payment Handler that, if returned by the
Consumer in another Payment Scheme Component
or by other means, enables the Payment
Handler to identify which payment is being
referred to. It is required whenever it is
known.
Cf. To "ConsumerPayId" for note about
uniqueness.
PaymentInstrumentId An identifier for a specific payment
(32) instrument, e.g., "credit card", "Mondex card
for English Pounds". This identifier is
fully customizable. It is assumed, that it
does not contain confidential information or
even an indication of it. The payment
instrument identifier is unique within each
payment brand. It is displayed to the
Consumer during brand selection.
PayReceiptNameRefs Optionally contains element references to
(32) other elements (containing payment scheme
specific data) that together make up the
receipt. Note that each payment scheme
defines in its supplement the elements that
must be referenced
The IOTP Application Core should save all
the components referenced so that the
payment receipt can be reconstructed when
required.
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 must conform
to [URL] and depends on the Transport
Mechanism.
PercentComplete (3) A number between 0 and 100 which indicates
the progress of the payment transaction. The
values range between 0 and 99 for pending
and suspended transactions.
ProcessState Contains a Process State Code that
indicates the current state of the process
being carried out. Valid values are:
o NotYetStarted. The Payment Request Block
has been received but processing of the
Payment Request has not yet started
o InProgress. The payment transaction is
pending. The processing of the (Payment)
Request Block has started but it is not
yet complete.
o (*)Suspended: The payment transaction has
been suspended and can be resumed.
This process state is mapped to
"InProgress", if it is passed to the
counter party's IOTP Application Core.
o CompletedOk. The processing of the (Payment)
Request Block and any following Payment
Exchange Blocks has completed successfully.
o Failed. The payment processing has finally
failed for a Business Error.
o ProcessError. This value is only used
when the Status Component is being used in
connection with an Inquiry Request Trading
Block. It indicates there was a Technical
Error in the Request Block which is being
processed or some internal processing
error. Each party's IOTP Payment Bridge
uses this value in order to notify the
IOTP Application Core about the presence
of technical errors.
PropertyType (14) The property type defines codes used for
interrogation of specific properties about a
payment instrument. They are unique for each
payment brand. The predefined property "all"
is used on general inquiries. However, these
property types are not used during normal
payment processing. E.g., they may apply to
payment brand specific transactions or
out-of-band failure resolution.
PropertyDesc The property description carries the
respective human readable property (value)'s
description.
PropertyValue The actual property value intends automatic
post processing.
ProtocolBrandId (64)This is an identifier to be used with a
particular payment protocol. For example,
SET and EMV have their own well defined, yet
different, values for the Brand identifier
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.
Identifier maps to at most one Protocol
Brand Identifier.
ProtocolId (64) An identifier for a specific payment
protocol and version, e.g., "SETv1.0",
"ecash". Valid values are defined by
supplements to the IOTP specification and
they are unique within each payment brand.
ProtocolIds A sequence of Protocol Identifiers
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.
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 [TLS] in order
to communicate with the Payment Handler.
The content of this attribute must conform
to [URL].
ReceiverOrgId The Organization Identification which
receives the payment bridge processing
Trading Role Data PackagedContent.
StatusDesc (256) An optional textual description of the
current process state in the language
identified by "xml:lang" that should be
displayed to the Consumer. The usage of this
attribute is defined in the payment
supplement for the payment method being
used. Particularly, it provides hints for
out-of-band failure resolution. Its length
is limited to 256 characters.
StyleSheetNetLocn This contains the net location to a style
sheet with visualisation rules for XML
encoded data.
TimeStamp (30) The date and time in UTC Format when the
payment transaction has been started.
For more information on UTC, see [UTC].
WalletId (32) Many existing payment wallet software are
multiple wallet capable. The Wallet
Identifier selects the actual wallet. It is
assumed, that the wallet identifier is a
public item, that might be stored by the
IOTP Application Core.
xml:lang Defines the language used by the Process
State Description attribute (cf. IOTP
Specification)
Table 3: Attributes
The following table explains the XML elements in alphabetical order:
Element Description
------- -----------
Algorithm This contains information which describes
an Algorithm that may be used to generate
the Authentication response.
The algorithm that may be used is
identified by the Name attribute (cf. IOTP
Specification).
AuthReqPackagedContent The Authentication Request Packaged
Content originates from a Authentication
(Data/Response) Component's content
whereby the outermost element tags are
prefixed with "AuthReq". Its declaration
coincides with the Packaged Content's
declaration (cf. IOTP Specification). It
encapsulates the authentication challenge
value. The content of this information is
defined in the supplement for a payment
protocol.
AuthResPackagedContent The Authentication Response Packaged
Content originates from a Authentication
Response Component's content whereby the
outermost element tags are prefixed with
"AuthRes".
Its declaration coincides with the
Packaged Content's declaration (cf. IOTP
Specification). It encapsulates the
authentication response value. The
content of this information is defined in
the supplement for a payment protocol.
BrandPackagedContent Container for further payment brand
description. Its content originates from
a Brand Element content whose outermost
element tags are prefixed with "Brand".
Its declaration coincides with the
Packaged Content's declaration (cf. IOTP
Specification).
BrandSelBrandInfoPackagedContent
This contains any additional data that
may be required by a particular payment
brand. It forms the content of the Brand
Selection Brand Info Element.
BrandSelProtocolAmountInfoPackagedContent
This contains any additional data that
may be required by a particular payment
brand in the format. It forms the content
of the Brand Selection Protocol Amount
Info Element.
BrandSelCurrencyAmountInfoPackagedContent
This contains any additional data that is
payment brand and currency specific in
the format. It forms the content of the
Brand Selection Currency Amount Info
Element.
MerchantData Any merchant related data that might be
used by the IOTP Payment Bridge for
different purposes, e.g., it might
contain IDs to access some mall data,
but not cryptographic keys. Its Packaged
declaration coincides with the Content's
declaration (cf. IOTP Specification).
PackagedContent Generic Container for non-IOTP data (cf.
IOTP Specification).
PayProtocolPackagedContent
The Pay Protocol Packaged Content
originates from a Pay Protocol
Element's content whereby the outermost
element tags are prefixed with
"PayProtocol". It contains 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. Its
declaration coincides with the Packaged
Content's declaration (cf. IOTP
Specification).
PaySchemePackagedContent
The PayScheme Packaged Content originates
from a Payment Scheme Component's content
whereby the outermost element tags are
prefixed with "PayScheme". Its
declaration coincides with the Packaged
Content's declaration (cf. IOTP
Specification). It carries the payment
specific data. The content of this
information is defined in the supplement
for a payment protocol.
ProtocolAmountPackagedContent
The Protocol Amount Packaged Content
originates from a Protocol Amount
Element's content whereby the outermost
element tags are prefixed with "Amount".
Its declaration coincides with the
Packaged Content's declaration (cf. IOTP
Specification). It contains 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.
ProtocolBrandPackagedContent
The Protocol Brand Packaged Content
originates from a Protocol Brand
Element's content whereby the outermost
element tags are prefixed with
"ProtocolBrand". Its declaration
coincides with the Packaged Content's
declaration (cf. IOTP Specification). It
contains information about the brand
which might be used by the payment
protocol. The content of this information
is defined in the supplement for a
payment protocol.
ResponsePackagedContent
Container for authentication response
data. Its content originates from a
Authentication Response Component's
Packaged Content whose outermost element
tags are prefixed with "Response". Its
declaration coincides with the Packaged
Content's declaration (cf. IOTP
Specification).
TradingRoleDataPackagedContent
The TradingRoleData Packaged Content
originates from a TradingRoleData
Component's content whereby the outermost
element tags are prefixed with
"TradingRoleData". Its declaration
coincides with the Packaged Content's
declaration (cf. IOTP Specification). It
contains information from Merchant to
Payment Handler via Consumer about the
protocol which is used by the payment.
The content of this information is
defined in the supplement for a payment
protocol. The Name attribute in this
packaged contents must include prefix as
"Payment:" to indicate that the payment
bridge processes this, for example
"Payment:SET-OD". See [SET/IOTP] for
more information.
The element's declaration coincides with
the Packaged Content's declaration (cf.
IOTP Specification).
Table 4: Elements
XML definition:
<!ENTITY % AuthReqPackagedContent "PackagedContent">
<!ENTITY % AuthResPackagedContent "PackagedContent">
<!ENTITY % BrandPackagedContent "PackagedContent">
<!ENTITY % BrandSelInfoPackagedContent "PackagedContent">
<!ENTITY % BrandSelProtocolAmountPackagedContent
"PackagedContent">
<!ENTITY % BrandSelCurrencyAmountPackagedContent
"PackagedContent">
<!ENTITY % ProtocolAmountPackagedContent
"PackagedContent">
<!ENTITY % PayProtocolPackagedContent "PackagedContent">
<!ENTITY % TradingRoleDataPackagedContent "PackagedContent">
<!ENTITY % MerchantData "PackagedContent">
<!ENTITY % PaySchemePackagedContent "PackagedContent">
3.3. Process States
The IOTP Payment API supports six different attribute values that
encode the transaction status from the IOTP's point of view, i.e.,
the appropriate point of view at the interface between the IOTP
Application Core and IOTP Payment Bridge. This point of view does
not completely mimic the more detailed view on the actual payment by
the actual Existing Payment Software or IOTP Payment Bridge.
The following three tables distinguish between the Merchant's,
Consumer's, and Payment Handlers' environment. They extend the
aforementioned explanations towards the mapping between IOTP process
states and the internal payment scheme related states of the Existing
Payment Software/IOTP Payment Bridge.
3.3.1. Merchant
The Merchant's point of view of payment is limited to the local
payment initiation being interlaced with order processing because
IOTP assigns the actual payment processing to the Payment Handler.
ProcessState Description
------------ -----------
NotYetStarted The Payment Transaction exists within the
IOTP Application Core, i.e., the
Merchant's shop has already signaled to
the IOTP Application Core that an IOTP
transaction has been initiated by the
Consumer.
However, neither any API call has been
issued to the IOTP Payment Bridge nor has
the IOTP Order Request has been created.
InProgress The IOTP Application changes the process
state to this value when it issues the
first API call to the Payment Bridge
during Brand List compilation.
This value indicates that the Payment
Bridge might have some knowledge about
the expected payment or might have
performed some preparatory tasks (even
with the Payment Handler out-of-band to
IOTP).
However, this value does not indicate
that any IOTP Order Request has been
created and transmitted to the Consumer.
Suspended The IOTP transaction has been suspended
before the order request block has been
transmitted to the Consumer.
Implicitly, the payment is also deferred.
CompletedOk The IOTP Order Request has been
successfully created and transmitted to
the Consumer. Actually, this process
state indicates only that the order
processing has been finished.
But it contains no indication about the
status of the actual payment, which is
accepted by the Payment Handler.
However, successful order processing
signals the IOTP Application Core that a
payment with some specific parameters is
expected within the near future. And this
signal might be used by the Existing
Payment Software for similar purposes.
This attribute might be interpreted as
successful preparation of the payment
system.
Particularly, it is expected that the
Existing Payment Software maps this IOTP
status value to some other internal
value, e.g., "NotYetStarted", that is more
accurate from its point of view.
As IOTP provides no communication channel
between the Merchant and Payment Handler,
any change of payment process state will
be initiated out-of-band to IOTP, e.g., by
electronic statements of account or
payment scheme specific mechanisms.
Failed The IOTP transaction, i.e., order
processing, has failed for some
(business) reason and it is known that no
payment will occur.
This indication might be used to clear
all data about this transaction within
the Existing Payment Bridge (by
"RemovePaymentLog" or
"ChangeProcessState") or to reverse any
preparation (with the Payment Handler
out-of-band to IOTP).
However, the ideal point of view of IOTP
suspects that the actual payment
transaction has been neither started nor
initiated.
ProcessError The IOTP transaction, i.e., order
processing, has failed for some
(technical) reason and it is known that
no payment will occur.
This indication might be used to clear
all data about this transaction within
the Existing Payment Bridge (by
"RemovePaymentLog" or
"ChangeProcessState") or to reverse any
preparation (with the Payment Handler
out-of-band to IOTP).
However, the ideal point of view of IOTP
suspects that the actual payment
transaction has been neither started nor
initiated.
Table 5: Merchant
3.3.2. Consumer
The Consumer's IOTP Application Core restricts its point of view to
the payment transaction. It is assumed that the IOTP Payment Bridge
handles the preceding brand selection process in a stateless manner.
ProcessState Description
------------ -----------
NotYetStarted This encodes the initial process state of
any IOTP payment transaction. This value
is set during brand selection but it
normally will not change during the whole brand
selection process.
InProgress With the issuance of the Start Payment
Consumer API call, the IOTP Application
Core changes the process state to this
value.
Suspended The payment transaction has been
suspended. Suspension may occur anywhere
during brand selection (with the
Merchant) or payment processing (with the
Payment Handler). On resumption, the IOTP
Application Core and the IOTP Payment
Bridge have to use other internal data to
decide whether brand selection or actual
payment processing needs to be continued,
i.e., whether the process state needs to
be reset to "NotYetStarted" or
"InProgress".
Note that the Payment API assumes
stateless brand selection by the IOTP
Payment Bridge. Typically, any suspension
during brand selection requires the
repetition of the whole process. Hereby,
the IOTP Application Core might need to
consider any already negotiated
conditions in a brand depended purchase
(brand, protocol).
CompletedOk The successful payment has been
acknowledged by the Payment Handler, i.e.,
the successful IOTP Payment Response has
been received.
Implicitly, this implies successful order
processing.
Failed The IOTP transaction, i.e., order or
payment processing, has failed for some
(business) reason. In either case it is
known that the payment will not succeed.
ProcessError The IOTP transaction, i.e., order or
payment processing, has failed for some
(technical) reason.
However, the local process state might be
different from that of Payment Handler.
Table 6: Consumer
3.3.3. Payment Handler
The Payment Handler is responsible for the actual payment processing.
New payment transactions are reported by the Consumer with the
transmission of new IOTP Payment Request Blocks. IOTP Payment
Exchange Block are send by the Consumer for payment transaction
continuation and resumption.
ProcessState Description
------------ -----------
NotYetStarted This encodes the initial process state of
any payment transaction. Typically, this
value will last for a short amount of
time.
InProgress The IOTP Application Core changes the
process state changes to "InProgress"
when the Payment Handler starts with the
actual processing of the IOTP Payment
Request Block.
Note that this does not assume that the
"StartPaymentPaymentHandler" API function
has been called.
Suspended The payment transaction has been
suspended.
CompletedOk The payment has been processed,
successfully, i.e., the IOTP Payment
Response Block was created and
transmitted to the Consumer.
Failed The payment transaction, has finally
failed for some (business) reason.
Note that this value encodes the payment
state reported by the IOTP Payment Bridge
on "InquireProcessState". It neither
reflects whether the payment receipt has
been inquired nor whether the IOTP
Payment Response Block has been created
and submitted to the Consumer.
ProcessError The payment transaction, has finally
failed for some (technical) reason.
Note that this value encodes the payment
state reported by the IOTP Payment
Bridge. It does not reflect whether some
IOTP Error Block has been created and
submitted to the Consumer.
Table 7: Consumer
(page 66 continued on part 4)