|
Network Working Group Request for Comments: 3867 Category: Informational |
Y. Kawatsura Hitachi M. Hiroya Technoinfo Service H. Beykirch Atos Origin November 2004 |
This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited.
Copyright © The Internet Society (2004).
The Internet Open Trading Protocol (IOTP) provides a data exchange format for trading purposes while integrating existing pure payment protocols seamlessly. This motivates the multiple layered system architecture which consists of at least some generic IOTP application core and multiple specific payment modules.
This document addresses a common interface between the IOTP
application core and the payment modules, enabling the
interoperability between these kinds of modules. Furthermore, such
an interface provides the foundations for a plug-in-mechanism in
actual implementations of IOTP application cores.
Such interfaces exist at the Consumers', the Merchants' and the Payment Handlers' installations connecting the IOTP application core and the payment software components/legacy systems.
1. Introduction
1.1. General payment phases
1.2. Assumptions
2. Message Flow
2.1. Authentication Documentation Exchange
2.2. Brand Compilation
2.3. Brand Selection
2.4. Successful Payment
2.5. Payment Inquiry
2.6. Abnormal Transaction Processing
2.6.1. Failures and Cancellations
2.6.2. Resumption
2.7. IOTP Wallet Initialization
2.8. Payment Software Management
3. Mutuality
3.1. Error Codes
3.2. Attributes and Elements
3.3. Process States
3.3.1. Merchant
3.3.2. Consumer
3.3.3. Payment Handler
4. Payment API Calls
4.1. Brand Compilation Related API Calls
4.1.1. Find Accepted Payment Brand
4.1.2. Find Accepted Payment Protocol
4.1.3. Get Payment Initialization Data
4.1.4. Inquire Authentication Challenge
4.1.5. Authenticate
4.1.6. Check Authentication Response
4.2. Brand Selection Related API Calls
4.2.1. Find Payment Instrument
4.2.2. Check Payment Possibility
4.3. Payment Transaction Related API calls
4.3.1. Start Payment Consumer
4.3.2. Start Payment Payment Handler
4.3.3. Resume Payment Consumer
4.3.4. Resume Payment Payment Handler
4.3.5. Continue Process
4.3.6. Change Process State
4.4. General Inquiry API Calls
4.4.1. Remove Payment Log
4.4.2. Payment Instrument Inquiry
4.4.3. Inquire Pending Payment
4.5. Payment Related Inquiry API Calls
4.5.1. Check Payment Receipt
4.5.2. Expand Payment Receipt
4.5.3. Inquire Process State
4.5.4. Start Payment Inquiry
4.5.5. Inquire Payment Status
4.6. Other API Calls
4.6.1. Manage Payment Software
5. Call Back Function
6. Security Considerations
7. References
7.1. Normative References
7.2. Informative References
Acknowledgement
Authors' Addresses
Full Copyright Statement
Common network technologies are based on standardized and established Internet technologies. The Internet technologies provide mechanisms and tools for presentation, application development, network infrastructure, security, and basic data exchange.
Due to the presence of already installed trading roles' systems with their own interfaces (Internet shop, order management, payment, billing, and delivery management systems, or financial institute's legacy systems), IOTP has been limited to the common external interface over the Internet. However, some of these internal interfaces might be also standardized for better integration of IOTP aware components with of the existing infrastructure and its cost effective reuse. For more information on IOTP, see [IOTP] and [IOTPBOOK].
The typical Payment Handlers (i.e., financial institutes or near-bank organizations) as well as Merchants require an IOTP aware application that easily fits into their existing financial infrastructure. The Payment Handler might even insist on the reuse of special in-house solutions for some subtasks of the IOTP aware application, e.g., reflecting their cryptography modules, gateway interfaces, or physical environment. Therefore, their IOTP aware implementation really requires such clear internal interfaces.
More important, consumers demand modularization and clear internal interfaces: Their IOTP application aims at the support of multiple payment methods. Consumers prefer the flexible use of different seamless integrating payment methods within one trading application with nearly identical behavior and user interface. The existence of a well-defined interface enables payment software developers to bolt on their components to other developer's general IOTP Application Core.
Initially, this consideration leads to the two-level layered view of the IOTP software for each role, consisting of:
In order to isolate the changes on the infrastructure, the IOTP trading application has been three-layered:
As IOTP extends payment schemes to a trading scheme, primarily, this document focuses on payment modules, i.e., the interface between the IOTP Payment Bridge and the IOTP Application Core. It provides a standard method for exchanging payment protocol messages between the parties involved in a payment. But, it does not specify any interface for order or delivery processing.
Such a Payment Application Programmers Interface (API) must suit for a broad range of payment methods: (1) software based like Credit Card SET or CyberCoin, (2) chip card based like Mondex or GeldKarte, and (3) mimicries of typical and traditional payment methods like money transfer, direct debit, deposit, withdrawal, money exchange and value points. It should support both payments with explicit consumer acknowledge and automatic repeated payments, which have been consumer approved in advance. For more information on SET, see [SET].
The following discussion focuses on the Consumer's point of view and uses the associated terminology. When switching to Merchants' or Delivery Handlers' IOTP aware applications, the payment related components should be implicitly renamed by Existing Legacy Systems to the IOTP Middle-ware.
The next two sub-sections describe the general payment scenario and several assumptions about the coarsely sketched software components.
Section 2 illustrates the payment transaction progress and message flow of different kinds of transaction behavior. Sections 3 to 4 provide the details of the API functions and Section 5 elaborates the call back interface.
The following table sketches the four logical steps of many payment schemes. The preceding agreements about the goods, payment method, purchase amount, or delivery rules are omitted.
Payment State Party Example Behavior
------------- ----- ----------------
Mutual Payment Handler Generation of identification
Authentication request, solvency request, or
and some nonce
Initialization Consumer Responses to the requests and
generation of own nonce
Authorization Payment Handler Generation of the authorization
request (for consumer)
Consumer Agreement to payment (by
reservation of the Consumer's
e-money)
Payment Handler Acceptance or rejection of the
agreement (consumer's
authorization response),
generation of the authorization
request (for issuer/acquirer),
and processing of its response
Capture Generation of the capture
request (for issuer/acquirer)
Consumer Is charged
Payment Handler Acceptance or rejection of the
e-money, close of the payment
transaction
Reversal On rejection (online/delayed):
generation of the reversal data
Consumer Receipt of the refund
However, some payment schemes:
This model applies not only to payments at the typical points of sales but extends to refunds, deposits, withdrawals, electronic cheques, direct debits, and money transfers.
In outline, the IOTP Payment Bridge processes some input sequence of
payment protocol messages being forwarded by the IOTP Application
Core. It (1) disassembles the messages, (2) maps them onto the
formats of the Existing Payment Software, (3) assembles its
responses, and (4) returns another sequence of payment protocol
messages that is mostly intended for transparent transmission by the
IOTP Application Core to some IOTP aware remote party. Normally,
this process continues between the two parties until the Payment
Handler's Payment API signals the payment termination.
Exceptionally, each system component may signal failures.
The relationship between the aforementioned components is illustrated in the following figure. These components might be related to each other in a flexible n-to-m-manner:
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
IOTP client (consumer) <---------------> IOTP server (merchant)
( contains Internet ( contains
IOTP Application Core) IOTP Application Core)
^ ^
| IOTP Payment | IOTP Payment
| API | API
v v
IOTP Payment Bridge IOTP Payment Bridge
^ ^
| Existing Payment APIs, e.g., |
| SET, Mondex, etc. |
v v
Existing Payment Software Existing Payment Software
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Figure 1: Relationship of the Components
The Payment API considers the following transaction types of Baseline IOTP:
For more information on Baseline IOTP, see [IOTP] and [IOTPBOOK].
First, the authors' vision of the IOTP aware application's and its main components' capabilities are clarified: On the one hand, the Payment API should be quite powerful and flexible for sufficient connection of the generic and specific components. On the other hand, the Payment API should not be overloaded with nice-to-haves being unsupported by Existing Payment Software.
Despite the strong similarities on the processing of successful payments, failure resolution and inquiry capabilities differ extremely among different payment schemes. These aspects may even vary between different payment instrument using the same payment schemes. Additionally, the specific requirements of Consumers, Merchants and Payment Handlers add variance and complexity. Therefore, it is envisioned that the IOTP Application Core provides only very basic inquiry mechanisms while complex and payment scheme specific inquiries, failure analysis, and failure resolution are fully deferred to the actual Existing Payment Software - including the user interface.
The IOTP Application Core processes payments transparently, i.e., it forwards the wrapped payment scheme specific messages to the associated IOTP Payment Bridge/Existing Payment Software. The Existing Payment Software might even use these messages for inbound failure resolution. It reports only the final payment status to the IOTP Application Core or some intermediate - might be also final - status on abnormal interruption.
The IOTP Application Core implements the generic and payment scheme independent part of the IOTP transaction processing and provides the suitable user interface. Focusing on payment related tasks, it
lowered to the party's Payment Identifier, IOTP Payment Bridge, Wallet Identifier, and the remote parties when the actual payment transaction has been successfully started.
In addition, the IOTP Application Core
However, the IOTP Payment Bridge and Existing Payment Software do not have to rely on all of these IOTP Application Core's capabilities. E.g., some Consumer's Existing Payment Software may refuse the disclosure of specific payment instruments at brand selection time and may delay this selection to the "Check Payment Possibility" invocation using its own user interface.
The IOTP Payment Bridge's capabilities do not only deal with actual payments between the Consumer and the Payment Handler but extend to the following:
However, some Existing Payment Software may defer the selection of the payment instrument to the actual payment carrying-out or it may even lack any management of payment instruments. E.g., chip card based payment methods may offer - Point of Sale like - implicit selection of the payment instrument by simple insertion of the chip card into the chip card reader or it interrogates the inserted card and requests an acknowledge (or selection) of the detected payment instrument(s).
Existing Payment Software may not provide full support of these capabilities. E.g., some payment schemes may not support or may even prevent the explicit transaction cancellation at arbitrary phases of the payment process. In this case, the IOTP Payment Bridge has to implement at least skeletons that signal such lack of support by the use of specific error codes (see below).
The Existing Payment Software's capabilities vary extremely. It
Even the generic dialog boxes of the IOTP Application Core might be unsuitable: Particular (business or scheme) rules may require some dedicated appearance / structure / content or the dialog boxes, may prohibit the unsecured export of payment instruments, or may prescribe the pass phrase input under its own control.
The following lists all functions of the IOTP Payment API:
"Find Accepted Payment Brand" identifies the accepted payment brands for any indicated currency amount.
"Find Accepted Payment Protocol" identifies the accepted payment protocols for any indicated currency amount (and brand) and returns payment scheme specific packaged content for brand selection purposes.
This function might be used in conjunction with the aforementioned function or called without any brand identifier.
"Get Payment Initialization Data" returns additional payment scheme specific packaged content for payment processing by the payment handler.
"Inquire Authentication Challenge" returns the payment scheme specific authentication challenge value.
"Check Authentication Response" verifies the returned payment scheme specific authentication response value.
"Change Process State" is used (here only) for abnormal termination. (cf. Payment Processing Related API Functions).
"Find Payment Instrument" identifies which instances of a payment instrument of a particular payment brand are available for use in a payment.
"Check Payment Possibility" checks whether a specific payment instrument is able to perform a payment.
"Authenticate" forwards any payment scheme specific authentication data to the IOTP Payment Bridge for processing.
"Change Process State" is used (here only) for abnormal termination. (cf. Payment Processing Related API Functions).
"Start or Resume Payment Consumer/Payment Handler" initiate or resume a payment transaction. There exist specific API functions for the two trading roles Consumer and Payment Handler.
"Continue Process" forwards payment scheme specific data to the Existing Payment Software and returns more payment scheme specific data for transmission to the counter party.
"Change Process State" changes the current status of payment transactions. Typically, this call is used for termination or suspension without success.
"Remove Payment Log" notifies the IOTP Payment Bridge that a particular entry has been removed from the Payment Log of the IOTP Application Core.
"Payment Instrument Inquiry" retrieves the properties of Payment Instruments.
"Inquire Pending Payment" reports any abnormal interrupted payment transaction known by the IOTP Payment Bridge.
Payment Processing Related Inquiry API Functions
"Check Payment Receipt" checks the consistency and validity of IOTP Payment Receipts, received from the Payment Handler or returned by "Inquire Process State" API calls. Typically, this function is called by the Consumer during the final processing of payment transactions. Nevertheless, this check might be advantageous both for Consumers and Payment Handlers on failure resolution.
"Expand Payment Receipt" expands the Packaged Content of IOTP Payment Receipts as well as payment scheme specific payment receipts into a form which can be used for display or printing purposes.
"Inquire Process State" responds with the payment state and the IOTP Payment Receipt Component. Normally, this function is called by the Payment Handler for final processing of the payment transaction.
"Start Payment Inquiry" prepares the remote inquiry of the payment transaction status and responds with payment scheme specific data that might be needed by the Payment Handler for the Consumer initiated inquiry processing.
"Inquire Payment Status" is called by the Payment Handler on Consumer initiated inquiry requests. This function returns the payment scheme specific content of the Inquiry Response Block.
"Continue Process" and "Change Process State" (cf. Payment Processing Related API Calls)
"Manage Payment Software" enables the immediate activation of the Existing Payment Software. Further user input is under control of the Existing Payment Software.
"Call Back" provides a general interface for the visualization of transaction progress by the IOTP Application Core.
The following table shows which API functions must (+), should (#), or might (?) be implemented by which Trading Roles.
API function Consumer Payment Handler Merchant ------------ -------- --------------- -------- Find Accepted Payment Brand + Find Accepted Payment Protocol # Find Payment Instrument + Get Payment Initialization Data + Check Payment Possibility + Start Payment Consumer + Start Payment Payment Handler + Resume Payment Consumer # Resume Payment Payment Handler # Continue Process + + Inquire Process State + + ? Change Process State + + ? Check Payment Receipt + ? Expand Payment Receipt # ? Remove Payment Log ? ? ? Inquire Authentication Challenge ?
Authenticate + Check Authentication Response ? Payment Instrument Inquiry ? Inquire Pending Payment # # Start Payment Inquiry ? Inquire Payment Status ? Manage Payment Software # ? ? Call Back #
Table 1: Requirements on API Functions by the Trading Roles
The next sections sketch the relationships and the dependencies between the API functions. They provide the informal description of the progress alternatives and depict the communication and synchronization between the general IOTP Application Core and the payment scheme specific modules.
This section describes how the functions in this document are used together to process authentication.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Authenticator Inquire Authentication Challenge(Alg1*) -> IPB
Inq. Auth. Challenge Response(Alg1,Ch1) <- IPB
. . .
Inquire Authentication Challenge(Algn*) -> IPB
Inq. Auth. Challenge Response(Algn,Chn) <- IPB
Create and transmit Authentication Request Block
Authenticatee Authenticate(Alg1, Ch1) -> IPB
AuthenticateResponse(...) <- IPB
. . .
Authenticate(Algm, Chm) -> IPB
AuthenticateResponse(Res) <- IPB
Create and transmit Authentication Response Block
Authenticator Check Authentication Response(Algm,Chm,Res)->IPB
Check Auth. Response() <-IPB
Create and transmit Authentication Status Block
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Figure 2. Authentication Message Flows
Note that the interface of the API function is limited to the response of exactly one algorithm per call. If the IOTP Application Core provides a choice of algorithms for input, this choice should be reduced successively by the returned algorithm ({Alg(i+1)*} is subset of {Algi*}).
During the registration of new Payment Instruments, the IOTP Payment Bridge notifies the IOTP Application Core about the supported authentication algorithms.
For each provided Authentication Request Component, the IOTP Application Core analyzes the algorithms' names, the transaction context, and optionally user preferences in order to determine the system components which are capable to process the authentication request items. Such system components might be the IOTP Application Core itself or any of the registered IOTP Payment Bridges.
Subsequently, the IOTP Application Core requests the responses to the supplied challenges from the determined system components in any order. The authentication trials stop with the first successful response, which is included in the IOTP Authentication Response Block.
Alternatively, the IOTP Application might ask for a user
selection. This might be appropriate, if two or more
authentication algorithms are received that require explicit user
interaction, like PIN or chip card insertion.
The Authenticatee's organizational data is requested by an IOTP Authentication Request Block without any content element. On failure, the authentication (sequence) might be retried, or the whole transaction might be suspended or cancelled.
On sole organizational data request, its presence is checked.
Any verification must succeed in order to proceed with the transaction.
The following shows how the API functions are used together so that the Merchant can (1) compile the Brand List Component, (2) generate the Payment Component, and (3) adjust the Order Component with payment scheme specific packaged content.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Merchant For each registered IOTP Payment Bridge
| Find Accepted Payment Brand() -> IPB
| Find Accepted Payment Brand Response (B*) <- IPB
| Find Accepted Payment Protocol(B1) -> IPB
| Find Accepted Payment Protocol Res.(P1*) <- IPB
| . . .
| Find Accepted Payment Protocol(Bn) -> IPB
| Find Accepted Payment Protocol Res.(Pn*) <- IPB
Create one Brand List Component, ideally sharing
common Brand, Protocol Amount, Currency Amount,
and Pay Protocol Elements
Create Trading Protocol Options Block
On brand independent transactions
| Create Brand Selection Component, implicitly
| Get Payment Initialization Data(B1,P1) -> IPB
| Get Payment Initialization Data Res.() <- IPB
| Optionally
| | Inquire Process State() -> IPB
| | Inquire Process State Response(State) <- IPB
| Create Offer Response Block
Transmit newly created Block(s)
Consumer Consumer selects Brand (Bi)/Currency/Protocol (Pj)
from those that will work and generates Brand
Selection Component - at least logically
On brand dependent transaction
| Transmit Brand Selection Component
Merchant On brand dependent transaction
| Get Payment Initialization Data(Bi,Pj) -> IPB
| Get Payment Initialization Data Res.() <- IPB
| Optionally
| | Inquire Process State() -> IPB
| | Inquire Process State Response(State) <- IPB
| Create Offer Response Block
| Transmit newly created Block
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Figure 3. Brand Compilation Message Flows
The IOTP Application Core must provide any wallet identifiers, if they are required by the IOTP Payment Bridges which signal their need by specific error codes (see below). Any signaled error that could not be immediately solved by the IOTP Application Core should be logged - this applies also to the subsequent API calls of this section. In this case, the IOTP Application Core creates an IOTP Error Block (hard error), transmits it to the Consumer, and terminates the current transaction.
Furthermore, the organisational data about the Payment Handler is returned. The IOTP Application Core might optionally match the returned payment brands with Merchant's general preferences.
Alternatively, the IOTP Application Core might skip the calls of "Find Accepted Payment Brands" (cf. Step 3) and issue the "Find Accepted Payment Protocol" call without any Brand given on the input parameter list. In this case, the IOTP Payment Bridge responds to the latter call with the whole set of payment schemes supported w.r.t. the other input parameters.
the Brand List Component. However, the compilation must consider several aspects in order to prevent conflicts - sharing detection might be textual matching (after normalization):
The rules and mechanisms of how this could be accomplished are
out of the scope of this document. Furthermore, this document
does not define any further restriction to the IOTP
specification.
If both conditions are fulfilled, the IOTP Application Core might request the remaining payment scheme specific payment initialization data from the IOTP Payment Bridge ("Get Payment Initialization Data") and compile the IOTP Offer Response Block.
Optionally, the IOTP Application Core might request the current process state from the IOTP Payment Bridge and add the inferred order status to the IOTP Offer Response Block. Alternatively, IOTP Application might determine the order status on its own.
As in step 6, the rules and mechanisms of how this could be accomplished are out of the scope of this document.
Any error during this process raises an IOTP Error Block.
This section describes the steps that happen mainly after the Merchant's Brand Compilation (in a brand independent transaction). However, these steps might partially interlace the previous process (in a brand dependent transaction).
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Merchant Merchant generates Brand List(s) containing
Brands, Payment Protocols and Currency Amounts
On brand independent transactions
| Merchant generates Offer Response Block
Consumer Compile set(s) of Brands B/Protocols P
for each set
| Find Payment Instrument(B, P, C) -> IPB
| Find Payment Instrument Response (PI*) <- IPB
Consumer selects Brand/Currency/Payment Instrument
from those that will work and generates Brand
Selection Component
For the Selection
| Get Payment Initialization Data(B,C,PI,P) -> IPB
| Get Payment Initialization Data Response()<- IPB
On brand dependent transaction
| Generate and transmit TPO Selection Block
Merchant On brand dependent transaction
| Merchant checks Brand Selection and generates
| and transmits Offer Response Block
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Figure 4. Brand Selection Message Flows
The payment protocol support may differ between payment instruments if the IOTP Payment Bridge supports payment instrument distinction.
These API calls are used to infer the payment alternatives at the startup of any payment transaction (without user unfriendly explicit user interaction).
The IOTP Application Core must provide wallet identifiers, if they are requested by the IOTP Payment Bridges which signal their need by specific error codes (see below).
It is recommended that the IOTP Application Core manages wallet identifiers. But for security reasons, it should store pass phrases in plain text only in runtime memory. Developers of IOTP
Payment Bridges and payment software modules should provide a thin and fast implementation - without lengthy initialization processes
- for this initial inquiry step.
The handling and resolution of unavailable IOTP Payment Bridges during the inquiry in Step 3 is up to the IOTP Application Core. It may skip these IOTP Payment Bridges or may allow user supported resolution.
Furthermore, it may offer the registration of new payment instruments when the Consumer is asked for payment instrument selection.
In any erroneous case, the user should be notified and offered accurate alternatives. Most probably, the user might be offered
If the payment software implements payment instrument selection on its own, it may request the Consumer's choice at this step.
If the check succeeds, it returns several IOTP Brand Selection Info Elements.
An example of how the functions in this document are used together to effect a successful payment is illustrated in the Figure 5. In the figure 5, PS0, PS1, ..., and PSn indicate the nth PayScheme Packaged Content data, and [ ] indicates optional.
(Technically, two payments happen during IOTP Value Exchange transactions.)
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer Start Payment Consumer(Amount,[PS0]...) -> IPB
Start Payment Cons. Res.([PS1], CS=Cont.) <- IPB
Create and transmit Payment Request Block
Payment Handler Start Payment Pay. Handler(Amount, [PS1]) -> IPB
Start Payment PH Response(PS2, CS=Cont.) <- IPB
Create and transmit Payment Exchange Block
Consumer Continue Process(PS2) -> IPB
Continue Process Response(PS3, CS=Cont.) <- IPB
... CONTINUE SWAPPING PAYMENT EXCHANGES UNTIL ...
Payment Handler Continue Process Response([PSn], CS=End) <- IPB
Request any local payment receipt
| Inquire Process State() -> IPB
| Inquire Proc. State Resp.(State, [Rcp.])<- IPB
Create and transmit Payment Response Block
Terminate transaction, actively
| Change Process State(State) -> IPB
| Change PS Response(State=CompletedOK) <- IPB
Consumer On receipt of final payment scheme data
| Continue Process(PSn) -> IPB
| Continue Process Response(CS=End) <- IPB
Check Payment Receipt(Receipt) -> IPB
Check Payment Receipt Response() <- IPB
Request any local payment receipt
| Inquire Process State() -> IPB
| Inquire Proc. State Resp.(State, [Rcp.])<- IPB
Terminate transaction, actively
| Change Process State(State) -> IPB
| Change PS Response(State=CompletedOk) <- IPB
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Figure 5. Example Payment Message Flows
This might be a milestone requiring the renewed Consumer's agreement about the payment transaction's continuation. Particularly, this is a good moment for payment suspension (and even cancellation), which will be most probably supported by all payment schemes. Simply, because the actual payment legacy systems have not yet been involved in the current transaction.
Such an agreement might be explicit per transaction or automatic based on configured preferences, e.g., early acknowledgments for specific payment limits.
It is assumed, that the transaction proceeds with minimal user (Consumer and Payment Handler) interaction and that its progress is controlled by the IOTP Application Core and IOTP Payment Bridge.
Generally, the called API function re-does most checks of the "Check Payment Possibility" call due to lack of strong dependencies between both requests: There might be a significant delay between both API requests.
The called API function may return further payment scheme specific data being considered as payment specific initialization data for the Payment Handler's IOTP Payment Bridge.
If the fixed Existing Payment Software implements payment instrument selection on its own, it may request the Consumer's choice at this step.
The IOTP Payment Bridge reports lack of capability quite similarly to the "Check Payment Possibility" request to the IOTP Application Core. The Consumer may decide to resolve the problem, to suspend, or to cancel the transaction, but this function call must succeed in order to proceed with the transaction.
Developers of payment modules may decide to omit payment instrument related checks like expiration date or refunds sufficiency, if such checks are part of the specific payment protocol.
If the IOTP Payment Bridge requests wallet identifiers or pass phrases anywhere during the payment process, they should be requested by this API function, too. It is recommended that the IOTP Application Core stores plain text pass phrases only in runtime memory.
Finally, the IOTP Application Core generates the IOTP Payment Request Block, inserts any returned payment scheme data, and submits it to the Payment Handler's system.
On success, the Payment Handler's IOTP Payment Bridge responds with payment scheme specific data. On failures, this non- interactive server application has to resolve any problems on its own or to give up aborting the payment transaction. However, the Consumer may restart the whole payment transaction. Anyway, the payment log file should reflect any trials of payments.
Eventually, the Payment Handler informs the Consumer about the current IOTP Process State using the IOTP Payment Response or IOTP Error Block.
Note that the "Start Payment Payment Handler" call might return the Continuation Status "End" such that payment processing proceeds with Step 7.
This Payment Scheme Component is encapsulated in an IOTP Payment Exchange Block and transmitted to the Payment Handler.
However, the processing of the payment scheme specific data may fail for several reasons. These are signaled by specific error codes which are transformed to IOTP Payment Response Blocks (generated by Payment Handler) or IOTP Error Blocks (both parties may generate them) and transmitted to the counter party.
However, any of these API calls may fail or any response might be incomplete (e.g., lack of payment receipt). Then, the Consumer has to be notified about the failed processing by an IOTP Error Block.
Finally, the Payment Handler terminates the payment transaction with the "Change Process State" API call without awaiting any further response from the Consumer. Further failures are not reported to the Consumer.
Note that it might be possible that the Consumer's IOTP Payment Bridge has returned the previous payment scheme specific data with the continuation status "End". Even in the absence of this knowledge - this status is not exchanged between the Consumer and the Payment Handler - the Payment Handler must not supply any further payment scheme specific data. Such data will be rejected by the Consumer's IOTP Payment Bridge.
Afterwards, the IOTP Application Core issues the "Inquire Process State" API call and verifies whether extensions to the payment receipt have been returned.
Finally, the transaction is terminated by calling the "Change Process State" API function which verifies and synchronizes the reported payment status with the local one and signals any inconsistencies. Any Inconsistency and returned status text should be displayed to the Consumer.
At this point, the payment transaction has already been closed by the Payment Handler. Therefore, any failure has to be resolved locally or out-of-band.
In Baseline IOTP, Payment inquiries are initiated by the Consumer in order to verify the current payment progress and process state at the remote Payment Handler. In the figure 6, PS1 and PS2 indicate the first and second PayScheme Packaged Content data, and [ ] indicates optional.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer Start Payment Inquiry() -> IPB
Start Payment Inquiry Response([PS1]) <- IPB
Create and transmit Inquiry Request Trading Block
Payment Handler Inquire Payment Status([PS1]) -> IPB
Inquire Payment Status Res.(State, [PS2]) -> IPB
Create and transmit Inquiry Response Trading
Block
Consumer If Payment Scheme Data present
| Continue Process(PS2) -> IPB
| Continue Process Response(CS=End) <- IPB
Change Process State(State) -> IPB
Change Process State Response(State) <- IPB
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Figure 6. Remote Process State Inquiry
Erroneous API responses should be reported to the Consumer and valid alternatives (typically retry and cancellation) should be presented by the IOTP Application Core.
This request might perform the complete initialization, e.g., availability check of periphery or pass phrase supplement, and the IOTP Payment Bridge reports lack of capability quite similarly to the "Check Payment Possibility" request to the IOTP Application Core.
If the IOTP Payment Bridge requests wallet identifiers or pass phrases anywhere during the payment process, they should be requested by this API function, too. It is recommended that the IOTP Application Core store plain text pass phrases only in runtime memory.
The IOTP Application Core encapsulates any Payment Scheme Component in an IOTP Inquiry Request Block and submits the block to the Payment Handler.
Any additional information that might be of interest to the Consumer has to be displayed by the IOTP Payment Bridge or Existing Payment Software on their own.
The IOTP specification distinguishes between several classes of failures:
Any IOTP Payment API has to deal with the receipt of failure notifications by and failure responses. This proposal has borrowed the basic mechanisms for error reporting between the IOTP Application Core and the IOTP Payment Bridge from the actual protocol: Business
errors are reported by Status Components within IOTP Response Blocks while technical errors are signaled by Error Components within IOTP Error Blocks.
Cancellations are mimicked as specific business errors which might be initiated by each trading party.
Preferring slim interfaces, this IOTP Payment API introduces one additional Error Code value for business error indication - errors can be raised on every API call. On receipt of this value, the IOTP Application Core has to infer further details by the issuance of the API function call "Inquire Process State".
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Any Party Issue some API request -> IPB
Error Response(Error Code) <- IPB
On "Business Error" response
| Inquire Process State() -> IPB
| Inquire P.S. Resp.(State, Receipt) <- IPB
Analyze local process state and try to resolve
with optional user interaction
If Process State Change needed
| Change Process State (State) -> IPB
| Change Process State Response(State) <- IPB
If counter party's notification required
| Create Error or Cancel Block (, add to next
| message, ) and transmit it to counter party
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Figure 7. Error Response from IPB
The specific Completion Codes "ConsCancelled", "MerchCancelled", and "PaymCancelled" - returned by "Inquire Process State" - determine that the IOTP Cancel Block has to be created instead of an IOTP Error Block.
The rules for determining the required behavior of the IOTP Application Core are given in the IOTP specification.
Note that any payment (intermediate) termination, i.e., failures, cancellations, and even successes are always reported to the IOTP Payment Bridge by the API function "Change Process State". This API function does both status changes and consistency checking / synchronization. Any suspicion of inconsistency should be reported by the IOTP Payment Bridge for display by the IOTP Application Core.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Any Party Error Block or Cancel Block Received
If Change Process State required
| Change Process State (State) -> IPB
| Change Process State Response(State) <- IPB
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Figure 8. Error Notification from counter party
Not every failure might be visible at the IOTP layer, e.g., the processing of payment transactions might temporarily be hampered by intermediate failures at the payment scheme or protocol transport layer which might be resolved by the actual components.
However, final failures or cancellations have to be reported at the IOTP layer. E.g., communication time-outs and heavily faulty communication channels may disable the transaction.
Any system component may implement time-out recognition and use the aforementioned API mechanisms for the notification of process state changes. But, time-outs may happens while communicating with both the counter party and local system components, like chip card readers or IOTP Payment Bridges. Anyway, the Consumer's IOTP Application Core should notify the Consumer about the resolution alternatives, i.e., retry, suspension, and cancellation.
Payment transaction resumption may apply at different steps of a payment transaction:
Any "Resume Payment ..." API function responds with an Error Code on non-suspended payment transaction that signals a business error. Afterwards the IOTP Application Core has to issue the "Inquire Process State" API call for further analysis of the process state.
Any "Resume Payment" API function responds with an Error Code on non-suspended payment transaction that signals a business error. Similar, the "Continue Process" API function should report business errors on non-pending payment transactions.
Any "Resume Payment", "Continue Process" or "Inquire Process
State" API function should return with an Error Code
"AttValIllegal" on non-existent payment transaction whereby the
further Error Attribute "Names" denote the payment identifier.
If the Consumer does not reconnect within an acceptable amount of time, the Payment Handler's system may perform local failure resolution in order to close the transaction and to retain resources for other transactions ("Change Process State"). If the Consumer reconnect afterwards, an IOTP Payment Response or IOTP Error Block could be generated.
At startup or on explicit user request the IOTP Application Core should check its IOTP Payment Bridges' internal status by searching for pending payment transactions.
The IOTP Payment Bridge may deny the processing of any new payment transactions until the pending transactions have been processed. Such denials are signaled by the error code "Business Error".
The IOTP Application Core provides only a simple and generic interface for the registration of new payment methods / instruments ("Manage Payment Software"). It receives the initial user request and defers the actual registration to the corresponding IOTP Payment Bridge.
The IOTP Application Core may also activate the Existing Payment Software for further payment instrument and wallet administration.
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
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:
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
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:
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
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:
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."
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.,
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:
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
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:
PayId (14) This attribute is introduced for API
simplification:
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 re