Movatterモバイル変換
[0]ホーム
[RFC Home] [TEXT|PDF|HTML] [Tracker] [IPR] [Info page]
INFORMATIONAL
Network Working Group Y. KawatsuraRequest for Comments: 3867 HitachiCategory: Informational M. Hiroya Technoinfo Service H. Beykirch Atos Origin November 2004Payment Application Programmers Interface (API) for v1.0Internet Open Trading Protocol (IOTP)Status of this Memo 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 Notice Copyright (C) The Internet Society (2004).Abstract 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.Hans, et al. Informational [Page 1]
RFC 3867 Payment API for IOTP November 2004Table of Contents1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . .31.1. General payment phases . . . . . . . . . . . . . . . . .51.2. Assumptions. . . . . . . . . . . . . . . . . . . . . . .62. Message Flow . . . . . . . . . . . . . . . . . . . . . . . . .122.1. Authentication Documentation Exchange. . . . . . . . . .152.2. Brand Compilation. . . . . . . . . . . . . . . . . . . .172.3. Brand Selection. . . . . . . . . . . . . . . . . . . . .212.4. Successful Payment . . . . . . . . . . . . . . . . . . .242.5. Payment Inquiry. . . . . . . . . . . . . . . . . . . . .292.6. Abnormal Transaction Processing. . . . . . . . . . . . .302.6.1. Failures and Cancellations . . . . . . . . . . .302.6.2. Resumption . . . . . . . . . . . . . . . . . . .322.7. IOTP Wallet Initialization . . . . . . . . . . . . . . .332.8. Payment Software Management. . . . . . . . . . . . . . .343. Mutuality. . . . . . . . . . . . . . . . . . . . . . . . . . .343.1. Error Codes. . . . . . . . . . . . . . . . . . . . . . .383.2. Attributes and Elements. . . . . . . . . . . . . . . . .483.3. Process States . . . . . . . . . . . . . . . . . . . . .613.3.1. Merchant . . . . . . . . . . . . . . . . . . . .613.3.2. Consumer . . . . . . . . . . . . . . . . . . . .633.3.3. Payment Handler. . . . . . . . . . . . . . . . .654. Payment API Calls. . . . . . . . . . . . . . . . . . . . . . .664.1. Brand Compilation Related API Calls. . . . . . . . . . .664.1.1. Find Accepted Payment Brand. . . . . . . . . . .664.1.2. Find Accepted Payment Protocol . . . . . . . . .684.1.3. Get Payment Initialization Data. . . . . . . . .704.1.4. Inquire Authentication Challenge . . . . . . . .724.1.5. Authenticate . . . . . . . . . . . . . . . . . .734.1.6. Check Authentication Response. . . . . . . . . .744.2. Brand Selection Related API Calls. . . . . . . . . . . .764.2.1. Find Payment Instrument. . . . . . . . . . . . .764.2.2. Check Payment Possibility. . . . . . . . . . . .784.3. Payment Transaction Related API calls. . . . . . . . . .804.3.1. Start Payment Consumer . . . . . . . . . . . . .804.3.2. Start Payment Payment Handler. . . . . . . . . .824.3.3. Resume Payment Consumer. . . . . . . . . . . . .844.3.4. Resume Payment Payment Handler . . . . . . . . .854.3.5. Continue Process . . . . . . . . . . . . . . . .864.3.6. Change Process State . . . . . . . . . . . . . .884.4. General Inquiry API Calls. . . . . . . . . . . . . . . .894.4.1. Remove Payment Log . . . . . . . . . . . . . . .904.4.2. Payment Instrument Inquiry . . . . . . . . . . .904.4.3. Inquire Pending Payment. . . . . . . . . . . . .924.5. Payment Related Inquiry API Calls. . . . . . . . . . . .934.5.1. Check Payment Receipt. . . . . . . . . . . . . .934.5.2. Expand Payment Receipt . . . . . . . . . . . . .94Hans, et al. Informational [Page 2]
RFC 3867 Payment API for IOTP November 20044.5.3. Inquire Process State. . . . . . . . . . . . . .964.5.4. Start Payment Inquiry. . . . . . . . . . . . . .974.5.5. Inquire Payment Status . . . . . . . . . . . . .984.6. Other API Calls. . . . . . . . . . . . . . . . . . . . .994.6.1. Manage Payment Software. . . . . . . . . . . . .995. Call Back Function . . . . . . . . . . . . . . . . . . . . . .1016. Security Considerations. . . . . . . . . . . . . . . . . . . .1037. References . . . . . . . . . . . . . . . . . . . . . . . . . .1037.1. Normative References . . . . . . . . . . . . . . . . . .1037.2. Informative References . . . . . . . . . . . . . . . . .104 Acknowledgement. . . . . . . . . . . . . . . . . . . . . . . . . .105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . .105 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . .1061. Introduction 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.Hans, et al. Informational [Page 3]
RFC 3867 Payment API for IOTP November 2004 Initially, this consideration leads to the two-level layered view of the IOTP software for each role, consisting of: o some generic IOTP system component, the so-called IOTP application core - providing IOTP based gateway services and generic business logic and o the trading roles' specific back-end systems implementing the specific trading transaction types' functionality. In order to isolate the changes on the infrastructure, the IOTP trading application has been three-layered: o the IOTP Application Core processes the generic parts of the IOTP transaction and holds the connection to the Internet, o the Existing Legacy System or Existing Payment Software which processes the actual transaction type, and particular payment transaction, and o the IOTP Middle-ware or IOTP Payment Bridge which glues the other two possibly incompatible components. It brokers between the specific interface of the Existing Legacy System and the standardized interfaces of the IOTP Application Core. 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.Hans, et al. Informational [Page 4]
RFC 3867 Payment API for IOTP November 2004 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. Sections3 to4 provide the details of the API functions andSection 5 elaborates the call back interface.1.1. General payment phases 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 refundHans, et al. Informational [Page 5]
RFC 3867 Payment API for IOTP November 2004 However, some payment schemes: o limit themselves to one-sided authentication, o perform off-line authorization without any referral to any issuer/acquirer, o apply capture processing in batch mode, or o do not distinguish between authorization and capture, o lack an inbound mechanism for reversals or implement a limited variant. 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.1.2. Assumptions 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: o One IOTP Application Core may manage multiple IOTP Payment Bridges and the latter might be shared between multiple IOTP Application Cores. o Each Payment Bridge may manage multiple Existing Payment Software modules and the latter might be shared between multiple Payment Bridges. o Each Existing Payment Software may manage multiple payment schemes (e.g., SET) and the latter might be supported by multiple Existing Payment Software modules. For more information on SET see [SET]. o Each payment scheme may support multiple payment instruments (e.g., particular card) or methods (e.g., Visa via SET) and the latter might be shared by multiple Existing Payment Software Components.Hans, et al. Informational [Page 6]
RFC 3867 Payment API for IOTP November 2004 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 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: o Baseline Purchase, o Baseline Refund, o Baseline Value Exchange, o Baseline Withdrawal, and o Baseline (Payment) Inquiry. 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.Hans, et al. Informational [Page 7]
RFC 3867 Payment API for IOTP November 2004 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 o manages the registered IOTP Payment Bridges and provides a mechanism for their registration - the latter is omitted by this document. o assumes that any IOTP Payment Bridge is a passive component, i.e., it strictly awaits input data and generates one response to each request, o supports the payment negotiation (Consumer: selection of the actual payment instrument or method; Merchant: selection of the payment methods being offered to the Consumer) preceding the payment request, o requests additional payment specific support from the Existing Payment Software via the selected and registered the IOTP Payment Bridge, o initializes and terminates the Existing Payment Software via the IOTP Payment Bridge, o inquires authentication data (for subsequent request or response) from the Existing Payment Software, specific authentication component - omitted in this document - or Consumer (by a suitable user interface), o supervises the online transaction process and traces its progress, o stores the transaction data being exchanged over the IOTP wire - payment scheme specific data is handled transparently, o relates each payment transaction with multiple payment parameters (IOTP Transaction Identifier, Trading Protocol Options, Payment Instrument/Method, Offer Response, IOTP Payment Bridge, and Wallet Identifier, associated remote Parties). The relation might beHans, et al. Informational [Page 8]
RFC 3867 Payment API for IOTP November 2004 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. o implements a payment transaction progress indicator, o enables the inquiry of pending and completed payment transactions, o implements generic dialogs, e.g., brand selection, payment acknowledge, payment suspension / cancellation, receipt visualization, basic transaction inquiry, balance inquiry, or receipt validation, o defers payment specific processing, supervision, validation, and error resolution to the Existing Payment Software. It is expected, that the Existing Payment Software will try to resolve many errors first by the extended exchange of Payment Exchange messages. The most significant and visible failures arise from sudden unavailability or lapses of the local or opposing payment component. o supports the invocation of any Existing Payment Software in an interactive mode, which might be used (1) for the payment scheme specific post-processing of a (set of) payment transactions, (2) for the analysis of a payment instrument, (3) for the registration of a new payment instrument/scheme, or (4) re-configuration of a payment instrument/scheme. o exports call back functions for use by the IOTP Payment Bridge or Existing Payment Software for progress indication. In addition, the IOTP Application Core o manages the IOTP message components and IOTP message blocks exchanged during the transaction which may be referenced and accessed during the processing of subsequent messages, e.g., for signature verification. In particular, it stores named Packaged Content elements exchanged during payments. o manages several kinds of identifiers, i.e., transaction, message, component, and block identifiers, o implements a message caching mechanism, o detects time-outs at the protocol and API level reflecting the communication with both the IOTP aware remote party and the Payment API aware local periphery, e.g., chip card (reader) may raise time-outs.Hans, et al. Informational [Page 9]
RFC 3867 Payment API for IOTP November 2004 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: o translation and (dis)assemblage of messages between the formats of the IOTP Payment API and those of the Existing Payment Software. Payment API requests and response are strictly 1-to-1 related. o Consumer's payment instrument selection by the means of an unsecured/public export of the relationship of payment brands, payment protocols, and payment instruments (identifiers). Generally, this includes not just the brand (Mondex, GeldKarte, etc.) but also which specific instance of the instrument and currency to use (e.g., which specific Mondex card and which currency of all those available). 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). o payment progress checks, e.g., is there enough funds available to carry out the purchase, or enough funds left for the refund, o IOTP Payment Receipt checks which might be performed over its Packaged Content or by other means. o recoding of payment scheme specific receipts into a format which can be displayed to the user or printed, o cancellation of payment, even though it is not complete, o suspension and resumption of payment transactions. Two kinds of failures the Existing Payment Software might deal with are (1) the time-out of the network connection and (2) lack of funds. For resolution, the IOTP Application Core may try the suspension with a view to later possible resumption.Hans, et al. Informational [Page 10]
RFC 3867 Payment API for IOTP November 2004 o recording the payment progress and status on a database. E.g., information about pending payments might be used to assist their continuation when the next payment protocol message is received. o payment transaction status inquiry, so that the inquirer - IOTP Application Core or User - can determine the appropriate next step. o balance inquiry or transaction history, e.g., consumers may interrogate their chip card based payment instrument or remotely administer some account in advance of a payment transaction acknowledge, o inquiry on abnormal interrupted payment transactions, which might be used by the IOTP Application Core to resolve these pending transactions at startup (after power failure). o payment progress indication. This could be used to inform the end user of details on what is happening with the payment. o payment method specific authentication methods. 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 o supports payment scheme specific processing, supervision, validation, and error resolution. It is expected, that many errors are tried to be resolved first by the extended exchange of Payment Exchange messages. o provides hints for out-of-band failure resolution on failed inbound resolution - inbound resolution is invisible to the IOTP Application Core. o may implement arbitrary transaction data management and inquiry mechanisms ranging from no transaction recording, last transaction recording, chip card deferred transaction recording, simple transaction history to sophisticated persistent data management with flexible user inquiry capabilities. The latter is required by Payment Handlers for easy and cost effective failure resolution.Hans, et al. Informational [Page 11]
RFC 3867 Payment API for IOTP November 2004 o implements the payment scheme specific dialog boxes. 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.2. Message Flow The following lists all functions of the IOTP Payment API: o Brand Compilation Related API Functions "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). o Brand Selection 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.Hans, et al. Informational [Page 12]
RFC 3867 Payment API for IOTP November 2004 "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). o 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. o General Inquiry API Functions "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.Hans, et al. Informational [Page 13]
RFC 3867 Payment API for IOTP November 2004 "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) o Other API Functions "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 ?Hans, et al. Informational [Page 14]
RFC 3867 Payment API for IOTP November 2004 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.2.1. Authentication Documentation Exchange 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 FlowsHans, et al. Informational [Page 15]
RFC 3867 Payment API for IOTP November 2004 1. (Authenticator Process) None, one or multiple IOTP Payment Bridges (IPB) are requested for one or multiple authentication challenge values ("Inquire Authentication Challenge"). Each value is encapsulated in an IOTP Authentication Request Component. In addition, the IOTP Application Core may add payment scheme independent authentication methods. All of them form the final IOTP Authentication Request Block, which describes the set of authentication methods being supported by the authenticator and from which the Authenticatee has to choose one method. 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. 2. On the presence of an IOTP Authentication Block within the received IOTP message, the Authenticatee's IOTP Application Core checks whether the IOTP transaction type in the current phase actually supports the authentication process. 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.Hans, et al. Informational [Page 16]
RFC 3867 Payment API for IOTP November 2004 3. (Authenticator Process) The IOTP Application Core checks the presence of the IOTP Authentication Response Component in the Authentication Response Block and forwards its content to the generator of the associated authentication challenge for verification ("Check Authentication Response"). On sole organizational data request, its presence is checked. Any verification must succeed in order to proceed with the transaction.2.2. Brand Compilation 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.Hans, et al. Informational [Page 17]
RFC 3867 Payment API for IOTP November 2004 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 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 1. The Merchant's commerce server controls the shopping dialog with its own mechanisms until the Consumer checks out the shopping cart and indicates the payment intention. The notion shopping subsumes any non-IOTP based visit of the Merchant Trading Role's (which subsumes Financial Institutes) web site in order to negotiate the content of the IOTP Order Component. The subsequent processing switches to the IOTP based form by the activation of the Merchant's IOTP aware application.Hans, et al. Informational [Page 18]
RFC 3867 Payment API for IOTP November 2004 2. The IOTP Application Core inquires for the IOTP level trading parameters (Consumer's shopping identifier, payment direction, initial currency amounts, discount rates, Merchant's and Delivery Handler's Net Locations, Non-Payment Handler's Organizational Data, initial order information, ....). 3. The registered IOTP Payment Bridges are inquired by the IOTP Application Core about the accepted payment brands ("Find Accepted Payment Brand"). Their responses provide most of the attribute values for the compilation of the Brand List Component's Brand Elements. The IOTP Application Core might optionally match the returned payment brands with Merchant's general preferences. 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. 4. The IOTP Application Core interrogates the IOTP Payment Bridges for each accepted payment brand about the supported payment protocols ("Find Accepted Payment Protocol"). These responses provide the remaining attribute values of the Brand Elements as well as all attribute values for the compilation of the Brand List Component's Protocol Amount and Pay Protocol Elements. 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. 5. The steps 3 and 4 are repeated during IOTP Value Exchange transactions - these steps are omitted in the previous figure. 6. The IOTP Application Core compiles the Brand List Component(s) and the IOTP Trading Protocol Options Block. It is recommended that the "equal" items returned by IOTP Payment Bridge function calls are shared due to the extensive linking capabilities withinHans, et al. Informational [Page 19]
RFC 3867 Payment API for IOTP November 2004 the Brand List Component. However, the compilation must consider several aspects in order to prevent conflicts - sharing detection might be textual matching (after normalization): o Packaged Content Elements contained in the Brand List Component (and subsequently generated Payment and Order Components) might be payment scheme specific and might depend on each other. o Currently, IOTP lacks precise rules for the content of the Packaged Content Element. Therefore, transaction / brand / protocol / currency amount (in)dependent data might share the same Packaged Content Element or might spread across multiple Packaged Content Elements. o The Consumer's IOTP Application Core transparently passes the Packaged Content Elements to the IOTP Payment Bridges which might not be able to handle payment scheme data of other payment schemes, accurately. 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. 7. The IOTP Application Core determines whether the IOTP message can be enriched with an Offer Response Block. This is valid under the following conditions: o All payment alternatives share the attribute values and Packaged Content Elements of the subsequently generated IOTP Payment and Order Components. o The subsequently generated data does not depend on any IOTP BrandSelInfo Elements that might be reported by the consumer within the TPO Selection Block in the brand dependent variant. 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.Hans, et al. Informational [Page 20]
RFC 3867 Payment API for IOTP November 2004 8. The IOTP Application Core compiles the IOTP TPO Message including all compiled IOTP Blocks and transmits the message to the Consumer. The IOTP Application Core terminates if an IOTP Offer Response Block has been created. 9. The Consumer performs the Brand Selection Steps (cf.Section 2.3) and responds with a TPO Selection Block if no IOTP Offer Response Block has been received. Otherwise, the following step is skipped. 10. On brand dependent transactions, the IOTP Application Core requests the remaining payment scheme specific payment initialization data from the IOTP Payment Bridge ("Get Payment Initialization Data"), compiles the IOTP Offer Response Block, transmits it to the Consumer, and terminates. Like Step 7, the IOTP Application Core might access the current process state of the IOTP Payment Bridge for the compilation of the order status. Any error during this process raises an IOTP Error Block.2.3. Brand Selection 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 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*Hans, et al. Informational [Page 21]
RFC 3867 Payment API for IOTP November 2004 Figure 4. Brand Selection Message Flows 1. The Merchant's commerce server controls the shopping dialog with its own mechanisms until the Consumer checks out the shopping cart and indicates his payment intention. The subsequent processing switches to the IOTP based form by the activation of the Merchant's IOTP aware application. 2. The IOTP Application Core compiles the IOTP Trading Protocol Options Block which contains the IOTP Brand List Component(s) enumerating Merchant's accepted payment brands and payment protocols and initiates the Brand Selection process. 3. This first IOTP message activates the Consumer's IOTP aware application, e.g., the Web browser invokes a helper application (e.g., Java applet or external application). Its IOTP Application Core o infers the accepted payment brands, payment protocols, payment direction, currencies, payment amounts, any descriptions etc., and their relationships from the IOTP message, o determines the registered IOTP Payment Bridges, o compiles one or multiple sets of brand and protocol such that the join of all sets describes exactly the payment alternatives being offered by the Merchant. o inquires payment (protocol) support and the known payment instruments from each registered IOTP Payment Bridge for each compiled set ("Find Payment Instrument"). However, some IOTP Payment Bridges may refuse payment instrument distinction. 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 IOTPHans, et al. Informational [Page 22]
RFC 3867 Payment API for IOTP November 2004 Payment Bridges and payment software modules should provide a thin and fast implementation - without lengthy initialization processes - for this initial inquiry step. 4. The IOTP Application Core verifies the Consumer's payment capabilities with the Merchant's accepted payment brands and currencies, o displays the valid payment instruments and payment instrument independent payment brands (brand and protocol) together with their purchase parameters (payment direction, currency, amount), and o requests the Consumer's choice or derives it automatically from any configured preferences. Any selection ties one IOTP Payment Bridge with the following payment transaction. 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. 5. The IOTP Application Core interrogates the fixed IOTP Payment Bridge whether the payment might complete with success ("Check Payment Possibility"). At this step, the IOTP Payment Bridge may issue several signals, e.g., o payment can proceed immediately, o required peripheral inclusive of some required physical payment instrument (chip card) is unavailable, o (non-IOTP) remote party (e.g., issuer, server wallet) is not available, o wallet identifier or pass phrase is required, o expired payment instrument (or certificate), insufficient funds, or o physical payment instrument unreadable. In any erroneous case, the user should be notified and offered accurate alternatives. Most probably, the user might be offered o to resolve the problem, e.g., to insert another payment instrument or to verify the periphery, o to proceed (assuming its success), o to cancel the whole transaction, orHans, et al. Informational [Page 23]
RFC 3867 Payment API for IOTP November 2004 o to suspend the transaction, e.g., initiating a nested transaction for uploading an electronic purse. 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. 6. The Steps 2 to 5 are repeated and possibly interlaced for the selection of the second payment instrument during IOTP Value Exchange transactions - this is omitted in the figure above. 7. The IOTP Brand Selection Component is generated and enriched with the Brand Selection Info elements. This component is transmitted to the Merchant inside a TPO Selection Block if the received IOTP message lacks the IOTP Offer Response Block. The Merchant will then respond with an IOTP Offer Response Block (following the aforementioned compilation rules).2.4. Successful Payment 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, activelyHans, et al. Informational [Page 24]
RFC 3867 Payment API for IOTP November 2004 | 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 1. After Brand Selection and receipt of the IOTP Offer Response Block, the Consumer switches from communicating with the Merchant to communicating with the Payment Handler. 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. 2. In order to open the actual payment transaction, the IOTP Application Core issues the "Start Payment Consumer" request towards the IOTP Payment Bridge. This request carries the whole initialization data of the payment transaction being referred to by the IOTP Payment Bridge for subsequent consistency checks: o payment brand and its description from the selected Brand Element of the IOTP Brand List Component, o payment instrument from preceding inquiry step,Hans, et al. Informational [Page 25]
RFC 3867 Payment API for IOTP November 2004 o further payment parameters (currency, amount, direction, expiration) from the selected Currency Amount element, Brand List Component, and Payment Component of the IOTP Offer Response Block, o payment protocol from the selected IOTP Pay Protocol Element, o order details contained in the IOTP Order Component which might be payment scheme specific, o payment scheme specific data inclusive of the payment protocol descriptions from the IOTP Protocol Amount Element, and IOTP Pay Protocol Element, and o payment scheme specific data inclusive of the payment protocol descriptions, in which the name attribute includes the prefix as "Payment:" from the Trading Role Data Component. 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.Hans, et al. Informational [Page 26]
RFC 3867 Payment API for IOTP November 2004 3. The Payment Handler's IOTP Application Core opens the payment transaction calling the "Start Payment Payment Handler" API function. The payment brand, its description, payment protocol, payment specific data, payment direction, currency and payment amount are determined quite similar to the Consumer's IOTP Application Core. Furthermore, the content of the IOTP Payment Scheme Component and the IOTP Brand Selection Info Elements are passed to this function. 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. 4. The IOTP Application Core verifies the presence of the Payment Exchange Block in the IOTP message and passes the contained payment scheme specific data to the fixed IOTP Payment Bridge ("Continue Process") which returns the next IOTP Payment Scheme Component. This Payment Scheme Component is encapsulated in an IOTP Payment Exchange Block and transmitted to the Payment Handler. 5. The Payment Handler's IOTP Application Core verifies the presence of the Payment Exchange Block and passes the contained payment scheme specific data to the fixed IOTP Payment Bridge ("Continue Process") which returns the next IOTP Payment Scheme Component for encapsulation and transmission to the Consumer. 6. The payment process continues with IOTP Payment Exchange Block exchanges, carrying the payment scheme specific data. Each party (1) submits the embedded payment scheme specific data transparently to the appropriate IOTP Payment Bridge calling the "Continue Process" API function, (2) wraps the returned payment scheme specific data into an IOTP Payment Exchange Block, and (3) transmits this block to the counter party.Hans, et al. Informational [Page 27]
RFC 3867 Payment API for IOTP November 2004 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. 7. Eventually, the Payment Handler's IOTP Payment Bridge recognizes the termination of the payment transaction and reports this by the continuation status "End" on the output parameter of "Continue Process" (or "Start Payment Payment Handler"). Then, the IOTP Application Core issues the "Inquire Process State" API call and verifies whether an IOTP Payment Receipt Component has been returned. The IOTP Application Core wraps the payment receipt, the status response, and the optional payment scheme specific data in an IOTP Payment Response Block and transmits this block to the Consumer. 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. 8. The Consumer passes the optional payment scheme specific data and the payment receipt to the fixed IOTP Payment Bridge by "Continue Process" and "Check Payment Receipt" API calls. 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.Hans, et al. Informational [Page 28]
RFC 3867 Payment API for IOTP November 2004 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.2.5. Payment Inquiry 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 1. The Consumer might initiate a payment inquiry once the payment transaction has been opened by the IOTP Application Core, i.e., at any time after the initial submission of the IOTP Payment Request Block. The IOTP Application Core requests any additional specific payment scheme data from the IOTP Payment Bridge which has been fixed during brand selection (cf.Section 2.3) using the "Start Payment Inquiry" API request. 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.Hans, et al. Informational [Page 29]
RFC 3867 Payment API for IOTP November 2004 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. 2. The Payment Handler analyses the IOTP Inquire Request Block, maps the Transaction Identifier to payment related attributes (brand, consumer and payment identifiers), determines the appropriate IOTP Payment Bridge, and forwards the request to the this IOTP Payment Bridge ("Inquire Payment Status"). The IOTP Application Core transforms the response to an IOTP Inquiry Response Block and transmits it to the Consumer. 3. On receipt of the respective IOTP Inquiry Response Block the Consumer's IOTP Application Core submits any encapsulated payment scheme specific data to the IOTP Payment Bridge for verification ("Continue Process"). 4. The IOTP Application Core passes the reported payment status (except textual descriptions) to the IOTP Payment Bridge ("Change Process State") for verification purposes and payment status change. The IOTP Payment Bridge reports any inconsistencies as well as the final payment status to the IOTP Application Core. 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.2.6. Abnormal Transaction Processing2.6.1. Failures and Cancellations The IOTP specification distinguishes between several classes of failures: o Business and technical errors o Error depths of transport, message and block level o Transient errors, warnings, and hard errors. 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: BusinessHans, et al. Informational [Page 30]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 31]
RFC 3867 Payment API for IOTP November 2004 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 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.2.6.2. Resumption Payment transaction resumption may apply at different steps of a payment transaction: o The Consumer's and Payment Handler's view of the transaction might not be synchronized: Due to different time-out values the payment transaction may not have been suspended by the counter party. 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. o One IOTP message sent by one party might not be processed successfully or even received by the counter party. This needs to be handled by the actual payment scheme. It is expected that the IOTP Application Core will not recognize anything.Hans, et al. Informational [Page 32]
RFC 3867 Payment API for IOTP November 2004 o IOTP does not provide any specific signal for payment resumption. On receipt of every IOTP Payment Exchange Block, the IOTP Application Core has to decide whether this Block belongs to a pending transaction or to a suspended transaction that should be resumed. The IOTP Application Core might call the "Inquire Process State" API function to update any lack of knowledge. 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. o The payment transaction may not have been created at the Payment Handler (early suspension and failed data transmission). In that case, the IOTP Application Core should respond with a business error that signals the repetition of the payment transaction (by the Consumer). 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. o The IOTP Application Core should always request fresh payment scheme specific data on resumption - for synchronization purposes with the Existing Payment Software. Old data in the cache that has not been sent to the counter party should not be accessed. 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.2.7. IOTP Wallet Initialization 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. 1. The IOTP Application Core interrogates the registered IOTP Payment Bridges about pending payment transactions. The IOTP Application Core may store indicators for pending transactions and use them for driving any subsequent inquiry ("Inquire Pending Payment").Hans, et al. Informational [Page 33]
RFC 3867 Payment API for IOTP November 2004 2. If one or more IOTP Payment Bridges report the presence of pending transactions, the IOTP Application Core may try to suspend ("Change Process State") or resume (only Consumer: "Resume Payment Consumer") the pending transactions (on user request). 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".2.8. Payment Software Management 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.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 |Hans, et al. Informational [Page 34]
RFC 3867 Payment API for IOTP November 2004 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" >Hans, et al. Informational [Page 35]
RFC 3867 Payment API for IOTP November 2004 <!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.Hans, et al. Informational [Page 36]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 37]
RFC 3867 Payment API for IOTP November 2004 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 53.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.Hans, et al. Informational [Page 38]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 39]
RFC 3867 Payment API for IOTP November 2004 (*)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).Hans, et al. Informational [Page 40]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 41]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 42]
RFC 3867 Payment API for IOTP November 2004 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 IdentifierHans, et al. Informational [Page 43]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 44]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 45]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 46]
RFC 3867 Payment API for IOTP November 2004 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 theHans, et al. Informational [Page 47]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 48]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 49]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 50]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 51]
RFC 3867 Payment API for IOTP November 2004 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, orHans, et al. Informational [Page 52]
RFC 3867 Payment API for IOTP November 2004 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 paymentHans, et al. Informational [Page 53]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 54]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 55]
RFC 3867 Payment API for IOTP November 2004 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].Hans, et al. Informational [Page 56]
RFC 3867 Payment API for IOTP November 2004 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 theHans, et al. Informational [Page 57]
RFC 3867 Payment API for IOTP November 2004 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 withHans, et al. Informational [Page 58]
RFC 3867 Payment API for IOTP November 2004 "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.Hans, et al. Informational [Page 59]
RFC 3867 Payment API for IOTP November 2004 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 % ProtocolAmountPackagedContentHans, et al. Informational [Page 60]
RFC 3867 Payment API for IOTP November 2004 "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.Hans, et al. Informational [Page 61]
RFC 3867 Payment API for IOTP November 2004 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 willHans, et al. Informational [Page 62]
RFC 3867 Payment API for IOTP November 2004 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: Merchant3.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.Hans, et al. Informational [Page 63]
RFC 3867 Payment API for IOTP November 2004 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.Hans, et al. Informational [Page 64]
RFC 3867 Payment API for IOTP November 2004 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: Consumer3.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.Hans, et al. Informational [Page 65]
RFC 3867 Payment API for IOTP November 2004 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: Consumer4. Payment API Calls4.1. Brand Compilation Related API Calls4.1.1. Find Accepted Payment Brand This API function determines the payment brands being accepted by the Payment Handler on behalf of the Merchant. Input Parameters o Payment Direction - provided by the IOTP Application Core o Currency Code and Currency - provided by the IOTP Application Core o Payment Amount - provided by the IOTP Application Core o Merchant Payment Identifier - Merchant's unique private reference to the payment transaction o Merchant Organisation Identifier - used for distinction between multiple merchants that share the some IOTP merchant system o Wallet Identifier - managed by the IOTP Application Core o Merchant Data - specific data used by the IOTP Payment Bridge which is managed in the IOTP Application Core.Hans, et al. Informational [Page 66]
RFC 3867 Payment API for IOTP November 2004 XML definition: <!ELEMENT FindAcceptedPaymentBrand (MerchantData*) > <!ATTLIST FindAcceptedPaymentBrand PayDirection (Debit|Credit) #REQUIRED CurrCodeType NMTOKEN 'ISO4217-A' CurrCode CDATA #REQUIRED Amount CDATA #REQUIRED MerchantPayId CDATA #REQUIRED MerchantOrgId CDATA #IMPLIED WalletID CDATA #IMPLIED > Output Parameters o Payment Brand Identifier - for insertion in the Brand List Component's Brand Element o Payment Brand Name and language annotation - for insertion in the Brand List Component's Brand Element o Payment Brand Logo Net Location - for insertion in the Brand List Component's Brand Element o Payment Brand Narrative Description - for insertion in the Brand List Component's Brand Element o (Brand) Packaged Content - further payment brand description for insertion in the Brand List Component's Brand Element The Existing Payment Software returns an empty list of brand items, if it does not support any payment brand/payment protocol combination for the given payment parameters. XML definition: <!ELEMENT FindAcceptedPaymentBrandResponse (BrandItem*) > <!ELEMENT BrandItem (BrandPackagedContent*) > <!ATTLIST BrandItem BrandId CDATA #REQUIRED xml:lang NMTOKEN #IMPLIED BrandName CDATA #REQUIRED BrandLogoNetLocn CDATA #REQUIRED BrandNarrative CDATA #IMPLIED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.Hans, et al. Informational [Page 67]
RFC 3867 Payment API for IOTP November 20044.1.2. Find Accepted Payment Protocol This API function determines the instances of payment protocols (and optionally the payment brands) being accepted by the Payment Handler on behalf of the Merchant. The function might be called in two variants: o With the Brand Identifier set on the input parameter list: The function responds with the payment protocols that fits to the submitted brand. o Without any Brand Identifier - that allows the omission of the "Find Accepted Payment Brand" API call (cf.Section 4.1.1): This function responds with both the supported brand identifiers and the payment protocols being specified by the Brand Elements. Input Parameters o Brand Identifier - returned by "Find Accepted Payment Brand" o Payment Direction o Currency Code and Currency o Payment Amount o Merchant Payment Identifier - Merchant's unique private reference to the payment transaction o Merchant Organisation Identifier - used for distinction between multiple merchants that share the some IOTP merchant system o Wallet Identifier - managed by the IOTP Application Core o (Brand) Packaged Content - further payment brand description; returned by "Find Accepted Payment Brand"; this elements are only provided if the Brand Identifier is set o Merchant Data - specific data used by the IOTP Payment Bridge which is managed in the IOTP Application Core. XML definition: <!ELEMENT FindAcceptedPaymentProtocol (BrandPackagedContent*, MerchantData?) > <!ATTLIST FindAcceptedPaymentProtocol BrandId CDATA #IMPLIED PayDirection (Debit|Credit) #REQUIRED CurrCodeType NMTOKEN 'ISO4217-A' CurrCode CDATA #REQUIRED Amount CDATA #REQUIRED MerchantPayId CDATA #REQUIRED MerchantOrgId CDATA #IMPLIED WalletID CDATA #IMPLIED >Hans, et al. Informational [Page 68]
RFC 3867 Payment API for IOTP November 2004 Output Parameters o Payment Protocol Identifier - for insertion in the Brand List Component's Pay Protocol Element o Protocol Brand Identifier - for insertion in the Protocol Brand Element of the Brand List Component's Brand Element o Payment Protocol Name and language annotation- for insertion in the Brand List Component's Pay Protocol Element o Payment Request Net Location - for insertion in the Brand List Component's Pay Protocol Element o Secured Payment Request Net Location - for insertion in the Brand List Component's Pay Protocol Element o Brand Item List (cf.Section 4.1.1) - there must be at least one element if no brand identifier has been provided on the input parameter list. o (Protocol Amount) Packaged Content - for insertion in the Brand List Component's Protocol Amount Element o (Pay Protocol) Packaged Content - for insertion in the Brand List Component's Pay Protocol Element o Currency Amount element - quite similar to the definition in [IOTP], that contain - refined Currency Code and Currency - for insertion in the Brand List Component's Currency Amount Element - refined Payment Amount - for insertion in the Brand List Component's Currency Amount Element o Brand - there must be at least one element in each Protocol Item if no brand identifier has been provided on the input parameter list. XML definition: <!ELEMENT FindAcceptedPaymentProtocolResponse (ProtocolItem+, BrandItem*) > <!ELEMENT ProtocolItem (ProtocolAmountPackagedContent*, PayProtocolPackagedContent* CurrencyAmount+, Brand*,ProtocolBrand*)> <!ATTLIST ProtocolItem ProtocolId CDATA #REQUIRED ProtocolBrandId CDATA #IMPLIED xml:lang NMTOKEN #IMPLIED ProtocolName CDATA #REQUIRED PayReqNetLocn CDATA #IMPLIED SecPayReqNetLocn CDATA #IMPLIED > <!ELEMENT Brand EMPTY > <!ATTLIST Brand BrandId CDATA #REQUIRED >Hans, et al. Informational [Page 69]
RFC 3867 Payment API for IOTP November 2004 <!ELEMENT CurrencyAmount EMPTY > <!ATTLIST CurrencyAmount CurrCodeType NMTOKEN 'ISO4217-A' CurrCode CDATA #IMPLIED Amount CDATA #IMPLIED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.1.3. Get Payment Initialization Data This API function provides the remaining initialization data being required by the Consumer's or Payment Handler's Existing Payment Software. This function might be called both for "brand dependent" and "brand independent" transaction types. In either case, this function is called with one particular brand. Input Parameters o Brand Identifier - returned by "Find Accepted Payment Brand" o Merchant Payment Identifier - Merchant's unique private reference to the payment transaction o Payment Direction o Currency Code and Currency - from the Brand List Component's Currency Amount Element o Payment Amount - from the Brand List Component's Currency Amount Element o Payment Protocol Identifier - from the Brand List Component's Pay Protocol Element o Protocol Brand Identifier - from the Protocol Brand Element which relates to the selected Brand Element, if any o (TradingRoleData) Receiver Organization Identifier o OkFrom, OkTo - identical to the entries of the Order Component Merchant Payment Identifier o Merchant Organisation Identifier - used for distinction between multiple merchants that share the some IOTP merchant system o Wallet Identifier and/or Pass Phrase Protocol Brand Element o (Brand) Packaged Content - further payment brand description, from the Brand List Component's Brand Element o (Protocol Amount) Packaged Content - further payment protocol description, from the Brand List Component's Protocol Amount ElementHans, et al. Informational [Page 70]
RFC 3867 Payment API for IOTP November 2004 o (Pay Protocol) Packaged Content - further payment protocol description, from the Brand List Component's Pay Protocol Element o (Protocol Brand) Packaged Content - further brand information, from the Protocol Brand Element of the Brand List Component which relates to the selected Brand Element, if any o (Order) Packaged Content - further order description, from the Order Element o three Brand Selection Info Packaged Content elements - copied from the Brand Selection Component on brand dependent purchases o Brand - additional data about the payment brand o Protocol Amount - additional data about the payment protocol o Currency Amount - additional payment brand and currency specific data o Merchant Data - specific data used by the IOTP Payment Bridge which is managed in the IOTP Application Core. XML definition: <!ELEMENT GetPaymentInitializationData (ProtocolBrand? BrandPackagedContent* ProtocolAmountPackagedContent*, PayProtocolPackagedContent*, OrderPackagedContent*, BrandSelBrandInfoPackagedContent*, BrandSelProtocolAmountInfoPackagedContent*, BrandSelCurrencyAmountInfoPackagedContent*, MerchantData*) > <!ATTLIST GetPaymentInitializationData BrandId CDATA #REQUIRED MerchantPayId CDATA #REQUIRED PayDirection (Debit|Credit) #REQUIRED CurrCodeType NMTOKEN 'ISO4217-A' CurrCode CDATA #REQUIRED Amount CDATA #REQUIRED ProtocolId CDATA #REQUIRED OkFrom CDATA #REQUIRED OkTo CDATA #REQUIRED ReceiverOrgId CDATA #IMPLIED MerchantOrgId CDATA #IMPLIED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED >Hans, et al. Informational [Page 71]
RFC 3867 Payment API for IOTP November 2004 Output Parameters o OkFrom, OkTo - for insertion in the Payment Component o (TradingRoleData) Packaged Content - further payment protocol description; the Name Attribute of the packaged Content element must include "Payment:" as the prefix, for example "Payment:SET-OD". For more information, see [SET/IOTP]. o (Order) Packaged Content - defaults to the supplied order packaged content if omitted. XML definition: <!ELEMENT GetPaymentInitializationDataResponse (OrderPackagedContent*, TradingRoleDataPackagedContent*) > <!ATTLIST GetPaymentInitializationDataResponse OkFrom CDATA #IMPLIED OkTo CDATA #IMPLIED> Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.1.4. Inquire Authentication Challenge This API function inquires any payment protocol specific authentication challenge value from the IOTP Payment Bridge. In Baseline IOTP this API function is called by the Merchant (or Financial Institution). The IOTP Application Core may propose a choice of algorithms to the IOTP Payment Bridge. However, the IOTP Payment Bridge may ignore the proposal and select some other algorithm. The inquiry is assumed to be stateless. E.g., the IOTP Application Core may check the returned algorithm and stop transaction processing without notifying the IOTP Payment Bridge. The IOTP Application Core may issue several API calls to the IOTP Payment Bridge to build up the IOTP Authentication Request Block. Any subsequently submitted choice of algorithms should be constrained by the accepted algorithms from earlier API responses. The IOTP Payment Bridge responds with the Business Error Code if it does not provide any (more) authentication algorithms and challenges.Hans, et al. Informational [Page 72]
RFC 3867 Payment API for IOTP November 2004 Input Parameters o Authentication Identifier - the authenticator may provide its payment identifier, i.e., Payment Handler or Merchant Payment Identifier. o Wallet Identifier and/or Pass Phrase o set of pre-selected algorithms for authentication XML definition: <!ELEMENT InquireAuthChallenge (Algorithm*) > <!ATTLIST InquireAuthChallenge AuthenticationId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o list of Authentication Challenge Packaged Contents - for insertion into the IOTP Authentication Request Component o Algorithm Element - for insertion into the IOTP Authentication Request Component XML definition: <!ELEMENT InquireAuthChallengeResponse (AuthReqPackagedContent*, Algorithm) >4.1.5. Authenticate The Consumer's IOTP Application Core defers payment protocol specific authentication processing and the current challenge value to the active IOTP Payment Bridge. Alternative authentication algorithms might be tried sequentially or offered to the user for selection. Note that the IOTP Application Core has to consider both the current context and the algorithm in order to determine the responsible IOTP Payment Bridge. Failed authentication is reported by the Business Error Code which might trigger the inquiry of the details ("Inquire Process State"). Final failures might be encoded by the process state "Failed".Hans, et al. Informational [Page 73]
RFC 3867 Payment API for IOTP November 2004 Input Parameters o Authentication Identifier o Wallet Identifier and/or Pass Phrase o Authentication Challenge Packaged Content - copied from the IOTP Authentication Request Component o Algorithm Element - copied from the IOTP Authentication Request Component XML definition: <!ELEMENT Authenticate (Algorithm, AuthReqPackagedContent*) > <!ATTLIST Authenticate AuthenticationId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o Authentication Response Packaged Content - for insertion into the IOTP Authentication Response Component XML definition: <!ELEMENT AuthenticateResponse (AuthResPackagedContent*) > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.1.6. Check Authentication Response This API function verifies the Consumer's payment protocol specific authentication response. In Baseline IOTP this API function is called by the Merchant (or the Financial Institution). It is called only if the counter party has responded with an IOTP Authentication Response Component within the Authentication Response Block. Of course, the IOTP Application Core traces the need of such an response. Due to the authentication's statelessness, all parameters (algorithm, challenge and response) are submitted to the IOTP Payment Bridge. Authentication failure is reported by a Process State different from "CompletedOK".Hans, et al. Informational [Page 74]
RFC 3867 Payment API for IOTP November 2004 Input Parameters o Authentication Identifier o Wallet Identifier and/or Pass Phrase o Authentication Challenge Packaged Content - generated by previous "Inquire Authentication Challenge" API call o Algorithm Element o Authentication Response Packaged Content - copied from the Authentication Response Component XML definition: <!ELEMENT CheckAuthResponse (Algorithm, AuthReqPackagedContent*, AuthResPackagedContent*) > <!ATTLIST CheckAuthResponse AuthenticationId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o Current Process (Authentication) State o Completion Code o Status Description and its language annotation XML definition: <!ELEMENT CheckAuthResponseResponse EMPTY > <!ATTLIST CheckAuthResponseResponse ProcessState (NotYetStarted | InProgress | Suspended | CompletedOk | Failed | ProcessError)#REQUIRED CompletionCode NMTOKEN #IMPLIED xml:lang NMTOKEN #IMPLIED StatusDesc CDATA #IMPLIED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.Hans, et al. Informational [Page 75]
RFC 3867 Payment API for IOTP November 20044.2. Brand Selection Related API Calls4.2.1. Find Payment Instrument This API function determines which instances of a Payment Brand, e.g., two Mondex cards, are present. The same physical card may even represent multiple payment instruments. The IOTP Application Core supplies possible payment brand and payment protocol to the IOTP Payment Bridge that has to be considered when the IOTP Payment Bridge searches for appropriate payment instruments. This set represents the (sub)set of payment alternatives being supported by the Merchant. If the IOTP Application Cote has multiple possible payment brand/protocol, it can call this function in turn. The Existing Payment Software responds with PayInstrument Elements with empty PayInstId attributes if it does not distinguish between different payment instruments for the particular payment alternatives. Note that the Payment API assumes that the values of the attributes BrandId, ProtocolId, ProtocolBrandId and the currency amount suffice for the determination of the appropriate Packaged Content Element that will be transmitted to the Payment Handler later on. Input Parameters o Brand Identifier - copied from the Brand List Component's Brand Element o Payment Protocol Identifier and associated Protocol Brand Identifier o Payment Direction - copied from the Brand List Component o Currency Code and Currency - copied from the Currency Amount Element o Payment Amount - copied from the Currency Amount Element o Consumer Payment Identifier - Consumer's unique reference to the current payment transaction o Wallet Identifier - managed by the IOTP Application Core o (Brand) Packaged Content - further payment brand description; copied from the Brand List Component's Brand Element o (Protocol Brand) Element - further information; copied from the Protocol Brand Element of the Brand List Component which relates to the Consumer selected Brand Element, if any. o (Protocol Amount) Packaged Content - further payment protocol description, copied from the Brand List Component's Protocol Amount ElementHans, et al. Informational [Page 76]
RFC 3867 Payment API for IOTP November 2004 o Element (Protocol) Packaged Content - further payment protocol description, copied from the Brand List Component's Pay Protocol Element XML definition: <!ELEMENT FindPaymentInstrument (BrandPackagedContent*, ProtocolBrand?, PayProtocolPackagedContent*, ProtocolAmountPackagedContent*) > <!ATTLIST FindPaymentInstrument BrandId CDATA #REQUIRED ProtocolId CDATA #REQUIRED PayDirection (Debit|Credit) #REQUIRED CurrCodeType NMTOKEN 'ISO4217-A' CurrCode CDATA #REQUIRED Amount CDATA #REQUIRED ConsumerPayId CDATA #REQUIRED WalletID CDATA #IMPLIED > Output Parameters o The known Payment Instrument Identifiers, these are internal values o The user-defined names of the payment instrument and their language encoding The Existing Payment Software responds with an empty list of identifiers, either if it does not distinguish between different payment instruments or if there are no registered payment instruments available despite brand support for at least one (unspecified) payment protocol. In the latter case, the IOTP Payment Bridge has to request the registration of a suitable payment instrument at a subsequent step of the payment process. XML definition: <!ELEMENT FindPaymentInstrumentResponse (PayInstrument*) > <!ELEMENT PayInstrument EMPTY > <!ATTLIST PayInstrument Id CDATA #REQUIRED xml:lang NMTOKEN #IMPLIED PayInstName CDATA #REQUIRED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.Hans, et al. Informational [Page 77]
RFC 3867 Payment API for IOTP November 20044.2.2. Check Payment Possibility This API function checks whether a payment (both debit and credit) can go ahead. It can be used, for example, to check o if there are sufficient funds available in a particular currency for an electronic cash payment brand, o whether there is sufficient value space left on the payment instrument for payment refund, o whether required system resources are available and properly configured, e.g., serial ports or baud rate, o whether environment requirements are fulfilled, e.g., chip card reader presence or Internet connection. If the payment method is based on external components, e.g., magnetic stripe or chip cards, and the check accesses the medium, the existing payment method should not mutually exclusive lock system resources, e.g., serial port or modem, that may also be required by other Existing Payment Software, e.g., multiple payment software components may share the same card reader. If this happens for API internal request processing, the function has to unlock these components prior to return. Otherwise, the payment may not proceed if the Consumer cancels immediately and decides to use another payment instrument. In this event the previous IOTP Payment Bridge is not notified about the change. This function call happens immediately after the Consumer's payment instrument selection. For example, if the payment instrument is a chip card, that is not inserted in the chip card reader, the Consumer may be prompted for its insertion. However, the Consumer should be able to hit some 'skip' button, if the payment check is part of the actual payment protocol, too. Finally, the IOTP Payment Bridge may provide only a subset of these capabilities or may even directly generate a successful response without any checks. Input Parameters o Brand Identifier - user selection o Payment Instrument Identifier - user selection o Currency Code and Currency Code Type - copied from the selected Currency Amount Element o Payment Amount - copied from the selected Currency Amount Element o Payment Direction - copied from the selected Trading Protocol Option Block o Protocol Identifier - copied from the selected Pay Protocol ElementHans, et al. Informational [Page 78]
RFC 3867 Payment API for IOTP November 2004 o Protocol Brand Identifier - copied from the selected Protocol Brand Element of the Brand List Component which relates to the selected Brand Element, if any o Consumer Payment Identifier - Consumer's unique reference to the current payment transaction o Wallet Identifier and/or Pass Phrase o (Brand) Packaged Content - copied from the selected Brand Element o (Protocol Amount) Packaged Content - copied from the selected Protocol Amount Element o (Protocol) Packaged Content - copied from the selected Pay Protocol Element o (Protocol Brand) Packaged Content - copied from the selected Protocol Brand Element of the Brand List Component which relates to the selected Brand Element, if any XML definition: <!ELEMENT CheckPaymentPossibility (BrandPackagedContent*, ProtocolBrand? ProtocolAmountPackagedContent*, PayProtocolPackagedContent*> <!ATTLIST CheckPaymentPossibility BrandId CDATA #REQUIRED PaymentInstrumentId CDATA #IMPLIED PayDirection (Debit|Credit) #REQUIRED CurrCodeType NMTOKEN 'ISO4217-A' CurrCode CDATA #REQUIRED Amount CDATA #REQUIRED ProtocolId CDATA #REQUIRED ConsumerPayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o three Brand Selection Info Packaged Content elements - for insertion into the Brand Selection component o Brand - additional data about the payment brand o Protocol Amount - additional data about the payment protocol o Currency Amount - additional payment brand and currency specific dataHans, et al. Informational [Page 79]
RFC 3867 Payment API for IOTP November 2004 XML definition: <!ELEMENT CheckPaymentPossibilityResponse (BrandSelBrandInfoPackagedContent*, BrandSelProtocolAmountInfoPackagedContent*, BrandSelCurrencyAmountInfoPackagedContent*) > <!ATTLIST CheckPaymentPossibilityResponse > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.3. Payment Transaction Related API calls These Payment API calls may be made either by the Consumer's or Payment Handler's IOTP Application Core.4.3.1. Start Payment Consumer This API function initiates the actual payment transaction at the Consumer side. The IOTP Payment Bridge and the Existing Payment Software perform all necessary initialization and preparation for payment transaction processing. This includes the reservation of external periphery. E.g., 1) the Consumer's chip card reader needs to be protected against access from other software components, 2) the insertion of the chip card may be requested, 3) the Internet connection may be re-established, or 4) the Payment Handler may open a mutual exclusive session to the security hardware. The IOTP Payment Bridge monitors the payment progress and stores the current payment states such that resumption - even after power failures - remains possible. Note that the IOTP Application Core supplies only a subset of the following input parameter to the associated resumption API function and refers to the payment transaction through the party's payment identifier. Input Parameters o Brand Identifier - copied from the selected Brand Element o Payment Instrument Identifier - the user selection o Currency Code and Currency - copied from the selected Currency Amount Element o Payment Amount - copied from the selected Currency Amount Element o Payment Direction - copied from the Brand List Component o Protocol Identifier - copied from the selected Payment Protocol ElementHans, et al. Informational [Page 80]
RFC 3867 Payment API for IOTP November 2004 o Protocol Brand Element - further information; copied from the Protocol Brand Element of the Brand List Component which relates to the selected Brand Element, if any o OkFrom, OkTo - copied from the Payment Component o Consumer Payment Identifier - Consumer's unique reference to the current payment transaction o Wallet Identifier and/or Pass Phrase o Call Back Function - used for end user notification/logging purposes o Call Back Language List. This list is required if the Call Back Function is set o (Brand) Packaged Content - further payment brand description; copied from the selected Brand Element's content o (Protocol Amount) Packaged Content - further payment protocol description; copied from the selected Protocol Amount Element's content o (Payment Protocol) Packaged Content - further payment protocol description; copied from the selected Pay Protocol Element's content o (Order) Packaged Content - further order description, copied from the Order Component XML definition: <!ELEMENT StartPaymentConsumer (BrandPackagedContent*, ProtocolBrand? ProtocolAmountPackagedContent*, PayProtocolPackagedContent*, OrderPackagedContent*) > <!ATTLIST StartPaymentConsumer BrandId CDATA #REQUIRED PaymentInstrumentId CDATA #IMPLIED CurrCodeType NMTOKEN 'ISO4217-A' CurrCode CDATA #REQUIRED Amount CDATA #REQUIRED PayDirection (Debit|Credit) #REQUIRED ProtocolId CDATA #REQUIRED ProtocolBrandId CDATA #IMPLIED OkFrom CDATA #REQUIRED OkTo CDATA #REQUIRED ConsumerPayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED CallBackFunction CDATA #IMPLIED CallBackLanguageList NMTOKENS #IMPLIED >Hans, et al. Informational [Page 81]
RFC 3867 Payment API for IOTP November 2004 Output Parameters o Continuation Status o (Payment Scheme) Packaged Content - for insertion into the Payment Scheme Component of the IOTP Payment Request Block The IOTP Application Core is allowed to reissue this request several times on failed analyses of the response. XML definition: <!ELEMENT StartPaymentConsumerResponse (PaySchemePackagedContent*) > <!ATTLIST StartPaymentConsumerResponse ContStatus (End|Continue) #REQUIRED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.3.2. Start Payment Payment Handler This API function initializes the Consumer initiated payment transaction at the Payment Handler's side. Similar to the Consumer's system, the IOTP Payment Bridge and the Existing Payment Software perform all necessary initialization and preparation for payment transaction processing. Input Parameters o Brand Identifier - copied from the Consumer selected Brand Element o Consumer Payment Identifier - copied from the Payment Scheme Component o Currency Code and Currency - copied from the Consumer selected Currency Amount Element o Payment Amount - copied from the Consumer selected Currency Amount Element o Payment Direction - copied from the Brand List Component o Protocol Identifier - copied from the Consumer selected Payment Protocol Element o Protocol Brand Identifier - copied from the Brand Protocol Element of the Brand List Component which relates to the Consumer selected Brand Element, if any o OkFrom, OkTo - copied from the Payment Component o Payment Handler Payment Identifier - Payment Handler's unique reference to the current payment transaction o Merchant Organisation Identifier - copied from the Merchant's Organisation ElementHans, et al. Informational [Page 82]
RFC 3867 Payment API for IOTP November 2004 o Wallet Identifier - renaming to till identifier neglected - and/or Pass Phrase o Call Back Function - used for end user notification/logging purposes o Call Back Language List. This list is required if the call back function is set o (Brand) Packaged Content - further payment brand description; copied from the Consumer selected Brand Element's content o (Protocol Brand) Packaged Content - further information; copied from the Protocol Brand Element of the Brand List Component which relates to the Consumer selected Brand Element, if any. o (Protocol Amount) Packaged Content - further payment protocol description; copied from the Consumer selected Protocol Amount Element's content o (Protocol) Packaged Content - further payment protocol description; copied from the Consumer selected Pay Protocol Element's content o (TradingRoleData) Packaged Content - further payment protocol description; the Name Attribute of the packaged contents must include "Payment:" as the prefix, for example "Payment:SET-OD". For more information, see [SET/IOTP]. o Three Brand Selection Info Packaged Content Elements - copied from the Brand Selection Component o Brand - additional data about the payment brand o Protocol Amount - additional data about the payment protocol o Currency Amount - additional payment brand and currency specific data o (Payment Scheme) Packaged Content. XML definition: <!ELEMENT StartPaymentPaymentHandler (BrandPackagedContent*, ProtocolBrand?, ProtocolAmountPackagedContent*, PayProtocolPackagedContent*, BrandSelBrandInfoPackagedContent*, BrandSelProtocolAmountInfoPackagedContent*, BrandSelCurrencyAmountInfoPackagedContent*, TradingRoleDataPackagedContent*, PaySchemePackagedContent*) > <!ATTLIST StartPaymentPaymentHandler BrandId CDATA #REQUIRED ConsumerPayId CDATA #IMPLIED CurrCodeType NMTOKEN 'ISO4217-A' CurrCode CDATA #REQUIRED Amount CDATA #REQUIRED PayDirection (Debit|Credit) #REQUIRED ProtocolId CDATA #REQUIREDHans, et al. Informational [Page 83]
RFC 3867 Payment API for IOTP November 2004 OkFrom CDATA #REQUIRED OkTo CDATA #REQUIRED PaymentHandlerPayId CDATA #REQUIRED MerchantOrgId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED CallBackFunction CDATA #IMPLIED CallBackLanguageList NMTOKENS #IMPLIED > Output Parameters o Continuation Status o (Payment Scheme) Packaged Content - for insertion into the Payment Scheme Component of the IOTP Payment Exchange Block The response message must contain payment schema data if the continuation status signals "Continue". The IOTP Application Core is allowed to reissue this request several times on failed analyses of the response. XML definition: <!ELEMENT StartPaymentPaymentHandlerResponse (PaySchemePackagedContent*) > <!ATTLIST StartPaymentPaymentHandlerResponse ContStatus (End|Continue) #REQUIRED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.3.3. Resume Payment Consumer This API function resumes a previously suspended payment at the Consumer side. Resumption includes the internal inquiry of the payment transaction data, e.g., payment amount, protocol identifier, and the whole initialization as it has been applied on the "Start Payment Consumer" API request. It is up to the IOTP Application Core to decide whether an IOTP Payment Request Block or a IOTP Payment Exchange Block needs to be generated. One indicator might be the receipt of a previous IOTP Payment Exchange Block from the Payment Handler, e.g., the knowledge of the Payment Handler Payment Identifier. Input Parameters o Consumer Payment Identifier o Wallet Identifier and/or Pass PhraseHans, et al. Informational [Page 84]
RFC 3867 Payment API for IOTP November 2004 o Call Back Function - used for end user notification/logging purposes XML definition: <!ELEMENT ResumePaymentConsumer EMPTY > <!ATTLIST ResumePaymentConsumer ConsumerPayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED CallBackFunction CDATA #IMPLIED CallBackLanguageList NMTOKENS #IMPLIED > Output Parameters o Continuation Status o (Payment Scheme) Packaged Content - for insertion in the Payment Scheme Component of the next IOTP message (Payment Exchange or Request Block). The IOTP Application Core is allowed to reissue this request several times on failed analyses of the response. However, the IOTP Payment Bridge might reject the resumption request by using the "AttNotSupp" Error Code "naming" the Consumer Payment Identifier attribute. Then the Consumer has to apply normal error processing to the current (sub-)transaction and to issue a new Payment Request Block to the Payment Handler. XML definition: <!ELEMENT ResumePaymentConsumerResponse (PaySchemePackagedContent*) > <!ATTLIST ResumePaymentConsumerResponse ContStatus (End|Continue) #REQUIRED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.3.4. Resume Payment Payment Handler This API function resumes a payment at the Payment Handler side. Input Parameters o Payment Handler Payment Identifier o Wallet Identifier - renaming to till identifier neglected - and Pass PhraseHans, et al. Informational [Page 85]
RFC 3867 Payment API for IOTP November 2004 o Call Back Function - used for end user notification/logging purposes o Call Back Language List. This list is required if the Call Back Function is set o (Payment Scheme) Packaged Content - copied from the Payment Scheme Component of the received IOTP message (Payment Exchange or Request Block). XML definition: <!ELEMENT ResumePaymentPaymentHandler (PaySchemePackagedContent*) > <!ATTLIST ResumePaymentPaymentHandler PaymentHandlerPayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED CallBackFunction CDATA #IMPLIED CallBackLanguageList NMTOKENS #IMPLIED > Output Parameters o Continuation Status o (Payment Scheme) Packaged Content - for insertion in the Payment Scheme Component of the next Payment Exchange Block. The response message contains payment schema specific data if the continuation status signals "Continue". The IOTP Application Core is allowed to reissue this request several times on failed analyses of the response. XML definition: <!ELEMENT ResumePaymentPaymentHandlerResponse (PaySchemePackagedContent*) > <!ATTLIST ResumePaymentPaymentHandlerResponse ContStatus (End|Continue) #REQUIRED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.3.5. Continue Process This API function passes one specific IOTP Payment Scheme Component, i.e., the encapsulated Packaged Content elements, received from the counter party (e.g., Consumer) to the IOTP Payment Bridge and responds with the next IOTP Payment Scheme Component for submission to the counter party.Hans, et al. Informational [Page 86]
RFC 3867 Payment API for IOTP November 2004 Input Parameters o Payty's Payment Identifier o Process (Transaction) Type which distinguishes between Payments and Inquiries. o Wallet Identifier and/or Pass Phrase o (Payment Scheme) Packaged Content - copied from the Payment Scheme Component of the received Payment Exchange Block or from the Error Block. Each party should set the payment identifier with the local identifier (Consumer: ConsumerPayId; Merchant: MerchantPayId; Payment Handler: PaymentHandlerPayId). XML definition: <!ELEMENT ContinueProcess (PaySchemePackagedContent+) > <!ATTLIST ContinueProcess PayId CDATA #REQUIRED ProcessType (Payment | Inquiry) 'Payment' WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o Continuation Status o (Payment Scheme) Packaged Content - for insertion in the Payment Scheme Component of the next Payment Exchange Block or final Payment Response Block The response message contains payment schema data if the continuation status signals "Continue". The IOTP Payment Bridge must signal "End", if the payment scheme data was received within an IOTP Error Block containing an Error Component with severity HardError. XML definition: <!ELEMENT ContinueProcessResponse (PaySchemePackagedContent*) > <!ATTLIST ContinueProcessResponse ContStatus (End|Continue) #REQUIRED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.Hans, et al. Informational [Page 87]
RFC 3867 Payment API for IOTP November 20044.3.6. Change Process State The IOTP Application Core changes the current payment status by this request. The IOTP Payment Bridge may be notified about business level normal termination, cancellation, suspension, and processing errors. Notification happens by requesting the intended process state. The IOTP Payment Bridge processes the status change and reports the result. The IOTP Application Core has to analyze any returned process status in order to check whether the IOTP Payment Bridge has agreed to or declined the status switch. E.g., the submitted Process State "CompleteOk" may lead to the Payment Status "Failed" if the payment transaction has already failed. Transaction Suspension is notified by the newly introduced Process State "Suspended". The other attribute values have been taken from the IOTP specification. This API function might be called by the Consumer, Merchant, or Payment Handler for each payment transaction anytime after the issuance of "FindPaymentInstrument" to the IOTP Payment Bridge by the Consumer, the issuance of "FindAcceptedPaymentBrand" by the Merchant, or the issuance of "StartPaymentPaymentHandler" by the Payment Handler. The Process States "CompletedOk", "Failed", and "ProcessError" are final in the sense that they can not be changed on subsequent calls. However, the API function should not return with an error code if such an incompatible call has been issued. Instead it should report the old unchanged Process State. Unknown payment transactions are reported by the Error Code "AttValInvalid" pointing to the PayId attribute. Input Parameters o Party's Payment Identifier o intended Payment Status o intended Completion Code o Process (Transaction) Type which distinguishes between Payments and Inquiries. o Wallet Identifier and/or Pass PhraseHans, et al. Informational [Page 88]
RFC 3867 Payment API for IOTP November 2004 XML definition: <!ELEMENT ChangeProcessState EMPTY > <!ATTLIST ChangeProcessState PayId CDATA #REQUIRED ProcessState (NotYetStarted | InProgress | Suspended | CompletedOk | Failed | ProcessError) #REQUIRED CompletionCode NMTOKEN #IMPLIED ProcessType (Payment | Inquiry) 'Payment' WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o Process State and Percent Complete o Completion Code o Status Description and its language annotation XML definition: <!ELEMENT ChangeProcessStateResponse EMPTY > <!ATTLIST ChangeProcessStateResponse ProcessState (NotYetStarted | InProgress | Suspended | CompletedOk | Failed | ProcessError) #REQUIRED PercentComplete CDATA #IMPLIED CompletionCode NMTOKEN #IMPLIED xml:lang NMTOKEN #IMPLIED StatusDesc CDATA #IMPLIED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.4. General Inquiry API Calls The following calls are not necessarily assigned to a payment transaction and may be issued at any time. There are no dependencies on any other calls.Hans, et al. Informational [Page 89]
RFC 3867 Payment API for IOTP November 20044.4.1. Remove Payment Log The IOTP Application Core notifies the IOTP Payment Bridge and/or the corresponding Existing Payment Software via IOTP Payment Bridge that any record in the Payment Log file, that deals with the listed payment transaction, might be removed. Input Parameters o Party's Payment Identifier o Wallet Identifier and/or Pass Phrase XML definition: <!ELEMENT RemovePaymentLog EMPTY > <!ATTLIST RemovePaymentLog PayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters XML definition: <!ELEMENT RemovePaymentLogResponse EMPTY > <!ATTLIST RemovePaymentLogResponse > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.4.2. Payment Instrument Inquiry This API function retrieves the properties of the Payment Instrument. The Payment Instrument Identifier could be omitted if this identifier is derived by other means, e.g., by analysis of the currently inserted chip card. If the Payment instrument could not uniquely determined, the IOTP Payment Bridge may provide suitable dialogs for user input. E.g., this API function might be used during problem resolution with the Customer Care Provider of the issuer of the payment instrument, in order to inquire payment instrument specific values. Input parameters o Brand Identifier o Payment Instrument Identifier o Protocol IdentifierHans, et al. Informational [Page 90]
RFC 3867 Payment API for IOTP November 2004 o Wallet Identifier and/or Pass Phrase o Property Type List - sequence of values whose language is identified by xml:lang o (Brand) PackagedContent Content - further payment brand description o Protocol Brand Content - further payment brand information o (Protocol Amount) PackagedContent Content - further payment protocol description o (Pay Protocol) PackagedContent Content - further payment protocol description The codes in the property type list are of two types: o generic codes which apply to all payment methods but might be unavailable o Payment Brand specific codes. Generic codes for the Property Type List are: Property Type Meaning Balance Current balance Limit Maximum balance PaymentLimit Maximum payment transaction limit Expiration Expiration date Identifier Issuer assigned identifier of the payment instrument. Usually, it does not match with the API's payment instrument identifier. LogEntries Number of stored payment transaction entries. The entries are numbered from 0 (the most recent) to some non-negative value for the oldest entry. PayAmountn Payment Amount of the n-th recorded payment transaction, n may negative PayPartyn Remote party of the n-th payment recorded transaction, n may negative PayTimen Time of the n-th payment recorded transaction, n may negative XML definition: <!ELEMENT PaymentInstrumentInquiry (BrandPackagedContent*, ProtocolBrand?, ProtocolAmountPackagedContent*, PayProtocolPackagedContent*) > <!ATTLIST PaymentInstrumentInquiry BrandId CDATA #REQUIRED PaymentInstrumentId CDATA #IMPLIED ProtocolId CDATA #REQUIREDHans, et al. Informational [Page 91]
RFC 3867 Payment API for IOTP November 2004 PropertyTypeList NMTOKENS #REQUIRED xml:lang NMTOKEN #IMPLIED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output parameters o a list of zero or more unavailable property values whose language are identified by xml:lang. o a list of zero or more sets of "Properties Types", "Property Values" and "Property Descriptions" XML definition: <!ELEMENT PaymentInstrumentInquiryResponse (PaymentInstrumentProperty*) > <!ATTLIST PaymentInstrumentInquiryResponse xml:lang NMTOKEN #REQUIRED UnavailablePropertyList NMTOKENS #IMPLIED > <!ELEMENT PaymentInstrumentProperty EMPTY > <!ATTLIST PaymentInstrumentProperty PropertyType NMTOKEN #REQUIRED PropertyValue CDATA #REQUIRED PropertyDesc CDATA #REQUIRED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.4.3. Inquire Pending Payment This API function reports the party's payment identifiers of any pending payment transactions that the IOTP Payment Bridge/Existing Payment Software recommends be completed or suspended prior to the processing of new payment transactions. It does not respond with further transaction details. These have to be requested with "Inquire Process State". Note that the IOTP Payment Bridge has to respond without the benefit of any pass phrase if there exist no pending payment transaction. But if there are some pending payment transactions, the IOTP Payment Bridge may refuse the immediate response and may instead request the appropriate pass phase from the IOTP Application Core. Input Parameters o Wallet Identifier and/or PassphraseHans, et al. Informational [Page 92]
RFC 3867 Payment API for IOTP November 2004 XML definition: <!ELEMENT InquirePendingPayment EMPTY > <!ATTLIST InquirePendingPayment WalletId CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o Party's Payment Identifier XML definition: <!ELEMENT InquirePendingPaymentResponse (PaymentId*) > <!ELEMENT PaymentId EMPTY > <!ATTLIST PaymentId PayId CDATA #REQUIRED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.5. Payment Related Inquiry API Calls4.5.1. Check Payment Receipt This function is used by the Consumer and might be used by the Payment Handler to check the consistency, validity, and integrity of IOTP payment receipts which might consist of Packaged Content Elements o from the IOTP Payment Receipt Component - provided by the Payment Handler's "Inquire Process State" API call shortly before payment completion, o from Payment Scheme Components being exchanged during the actual payment, or o being returned by the Consumer's "Inquire Process State" API call shortly before payment completion The IOTP Application Core has to check the PayReceiptNameRefs attribute of the IOTP Payment Receipt Component and to supply exactly the Packaged Content Elements being referred to. Failed verification is returns a business error.Hans, et al. Informational [Page 93]
RFC 3867 Payment API for IOTP November 2004 Note that this Payment API assumes that any payment receipt builds upon a subset of elements with reference to [IOTP]. Furthermore, the Packaged Content Element have to be distinguishable by their Name attribute. Input Parameters o Party's Payment Identifier o Wallet Identifier and/or Pass Phrase o All Packaged Content Elements in the payment receipt XML definition: <!ELEMENT CheckPaymentReceipt (PackagedContent*) > <!ATTLIST CheckPaymentReceipt PayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters XML definition: <!ELEMENT CheckPaymentReceiptResponse EMPTY > <!ATTLIST CheckPaymentReceiptResponse > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.5.2. Expand Payment Receipt This API function expands any IOTP payment receipt into a form which may be used for display or printing purposes. "Check Payment Receipt" should be used first if there is any question of the payment receipt containing errors. The same conventions apply to the input parameter as for "Check Payment Receipt" (cf.Section 4.5.1). Input Parameters o Party's Payment Identifier o Wallet Identifier and/or Pass Phrase o All Packaged Content Elements that build the payment receiptHans, et al. Informational [Page 94]
RFC 3867 Payment API for IOTP November 2004 XML definition: <!ELEMENT ExpandPaymentReceipt (PackagedContent*) > <!ATTLIST ExpandPaymentReceipt PayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o Brand Identifier o Protocol specific Brand Identifier o Payment Instrument Identifier o Currency Code and Currency Code Type o Payment Amount o Payment Direction o Time Stamp - issuance of the receipt o Protocol Identifier o Protocol specific Transaction Identifier - this is an internal reference number which identifies the payment o Consumer Description, Payment Handler Description, and a language annotation o Style Sheet Net Location o Payment Property List. A list of type/value/description triples which contains additional information about the payment which is not covered by any of the other output parameters; property descriptions have to consider the language annotation. The Style Sheet Net Location refers to a Style Sheet (e.g., [XSLT]) that contains presentation information about the reported XML encoded data. XML definition: <!ELEMENT ExpandPaymentReceiptResponse (PaymentProperty*) > <!ATTLIST ExpandPaymentReceiptResponse BrandId CDATA #IMPLIED PaymentInstrumentId CDATA #IMPLIED Amount CDATA #IMPLIED CurrCodeType NMTOKEN #IMPLIED CurrCode CDATA #IMPLIED PayDirection (Debit|Credit) #IMPLIED TimeStamp CDATA #IMPLIED ProtocolId CDATA #IMPLIED ProtocolBrandId CDATA #IMPLIED ProtocolTransId CDATA #IMPLIED xml:lang NMTOKEN #IMPLIED ConsumerDesc CDATA #IMPLIEDHans, et al. Informational [Page 95]
RFC 3867 Payment API for IOTP November 2004 PaymentHandlerDesc CDATA #IMPLIED StyleSheetNetLocn CDATA #IMPLIED> <!ELEMENT PaymentProperty EMPTY > <!ATTLIST PaymentProperty PropertyType NMTOKEN #REQUIRED PropertyValue CDATA #REQUIRED PropertyDesc CDATA #REQUIRED > The Existing Payment Software should return as many attributes as possible from the supplied IOTP Payment Receipt. The payment supplement defines the attribute values for the payment properties. Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.5.3. Inquire Process State This API function returns the current payment state and optionally further Packaged Content Elements that form the payment receipt. Called by the Payment Handler, the IOTP Payment Bridge might respond with data intended for inclusion in the IOTP Payment Receipt Component's Packaged Content. When the Consumer calls this function shortly before payment completion, it may respond with further items of the payment receipt. Such items might be created by a chip card. Input Parameters o Party's Payment Identifier o Wallet Identifier and/or Pass Phrase XML definition: <!ELEMENT InquireProcessState EMPTY > <!ATTLIST InquireProcessState PayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o Current Process State and Percent Complete o Completion Code o Status Description and its language annotation o Payment Receipt Name References to all Packaged Content Elements that build the payment receipt (cf.Section 4.5.1), even if they have not been created so far (Consumer's share)Hans, et al. Informational [Page 96]
RFC 3867 Payment API for IOTP November 2004 o Any Packaged Content Element being available that form the payment receipt The IOTP provides a linking capability to the payment receipt delivery. Instead of encapsulating the whole payment specific data into the packaged content of the payment receipt, other Payment Scheme Components' Packaged Content might be referred to. XML definition: <!ELEMENT InquireProcessStateResponse (PackagedContent*) > <!ATTLIST InquireProcessStateResponse ProcessState (NotYetStarted | InProgress | Suspended | CompletedOk | Failed | ProcessError) #REQUIRED PercentComplete CDATA #IMPLIED CompletionCode NMTOKEN #IMPLIED xml:lang NMTOKEN #IMPLIED StatusDesc CDATA #IMPLIED PayReceiptNameRefs NMTOKENS #IMPLIED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.5.4. Start Payment Inquiry This API function responds with any additional payment scheme specific data that is needed by the Payment Handler for Consumer initiated payment transaction inquiry processing. Probably, the IOTP Payment Bridge (or the corresponding Existing Payment Software) has to determine the payment related items that were provided with the "Start Payment Consumer" API function call. Input Parameters o Consumer Payment Identifier o Wallet Identifier and/or Pass PhraseHans, et al. Informational [Page 97]
RFC 3867 Payment API for IOTP November 2004 XML definition: <!ELEMENT StartPaymentInquiry EMPTY > <!ATTLIST StartPaymentInquiry ConsumerPayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o (Payment Scheme) Packaged Content - intended for insertion in the Payment Scheme Component of the Inquiry Request Block XML definition: <!ELEMENT StartPaymentInquiryResponse (PaySchemePackagedContent*) > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.5.5. Inquire Payment Status The Payment Handler calls this API function for Consumer initiated inquiry processing. It differs from the previous "Inquire Process State" API function by the optional inclusion of payment scheme specific data. The response may encapsulate further details about the payment transaction. Input Parameters o Payment Handler Payment Identifier o Wallet Identifier and/or Pass Phrase o (Payment Scheme) Packaged Content - copied from the Inquiry Request Block's Payment Scheme Component XML definition: <!ELEMENT InquirePaymentStatus (PaySchemePackagedContent*) > <!ATTLIST InquirePaymentStatus PaymentHandlerPayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o Current Process State o Completion CodeHans, et al. Informational [Page 98]
RFC 3867 Payment API for IOTP November 2004 o Status Description and its language annotation o (Payment Scheme) Packaged Content - intended for insertion in the Payment Scheme Component of the Inquiry Response Block XML definition: <!ELEMENT InquirePaymentStatusResponse (PaySchemePackagedContent*) > <!ATTLIST InquirePaymentStatusResponse PaymentHandlerPayId CDATA #REQUIRED ProcessState (NotYetStarted | InProgress | Suspended | CompletedOk | Failed | ProcessError) #REQUIRED CompletionCode NMTOKEN #IMPLIED xml:lang NMTOKEN #IMPLIED StatusDesc CDATA #IMPLIED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.6. Other API Calls4.6.1. Manage Payment Software The following API function notifies the IOTP Payment Bridge about the intended registration, modification, or deletion of a payment instrument. The actual processing is up to the IOTP Payment Bridge. This API request may also be used to activate the IOTP Payment Bridge (and the corresponding Existing Payment Software) for general administration purposes. Input Parameters o Brand Identifier o Protocol Identifier o Any action code: o New - add new payment method / instrument o Update - change the payment method's / instrument's data o Delete - delete a payment method / instrument o Wallet Identifier and/or Pass Phrase o (Brand) Packaged Content - further payment brand description o (Pay Protocol) Packaged Content - further payment protocol descriptionHans, et al. Informational [Page 99]
RFC 3867 Payment API for IOTP November 2004 o (Protocol Amount) Packaged Content - further payment protocol description If the Action attribute is set, the Brand and Protocol Identifier have to also be set. The IOTP Payment Bridge has to provide the required user dialogs and selection mechanisms. E.g., updates and deletions may require the selection of the payment instrument. A new wallet might be silently generated on the supplement of a new Wallet Identifier or after an additional end user acknowledge. The IOTP Application Core should not provide any pass phrases for new wallets. Instead, the IOTP Payment Bridge has to request and verify them, which may return their value to the IOTP Application Core in plain text. In addition, the IOTP Payment Bridge returns the supported authentication algorithms when a new brand and protocol pair has been registered. If the "Action" attribute is omitted, the IOTP Payment Bridge which is responsible for the Existing Payment Software pops up in a general interactive mode. XML definition: <!ELEMENT ManagePaymentSoftware (BrandPackagedContent*, ProtocolAmountPackagedContent*, PayProtocolPackagedContent*) > <!ATTLIST ManagePaymentSoftware BrandId CDATA #IMPLIED ProtocolId CDATA #IMPLIED Action (New | Update | Delete) #IMPLIED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters o An action code: o New - added new wallet o Update - changed wallet's configuration o Delete - removed a wallet o Wallet Identifier and/or Pass Phrase The IOTP Payment Bridge does not return any information about the set of registered payment instruments because these data items are dynamically inferred during the brand selection process at the beginning of each IOTP transaction. However, the IOTP Application Core has to be notified about new wallets and should be notified about updated and removed wallets (identifier). Alternatively,Hans, et al. Informational [Page 100]
RFC 3867 Payment API for IOTP November 2004 removed wallets can be implicitly detected during the next brand selection phase. Updated wallets do no affect the processing of the IOTP Application Core. The IOTP Payment Bridge should only support the addition of at most one wallet because it is not able to report multiple additions at once back to the IOTP Application Core. XML definition: <!ELEMENT ManagePaymentSoftwareResponse EMPTY > <!ATTLIST ManagePaymentSoftwareResponse Action (New | Update | Delete) #IMPLIED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED AuthNames NMTOKENS #REQUIRED > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.5. Call Back Function This API function, called by the IOTP Payment Bridge, is used to provide information for Consumer or Payment Handler notification about the progress of the payment transaction. Its use is illustrated in the diagram below. *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* IOTP Application ----calls---- | Core | | display | | v to <---------- Call Back <--calls--- Payment user | | Software ---------------- *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* Figure 9. Call Back Function Whenever this function is called, the content of the status description should be made available to the user. For example on a status bar, a pop up window, etc. A reference to the Call Back function is passed as an input parameter to the "Start Payment X" and "Resume Payment X" API function. Afterwards, this function might be called whenever the status changes or progress needs to be reported.Hans, et al. Informational [Page 101]
RFC 3867 Payment API for IOTP November 2004 Input Parameters o the software identifier of the caller o Party's Payment Identifier o Process State and Percent Complete o Completion Code o Status Description and its language annotation, text which provides information about the progress of the call. It should be displayed or made available to, for example, the Consumer. Examples of Status Description could be: o "Paying 12.30 USD to XYZ Inc" o "Payment completed" o "Payment aborted" The valid languages are announced in the Call Back Language List attribute in "Start Payment X" and "Resume Payment X" API function calls. XML definition: <!ELEMENT CallBack EMPTY > <!ATTLIST CallBack ContentSoftwareID CDATA #IMPLIED PayId CDATA #REQUIRED ProcessState (NotYetStarted | InProgress | Suspended | CompletedOk | Failed | ProcessError) #IMPLIED PercentComplete CDATA #IMPLIED CompletionCode NMTOKEN #IMPLIED xml:lang NMTOKEN #IMPLIED StatusDesc CDATA #IMPLIED > Output Parameters XML definition: <!ELEMENT CallBackResponse EMPTY > <!ATTLIST CallBackResponse <!-- see below --> > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.Hans, et al. Informational [Page 102]
RFC 3867 Payment API for IOTP November 2004 Basically, the call back function accepts all input arguments or rejects the whole request. It may even accept malformed requests. Some payment schemes may support or require that the Consumer might be able to cancel the payment at any time. The Call Back function can be used to facilitate this by returning the cancellation request on the next call (using the Business Error Code and Completion Code "ConsCancelled"). Vice versa the Payment Handler's Application Core might use the similar mechanism to signal its IOTP Payment Bridges any exceptional need for a fast shutdown. These IOTP Payment Bridges may initiate the appropriate steps for terminating/cancelling all pending payment transactions. Note that the "Change Process State" API function provides the second mechanism for such kind of notification. Therefore, the IOTP Payment Bridge or Existing Payment Software may ignore the details of the "Call Back" response.6. Security Consideration The IOTP Payment APIs only supports security using pass phrase to access to payment Wallet. These can be protected over TLS, which provides stronger security at the transport layer, but implementations are out the scope of this document. See also security consideration section of [IOTP].7. References7.1. Normative References [IOTP] Burdett, D., "Internet Open Trading Protocol - IOTP version 1.0",RFC 2801, April 2000. [ISO4217] ISO 4217: Codes for the Representation of Currencies. Available from ANSI or ISO. [URL] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource Locators (URL)",RFC 1738, December 1994. [UTC] Universal Time Coordinated. A method of defining time absolutely relative to Greenwich Mean Time (GMT). Typically of the form: "CCYY-MM- DDTHH:MM:SS.sssZ+n" where the "+n" defines the number of hours from GMT. See ISO DIS8601.Hans, et al. Informational [Page 103]
RFC 3867 Payment API for IOTP November 2004 [XML] Extensible Mark Up Language (XML) 1.0 (Third Edition). A W3C recommendation. Seehttp://www.w3.org/TR/REC-xml [XML-NS] Namespaces in XML Recommendation. T. Bray, D. Hollander, A. Layman. Janaury 1999.http://www.w3.org/TR/REC-xml-names [XSLT] Extensible Style Language Transformations 1.0, November 1999, Seehttp://www.w3.org/TR/xslt7.2. Informative References [IOTPBOOK] D. Burdett, D.E. Eastlake III, and M. Goncalves, Internet Open Trading Protocol, McGraw-Hill, 2000. ISBN 0-07- 135501-4. [SET] SET Secure Electronic Transaction(TM) , Version 1.0, May 31, 1997 Book 1: Business Description Book 2: Programmer's Guide Book 3: Formal Protocol Definition [SET/IOTP] Kawatsura, Y., "Secure Electronic Transaction (SET) Supplement for the v1.0 Internet Open Trading Protocol (IOTP)",RFC 3538, June 2003. [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",RFC 2246, January 1999.Hans, et al. Informational [Page 104]
RFC 3867 Payment API for IOTP November 2004Acknowledgement The contributions of Werner Hans of Atos Origin are gratefully acknowledged.Authors' Addresses Hans-Bernhard Beykirch EMail: hbbeykirch@web.de Yoshiaki Kawatsura Hitachi, Ltd. 890 Kashimada Saiwai-ku Kawasaki-shi Kanagawa, Japan 212-8567 EMail: ykawatsu@itg.hitachi.co.jp Masaaki Hiroya Technoinfo Service, Inc. 333-2-718 Uchikoshi-machi Hachioji-shi Tokyo 192-0911 JAPAN EMail: hiroya@st.rim.or.jpHans, et al. Informational [Page 105]
RFC 3867 Payment API for IOTP November 2004Full Copyright Statement Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained inBCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found inBCP 78 andBCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository athttp://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf- ipr@ietf.org.Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society.Hans, et al. Informational [Page 106]
[8]ページ先頭