idnits 2.17.1 draft-ietf-trade-iotp-v1.0-papi-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** Bad filename characters: the document name given in the document, 'draft-ietf-trade-iotp-v1.0-papi-02', contains other characters than digits, lowercase letters and dash. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1695 has weird spacing: '...n error that ...' == Line 1733 has weird spacing: '...ding on the n...' == Line 1744 has weird spacing: '...Content cf. T...' == Line 2778 has weird spacing: '...ontents must ...' == Line 4509 has weird spacing: '...nent of the I...' == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- The document date (September 2000) is 8621 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'PS1' is mentioned on line 1316, but not defined == Missing Reference: 'PSn' is mentioned on line 1113, but not defined == Missing Reference: 'PS2' is mentioned on line 1317, but not defined == Unused Reference: 'IOTPBOOK' is defined on line 4792, but no explicit reference was found in the text == Unused Reference: 'HTML' is defined on line 4795, but no explicit reference was found in the text == Unused Reference: 'HTTP' is defined on line 4800, but no explicit reference was found in the text == Unused Reference: 'ISO4217' is defined on line 4806, but no explicit reference was found in the text == Unused Reference: 'MIME' is defined on line 4810, but no explicit reference was found in the text == Unused Reference: 'SET' is defined on line 4816, but no explicit reference was found in the text == Unused Reference: 'UTC' is defined on line 4826, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 2801 (ref. 'IOTP') -- Possible downref: Non-RFC (?) normative reference: ref. 'IOTPBOOK' ** Obsolete normative reference: RFC 1866 (ref. 'HTML') (Obsoleted by RFC 2854) ** Obsolete normative reference: RFC 2068 (ref. 'HTTP') (Obsoleted by RFC 2616) -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO4217' ** Obsolete normative reference: RFC 1738 (ref. 'URL') (Obsoleted by RFC 4248, RFC 4266) -- Possible downref: Non-RFC (?) normative reference: ref. 'SET' -- Possible downref: Non-RFC (?) normative reference: ref. 'UTC' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSLT' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML-NS' Summary: 11 errors (**), 0 flaws (~~), 18 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 TRADE Working Group Werner Hans 2 INTERNET-DRAFT Hans-Bernhard.Beykirch 3 SIZ 4 Masaaki Hiroya 5 Yoshiaki Kawatsura 6 Hitachi 7 Expires: March 2001 September 2000 9 Payment API for v1.0 Internet Open Trading Protocol (IOTP) 10 ------- --- --- ---- -------- ---- ------- -------- ------ 11 13 Status of this Memo 15 This document is intended to become an Informational RFC and will be 16 in full conformance with all provisions of Section 10 of RFC2026. 18 This document is an Internet-Draft and is in full conformance with 19 all provisions of Section 10 of RFC 2026. Internet-Drafts are 20 working documents of the Internet Engineering Task Force (IETF), its 21 areas, and its working groups. Note that other groups may also 22 distribute working documents as Internet-Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet- Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 Distribution of this document is unlimited. Please send comments to 36 the TRADE working group at , which may 37 be joined by sending a message with subject "subscribe" to . 40 Discussions of the TRADE working group are archived at 41 http://www.elistx.com/archives/ietf-trade. 43 Abstract 45 The Internet Open Trading Protocol provides a data exchange format 46 for trading purposes while integrating existing pure payment 47 protocols seamlessly. This motivates the multiple layered system 48 architecture which consists of at least some generic IOTP application 49 core and multiple specific payment modules. 51 This document addresses the common interface between the IOTP 52 application core and the payment modules, enabling the 53 interoperability between these kinds of modules. Furthermore, such an 54 interface provides the foundations for a plug-in- mechanism in actual 55 implementations of IOTP application cores. 57 Such interfaces exist at the Consumers', the Merchants' and the 58 Payment Handlers' installations connecting the IOTP application core 59 and the payment software components/legacy systems. 61 Intended Readership 63 Software and hardware developers, development analysts, and users of 64 payment protocols. 66 Copyright 68 Copyright (C) The Internet Society 2000. 70 Table of Contents 72 Status of this Memo........................................1 73 Abstract...................................................1 74 Intended Readership........................................2 75 Copyright..................................................2 77 Table of Contents..........................................3 78 1. Introduction............................................5 79 1.1 General payment phases................................6 80 1.2 Assumptions...........................................7 81 2. Message Flow..........................................13 82 2.1 Authentication Documentation Exchange................16 83 2.2 Brand Compilation....................................18 84 2.3 Brand Selection......................................21 85 2.4 Successful Payment...................................24 86 2.5 Payment Inquiry......................................28 87 2.6 Abnormal Transaction Processing......................30 88 2.6.1 Failures and Cancellations.........................30 89 2.6.2 Resumption.........................................32 90 2.7 IOTP Wallet Initialization...........................33 91 2.8 Payment Software Management..........................33 92 3. Mutuality.............................................34 93 3.1 Error Codes..........................................37 94 3.2 Attributes and Elements..............................47 95 3.3 Process States........................................59 96 3.3.1 Merchant............................................59 97 3.3.2 Consumer............................................61 98 3.3.3 Payment Handler.....................................63 99 4. Payment API Calls.....................................64 100 4.1 Brand Compilation Related API Calls..................64 101 4.1.1 Find Accepted Payment Brand........................64 102 4.1.2 Find Accepted Payment Protocol.....................65 103 4.1.3 Get Payment Initialization Data....................67 104 4.1.4 Inquire Authentication Challenge...................69 105 4.1.5 Authenticate.......................................71 106 4.1.6 Check Authentication Response......................71 107 4.2 Brand Selection Related API Calls....................73 108 4.2.1 Find Payment Instrument............................73 109 4.2.2 Check Payment Possibility..........................75 110 4.3 Payment Transaction Related API calls................77 111 4.3.1 Start Payment Consumer.............................77 112 4.3.2 Start Payment Payment Handler......................79 113 4.3.3 Resume Payment Consumer............................81 114 4.3.4 Resume Payment Payment Handler.....................82 115 4.3.5 Continue Process ..................................83 116 4.3.6 Change Process State...............................84 117 4.4 General Inquiry API Calls............................86 118 4.4.1 Remove Payment Log.................................86 119 4.4.2 Payment Instrument Inquiry.........................87 120 4.4.3 Inquire Pending Payment............................89 121 4.5 Payment Related Inquiry API Calls....................89 122 4.5.1 Check Payment Receipt..............................90 123 4.5.2 Expand Payment Receipt.............................91 124 4.5.3 Inquire Process State..............................92 125 4.5.4 Start Payment Inquiry..............................94 126 4.5.5 Inquire Payment Status.............................94 127 4.6 Other API Calls......................................95 128 4.6.1 Manage Payment Software............................95 129 5. Call Back Function.....................................97 130 6. Security Consideration.................................99 132 Full Copyright Statement.................................100 133 References...............................................100 134 Author's Address.........................................101 135 Expiration and File Name.................................102 137 1. Introduction 139 Common network technologies are based on standardized and established 140 Internet technologies. The Internet technologies provide mechanisms 141 and tools for presentation, application development, network 142 infrastructure, security, and basic data exchange. 144 Due to the presence of already installed trading roles' systems with 145 their own interfaces (Internet shop, order management, payment, 146 billing, and delivery management systems, or financial institute's 147 legacy systems), IOTP has been limited to the common external 148 interface over the Internet. However, some of these internal 149 interfaces might be also standardized for better integration of IOTP 150 aware components with of the existing infrastructure and its cost 151 effective reuse. 153 The typical Payment Handlers, i.e., financial institutes or near- 154 bank organizations, as well as Merchants require an IOTP aware 155 application that easily fits into their existing financial 156 infrastructure. The Payment Handler might even insist on the reuse of 157 special in-house solutions for some subtasks of the IOTP aware 158 application, e.g., reflecting their cryptography modules, gateway 159 interfaces, or physical environment. Therefore, their IOTP aware 160 implementation really requires such clear internal interfaces. 162 More important, Consumers demand modularization and clear internal 163 interfaces: Their IOTP application aims at the support of multiple 164 payment methods. Consumers prefer the flexible use of different 165 seamless integrating payment methods within one trading application 166 with nearly identical behavior and user interface. The existence of a 167 well-defined interface enables payment software developers to bolt on 168 their components to other developer's general IOTP Application Core. 170 Initially, this consideration leads to the two-level layered view of 171 the IOTP software for each role, consisting of 173 o some generic IOTP system component, the so-called IOTP application 174 core - providing IOTP based gateway services and generic business 175 logic and 177 o the trading roles' specific backend systems implementing the 178 specific trading transaction types' functionality. 180 In order to isolate the changes on the infrastructure, the IOTP 181 trading application has been three-layered: 183 o the IOTP Application Core processes the generic parts of the IOTP 184 transaction and holds the connection to the Internet, 186 o the Existing Legacy System or Existing Payment Software which 187 processes the actual transaction type, and particular payment 188 transaction, and 190 o the IOTP Middleware or IOTP Payment Bridge which glues the other 191 two possibly incompatible components. It brokers between the specific 192 interface of the Existing Legacy System and the standardized 193 interfaces of the IOTP Application Core. 195 As IOTP extends payment schemes to a trading scheme, primarily, this 196 document focuses on payment modules, i.e. the interface between the 197 IOTP Payment Bridge and the IOTP Application Core. It provides a 198 standard method for exchanging payment protocol messages between the 199 parties involved in a payment. But, it does not specify any interface 200 for order or delivery processing. 202 Such a Payment Application Programmers Interface (API) must suit for 203 a broad range of payment methods: (1) software based like Credit Card 204 SET or CyberCoin, (2) chip card based like Mondex or GeldKarte, and 205 (3) mimicries of typical and traditional payment methods like money 206 transfer, direct debit, deposit, withdrawal, money exchange and value 207 points. It should support both payments with explicit consumer 208 acknowledge and automatic repeated payments, which have been consumer 209 approved in advance. 211 The following discussion focuses on the Consumer's point of view and 212 uses the associated terminology. When switching to Merchants' or 213 Delivery Handlers' IOTP aware applications, the payment related 214 components should be implicitly renamed by Existing Legacy Systems to 215 the IOTP Middleware. 217 The next two sub-sections describe the general payment scenario and 218 several assumptions about the coarsely sketched software components. 220 Chapter 2 illustrates the payment transaction progress and message 221 flow of different kinds of transaction behavior. Chapters 3 to 4 222 provide the details of the API functions and Chapter 5 elaborates the 223 call back interface. 225 1.1 General payment phases 227 The following table sketches the four logical steps of many payment 228 schemes. The preceding agreements about the goods, payment method, 229 purchase amount, or delivery rules are omitted. 231 Payment State Party Example Behavior 233 Mutual Payment Handler Generation of identification 234 Authentication request, solvency request, or 235 and Init- some nonce 236 ialization Consumer Responses to the requests and 237 generation of the own nonce 239 Authorization Payment Handler Generation of the authorization 240 request (for consumer) 241 Consumer Agreement to payment (by 242 reservation of the Consumer's 243 e-money) 244 Payment Handler Acceptance or rejection of the 245 agreement (consumer's 246 authorization response), 247 generation of the authorization 248 request (for issuer/acquirer), 249 and processing of its response 251 Capture Generation of the capture 252 request (for issuer/acquirer) 253 Consumer Is charged 254 Payment Handler Acceptance or rejection of the 255 e-money, close of the payment 256 transaction 258 Reversal On rejection (online/delayed): 259 generation of the reversal data 260 Consumer Receipt of the refund 262 However, some payment schemes 264 o limit themselves to one-sided authentication, 265 o perform offline authorization without any referral to any 266 issuer/acquirer, 267 o apply capture processing in batch mode, or 268 o do not distinguish between authorization and capture, 269 o lack an inbound mechanism for reversals or implement a limited 270 variant. 272 This model applies not only to payments at the typical points of 273 sales but extends to refunds, deposits, withdrawals, electronic 274 cheques, direct debits, and money transfers. 276 1.2 Assumptions 278 In outline, the IOTP Payment Bridge processes some input sequence of 279 payment protocol messages being forwarded by the IOTP Application 280 Core. It (1) disassembles the messages, (2) maps them onto the 281 formats of the Existing Payment Software, (3) assembles its 282 responses, and (4) returns another sequence of payment protocol 283 messages that is mostly intended for transparent transmission by the 284 IOTP Application Core to some IOTP aware remote party. Normally, this 285 process continues between the two parties until the Payment Handler's 286 Payment API signals the payment termination. Exceptionally, each 287 system component may signal failures. 289 The relationship between the aforementioned components is illustrated 290 in the following figure. These components might be related to each 291 other in a flexible n-to-m-manner: 293 o One IOTP Application Core may manage multiple IOTP Payment 294 Bridges and the latter might be shared between multiple IOTP 295 Application Cores. 296 o Each Payment Bridge may manage multiple Existing Payment 297 Software modules and the latter might be shared between multiple 298 Payment Bridges. 299 o Each Existing Payment Software may manage multiple payment 300 schemes (e.g. SET) and the latter might be supported by multiple 301 Existing Payment Software modules. 302 o Each payment scheme may support multiple payment instruments 303 (e.g. particular card) or methods (e.g. Visa via SET) and the 304 latter might be shared by multiple Existing Payment Software 305 Components. 307 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 308 IOTP client (consumer) <---------------> IOTP server (merchant) 309 ( contains Internet ( containes 310 IOTP Application Core) IOTP Application Core) 311 ^ ^ 312 | IOTP Payment | IOTP Payment 313 | API | API 314 v v 315 IOTP Payment Bridge IOTP Payment Bridge 316 ^ ^ 317 | Existing Payment APIs, e.g., | 318 | SET, Mondex, etc. | 319 v v 320 Existing Payment Software Existing Payment Software 321 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 322 Figure 1: Relationship of the Components 324 The Payment API considers the following transaction types of Baseline 325 IOTP [IOTP]: 327 o Baseline Purchase, 328 o Baseline Refund, 329 o Baseline Value Exchange, 330 o Baseline Withdrawal, and 331 o Baseline (Payment) Inquiry. 333 First, the authors' vision of the IOTP aware application's and its 334 main components' capabilities are clarified: On the one hand, the 335 Payment API should be quite powerful and flexible for sufficient 336 connection of the generic and specific components. On the other hand, 337 the Payment API should not be overloaded with nice-to-haves being 338 unsupported by Existing Payment Software. 340 Despite the strong similarities on the processing of successful 341 payments, failure resolution and inquiry capabilities differ 342 extremely among different payment schemes. These aspects may even 343 vary between different payment instrument using the same payment 344 schemes. Eventually, the specific requirements of Consumers, 345 Merchants and Payment Handlers add variance and complexity. 346 Therefore, it is envisioned that the IOTP Application Core provides 347 only very basic inquiry mechanisms while complex and payment scheme 348 specific inquiries, failure analysis, and failure resolution are 349 fully deferred to the actual Existing Payment Software - including 350 the user interface. 352 The IOTP Application Core processes payments transparently, i.e., it 353 forwards the wrapped payment scheme specific messages to the 354 associated IOTP Payment Bridge/Existing Payment Software. The 355 Existing Payment Software might even use these messages for inbound 356 failure resolution. It reports only the final payment status to the 357 IOTP Application Core or some intermediate - might be also final - 358 status on abnormal interruption. 360 The IOTP Application Core implements the generic and payment scheme 361 independent part of the IOTP transaction processing and provides the 362 suitable user interface. Focusing on payment related tasks, it 364 o manages the registered IOTP Payment Bridges and provides a 365 mechanism for their registration - the latter is omitted by this 366 document. 368 o assumes that any IOTP Payment Bridge is a passive component, i.e., 369 it strictly awaits input data and generates one response to each 370 request, 372 o supports the payment negotiation (Consumer: selection of the actual 373 payment instrument or method; Merchant: selection of the payment 374 methods being offered to the Consumer) preceding the payment request, 376 o requests additional payment specific support from the Existing 377 Payment Software via the selected and registered the IOTP Payment 378 Bridge, 380 o initializes and terminates the Existing Payment Software via the 381 IOTP Payment Bridge, 382 o inquires authentication data (for subsequent request or response) 383 from the Existing Payment Software, specific authentication component 384 - omitted in this document - or Consumer (by a suitable user 385 interface), 387 o supervises the online transaction process and traces its progress, 389 o stores the transaction data being exchanged over the IOTP wire - 390 payment scheme specific data is handled transparently, 392 o relates each payment transaction with multiple payment parameters 393 (IOTP Transaction Identifier, Trading Protocol Options, Payment 394 Instrument/Method, Offer Response, IOTP Payment Bridge, and Wallet 395 Identifier, associated remote Parties). The relation might be lowered 396 to the party's Payment Identifier, IOTP Payment Bridge, Wallet 397 Identifier, and the remote parties when the actual payment 398 transaction has been successfully started. 400 o implements a payment transaction progress indicator, 402 o enables the inquiry of pending and completed payment transactions, 404 o implements generic dialogs, e.g., brand selection, payment 405 acknowledge, payment suspension / cancellation, receipt 406 visualization, basic transaction inquiry, balance inquiry, or receipt 407 validation, 409 o defers payment specific processing, supervision, validation, and 410 error resolution to the Existing Payment Software. It is expected, 411 that the Existing Payment Software tries to resolve many errors first 412 by the extended exchange of Payment Exchange messages. The most 413 significant and visible failures arise from sudden unavailability or 414 lapses of the local or opposing payment component. 416 o supports the invocation of any Existing Payment Software in an 417 interactive mode, which might be used (1) for the payment scheme 418 specific post-processing of a (set of) payment transactions, (2) for 419 the analysis of a payment instrument, (3) for the registration of a 420 new payment instrument/scheme, or (4) re-configuration of a payment 421 instrument/scheme. 423 o exports call back functions for use by the IOTP Payment Bridge or 424 Existing Payment Software for progress indication. 426 In addition, the IOTP Application Core 428 o manages the IOTP message components and IOTP message blocks 429 exchanged during the transaction which may be referenced and accessed 430 during the processing of subsequent messages, e.g., for signature 431 verification. In particular, it stores named Packaged Content 432 elements exchanged during payments. 434 o manages several kinds of identifiers, i.e., transaction, message, 435 component, and block identifiers, 437 o implements a message caching mechanism, 439 o detects time-outs at the protocol and API level reflecting the 440 communication with both the IOTP aware remote party and the Payment 441 API aware local periphery, e.g., chip card (reader) may raise time- 442 outs. 444 However, the IOTP Payment Bridge and Existing Payment Software do not 445 have to rely on all of these IOTP Application Core's capabilities. 446 E.g., some Consumer's Existing Payment Software may refuse the 447 disclosure of specific payment instruments at brand selection time 448 and may delay this selection to the "Check Payment Possibility" 449 invocation using its own user interface. 451 The IOTP Payment Bridge's capabilities do not only deal with actual 452 payments between the Consumer and the Payment Handler but extend to 453 the following: 455 o translation and (dis)assemblage of messages between the formats of 456 the IOTP Payment API and those of the Existing Payment Software. 457 Payment API requests and response are strictly 1-to-1 related. 459 o Consumer's payment instrument selection by the means of an 460 unsecured/public export of the relationship of payment brands, 461 payment protocols, and payment instruments (identifiers). Generally, 462 this includes not just the brand (Mondex, GeldKarte, etc.) but also 463 which specific instance of the instrument and currency to use (e.g. 464 which specific Mondex card and which currency of all those 465 available). 467 However, some Existing Payment Software may defer the selection of 468 the payment instrument to the actual payment carrying-out or it may 469 even lack any management of payment instruments. E.g., chip card 470 based payment methods may offer - Point of Sale like - implicit 471 selection of the payment instrument by simple insertion of the chip 472 card into the chip card reader or it interrogates the inserted card 473 and requests an acknowledge (or selection) of the detected payment 474 instrument(s). 476 o payment progress checks, e.g., is there enough funds available to 477 carry out the purchase, or enough funds left for the refund, 479 o IOTP Payment Receipt checks which might be performed over its 480 Packaged Content or by other means. 482 o recoding of payment scheme specific receipts into a format which 483 can be displayed to the user or printed, 485 o cancellation of payment, even though it is not complete, 487 o suspension and resumption of payment transactions. Two kinds of 488 failures the Existing Payment Software might deal with are (1) the 489 time-out of the network connection and (2) lack of funds. For 490 resolution, the IOTP Application Core may try the suspension with a 491 view to later possible resumption. 493 o recording the payment progress and status on a database. E.g., 494 information about pending payments might be used to assist their 495 continuation when the next payment protocol message is received. 497 o payment transaction status inquiry, so that the inquirer - IOTP 498 Application Core or User - can determine the appropriate next step. 500 o balance inquiry or transaction history, e.g. consumers may 501 interrogate their chip card based payment instrument or remotely 502 administer some account in advance of a payment transaction 503 acknowledge, 505 o inquiry on abnormal interrupted payment transactions, which might 506 be used by the IOTP Application Core to resolve these pending 507 transactions at startup (after power failure). 509 o payment progress indication. This could be used to inform the end 510 user of details on what is happening with the payment. 512 o payment method specific authentication methods. 514 Existing Payment Software may not provide full support of these 515 capabilities. E.g., some payment schemes may not support or even 516 prevent the explicit transaction cancellation at arbitrary phases of 517 the payment process. In this case, the IOTP Payment Bridge has to 518 implement at least skeletons that signal such lack of support by the 519 use of specific error codes (see below). 521 The Existing Payment Software's capabilities vary extremely. It 523 o supports payment scheme specific processing, supervision, 524 validation, and error resolution. It is expected, that many errors 525 are tried to be resolved first by the extended exchange of Payment 526 Exchange messages. 528 o provides hints for out-of-band failure resolution on failed inbound 529 resolution - inbound resolution is invisible to the IOTP Application 530 Core. 532 o may implement arbitrary transaction data management and inquiry 533 mechanisms ranging from no transaction recording, last transaction 534 recording, chip card deferred transaction recording, simple 535 transaction history to sophisticated persistent data management with 536 flexible user inquiry capabilities. The latter is required by Payment 537 Handlers for easy and cost effective failure resolution. 539 o implements the payment scheme specific dialog boxes. 541 Even the generic dialog boxes of the IOTP Application Core might be 542 unsuitable: Particular (business or scheme) rules may require some 543 dedicated appearance / structure / content or the dialog boxes, may 544 prohibit the unsecured export of payment instruments, or may 545 prescribe the pass phrase input under its own control. 547 2. Message Flow 549 The following lists all functions of the IOTP Payment API: 551 o Brand Compilation Related API Functions 553 "Find Accepted Payment Brand" identifies the accepted payment brands 554 for any indicated currency amount. 556 "Find Accepted Payment Protocol" identifies the accepted payment 557 protocols for any indicated currency amount (and brand) and returns 558 payment scheme specific packaged content for brand selection 559 purposes. 561 This function might be used in conjunction with the aforementioned 562 function or called without any brand identifier. 564 "Get Payment Initialization Data" returns additional payment scheme 565 specific packaged content for payment processing by the payment 566 handler. 568 "Inquire Authentication Challenge" returns the payment scheme 569 specific authentication challenge value. 571 "Check Authentication Response" verifies the returned payment scheme 572 specific authentication response value. 574 "Change Process State" is used (here only) for abnormal termination. 575 (cf. Payment Processing Related API Functions). 577 o Brand Selection Related API Functions 579 "Find Payment Instrument" identifies which instances of a payment 580 instrument of a particular payment brand are available for use in a 581 payment. 583 "Check Payment Possibility" checks whether a specific payment 584 instrument is able to perform a payment. 586 "Authenticate" forwards any payment scheme specific authentication 587 data to the IOTP Payment Bridge for processing. 589 "Change Process State" is used (here only) for abnormal termination. 590 (cf. Payment Processing Related API Functions). 592 o Payment Processing Related API Functions 594 "Start or Resume Payment Consumer/Payment Handler" initiate or resume 595 a payment transaction. There exist specific API functions for the two 596 trading roles Consumer and Payment Handler. 598 "Continue Process" forwards payment scheme specific data to the 599 Existing Payment Software and returns more payment scheme specific 600 data for transmission to the counter party. 602 "Change Process State" changes the current status of payment 603 transactions. Typically, this call is used for successful/- less 604 termination or suspension. 606 o General Inquiry API Functions 608 "Remove Payment Log" notifies the IOTP Payment Bridge that a 609 particular entry has been removed from the Payment Log of the IOTP 610 Application Core. 612 "Payment Instrument Inquiry" retrieves the properties of Payment 613 Instruments. 615 "Inquire Pending Payment" reports any abnormal interrupted payment 616 transaction known by the IOTP Payment Bridge. 618 Payment Processing Related Inquiry API Functions 620 "Check Payment Receipt" checks the consistency and validity of IOTP 621 Payment Receipts, received from the Payment Handler or returned by 622 "Inquire Process State" API calls. Typically, this function is called 623 by the Consumer during the final processing of payment transactions. 624 Nevertheless, this check might be advantageous both for Consumers and 625 Payment Handlers on failure resolution. 627 "Expand Payment Receipt" expands the Packaged Content of IOTP Payment 628 Receipts as well as payment scheme specific payment receipts into a 629 form which can be used for display or printing purposes. 631 "Inquire Process State" responds with the payment state and the IOTP 632 Payment Receipt Component. Normally, this function is called by the 633 Payment Handler for final processing of the payment transaction. 635 "Start Payment Inquiry" prepares the remote inquiry of the payment 636 transaction status and responds with payment scheme specific data 637 that might be needed by the Payment Handler for the Consumer 638 initiated inquiry processing. 640 "Inquire Payment Status" is called by the Payment Handler on Consumer 641 initiated inquiry requests. This function returns the payment scheme 642 specific content of the Inquiry Response Block. 644 "Continue Process" and "Change Process State" (cf. Payment Processing 645 Related API Calls) 647 o Other API Functions 649 "Manage Payment Software" enables the immediate activation of the 650 Existing Payment Software. Further user input is under control of the 651 Existing Payment Software. 653 "Call Back" provides a general interface for the visualization of 654 transaction progress by the IOTP Application Core. 656 The following table shows which API functions must (+), should (#), 657 or might (?) be implemented by which Trading Roles. 659 API function Consumer Payment Handler Merchant 661 Find Accepted Payment Brand + 662 Find Accepted Payment Protocol # 663 Find Payment Instrument + 665 Get Payment Initialization Data + 666 Check Payment Possibility + 668 Start Payment Consumer + 669 Start Payment Payment Handler + 670 Resume Payment Consumer # 671 Resume Payment Payment Handler # 673 Continue Process + + 674 Inquire Process State + + ? 675 Change Process State + + ? 676 Check Payment Receipt + ? 677 Expand Payment Receipt # ? 679 Remove Payment Log ? ? ? 680 Inquire Authentication Challenge ? 681 Authenticate + 682 Check Authentication Response ? 684 Payment Instrument Inquiry ? 685 Inquire Pending Payment # # 686 Start Payment Inquiry ? 687 Inquire Payment Status ? 689 Manage Payment Software # ? ? 691 Call Back # 692 Table 1: Requirements on API Functions by the Trading Roles 694 The next sections sketch the relationships and the dependencies 695 between the API functions. They provide the informal description of 696 the progress alternatives and depict the communication and 697 synchronization between the general IOTP Application Core and the 698 payment scheme specific modules. 700 2.1 Authentication Documentation Exchange 702 This section describes how the functions in this document are used 703 together to process authentication. 705 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 706 Authenticator Inquire Authentication Challenge(Alg1*) -> IPB 707 Inq. Auth. Challenge Response(Alg1,Ch1) <- IPB 708 . . . 709 Inquire Authentication Challenge(Algn*) -> IPB 710 Inq. Auth. Challenge Response(Algn,Chn) <- IPB 711 Create and transmit Authentication Request Block 712 Authenticatee Authenticate(Alg1, Ch1) -> IPB 713 AuthenticateResponse(...) <- IPB 714 . . . 715 Authenticate(Algm, Chm) -> IPB 716 AuthenticateResponse(Res) <- IPB 717 Create and transmit Authentication Response Block 718 Authenticator Check Authentication Response(Algm,Chm,Res)->IPB 719 Check Auth. Response() <-IPB 720 Create and transmit Authentication Status Block 721 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 722 Figure 12 Authentication Message Flows 724 1. (Authenticator Process) None, one or multiple IOTP Payment Bridges 725 (IPB) are requested for one or multiple authentication challenge 726 values ("Inquire Authentication Challenge"). Each value is 727 encapsulated in an IOTP Authentication Request Component. In 728 addition, the IOTP Application Core may add payment scheme 729 independent authentication methods. All of them form the final IOTP 730 Authentication Request Block, which describes the set of 731 authentication methods being supported by the authenticator and from 732 which the authenticatee has to choose one method. 734 Note that the interface of the API function is limited to the 735 response of exactly one algorithm per call. If the IOTP Application 736 Core provides a choice of algorithms for input, this choice should be 737 reduced successively by the returned algorithm ({Alg(i+1)*} is subset 738 of {Algi*}). 740 During the registration of new Payment Instruments, the IOTP Payment 741 Bridge notifies the IOTP Application Core about the supported 742 authentication algorithms. 744 2. On presence of an IOTP Authentication Block within the received 745 IOTP message, the Authenticatee's IOTP Application Core checks 746 whether the IOTP transaction type in the current phase actually 747 supports the authentication process. 749 For each provided Authentication Request Component, the IOTP 750 Application Core analyzes the algorithms' names, the transaction 751 context, and optionally user preferences in order to determine the 752 system components which are capable to process the authentication 753 request items. Such system components might be the IOTP Application 754 Core itself or any of the registered IOTP Payment Bridges. 756 Subsequently, the IOTP Application Core requests the responses to 757 the supplied challenges from the determined system components in any 758 order. The authentication trials stop with the first successful 759 response, which is included in the IOTP Authentication Response 760 Block. 762 Alternatively, the IOTP Application might ask for a user selection. 763 This might be appropriate, if two or more authentication algorithms 764 are received that require explicit user interaction, like PIN or chip 765 card insertion. 767 The Authenticatee's organizational data is requested by an IOTP 768 Authentication Request Block without any content element. On failure, 769 the authentication (sequence) might be retried, or the whole 770 transaction might be suspended or cancelled. 772 3. (Authenticator Process) The IOTP Application Core checks the 773 presence of the IOTP Authentication Response Component in the 774 Authentication Response Block and forwards its content to the 775 generator of the associated authentication challenge for verification 776 ("Check Authentication Response"). 778 On sole organizational data request, its presence is checked. 780 Any verification must succeed in order to proceed with the 781 transaction. 783 2.2 Brand Compilation 785 The following shows how the API functions are used together so that 786 the Merchant can (1) compile the Brand List Component, (2) generate 787 the Payment Component, and (3) adjust the Order Component with 788 payment scheme specific packaged content. 790 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 791 Merchant For each registered IOTP Payment Bridge 792 | Find Accepted Payment Brand() -> IPB 793 | Find Accepted Payment Brand Response (B*) <- IPB 794 | Find Accepted Payment Protocol(B1) -> IPB 795 | Find Accepted Payment Protocol Res.(P1*) <- IPB 796 | . . . 797 | Find Accepted Payment Protocol(Bn) -> IPB 798 | Find Accepted Payment Protocol Res.(Pn*) <- IPB 799 Create one Brand List Component, ideally sharing 800 common Brand, Protocol Amount, Currency Amount, 801 and Pay Protocol Elements 802 Create Trading Protocol Options Block 803 On brand independent transactions 804 | Create Brand Selection Component, implicitly 805 | Get Payment Initialization Data(B1,P1) -> IPB 806 | Get Payment Initialization Data Res.() <- IPB 807 | Optionally 808 | | Inquire Process State() -> IPB 809 | | Inquire Process State Response(State) <- IPB 810 | Create Offer Response Block 811 Transmit newly created Block(s) 812 Consumer Consumer selects Brand (Bi)/Currency/Protocol (Pj) 813 from those that will work and generates Brand 814 Selection Component - at least logically 815 On brand dependent transaction 816 | Transmit Brand Selection Component 817 Merchant On brand dependent transaction 818 | Get Payment Initialization Data(Bi,Pj) -> IPB 819 | Get Payment Initialization Data Res.() <- IPB 820 | Optionally 821 | | Inquire Process State() -> IPB 822 | | Inquire Process State Response(State) <- IPB 823 | Create Offer Response Block 824 | Transmit newly created Block 825 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 826 Figure 3 Brand Compilation Message Flows 828 1. The Merchant's commerce server controls the shopping dialog with 829 its own mechanisms until the Consumer checks out the shopping cart 830 and indicates the payment intention. The notion shopping subsumes any 831 non-IOTP based visit of the Merchant Trading Role's (which subsumes 832 Financial Institutes) web site in order to negotiate the content of 833 the IOTP Order Component. The subsequent processing switches to the 834 IOTP based form by the activation of the Merchant's IOTP aware 835 application. 837 2. The IOTP Application Core inquires the IOTP level trading 838 parameters (Consumer's shopping identifier, payment direction, 839 initial currency amounts, discount rates, Merchant's and Delivery 840 Handler's Net Locations, Non-Payment Handler's Organisational Data, 841 initial order information, ....). 843 3. The registered IOTP Payment Bridges are inquired by the IOTP 844 Application Core about the accepted payment brands ("Find Accepted 845 Payment Brand"). Their responses provide most of the attribute values 846 for the compilation of the Brand List Component's Brand Elements. The 847 IOTP Application Core might optionally match the returned payment 848 brands with Merchant's general preferences. 850 The IOTP Application Core must provide any wallet identifiers, if 851 they are required by the IOTP Payment Bridges which signal their need 852 by specific error codes (see below). Any signaled error that could 853 not immediately solved by the IOTP Application Core should be logged 854 - this applies also to the subsequent API calls of this section. In 855 this case, the IOTP Application Core creates an IOTP Error Block 856 (hard error), transmits it to the Consumer, and terminates the 857 current transaction. 859 4. The IOTP Application Core interrogates the IOTP Payment Bridges 860 for each accepted payment brand about the supported payment protocols 861 ("Find Accepted Payment Protocol"). These responses provide the 862 remaining attribute values of the Brand Elements as well as all 863 attribute values for the compilation of the Brand List Component's 864 Protocol Amount and Pay Protocol Elements. Furthermore, the 865 organisational data about the Payment Handler is returned. The IOTP 866 Application Core might optionally match the returned payment brands 867 with Merchant's general preferences. 869 Alternatively, the IOTP Application Core might skip the calls of 870 "Find Accepted Payment Brands" (cf. Step 3) and issue the "Find 871 Accepted Payment Protocol" call without any Brand given on the input 872 parameter list. In this case, the IOTP Payment Bridge responds on the 873 latter call with the whole set of payment schemes supported w.r.t. 874 the other input parameters. 876 5. The steps 3 and 4 are repeated during IOTP Value Exchange 877 transactions - these steps are omitted in the previous figure. 879 6. The IOTP Application Core compiles the Brand List Component(s) and 880 the IOTP Trading Protocol Options Block. It is recommended that 881 "equal" items returned by IOTP Payment Bridge function calls are 882 shared due to the extensive linking capabilities within the Brand 883 List Component. However, the compilation must consider several 884 aspects in order to prevent conflicts - sharing detection might be 885 textual matching (after normalization): 887 o Packaged Content Elements contained in the Brand List Component 888 (and subsequently generated Payment and Order Components) might be 889 payment scheme specific and might depend on each other. 891 o Currently, IOTP lacks precise rules for the content of the 892 Packaged Content Element. Therefore, transaction / brand / 893 protocol / currency amount (in)dependent data might share the same 894 Packaged Content Element or might spread across multiple Packaged 895 Content Elements. 897 o The Consumer's IOTP Application Core transparently passes the 898 Packaged Content Elements to the IOTP Payment Bridges which might 899 not be able to handle payment scheme data of other payment 900 schemes, accurately. 902 The rules and mechanisms of how this could be accomplished are out 903 of the scope of this document. Furthermore, this document does not 904 define any further restriction to the IOTP specification. 906 7. The IOTP Application Core determines whether the IOTP message can 907 be enriched with an Offer Response Block. This is valid under the 908 following conditions: 910 o All payment alternatives share the attribute values and Packaged 911 Content Elements of the subsequently generated IOTP Payment and 912 Order Components. 914 o The subsequently generated data does not depend on any IOTP 915 BrandSelInfo Elements that might be reported by the consumer 916 within the TPO Selection Block in the brand dependent variant. 918 If both conditions are fulfilled, the IOTP Application Core might 919 request the remaining payment scheme specific payment initialization 920 data from the IOTP Payment Bridge ("Get Payment Initialization Data") 921 and compile the IOTP Offer Response Block. 923 Optionally, the IOTP Application Core might request the current 924 process state from the IOTP Payment Bridge and add the inferred order 925 status to the IOTP Offer Response Block. Alternatively, IOTP 926 Application might determine the order status on its own. 928 As in step 6, the rules and mechanisms of how this could be 929 accomplished are out of the scope of this document. 931 8. The IOTP Application Core compiles the IOTP TPO Message including 932 all compiled IOTP Blocks and transmits the message to the Consumer. 933 The IOTP Application Core terminates if an IOTP Offer Response Block 934 has been created. 936 9. The Consumer performs the Brand Selection Steps (cf. Section 2.3) 937 and responds with a TPO Selection Block if no IOTP Offer Response 938 Block has been received. Otherwise, the following step is skipped. 940 10. On brand dependent transactions, the IOTP Application Core 941 requests the remaining payment scheme specific payment initialization 942 data from the IOTP Payment Bridge ("Get Payment Initialization 943 Data"), compiles the IOTP Offer Response Block, transmits it to the 944 Consumer, and terminates. Like Step 7, the IOTP Application Core 945 might access the current process state of the IOTP Payment Bridge for 946 the compilation of the order status. 948 Any error during this process raises an IOTP Error Block. 950 2.3 Brand Selection 952 This section describes the steps that happen mainly after the 953 Merchant's Brand Compilation (in a brand independent transaction). 954 However, these steps might partially interlace the previous process 955 (in a brand dependent transaction). 957 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 958 Merchant Merchant generates Brand List(s) containing 959 Brands, Payment Protocols and Currency Amounts 960 On brand independent transactions 961 | Merchant generates Offer Response Block 962 Consumer Compile set(s) of Brands B/Protocols P 963 for each set 964 | Find Payment Instrument(B, P, C) -> IPB 965 | Find Payment Instrument Response (PI*) <- IPB 966 Consumer selects Brand/Currency/Payment Instrument 967 from those that will work and generates Brand 968 Selection Component 969 For the Selection 970 | Get Payment Initialization Data(B,C,PI,P) -> IPB 971 | Get Payment Initialization Data Response()<- IPB 972 On brand dependent transaction 973 | Generate and transmit TPO Selection Block 975 Merchant On brand dependent transaction 976 | Merchant checks Brand Selection and generates 977 | and transmits Offer Response Block 978 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 979 Figure 4 Brand Selection Message Flows 981 1. The Merchant's commerce server controls the shopping dialog with 982 its own mechanisms until the Consumer checks out the shopping cart 983 and indicates his payment intention. The subsequent processing 984 switches to the IOTP based form by the activation of the Merchant's 985 IOTP aware application. 987 2. The IOTP Application Core compiles the IOTP Trading Protocol 988 Options Block which contains the IOTP Brand List Component(s) 989 enumerating Merchant's accepted payment brands and payment protocols 990 and initiates the Brand Selection process. 992 3. This first IOTP message activates the Consumer's IOTP aware 993 application, e.g., the Web browser invokes a helper application 994 (e.g., Java applet or external application). Its IOTP Application 995 Core 997 o infers the accepted payment brands, payment protocols, payment 998 direction, currencies, payment amounts, any descriptions etc., and 999 their relationships from the IOTP message, 1001 o determines the registered IOTP Payment Bridges, 1003 o compiles one or multiple set of brand and protocol such that the 1004 join of all set describes exactly the set of payment alternatives 1005 being offered by the Merchant. 1007 o inquires payment (protocol) support and the known payment 1008 instruments from each registered IOTP Payment Bridge for each 1009 compiled set ("Find Payment Instrument"). However, some IOTP Payment 1010 Bridges may refuse payment instrument distinction. 1012 The payment protocol support may differ between payment instruments 1013 if the IOTP Payment Bridge supports payment instrument distinction. 1015 These API calls are used to infer the payment alternatives at the 1016 startup of any payment transaction (without user unfriendly explicit 1017 user interaction). 1019 The IOTP Application Core must provide wallet identifiers, if they 1020 are requested by the IOTP Payment Bridges which signal their need by 1021 specific error codes (see below). 1023 It is recommended that the IOTP Application Core manages wallet 1024 identifiers. But for security reasons, it should store pass phrases 1025 in plain text only in runtime memory. Developers of IOTP Payment 1026 Bridges and payment software modules should provide a thin and fast 1027 implementation - without lengthy initialization processes- for this 1028 initial inquiry step. 1030 4. The IOTP Application Core 1032 verifies the Consumer's payment capabilities with the Merchant's 1033 accepted payment brands and currencies, 1035 o displays the valid payment instruments and payment instrument 1036 independent payment brands (brand and protocol) together with their 1037 purchase parameters (payment direction, currency, amount), and 1039 o requests the Consumer's choice or derives it automatically from any 1040 configured preferences. Any selection ties one IOTP Payment Bridge 1041 with the following payment transaction. 1043 The handling and resolution of unavailable IOTP Payment Bridges 1044 during the inquiry in Step 3 is up to the IOTP Application Core. It 1045 may skip these IOTP Payment Bridges or may allow user supported 1046 resolution. 1048 Furthermore, it may offer the registration of new payment 1049 instruments when the Consumer is requested for payment instrument 1050 selection. 1052 5. The IOTP Application Core interrogates the fixed IOTP Payment 1053 Bridge whether the payment might complete with success ("Check 1054 Payment Possibility"). At this step, the IOTP Payment Bridge may 1055 issue several signals, e.g., 1056 o payment can proceed immediately, 1057 o required peripheral inclusive some required physical payment 1058 instrument (chip card) is unavailable, 1059 o (non-IOTP) remote party (e.g. issuer, server wallet) is not 1060 available, 1061 o wallet identifier or pass phrase is required, 1062 o expired payment instrument (or certificate), insufficient funds, 1063 or 1064 o physical payment instrument unreadable. 1066 In any erroneous case, the user should be notified and offered 1067 accurate alternatives. Most probably, the user might be recommended 1069 o to resolve the problem, e.g. to insert another payment 1070 instrument or to verify the periphery, 1071 o to proceed (assuming its success), 1072 o to cancel the whole transaction, or 1073 o to suspend the transaction, e.g., initiating a nested 1074 transaction for uploading an electronic purse. 1076 If the payment software implements payment instrument selection on 1077 its own, it may request the Consumer's choice at this step. 1079 If the check succeeds, it returns several IOTP Brand Selection Info 1080 Elements. 1082 6. The Steps 2 to 5 are repeated and possibly interlaced for the 1083 selection of the second payment instrument during IOTP Value Exchange 1084 transactions - this is omitted in the figure above. 1086 7. The IOTP Brand Selection Component is generated and enriched with 1087 the Brand Selection Info elements. This component is transmitted to 1088 the Merchant inside a TPO Selection Block if the received IOTP 1089 message lacks the IOTP Offer Response Block. The Merchant will then 1090 respond with an IOTP Offer Response Block (following the 1091 aforementioned compilation rules). 1093 2.4 Successful Payment 1095 An example of how the functions in this document are used together 1096 to effect a successful payment is illustrated in the Figure 5. 1098 Technically, two payments happen during IOTP Value Exchange 1099 transactions. 1101 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1102 Consumer Start Payment Consumer(Amount,[PS0]...) -> IPB 1103 Start Payment Cons. Res.([PS1], CS=Cont.) <- IPB 1104 Create and transmit Payment Request Block 1105 Payment Handler Start Payment Pay. Handler(Amount, [PS1]) -> IPB 1106 Start Payment PH Response(PS2, CS=Cont.) <- IPB 1107 Create and transmit Payment Exchange Block 1108 Consumer Continue Process(PS2) -> IPB 1109 Continue Process Response(PS3, CS=Cont.) <- IPB 1111 ... CONTINUE SWAPPING PAYMENT EXCHANGES UNTIL ... 1113 Payment Handler Continue Process Response([PSn], CS=End) <- IPB 1114 Request any local payment receipt 1115 | Inquire Process State() -> IPB 1116 | Inquire Proc. State Resp.(State, [Rcp.])<- IPB 1117 Create and transmit Payment Response Block 1118 Terminate transaction, actively 1119 | Change Process State(State) -> IPB 1120 | Change PS Response(State=CompletedOK) <- IPB 1122 Consumer On receipt of final payment scheme data 1123 | Continue Process(PSn) -> IPB 1124 | Continue Process Response(CS=End) <- IPB 1125 Check Payment Receipt(Receipt) -> IPB 1126 Check Payment Receipt Response() <- IPB 1127 Request any local payment receipt 1128 | Inquire Process State() -> IPB 1129 | Inquire Proc. State Resp.(State, [Rcp.])<- IPB 1130 Terminate transaction, actively 1131 | Change Process State(State) -> IPB 1132 | Change PS Response(State=CompletedOk) <- IPB 1133 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1134 Figure 5 Example Payment Message Flows 1136 1. After Brand Selection and receipt of the IOTP Offer Response 1137 Block, the Consumer switches from communicating with the Merchant to 1138 communicating with the Payment Handler. 1140 This might be a milestone requiring the renewed Consumer's agreement 1141 about the payment transaction's continuation. Particularly, this is a 1142 good moment for payment suspension (and even cancellation), which 1143 will be most probably supported by all payment schemes. Simply, 1144 because the genuine payment legacy systems have not been involved in 1145 the current transaction. 1147 Such an agreement might be explicit per transaction or automatic 1148 based on configured preferences, e.g., early acknowledgements for 1149 specific payment limits. 1151 It is assumed, that the transaction proceeds with minimal user 1152 (Consumer and Payment Handler) interaction and that its progess is 1153 controlled by the IOTP Application Core and IOTP Payment Bridge. 1155 2. In order to open the actual payment transaction, the IOTP 1156 Application Core issues the "Start Payment Consumer" request towards 1157 the IOTP Payment Bridge. This request carries the whole 1158 initialization data of the payment transaction being referred to by 1159 the IOTP Payment Bridge for subsequent consistency checks: 1161 o payment brand and its description from the selected Brand 1162 Element of the IOTP Brand List Component, 1163 o payment instrument from preceding inquiry step, 1164 o further payment parameters (currency, amount, direction, 1165 expiration) from the selected Currency Amount element, Brand List 1166 Component, and Payment Component of the IOTP Offer Response Block, 1167 o payment protocol from the selected IOTP Pay Protocol Element, 1168 o order details contained in the IOTP Order Component which might 1169 be payment scheme specific, 1170 o payment scheme specific data inclusive payment protocol 1171 descriptions from the IOTP Protocol Amount Element, and IOTP Pay 1172 Protocol Element, and 1173 o payment scheme specific data inclusive payment protocol 1174 descriptions, in which the name attribute includes the prefix as 1175 "Payment:" from the Trading Role Data Component. 1177 Generally, the called API function redoes most checks of the "Check 1178 Payment Possibility" call due to lack of strong dependencies between 1179 both requests: There might be a significant delay between both API 1180 requests. 1182 The called API function may return further payment scheme specific 1183 data being considered as payment specific initialization data for the 1184 Payment Handler's IOTP Payment Bridge. 1186 If the fixed Existing Payment Software implements payment instrument 1187 selection on its own, it may request the Consumer's choice at this 1188 step. 1190 The IOTP Payment Bridge reports lack of capability quite similar to 1191 the "Check Payment Possibility" request to the IOTP Application Core. 1192 The Consumer may decide to resolve the problem, to suspend, or to 1193 cancel the transaction, but this function call must succeed in order 1194 to proceed with the transaction. 1196 Developers of payment modules may decide to omit payment instrument 1197 related checks like expiration date or refunds sufficiency, if they 1198 are part of the specific payment protocol. 1200 If the IOTP Payment Bridge requests wallet identifiers or pass 1201 phrases anywhere during the payment process, they should be requested 1202 by this API function, too. It is recommended that the IOTP 1203 Application Core stores plain text pass phrases only in runtime 1204 memory. 1206 Finally, the IOTP Application Core generates the IOTP Payment 1207 Request Block, inserts any returned payment scheme data, and submits 1208 it to the Payment Handler's system. 1210 3. The Payment Handler's IOTP Application Core opens the payment 1211 transaction calling the "Start Payment Payment Handler" API function. 1212 The payment brand, its description, payment protocol, payment 1213 specific data, payment direction, currency and payment amount are 1214 determined quite similar to the Consumer's IOTP Application Core. 1215 Furthermore, the content of the IOTP Payment Scheme Component and the 1216 IOTP Brand Selection Info Elements are passed to this function. 1218 On success, the Payment Handler's IOTP Payment Bridge responds with 1219 payment scheme specific data. On failures, this non- interactive 1220 server application has to resolve any problems on its own or to give 1221 up aborting the payment transaction. However, the Consumer may 1222 restart the whole payment transaction. Anyway, the payment log file 1223 should reflect any trials of payments. 1225 Eventually, the Payment Handler informs the Consumer about the 1226 current IOTP Process State using the IOTP Payment Response or IOTP 1227 Error Block. 1229 Note that the "Start Payment Payment Handler" call might return the 1230 Continuation Status "End" such that payment processing proceeds with 1231 Step 7. 1233 4. The IOTP Application Core verifies the presence of the Payment 1234 Exchange Block in the IOTP message and passes the contained payment 1235 scheme specific data to the fixed IOTP Payment Bridge ("Continue 1236 Process") which returns the next IOTP Payment Scheme Component. 1238 This Payment Scheme Component is encapsulated in an IOTP Payment 1239 Exchange Block and transmitted to the Payment Handler. 1241 5. The Payment Handler's IOTP Application Core verifies the presence 1242 of the Payment Exchange Block and passes the contained payment scheme 1243 specific data to the fixed IOTP Payment Bridge ("Continue Process") 1244 which returns the next IOTP Payment Scheme Component for 1245 encapsulation and transmission to the Consumer. 1247 6. The payment process continues with IOTP Payment Exchange Block 1248 exchanges, carrying the payment scheme specific data. Each party (1) 1249 submits the embedded payment scheme specific data transparently to 1250 the appropriate IOTP Payment Bridge calling the "Continue Process" 1251 API function, (2) wraps the returned payment scheme specific data 1252 into an IOTP Payment Exchange Block, and (3) transmits this block to 1253 the counter party. 1255 However, the processing of the payment scheme specific data may fail 1256 for several reasons signaled by specific error codes which are 1257 transformed to IOTP Payment Response Blocks (generated by Payment 1258 Handler) or IOTP Error Blocks (both parties may generate them) and 1259 transmitted to the counter party. 1261 7. Eventually, the Payment Handler's IOTP Payment Bridge recognizes 1262 the termination of the payment transaction and reports this by the 1263 continuation status "End" on the output parameter of "Continue 1264 Process" (or "Start Payment Payment Handler"). Then, the IOTP 1265 Application Core issues the "Inquire Process State" API call and 1266 verifies whether an IOTP Payment Receipt Component has been returned. 1267 The IOTP Application Core wraps the payment receipt, the status 1268 response, and the optional payment scheme specific data in an IOTP 1269 Payment Response Block and transmits this block to the Consumer. 1271 However, any of these API calls may fail or any response might be 1272 incomplete (e.g., lack of payment receipt). Then, the Consumer has to 1273 be notified about the failed processing by an IOTP Error Block. 1275 Finally, the Payment Handler terminates the payment transaction with 1276 the "Change Process State" API call without awaiting any further 1277 response from the Consumer. Further failures are not reported to the 1278 Consumer. 1280 Note that it might be possible that the Consumer's IOTP Payment 1281 Bridge has returned the previous payment scheme specific data with 1282 the continuation status "End". Even in the absence of this knowledge 1283 - this status is not exchanged between the Consumer and the Payment 1284 Handler - the Payment Handler must not supply any further payment 1285 scheme specific data. Such data will be rejected by the Consumer's 1286 IOTP Payment Bridge. 1288 8. The Consumer passes the optional payment scheme specific data and 1289 the payment receipt to the fixed IOTP Payment Bridge by "Continue 1290 Process" and "Check Payment Receipt" API calls. 1292 Afterwards, the IOTP Application Core issues the "Inquire Process 1293 State" API call and verifies whether extensions to the payment 1294 receipt have been returned. 1296 Finally, the transaction is terminated by calling the "Change 1297 Process State" API function which verifies and synchronizes the 1298 reported payment status with the local one and signals any 1299 inconsistencies. Any Inconsistency and returned status text should be 1300 displayed to the Consumer. 1302 At this point, the payment transaction has already been closed by 1303 the Payment Handler. Therefore, any failure has to be resolved 1304 locally or out-of-band. 1306 2.5 Payment Inquiry 1308 In Baseline IOTP, Payment inquiries are initiated by the Consumer in 1309 order to verify the current payment progress and process state at the 1310 remote Payment Handler. 1312 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1313 Consumer Start Payment Inquiry() -> IPB 1314 Start Payment Inquiry Response([PS1]) <- IPB 1315 Create and transmit Inquiry Request Trading Block 1316 Payment Handler Inquire Payment Status([PS1]) -> IPB 1317 Inquire Payment Status Res.(State, [PS2]) -> IPB 1318 Create and transmit Inquiry Response Trading 1319 Block 1320 Consumer If Payment Scheme Data present 1321 | Continue Process(PS2) -> IPB 1322 | Continue Process Response(CS=End) <- IPB 1323 Change Process State(State) -> IPB 1324 Change Process State Response(State) <- IPB 1325 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1326 Figure 6 Remote Process State Inquiry 1328 1. The Consumer might initiate a payment inquiry once the payment 1329 transaction has been opened by the IOTP Application Core, i.e., at 1330 any time after the initial submission of the IOTP Payment Request 1331 Block. The IOTP Application Core requests any additional specific 1332 payment scheme data from the IOTP Payment Bridge which has been fixed 1333 during brand selection (cf. Section 2.3) using the "Start Payment 1334 Inquiry" API request. 1336 Erroneous API responses should be reported to the Consumer and valid 1337 alternatives (typically retry and cancellation) should be presented 1338 by the IOTP Application Core. 1340 This request might perform the complete initialization, e.g. 1341 availability check of periphery or pass phrase supplement, and the 1342 IOTP Payment Bridge reports lack of capability quite similar to the 1343 "Check Payment Possibility" request to the IOTP Application Core. 1345 If the IOTP Payment Bridge requests wallet identifiers or pass 1346 phrases anywhere during the payment process, they should be requested 1347 by this API function, too. It is recommended that the IOTP 1348 Application Core stores plain text pass phrases only in runtime 1349 memory. 1351 The IOTP Application Core encapsulates any Payment Scheme Component 1352 in an IOTP Inquiry Request Block and submits the block to the Payment 1353 Handler. 1355 2. The Payment Handler analyses the IOTP Inquire Request Block, maps 1356 the Transaction Identifier to payment related attributes (brand, 1357 consumer and payment identifiers), determines the appropriate IOTP 1358 Payment Bridge, and forwards the request to the this IOTP Payment 1359 Bridge ("Inquire Payment Status"). The IOTP Application Core 1360 transforms the response to an IOTP Inquiry Response Block and 1361 transmits it to the Consumer. 1363 3. On receipt of the respective IOTP Inquiry Response Block the 1364 Consumer's IOTP Application Core submits any encapsulated payment 1365 scheme specific data to the IOTP Payment Bridge for verification 1366 ("Continue Process"). 1368 4. The IOTP Application Core passes the reported payment status 1369 (except textual descriptions) to the IOTP Payment Bridge ("Change 1370 Process State") for verification purposes and payment status change. 1371 The IOTP Payment Bridge reports any inconsistencies as well as the 1372 final payment status to the IOTP Application Core. 1374 Any additional information that might be of interest for the 1375 Consumer has to be displayed by the IOTP Payment Bridge or Existing 1376 Payment Software on their own. 1378 2.6 Abnormal Transaction Processing 1380 2.6.1 Failures and Cancellations 1382 The IOTP specification distinguishes between several classes of 1383 failures: 1385 o Business and technical errors 1386 o Error depth on transport, message and block level 1387 o Transient errors, warnings, and hard errors. 1389 Any IOTP Payment API has to deal with the receipt of failure 1390 notifications by and failure responses. This proposal has borrowed 1391 the basic mechanisms for error reporting between the IOTP Application 1392 Core and the IOTP Payment Bridge from the genuine protocol: Business 1393 errors are reported by Status Components within IOTP Response Blocks 1394 while technical errors are signaled by Error Components within IOTP 1395 Error Blocks. 1397 Cancellations are mimicked as specific business errors which might 1398 be initiated by each trading party. 1400 Preferring slim interfaces, this IOTP Payment API introduces one 1401 additional Error Code value for business error indication - errors 1402 can be raised on every API call. On receipt of this value, the IOTP 1403 Application Core has to infer further details by the issuance of the 1404 API function call "Inquire Process State". 1406 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1407 Any Party Issue some API request -> IPB 1408 Error Response(Error Code) <- IPB 1409 On "Business Error" response 1410 | Inquire Process State() -> IPB 1411 | Inquire P.S. Resp.(State, Receipt) <- IPB 1412 Analyze local process state and try to resolve 1413 with optional user interaction 1414 If Process State Change needed 1415 | Change Process State (State) -> IPB 1416 | Change Process State Response(State) <- IPB 1417 If counter party's notification required 1418 | Create Error or Cancel Block (, add to next 1419 | message, ) and transmit it to counter party 1420 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1421 Figure 7 Error Response from IPB 1423 The specific Completion Codes "ConsCancelled", "MerchCancelled", and 1424 "PaymCancelled" - returned by "Inquire Process State" - determine 1425 that the IOTP Cancel Block has to be created instead of an IOTP Error 1426 Block. 1428 The rules for determining the required behavior of the IOTP 1429 Application Core are given in the IOTP specification. 1431 Note that any payment (intermediate) termination, i.e., failures, 1432 cancellations, and even success's is always reported to the IOTP 1433 Payment Bridge by the API function "Change Process State". This API 1434 function does both status changes and consistency checking / 1435 synchronization. Any suspicion of inconsistency should be reported by 1436 the IOTP Payment Bridge for display by the IOTP Application Core. 1438 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1439 Any Party Error Block or Cancel Block Received 1440 If Change Process State required 1441 | Change Process State (State) -> IPB 1442 | Change Process State Response(State) <- IPB 1443 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1444 Figure 8 Error Notification from counter party 1446 Not every failure might be visible at the IOTP layer, e.g., the 1447 processing of payment transactions might temporarily be hampered by 1448 intermediate failures at the payment scheme or protocol transport 1449 layer which might be resolved by the genuine components. 1451 However, final failures or cancellations have to be reported at the 1452 IOTP layer. E.g., communication time-outs and heavily faulty 1453 communication channels may disable the transaction. 1455 Any system component may implement time-out recognition and use the 1456 aforementioned API mechanisms for the notification of process state 1457 changes. But, time-outs may happens while communicating with both the 1458 counter party and local system components, like chip card readers or 1459 IOTP Payment Bridges. Anyway, the Consumer's IOTP Application Core 1460 should notify the Consumer about the resolution alternatives, i.e., 1461 retry, suspension, and cancellation. 1463 2.6.2 Resumption 1465 Payment transaction resumption may apply at different steps of a 1466 payment transaction: 1468 o The Consumer's and Payment Handler's view of the transaction 1469 might not be synchronized: Due to different time-out values the 1470 payment transaction may not have been suspended by the counter 1471 party. 1473 Any "Resume Payment ..." API function responds with an Error Code 1474 on non suspended payment transaction that signals a business 1475 error. Afterwards the IOTP Application Core has to issue the 1476 "Inquire Process State" API call for further analysis of the 1477 process state. 1479 o One IOTP message sent by one party might not be processed 1480 successfully or even received by the counter party. 1482 This needs to be handled by the genuine payment scheme. It is 1483 expected that the IOTP Application Core will not recognize 1484 anything. 1486 o IOTP does not provide any specific signal for payment 1487 resumption. On receipt of every IOTP Payment Exchange Block, the 1488 IOTP Application Core has to decide whether this Block belongs to 1489 a pending transaction or to a suspended transaction that should be 1490 resumed. The IOTP Application Core might call the "Inquire Process 1491 State" API function to update any lack of knowledge. 1493 Any "Resume Payment" API function responds with an Error Code on 1494 non suspended payment transaction that signals a business error. 1495 Similar, the "Continue Process" API function should report 1496 business errors on non pending payment transactions. 1498 o The payment transaction may not have been created at the Payment 1499 Handler (early suspension and failed data transmission). In that 1500 case, the IOTP Application Core should respond with a business 1501 error that signals the repetition of the payment transaction (by 1502 the Consumer). 1504 Any "Resume Payment", "Continue Process" or "Inquire Process 1505 State" API function should return with an Error Code 1506 "AttValIllegal" on non existent payment transaction whereby the 1507 further Error Attribute "Names" denote the payment identifier. 1509 o The IOTP Application Core should always request fresh payment 1510 scheme specific data on resumption - for synchronization purposes 1511 with the Existing Payment Software. Old data in the cache that has 1512 not been send to the counter party should not be accessed. 1514 If the Consumer does not reconnect within an acceptable amount of 1515 time, the Payment Handler's system may perform local failure 1516 resolution in order to close the transaction and to retain resources 1517 for other transactions ("Change Process State"). If the Consumer 1518 reconnect afterwards, an IOTP Payment Response or IOTP Error Block 1519 could be generated. 1521 2.7 IOTP Wallet Initialization 1523 At startup or on explicit user request the IOTP Application Core 1524 should check its IOTP Payment Bridges' internal status by searching 1525 for pending payment transactions. 1527 1. The IOTP Application Core interrogates the registered IOTP 1528 Payment Bridges about pending payment transactions. The IOTP 1529 Application Core may store indicators for pending transactions and 1530 use them for driving any subsequent inquiry ("Inquire Pending 1531 Payment"). 1533 2. If one or more IOTP Payment Bridges report the presence of pending 1534 transactions, the IOTP Application Core may try to suspend ("Change 1535 Process State") or resume (only Consumer: "Resume Payment Consumer") 1536 the pending transactions (on user request). 1538 The IOTP Payment Bridge may deny the processing of any new payment 1539 transactions until the pending transactions have been processed. Such 1540 denials are signaled by the error code "Business Error". 1542 2.8 Payment Software Management 1544 The IOTP Application Core provides only a simple and generic 1545 interface for the registration of new payment methods / instruments 1546 ("Manage Payment Software"). It receives the initial user request and 1547 defers the actual registration to the corresponding IOTP Payment 1548 Bridge. 1550 The IOTP Application Core may also activate the Existing Payment 1551 Software for further payment instrument and wallet administration. 1553 3. Mutuality 1555 The Payment API is formalized using the Extensible Markup Language 1556 (XML). It defines wrapper elements for both the input parameters and 1557 the API function's response. In particular, the response wrapper 1558 provides common locations for Error Codes and Error Descriptions. 1560 It is anticipated that this description reflects the logical 1561 structure of the API parameter and might be used to derive 1562 implementation language specific API definitions. 1564 XML definition: 1566 1592 1598 1624 1630 1631 1641 Most of the attribute items are intended for immediate insertion in 1642 the IOTP Error Block. The attribute values of the Error Location 1643 elements attribute have to enriched and transformed into Error 1644 Location Elements of the Error Component (cf. IOTP Specification). 1646 Attributes (cf. IOTP Specification): 1648 xml:lang Defines the language used by attributes or 1649 child elements within this component, unless 1650 overridden by an xml:lang attribute on a child 1651 element. 1653 ContentSoftwareId Contains information which identifies the 1654 ssoftware that generated the content of the 1655 element. Its purpose is to help resolve 1656 interoperability problems that might occur as 1657 a result of incompatibilities between messages 1658 produced by different software. It is a single 1659 text string in the language defined by 1660 "xml:lang". It must contain, as a minimum 1661 problems that might occur as a result of 1663 o the name of the software manufacturer, 1664 o the name of the software, 1665 o the version of the software, and 1666 o the build of the software. 1668 ErrorCode Contains an error code which indicates the 1669 nature of the error in the message in error. 1670 Valid values for the Error Code are given in 1671 the following section. This mnemonic enables 1672 the automatic failure resolution of the IOTP 1673 Application Core which analyzes the error code 1674 value in order to determine the continuation 1675 alternatives. 1677 ErrorDesc Contains a description of the error in the 1678 language defined by xml:lang. The content of 1679 this attribute is defined by the 1680 vendor/developer of the software that 1681 generated the Error Response Element. 1682 It is intended for user display and provides 1683 detailed explanations about the failure and 1684 its (out-of-band) resolution alternatives. 1686 Severity Indicates the severity of the error. Valid 1687 values are: 1689 o Warning. This indicates that although there 1690 is a message in error the IOTP Transaction 1691 can still continue. 1693 o TransientError. This indicates that the 1694 error in the message in error may be 1695 recovered if the message in error that is 1696 referred to by the "Names" attribute is 1697 resent. 1699 o HardError. This indicates that there is an 1700 unrecoverable error in the message in error 1701 and the IOTP Transaction must stop. 1703 MinRetrySecs This attribute should be present if "Severity" 1704 is set to "TransientError". It is the minimum 1705 number of whole seconds which the IOTP aware 1706 application which received the message 1707 reporting the error should wait before re- 1708 sending the message in error identified by the 1709 "ErrorLocation" attribute. 1711 If Severity is not set to 1712 "TransientError" then the value of this 1713 attribute is ignored. 1715 SwVendorErrorRef This attribute is a reference whose value is 1716 set by the vendor/developer of the software 1717 that generated the Error Element. It should 1718 contain data that enables the vendor to 1719 identify the precise location in their 1720 software and the set of circumstances that 1721 caused the software to generate a message 1722 reporting the error. 1724 Content: 1726 ErrorLocation This identifies, where possible, the 1727 element and attribute in the message 1728 in error that caused the Error 1729 Element to be generated. If the 1730 "Severity" of the error is not 1731 "TransientError", more that one 1732 "ErrorLocation" may be specified as 1733 appropriate depending on the nature 1734 of the error and at the discretion of 1735 the vendor/developer of the IOTP 1736 Payment Bridge. 1738 Its definition coincides with the 1739 IOTP specification whereby the 1740 attributes "IotpMsgRef", "BlkRef" and 1741 "CompRef" are left blank, 1742 intentionally. 1744 PaySchemePackagedContent cf. Table 5 1746 3.1 Error Codes 1748 The following table lists the valid values for the ErrorCode 1749 attribute of the Error Response Element. The first sentence of the 1750 error description contains the default text that can be used to 1751 describe the error when displayed or otherwise reported. Individual 1752 implementations may translate this into alternative languages at 1753 their discretion. However, not every error code may apply to every 1754 API call. An Error Code must not be more than 14 characters long. 1756 The Error Codes have been taken from the IOTP Specification and 1757 extended by some additional codes which are highlighted by a 1758 preceding asterisk. 1760 Generally, if the corrupt values have been user supplied, the IOTP 1761 Application Core might prompt for their correction. If the renewal 1762 fails or if the IOTP Application Core skips any renewals and some 1763 notification has to be send to the counter-party, the error code is 1764 encapsulated within an IOTP Error Block. 1766 However, the IOTP server application reports business errors - 1767 visible at the IOTP layer - in the Status Component of the respective 1768 Response Block. 1770 The IOTP Application Core may add the attributes (and values) within 1771 the ErrorLocation elements being omitted by the IOTP Payment Bridge. 1773 The following table mentions any modification from this general 1774 processing for particular error values. Furthermore, it contains 1775 hints for developers of IOTP Application Core software components 1776 about the processing of error codes. Conversely, developers of IOTP 1777 Payment Bridges get impressions about the expected behavior of the 1778 IOTP Application Core. 1780 The IOTP Payment API assumes that the IOTP Application Core 1781 implements the dialog boxes needed for error resolution. But it does 1782 not assume, that the IOTP Payment Bridge actually relies on them. 1783 Instead, the IOTP Payment Bridge may try resolution on its own, may 1784 implement specific dialog boxes, and may signal only final failures. 1786 Note: This abstract document assumes that the API parameters are 1787 exchanged XML encoded. Therefore, several error values might 1788 disappear in lower level language specific derivations. 1790 Error Value Error Description 1792 Reserved Reserved. This error is reserved by the 1793 vendor/developer of the software. Contact 1794 the vendor/developer of the software for 1795 more information (see the SoftwareId 1796 attribute of the Message Id element in the 1797 Transaction Reference Block [IOTP]). 1799 XmlNotWellFrmd XML not well formed. The XML document is not 1800 well formed. See [XML] for the meaning of 1801 "well formed". 1803 XmlNotValid XML not valid. The XML document is well 1804 formed but the document is not valid. See 1805 [XML] for the meaning of "valid". 1806 Specifically: 1808 o the XML document does not comply with the 1809 constraints defined in the IOTP document 1810 type declaration, and 1811 o the XML document does not comply with the 1812 constraints defined in the document type 1813 declaration of any additional [XML-NS] 1814 that are declared. 1816 The Names attribute might refer some 1817 attributes and elements of the input 1818 parameter list. 1820 (*)ElNotValid Element not valid. Invalid element in terms 1821 of prescribed syntactical characteristics. 1823 The ElementRef attributes of ErrorLocation 1824 elements might refer to the corresponding 1825 elements (if they have ID attributes). 1827 The IOTP Application Core has to replace the 1828 error code with "XmlNotValid" before 1829 transmission to the counterparty. 1831 ElUnexpected Unexpected element. Although the XML 1832 document is well formed and valid, an 1833 element is present that is not expected in 1834 the particular context according to the 1835 rules and constraints contained in this 1836 specification. 1838 The ElementRef attributes of ErrorLocation 1839 elements might refer to the corresponding 1840 elements (if they have ID attributes). 1842 ElNotSupp Element not supported. Although the document 1843 is well formed and valid, an element is 1844 present that 1846 o is consistent with the rules and 1847 constraints contained in this 1848 specification, but 1849 o is not supported by the IOTP Aware 1850 Application which is processing the IOTP 1851 Message. 1853 The ElementRef attributes of ErrorLocation 1854 elements might refer to the corresponding 1855 elements (if they have ID attributes). 1857 ElMissing Element missing. Although the document is 1858 well formed and valid, an element is missing 1859 that should have been present if the rules 1860 and constraints contained in this 1861 specification are followed. 1863 The ElementRef attributes of ErrorLocation 1864 elements might refer to the corresponding 1865 elements (if they have ID attributes). 1867 ElContIllegal Element content illegal. Although the 1868 document is well formed and valid, the 1869 element contains values which do not conform 1870 the rules and constraints contained in this 1871 specification. 1873 The ElementRef attributes of ErrorLocation 1874 elements might refer to the corresponding 1875 element (if they have ID attributes). 1877 The IOTP Application Core has to replace the 1878 Error Code with "ElNotSupp" before 1879 transmission to the counter party, if the 1880 ErrorLocation elements refer to non 1881 PackagedContent element. 1883 EncapProtErr Encapsulated protocol error. Although the 1884 document is well formed and valid, the 1885 Packaged Content of an element contains data 1886 from an encapsulated protocol which contains 1887 errors. 1889 The ElementRef attributes of ErrorLocation 1890 elements might refer to the corresponding 1891 element (if they have ID attributes). 1893 AttUnexpected Unexpected attribute. Although the XML 1894 document is well formed and valid, the 1895 presence of the attribute is not expected in 1896 the particular context according to the 1897 rules and constraints contained in this 1898 specification. 1900 The AttName attributes of ErrorLocation 1901 elements might refer to the corresponding 1902 attribute tags. 1904 (*)AttNotValid Attribute not valid. Invalid attribute value 1905 in terms of prescribed syntactical 1906 characteristics. 1908 The AttName attributes of ErrorLocation 1909 elements might refer to the corresponding 1910 attribute tags. 1912 The IOTP Application Core has to replace the 1913 error code with "XmlNotValid" before 1914 transmission to the counter party. 1916 AttNotSupp Attribute not supported. Although the XML 1917 document is well formed and valid, and the 1918 presence of the attribute in an element is 1919 consistent with the rules and constraints 1920 contained in this specification, it is not 1921 supported by the IOTP Aware Application 1922 which is processing the IOTP Message. 1924 AttMissing Attribute missing. Although the document is 1925 well formed and valid, an attribute is 1926 missing that should have been present if the 1927 rules and constraints contained in this 1928 specification are followed. 1930 The AttName attributes of ErrorLocation 1931 elements might refer to the corresponding 1932 attribute tags. 1934 If the attribute is required by the IOTP 1935 Document Type Declaration (#REQUIRED) the 1936 hints for non valid attributes should be 1937 adopted, otherwise these for illegal 1938 attribute values. 1940 AttValIllegal Attribute value illegal. The attribute 1941 contains a value which does not conform to 1942 the rules and constraints contained in this 1943 specification. 1945 The AttName attributes of ErrorLocation 1946 elements might refer to the corresponding 1947 attribute tags - valid values are: 1949 BrandId: illegal/unknown Brand Identifier - 1950 If the brand is not recognized/known by any 1951 IOTP Payment Bridge, the IOTP Application 1952 Core may offer the registration of a new 1953 Payment Instrument. 1955 PaymentInstrumentId: illegal/unknown 1956 Payment Instrument Identifier - This 1957 indicates a serious communication problem if 1958 the attribute value has been reported by the 1959 same "wallet" on a previous inquiry 1960 requests. The IOTP Application Core has to 1961 replace the error code with 1962 "UnknownError" before transmission to the 1963 counter party. 1965 WalletId: illegal/unknown Wallet Identifier 1966 - It is assumed that the wallet identifier 1967 is checked before the pass phrase. On 1968 invalid wallet identifiers, the IOTP 1969 Application Core may open the dialog in 1970 order to request the correct wallet 1971 identifier. In addition, any pass phrase may 1972 be supplied by the user. The dialog should 1973 indicate the respective payment brand(s). 1974 The IOTP Application Core has to replace the 1975 error code with "UnknownError" before 1976 transmission to the counter party. 1978 Passphrase: illegal/unknown Pass Phrase - 1979 The IOTP Application Core may open the 1980 dialog in order to request the correct pass 1981 phrase. If the pass phrase is wallet 1982 identifier specific the dialog should 1983 display the wallet identifier. The IOTP 1984 Application Core has to replace the error 1985 code with "TransportError" before 1986 transmission to the counter party. 1988 Action: illegal / unknown / unsupported 1989 Action 1991 PropertyTypeList: lists contains illegal / 1992 unknown / unsupported Property Types - The 1993 IOTP Application Core tries only the local 1994 resolution but does never transmit any IOTP 1995 Error Block to the counter party. 1997 CurrCode: illegal/unknown/unsupported 1998 Currency Code 2000 CurrCodeType: illegal/unknown/unsupported 2001 Currency Code Type 2003 Amount: illegal/unknown/unsupported Payment 2004 Amount 2006 PayDirection: illegal/unknown/unsupported 2007 Payment Direction 2009 ProtocolId: illegal/unknown/unsupported 2010 Protocol Identifier 2012 OkFrom: illegal/unknown/unsupported OkFrom 2013 Timestamp 2015 OkTo: illegal/unknown/unsupported OkTo 2016 Timestamp 2018 ConsumerPayId: illegal/unknown Consumer 2019 Payment Identifier 2021 PaymentHandlerPayId: illegal/unknown Payment 2022 Handler Payment Identifier 2024 PayId: illegal/unknown Payment Identifier 2026 AttValNotRecog Attribute Value Not Recognized. The 2027 attribute contains a value which the IOTP 2028 Aware Application generating the message 2029 reporting the error could not recognize. 2031 The AttName attributes of ErrorLocation 2032 elements might refer to the corresponding 2033 attribute tags 2035 MsgTooLarge Message too large. The message is too large 2036 to be processed by the IOTP Payment Bridge 2037 (or IOTP Application Core). 2039 ElTooLarge Element too large. The element is too large 2040 to be processed by the IOTP Payment Bridge 2041 (or IOTP Application Core). 2043 The ElementRef attributes of ErrorLocation 2044 elements might might refer to the 2045 corresponding elements. 2047 ValueTooSmall Value too small or early. The value of all 2048 or part of an element content or an 2049 attribute, although valid, is too small. 2051 The ErrorLocation elements might refer to 2052 the corresponding attribute tags or 2053 elements. 2055 ValueTooLarge Value too large or in the future. The value 2056 of all or part of an element content or an 2057 attribute, although valid, is too large. 2059 The ErrorLocation elements might refer to 2060 the corresponding attribute tags or 2061 elements. 2063 ElInconsistent Element Inconsistent. Although the document 2064 is well formed and valid, according to the 2065 rules and constraints contained in this 2066 specification: 2068 o the content of an element is inconsistent 2069 with the content of other elements or 2070 their attributes, or 2071 o the value of an attribute is inconsistent 2072 with the value of one or more other 2073 attributes. 2075 The Error Description may contain further 2076 explanations. 2078 The ErrorLocation elements might refer to 2079 the corresponding attribute tags or elements 2080 that are inconsistent. 2082 TransportError Transport Error. This error code is used to 2083 indicate that there is a problem with the 2084 transport mechanism that is preventing the 2085 message from being received. It is typically 2086 associated with a "Transient Error". 2088 The connection to some 2089 periphery or the counter party could not be 2090 established, is erroneous, or has been lost. 2092 The Error Description may contain further 2093 narrative explanations, e.g., "chip card 2094 does not respond", "remote account manager 2095 unreachable", "Internet connection to xyz 2096 lost", "no Internet connection available", 2097 "no modem connected", or "serial port to 2098 modem used by another application". This 2099 text should be shown to the end user. If 2100 timeout has occurred at the Consumer this 2101 text should be shown and the Consumer may 2102 decide how to proceed - alternatives are 2103 retry, payment transaction suspension, and 2104 cancellation. 2106 MsgBeingProc Message Being Processed. This error code is 2107 only used with a Severity of Transient 2108 Error. It indicates that the previous 2109 message, which may be an exchange message or 2110 a request message, is being processed and, 2111 if no response is received by the time 2112 indicated by the "MinRetrySecs" attribute, 2113 then the original message should be resent. 2115 SystemBusy System Busy. This error code is only used 2116 with a Severity of Transient Error. It 2117 indicates that the IOTP Payment Bridge or 2118 Existing Payment Software that received the 2119 API request is currently too busy to handle 2120 it. If no response is received by the time 2121 indicated by the "MinRetrySecs" attribute, 2122 then the original message should be resent. 2124 The Error Description may provide further 2125 explanations, e.g., "wallet / chip card 2126 reader is unavailable or locked by another 2127 payment transaction", "payment gateway is 2128 overloaded", "unknown chip card reader", or 2129 "unrecognized chip card inserted, change 2130 chip card". 2132 The Consumer's IOTP Application Core may 2133 visualize the error description and ask the 2134 Consumer about the continuation - 2135 alternatives are retry, payment transaction 2136 suspension, and cancellation. 2138 UnknownError Unknown Error. Indicates that the 2139 transaction cannot complete for some reason 2140 that is not covered explicitly by any of the 2141 other errors. The Error description 2142 attribute should be used to indicate the 2143 nature of the problem. 2145 The ErrorLocation elements might refer to 2146 the corresponding attribute tags or elements 2147 that are inconsistent. 2149 (*)SyntaxError Syntax Error. An (unknown) syntax error has 2150 occurred. 2152 The ErrorLocation elements might refer to 2153 the corresponding attribute tags or elements 2154 that are inconsistent. 2156 The IOTP Application Core has to replace the 2157 error code with "XmlNotValid" or 2158 "UnknownError" before transmission to the 2159 counter party. 2161 (*)ReqRefused Request refused. The API request is 2162 (currently) refused by the IOTP Payment 2163 Bridge. The error description may provide 2164 further explanations, e.g., "wallet / chip 2165 card reader is unavailable or locked by 2166 another payment transaction", "payment 2167 gateway is overloaded", "unknown chip card 2168 reader", or "unrecognized chip card 2169 inserted, change chip card". 2171 The Consumer's IOTP Application Core may 2172 visualize the error description and ask the 2173 Consumer about the continuation - 2174 alternatives are retry, payment transaction 2175 suspension, and cancellation. Denials due to 2176 invalid Process States should be signaled by 2177 "BusinessError". Typically, this kind of 2178 error is not passed to the counter party's 2179 IOTP Application Core. Otherwise, it maps to 2180 "TransportError" or "UnknownError". 2182 (*)ReqNotSupp Request not supported. The API 2183 function(ality) has not been implemented in 2184 the IOTP Payment Bridge. Typically, this 2185 kind of error is not passed to the 2186 counter party's IOTP Application Core. 2187 Otherwise, it maps to "TransportError" or 2188 "UnknownError". 2190 (*)BusError Business Error. The API request has been 2191 rejected because some payment transaction 2192 has an illegal payment status. 2193 Particularly, this error code is used to 2194 signal any raise of payment business layered 2195 failures. 2197 The ErrorLocation elements may refer to 2198 payment transactions using the party's 2199 Payment Identifier - it defaults to the 2200 current transaction or might contain the 2201 current payment transaction party's Payment 2202 Identifier - identified by the ElementRef 2203 attribute while the AttName attribute is 2204 fixed with "PayId". 2206 The IOTP Application Core must inquire the 2207 IOTP Payment Bridge about the actual Process 2208 State which actually encodes the business 2209 error ("Inquire Process State"). 2210 This error code must not be 2211 passed to the counter party's IOTP 2212 Application Core. 2214 Table 2: Common Error Codes 2216 The IOTP Payment Bridge may also use the error description in order 2217 to notify the Consumer about further necessary steps for failure 2218 resolution, e.g., "sorry, your payment transaction failed. 2219 Unfortunately, you have been charged, please contact your issuer." 2221 3.2 Attributes and Elements 2223 The following table explains the XML attributes in alphabetical order 2224 - any parenthesized number behind the attribute tag recommends the 2225 maximal length of the attribute value in characters: 2227 Attribute Description 2229 Amount (11) Indicates the payment amount to be paid in 2230 AmountFrom(11) whole and fractional units of the currency. 2231 AmountTo (11) For example $245.35 would be expressed 2232 "245.35". Note that values smaller than the 2233 smallest denomination are allowed. For 2234 example one tenth of a cent would be 2235 "0.001". 2237 AuthenticationId An identifier specified by the 2238 authenticator which, if returned by the 2239 organization that receives the 2240 authentication request, will enable the 2241 authenticator to identify which 2242 authentication is being referred to. 2244 BrandId (128) This contains a unique identifier for the 2245 brand (or promotional brand). It is used to 2246 match against a list of Payment Instruments 2247 which the Consumer holds to determine 2248 whether or not the Consumer can pay with the 2249 Brand. 2251 Values of BrandId are managed under 2252 procedure being described in the IOTP 2253 protocol specification. 2255 BrandLogoNetLocn The net location which can be used to 2256 download the logo for the organization (cf. 2257 IOTP Specification). 2259 The content of this attribute must conform 2260 to [URL]. 2262 BrandName This contains the name of the brand, for 2263 example "MasterCard Credit". This is the 2264 description of the Brand which is displayed 2265 to the consumer in the Consumer's language 2266 defined by "xml:lang". For example it might 2267 be "American Airlines Advantage Visa". Note 2268 that this attribute is not used for matching 2269 against the payment instruments held by the 2270 Consumer. 2272 BrandNarrative This optional attribute is 2273 used by the Merchant to indicate some 2274 special conditions or benefit which would 2275 apply if the Consumer selected that brand. 2276 For example "5% discount", "free shipping 2277 and handling", "free breakage insurance for 2278 1 year", "double air miles apply", etc. 2280 CallBackFunction A function which is called whenever there is 2281 a change of Process State or payment 2282 progress, e.g. for display updates. However, 2283 the IOTP Payment Bridge may use its own 2284 mechanisms and dialog boxes. 2286 CallBackLanguageLis A list of language codes which contain, in 2287 t order of preference, the languages in which 2288 the text passed to the Call Back function 2289 will be encoded. 2291 CompletionCode (14) Indicates how the process completed. 2292 It is required if ProcessState is set to 2293 "Failed" otherwise it is ignored. Valid 2294 values as well as recovery options are given 2295 in the IOTP specification. 2297 The IOTP Payment Bridge may also use the 2298 Status Description to notify the Consumer 2299 about further necessary steps in order to 2300 resolve some kind of business failures, 2301 e.g., 2303 o "sorry, your payment transaction failed. 2304 Unfortunately, you have been charged, 2305 please contact your issuer." 2306 o "insufficient capacity left (on your card) 2307 for refund", 2308 o "payment failed/chip card error/internal 2309 error, please contact your payment 2310 instrument's issuer" 2312 ConsumerDesc A narrative description of the Consumer. 2314 ConsumerPayId (14) An unique identifier specified by the 2315 Consumer that, if returned by the Payment 2316 Handler in another Payment Scheme Component 2317 or by other means, enables the Consumer to 2318 identify which payment is being referred to. 2320 This unique identifier is generated by the 2321 IOTP Application Core and submitted to the 2322 IOTP Payment Bridge on every API call. It 2323 may equal to the Payment Handler Payment 2324 Identifiers but need not necessarily be so. 2326 The uniqueness extends to multiple payment 2327 instruments, payment brands, payment 2328 protocols, wallet identifiers, and even 2329 multiple IOTP Payment Bridges. 2331 ContStatus During payment progress, this status value 2332 indicates whether the payment needs to be 2333 continued with further IOTP Payment Scheme 2334 Component exchanges with the remote party. 2335 "End" indicates that the reported payment 2336 scheme data is the last data to be exchanged 2337 with the counter party. 2339 ContentSoftwareId This contains information that identifies 2340 the software that generated the content of 2341 the element. Its purpose is to help resolve 2342 interoperability problems that might occur 2343 as a result of incompatibilities between 2344 messages produced by different software. It 2345 is a single text string in the language 2346 defined by xml:lang. It must contain, as a 2347 minimum: 2349 o the name of the software manufacturer, 2350 o the name of the software, 2351 o the version of the software, and 2352 o the build of the software. 2354 CurrCodeType (14) Indicates the domain of the CurrCode. This 2355 attribute is included so that the currency 2356 code may support nonstandard currencies 2357 such as frequent flyer point, trading 2358 stamps, etc. Its values may be 2360 o ISO-4217-A, the default, indicates the 2361 currency code is the three-letter 2362 alphabetic code that conform to ISO 4217 2364 o IOTP indicates that the values of 2365 CurrCode are managed under the procedure 2366 described in [IOTP]. 2368 CurrCode (14) A code which identifies the currency to be 2369 used in the payment. The domain of valid 2370 currency codes is defined by "CurrCodeType" 2372 MerchantPayId (14) An private identifier specified by the 2373 Merchant which will enable the Merchant to 2374 identify which payment is being referred to. 2375 It is a pure private item and is never sent 2376 to any other party. It is provided by the 2377 IOTP Payment Bridge on payment preparation 2378 during brand compilation. 2380 Cf. To "ConsumerPayId" for note about 2381 uniqueness. 2383 MerchantOrgId (64) A local item that might refer to some 2384 specific shop in a multi shop environment. 2385 This item is optional and might enrich the 2386 Wallet Identifier which itself can be used 2387 for the same purpose. 2389 Name Distinguishes between multiple occurrences 2390 of Packaged Content Elements at the same 2391 point in IOTP. For example: 2393 2394 2395 snroasdfnas934k 2396 2397 2398 dvdsjnl5poidsdsflkjnw45 2399 2400 2401 The "Name" attribute may be omitted, for 2402 example if there is only one Packaged 2403 Content element. 2405 OkFrom (30) The date and time in UTC Format range 2406 OkTo (30) indicated by the merchant in which the 2407 Payment Handler may accept the payment. 2409 Passphrase (32) Payment wallets may use pass phrase 2410 protection for transaction data and payment 2411 instruments' data. However, it is assumed 2412 that there exists a public and customizable 2413 payment instrument identifier such that 2414 these identifiers together with their 2415 relationship to payment brands, payment 2416 protocols, payment directions, and currency 2417 amounts can be inquired by the IOTP 2418 application without any pass phrase 2419 knowledge. 2421 PayDirection Indicates the direction in which the 2422 payment for which a Brand is being selected 2423 is to be made. Its values may be: 2425 o Debit: The sender of the Payment Request 2426 Block (e.g. the Consumer) to which this 2427 Brand List relates will make the payment 2428 to the Payment Handler, or 2429 o Credit: The sender of the Payment Request 2430 Block to which this Brand List relates 2431 will receive a payment from the Payment 2432 Handler. 2434 PayId (14) This attribute is introduced for API 2435 simplification: 2437 o The Consumer has to identify PayId and 2438 ConsumerPayId. 2440 o The Merchant has to identify PayId and 2441 MerchantPayId. 2443 o The Payment Handler has to identify PayId 2444 and Payment Handler Pay Id. 2446 PayInstId This contains the unique identifier used 2447 internally by the IOTP Payment 2448 Bridge/Existing Payment Software. 2450 PayInstName This contains the user-defined name of the 2451 payment instrument. There exist no 2452 (technical) constraints like uniqueness. The 2453 "xml:lang" attribute denotes the language 2454 encoding of its value. 2456 PaymentHandlerDesc A narrative description of the Payment 2457 Handler. 2459 PaymentHandlerPayId An unique identifier specified by the 2460 (14) Payment Handler that, if returned by the 2461 Consumer in another Payment Scheme Component 2462 or by other means, enables the Payment 2463 Handler to identify which payment is being 2464 referred to. It is required whenever it is 2465 known. 2467 Cf. To "ConsumerPayId" for note about 2468 uniqueness. 2470 PaymentInstrumentId An identifier for a specific payment 2471 (32) instrument, e.g. "credit card", "Mondex card 2472 for English Pounds". This identifier is 2473 fully customizable. It is assumed, that it 2474 does not contain confidential information or 2475 even an indication to it. The payment 2476 instrument identifier is unique within each 2477 payment brand. It is displayed to the 2478 Consumer during brand selection. 2480 PayReceiptNameRefs Optionally contains element references to 2481 (32) other elements (containing payment scheme 2482 specific data) that together make up the 2483 receipt. Note that each payment scheme 2484 defines in its supplement the elements that 2485 must be referenced 2487 The IOTP Application Core should save all 2488 the components referenced so that the 2489 payment receipt can be reconstructed when 2490 required. 2492 PayReqNetLocn The Net Location indicating where an 2493 unsecured Payment Request message should be 2494 sent if this protocol choice is used. 2496 The content of this attribute must conform 2497 to [URL] and depends on the Transport 2498 Mechanism. 2500 PercentComplete (3) A number between 0 and 100 which indicates 2501 the progress of the payment transaction. The 2502 values range between 0 and 99 for pending 2503 and suspended transactions. 2505 ProcessState Contains a Process State Code that 2506 indicates the current state of the process 2507 being carried out. Valid values are: 2509 o NotYetStarted. The Payment Request Block 2510 has been received but processing of the 2511 Payment Request has not yet started 2513 o InProgress. The payment transaction is 2514 pending. The processing of the (Payment) 2515 Request Block has started but it is not 2516 yet complete. 2518 o (*)Suspended: The payment transaction has 2519 been suspended and can be resumed. 2521 This process state is mapped to 2522 "InProgress", if it is passed to the 2523 counter party's IOTP Application Core. 2525 o CompletedOk. The processing of the (Payment) 2526 Request Block and any following Payment 2527 Exchange Blocks has completed successfully. 2529 o Failed. The payment processing has finally 2530 failed for a Business Error. 2532 o ProcessError. This value is only used 2533 when the Status Component is being used in 2534 connection with an Inquiry Request Trading 2535 Block. It indicates there was a Technical 2536 Error in the Request Block which is being 2537 processed or some internal processing 2538 error. Each party's IOTP Payment Bridge 2539 uses this value in order to notify the 2540 IOTP Application Core about the presence 2541 of technical errors. 2543 PropertyType (14) The property type defines codes used for 2544 interrogation of specific properties about a 2545 payment instrument. They are unique for each 2546 payment brand. The predefined property "all" 2547 is used on general inquiries. However, these 2548 property types are not used during normal 2549 payment processing. E.g., they may apply to 2550 payment brand specific transactions or out- 2551 of-band failure resolution. 2553 PropertyDesc The property description carries the 2554 respective human readable property (value)'s 2555 description. 2557 PropertyValue The actual property value intends automatic 2558 post processing. 2560 ProtocolBrandId (64)This is an identifier to be used with a 2561 particular payment protocol. For example, 2562 SET and EMV have their own well defined, yet 2563 different, values for the Brand identifier 2564 to be used with each protocol. The valid values 2565 of this attribute are defined in the 2566 supplement for the payment protocol 2567 identified by "ProtocolId" that describes 2568 how the payment protocol works with IOTP. 2569 Identifier maps to at most one Protocol 2570 Brand Identifier. 2572 ProtocolId (64) An identifier for a specific payment 2573 protocol and version, e.g. "SETv1.0", 2574 "ecash". Valid values are defined by 2575 supplements to the IOTP specification and 2576 they are unique within each payment brand. 2578 ProtocolIds A sequence of Protocol Identifiers 2580 ProtocolName A narrative description of the payment 2581 protocol and its version in the language 2582 identified by "xml:lang". For example 2583 "Secure Electronic Transaction Version 1.0". 2584 Its purpose is to help provide information 2585 on the payment protocol being used if 2586 problems arise. 2588 SecPayReqNetLocn The Net Location indicating where a secured 2589 Payment Request message should be sent if 2590 this protocol choice is used. 2592 A secured payment involves the use of a 2593 secure channel such as [SSL]/[TLS] in order 2594 to communicate with the Payment Handler. 2596 The content of this attribute must conform 2597 to [URL]. 2599 ReceiverOrgId The Organization Identification which 2600 receives the payment bridge processing 2601 Trading Role Data PackagedContent. 2603 StatusDesc (256) An optional textual description of the 2604 current process state in the language 2605 identified by "xml:lang" that should be 2606 displayed to the Consumer. The usage of this 2607 attribute is defined in the payment 2608 supplement for the payment method being 2609 used. Particularly, it provides hints for 2610 out-of-band failure resolution. Its length 2611 is limited to 256 characters. 2613 StyleSheetNetLocn This contains the net location to a style 2614 sheet with visualisation rules for XML 2615 encoded data. 2617 TimeStamp (30) The date and time in UTC Format when the 2618 payment transaction has been started. 2620 WalletId (32) Many existing payment wallet software are 2621 multiple wallet capable. The Wallet 2622 Identifier selects the actual wallet. It is 2623 assumed, that the wallet identifier is a 2624 public item, that might be stored by the 2625 IOTP Application Core. 2627 xml:lang Defines the language used by the Process 2628 State Description attribute (cf. IOTP 2629 Specification) 2631 Table 3: Attributes 2633 The following table explains the XML elements in alphabetical 2634 order: 2636 Element Description 2638 Algorithm This contains information which describes 2639 an Algorithm that may be used to generate 2640 the Authentication response. 2642 The algorithm that may be used is 2643 identified by the Name attribute (cf. IOTP 2644 Specification). 2646 AuthReqPackagedContent The Authentication Request Packaged 2647 Content originates from a Authentication 2648 (Data/Response) Component's content 2649 whereby the outermost element tags are 2650 prefixed with "AuthReq". Its declaration 2651 coincides with the Packaged Content's 2652 declaration (cf. IOTP Specification). It 2653 encapsulates the authentication challenge 2654 value. The content of this information is 2655 defined in the supplement for a payment 2656 protocol. 2658 AuthResPackagedContent The Authentication Response Packaged 2659 Content originates from a Authentication 2660 Response Component's content whereby the 2661 outermost element tags are prefixed with 2662 "AuthRes". 2664 Its declaration coincides with the 2665 Packaged Content's declaration (cf. IOTP 2666 Specification). It encapsulates the 2667 authentication response value. The 2668 content of this information is defined in 2669 the supplement for a payment protocol. 2671 BrandPackagedContent Container for further payment brand 2672 description. Its content originates from 2673 a Brand Element content whose outermost 2674 element tags are prefixed with "Brand". 2675 Its declaration coincides with the 2676 Packaged Content's declaration (cf. IOTP 2677 Specification). 2679 BrandSelBrandInfoPacka This contains any additional data that 2680 gedContent may be required by a particular payment 2681 brand. It forms the content of the Brand 2682 Selection Brand Info Element. 2684 BrandSelProtocolAmount This contains any additional data that 2685 InfoPackagedContent may be required by a particular payment 2686 brand in the format. It forms the content 2687 of the Brand Selection Protocol Amount 2688 Info Element. 2690 BrandSelCurrencyAmount This contains any additional data that 2691 InfoPackagedContent payment brand and currency specific in 2692 the format. It forms the content of the 2693 Brand Selection Currency Amount Info 2694 Element. 2696 MerchantData Any merchant related data that might be 2697 used by the IOTP Payment Bridge for 2698 different purposes, e.g., it might 2699 contain access keys to some mall keys. 2700 Its declaration coincides with the 2701 Packaged Content's declaration (cf. IOTP 2702 Specification). 2704 PackagedContent Generic Container for non-IOTP data (cf. 2705 IOTP Specification). 2707 PayProtocolPackaged The Pay Protocol Packaged Content 2708 Content originates from a Pay Protocol 2709 Element's content whereby the outermost 2710 element tags are prefixed with 2711 "PayProtocol". It contains information 2712 about the protocol which is used by 2713 the payment protocol. The content of 2714 this information is defined in the 2715 supplement for a payment protocol.Its 2716 declaration coincides with the Packaged 2717 Content's declaration (cf. IOTP 2718 Specification). 2720 PaySchemePackagedConte The PayScheme Packaged Content originates 2721 nt from a Payment Scheme Component's content 2722 whereby the outermost element tags are 2723 prefixed with "PayScheme". Its 2724 declaration coincides with the Packaged 2725 Content's declaration (cf. IOTP 2726 Specification). It carries the payment 2727 specific data. The content of this 2728 information is defined in the supplement 2729 for a payment protocol. 2731 ProtocolAmountPackaged The Protocol Amount Packaged Content 2732 Content originates from a Protocol Amount 2733 Element's content whereby the outermost 2734 element tags are prefixed with "Amount". 2735 Its declaration coincides with the 2736 Packaged Content's declaration (cf. IOTP 2737 Specification). It contains information 2738 about the protocol which is used by the 2739 payment protocol. The content of this 2740 information is defined in the supplement 2741 for a payment protocol. 2743 ProtocolBrandPackagedC The Protocol Brand Packaged Content 2744 ontent originates from a Protocol Brand 2745 Element's content whereby the outermost 2746 element tags are prefixed with 2747 "ProtocolBrand". Its declaration 2748 coincides with the Packaged Content's 2749 declaration (cf. IOTP Specification). It 2750 contains information about the brand 2751 which might be used by the payment 2752 protocol. The content of this information 2753 is defined in the supplement for a 2754 payment protocol. 2756 ResponsePackagedConten Container for authentication response 2757 t data. Its content originates from a 2758 Authentication Response Component's 2759 Packaged Content whose outermost element 2760 tags are prefixed with "Response". Its 2761 declaration coincides with the Packaged 2762 Content's declaration (cf. IOTP 2763 Specification). 2765 TradingRoleDataPackage The TradingRoleData Packaged Content 2766 dContent originates from a TradingRoleData 2767 Component's content whereby the outermost 2768 element tags are prefixed with 2769 "TradingRoleData". Its declaration 2770 coincides with the Packaged Content's 2771 declaration (cf. IOTP Specification). It 2772 contains information from Merchant to 2773 Payment Handler via Consumer about the 2774 protocol which is used by the payment. 2775 The content of this information is 2776 defined in the supplement for a payment 2777 protocol. The Name attribute in this 2778 packaged contents must include prefix as 2779 "Payment:" to indicate that the payment 2780 bridge processes this, for example 2781 "Payment:SET-OD" 2783 The element's declaration coincides with 2784 the Packaged Content's declaration (cf. 2785 IOTP Specification). 2786 Table 4: Elements 2788 XML definition: 2792 2799 2803 2805 2807 2809 3.3 Process States 2810 The IOTP Payment API supports six different attribute values that 2811 encode the transaction status from the IOTP's point of view, i.e. the 2812 appropriate point of view at the interface between the IOTP 2813 Application Core and IOTP Payment Bridge. This point of view does not 2814 completely mimic the more detailed view on the actual payment by the 2815 genuine Existing Payment Software or IOTP Payment Bridge. 2817 The following three tables distinguish between the Merchant's, 2818 Consumer's, and Payment Handlers' environment. They extend the 2819 aforementioned explanations towards the mapping between IOTP process 2820 states and the internal payment scheme related states of the Existing 2821 Payment Software/IOTP Payment Bridge. 2823 3.3.1 Merchant 2825 The Merchant's point of view of payment is limited to the local 2826 payment initiation being interlaced with order processing because 2827 IOTP assigns the actual payment processing to the Payment Handler. 2829 ProcessState Description 2830 NotYetStarted The Payment Transaction exists within the 2831 IOTP Application Core, i.e., the 2832 Merchant's shop has already signaled to 2833 the IOTP Application Core that an IOTP 2834 transaction has been initiated by the 2835 Consumer. 2837 However, neither any API call has been 2838 issued to the IOTP Payment Bridge nor the 2839 IOTP Order Request has been created. 2841 InProgress The IOTP Application changes the process 2842 state to this value when it issues the 2843 first API call to the Payment Bridge 2844 during Brand List compilation. 2846 This value indicates that the Payment 2847 Bridge might have some knowledge about 2848 the expected payment or might have 2849 performed some preparatory tasks (even 2850 with the Payment Handler out-of-band to 2851 IOTP). 2853 However, this value does not indicate 2854 that some IOTP Order Request has been 2855 created and transmitted to the Consumer. 2857 Suspended The IOTP transaction has been suspended 2858 before the order request block has been 2859 transmitted to the Consumer. 2861 Implicitly, the payment is also deferred. 2863 CompletedOk The IOTP Order Request has been 2864 successfully created and transmitted to 2865 the Consumer. Actually, this process 2866 state indicates only that the order 2867 processing has been finished. 2869 But it contains no indication about the 2870 status of the genuine payment, which is 2871 accepted by the Payment Handler. 2873 However, successful order processing 2874 signals the IOTP Application Core that a 2875 payment with some specific parameters is 2876 expected within the near future. And this 2877 signal might be used by the Existing 2878 Payment Software for similar purposes. 2879 This attribute might be interpreted as 2880 successful preparation of the payment 2881 system. 2883 Particularly, it is expected that the 2884 Existing Payment Software maps this IOTP 2885 status value to some other internal 2886 value, e.g. "NotYetStarted", that is more 2887 accurate from its point of view. 2889 As IOTP provides no communication channel 2890 between the Merchant and Payment Handler, 2891 any change of payment process state will 2892 be initiated out-of-band to IOTP, e.g. by 2893 electronic statements of account or 2894 payment scheme specific mechanisms. 2896 Failed The IOTP transaction, i.e. order 2897 processing, has failed for some 2898 (business) reason and it is known that no 2899 payment will occur. 2901 This indication might be used to clear 2902 all data about this transaction within 2903 the Existing Payment Bridge (by 2904 "RemovePaymentLog" or 2905 "ChangeProcessState") or to reverse any 2906 preparation (with the Payment Handler 2907 out-of-band to IOTP). 2909 However, the ideal point of view of IOTP 2910 suspects that the genuine payment 2911 transaction has been neither started nor 2912 initiated. 2914 ProcessError The IOTP transaction, i.e. order 2915 processing, has failed for some 2916 (technical) reason and it is known that 2917 no payment will occur. 2919 This indication might be used to clear 2920 all data about this transaction within 2921 the Existing Payment Bridge (by 2922 "RemovePaymentLog" or 2923 "ChangeProcessState") or to reverse any 2924 preparation (with the Payment Handler 2925 out-of-band to IOTP). 2927 However, the ideal point of view of IOTP 2928 suspects that the genuine payment 2929 transaction has been neither started nor 2930 initiated. 2931 Table 5: Merchant 2933 3.3.2 Consumer 2935 The Consumer's IOTP Application Core restricts its point of view to 2936 the payment transaction. It is assumed that the IOTP Payment Bridge 2937 handles the preceding brand selection process in a stateless manner. 2939 NotYetStarted This encodes the initial process state of 2940 any IOTP payment transaction. This value 2941 is set during brand selection but it will 2942 not change during the whole brand 2943 selection process, normally. 2945 InProgress With the issuance of the Start Payment 2946 Consumer API call, the IOTP Application 2947 Core changes the process state to this 2948 value. 2950 Suspended The payment transaction has been 2951 suspended. Suspension may occur anywhere 2952 during brand selection (with the 2953 Merchant) or payment processing (with the 2954 Payment Handler). On resumption, the IOTP 2955 Application Core and the IOTP Payment 2956 Bridge have to use other internal data to 2957 decide whether brand selection or actual 2958 payment processing needs to be continued, 2959 i.e., whether the process state needs to 2960 be reset to "NotYetStarted" or 2961 "InProgress". 2963 Note that the Payment API assumes 2964 stateless brand selection by the IOTP 2965 Payment Bridge. Typically, any suspension 2966 during brand selection requires the 2967 repetition of the whole process. Hereby, 2968 the IOTP Application Core might to 2969 consider any already negotiated 2970 conditions in a brand depended purchase 2971 (brand, protocol). 2973 CompletedOk The successful payment has been 2974 acknowledged by the Payment Handler, i.e. 2975 the successful IOTP Payment Response has 2976 been received. 2978 Implicitly, this implies successful order 2979 processing. 2981 Failed The IOTP transaction, i.e. order or 2982 payment processing, has failed for some 2983 (business) reason. In either case it is 2984 known that the payment will not succeed. 2986 ProcessError The IOTP transaction, i.e. order or 2987 payment processing, has failed for some 2988 (technical) reason. 2990 However, the local process state might be 2991 different from that of Payment Handler. 2993 Table 6: Consumer 2995 3.3.3 Payment Handler 2997 The Payment Handler is responsible for the actual payment processing. 2998 New payment transactions are reported by the Consumer with the 2999 transmission of new IOTP Payment Request Blocks. IOTP Payment 3000 Exchange Block are send by the Consumer for payment transaction 3001 continuation and resumption. 3003 NotYetStarted This encodes the initial process state of 3004 any payment transaction. Typically, this 3005 value will last for a short amount of 3006 time. 3008 InProgress The IOTP Application Core changes the 3009 process state changes to "InProgress" 3010 when the Payment Handler starts with the 3011 actual processing of the IOTP Payment 3012 Request Block. 3014 Note that this does not assume that the 3015 "StartPaymentPaymentHandler" API function 3016 has been called. 3018 Suspended The payment transaction has been 3019 suspended. 3021 CompletedOk The payment has been processed, 3022 successfully, i.e. the IOTP Payment 3023 Response Block was created and 3024 transmitted to the Consumer. 3026 Failed The payment transaction, has finally 3027 failed for some (business) reason. 3029 Note that this value encodes the payment 3030 state reported by the IOTP Payment Bridge 3031 on "InquireProcessState". It does neither 3032 reflect whether the payment receipt has 3033 been inquired nor whether the IOTP 3034 Payment Response Block has been created 3035 and submitted to the Consumer. 3037 ProcessError The payment transaction, has finally 3038 failed for some (technical) reason. 3040 Note that this value encodes the payment 3041 state reported by the IOTP Payment 3042 Bridge. It does not reflect whether some 3043 IOTP Error Block has been created and 3044 submitted to the Consumer. 3045 Table 7: Consumer 3047 4. Payment API Calls 3049 4.1 Brand Compilation Related API Calls 3051 4.1.1 Find Accepted Payment Brand 3053 This API finction determines the payment brands being accepted by the 3054 Payment Handler on behalf of the Merchant. 3056 Input Parameters 3058 o Payment Direction - provided by the IOTP Application Core 3059 o Currency Code and Currency - provided by the IOTP Application 3060 Core 3061 o Payment Amount - provided by the IOTP Application Core 3062 o Merchant Payment Identifier - Merchant's unique private 3063 reference to the payment transaction 3064 o Merchant Organisation Identifier - used for distinction between 3065 multiple merchants that share the some IOTP merchant system 3066 o Wallet Identifier - managed by the IOTP Application Core 3067 o Merchant Data - specific data used by the IOTP Payment Bridge 3068 which is managed in the IOTP Application Core. 3070 XML definition: 3072 3073 3082 Output Parameters 3084 o Payment Brand Identifier - for insertion in the Brand List 3085 Component's Brand Element 3086 o Payment Brand Name and language annotation - for insertion in 3087 the Brand List Component's Brand Element 3088 o Payment Brand Logo Net Location - for insertion in the Brand 3089 List Component's Brand Element 3090 o Payment Brand Narrative Description - for insertion in the 3091 Brand List Component's Brand Element 3092 o (Brand) Packaged Content - further payment brand description 3093 for insertion in the Brand List Component's Brand Element 3095 The Existing Payment Software returns an empty list of brand items, 3096 if it does not support any payment brand/payment protocol combination 3097 for the given payment parameters. 3099 XML definition: 3101 3102 3103 3110 Tables 4 and 5 explain the attributes and elements; Table 3 3111 introduces the Error Codes. 3113 4.1.2 Find Accepted Payment Protocol 3115 This API function determines the instances of payment protocols (and 3116 optionally the payment brands) being accepted by the Payment Handler 3117 on behalf of the Merchant. The function might be called in two 3118 variants: 3120 o With the Brand Identifier set on the input parameter list: The 3121 function responds with the payment protocols that fits to the 3122 submitted brand. 3124 o Without any Brand Identifier - that allows the omission of the 3125 "Find Accepted Payment Brand" API call (cf. Section 4.1.1): This 3126 function responds with both the supported brand identifiers and 3127 the payment protocols being related by the Brand Elements. 3129 Input Parameters 3131 o Brand Identifier - returned by "Find Accepted Payment Brand" 3132 o Payment Direction 3133 o Currency Code and Currency 3134 o Payment Amount 3135 o Merchant Payment Identifier - Merchant's unique private 3136 reference to the payment transaction 3137 o Merchant Organisation Identifier - used for distinction between 3138 multiple merchants that share the some IOTP merchant system 3139 o Wallet Identifier - managed by the IOTP Application Core 3140 o (Brand) Packaged Content - further payment brand description; 3141 returned by "Find Accepted Payment Brand"; this elements are 3142 only provided iff the Brand Identifier is set 3143 o Merchant Data - specific data used by the IOTP Payment Bridge 3144 which is managed in the IOTP Application Core. 3146 XML definition: 3148 3150 3160 Output Parameters 3162 o Payment Protocol Identifier - for insertion in the Brand List 3163 Component's Pay Protocol Element 3164 o Protocol Brand Identifier - for insertion in the Protocol Brand 3165 Element of the Brand List Component's Brand Element 3166 o Payment Protocol Name and language annotation- for insertion in 3167 the Brand List Component's Pay Protocol Element 3168 o Payment Request Net Location - for insertion in the Brand List 3169 Component's Pay Protocol Element 3170 o Secured Payment Request Net Location - for insertion in the 3171 Brand List Component's Pay Protocol Element 3172 o Brand Item List (cf. Section 4.1.1) - there must be at least 3173 one element if no brand identifier has been provided on the 3174 input parameter list. 3175 o (Protocol Amount) Packaged Content - for insertion in the Brand 3176 List Component's Protocol Amount Element 3177 o (Pay Protocol) Packaged Content - for insertion in the Brand 3178 List Component's Pay Protocol Element 3179 o Currency Amount element - quite similar to the definition in 3180 [IOTP], that contain 3181 - refined Currency Code and Currency - for insertion in the 3182 Brand List Component's Currency Amount Element 3183 - refined Payment Amount - for insertion in the Brand List 3184 Component's Currency Amount Element 3185 o Brand - there must be at least one element in each Protocol 3186 Item if no brand identifier has been provided on the input 3187 parameter list. 3189 XML definition: 3191 3193 3196 3204 3205 3208 3209 3214 Tables 4 and 5 explain the attributes and elements; Table 3 3215 introduces the Error Codes. 3217 4.1.3 Get Payment Initialization Data 3219 This API function provides the remaining initialization data being 3220 required by the Consumer's or Payment Handler's Existing Payment 3221 Software. This function might be called both for "brand dependent" 3222 and "brand independent" transaction types. In ether case, this 3223 function is called with one particular brand. 3225 Input Parameters 3227 o Brand Identifier - returned by "Find Accepted Payment Brand" 3228 o Merchant Payment Identifier - Merchant's unique private 3229 reference to the payment transaction 3231 o Payment Direction 3232 o Currency Code and Currency - from the Brand List Component's 3233 Currency Amount Element 3234 o Payment Amount - from the Brand List Component's Currency 3235 Amount Element 3236 o Payment Protocol Identifier - from the Brand List Component's 3237 Pay Protocol Element 3238 o Protocol Brand Identifier - from the Protocol Brand Element 3239 which relates to the selected Brand Element, if any 3241 o (TradingRoleData) Receiver Organization Identifier 3243 o OkFrom, OkTo - identical to the entries of the Order Component 3245 Merchant Payment Identifier 3247 o Merchant Organisation Identifier - used for distinction between 3248 multiple merchants that share the some IOTP merchant system 3249 o Wallet Identifier and/or Pass Phrase 3251 Protocol Brand Element 3253 o (Brand) Packaged Content - further payment brand description, 3254 from the Brand List Component's Brand Element 3255 o (Protocol Amount) Packaged Content - further payment protocol 3256 description, from the Brand List Component's Protocol Amount 3257 Element 3258 o (Pay Protocol) Packaged Content - further payment protocol 3259 description, from the Brand List Component's Pay Protocol 3260 Element 3262 o (Protocol Brand) Packaged Content - further brand information, 3263 from the Protocol Brand Element of the Brand List Component 3264 which relates to the selected Brand Element, if any 3266 o (Order) Packaged Content - further order description, from the 3267 Order Element 3268 o three Brand Selection Info Packaged Content elements - copied 3269 from the Brand Selection Component on brand dependent purchases 3270 o Brand - additional data about the payment brand 3271 o Protocol Amount - additional data about the payment protocol 3272 o Currency Amount - additional payment brand and currency 3273 specific data 3274 o Merchant Data - specific data used by the IOTP Payment Bridge 3275 which is managed in the IOTP Application Core. 3277 XML definition: 3279 3288 3303 Output Parameters 3305 o OkFrom, OkTo - for insertion in the Payment Component 3306 o (TradingRoleData) Packaged Content - further payment protocol 3307 description; the Name Attribute of the packaged Content 3308 element must include "Payment:" as the prefix, 3309 for example "Payment:SET-OD". 3310 o (Order) Packaged Content - defaults to the supplied order 3311 packaged content if omitted. 3313 XML definition: 3315 3318 3322 Tables 4 and 5 explain the attributes and elements; Table 3 3323 introduces the Error Codes. 3325 4.1.4 Inquire Authentication Challenge 3327 This API function inquires any payment protocol specific 3328 authentication challenge value from the IOTP Payment Bridge. In 3329 Baseline IOTP this API function is called by the Merchant (or 3330 Financial Institution). The IOTP Application Core may propose a 3331 choice of algorithms to the IOTP Payment Bridge. However, the IOTP 3332 Payment Bridge may ignore the proposal and select some other 3333 algorithm. 3335 The inquiry is assumed to be stateless. E.g., the IOTP Application 3336 Core may check the returned algorithm and stop transaction processing 3337 without notifying the IOTP Payment Bridge. 3339 The IOTP Application Core may issue several API calls to the IOTP 3340 Payment Bridge to build up the IOTP Authentication Request Block. Any 3341 subsequently submitted choice of algorithms should be reduced by the 3342 accepted algorithms from earlier API responses. 3344 The IOTP Payment Bridge responds with the Business Error Code if it 3345 does not provide any (more) authentication algorithms and challenges. 3347 Input Parameters 3349 o Authentication Identifier - the authenticator may provide its 3350 payment identifier, i.e., Payment Handler or Merchant Payment 3351 Identifier. 3352 o Wallet Identifier and/or Pass Phrase 3353 o set of pre-selected algorithms for authentication 3355 XML definition: 3357 3358 3363 Output Parameters 3365 o list of Authentication Challenge Packaged Contents - for 3366 insertion into the IOTP Authentication Request Component 3367 o Algorithm Element - for insertion into the IOTP Authentication 3368 Request Component 3370 XML definition: 3372 3375 Tables 4 and 5 explain the attributes and elements; Table 3 3376 introduces the Error Codes. 3378 4.1.5 Authenticate 3380 The Consumer's IOTP Application Core defers payment protocol specific 3381 authentication processing and the current challenge value to the 3382 active IOTP Payment Bridge. Alternative authentication algorithms 3383 might be tried sequentially or offered to the user for selection. 3385 Note that the IOTP Application Core has to consider both the current 3386 context and the algorithm in order to determine the responsible IOTP 3387 Payment Bridge. 3389 Failed authentication is reported by the Business Error Code which 3390 might trigger the inquiry of the details ("Inquire Process State"). 3391 Final failures might be encoded by the process state "Failed". 3393 Input Parameters 3395 o Authentication Identifier 3396 o Wallet Identifier and/or Pass Phrase 3397 o Authentication Challenge Packaged Content - copied from the 3398 IOTP Authentication Request Component 3399 o Algorithm Element - copied from the IOTP Authentication Request 3400 Component 3402 XML definition: 3404 3405 3410 Output Parameters 3412 o Authentication Response Packaged Content - for insertion into 3413 the IOTP Authentication Response Component 3415 XML definition: 3417 3419 Tables 4 and 5 explain the attributes and elements; Table 3 3420 introduces the Error Codes. 3422 4.1.6 Check Authentication Response 3424 This API function verifies the Consumer's payment protocol specific 3425 authentication response. In Baseline IOTP this API function is called 3426 by the Merchant (or the Financial Institution). It is called only if 3427 the counter party has responded with an IOTP Authentication Response 3428 Component within the Authentication Response Block. Of course, the 3429 IOTP Application Core traces the need of such an response. 3431 Due to the authentication's statelessness, all parameters (algorithm, 3432 challenge and response) are submitted to the IOTP Payment Bridge. 3433 Authentication failure is reported by a Process State different from 3434 "CompletedOK". 3436 Input Parameters 3438 o Authentication Identifier 3439 o Wallet Identifier and/or Pass Phrase 3440 o Authentication Challenge Packaged Content - generated by 3441 previous "Inquire Authentication Challenge" API call 3442 o Algorithm Element 3443 o Authentication Response Packaged Content - copied from the 3444 Authentication Response Component 3446 XML definition: 3448 3450 3455 Output Parameters 3457 o Current Process (Authentication) State 3458 o Completion Code 3459 o Status Description and its language annotation 3461 XML definition: 3463 3464 3475 Tables 4 and 5 explain the attributes and elements; Table 3 3476 introduces the Error Codes. 3478 4.2 Brand Selection Related API Calls 3480 4.2.1 Find Payment Instrument 3482 This API function determines which instances of a Payment Brand, 3483 e.g., two Mondex cards, are present. The same physical card may even 3484 represent multiple payment instruments. 3486 The IOTP Application Core supplies possible payment brand and payment 3487 protocol to the IOTP Payment Bridge that has to be considered when 3488 the IOTP Payment Bridge searches for appropriate payment instruments. 3489 This set represents the (sub)set of payment alternatives being 3490 supported by the Merchant. If the IOTP Application Cote has multiple 3491 possible payment brand/protocol, it can call this function in turn. 3493 The Existing Payment Software responds with PayInstrument Elements 3494 with empty PayInstId attributes if it does not distinguish between 3495 different payment instruments for the particular payment 3496 alternatives. 3498 Note that the Payment API assumes that the values of the attributes 3499 BrandId, ProtocolId, ProtocolBrandId and the currency amount suffice 3500 for the determination of the appropriate Packaged Content Element 3501 that will be transmitted to the Payment Handler later on. 3503 Input Parameters 3505 o Brand Identifier - copied from the Brand List Component's Brand 3506 Element 3507 o Payment Protocol Identifier and associated Protocol Brand 3508 Identifier 3509 o Payment Direction - copied from the Brand List Component 3510 o Currency Code and Currency - copied from the Currency Amount 3511 Element 3512 o Payment Amount - copied from the Currency Amount Element 3513 o Consumer Payment Identifier - Consumer's unique reference to 3514 the current payment transaction 3515 o Wallet Identifier - managed by the IOTP Application Core 3516 o (Brand) Packaged Content - further payment brand description; 3517 copied from the Brand List Component's Brand Element 3518 o (Protocol Brand) Element - further information; copied from the 3519 Protocol Brand Element of the Brand List Component which 3520 relates to the Consumer selected Brand Element, if any. 3522 o (Protocol Amount) Packaged Content - further payment protocol 3523 description, copied from the Brand List Component's Protocol 3524 Amount Element 3525 o Element (Protocol) Packaged Content - further payment protocol 3526 description, copied from the Brand List Component's Pay 3527 Protocol Element 3529 XML definition: 3531 3535 3545 Output Parameters 3547 o The known Payment Instrument Identifiers, these are internal 3548 values 3549 o The user-defined names of the payment instrument and their 3550 language encoding 3552 The Existing Payment Software responds with an empty list of 3553 identifiers, either if it does not distinguish between different 3554 payment instruments or if there are no registered payment instruments 3555 available despite brand support for at least one (unspecified) 3556 payment protocol. In the latter case, the IOTP Payment Bridge has to 3557 request the registration of a suitable payment instrument at a 3558 subsequent step of the payment process. 3560 XML definition: 3562 3563 3564 3569 Tables 4 and 5 explain the attributes and elements; Table 3 3570 introduces the Error Codes. 3572 4.2.2 Check Payment Possibility 3574 This API function checks whether a payment (both debit and credit) 3575 can go ahead. It can be used, for example, to check 3577 o if there are sufficient funds available in a particular 3578 currency for an electronic cash payment brand, 3579 o whether there is sufficient value space left on the payment 3580 instrument for payment refund, 3581 o whether required system resources are available and properly 3582 configured, e.g., serial ports or baud rate, 3583 o whether environment requirements are fulfilled, e.g., chip card 3584 reader presence or Internet connection. 3586 If the payment method bases on external components, e.g., magnetic 3587 stripe or chip cards, and the check accesses the medium, the existing 3588 payment method should not mutually exclusive lock system resources, 3589 e.g., serial port or modem, that may also be required by other 3590 Existing Payment Software, e.g., multiple payment software components 3591 may share the same card reader. If this happens for API internal 3592 request processing, the function has to unlock these components prior 3593 to return. Otherwise, the payment may not proceed if the Consumer 3594 cancels immediately and decides to use another payment instrument. In 3595 this event the previous IOTP Payment Bridge is not notified about the 3596 change. 3598 This function call happens immediately after the Consumer's payment 3599 instrument selection. For example, if the payment instrument is a 3600 chip card, that is not inserted in the chip card reader, the Consumer 3601 may be prompted for its insertion. However, the Consumer should be 3602 able to hit some 'skip' button, if the payment check is part of the 3603 actual payment protocol, too. Finally, the IOTP Payment Bridge may 3604 provide only a subset of these capabilities or may even directly 3605 generate a successful response without any checks. 3607 Input Parameters 3609 o Brand Identifier - user selection 3610 o Payment Instrument Identifier - user selection 3611 o Currency Code and Currency Code Type - copied from the selected 3612 Currency Amount Element 3613 o Payment Amount - copied from the selected Currency Amount 3614 Element 3615 o Payment Direction - copied from the selected Trading Protocol 3616 Option Block 3617 o Protocol Identifier - copied from the selected Pay Protocol 3618 Element 3619 o Protocol Brand Identifier - copied from the selected Protocol 3620 Brand Element of the Brand List Component which relates to the 3621 selected Brand Element, if any 3623 o Consumer Payment Identifier - Consumer's unique reference to 3624 the current payment transaction 3625 o Wallet Identifier and/or Pass Phrase 3626 o (Brand) Packaged Content - copied from the selected Brand 3627 Element 3628 o (Protocol Amount) Packaged Content - copied from the selected 3629 Protocol Amount Element 3630 o (Protocol) Packaged Content - copied from the selected Pay 3631 Protocol Element 3632 o (Protocol Brand) Packaged Content - copied from the selected 3633 Protocol Brand Element of the Brand List Component which 3634 relates to the selected Brand Element, if any 3636 XML definition: 3638 3642 3654 Output Parameters 3656 o three Brand Selection Info Packaged Content elements - for 3657 insertion into the Brand Selection component 3658 o Brand - additional data about the payment brand 3659 o Protocol Amount - additional data about the payment protocol 3660 o Currency Amount - additional payment brand and currency 3661 specific data 3663 XML definition: 3665 3669 3671 Tables 4 and 5 explain the attributes and elements; Table 3 3672 introduces the Error Codes. 3674 4.3 Payment Transaction Related API calls 3676 These Payment API calls may be made either by the Consumer's or 3677 Payment Handler's IOTP Application Core. 3679 4.3.1 Start Payment Consumer 3681 This API function initiates the genuine payment transaction at the 3682 Consumer side. The IOTP Payment Bridge and the Existing Payment 3683 Software perform all necessary initialization and preparation for 3684 payment transaction processing. This includes the reservation of 3685 external periphery. E.g., 1) the Consumer's chip card reader needs to 3686 be protected against access from other software components, 2) the 3687 insertion of the chip card may be requested, 3) the Internet 3688 connection may be re-established, or 4) the Payment Handler may open 3689 a mutual exclusive session to the security hardware. 3691 The IOTP Payment Bridge monitors the payment progress and stores the 3692 current payment states such that resumption - even after power 3693 failures - remains possible. Note that the IOTP Application Core 3694 supplies only a subset of the following input parameter to the 3695 associated resumption API function and refers to the payment 3696 transaction through the party's payment identifier. 3698 Input Parameters 3700 o Brand Identifier - copied from the selected Brand Element 3701 o Payment Instrument Identifier - the user selection 3702 o Currency Code and Currency - copied from the selected Currency 3703 Amount Element 3704 o Payment Amount - copied from the selected Currency Amount 3705 Element 3706 o Payment Direction - copied from the Brand List Component 3707 o Protocol Identifier - copied from the selected Payment Protocol 3708 Element 3709 o Protocol Brand Element - further information; copied from the 3710 Protocol Brand Element of the Brand List Component which 3711 relates to the selected Brand Element, if any 3712 o OkFrom, OkTo - copied from the Payment Component 3713 o Consumer Payment Identifier - Consumer's unique reference to 3714 the current payment transaction 3715 o Wallet Identifier and/or Pass Phrase 3716 o Call Back Function - used for end user notification/logging 3717 purposes 3718 o Call Back Language List. This list is required if the Call Back 3719 Function is set 3720 o (Brand) Packaged Content - further payment brand description; 3721 copied from the selected Brand Element's content 3723 o (Protocol Amount) Packaged Content - further payment protocol 3724 description; copied from the selected Protocol Amount Element's 3725 content 3726 o (Payment Protocol) Packaged Content - further payment protocol 3727 description; copied from the selected Pay Protocol Element's 3728 content 3729 o (Order) Packaged Content - further order description, copied 3730 from the Order Component 3732 XML definition: 3734 3739 3756 Output Parameters 3758 o Continuation Status 3759 o (Payment Scheme) Packaged Content - for insertion into the 3760 Payment Scheme Component of the IOTP Payment Request Block 3762 The IOTP Application Core is allowed to reissue this request several 3763 times on failed analyses of the response. 3765 XML definition: 3767 3769 3772 Tables 4 and 5 explain the attributes and elements; Table 3 3773 introduces the Error Codes. 3775 4.3.2 Start Payment Payment Handler 3777 This API function initializes the Consumer initiated payment 3778 transaction at the Payment Handler's side. Similar to the Consumer's 3779 system, the IOTP Payment Bridge and the Existing Payment Software 3780 perform all necessary initialization and preparation for payment 3781 transaction processing. 3783 Input Parameters 3785 o Brand Identifier - copied from the Consumer selected Brand 3786 Element 3787 o Consumer Payment Identifier - copied from the Payment Scheme 3788 Component 3789 o Currency Code and Currency - copied from the Consumer selected 3790 Currency Amount Element 3791 o Payment Amount - copied from the Consumer selected Currency 3792 Amount Element 3793 o Payment Direction - copied from the Brand List Component 3794 o Protocol Identifier - copied from the Consumer selected 3795 Payment Protocol Element 3796 o Protocol Brand Identifier - copied from the Brand Protocol 3797 Element of the Brand List Component which relates to the 3798 Consumer selected Brand Element, if any 3799 o OkFrom, OkTo - copied from the Payment Component 3800 o Payment Handler Payment Identifier - Payment Handler's unique 3801 reference to the current payment transaction 3802 o Merchant Organisation Identifier - copied from the Merchant's 3803 Organisation Element 3804 o Wallet Identifier - renaming to till identifier neglected - 3805 and/or Pass Phrase 3806 o Call Back Function - used for end user notification/logging 3807 purposes 3808 o Call Back Language List. This list is required if the call back 3809 function is set 3810 o (Brand) Packaged Content - further payment brand description; 3811 copied from the Consumer selected Brand Element's content 3812 o (Protocol Brand) Packaged Content - further information; copied 3813 from the Protocol Brand Element of the Brand List Component 3814 which relates to the Consumer selected Brand Element, if any. 3815 o (Protocol Amount) Packaged Content - further payment protocol 3816 description; copied from the Consumer selected Protocol Amount 3817 Element's content 3818 o (Protocol) Packaged Content - further payment protocol 3819 description; copied from the Consumer selected Pay Protocol 3820 Element's content 3821 o (TradingRoleData) Packaged Content - further payment protocol 3822 description; the Name Attribute of the packaged contents must 3823 include "Payment:" as the prefix, for example "Payment:SET-OD". 3824 o Three Brand Selection Info Packaged Content Elements - copied 3825 from the Brand Selection Component 3826 o Brand - additional data about the payment brand 3827 o Protocol Amount - additional data about the payment protocol 3828 o Currency Amount - additional payment brand and currency 3829 specific data 3830 o (Payment Scheme) Packaged Content. 3832 XML definition: 3834 3843 3860 Output Parameters 3862 o Continuation Status 3863 o (Payment Scheme) Packaged Content - for insertion into the 3864 Payment Scheme Component of the IOTP Payment Exchange Block 3866 The response message must contain payment schema data if the 3867 continuation status signals "Continue". The IOTP Application Core is 3868 allowed to reissue this request several times on failed analyses of 3869 the response. 3871 XML definition: 3873 3875 3878 Tables 4 and 5 explain the attributes and elements; Table 3 3879 introduces the Error Codes. 3881 4.3.3 Resume Payment Consumer 3883 This API function resumes a previously suspended payment at the 3884 Consumer side. Resumption includes the internal inquiry of the 3885 payment transaction data, e.g., payment amount, protocol identifier, 3886 and the whole initialization as it has been applied on the "Start 3887 Payment Consumer" API request. 3889 It is up to the IOTP Application Core to decide whether an IOTP 3890 Payment equest Block or a IOTP Payment Exchange Block needs to be 3891 generated. One indicator might be the receipt of a previous IOTP 3892 Payment Exchange Block from the Payment Handler, e.g., the knowledge 3893 of the Payment Handler Payment Identifier. 3895 Input Parameters 3897 o Consumer Payment Identifier 3898 o Wallet Identifier and/or Pass Phrase 3899 o Call Back Function - used for end user notification/logging 3900 purposes 3902 XML definition: 3904 3905 3912 Output Parameters 3914 o Continuation Status 3915 o (Payment Scheme) Packaged Content - for insertion in the 3916 Payment Scheme Component of the next IOTP message (Payment 3917 Exchange or Request Block). 3919 The IOTP Application Core is allowed to reissue this request several 3920 times on failed analyses of the response. However, the IOTP Payment 3921 Bridge might reject the resumption request by using the "AttNotSupp" 3922 Error Code "naming" the Consumer Payment Identifier attribute. Then 3923 the Consumer has to apply normal error processing to the current 3924 (sub-)transaction and to issue a new Payment Request Block to the 3925 Payment Handler. 3927 XML definition: 3929 3931 3934 Tables 4 and 5 explain the attributes and elements; Table 3 3935 introduces the Error Codes. 3937 4.3.4 Resume Payment Payment Handler 3939 This API function resumes a payment at the Payment Handler side. 3941 Input Parameters 3943 o Payment Handler Payment Identifier 3944 o Wallet Identifier - renaming to till identifier neglected - and 3945 Pass Phrase 3946 o Call Back Function - used for end user notification/logging 3947 purposes 3948 o Call Back Language List. This list is required if the Call Back 3949 Function is set 3950 o (Payment Scheme) Packaged Content - copied from the Payment 3951 Scheme Component of the received IOTP message (Payment Exchange 3952 or Request Block). 3954 XML definition: 3956 3958 3965 Output Parameters 3966 o Continuation Status 3967 o (Payment Scheme) Packaged Content - for insertion in the 3968 Payment Scheme Component of the next Payment Exchange Block. 3970 The response message contains payment schema specific data if the 3971 continuation status signals "Continue". The IOTP Application Core is 3972 allowed to reissue this request several times on failed analyses of 3973 the response. 3975 XML definition: 3977 3979 3982 Tables 4 and 5 explain the attributes and elements; Table 3 3983 introduces the Error Codes. 3985 4.3.5 Continue Process 3987 This API function passes one specific IOTP Payment Scheme Component, 3988 i.e., the encapsulated Packaged Content elements, received from the 3989 counter party (e.g. Consumer) to the IOTP Payment Bridge and responds 3990 with the next IOTP Payment Scheme Component for submission to the 3991 counter party. 3993 Input Parameters 3995 o Payty's Payment Idetifier 3996 o Process (Transaction) Type which distinguishes between Payments 3997 and Inquiries. 3998 o Wallet Identifier and/or Pass Phrase 3999 o (Payment Scheme) Packaged Content - copied from the Payment 4000 Scheme Component of the received Payment Exchange Block or from 4001 the Error Block. 4003 Each party should set the payment identifier with the local 4004 identifier (Consumer: ConsumerPayId; Merchant: MerchantPayId; Payment 4005 Handler: PaymentHandlerPayId). 4007 XML definition: 4009 4010 4016 Output Parameters 4018 o Continuation Status 4019 o (Payment Scheme) Packaged Content - for insertion in the 4020 Payment Scheme Component of the next Payment Exchange Block or 4021 final Payment Response Block 4023 The response message contains payment schema data if the continuation 4024 status signals "Continue". The IOTP Payment Bridge must signal "End", 4025 if the payment scheme data was received within an IOTP Error Block 4026 containing an Error Component with severity HardError. 4028 XML definition: 4030 4031 4034 Tables 4 and 5 explain the attributes and elements; Table 3 4035 introduces the Error Codes. 4037 4.3.6 Change Process State 4039 The IOTP Application Core changes the current payment status by this 4040 request. The IOTP Payment Bridge may be notified about business level 4041 normal termination, cancellation, suspension, and processing errors. 4042 Notification happens by requesting the intended process state. 4044 The IOTP Payment Bridge processes the status change and reports the 4045 result. 4047 The IOTP Application Core has to analyze any returned process status 4048 in order to check whether the IOTP Payment Bridge has agreed to or 4049 declined the status switch. E.g., the submitted Process State 4050 "CompleteOk" may lead to the Payment Status "Failed" if the payment 4051 transaction has already failed. 4053 Transaction Suspension is notified by the newly introduced Process 4054 State "Suspended". The other attribute values have been taken from 4055 the IOTP specification. 4057 This API function might be called by the Consumer, Merchant, or 4058 Payment Handler for each payment transaction anytime after the 4059 issuance of "FindPaymentInstrument" to the IOTP Payment Bridge by the 4060 Consumer, the issuance of "FindAcceptedPaymentBrand" by the Merchant, 4061 or the issuance of "StartPaymentPaymentHandler" by the Payment 4062 Handler. 4064 The Process States "CompletedOk", "Failed", and "ProcessError" are 4065 final in the sense that they can not be changed on subsequent calls. 4066 However, the API function should not return with an error code if 4067 such an incompatible call has been issued. Instead it should report 4068 the old unchanged Process State. 4070 Unknown payment transactions are reported by the Error Code 4071 "AttValInvalid" pointing to the PayId attribute. 4073 Input Parameters 4075 o Party's Payment Identifier 4076 o intended Payment Status 4077 o intended Completion Code 4078 o Process (Transaction) Type which distinguishes between Payments 4079 and Inquiries. 4080 o Wallet Identifier and/or Pass Phrase 4082 XML definition: 4084 4085 4098 Output Parameters 4100 o Process State and Percent Complete 4101 o Completion Code 4102 o Status Description and its language annotation 4104 XML definition: 4106 4107 4119 Tables 4 and 5 explain the attributes and elements; Table 3 4120 introduces the Error Codes. 4122 4.4 General Inquiry API Calls 4124 The following calls are not necessarily assigned to a payment 4125 transaction and may be issued at any time. There are no dependencies 4126 on any other calls. 4128 4.4.1 Remove Payment Log 4130 The IOTP Application Core notifies the IOTP Payment Bridge and/or the 4131 corresponding Existing Payment Software via IOTP Payment Bridge that 4132 any record in the Payment Log file, that deals with the listed 4133 payment transaction, might be removed. 4135 Input Parameters 4137 o Party's Payment Identifier 4138 o Wallet Identifier and/or Pass Phrase 4140 XML definition: 4142 4143 4148 Output Parameters 4150 XML definition: 4152 4153 4155 Tables 4 and 5 explain the attributes and elements; Table 3 4156 introduces the Error Codes. 4158 4.4.2 Payment Instrument Inquiry 4160 This API function retrieves the properties of the Payment Instrument. 4161 The Payment Instrument Identifier could be omitted if this identifier 4162 is derived by other means, e.g., by analysis of the currently 4163 inserted chip card. If the Payment instrument could not uniquely 4164 determined, the IOTP Payment Bridge may provide suitable dialogs for 4165 user input. 4167 E.g., this API function might be used during problem resolution with 4168 the Customer Care Provider of the issuer of the payment instrument, 4169 in order to inquire payment instrument specific values. 4171 Input parameters 4173 o Brand Identifier 4174 o Payment Instrument Identifier 4175 o Protocol Identifier 4176 o Wallet Identifier and/or Pass Phrase 4177 o Property Type List - sequence of values whose language is 4178 identified by xml:lang 4179 o (Brand) PackagedContent Content - further payment brand 4180 description 4181 o Protocol Brand Content - further payment brand information 4182 o (Protocol Amount) PackagedContent Content - further payment 4183 protocol description 4184 o (Pay Protocol) PackagedContent Content - further payment 4185 protocol description 4187 The codes in the property type list are of two types: 4189 o generic codes which apply to all payment methods but might be 4190 unavailable 4191 o Payment Brand specific codes. 4193 Generic codes for the Property Type List are: 4195 Property Type Meaning 4196 Balance Current balance 4197 Limit Maximum balance 4198 PaymentLimit Maximum payment transaction limit 4199 Expiration Expiration date 4200 Identifier Issuer assigned identifier of the payment 4201 instrument. Usually, it does not match with 4202 the API's payment instrument identifier. 4203 LogEntries Number of stored payment transaction 4204 entries. The entries are numbered from 0 4205 (the most recent) to some non-negative 4206 value for the oldest entry. 4207 PayAmountn Payment Amount of the n-th recorded payment 4208 transaction, n may negative 4209 PayPartyn Remote party of the n-th payment recorded 4210 transaction, n may negative 4211 PayTimen Time of the n-th payment recorded 4212 transaction, n may negative 4214 XML definition: 4216 4220 4229 Output parameters 4231 o a list of zero or more unavailable property values whose 4232 language are identified by xml:lang. 4233 o a list of zero or more sets of "Properties Types", "Property 4234 Values" and "Property Descriptions" 4236 XML definition: 4238 4240 4244 4245 4250 Tables 4 and 5 explain the attributes and elements; Table 3 4251 introduces the Error Codes. 4253 4.4.3 Inquire Pending Payment 4255 This API function reports the party's payment identifiers of any 4256 pending payment transactions that the IOTP Payment Bridge/Existing 4257 Payment Software recommends to complete or suspend prior to the 4258 processing of new payment transactions. It does not respond further 4259 transaction details. These have to be inquired by "Inquire Process 4260 State". 4262 Note that the IOTP Payment Bridge has to respond without the 4263 supplement of any pass phrase if there exist no pending payment 4264 transaction. But if there are some pending payment transactions, the 4265 IOTP Payment Bridge may refuse the immediate response and may instead 4266 request the appropriate pass phase from the IOTP Application Core. 4268 Input Parameters 4270 o Wallet Identifier and/or PassPhrase 4272 XML definition: 4274 4275 4279 Output Parameters 4281 o Party's Payment Identifier 4283 XML definition: 4285 4287 4288 4291 Tables 4 and 5 explain the attributes and elements; Table 3 4292 introduces the Error Codes. 4294 4.5 Payment Related Inquiry API Calls 4295 4.5.1 Check Payment Receipt 4297 This function is used by the Consumer and might be used by the 4298 Payment Handler to check the consistency, validity, and integrity of 4299 IOTP payment receipts whereby any receipt might consist of Packaged 4300 Content Elements 4302 o from the IOTP Payment Receipt Component - provided by the 4303 Payment Handler's "Inquire Process State" API call shortly 4304 before payment completion, 4306 o from Payment Scheme Components being exchanged during the 4307 actual payment, or 4309 o being returned by the Consumer's "Inquire Process State" API 4310 call shortly before payment completion 4312 The IOTP Application Core has to check the PayReceiptNameRefs 4313 attribute of the IOTP Payment Receipt Component and to supply exactly 4314 the Packaged Content Elements being referred to. 4316 Failed verification is returned with a business error. 4318 Note that this Payment API assumes that any payment receipt builds 4319 upon a subset of elements w.r.t. [IOTP]. Furthermore, the Packaged 4320 Content Element have to be distinguishable by their Name attribute. 4322 Input Parameters 4324 o Party's Payment Identifier 4325 o Wallet Identifier and/or Pass Phrase 4326 o All Packaged Content Elements that build the payment receipt 4328 XML definition: 4330 4331 4336 Output Parameters 4338 XML definition: 4340 4341 4343 Tables 4 and 5 explain the attributes and elements; Table 3 4344 introduces the Error Codes. 4346 4.5.2 Expand Payment Receipt 4348 This API function expands any IOTP payment receipt into a form which 4349 may be used for display or printing purposes. "Check Payment Receipt" 4350 should be used first if there is any question of the payment receipt 4351 containing errors. 4353 There apply the same conventions to the input parameter as for "Check 4354 Payment Receipt" (cf. Section 4.5.1). 4356 Input Parameters 4358 o Party's Payment Identifier 4359 o Wallet Identifier and/or Pass Phrase 4360 o All Packaged Content Elements that build the payment receipt 4362 XML definition: 4364 4365 4370 Output Parameters 4372 o Brand Identifier 4373 o Protocol specific Brand Identifier 4374 o Payment Instrument Identifier 4375 o Currency Code and Currency Code Type 4376 o Payment Amount 4377 o Payment Direction 4378 o Time Stamp - issuance of the receipt 4379 o Protocol Identifier 4380 o Protocol specific Transaction Identifier - this is an internal 4381 reference number which identifies the payment 4382 o Consumer Description, Payment Handler Description, and a 4383 language annotation 4384 o Style Sheet Net Location 4385 o Payment Property List. A list of type/value/description triples 4386 which contains additional information about the payment which 4387 is not covered by any of the other output parameters; property 4388 descriptions have to consider the language annotation. 4390 The Style Sheet Net Location refers to a Style Sheet (e.g. [XSLT]) 4391 that contains visualization information about the reported XML 4392 encoded data. 4394 XML definition: 4396 4397 4413 4414 4419 The Existing Payment Software should return as many attributes as 4420 possible from the supplied IOTP Payment Receipt. The payment 4421 supplement define that attribute value for the payment properties. 4423 Tables 4 and 5 explain the attributes and elements; Table 3 4424 introduces the Error Codes. 4426 4.5.3 Inquire Process State 4428 This API function returns the current payment state and optionally 4429 further Packaged Content Elements that form the payment receipt. 4430 Called by the Payment Handler, the IOTP Payment Bridge might respond 4431 with data intended for inclusion in the IOTP Payment Receipt 4432 Component's Packaged Content. When the Consumer calls this function 4433 shortly before payment completion, it may respond with further items 4434 of the payment receipt. Such items might be created by a chip card. 4436 Input Parameters 4438 o Party's Payment Identifier 4439 o Wallet Identifier and/or Pass Phrase 4440 XML definition: 4442 4443 4448 Output Parameters 4450 o Current Process State and Percent Complete 4451 o Completion Code 4452 o Status Description and its language annotation 4453 o Payment Receipt Name References to all Packaged Content 4454 Elements that build the payment receipt (cf. Section 4.5.1), 4455 even if they have not been created so far (Consumer's share) 4456 o Any Packaged Content Element being available that form the 4457 payment receipt 4459 The IOTP provides a linking capability to the payment receipt 4460 delivery. Instead of encapsulating the whole payment specific data 4461 into the packaged content of the payment receipt, other Payment 4462 Scheme Components' Packaged Content might be referred to. 4464 XML definition: 4466 4468 4481 Tables 4 and 5 explain the attributes and elements; Table 3 4482 introduces the Error Codes. 4484 4.5.4 Start Payment Inquiry 4486 This API function responds any additional payment scheme specific 4487 data that is needed by the Payment Handler for Consumer initiated 4488 payment transaction inquiry processing. Probably, the IOTP Payment 4489 Bridge (or the corresponding Existing Payment Software) has to 4490 determine the payment related items that were provided with the 4491 "Start Payment Consumer" API function call. 4493 Input Parameters 4495 o Consumer Payment Identifier 4496 o Wallet Identifier and/or Pass Phrase 4498 XML definition: 4500 4501 4506 Output Parameters 4508 o (Payment Scheme) Packaged Content - intended for insertion in 4509 the Payment Scheme Component of the Inquiry Request Block 4511 XML definition: 4513 4516 Tables 4 and 5 explain the attributes and elements; Table 3 4517 introduces the Error Codes. 4519 4.5.5 Inquire Payment Status 4521 The Payment Handler calls this API function for Consumer initiated 4522 inquiry processing. It differs from the previous "Inquire Process 4523 State" API function by the optional supplement of payment scheme 4524 specific data. The response may encapsulate further details about the 4525 payment transaction. 4527 Input Parameters 4529 o Payment Handler Payment Identifier 4530 o Wallet Identifier and/or Pass Phrase 4531 o (Payment Scheme) Packaged Content - copied from the Inquiry 4532 Request Block's Payment Scheme Component 4534 XML definition: 4536 4537 4542 Output Parameters 4544 o Current Process State 4545 o Completion Code 4546 o Status Description and its language annotation 4547 o (Payment Scheme) Packaged Content - intended for insertion in 4548 the Payment Scheme Component of the Inquiry Response Block 4550 XML definition: 4552 4554 4566 Tables 4 and 5 explain the attributes and elements; Table 3 4567 introduces the Error Codes. 4569 4.6 Other API Calls 4571 4.6.1 Manage Payment Software 4573 The following API function notifies the IOTP Payment Bridge about the 4574 intended registration, modification, or deletion of a payment 4575 instrument. The actual processing is up to the IOTP Payment Bridge. 4577 This API request may also be used to activate the IOTP Payment Bridge 4578 (and the corresponding Existing Payment Software) for general 4579 administration purposes. 4581 Input Parameters 4583 o Brand Identifier 4584 o Protocol Identifier 4585 o Any action code: 4586 o New - add new payment method / instrument 4587 o Update - change the payment method's / instrument's data 4588 o Delete - delete a payment method / instrument 4589 o Wallet Identifier and/or Pass Phrase 4590 o (Brand) Packaged Content - further payment brand description 4591 o (Pay Protocol) Packaged Content - further payment protocol 4592 description 4593 o (Protocol Amount) Packaged Content - further payment protocol 4594 description 4596 If the Action attribute is set, the Brand and Protocol Identifier 4597 have to be set, too. The IOTP Payment Bridge has to provide the 4598 required user dialogs and selection mechanisms. E.g., updates and 4599 deletions may require the selection of the payment instrument. A new 4600 wallet might be silently generated on the supplement of a new Wallet 4601 Identifier or after an additional end user acknowledge. The IOTP 4602 Application Core should not provide any pass phrases for new wallets. 4603 Instead, the IOTP Payment Bridge has to request and verify them which 4604 may return their value to the IOTP Application Core in plain text. In 4605 addition, the IOTP Payment Bridge returns the supported 4606 authentication algorithms when a new brand and protocol pair has been 4607 registered. 4609 If the "Action" attribute is omitted, the IOTP Payment Bridge which 4610 is responsible for the Existing Payment Software pops up in a general 4611 interactive mode. 4613 XML definition: 4615 4618 4627 Output Parameters 4628 o An action code: 4629 o New - added new wallet 4630 o Update - changed wallet's configuration 4631 o Delete - removed a wallet 4632 o Wallet Identifier and/or Pass Phrase 4634 The IOTP Payment Bridge does not return any information about the set 4635 of registered payment instruments because these data items are 4636 dynamically inferred during the brand selection process at the 4637 beginning of each IOTP transaction. However, the IOTP Application 4638 Core has to be notified about new wallets and should be notified 4639 about updated and removed wallet (identifier)s". Alternatively, 4640 removed wallets can be implicitly detected during the next brand 4641 selection phase. Updated wallets do no affect the processing of the 4642 IOTP Application Core. The IOTP Payment Bridge should only support 4643 the addition of at most one wallet because it is not able to report 4644 multiple additions at once back to the IOTP Application Core. 4646 XML definition: 4648 4649 4657 Tables 4 and 5 explain the attributes and elements; Table 3 4658 introduces the Error Codes. 4660 5. Call Back Function 4662 This API function, called by the IOTP Payment Bridge, is used to 4663 provide information for Consumer or Payment Handler notification 4664 about the progress of the payment transaction. 4666 Its use is illustrated in the diagram below. 4668 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 4669 IOTP Application ----calls---- 4670 | Core | | 4671 display | | v 4672 to <---------- Call Back <--calls--- Payment 4673 user | | Software 4674 ---------------- 4675 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 4676 Figure 9 Call Back Function 4678 Whenever this function is called, the content of the status 4679 description should be made available to the user. For example on a 4680 status bar, a pop up window, etc. 4682 A reference to the Call Back function is passed as an input parameter 4683 to the "Start Payment X" and "Resume Payment X" API function. 4684 Afterwards, this function might be called whenever the status changes 4685 or progress needs to be reported. 4687 Input Parameters 4689 o the software identifier of the caller 4690 o Party's Payment Identifier 4691 o Process State and Percent Complete 4692 o Completion Code 4693 o Status Description and its language annotation, text which 4694 provides information about the progress of the call. It should 4695 be displayed or made available to, for example, the Consumer. 4697 Examples of Status Description could be: 4699 o "Paying 12.30 USD to XYZ Inc" 4700 o "Payment completed" 4701 o "Payment aborted" 4703 The valid languages are announced in the Call Back Language List 4704 attribute in "Start Payment X" and "Resume Payment X" API function 4705 calls. 4707 XML definition: 4709 4710 4724 Output Parameters 4725 XML definition: 4727 4728 > 4730 Tables 4 and 5 explain the attributes and elements; Table 3 4731 introduces the Error Codes. 4733 Basically, the call back function accepts all input arguments or 4734 rejects the whole request. It may even accept malformed requests. 4736 Some payment schemes may support or require that the Consumer might 4737 be able to cancel the payment at any time. The Call Back function can 4738 be used to facilitate this by returning the cancellation request on 4739 the next call (using the Business Error Code and Completion Code 4740 "ConsCancelled"). 4742 Vice versa the Payment Handler's Application Core might use the 4743 similar mechanism to signal its IOTP Payment Bridges any exceptional 4744 need for a fast shutdown. These IOTP Payment Bridges may initiate the 4745 appropriate steps for terminating/canceling all pending payment 4746 transactions. 4748 Note that the "Change Process State" API function provides the second 4749 mechanism for such kind of notification. Therefore, the IOTP Payment 4750 Bridge or Existing Payment Software may ignore the details of the 4751 "Call Back" response. 4753 6. Security Consideration 4755 [T.B.D.] 4757 See also security consideration section of [IOTP]. 4759 Full Copyright Statement 4761 Copyright (C) The Internet Society 2000. 4763 This document and translations of it may be copied and furnished to 4764 others, and derivative works that comment on or otherwise explain it 4765 or assist in its implementation may be prepared, copied, published 4766 and distributed, in whole or in part, without restriction of any 4767 kind, provided that the above copyright notice and this paragraph are 4768 included on all such copies and derivative works. However, this 4769 document itself may not be modified in any way, such as by removing 4770 the copyright notice or references to the Internet Society or other 4771 Internet organizations, except as needed for the purpose of 4772 developing Internet standards in which case the procedures for 4773 copyrights defined in the Internet Standards process must be 4774 followed, or as required to translate it into languages other than 4775 English. 4777 The limited permissions granted above are perpetual and will not be 4778 revoked by the Internet Society or its successors or assigns. 4780 This document and the information contained herein is provided on an 4781 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4782 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4783 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4784 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4785 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4787 References 4789 [IOTP] - Internet Open Trading Protocol Specification, Version 1.0, 4790 April 2000, See RFC2801. 4792 [IOTPBOOK] - D. Burdett, D.E. Eastlake III, and M. Goncalves, 4793 Internet Open Trading Protocol, McGraw-Hill, 2000 4795 [HTML] - Hyper Text Mark Up Language. The Hypertext Markup Language 4796 (HTML) is a simple markup language used to create hypertext documents 4797 that are platform independent. See RFC 1866 and the World Wide Web 4798 (W3C) consortium web site at: http://www.w3.org/MarkUp/ 4800 [HTTP] - Hyper Text Transfer Protocol versions 1.0 and 1.1. See RFC 4801 1945: Hypertext Transfer Protocol - HTTP/1.0. T. Berners-Lee, R. 4802 Fielding & H. Frystyk. May 1996. and RFC 2068: Hypertext Transfer 4803 Protocol - HTTP/1.1. R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. 4804 Berners-Lee. January 1997. 4806 [ISO4217] - ISO 4217: Codes for the Representation of Currencies. 4808 Available from ANSI or ISO. 4810 [MIME] - Multipurpose Internet Mail Extensions. See RFC822, RFC2045, 4811 RFC2046, RFC2047, RFC2048 and RFC2049. 4813 [URL] - Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform 4814 Resource Locators (URL)", RFC 1738, December 1994. 4816 [SET] - SET Secure Electronic Transaction(TM) , Version 1.0, May 31, 4817 1997 4818 Book 1: Business Description 4819 Book 2: Programmer's Guide 4820 Book 3: Formal Protocol Definition 4821 Download from: . 4823 [SET/IOTP] - Yoshiaki Kawatsura "SET Supplement for IOTP" (currently 4824 draft-ietf-trade-iotp-v1.0-set-01.txt) 4826 [UTC] - Universal Time Coordinated. A method of defining time 4827 absolutely relative to Greenwich Mean Time (GMT). Typically of the 4828 form: "CCYY-MM- DDTHH:MM:SS.sssZ+n" where the "+n" defines the number 4829 of hours from GMT. See ISO DIS8601. 4831 [XML] - Extensible Mark Up Language. A W3C recommendation. See 4832 http://www.w3.org/TR/1998/REC-xml-19980210 4834 [XSLT] - Extensible Style Language Transformations 1.0, November 4835 1999, See http://www.w3.org/TR/xslt 4837 [XML-NS] - Namespaces in XML Recommendation. T. Bray, D. Hollander, 4838 A. Layman. Janaury 1999. http://www.w3.org/TR/1999/REC-xml-names- 4839 19990114 4841 Author's Address 4843 Hans-Bernhard Beykirch and Werner Hans 4844 IT Development & Coordination Center for the German Savings Banks 4845 Organization (SIZ) 4846 Konigswinterer Strase 553 4847 53227 Bonn 4848 Germany 4849 E-mail: Hans-Bernhard.Beykirch@siz.de, Werner.Hans@siz.de 4851 Masaaki Hiroya and Yoshiaki Kawatsura 4852 Hitachi, Ltd. 4853 890 Kashimada Saiwai-ku Kawasaki-shi 4854 Kanagawa, Japan 212-8567 4855 E-mail: hiroya@sdl.hitachi.co.jp, kawatura@bisd.hitachi.co.jp 4857 Expiration and File Name 4859 This draft expires March 2001. 4861 Its file name is draft-ietf-trade-iotp-v1.0-papi-02.txt.