idnits 2.17.1 draft-ietf-trade-iotp-v1.0-papi-01.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-01', 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 1702 has weird spacing: '...n error that ...' == Line 1740 has weird spacing: '...ding on the n...' == Line 1751 has weird spacing: '...Content cf. T...' == Line 2785 has weird spacing: '...ontents must ...' == Line 4516 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 8623 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 1323, but not defined == Missing Reference: 'PSn' is mentioned on line 1121, but not defined == Missing Reference: 'PS2' is mentioned on line 1324, but not defined == Unused Reference: 'IOTPBOOK' is defined on line 4800, but no explicit reference was found in the text == Unused Reference: 'HTML' is defined on line 4803, but no explicit reference was found in the text == Unused Reference: 'HTTP' is defined on line 4808, but no explicit reference was found in the text == Unused Reference: 'ISO4217' is defined on line 4814, but no explicit reference was found in the text == Unused Reference: 'MIME' is defined on line 4818, but no explicit reference was found in the text == Unused Reference: 'SET' is defined on line 4824, but no explicit reference was found in the text == Unused Reference: 'UTC' is defined on line 4834, 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 draft-ietf-trade-iotp-v1.0-papi-01.txt 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 "Find Payment Protocol" identifies which payment protocols are 584 supported by a specific payment instrument, resp. payment brand. 586 This function might be used in conjunction with the aforementioned 587 function or called without any brand identifier. 589 "Check Payment Possibility" checks whether a specific payment 590 instrument is able to perform a payment. 592 "Authenticate" forwards any payment scheme specific authentication 593 data to the IOTP Payment Bridge for processing. 595 "Change Process State" is used (here only) for abnormal termination. 596 (cf. Payment Processing Related API Functions). 598 o Payment Processing Related API Functions 600 "Start or Resume Payment Consumer/Payment Handler" initiate or resume 601 a payment transaction. There exist specific API functions for the two 602 trading roles Consumer and Payment Handler. 604 "Continue Process" forwards payment scheme specific data to the 605 Existing Payment Software and returns more payment scheme specific 606 data for transmission to the counter party. 608 "Change Process State" changes the current status of payment 609 transactions. Typically, this call is used for successful/- less 610 termination or suspension. 612 o General Inquiry API Functions 614 "Remove Payment Log" notifies the IOTP Payment Bridge that a 615 particular entry has been removed from the Payment Log of the IOTP 616 Application Core. 618 "Payment Instrument Inquiry" retrieves the properties of Payment 619 Instruments. 621 "Inquire Pending Payment" reports any abnormal interrupted payment 622 transaction known by the IOTP Payment Bridge. 624 Payment Processing Related Inquiry API Functions 626 "Check Payment Receipt" checks the consistency and validity of IOTP 627 Payment Receipts, received from the Payment Handler or returned by 628 "Inquire Process State" API calls. Typically, this function is called 629 by the Consumer during the final processing of payment transactions. 631 Nevertheless, this check might be advantageous both for Consumers and 632 Payment Handlers on failure resolution. 634 "Expand Payment Receipt" expands the Packaged Content of IOTP Payment 635 Receipts as well as payment scheme specific payment receipts into a 636 form which can be used for display or printing purposes. 638 "Inquire Process State" responds with the payment state and the IOTP 639 Payment Receipt Component. Normally, this function is called by the 640 Payment Handler for final processing of the payment transaction. 642 "Start Payment Inquiry" prepares the remote inquiry of the payment 643 transaction status and responds with payment scheme specific data 644 that might be needed by the Payment Handler for the Consumer 645 initiated inquiry processing. 647 "Inquire Payment Status" is called by the Payment Handler on Consumer 648 initiated inquiry requests. This function returns the payment scheme 649 specific content of the Inquiry Response Block. 651 "Continue Process" and "Change Process State" (cf. Payment Processing 652 Related API Calls) 654 o Other API Functions 656 "Manage Payment Software" enables the immediate activation of the 657 Existing Payment Software. Further user input is under control of the 658 Existing Payment Software. 660 "Call Back" provides a general interface for the visualization of 661 transaction progress by the IOTP Application Core. 663 The following table shows which API functions must (+), should (#), 664 or might (?) be implemented by which Trading Roles. 666 API function Consumer Payment Handler Merchant 668 Find Accepted Payment Brand + 669 Find Accepted Payment Protocol # 670 Find Payment Instrument + 672 Get Payment Initialization Data + 673 Check Payment Possibility + 675 Start Payment Consumer + 676 Start Payment Payment Handler + 677 Resume Payment Consumer # 678 Resume Payment Payment Handler # 680 Continue Process + + 681 Inquire Process State + + ? 682 Change Process State + + ? 683 Check Payment Receipt + ? 684 Expand Payment Receipt # ? 686 Remove Payment Log ? ? ? 688 Inquire Authentication Challenge ? 689 Authenticate + 690 Check Authentication Response ? 692 Payment Instrument Inquiry ? 693 Inquire Pending Payment # # 694 Start Payment Inquiry ? 695 Inquire Payment Status ? 697 Manage Payment Software # ? ? 699 Call Back # 700 Table 1: Requirements on API Functions by the Trading Roles 702 The next sections sketch the relationships and the dependencies 703 between the API functions. They provide the informal description of 704 the progress alternatives and depict the communication and 705 synchronization between the general IOTP Application Core and the 706 payment scheme specific modules. 708 2.1 Authentication Documentation Exchange 710 This section describes how the functions in this document are used 711 together to process authentication. 713 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 714 Authenticator Inquire Authentication Challenge(Alg1*) -> IPB 715 Inq. Auth. Challenge Response(Alg1,Ch1) <- IPB 716 . . . 717 Inquire Authentication Challenge(Algn*) -> IPB 718 Inq. Auth. Challenge Response(Algn,Chn) <- IPB 719 Create and transmit Authentication Request Block 720 Authenticatee Authenticate(Alg1, Ch1) -> IPB 721 AuthenticateResponse(...) <- IPB 722 . . . 723 Authenticate(Algm, Chm) -> IPB 724 AuthenticateResponse(Res) <- IPB 725 Create and transmit Authentication Response Block 726 Authenticator Check Authentication Response(Algm,Chm,Res)->IPB 727 Check Auth. Resp. Response() <-IPB 728 Create and transmit Authentication Status Block 730 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 731 Figure 12 Authentication Message Flows 733 1. (Authenticator Process) None, one or multiple IOTP Payment Bridges 734 (IPB) are requested for one or multiple authentication challenge 735 values ("Inquire Authentication Challenge"). Each value is 736 encapsulated in an IOTP Authentication Request Component. In 737 addition, the IOTP Application Core may add payment scheme 738 independent authentication methods. All of them form the final IOTP 739 Authentication Request Block, which describes the set of 740 authentication methods being supported by the authenticator and from 741 which the authenticatee has to choose one method. 743 Note that the interface of the API function is limited to the 744 response of exactly one algorithm per call. If the IOTP Application 745 Core provides a choice of algorithms for input, this choice should be 746 reduced successively by the returned algorithm ({Alg(i+1)*} is subset 747 of {Algi*}). 749 During the registration of new Payment Instruments, the IOTP Payment 750 Bridge notifies the IOTP Application Core about the supported 751 authentication algorithms. 753 2. On presence of an IOTP Authentication Block within the received 754 IOTP message, the Authenticatee's IOTP Application Core checks 755 whether the IOTP transaction type in the current phase actually 756 supports the authentication process. 758 For each provided Authentication Request Component, the IOTP 759 Application Core analyzes the algorithms' names, the transaction 760 context, and optionally user preferences in order to determine the 761 system components which are capable to process the authentication 762 request items. Such system components might be the IOTP Application 763 Core itself or any of the registered IOTP Payment Bridges. 765 Subsequently, the IOTP Application Core requests the responses to 766 the supplied challenges from the determined system components in any 767 order. The authentication trials stop with the first successful 768 response, which is included in the IOTP Authentication Response 769 Block. 771 Alternatively, the IOTP Application might ask for a user selection. 772 This might be appropriate, if two or more authentication algorithms 773 are received that require explicit user interaction, like PIN or chip 774 card insertion. 776 The Authenticatee's organizational data is requested by an IOTP 777 Authentication Request Block without any content element. On failure, 778 the authentication (sequence) might be retried, or the whole 779 transaction might be suspended or cancelled. 781 3. (Authenticator Process) The IOTP Application Core checks the 782 presence of the IOTP Authentication Response Component in the 783 Authentication Response Block and forwards its content to the 784 generator of the associated authentication challenge for verification 785 ("Check Authentication Response"). 787 On sole organizational data request, its presence is checked. 789 Any verification must succeed in order to proceed with the 790 transaction. 792 2.2 Brand Compilation 794 The following shows how the API functions are used together so that 795 the Merchant can (1) compile the Brand List Component, (2) generate 796 the Payment Component, and (3) adjust the Order Component with 797 payment scheme specific packaged content. 799 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 800 Merchant For each registered IOTP Payment Bridge 801 | Find Accepted Payment Brand() -> IPB 802 | Find Accepted Payment Brand Response (B*) <- IPB 803 | Find Accepted Payment Protocol(B1) -> IPB 804 | Find Accepted Payment Protocol Res.(P1*) <- IPB 805 | . . . 806 | Find Accepted Payment Protocol(Bn) -> IPB 807 | Find Accepted Payment Protocol Res.(Pn*) <- IPB 808 Create one Brand List Component, ideally sharing 809 common Brand, Protocol Amount, Currency Amount, 810 and Pay Protocol Elements 811 Create Trading Protocol Options Block 812 On brand independent transactions 813 | Create Brand Selection Component, implicitly 814 | Get Payment Initialization Data(B1,P1) -> IPB 815 | Get Payment Initialization Data Res.() <- IPB 816 | Optionally 817 | | Inquire Process State() -> IPB 818 | | Inquire Process State Response(State) <- IPB 819 | Create Offer Response Block 820 Transmit newly created Block(s) 821 Consumer Consumer selects Brand (Bi)/Currency/Protocol (Pj) 822 from those that will work and generates Brand 823 Selection Component - at least logically 824 On brand dependent transaction 825 | Transmit Brand Selection Component 826 Merchant On brand dependent transaction 827 | Get Payment Initialization Data(Bi,Pj) -> IPB 828 | Get Payment Initialization Data Res.() <- IPB 829 | Optionally 830 | | Inquire Process State() -> IPB 831 | | Inquire Process State Response(State) <- IPB 832 | Create Offer Response Block 833 | Transmit newly created Block 834 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 835 Figure 3 Brand Compilation Message Flows 837 1. The Merchant's commerce server controls the shopping dialog with 838 its own mechanisms until the Consumer checks out the shopping cart 839 and indicates the payment intention. The notion shopping subsumes any 840 non-IOTP based visit of the Merchant Trading Role's (which subsumes 841 Financial Institutes) web site in order to negotiate the content of 842 the IOTP Order Component. The subsequent processing switches to the 843 IOTP based form by the activation of the Merchant's IOTP aware 844 application. 846 2. The IOTP Application Core inquires the IOTP level trading 847 parameters (Consumer's shopping identifier, payment direction, 848 initial currency amounts, discount rates, Merchant's and Delivery 849 Handler's Net Locations, Non-Payment Handler's Organisational Data, 850 initial order information, ....). 852 3. The registered IOTP Payment Bridges are inquired by the IOTP 853 Application Core about the accepted payment brands ("Find Accepted 854 Payment Brand"). Their responses provide most of the attribute values 855 for the compilation of the Brand List Component's Brand Elements. The 856 IOTP Application Core might optionally match the returned payment 857 brands with Merchant's general preferences. 859 The IOTP Application Core must provide any wallet identifiers, if 860 they are required by the IOTP Payment Bridges which signal their need 861 by specific error codes (see below). Any signaled error that could 862 not immediately solved by the IOTP Application Core should be logged 863 - this applies also to the subsequent API calls of this section. In 864 this case, the IOTP Application Core creates an IOTP Error Block 865 (hard error), transmits it to the Consumer, and terminates the 866 current transaction. 868 4. The IOTP Application Core interrogates the IOTP Payment Bridges 869 for each accepted payment brand about the supported payment protocols 870 ("Find Accepted Payment Protocol"). These responses provide the 871 remaining attribute values of the Brand Elements as well as all 872 attribute values for the compilation of the Brand List Component's 873 Protocol Amount and Pay Protocol Elements. Furthermore, the 874 organisational data about the Payment Handler is returned. The IOTP 875 Application Core might optionally match the returned payment brands 876 with Merchant's general preferences. 878 Alternatively, the IOTP Application Core might skip the calls of 880 "Find Accepted Payment Brands" (cf. Step 3) and issue the "Find 881 Accepted Payment Protocol" call without any Brand given on the input 882 parameter list. In this case, the IOTP Payment Bridge responds on the 883 latter call with the whole set of payment schemes supported w.r.t. 884 the other input parameters. 886 5. The steps 3 and 4 are repeated during IOTP Value Exchange 887 transactions - these steps are omitted in the previous figure. 889 6. The IOTP Application Core compiles the Brand List Component(s) and 890 the IOTP Trading Protocol Options Block. It is recommended that 891 "equal" items returned by IOTP Payment Bridge function calls are 892 shared due to the extensive linking capabilities within the Brand 893 List Component. However, the compilation must consider several 894 aspects in order to prevent conflicts - sharing detection might be 895 textual matching (after normalization): 897 o Packaged Content Elements contained in the Brand List Component 898 (and subsequently generated Payment and Order Components) might be 899 payment scheme specific and might depend on each other. 901 o Currently, IOTP lacks precise rules for the content of the 902 Packaged Content Element. Therefore, transaction / brand / 903 protocol / currency amount (in)dependent data might share the same 904 Packaged Content Element or might spread across multiple Packaged 905 Content Elements. 907 o The Consumer's IOTP Application Core transparently passes the 908 Packaged Content Elements to the IOTP Payment Bridges which might 909 not be able to handle payment scheme data of other payment 910 schemes, accurately. 912 The rules and mechanisms of how this could be accomplished are out 913 of the scope of this document. Furthermore, this document does not 914 define any further restriction to the IOTP specification. 916 7. The IOTP Application Core determines whether the IOTP message can 917 be enriched with an Offer Response Block. This is valid under the 918 following conditions: 920 o All payment alternatives share the attribute values and Packaged 921 Content Elements of the subsequently generated IOTP Payment and 922 Order Components. 924 o The subsequently generated data does not depend on any IOTP 925 BrandSelInfo Elements that might be reported by the consumer 926 within the TPO Selection Block in the brand dependent variant. 928 If both conditions are fulfilled, the IOTP Application Core might 929 request the remaining payment scheme specific payment initialization 930 data from the IOTP Payment Bridge ("Get Payment Initialization Data") 931 and compile the IOTP Offer Response Block. 933 Optionally, the IOTP Application Core might request the current 934 process state from the IOTP Payment Bridge and add the inferred order 935 status to the IOTP Offer Response Block. Alternatively, IOTP 936 Application might determine the order status on its own. 938 As in step 6, the rules and mechanisms of how this could be 939 accomplished are out of the scope of this document. 941 8. The IOTP Application Core compiles the IOTP TPO Message including 942 all compiled IOTP Blocks and transmits the message to the Consumer. 943 The IOTP Application Core terminates if an IOTP Offer Response Block 944 has been created. 946 9. The Consumer performs the Brand Selection Steps (cf. Section 2.3) 947 and responds with a TPO Selection Block if no IOTP Offer Response 948 Block has been received. Otherwise, the following step is skipped. 950 10. On brand dependent transactions, the IOTP Application Core 951 requests the remaining payment scheme specific payment initialization 952 data from the IOTP Payment Bridge ("Get Payment Initialization 953 Data"), compiles the IOTP Offer Response Block, transmits it to the 954 Consumer, and terminates. Like Step 7, the IOTP Application Core 955 might access the current process state of the IOTP Payment Bridge for 956 the compilation of the order status. 958 Any error during this process raises an IOTP Error Block. 960 2.3 Brand Selection 962 This section describes the steps that happen mainly after the 963 Merchant's Brand Compilation (in a brand independent transaction). 964 However, these steps might partially interlace the previous process 965 (in a brand dependent transaction). 967 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 968 Merchant Merchant generates Brand List(s) containing 969 Brands, Payment Protocols and Currency Amounts 970 On brand independent transactions 971 | Merchant generates Offer Response Block 972 Consumer Compile set(s) of Brands B/Protocols P 973 for each set 974 | Find Payment Instrument(B, P, C) -> IPB 975 | Find Payment Instrument Response (PI*) <- IPB 976 Consumer selects Brand/Currency/Payment Instrument 977 from those that will work and generates Brand 978 Selection Component 979 For the Selection 980 | Get Payment Initialization Data(B,C,PI,P) -> IPB 981 | Get Payment Initialization Data Response()<- IPB 982 On brand dependent transaction 983 | Generate and transmit TPO Selection Block 984 Merchant On brand dependent transaction 985 | Merchant checks Brand Selection and generates 986 | and transmits Offer Response Block 987 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 988 Figure 4 Brand Selection Message Flows 990 1. The Merchant's commerce server controls the shopping dialog with 991 its own mechanisms until the Consumer checks out the shopping cart 992 and indicates his payment intention. The subsequent processing 993 switches to the IOTP based form by the activation of the Merchant's 994 IOTP aware application. 996 2. The IOTP Application Core compiles the IOTP Trading Protocol 997 Options Block which contains the IOTP Brand List Component(s) 998 enumerating Merchant's accepted payment brands and payment protocols 999 and initiates the Brand Selection process. 1001 3. This first IOTP message activates the Consumer's IOTP aware 1002 application, e.g., the Web browser invokes a helper application 1003 (e.g., Java applet or external application). Its IOTP Application 1004 Core 1006 o infers the accepted payment brands, payment protocols, payment 1007 direction, currencies, payment amounts, any descriptions etc., and 1008 their relationships from the IOTP message, 1010 o determines the registered IOTP Payment Bridges, 1012 o compiles one or multiple set of brand and protocol such that the 1013 join of all set describes exactly the set of payment alternatives 1014 being offered by the Merchant. 1016 o inquires payment (protocol) support and the known payment 1017 instruments from each registered IOTP Payment Bridge for each 1018 compiled set ("Find Payment Instrument"). However, some IOTP Payment 1019 Bridges may refuse payment instrument distinction. 1021 The payment protocol support may differ between payment instruments 1022 if the IOTP Payment Bridge supports payment instrument distinction. 1024 These API calls are used to infer the payment alternatives at the 1025 startup of any payment transaction (without user unfriendly explicit 1026 user interaction). 1028 The IOTP Application Core must provide wallet identifiers, if they 1029 are requested by the IOTP Payment Bridges which signal their need by 1030 specific error codes (see below). 1032 It is recommended that the IOTP Application Core manages wallet 1033 identifiers. But for security reasons, it should store pass phrases 1034 in plain text only in runtime memory. Developers of IOTP Payment 1035 Bridges and payment software modules should provide a thin and fast 1036 implementation - without lengthy initialization processes- for this 1037 initial inquiry step. 1039 4. The IOTP Application Core 1041 verifies the Consumer's payment capabilities with the Merchant's 1042 accepted payment brands and currencies, 1044 o displays the valid payment instruments and payment instrument 1045 independent payment brands (brand and protocol) together with their 1046 purchase parameters (payment direction, currency, amount), and 1048 o requests the Consumer's choice or derives it automatically from any 1049 configured preferences. Any selection ties one IOTP Payment Bridge 1050 with the following payment transaction. 1052 The handling and resolution of unavailable IOTP Payment Bridges 1053 during the inquiry in Step 3 is up to the IOTP Application Core. It 1054 may skip these IOTP Payment Bridges or may allow user supported 1055 resolution. 1057 Furthermore, it may offer the registration of new payment 1058 instruments when the Consumer is requested for payment instrument 1059 selection. 1061 5. The IOTP Application Core interrogates the fixed IOTP Payment 1062 Bridge whether the payment might complete with success ("Check 1063 Payment Possibility"). At this step, the IOTP Payment Bridge may 1064 issue several signals, e.g., 1065 o payment can proceed immediately, 1066 o required peripheral inclusive some required physical payment 1067 instrument (chip card) is unavailable, 1068 o (non-IOTP) remote party (e.g. issuer, server wallet) is not 1069 available, 1070 o wallet identifier or pass phrase is required, 1071 o expired payment instrument (or certificate), insufficient funds, 1072 or 1073 o physical payment instrument unreadable. 1075 In any erroneous case, the user should be notified and offered 1076 accurate alternatives. Most probably, the user might be recommended 1077 o to resolve the problem, e.g. to insert another payment 1078 instrument or to verify the periphery, 1079 o to proceed (assuming its success), 1080 o to cancel the whole transaction, or 1081 o to suspend the transaction, e.g., initiating a nested 1082 transaction for uploading an electronic purse. 1084 If the payment software implements payment instrument selection on 1085 its own, it may request the Consumer's choice at this step. 1087 If the check succeeds, it returns several IOTP Brand Selection Info 1088 Elements. 1090 6. The Steps 2 to 5 are repeated and possibly interlaced for the 1091 selection of the second payment instrument during IOTP Value Exchange 1092 transactions - this is omitted in the figure above. 1094 7. The IOTP Brand Selection Component is generated and enriched with 1095 the Brand Selection Info elements. This component is transmitted to 1096 the Merchant inside a TPO Selection Block if the received IOTP 1097 message lacks the IOTP Offer Response Block. The Merchant will then 1098 respond with an IOTP Offer Response Block (following the 1099 aforementioned compilation rules). 1101 2.4 Successful Payment 1103 An example of how the functions in this document are used together 1104 to effect a successful payment is illustrated in the Figure 5. 1106 Technically, two payments happen during IOTP Value Exchange 1107 transactions. 1109 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1110 Consumer Start Payment Consumer(Amount,[PS0]...) -> IPB 1111 Start Payment Cons. Res.([PS1], CS=Cont.) <- IPB 1112 Create and transmit Payment Request Block 1113 Payment Handler Start Payment Pay. Handler(Amount, [PS1]) -> IPB 1114 Start Payment PH Response(PS2, CS=Cont.) <- IPB 1115 Create and transmit Payment Exchange Block 1116 Consumer Continue Process(PS2) -> IPB 1117 Continue Process Response(PS3, CS=Cont.) <- IPB 1119 ... CONTINUE SWAPPING PAYMENT EXCHANGES UNTIL ... 1121 Payment Handler Continue Process Response([PSn], CS=End) <- IPB 1122 Request any local payment receipt 1123 | Inquire Process State() -> IPB 1124 | Inquire Proc. State Resp.(State, [Rcp.])<- IPB 1125 Create and transmit Payment Response Block 1126 Terminate transaction, actively 1127 | Change Process State(State) -> IPB 1128 | Change PS Response(State=CompletedOK) <- IPB 1129 Consumer On receipt of final payment scheme data 1130 | Continue Process(PSn) -> IPB 1131 | Continue Process Response(CS=End) <- IPB 1132 Check Payment Receipt(Receipt) -> IPB 1133 Check Payment Receipt Response() <- IPB 1134 Request any local payment receipt 1135 | Inquire Process State() -> IPB 1136 | Inquire Proc. State Resp.(State, [Rcp.])<- IPB 1137 Terminate transaction, actively 1138 | Change Process State(State) -> IPB 1139 | Change PS Response(State=CompletedOk) <- IPB 1140 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1141 Figure 5 Example Payment Message Flows 1143 1. After Brand Selection and receipt of the IOTP Offer Response 1144 Block, the Consumer switches from communicating with the Merchant to 1145 communicating with the Payment Handler. 1147 This might be a milestone requiring the renewed Consumer's agreement 1148 about the payment transaction's continuation. Particularly, this is a 1149 good moment for payment suspension (and even cancellation), which 1150 will be most probably supported by all payment schemes. Simply, 1151 because the genuine payment legacy systems have not been involved in 1152 the current transaction. 1154 Such an agreement might be explicit per transaction or automatic 1155 based on configured preferences, e.g., early acknowledgements for 1156 specific payment limits. 1158 It is assumed, that the transaction proceeds with minimal user 1159 (Consumer and Payment Handler) interaction and that its progess is 1160 controlled by the IOTP Application Core and IOTP Payment Bridge. 1162 2. In order to open the actual payment transaction, the IOTP 1163 Application Core issues the "Start Payment Consumer" request towards 1164 the IOTP Payment Bridge. This request carries the whole 1165 initialization data of the payment transaction being referred to by 1166 the IOTP Payment Bridge for subsequent consistency checks: 1168 o payment brand and its description from the selected Brand 1169 Element of the IOTP Brand List Component, 1170 o payment instrument from preceding inquiry step, 1171 o further payment parameters (currency, amount, direction, 1172 expiration) from the selected Currency Amount element, Brand List 1173 Component, and Payment Component of the IOTP Offer Response Block, 1174 o payment protocol from the selected IOTP Pay Protocol Element, 1175 o order details contained in the IOTP Order Component which might 1176 be payment scheme specific, 1177 o payment scheme specific data inclusive payment protocol 1178 descriptions from the IOTP Protocol Amount Element, and IOTP Pay 1179 Protocol Element, and 1180 o payment scheme specific data inclusive payment protocol 1181 descriptions, in which the name attribute includes the prefix as 1182 "Payment:" from the Trading Role Data Component. 1184 Generally, the called API function redoes most checks of the "Check 1185 Payment Possibility" call due to lack of strong dependencies between 1186 both requests: There might be a significant delay between both API 1187 requests. 1189 The called API function may return further payment scheme specific 1190 data being considered as payment specific initialization data for the 1191 Payment Handler's IOTP Payment Bridge. 1193 If the fixed Existing Payment Software implements payment instrument 1194 selection on its own, it may request the Consumer's choice at this 1195 step. 1197 The IOTP Payment Bridge reports lack of capability quite similar to 1198 the "Check Payment Possibility" request to the IOTP Application Core. 1199 The Consumer may decide to resolve the problem, to suspend, or to 1200 cancel the transaction, but this function call must succeed in order 1201 to proceed with the transaction. 1203 Developers of payment modules may decide to omit payment instrument 1204 related checks like expiration date or refunds sufficiency, if they 1205 are part of the specific payment protocol. 1207 If the IOTP Payment Bridge requests wallet identifiers or pass 1208 phrases anywhere during the payment process, they should be requested 1209 by this API function, too. It is recommended that the IOTP 1210 Application Core stores plain text pass phrases only in runtime 1211 memory. 1213 Finally, the IOTP Application Core generates the IOTP Payment 1214 Request Block, inserts any returned payment scheme data, and submits 1215 it to the Payment Handler's system. 1217 3. The Payment Handler's IOTP Application Core opens the payment 1218 transaction calling the "Start Payment Payment Handler" API function. 1219 The payment brand, its description, payment protocol, payment 1220 specific data, payment direction, currency and payment amount are 1221 determined quite similar to the Consumer's IOTP Application Core. 1222 Furthermore, the content of the IOTP Payment Scheme Component and the 1223 IOTP Brand Selection Info Elements are passed to this function. 1225 On success, the Payment Handler's IOTP Payment Bridge responds with 1226 payment scheme specific data. On failures, this non- interactive 1227 server application has to resolve any problems on its own or to give 1228 up aborting the payment transaction. However, the Consumer may 1229 restart the whole payment transaction. Anyway, the payment log file 1230 should reflect any trials of payments. 1232 Eventually, the Payment Handler informs the Consumer about the 1233 current IOTP Process State using the IOTP Payment Response or IOTP 1234 Error Block. 1236 Note that the "Start Payment Payment Handler" call might return the 1237 Continuation Status "End" such that payment processing proceeds with 1238 Step 7. 1240 4. The IOTP Application Core verifies the presence of the Payment 1241 Exchange Block in the IOTP message and passes the contained payment 1242 scheme specific data to the fixed IOTP Payment Bridge ("Continue 1243 Process") which returns the next IOTP Payment Scheme Component. 1245 This Payment Scheme Component is encapsulated in an IOTP Payment 1246 Exchange Block and transmitted to the Payment Handler. 1248 5. The Payment Handler's IOTP Application Core verifies the presence 1249 of the Payment Exchange Block and passes the contained payment scheme 1250 specific data to the fixed IOTP Payment Bridge ("Continue Process") 1251 which returns the next IOTP Payment Scheme Component for 1252 encapsulation and transmission to the Consumer. 1254 6. The payment process continues with IOTP Payment Exchange Block 1255 exchanges, carrying the payment scheme specific data. Each party (1) 1256 submits the embedded payment scheme specific data transparently to 1257 the appropriate IOTP Payment Bridge calling the "Continue Process" 1258 API function, (2) wraps the returned payment scheme specific data 1259 into an IOTP Payment Exchange Block, and (3) transmits this block to 1260 the counter party. 1262 However, the processing of the payment scheme specific data may fail 1263 for several reasons signaled by specific error codes which are 1264 transformed to IOTP Payment Response Blocks (generated by Payment 1265 Handler) or IOTP Error Blocks (both parties may generate them) and 1266 transmitted to the counter party. 1268 7. Eventually, the Payment Handler's IOTP Payment Bridge recognizes 1269 the termination of the payment transaction and reports this by the 1270 continuation status "End" on the output parameter of "Continue 1271 Process" (or "Start Payment Payment Handler"). Then, the IOTP 1272 Application Core issues the "Inquire Process State" API call and 1273 verifies whether an IOTP Payment Receipt Component has been returned. 1274 The IOTP Application Core wraps the payment receipt, the status 1275 response, and the optional payment scheme specific data in an IOTP 1276 Payment Response Block and transmits this block to the Consumer. 1278 However, any of these API calls may fail or any response might be 1279 incomplete (e.g., lack of payment receipt). Then, the Consumer has to 1280 be notified about the failed processing by an IOTP Error Block. 1282 Finally, the Payment Handler terminates the payment transaction with 1283 the "Change Process State" API call without awaiting any further 1284 response from the Consumer. Further failures are not reported to the 1285 Consumer. 1287 Note that it might be possible that the Consumer's IOTP Payment 1288 Bridge has returned the previous payment scheme specific data with 1289 the continuation status "End". Even in the absence of this knowledge 1290 - this status is not exchanged between the Consumer and the Payment 1291 Handler - the Payment Handler must not supply any further payment 1292 scheme specific data. Such data will be rejected by the Consumer's 1293 IOTP Payment Bridge. 1295 8. The Consumer passes the optional payment scheme specific data and 1296 the payment receipt to the fixed IOTP Payment Bridge by "Continue 1297 Process" and "Check Payment Receipt" API calls. 1299 Afterwards, the IOTP Application Core issues the "Inquire Process 1300 State" API call and verifies whether extensions to the payment 1301 receipt have been returned. 1303 Finally, the transaction is terminated by calling the "Change 1304 Process State" API function which verifies and synchronizes the 1305 reported payment status with the local one and signals any 1306 inconsistencies. Any Inconsistency and returned status text should be 1307 displayed to the Consumer. 1309 At this point, the payment transaction has already been closed by 1310 the Payment Handler. Therefore, any failure has to be resolved 1311 locally or out-of-band. 1313 2.5 Payment Inquiry 1315 In Baseline IOTP, Payment inquiries are initiated by the Consumer in 1316 order to verify the current payment progress and process state at the 1317 remote Payment Handler. 1319 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1320 Consumer Start Payment Inquiry() -> IPB 1321 Start Payment Inquiry Response([PS1]) <- IPB 1322 Create and transmit Inquiry Request Trading Block 1323 Payment Handler Inquire Payment Status([PS1]) -> IPB 1324 Inquire Payment Status Res.(State, [PS2]) -> IPB 1325 Create and transmit Inquiry Response Trading 1326 Block 1327 Consumer If Payment Scheme Data present 1328 | Continue Process(PS2) -> IPB 1329 | Continue Process Response(CS=End) <- IPB 1330 Change Process State(State) -> IPB 1331 Change Process State Response(State) <- IPB 1332 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1333 Figure 6 Remote Process State Inquiry 1335 1. The Consumer might initiate a payment inquiry once the payment 1336 transaction has been opened by the IOTP Application Core, i.e., at 1337 any time after the initial submission of the IOTP Payment Request 1338 Block. The IOTP Application Core requests any additional specific 1339 payment scheme data from the IOTP Payment Bridge which has been fixed 1340 during brand selection (cf. Section 2.3) using the "Start Payment 1341 Inquiry" API request. 1343 Erroneous API responses should be reported to the Consumer and valid 1344 alternatives (typically retry and cancellation) should be presented 1345 by the IOTP Application Core. 1347 This request might perform the complete initialization, e.g. 1348 availability check of periphery or pass phrase supplement, and the 1349 IOTP Payment Bridge reports lack of capability quite similar to the 1350 "Check Payment Possibility" request to the IOTP Application Core. 1352 If the IOTP Payment Bridge requests wallet identifiers or pass 1353 phrases anywhere during the payment process, they should be requested 1354 by this API function, too. It is recommended that the IOTP 1355 Application Core stores plain text pass phrases only in runtime 1356 memory. 1358 The IOTP Application Core encapsulates any Payment Scheme Component 1359 in an IOTP Inquiry Request Block and submits the block to the Payment 1360 Handler. 1362 2. The Payment Handler analyses the IOTP Inquire Request Block, maps 1363 the Transaction Identifier to payment related attributes (brand, 1364 consumer and payment identifiers), determines the appropriate IOTP 1365 Payment Bridge, and forwards the request to the this IOTP Payment 1366 Bridge ("Inquire Payment Status"). The IOTP Application Core 1367 transforms the response to an IOTP Inquiry Response Block and 1368 transmits it to the Consumer. 1370 3. On receipt of the respective IOTP Inquiry Response Block the 1371 Consumer's IOTP Application Core submits any encapsulated payment 1372 scheme specific data to the IOTP Payment Bridge for verification 1373 ("Continue Process"). 1375 4. The IOTP Application Core passes the reported payment status 1376 (except textual descriptions) to the IOTP Payment Bridge ("Change 1377 Process State") for verification purposes and payment status change. 1378 The IOTP Payment Bridge reports any inconsistencies as well as the 1379 final payment status to the IOTP Application Core. 1381 Any additional information that might be of interest for the 1382 Consumer has to be displayed by the IOTP Payment Bridge or Existing 1383 Payment Software on their own. 1385 2.6 Abnormal Transaction Processing 1387 2.6.1 Failures and Cancellations 1389 The IOTP specification distinguishes between several classes of 1390 failures: 1392 o Business and technical errors 1393 o Error depth on transport, message and block level 1394 o Transient errors, warnings, and hard errors. 1396 Any IOTP Payment API has to deal with the receipt of failure 1397 notifications by and failure responses. This proposal has borrowed 1398 the basic mechanisms for error reporting between the IOTP Application 1399 Core and the IOTP Payment Bridge from the genuine protocol: Business 1400 errors are reported by Status Components within IOTP Response Blocks 1401 while technical errors are signaled by Error Components within IOTP 1402 Error Blocks. 1404 Cancellations are mimicked as specific business errors which might 1405 be initiated by each trading party. 1407 Preferring slim interfaces, this IOTP Payment API introduces one 1408 additional Error Code value for business error indication - errors 1409 can be raised on every API call. On receipt of this value, the IOTP 1410 Application Core has to infer further details by the issuance of the 1411 API function call "Inquire Process State". 1413 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1414 Any Party Issue some API request -> IPB 1415 Error Response(Error Code) <- IPB 1416 On "Business Error" response 1417 | Inquire Process State() -> IPB 1418 | Inquire P.S. Resp.(State, Receipt) <- IPB 1419 Analyze local process state and try to resolve 1420 with optional user interaction 1421 If Process State Change needed 1422 | Change Process State (State) -> IPB 1423 | Change Process State Response(State) <- IPB 1424 If counter party's notification required 1425 | Create Error or Cancel Block (, add to next 1426 | message, ) and transmit it to counter party 1427 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1428 Figure 7 Error Response from IPB 1430 The specific Completion Codes "ConsCancelled", "MerchCancelled", and 1431 "PaymCancelled" - returned by "Inquire Process State" - determine 1432 that the IOTP Cancel Block has to be created instead of an IOTP Error 1433 Block. 1435 The rules for determining the required behavior of the IOTP 1436 Application Core are given in the IOTP specification. 1438 Note that any payment (intermediate) termination, i.e., failures, 1439 cancellations, and even success's is always reported to the IOTP 1440 Payment Bridge by the API function "Change Process State". This API 1441 function does both status changes and consistency checking / 1442 synchronization. Any suspicion of inconsistency should be reported by 1443 the IOTP Payment Bridge for display by the IOTP Application Core. 1445 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1446 Any Party Error Block or Cancel Block Received 1447 If Change Process State required 1448 | Change Process State (State) -> IPB 1449 | Change Process State Response(State) <- IPB 1450 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1451 Figure 8 Error Notification from counter party 1453 Not every failure might be visible at the IOTP layer, e.g., the 1454 processing of payment transactions might temporarily be hampered by 1455 intermediate failures at the payment scheme or protocol transport 1456 layer which might be resolved by the genuine components. 1458 However, final failures or cancellations have to be reported at the 1459 IOTP layer. E.g., communication time-outs and heavily faulty 1460 communication channels may disable the transaction. 1462 Any system component may implement time-out recognition and use the 1463 aforementioned API mechanisms for the notification of process state 1464 changes. But, time-outs may happens while communicating with both the 1465 counter party and local system components, like chip card readers or 1466 IOTP Payment Bridges. Anyway, the Consumer's IOTP Application Core 1467 should notify the Consumer about the resolution alternatives, i.e., 1468 retry, suspension, and cancellation. 1470 2.6.2 Resumption 1472 Payment transaction resumption may apply at different steps of a 1473 payment transaction: 1475 o The Consumer's and Payment Handler's view of the transaction 1476 might not be synchronized: Due to different time-out values the 1477 payment transaction may not have been suspended by the counter 1478 party. 1480 Any "Resume Payment ..." API function responds with an Error Code 1481 on non suspended payment transaction that signals a business 1482 error. Afterwards the IOTP Application Core has to issue the 1483 "Inquire Process State" API call for further analysis of the 1484 process state. 1486 o One IOTP message sent by one party might not be processed 1487 successfully or even received by the counter party. 1489 This needs to be handled by the genuine payment scheme. It is 1490 expected that the IOTP Application Core will not recognize 1491 anything. 1493 o IOTP does not provide any specific signal for payment 1494 resumption. On receipt of every IOTP Payment Exchange Block, the 1495 IOTP Application Core has to decide whether this Block belongs to 1496 a pending transaction or to a suspended transaction that should be 1497 resumed. The IOTP Application Core might call the "Inquire Process 1498 State" API function to update any lack of knowledge. 1500 Any "Resume Payment" API function responds with an Error Code on 1501 non suspended payment transaction that signals a business error. 1502 Similar, the "Continue Process" API function should report 1503 business errors on non pending payment transactions. 1505 o The payment transaction may not have been created at the Payment 1506 Handler (early suspension and failed data transmission). In that 1507 case, the IOTP Application Core should respond with a business 1508 error that signals the repetition of the payment transaction (by 1509 the Consumer). 1511 Any "Resume Payment", "Continue Process" or "Inquire Process 1512 State" API function should return with an Error Code 1513 "AttValIllegal" on non existent payment transaction whereby the 1514 further Error Attribute "Names" denote the payment identifier. 1516 o The IOTP Application Core should always request fresh payment 1517 scheme specific data on resumption - for synchronization purposes 1518 with the Existing Payment Software. Old data in the cache that has 1519 not been send to the counter party should not be accessed. 1521 If the Consumer does not reconnect within an acceptable amount of 1522 time, the Payment Handler's system may perform local failure 1523 resolution in order to close the transaction and to retain resources 1524 for other transactions ("Change Process State"). If the Consumer 1525 reconnect afterwards, an IOTP Payment Response or IOTP Error Block 1526 could be generated. 1528 2.7 IOTP Wallet Initialization 1530 At startup or on explicit user request the IOTP Application Core 1531 should check its IOTP Payment Bridges' internal status by searching 1532 for pending payment transactions. 1534 1. The IOTP Application Core interrogates the registered IOTP 1535 Payment Bridges about pending payment transactions. The IOTP 1536 Application Core may store indicators for pending transactions and 1537 use them for driving any subsequent inquiry ("Inquire Pending 1538 Payment"). 1540 2. If one or more IOTP Payment Bridges report the presence of pending 1541 transactions, the IOTP Application Core may try to suspend ("Change 1542 Process State") or resume (only Consumer: "Resume Payment Consumer") 1543 the pending transactions (on user request). 1545 The IOTP Payment Bridge may deny the processing of any new payment 1546 transactions until the pending transactions have been processed. Such 1547 denials are signaled by the error code "Business Error". 1549 2.8 Payment Software Management 1551 The IOTP Application Core provides only a simple and generic 1552 interface for the registration of new payment methods / instruments 1553 ("Manage Payment Software"). It receives the initial user request and 1554 defers the actual registration to the corresponding IOTP Payment 1555 Bridge. 1557 The IOTP Application Core may also activate the Existing Payment 1558 Software for further payment instrument and wallet administration. 1560 3. Mutuality 1562 The Payment API is formalized using the Extensible Markup Language 1563 (XML). It defines wrapper elements for both the input parameters and 1564 the API function's response. In particular, the response wrapper 1565 provides common locations for Error Codes and Error Descriptions. 1567 It is anticipated that this description reflects the logical 1568 structure of the API parameter and might be used to derive 1569 implementation language specific API definitions. 1571 XML definition: 1573 1599 1605 1631 1637 1638 1648 Most of the attribute items are intended for immediate insertion in 1649 the IOTP Error Block. The attribute values of the Error Location 1650 elements attribute have to enriched and transformed into Error 1651 Location Elements of the Error Component (cf. IOTP Specification). 1653 Attributes (cf. IOTP Specification): 1655 xml:lang Defines the language used by attributes or 1656 child elements within this component, unless 1657 overridden by an xml:lang attribute on a child 1658 element. 1660 ContentSoftwareId Contains information which identifies the 1661 ssoftware that generated the content of the 1662 element. Its purpose is to help resolve 1663 interoperability problems that might occur as 1664 a result of incompatibilities between messages 1665 produced by different software. It is a single 1666 text string in the language defined by 1667 "xml:lang". It must contain, as a minimum 1668 problems that might occur as a result of 1670 o the name of the software manufacturer, 1671 o the name of the software, 1672 o the version of the software, and 1673 o the build of the software. 1675 ErrorCode Contains an error code which indicates the 1676 nature of the error in the message in error. 1677 Valid values for the Error Code are given in 1678 the following section. This mnemonic enables 1679 the automatic failure resolution of the IOTP 1680 Application Core which analyzes the error code 1681 value in order to determine the continuation 1682 alternatives. 1684 ErrorDesc Contains a description of the error in the 1685 language defined by xml:lang. The content of 1686 this attribute is defined by the 1687 vendor/developer of the software that 1688 generated the Error Response Element. 1689 It is intended for user display and provides 1690 detailed explanations about the failure and 1691 its (out-of-band) resolution alternatives. 1693 Severity Indicates the severity of the error. Valid 1694 values are: 1696 o Warning. This indicates that although there 1697 is a message in error the IOTP Transaction 1698 can still continue. 1700 o TransientError. This indicates that the 1701 error in the message in error may be 1702 recovered if the message in error that is 1703 referred to by the "Names" attribute is 1704 resent. 1706 o HardError. This indicates that there is an 1707 unrecoverable error in the message in error 1708 and the IOTP Transaction must stop. 1710 MinRetrySecs This attribute should be present if "Severity" 1711 is set to "TransientError". It is the minimum 1712 number of whole seconds which the IOTP aware 1713 application which received the message 1714 reporting the error should wait before re- 1715 sending the message in error identified by the 1716 "ErrorLocation" attribute. 1718 If Severity is not set to 1719 "TransientError" then the value of this 1720 attribute is ignored. 1722 SwVendorErrorRef This attribute is a reference whose value is 1723 set by the vendor/developer of the software 1724 that generated the Error Element. It should 1725 contain data that enables the vendor to 1726 identify the precise location in their 1727 software and the set of circumstances that 1728 caused the software to generate a message 1729 reporting the error. 1731 Content: 1733 ErrorLocation This identifies, where possible, the 1734 element and attribute in the message 1735 in error that caused the Error 1736 Element to be generated. If the 1737 "Severity" of the error is not 1738 "TransientError", more that one 1739 "ErrorLocation" may be specified as 1740 appropriate depending on the nature 1741 of the error and at the discretion of 1742 the vendor/developer of the IOTP 1743 Payment Bridge. 1745 Its definition coincides with the 1746 IOTP specification whereby the 1747 attributes "IotpMsgRef", "BlkRef" and 1748 "CompRef" are left blank, 1749 intentionally. 1751 PaySchemePackagedContent cf. Table 5 1753 3.1 Error Codes 1755 The following table lists the valid values for the ErrorCode 1756 attribute of the Error Response Element. The first sentence of the 1757 error description contains the default text that can be used to 1758 describe the error when displayed or otherwise reported. Individual 1759 implementations may translate this into alternative languages at 1760 their discretion. However, not every error code may apply to every 1761 API call. An Error Code must not be more than 14 characters long. 1763 The Error Codes have been taken from the IOTP Specification and 1764 extended by some additional codes which are highlighted by a 1765 preceding asterisk. 1767 Generally, if the corrupt values have been user supplied, the IOTP 1768 Application Core might prompt for their correction. If the renewal 1769 fails or if the IOTP Application Core skips any renewals and some 1770 notification has to be send to the counter-party, the error code is 1771 encapsulated within an IOTP Error Block. 1773 However, the IOTP server application reports business errors - 1774 visible at the IOTP layer - in the Status Component of the respective 1775 Response Block. 1777 The IOTP Application Core may add the attributes (and values) within 1778 the ErrorLocation elements being omitted by the IOTP Payment Bridge. 1780 The following table mentions any modification from this general 1781 processing for particular error values. Furthermore, it contains 1782 hints for developers of IOTP Application Core software components 1783 about the processing of error codes. Conversely, developers of IOTP 1784 Payment Bridges get impressions about the expected behavior of the 1785 IOTP Application Core. 1787 The IOTP Payment API assumes that the IOTP Application Core 1788 implements the dialog boxes needed for error resolution. But it does 1789 not assume, that the IOTP Payment Bridge actually relies on them. 1790 Instead, the IOTP Payment Bridge may try resolution on its own, may 1791 implement specific dialog boxes, and may signal only final failures. 1793 Note: This abstract document assumes that the API parameters are 1794 exchanged XML encoded. Therefore, several error values might 1795 disappear in lower level language specific derivations. 1797 Error Value Error Description 1799 Reserved Reserved. This error is reserved by the 1800 vendor/developer of the software. Contact 1801 the vendor/developer of the software for 1802 more information (see the SoftwareId 1803 attribute of the Message Id element in the 1804 Transaction Reference Block [IOTP]). 1806 XmlNotWellFrmd XML not well formed. The XML document is not 1807 well formed. See [XML] for the meaning of 1808 "well formed". 1810 XmlNotValid XML not valid. The XML document is well 1811 formed but the document is not valid. See 1812 [XML] for the meaning of "valid". 1813 Specifically: 1815 o the XML document does not comply with the 1816 constraints defined in the IOTP document 1817 type declaration, and 1818 o the XML document does not comply with the 1819 constraints defined in the document type 1820 declaration of any additional [XML-NS] 1821 that are declared. 1823 The Names attribute might refer some 1824 attributes and elements of the input 1825 parameter list. 1827 (*)ElNotValid Element not valid. Invalid element in terms 1828 of prescribed syntactical characteristics. 1830 The ElementRef attributes of ErrorLocation 1831 elements might refer to the corresponding 1832 elements (if they have ID attributes). 1834 The IOTP Application Core has to replace the 1835 error code with "XmlNotValid" before 1836 transmission to the counterparty. 1838 ElUnexpected Unexpected element. Although the XML 1839 document is well formed and valid, an 1840 element is present that is not expected in 1841 the particular context according to the 1842 rules and constraints contained in this 1843 specification. 1845 The ElementRef attributes of ErrorLocation 1846 elements might refer to the corresponding 1847 elements (if they have ID attributes). 1849 ElNotSupp Element not supported. Although the document 1850 is well formed and valid, an element is 1851 present that 1853 o is consistent with the rules and 1854 constraints contained in this 1855 specification, but 1856 o is not supported by the IOTP Aware 1857 Application which is processing the IOTP 1858 Message. 1860 The ElementRef attributes of ErrorLocation 1861 elements might refer to the corresponding 1862 elements (if they have ID attributes). 1864 ElMissing Element missing. Although the document is 1865 well formed and valid, an element is missing 1866 that should have been present if the rules 1867 and constraints contained in this 1868 specification are followed. 1870 The ElementRef attributes of ErrorLocation 1871 elements might refer to the corresponding 1872 elements (if they have ID attributes). 1874 ElContIllegal Element content illegal. Although the 1875 document is well formed and valid, the 1876 element contains values which do not conform 1877 the rules and constraints contained in this 1878 specification. 1880 The ElementRef attributes of ErrorLocation 1881 elements might refer to the corresponding 1882 element (if they have ID attributes). 1884 The IOTP Application Core has to replace the 1885 Error Code with "ElNotSupp" before 1886 transmission to the counter party, if the 1887 ErrorLocation elements refer to non 1888 PackagedContent element. 1890 EncapProtErr Encapsulated protocol error. Although the 1891 document is well formed and valid, the 1892 Packaged Content of an element contains data 1893 from an encapsulated protocol which contains 1894 errors. 1896 The ElementRef attributes of ErrorLocation 1897 elements might refer to the corresponding 1898 element (if they have ID attributes). 1900 AttUnexpected Unexpected attribute. Although the XML 1901 document is well formed and valid, the 1902 presence of the attribute is not expected in 1903 the particular context according to the 1904 rules and constraints contained in this 1905 specification. 1907 The AttName attributes of ErrorLocation 1908 elements might refer to the corresponding 1909 attribute tags. 1911 (*)AttNotValid Attribute not valid. Invalid attribute value 1912 in terms of prescribed syntactical 1913 characteristics. 1915 The AttName attributes of ErrorLocation 1916 elements might refer to the corresponding 1917 attribute tags. 1919 The IOTP Application Core has to replace the 1920 error code with "XmlNotValid" before 1921 transmission to the counter party. 1923 AttNotSupp Attribute not supported. Although the XML 1924 document is well formed and valid, and the 1925 presence of the attribute in an element is 1926 consistent with the rules and constraints 1927 contained in this specification, it is not 1928 supported by the IOTP Aware Application 1929 which is processing the IOTP Message. 1931 AttMissing Attribute missing. Although the document is 1932 well formed and valid, an attribute is 1933 missing that should have been present if the 1934 rules and constraints contained in this 1935 specification are followed. 1937 The AttName attributes of ErrorLocation 1938 elements might refer to the corresponding 1939 attribute tags. 1941 If the attribute is required by the IOTP 1942 Document Type Declaration (#REQUIRED) the 1943 hints for non valid attributes should be 1944 adopted, otherwise these for illegal 1945 attribute values. 1947 AttValIllegal Attribute value illegal. The attribute 1948 contains a value which does not conform to 1949 the rules and constraints contained in this 1950 specification. 1952 The AttName attributes of ErrorLocation 1953 elements might refer to the corresponding 1954 attribute tags - valid values are: 1956 BrandId: illegal/unknown Brand Identifier - 1957 If the brand is not recognized/known by any 1958 IOTP Payment Bridge, the IOTP Application 1959 Core may offer the registration of a new 1960 Payment Instrument. 1962 PaymentInstrumentId: illegal/unknown 1963 Payment Instrument Identifier - This 1964 indicates a serious communication problem if 1965 the attribute value has been reported by the 1966 same "wallet" on a previous inquiry 1967 requests. The IOTP Application Core has to 1968 replace the error code with 1969 "UnknownError" before transmission to the 1970 counter party. 1972 WalletId: illegal/unknown Wallet Identifier 1973 - It is assumed that the wallet identifier 1974 is checked before the pass phrase. On 1975 invalid wallet identifiers, the IOTP 1976 Application Core may open the dialog in 1977 order to request the correct wallet 1978 identifier. In addition, any pass phrase may 1979 be supplied by the user. The dialog should 1980 indicate the respective payment brand(s). 1981 The IOTP Application Core has to replace the 1982 error code with "UnknownError" before 1983 transmission to the counter party. 1985 Passphrase: illegal/unknown Pass Phrase - 1986 The IOTP Application Core may open the 1987 dialog in order to request the correct pass 1988 phrase. If the pass phrase is wallet 1989 identifier specific the dialog should 1990 display the wallet identifier. The IOTP 1991 Application Core has to replace the error 1992 code with "TransportError" before 1993 transmission to the counter party. 1995 Action: illegal / unknown / unsupported 1996 Action 1998 PropertyTypeList: lists contains illegal / 1999 unknown / unsupported Property Types - The 2000 IOTP Application Core tries only the local 2001 resolution but does never transmit any IOTP 2002 Error Block to the counter party. 2004 CurrCode: illegal/unknown/unsupported 2005 Currency Code 2007 CurrCodeType: illegal/unknown/unsupported 2008 Currency Code Type 2010 Amount: illegal/unknown/unsupported Payment 2011 Amount 2013 PayDirection: illegal/unknown/unsupported 2014 Payment Direction 2016 ProtocolId: illegal/unknown/unsupported 2017 Protocol Identifier 2019 OkFrom: illegal/unknown/unsupported OkFrom 2020 Timestamp 2022 OkTo: illegal/unknown/unsupported OkTo 2023 Timestamp 2025 ConsumerPayId: illegal/unknown Consumer 2026 Payment Identifier 2028 PaymentHandlerPayId: illegal/unknown Payment 2029 Handler Payment Identifier 2031 PayId: illegal/unknown Payment Identifier 2033 AttValNotRecog Attribute Value Not Recognized. The 2034 attribute contains a value which the IOTP 2035 Aware Application generating the message 2036 reporting the error could not recognize. 2038 The AttName attributes of ErrorLocation 2039 elements might refer to the corresponding 2040 attribute tags 2042 MsgTooLarge Message too large. The message is too large 2043 to be processed by the IOTP Payment Bridge 2044 (resp. IOTP Application Core). 2046 ElTooLarge Element too large. The element is too large 2047 to be processed by the IOTP Payment Bridge 2048 (resp. IOTP Application Core). 2050 The ElementRef attributes of ErrorLocation 2051 elements might might refer to the 2052 corresponding elements. 2054 ValueTooSmall Value too small or early. The value of all 2055 or part of an element content or an 2056 attribute, although valid, is too small. 2058 The ErrorLocation elements might refer to 2059 the corresponding attribute tags or 2060 elements. 2062 ValueTooLarge Value too large or in the future. The value 2063 of all or part of an element content or an 2064 attribute, although valid, is too large. 2066 The ErrorLocation elements might refer to 2067 the corresponding attribute tags or 2068 elements. 2070 ElInconsistent Element Inconsistent. Although the document 2071 is well formed and valid, according to the 2072 rules and constraints contained in this 2073 specification: 2075 o the content of an element is inconsistent 2076 with the content of other elements or 2077 their attributes, or 2078 o the value of an attribute is inconsistent 2079 with the value of one or more other 2080 attributes. 2082 The Error Description may contain further 2083 explanations. 2085 The ErrorLocation elements might refer to 2086 the corresponding attribute tags or elements 2087 that are inconsistent. 2089 TransportError Transport Error. This error code is used to 2090 indicate that there is a problem with the 2091 transport mechanism that is preventing the 2092 message from being received. It is typically 2093 associated with a "Transient Error". 2095 The connection to some 2096 periphery or the counter party could not be 2097 established, is erroneous, or has been lost. 2099 The Error Description may contain further 2100 narrative explanations, e.g., "chip card 2101 does not respond", "remote account manager 2102 unreachable", "Internet connection to xyz 2103 lost", "no Internet connection available", 2104 "no modem connected", or "serial port to 2105 modem used by another application". This 2106 text should be shown to the end user. If 2107 timeout has occurred at the Consumer this 2108 text should be shown and the Consumer may 2109 decide how to proceed - alternatives are 2110 retry, payment transaction suspension, and 2111 cancellation. 2113 MsgBeingProc Message Being Processed. This error code is 2114 only used with a Severity of Transient 2115 Error. It indicates that the previous 2116 message, which may be an exchange message or 2117 a request message, is being processed and, 2118 if no response is received by the time 2119 indicated by the "MinRetrySecs" attribute, 2120 then the original message should be resent. 2122 SystemBusy System Busy. This error code is only used 2123 with a Severity of Transient Error. It 2124 indicates that the IOTP Payment Bridge or 2125 Existing Payment Software that received the 2126 API request is currently too busy to handle 2127 it. If no response is received by the time 2128 indicated by the "MinRetrySecs" attribute, 2129 then the original message should be resent. 2131 The Error Description may provide further 2132 explanations, e.g., "wallet / chip card 2133 reader is unavailable or locked by another 2134 payment transaction", "payment gateway is 2135 overloaded", "unknown chip card reader", or 2136 "unrecognized chip card inserted, change 2137 chip card". 2139 The Consumer's IOTP Application Core may 2140 visualize the error description and ask the 2141 Consumer about the continuation - 2142 alternatives are retry, payment transaction 2143 suspension, and cancellation. 2145 UnknownError Unknown Error. Indicates that the 2146 transaction cannot complete for some reason 2147 that is not covered explicitly by any of the 2148 other errors. The Error description 2149 attribute should be used to indicate the 2150 nature of the problem. 2152 The ErrorLocation elements might refer to 2153 the corresponding attribute tags or elements 2154 that are inconsistent. 2156 (*)SyntaxError Syntax Error. An (unknown) syntax error has 2157 occurred. 2159 The ErrorLocation elements might refer to 2160 the corresponding attribute tags or elements 2161 that are inconsistent. 2163 The IOTP Application Core has to replace the 2164 error code with "XmlNotValid" or 2165 "UnknownError" before transmission to the 2166 counter party. 2168 (*)ReqRefused Request refused. The API request is 2169 (currently) refused by the IOTP Payment 2170 Bridge. The error description may provide 2171 further explanations, e.g., "wallet / chip 2172 card reader is unavailable or locked by 2173 another payment transaction", "payment 2174 gateway is overloaded", "unknown chip card 2175 reader", or "unrecognized chip card 2176 inserted, change chip card". 2178 The Consumer's IOTP Application Core may 2179 visualize the error description and ask the 2180 Consumer about the continuation - 2181 alternatives are retry, payment transaction 2182 suspension, and cancellation. Denials due to 2183 invalid Process States should be signaled by 2184 "BusinessError". Typically, this kind of 2185 error is not passed to the counter party's 2186 IOTP Application Core. Otherwise, it maps to 2187 "TransportError" or "UnknownError". 2189 (*)ReqNotSupp Request not supported. The API 2190 function(ality) has not been implemented in 2191 the IOTP Payment Bridge. Typically, this 2192 kind of error is not passed to the 2193 counter party's IOTP Application Core. 2194 Otherwise, it maps to "TransportError" or 2195 "UnknownError". 2197 (*)BusError Business Error. The API request has been 2198 rejected because some payment transaction 2199 has an illegal payment status. 2200 Particularly, this error code is used to 2201 signal any raise of payment business layered 2202 failures. 2204 The ErrorLocation elements may refer to 2205 payment transactions using the party's 2206 Payment Identifier - it defaults to the 2207 current transaction or might contain the 2208 current payment transaction party's Payment 2209 Identifier - identified by the ElementRef 2210 attribute while the AttName attribute is 2211 fixed with "PayId". 2213 The IOTP Application Core must inquire the 2214 IOTP Payment Bridge about the actual Process 2215 State which actually encodes the business 2216 error ("Inquire Process State"). 2217 This error code must not be 2218 passed to the counter party's IOTP 2219 Application Core. 2221 Table 2: Common Error Codes 2223 The IOTP Payment Bridge may also use the error description in order 2224 to notify the Consumer about further necessary steps for failure 2225 resolution, e.g., "sorry, your payment transaction failed. 2226 Unfortunately, you have been charged, please contact your issuer." 2228 3.2 Attributes and Elements 2230 The following table explains the XML attributes in alphabetical order 2231 - any parenthesized number behind the attribute tag recommends the 2232 maximal length of the attribute value in characters: 2234 Attribute Description 2236 Amount (11) Indicates the payment amount to be paid in 2237 AmountFrom(11) whole and fractional units of the currency. 2238 AmountTo (11) For example $245.35 would be expressed 2239 "245.35". Note that values smaller than the 2240 smallest denomination are allowed. For 2241 example one tenth of a cent would be 2242 "0.001". 2244 AuthenticationId An identifier specified by the 2245 authenticator which, if returned by the 2246 organization that receives the 2247 authentication request, will enable the 2248 authenticator to identify which 2249 authentication is being referred to. 2251 BrandId (128) This contains a unique identifier for the 2252 brand (or promotional brand). It is used to 2253 match against a list of Payment Instruments 2254 which the Consumer holds to determine 2255 whether or not the Consumer can pay with the 2256 Brand. 2258 Values of BrandId are managed under 2259 procedure being described in the IOTP 2260 protocol specification. 2262 BrandLogoNetLocn The net location which can be used to 2263 download the logo for the organization (cf. 2264 IOTP Specification). 2266 The content of this attribute must conform 2267 to [URL]. 2269 BrandName This contains the name of the brand, for 2270 example "MasterCard Credit". This is the 2271 description of the Brand which is displayed 2272 to the consumer in the Consumer's language 2273 defined by "xml:lang". For example it might 2274 be "American Airlines Advantage Visa". Note 2275 that this attribute is not used for matching 2276 against the payment instruments held by the 2277 Consumer. 2279 BrandNarrative This optional attribute is 2280 used by the Merchant to indicate some 2281 special conditions or benefit which would 2282 apply if the Consumer selected that brand. 2283 For example "5% discount", "free shipping 2284 and handling", "free breakage insurance for 2285 1 year", "double air miles apply", etc. 2287 CallBackFunction A function which is called whenever there is 2288 a change of Process State or payment 2289 progress, e.g. for display updates. However, 2290 the IOTP Payment Bridge may use its own 2291 mechanisms and dialog boxes. 2293 CallBackLanguageLis A list of language codes which contain, in 2294 t order of preference, the languages in which 2295 the text passed to the Call Back function 2296 will be encoded. 2298 CompletionCode (14) Indicates how the process completed. 2299 It is required if ProcessState is set to 2300 "Failed" otherwise it is ignored. Valid 2301 values as well as recovery options are given 2302 in the IOTP specification. 2304 The IOTP Payment Bridge may also use the 2305 Status Description to notify the Consumer 2306 about further necessary steps in order to 2307 resolve some kind of business failures, 2308 e.g., 2310 o "sorry, your payment transaction failed. 2311 Unfortunately, you have been charged, 2312 please contact your issuer." 2313 o "insufficient capacity left (on your card) 2314 for refund", 2315 o "payment failed/chip card error/internal 2316 error, please contact your payment 2317 instrument's issuer" 2319 ConsumerDesc A narrative description of the Consumer. 2321 ConsumerPayId (14) An unique identifier specified by the 2322 Consumer that, if returned by the Payment 2323 Handler in another Payment Scheme Component 2324 or by other means, enables the Consumer to 2325 identify which payment is being referred to. 2327 This unique identifier is generated by the 2328 IOTP Application Core and submitted to the 2329 IOTP Payment Bridge on every API call. It 2330 may equal to the Payment Handler Payment 2331 Identifiers but need not necessarily be so. 2333 The uniqueness extends to multiple payment 2334 instruments, payment brands, payment 2335 protocols, wallet identifiers, and even 2336 multiple IOTP Payment Bridges. 2338 ContStatus During payment progress, this status value 2339 indicates whether the payment needs to be 2340 continued with further IOTP Payment Scheme 2341 Component exchanges with the remote party. 2342 "End" indicates that the reported payment 2343 scheme data is the last data to be exchanged 2344 with the counter party. 2346 ContentSoftwareId This contains information that identifies 2347 the software that generated the content of 2348 the element. Its purpose is to help resolve 2349 interoperability problems that might occur 2350 as a result of incompatibilities between 2351 messages produced by different software. It 2352 is a single text string in the language 2353 defined by xml:lang. It must contain, as a 2354 minimum: 2356 o the name of the software manufacturer, 2357 o the name of the software, 2358 o the version of the software, and 2359 o the build of the software. 2361 CurrCodeType (14) Indicates the domain of the CurrCode. This 2362 attribute is included so that the currency 2363 code may support nonstandard currencies 2364 such as frequent flyer point, trading 2365 stamps, etc. Its values may be 2367 o ISO-4217-A, the default, indicates the 2368 currency code is the three-letter 2369 alphabetic code that conform to ISO 4217 2371 o IOTP indicates that the values of 2372 CurrCode are managed under the procedure 2373 described in [IOTP]. 2375 CurrCode (14) A code which identifies the currency to be 2376 used in the payment. The domain of valid 2377 currency codes is defined by "CurrCodeType" 2379 MerchantPayId (14) An private identifier specified by the 2380 Merchant which will enable the Merchant to 2381 identify which payment is being referred to. 2382 It is a pure private item and is never sent 2383 to any other party. It is provided by the 2384 IOTP Payment Bridge on payment preparation 2385 during brand compilation. 2387 Cf. To "ConsumerPayId" for note about 2388 uniqueness. 2390 MerchantOrgId (64) A local item that might refer to some 2391 specific shop in a multi shop environment. 2392 This item is optional and might enrich the 2393 Wallet Identifier which itself can be used 2394 for the same purpose. 2396 Name Distinguishes between multiple occurrences 2397 of Packaged Content Elements at the same 2398 point in IOTP. For example: 2400 2401 2402 snroasdfnas934k 2403 2404 2405 dvdsjnl5poidsdsflkjnw45 2406 2407 2408 The "Name" attribute may be omitted, for 2409 example if there is only one Packaged 2410 Content element. 2412 OkFrom (30) The date and time in UTC Format range 2413 OkTo (30) indicated by the merchant in which the 2414 Payment Handler may accept the payment. 2416 Passphrase (32) Payment wallets may use pass phrase 2417 protection for transaction data and payment 2418 instruments' data. However, it is assumed 2419 that there exists a public and customizable 2420 payment instrument identifier such that 2421 these identifiers together with their 2422 relationship to payment brands, payment 2423 protocols, payment directions, and currency 2424 amounts can be inquired by the IOTP 2425 application without any pass phrase 2426 knowledge. 2428 PayDirection Indicates the direction in which the 2429 payment for which a Brand is being selected 2430 is to be made. Its values may be: 2432 o Debit: The sender of the Payment Request 2433 Block (e.g. the Consumer) to which this 2434 Brand List relates will make the payment 2435 to the Payment Handler, or 2436 o Credit: The sender of the Payment Request 2437 Block to which this Brand List relates 2438 will receive a payment from the Payment 2439 Handler. 2441 PayId (14) This attribute is introduced for API 2442 simplification: 2444 o The Consumer has to identify PayId and 2445 ConsumerPayId. 2447 o The Merchant has to identify PayId and 2448 MerchantPayId. 2450 o The Payment Handler has to identify PayId 2451 and Payment Handler Pay Id. 2453 PayInstId This contains the unique identifier used 2454 internally by the IOTP Payment 2455 Bridge/Existing Payment Software. 2457 PayInstName This contains the user-defined name of the 2458 payment instrument. There exist no 2459 (technical) constraints like uniqueness. The 2460 "xml:lang" attribute denotes the language 2461 encoding of its value. 2463 PaymentHandlerDesc A narrative description of the Payment 2464 Handler. 2466 PaymentHandlerPayId An unique identifier specified by the 2467 (14) Payment Handler that, if returned by the 2468 Consumer in another Payment Scheme Component 2469 or by other means, enables the Payment 2470 Handler to identify which payment is being 2471 referred to. It is required whenever it is 2472 known. 2474 Cf. To "ConsumerPayId" for note about 2475 uniqueness. 2477 PaymentInstrumentId An identifier for a specific payment 2478 (32) instrument, e.g. "credit card", "Mondex card 2479 for English Pounds". This identifier is 2480 fully customizable. It is assumed, that it 2481 does not contain confidential information or 2482 even an indication to it. The payment 2483 instrument identifier is unique within each 2484 payment brand. It is displayed to the 2485 Consumer during brand selection. 2487 PayReceiptNameRefs Optionally contains element references to 2488 (32) other elements (containing payment scheme 2489 specific data) that together make up the 2490 receipt. Note that each payment scheme 2491 defines in its supplement the elements that 2492 must be referenced 2494 The IOTP Application Core should save all 2495 the components referenced so that the 2496 payment receipt can be reconstructed when 2497 required. 2499 PayReqNetLocn The Net Location indicating where an 2500 unsecured Payment Request message should be 2501 sent if this protocol choice is used. 2503 The content of this attribute must conform 2504 to [URL] and depends on the Transport 2505 Mechanism. 2507 PercentComplete (3) A number between 0 and 100 which indicates 2508 the progress of the payment transaction. The 2509 values range between 0 and 99 for pending 2510 and suspended transactions. 2512 ProcessState Contains a Process State Code that 2513 indicates the current state of the process 2514 being carried out. Valid values are: 2516 o NotYetStarted. The Payment Request Block 2517 has been received but processing of the 2518 Payment Request has not yet started 2520 o InProgress. The payment transaction is 2521 pending. The processing of the (Payment) 2522 Request Block has started but it is not 2523 yet complete. 2525 o (*)Suspended: The payment transaction has 2526 been suspended and can be resumed. 2528 This process state is mapped to 2529 "InProgress", if it is passed to the 2530 counter party's IOTP Application Core. 2532 o CompletedOk. The processing of the (Payment) 2533 Request Block and any following Payment 2534 Exchange Blocks has completed successfully. 2536 o Failed. The payment processing has finally 2537 failed for a Business Error. 2539 o ProcessError. This value is only used 2540 when the Status Component is being used in 2541 connection with an Inquiry Request Trading 2542 Block. It indicates there was a Technical 2543 Error in the Request Block which is being 2544 processed or some internal processing 2545 error. Each party's IOTP Payment Bridge 2546 uses this value in order to notify the 2547 IOTP Application Core about the presence 2548 of technical errors. 2550 PropertyType (14) The property type defines codes used for 2551 interrogation of specific properties about a 2552 payment instrument. They are unique for each 2553 payment brand. The predefined property "all" 2554 is used on general inquiries. However, these 2555 property types are not used during normal 2556 payment processing. E.g., they may apply to 2557 payment brand specific transactions or out- 2558 of-band failure resolution. 2560 PropertyDesc The property description carries the 2561 respective human readable property (value)'s 2562 description. 2564 PropertyValue The actual property value intends automatic 2565 post processing. 2567 ProtocolBrandId (64)This is an identifier to be used with a 2568 particular payment protocol. For example, 2569 SET and EMV have their own well defined, yet 2570 different, values for the Brand identifier 2571 to be used with each protocol. The valid values 2572 of this attribute are defined in the 2573 supplement for the payment protocol 2574 identified by "ProtocolId" that describes 2575 how the payment protocol works with IOTP. 2576 Identifier maps to at most one Protocol 2577 Brand Identifier. 2579 ProtocolId (64) An identifier for a specific payment 2580 protocol and version, e.g. "SETv1.0", 2581 "ecash". Valid values are defined by 2582 supplements to the IOTP specification and 2583 they are unique within each payment brand. 2585 ProtocolIds A sequence of Protocol Identifiers 2587 ProtocolName A narrative description of the payment 2588 protocol and its version in the language 2589 identified by "xml:lang". For example 2590 "Secure Electronic Transaction Version 1.0". 2591 Its purpose is to help provide information 2592 on the payment protocol being used if 2593 problems arise. 2595 SecPayReqNetLocn The Net Location indicating where a secured 2596 Payment Request message should be sent if 2597 this protocol choice is used. 2599 A secured payment involves the use of a 2600 secure channel such as [SSL]/[TLS] in order 2601 to communicate with the Payment Handler. 2603 The content of this attribute must conform 2604 to [URL]. 2606 ReceiverOrgId The Organization Identification which 2607 receives the payment bridge processing 2608 Trading Role Data PackagedContent. 2610 StatusDesc (256) An optional textual description of the 2611 current process state in the language 2612 identified by "xml:lang" that should be 2613 displayed to the Consumer. The usage of this 2614 attribute is defined in the payment 2615 supplement for the payment method being 2616 used. Particularly, it provides hints for 2617 out-of-band failure resolution. Its length 2618 is limited to 256 characters. 2620 StyleSheetNetLocn This contains the net location to a style 2621 sheet with visualisation rules for XML 2622 encoded data. 2624 TimeStamp (30) The date and time in UTC Format when the 2625 payment transaction has been started. 2627 WalletId (32) Many existing payment wallet software are 2628 multiple wallet capable. The Wallet 2629 Identifier selects the actual wallet. It is 2630 assumed, that the wallet identifier is a 2631 public item, that might be stored by the 2632 IOTP Application Core. 2634 xml:lang Defines the language used by the Process 2635 State Description attribute (cf. IOTP 2636 Specification) 2638 Table 3: Attributes 2640 The following table explains the XML elements in alphabetical 2641 order: 2643 Element Description 2645 Algorithm This contains information which describes 2646 an Algorithm that may be used to generate 2647 the Authentication response. 2649 The algorithm that may be used is 2650 identified by the Name attribute (cf. IOTP 2651 Specification). 2653 AuthReqPackagedContent The Authentication Request Packaged 2654 Content originates from a Authentication 2655 (Data/Response) Component's content 2656 whereby the outermost element tags are 2657 prefixed with "AuthReq". Its declaration 2658 coincides with the Packaged Content's 2659 declaration (cf. IOTP Specification). It 2660 encapsulates the authentication challenge 2661 value. The content of this information is 2662 defined in the supplement for a payment 2663 protocol. 2665 AuthResPackagedContent The Authentication Response Packaged 2666 Content originates from a Authentication 2667 Response Component's content whereby the 2668 outermost element tags are prefixed with 2669 "AuthRes". 2671 Its declaration coincides with the 2672 Packaged Content's declaration (cf. IOTP 2673 Specification). It encapsulates the 2674 authentication response value. The 2675 content of this information is defined in 2676 the supplement for a payment protocol. 2678 BrandPackagedContent Container for further payment brand 2679 description. Its content originates from 2680 a Brand Element content whose outermost 2681 element tags are prefixed with "Brand". 2682 Its declaration coincides with the 2683 Packaged Content's declaration (cf. IOTP 2684 Specification). 2686 BrandSelBrandInfoPacka This contains any additional data that 2687 gedContent may be required by a particular payment 2688 brand. It forms the content of the Brand 2689 Selection Brand Info Element. 2691 BrandSelProtocolAmount This contains any additional data that 2692 InfoPackagedContent may be required by a particular payment 2693 brand in the format. It forms the content 2694 of the Brand Selection Protocol Amount 2695 Info Element. 2697 BrandSelCurrencyAmount This contains any additional data that 2698 InfoPackagedContent payment brand and currency specific in 2699 the format. It forms the content of the 2700 Brand Selection Currency Amount Info 2701 Element. 2703 MerchantData Any merchant related data that might be 2704 used by the IOTP Payment Bridge for 2705 different purposes, e.g., it might 2706 contain access keys to some mall keys. 2707 Its declaration coincides with the 2708 Packaged Content's declaration (cf. IOTP 2709 Specification). 2711 PackagedContent Generic Container for non-IOTP data (cf. 2712 IOTP Specification). 2714 PayProtocolPackaged The Pay Protocol Packaged Content 2715 Content originates from a Pay Protocol 2716 Element's content whereby the outermost 2717 element tags are prefixed with 2718 "PayProtocol". It contains information 2719 about the protocol which is used by 2720 the payment protocol. The content of 2721 this information is defined in the 2722 supplement for a payment protocol.Its 2723 declaration coincides with the Packaged 2724 Content's declaration (cf. IOTP 2725 Specification). 2727 PaySchemePackagedConte The PayScheme Packaged Content originates 2728 nt from a Payment Scheme Component's content 2729 whereby the outermost element tags are 2730 prefixed with "PayScheme". Its 2731 declaration coincides with the Packaged 2732 Content's declaration (cf. IOTP 2733 Specification). It carries the payment 2734 specific data. The content of this 2735 information is defined in the supplement 2736 for a payment protocol. 2738 ProtocolAmountPackaged The Protocol Amount Packaged Content 2739 Content originates from a Protocol Amount 2740 Element's content whereby the outermost 2741 element tags are prefixed with "Amount". 2742 Its declaration coincides with the 2743 Packaged Content's declaration (cf. IOTP 2744 Specification). It contains information 2745 about the protocol which is used by the 2746 payment protocol. The content of this 2747 information is defined in the supplement 2748 for a payment protocol. 2750 ProtocolBrandPackagedC The Protocol Brand Packaged Content 2751 ontent originates from a Protocol Brand 2752 Element's content whereby the outermost 2753 element tags are prefixed with 2754 "ProtocolBrand". Its declaration 2755 coincides with the Packaged Content's 2756 declaration (cf. IOTP Specification). It 2757 contains information about the brand 2758 which might be used by the payment 2759 protocol. The content of this information 2760 is defined in the supplement for a 2761 payment protocol. 2763 ResponsePackagedConten Container for authentication response 2764 t data. Its content originates from a 2765 Authentication Response Component's 2766 Packaged Content whose outermost element 2767 tags are prefixed with "Response". Its 2768 declaration coincides with the Packaged 2769 Content's declaration (cf. IOTP 2770 Specification). 2772 TradingRoleDataPackage The TradingRoleData Packaged Content 2773 dContent originates from a TradingRoleData 2774 Component's content whereby the outermost 2775 element tags are prefixed with 2776 "TradingRoleData". Its declaration 2777 coincides with the Packaged Content's 2778 declaration (cf. IOTP Specification). It 2779 contains information from Merchant to 2780 Payment Handler via Consumer about the 2781 protocol which is used by the payment. 2782 The content of this information is 2783 defined in the supplement for a payment 2784 protocol. The Name attribute in this 2785 packaged contents must include prefix as 2786 "Payment:" to indicate that the payment 2787 bridge processes this, for example 2788 "Payment:SET-OD" 2790 The element's declaration coincides with 2791 the Packaged Content's declaration (cf. 2792 IOTP Specification). 2793 Table 4: Elements 2795 XML definition: 2799 2806 2810 2812 2814 2816 3.3 Process States 2817 The IOTP Payment API supports six different attribute values that 2818 encode the transaction status from the IOTP's point of view, i.e. the 2819 appropriate point of view at the interface between the IOTP 2820 Application Core and IOTP Payment Bridge. This point of view does not 2821 completely mimic the more detailed view on the actual payment by the 2822 genuine Existing Payment Software or IOTP Payment Bridge. 2824 The following three tables distinguish between the Merchant's, 2825 Consumer's, and Payment Handlers' environment. They extend the 2826 aforementioned explanations towards the mapping between IOTP process 2827 states and the internal payment scheme related states of the Existing 2828 Payment Software/IOTP Payment Bridge. 2830 3.3.1 Merchant 2832 The Merchant's point of view of payment is limited to the local 2833 payment initiation being interlaced with order processing because 2834 IOTP assigns the actual payment processing to the Payment Handler. 2836 ProcessState Description 2837 NotYetStarted The Payment Transaction exists within the 2838 IOTP Application Core, i.e., the 2839 Merchant's shop has already signaled to 2840 the IOTP Application Core that an IOTP 2841 transaction has been initiated by the 2842 Consumer. 2844 However, neither any API call has been 2845 issued to the IOTP Payment Bridge nor the 2846 IOTP Order Request has been created. 2848 InProgress The IOTP Application changes the process 2849 state to this value when it issues the 2850 first API call to the Payment Bridge 2851 during Brand List compilation. 2853 This value indicates that the Payment 2854 Bridge might have some knowledge about 2855 the expected payment or might have 2856 performed some preparatory tasks (even 2857 with the Payment Handler out-of-band to 2858 IOTP). 2860 However, this value does not indicate 2861 that some IOTP Order Request has been 2862 created and transmitted to the Consumer. 2864 Suspended The IOTP transaction has been suspended 2865 before the order request block has been 2866 transmitted to the Consumer. 2868 Implicitly, the payment is also deferred. 2870 CompletedOk The IOTP Order Request has been 2871 successfully created and transmitted to 2872 the Consumer. Actually, this process 2873 state indicates only that the order 2874 processing has been finished. 2876 But it contains no indication about the 2877 status of the genuine payment, which is 2878 accepted by the Payment Handler. 2880 However, successful order processing 2881 signals the IOTP Application Core that a 2882 payment with some specific parameters is 2883 expected within the near future. And this 2884 signal might be used by the Existing 2885 Payment Software for similar purposes. 2886 This attribute might be interpreted as 2887 successful preparation of the payment 2888 system. 2890 Particularly, it is expected that the 2891 Existing Payment Software maps this IOTP 2892 status value to some other internal 2893 value, e.g. "NotYetStarted", that is more 2894 accurate from its point of view. 2896 As IOTP provides no communication channel 2897 between the Merchant and Payment Handler, 2898 any change of payment process state will 2899 be initiated out-of-band to IOTP, e.g. by 2900 electronic statements of account or 2901 payment scheme specific mechanisms. 2903 Failed The IOTP transaction, i.e. order 2904 processing, has failed for some 2905 (business) reason and it is known that no 2906 payment will occur. 2908 This indication might be used to clear 2909 all data about this transaction within 2910 the Existing Payment Bridge (by 2911 "RemovePaymentLog" or 2912 "ChangeProcessState") or to reverse any 2913 preparation (with the Payment Handler 2914 out-of-band to IOTP). 2916 However, the ideal point of view of IOTP 2917 suspects that the genuine payment 2918 transaction has been neither started nor 2919 initiated. 2921 ProcessError The IOTP transaction, i.e. order 2922 processing, has failed for some 2923 (technical) reason and it is known that 2924 no payment will occur. 2926 This indication might be used to clear 2927 all data about this transaction within 2928 the Existing Payment Bridge (by 2929 "RemovePaymentLog" or 2930 "ChangeProcessState") or to reverse any 2931 preparation (with the Payment Handler 2932 out-of-band to IOTP). 2934 However, the ideal point of view of IOTP 2935 suspects that the genuine payment 2936 transaction has been neither started nor 2937 initiated. 2938 Table 5: Merchant 2940 3.3.2 Consumer 2942 The Consumer's IOTP Application Core restricts its point of view to 2943 the payment transaction. It is assumed that the IOTP Payment Bridge 2944 handles the preceding brand selection process in a stateless manner. 2946 NotYetStarted This encodes the initial process state of 2947 any IOTP payment transaction. This value 2948 is set during brand selection but it will 2949 not change during the whole brand 2950 selection process, normally. 2952 InProgress With the issuance of the Start Payment 2953 Consumer API call, the IOTP Application 2954 Core changes the process state to this 2955 value. 2957 Suspended The payment transaction has been 2958 suspended. Suspension may occur anywhere 2959 during brand selection (with the 2960 Merchant) or payment processing (with the 2961 Payment Handler). On resumption, the IOTP 2962 Application Core and the IOTP Payment 2963 Bridge have to use other internal data to 2964 decide whether brand selection or actual 2965 payment processing needs to be continued, 2966 i.e., whether the process state needs to 2967 be reset to "NotYetStarted" or 2968 "InProgress". 2970 Note that the Payment API assumes 2971 stateless brand selection by the IOTP 2972 Payment Bridge. Typically, any suspension 2973 during brand selection requires the 2974 repetition of the whole process. Hereby, 2975 the IOTP Application Core might to 2976 consider any already negotiated 2977 conditions in a brand depended purchase 2978 (brand, protocol). 2980 CompletedOk The successful payment has been 2981 acknowledged by the Payment Handler, i.e. 2982 the successful IOTP Payment Response has 2983 been received. 2985 Implicitly, this implies successful order 2986 processing. 2988 Failed The IOTP transaction, i.e. order or 2989 payment processing, has failed for some 2990 (business) reason. In either case it is 2991 known that the payment will not succeed. 2993 ProcessError The IOTP transaction, i.e. order or 2994 payment processing, has failed for some 2995 (technical) reason. 2997 However, the local process state might be 2998 different from that of Payment Handler. 3000 Table 6: Consumer 3002 3.3.3 Payment Handler 3004 The Payment Handler is responsible for the actual payment processing. 3005 New payment transactions are reported by the Consumer with the 3006 transmission of new IOTP Payment Request Blocks. IOTP Payment 3007 Exchange Block are send by the Consumer for payment transaction 3008 continuation and resumption. 3010 NotYetStarted This encodes the initial process state of 3011 any payment transaction. Typically, this 3012 value will last for a short amount of 3013 time. 3015 InProgress The IOTP Application Core changes the 3016 process state changes to "InProgress" 3017 when the Payment Handler starts with the 3018 actual processing of the IOTP Payment 3019 Request Block. 3021 Note that this does not assume that the 3022 "StartPaymentPaymentHandler" API function 3023 has been called. 3025 Suspended The payment transaction has been 3026 suspended. 3028 CompletedOk The payment has been processed, 3029 successfully, i.e. the IOTP Payment 3030 Response Block was created and 3031 transmitted to the Consumer. 3033 Failed The payment transaction, has finally 3034 failed for some (business) reason. 3036 Note that this value encodes the payment 3037 state reported by the IOTP Payment Bridge 3038 on "InquireProcessState". It does neither 3039 reflect whether the payment receipt has 3040 been inquired nor whether the IOTP 3041 Payment Response Block has been created 3042 and submitted to the Consumer. 3044 ProcessError The payment transaction, has finally 3045 failed for some (technical) reason. 3047 Note that this value encodes the payment 3048 state reported by the IOTP Payment 3049 Bridge. It does not reflect whether some 3050 IOTP Error Block has been created and 3051 submitted to the Consumer. 3052 Table 7: Consumer 3054 4. Payment API Calls 3056 4.1 Brand Compilation Related API Calls 3058 4.1.1 Find Accepted Payment Brand 3060 This API finction determines the payment brands being accepted by the 3061 Payment Handler on behalf of the Merchant. 3063 Input Parameters 3065 o Payment Direction - provided by the IOTP Application Core 3066 o Currency Code and Currency - provided by the IOTP Application 3067 Core 3068 o Payment Amount - provided by the IOTP Application Core 3069 o Merchant Payment Identifier - Merchant's unique private 3070 reference to the payment transaction 3071 o Merchant Organisation Identifier - used for distinction between 3072 multiple merchants that share the some IOTP merchant system 3073 o Wallet Identifier - managed by the IOTP Application Core 3074 o Merchant Data - specific data used by the IOTP Payment Bridge 3075 which is managed in the IOTP Application Core. 3077 XML definition: 3079 3080 3089 Output Parameters 3091 o Payment Brand Identifier - for insertion in the Brand List 3092 Component's Brand Element 3093 o Payment Brand Name and language annotation - for insertion in 3094 the Brand List Component's Brand Element 3095 o Payment Brand Logo Net Location - for insertion in the Brand 3096 List Component's Brand Element 3097 o Payment Brand Narrative Description - for insertion in the 3098 Brand List Component's Brand Element 3099 o (Brand) Packaged Content - further payment brand description 3100 for insertion in the Brand List Component's Brand Element 3102 The Existing Payment Software returns an empty list of brand items, 3103 if it does not support any payment brand/payment protocol combination 3104 for the given payment parameters. 3106 XML definition: 3108 3109 3110 3117 Tables 4 and 5 explain the attributes and elements; Table 3 3118 introduces the Error Codes. 3120 4.1.2 Find Accepted Payment Protocol 3122 This API function determines the instances of payment protocols (and 3123 optionally the payment brands) being accepted by the Payment Handler 3124 on behalf of the Merchant. The function might be called in two 3125 variants: 3127 o With the Brand Identifier set on the input parameter list: The 3128 function responds with the payment protocols that fits to the 3129 submitted brand. 3131 o Without any Brand Identifier - that allows the omission of the 3132 "Find Accepted Payment Brand" API call (cf. Section 4.1.1): This 3133 function responds with both the supported brand identifiers and 3134 the payment protocols being related by the Brand Elements. 3136 Input Parameters 3138 o Brand Identifier - returned by "Find Accepted Payment Brand" 3139 o Payment Direction 3140 o Currency Code and Currency 3141 o Payment Amount 3142 o Merchant Payment Identifier - Merchant's unique private 3143 reference to the payment transaction 3144 o Merchant Organisation Identifier - used for distinction between 3145 multiple merchants that share the some IOTP merchant system 3146 o Wallet Identifier - managed by the IOTP Application Core 3147 o (Brand) Packaged Content - further payment brand description; 3148 returned by "Find Accepted Payment Brand"; this elements are 3149 only provided iff the Brand Identifier is set 3150 o Merchant Data - specific data used by the IOTP Payment Bridge 3151 which is managed in the IOTP Application Core. 3153 XML definition: 3155 3157 3167 Output Parameters 3169 o Payment Protocol Identifier - for insertion in the Brand List 3170 Component's Pay Protocol Element 3171 o Protocol Brand Identifier - for insertion in the Protocol Brand 3172 Element of the Brand List Component's Brand Element 3173 o Payment Protocol Name and language annotation- for insertion in 3174 the Brand List Component's Pay Protocol Element 3175 o Payment Request Net Location - for insertion in the Brand List 3176 Component's Pay Protocol Element 3177 o Secured Payment Request Net Location - for insertion in the 3178 Brand List Component's Pay Protocol Element 3179 o Brand Item List (cf. Section 4.1.1) - there must be at least 3180 one element if no brand identifier has been provided on the 3181 input parameter list. 3182 o (Protocol Amount) Packaged Content - for insertion in the Brand 3183 List Component's Protocol Amount Element 3184 o (Pay Protocol) Packaged Content - for insertion in the Brand 3185 List Component's Pay Protocol Element 3186 o Currency Amount element - quite similar to the definition in 3187 [IOTP], that contain 3188 - refined Currency Code and Currency - for insertion in the 3189 Brand List Component's Currency Amount Element 3190 - refined Payment Amount - for insertion in the Brand List 3191 Component's Currency Amount Element 3192 o Brand - there must be at least one element in each Protocol 3193 Item if no brand identifier has been provided on the input 3194 parameter list. 3196 XML definition: 3198 3200 3203 3211 3212 3215 3216 3221 Tables 4 and 5 explain the attributes and elements; Table 3 3222 introduces the Error Codes. 3224 4.1.3 Get Payment Initialization Data 3226 This API function provides the remaining initialization data being 3227 required by the Consumer's or Payment Handler's Existing Payment 3228 Software. This function might be called both for "brand dependent" 3229 and "brand independent" transaction types. In ether case, this 3230 function is called with one particular brand. 3232 Input Parameters 3234 o Brand Identifier - returned by "Find Accepted Payment Brand" 3235 o Merchant Payment Identifier - Merchant's unique private 3236 reference to the payment transaction 3238 o Payment Direction 3239 o Currency Code and Currency - from the Brand List Component's 3240 Currency Amount Element 3241 o Payment Amount - from the Brand List Component's Currency 3242 Amount Element 3243 o Payment Protocol Identifier - from the Brand List Component's 3244 Pay Protocol Element 3245 o Protocol Brand Identifier - from the Protocol Brand Element 3246 which relates to the selected Brand Element, if any 3248 o (TradingRoleData) Receiver Organization Identifier 3250 o OkFrom, OkTo - identical to the entries of the Order Component 3252 Merchant Payment Identifier 3254 o Merchant Organisation Identifier - used for distinction between 3255 multiple merchants that share the some IOTP merchant system 3256 o Wallet Identifier and/or Pass Phrase 3258 Protocol Brand Element 3260 o (Brand) Packaged Content - further payment brand description, 3261 from the Brand List Component's Brand Element 3262 o (Protocol Amount) Packaged Content - further payment protocol 3263 description, from the Brand List Component's Protocol Amount 3264 Element 3265 o (Pay Protocol) Packaged Content - further payment protocol 3266 description, from the Brand List Component's Pay Protocol 3267 Element 3269 o (Protocol Brand) Packaged Content - further brand information, 3270 from the Protocol Brand Element of the Brand List Component 3271 which relates to the selected Brand Element, if any 3273 o (Order) Packaged Content - further order description, from the 3274 Order Element 3275 o three Brand Selection Info Packaged Content elements - copied 3276 from the Brand Selection Component on brand dependent purchases 3277 o Brand - additional data about the payment brand 3278 o Protocol Amount - additional data about the payment protocol 3279 o Currency Amount - additional payment brand and currency 3280 specific data 3281 o Merchant Data - specific data used by the IOTP Payment Bridge 3282 which is managed in the IOTP Application Core. 3284 XML definition: 3286 3295 3310 Output Parameters 3312 o OkFrom, OkTo - for insertion in the Payment Component 3313 o (TradingRoleData) Packaged Content - further payment protocol 3314 description; the Name Attribute of the packaged Content 3315 element must include "Payment:" as the prefix, 3316 for example "Payment:SET-OD". 3317 o (Order) Packaged Content - defaults to the supplied order 3318 packaged content if omitted. 3320 XML definition: 3322 3325 3329 Tables 4 and 5 explain the attributes and elements; Table 3 3330 introduces the Error Codes. 3332 4.1.4 Inquire Authentication Challenge 3334 This API function inquires any payment protocol specific 3335 authentication challenge value from the IOTP Payment Bridge. In 3336 Baseline IOTP this API function is called by the Merchant (or 3337 Financial Institution). The IOTP Application Core may propose a 3338 choice of algorithms to the IOTP Payment Bridge. However, the IOTP 3339 Payment Bridge may ignore the proposal and select some other 3340 algorithm. 3342 The inquiry is assumed to be stateless. E.g., the IOTP Application 3343 Core may check the returned algorithm and stop transaction processing 3344 without notifying the IOTP Payment Bridge. 3346 The IOTP Application Core may issue several API calls to the IOTP 3347 Payment Bridge to build up the IOTP Authentication Request Block. Any 3348 subsequently submitted choice of algorithms should be reduced by the 3349 accepted algorithms from earlier API responses. 3351 The IOTP Payment Bridge responds with the Business Error Code if it 3352 does not provide any (more) authentication algorithms and challenges. 3354 Input Parameters 3356 o Authentication Identifier - the authenticator may provide its 3357 payment identifier, i.e., Payment Handler or Merchant Payment 3358 Identifier. 3359 o Wallet Identifier and/or Pass Phrase 3360 o set of pre-selected algorithms for authentication 3362 XML definition: 3364 3365 3370 Output Parameters 3372 o list of Authentication Challenge Packaged Contents - for 3373 insertion into the IOTP Authentication Request Component 3374 o Algorithm Element - for insertion into the IOTP Authentication 3375 Request Component 3377 XML definition: 3379 3382 Tables 4 and 5 explain the attributes and elements; Table 3 3383 introduces the Error Codes. 3385 4.1.5 Authenticate 3387 The Consumer's IOTP Application Core defers payment protocol specific 3388 authentication processing and the current challenge value to the 3389 active IOTP Payment Bridge. Alternative authentication algorithms 3390 might be tried sequentially or offered to the user for selection. 3392 Note that the IOTP Application Core has to consider both the current 3393 context and the algorithm in order to determine the responsible IOTP 3394 Payment Bridge. 3396 Failed authentication is reported by the Business Error Code which 3397 might trigger the inquiry of the details ("Inquire Process State"). 3398 Final failures might be encoded by the process state "Failed". 3400 Input Parameters 3402 o Authentication Identifier 3403 o Wallet Identifier and/or Pass Phrase 3404 o Authentication Challenge Packaged Content - copied from the 3405 IOTP Authentication Request Component 3406 o Algorithm Element - copied from the IOTP Authentication Request 3407 Component 3409 XML definition: 3411 3412 3417 Output Parameters 3419 o Authentication Response Packaged Content - for insertion into 3420 the IOTP Authentication Response Component 3422 XML definition: 3424 3426 Tables 4 and 5 explain the attributes and elements; Table 3 3427 introduces the Error Codes. 3429 4.1.6 Check Authentication Response 3431 This API function verifies the Consumer's payment protocol specific 3432 authentication response. In Baseline IOTP this API function is called 3433 by the Merchant (or the Financial Institution). It is called only if 3434 the counter party has responded with an IOTP Authentication Response 3435 Component within the Authentication Response Block. Of course, the 3436 IOTP Application Core traces the need of such an response. 3438 Due to the authentication's statelessness, all parameters (algorithm, 3439 challenge and response) are submitted to the IOTP Payment Bridge. 3440 Authentication failure is reported by a Process State different from 3441 "CompletedOK". 3443 Input Parameters 3445 o Authentication Identifier 3446 o Wallet Identifier and/or Pass Phrase 3447 o Authentication Challenge Packaged Content - generated by 3448 previous "Inquire Authentication Challenge" API call 3449 o Algorithm Element 3450 o Authentication Response Packaged Content - copied from the 3451 Authentication Response Component 3453 XML definition: 3455 3457 3462 Output Parameters 3464 o Current Process (Authentication) State 3465 o Completion Code 3466 o Status Description and its language annotation 3468 XML definition: 3470 3471 3482 Tables 4 and 5 explain the attributes and elements; Table 3 3483 introduces the Error Codes. 3485 4.2 Brand Selection Related API Calls 3487 4.2.1 Find Payment Instrument 3489 This API function determines which instances of a Payment Brand, 3490 e.g., two Mondex cards, are present. The same physical card may even 3491 represent multiple payment instruments. 3493 The IOTP Application Core supplies possible payment brand and payment 3494 protocol to the IOTP Payment Bridge that has to be considered when 3495 the IOTP Payment Bridge searches for appropriate payment instruments. 3496 This set represents the (sub)set of payment alternatives being 3497 supported by the Merchant. If the IOTP Application Cote has multiple 3498 possible payment brand/protocol, it can call this function in turn. 3500 The Existing Payment Software responds with PayInstrument Elements 3501 with empty PayInstId attributes if it does not distinguish between 3502 different payment instruments for the particular payment 3503 alternatives. 3505 Note that the Payment API assumes that the values of the attributes 3506 BrandId, ProtocolId, ProtocolBrandId and the currency amount suffice 3507 for the determination of the appropriate Packaged Content Element 3508 that will be transmitted to the Payment Handler later on. 3510 Input Parameters 3512 o Brand Identifier - copied from the Brand List Component's Brand 3513 Element 3514 o Payment Protocol Identifier and associated Protocol Brand 3515 Identifier 3516 o Payment Direction - copied from the Brand List Component 3517 o Currency Code and Currency - copied from the Currency Amount 3518 Element 3519 o Payment Amount - copied from the Currency Amount Element 3520 o Consumer Payment Identifier - Consumer's unique reference to 3521 the current payment transaction 3522 o Wallet Identifier - managed by the IOTP Application Core 3523 o (Brand) Packaged Content - further payment brand description; 3524 copied from the Brand List Component's Brand Element 3525 o (Protocol Brand) Element - further information; copied from the 3526 Protocol Brand Element of the Brand List Component which 3527 relates to the Consumer selected Brand Element, if any. 3529 o (Protocol Amount) Packaged Content - further payment protocol 3530 description, copied from the Brand List Component's Protocol 3531 Amount Element 3532 o Element (Protocol) Packaged Content - further payment protocol 3533 description, copied from the Brand List Component's Pay 3534 Protocol Element 3536 XML definition: 3538 3542 3552 Output Parameters 3554 o The known Payment Instrument Identifiers, these are internal 3555 values 3556 o The user-defined names of the payment instrument and their 3557 language encoding 3559 The Existing Payment Software responds with an empty list of 3560 identifiers, either if it does not distinguish between different 3561 payment instruments or if there are no registered payment instruments 3562 available despite brand support for at least one (unspecified) 3563 payment protocol. In the latter case, the IOTP Payment Bridge has to 3564 request the registration of a suitable payment instrument at a 3565 subsequent step of the payment process. 3567 XML definition: 3569 3571 3572 3577 Tables 4 and 5 explain the attributes and elements; Table 3 3578 introduces the Error Codes. 3580 4.2.2 Check Payment Possibility 3582 This API function checks whether a payment (both debit and credit) 3583 can go ahead. It can be used, for example, to check 3585 o if there are sufficient funds available in a particular 3586 currency for an electronic cash payment brand, 3587 o whether there is sufficient value space left on the payment 3588 instrument for payment refund, 3589 o whether required system resources are available and properly 3590 configured, e.g., serial ports or baud rate, 3591 o whether environment requirements are fulfilled, e.g., chip card 3592 reader presence or Internet connection. 3594 If the payment method bases on external components, e.g., magnetic 3595 stripe or chip cards, and the check accesses the medium, the existing 3596 payment method should not mutually exclusive lock system resources, 3597 e.g., serial port or modem, that may also be required by other 3598 Existing Payment Software, e.g., multiple payment software components 3599 may share the same card reader. If this happens for API internal 3600 request processing, the function has to unlock these components prior 3601 to return. Otherwise, the payment may not proceed if the Consumer 3602 cancels immediately and decides to use another payment instrument. In 3603 this event the previous IOTP Payment Bridge is not notified about the 3604 change. 3606 This function call happens immediately after the Consumer's payment 3607 instrument selection. For example, if the payment instrument is a 3608 chip card, that is not inserted in the chip card reader, the Consumer 3609 may be prompted for its insertion. However, the Consumer should be 3610 able to hit some 'skip' button, if the payment check is part of the 3611 actual payment protocol, too. Finally, the IOTP Payment Bridge may 3612 provide only a subset of these capabilities or may even directly 3613 generate a successful response without any checks. 3615 Input Parameters 3617 o Brand Identifier - user selection 3618 o Payment Instrument Identifier - user selection 3619 o Currency Code and Currency Code Type - copied from the selected 3620 Currency Amount Element 3621 o Payment Amount - copied from the selected Currency Amount 3622 Element 3623 o Payment Direction - copied from the selected Trading Protocol 3624 Option Block 3625 o Protocol Identifier - copied from the selected Pay Protocol 3626 Element 3627 o Protocol Brand Identifier - copied from the selected Protocol 3628 Brand Element of the Brand List Component which relates to the 3629 selected Brand Element, if any 3631 o Consumer Payment Identifier - Consumer's unique reference to 3632 the current payment transaction 3633 o Wallet Identifier and/or Pass Phrase 3634 o (Brand) Packaged Content - copied from the selected Brand 3635 Element 3636 o (Protocol Amount) Packaged Content - copied from the selected 3637 Protocol Amount Element 3638 o (Protocol) Packaged Content - copied from the selected Pay 3639 Protocol Element 3640 o (Protocol Brand) Packaged Content - copied from the selected 3641 Protocol Brand Element of the Brand List Component which 3642 relates to the selected Brand Element, if any 3644 XML definition: 3646 3650 3662 Output Parameters 3664 o three Brand Selection Info Packaged Content elements - for 3665 insertion into the Brand Selection component 3666 o Brand - additional data about the payment brand 3667 o Protocol Amount - additional data about the payment protocol 3668 o Currency Amount - additional payment brand and currency 3669 specific data 3671 XML definition: 3673 3677 3679 Tables 4 and 5 explain the attributes and elements; Table 3 3680 introduces the Error Codes. 3682 4.3 Payment Transaction Related API calls 3684 These Payment API calls may be made either by the Consumer's or 3685 Payment Handler's IOTP Application Core. 3687 4.3.1 Start Payment Consumer 3689 This API function initiates the genuine payment transaction at the 3690 Consumer side. The IOTP Payment Bridge and the Existing Payment 3691 Software perform all necessary initialization and preparation for 3692 payment transaction processing. This includes the reservation of 3693 external periphery. E.g., 1) the Consumer's chip card reader needs to 3694 be protected against access from other software components, 2) the 3695 insertion of the chip card may be requested, 3) the Internet 3696 connection may be re-established, or 4) the Payment Handler may open 3697 a mutual exclusive session to the security hardware. 3699 The IOTP Payment Bridge monitors the payment progress and stores the 3700 current payment states such that resumption - even after power 3701 failures - remains possible. Note that the IOTP Application Core 3702 supplies only a subset of the following input parameter to the 3703 associated resumption API function and refers to the payment 3704 transaction through the party's payment identifier. 3706 Input Parameters 3708 o Brand Identifier - copied from the selected Brand Element 3709 o Payment Instrument Identifier - the user selection 3710 o Currency Code and Currency - copied from the selected Currency 3711 Amount Element 3712 o Payment Amount - copied from the selected Currency Amount 3713 Element 3714 o Payment Direction - copied from the Brand List Component 3715 o Protocol Identifier - copied from the selected Payment Protocol 3716 Element 3717 o Protocol Brand Element - further information; copied from the 3718 Protocol Brand Element of the Brand List Component which 3719 relates to the selected Brand Element, if any 3720 o OkFrom, OkTo - copied from the Payment Component 3721 o Consumer Payment Identifier - Consumer's unique reference to 3722 the current payment transaction 3723 o Wallet Identifier and/or Pass Phrase 3724 o Call Back Function - used for end user notification/logging 3725 purposes 3726 o Call Back Language List. This list is required if the Call Back 3727 Function is set 3728 o (Brand) Packaged Content - further payment brand description; 3729 copied from the selected Brand Element's content 3731 o (Protocol Amount) Packaged Content - further payment protocol 3732 description; copied from the selected Protocol Amount Element's 3733 content 3734 o (Payment Protocol) Packaged Content - further payment protocol 3735 description; copied from the selected Pay Protocol Element's 3736 content 3737 o (Order) Packaged Content - further order description, copied 3738 from the Order Component 3740 XML definition: 3742 3747 3764 Output Parameters 3766 o Continuation Status 3767 o (Payment Scheme) Packaged Content - for insertion into the 3768 Payment Scheme Component of the IOTP Payment Request Block 3770 The IOTP Application Core is allowed to reissue this request several 3771 times on failed analyses of the response. 3773 XML definition: 3775 3777 3780 Tables 4 and 5 explain the attributes and elements; Table 3 3781 introduces the Error Codes. 3783 4.3.2 Start Payment Payment Handler 3785 This API function initializes the Consumer initiated payment 3786 transaction at the Payment Handler's side. Similar to the Consumer's 3787 system, the IOTP Payment Bridge and the Existing Payment Software 3788 perform all necessary initialization and preparation for payment 3789 transaction processing. 3791 Input Parameters 3793 o Brand Identifier - copied from the Consumer selected Brand 3794 Element 3795 o Consumer Payment Identifier - copied from the Payment Scheme 3796 Component 3797 o Currency Code and Currency - copied from the Consumer selected 3798 Currency Amount Element 3799 o Payment Amount - copied from the Consumer selected Currency 3800 Amount Element 3801 o Payment Direction - copied from the Brand List Component 3802 o Protocol Identifier - copied from the Consumer selected 3803 Payment Protocol Element 3804 o Protocol Brand Identifier - copied from the Brand Protocol 3805 Element of the Brand List Component which relates to the 3806 Consumer selected Brand Element, if any 3807 o OkFrom, OkTo - copied from the Payment Component 3808 o Payment Handler Payment Identifier - Payment Handler's unique 3809 reference to the current payment transaction 3810 o Merchant Organisation Identifier - copied from the Merchant's 3811 Organisation Element 3812 o Wallet Identifier - renaming to till identifier neglected - 3813 and/or Pass Phrase 3814 o Call Back Function - used for end user notification/logging 3815 purposes 3816 o Call Back Language List. This list is required if the call back 3817 function is set 3818 o (Brand) Packaged Content - further payment brand description; 3819 copied from the Consumer selected Brand Element's content 3820 o (Protocol Brand) Packaged Content - further information; copied 3821 from the Protocol Brand Element of the Brand List Component 3822 which relates to the Consumer selected Brand Element, if any. 3823 o (Protocol Amount) Packaged Content - further payment protocol 3824 description; copied from the Consumer selected Protocol Amount 3825 Element's content 3826 o (Protocol) Packaged Content - further payment protocol 3827 description; copied from the Consumer selected Pay Protocol 3828 Element's content 3829 o (TradingRoleData) Packaged Content - further payment protocol 3830 description; the Name Attribute of the packaged contents must 3831 include "Payment:" as the prefix, for example "Payment:SET-OD". 3832 o Three Brand Selection Info Packaged Content Elements - copied 3833 from the Brand Selection Component 3834 o Brand - additional data about the payment brand 3835 o Protocol Amount - additional data about the payment protocol 3836 o Currency Amount - additional payment brand and currency 3837 specific data 3838 o (Payment Scheme) Packaged Content. 3840 XML definition: 3842 3851 3868 Output Parameters 3870 o Continuation Status 3871 o (Payment Scheme) Packaged Content - for insertion into the 3872 Payment Scheme Component of the IOTP Payment Exchange Block 3874 The response message must contain payment schema data if the 3875 continuation status signals "Continue". The IOTP Application Core is 3876 allowed to reissue this request several times on failed analyses of 3877 the response. 3879 XML definition: 3881 3883 3886 Tables 4 and 5 explain the attributes and elements; Table 3 3887 introduces the Error Codes. 3889 4.3.3 Resume Payment Consumer 3891 This API function resumes a previously suspended payment at the 3892 Consumer side. Resumption includes the internal inquiry of the 3893 payment transaction data, e.g., payment amount, protocol identifier, 3894 and the whole initialization as it has been applied on the "Start 3895 Payment Consumer" API request. 3897 It is up to the IOTP Application Core to decide whether an IOTP 3898 Payment equest Block or a IOTP Payment Exchange Block needs to be 3899 generated. One indicator might be the receipt of a previous IOTP 3900 Payment Exchange Block from the Payment Handler, e.g., the knowledge 3901 of the Payment Handler Payment Identifier. 3903 Input Parameters 3905 o Consumer Payment Identifier 3906 o Wallet Identifier and/or Pass Phrase 3907 o Call Back Function - used for end user notification/logging 3908 purposes 3910 XML definition: 3912 3913 3920 Output Parameters 3922 o Continuation Status 3923 o (Payment Scheme) Packaged Content - for insertion in the 3924 Payment Scheme Component of the next IOTP message (Payment 3925 Exchange or Request Block). 3927 The IOTP Application Core is allowed to reissue this request several 3928 times on failed analyses of the response. However, the IOTP Payment 3929 Bridge might reject the resumption request by using the "AttNotSupp" 3930 Error Code "naming" the Consumer Payment Identifier attribute. Then 3931 the Consumer has to apply normal error processing to the current 3932 (sub-)transaction and to issue a new Payment Request Block to the 3933 Payment Handler. 3935 XML definition: 3937 3939 3942 Tables 4 and 5 explain the attributes and elements; Table 3 3943 introduces the Error Codes. 3945 4.3.4 Resume Payment Payment Handler 3947 This API function resumes a payment at the Payment Handler side. 3949 Input Parameters 3951 o Payment Handler Payment Identifier 3952 o Wallet Identifier - renaming to till identifier neglected - and 3953 Pass Phrase 3954 o Call Back Function - used for end user notification/logging 3955 purposes 3956 o Call Back Language List. This list is required if the Call Back 3957 Function is set 3958 o (Payment Scheme) Packaged Content - copied from the Payment 3959 Scheme Component of the received IOTP message (Payment Exchange 3960 or Request Block). 3962 XML definition: 3964 3966 3973 Output Parameters 3974 o Continuation Status 3975 o (Payment Scheme) Packaged Content - for insertion in the 3976 Payment Scheme Component of the next Payment Exchange Block. 3978 The response message contains payment schema specific data if the 3979 continuation status signals "Continue". The IOTP Application Core is 3980 allowed to reissue this request several times on failed analyses of 3981 the response. 3983 XML definition: 3985 3987 3990 Tables 4 and 5 explain the attributes and elements; Table 3 3991 introduces the Error Codes. 3993 4.3.5 Continue Process 3995 This API function passes one specific IOTP Payment Scheme Component, 3996 i.e., the encapsulated Packaged Content elements, received from the 3997 counter party (e.g. Consumer) to the IOTP Payment Bridge and responds 3998 with the next IOTP Payment Scheme Component for submission to the 3999 counter party. 4001 Input Parameters 4003 o Payty's Payment Idetifier 4004 o Process (Transaction) Type which distinguishes between Payments 4005 and Inquiries. 4006 o Wallet Identifier and/or Pass Phrase 4007 o (Payment Scheme) Packaged Content - copied from the Payment 4008 Scheme Component of the received Payment Exchange Block or from 4009 the Error Block. 4011 Each party should set the payment identifier with the local 4012 identifier (Consumer: ConsumerPayId; Merchant: MerchantPayId; Payment 4013 Handler: PaymentHandlerPayId). 4015 XML definition: 4017 4018 4024 Output Parameters 4026 o Continuation Status 4027 o (Payment Scheme) Packaged Content - for insertion in the 4028 Payment Scheme Component of the next Payment Exchange Block or 4029 final Payment Response Block 4031 The response message contains payment schema data if the continuation 4032 status signals "Continue". The IOTP Payment Bridge must signal "End", 4033 if the payment scheme data was received within an IOTP Error Block 4034 containing an Error Component with severity HardError. 4036 XML definition: 4038 4039 4042 Tables 4 and 5 explain the attributes and elements; Table 3 4043 introduces the Error Codes. 4045 4.3.6 Change Process State 4047 The IOTP Application Core changes the current payment status by this 4048 request. The IOTP Payment Bridge may be notified about business level 4049 normal termination, cancellation, suspension, and processing errors. 4050 Notification happens by requesting the intended process state. 4052 The IOTP Payment Bridge processes the status change and reports the 4053 result. 4055 The IOTP Application Core has to analyze any returned process status 4056 in order to check whether the IOTP Payment Bridge has agreed to or 4057 declined the status switch. E.g., the submitted Process State 4058 "CompleteOk" may lead to the Payment Status "Failed" if the payment 4059 transaction has already failed. 4061 Transaction Suspension is notified by the newly introduced Process 4062 State "Suspended". The other attribute values have been taken from 4063 the IOTP specification. 4065 This API function might be called by the Consumer, Merchant, or 4066 Payment Handler for each payment transaction anytime after the 4067 issuance of "FindPaymentInstrument" to the IOTP Payment Bridge by the 4068 Consumer, the issuance of "FindAcceptedPaymentBrand" by the Merchant, 4069 or the issuance of "StartPaymentPaymentHandler" by the Payment 4070 Handler. 4072 The Process States "CompletedOk", "Failed", and "ProcessError" are 4073 final in the sense that they can not be changed on subsequent calls. 4074 However, the API function should not return with an error code if 4075 such an incompatible call has been issued. Instead it should report 4076 the old unchanged Process State. 4078 Unknown payment transactions are reported by the Error Code 4079 "AttValInvalid" pointing to the PayId attribute. 4081 Input Parameters 4083 o Party's Payment Identifier 4084 o intended Payment Status 4085 o intended Completion Code 4086 o Process (Transaction) Type which distinguishes between Payments 4087 and Inquiries. 4088 o Wallet Identifier and/or Pass Phrase 4090 XML definition: 4092 4093 4106 Output Parameters 4108 o Process State and Percent Complete 4109 o Completion Code 4110 o Status Description and its language annotation 4112 XML definition: 4114 4115 4127 Tables 4 and 5 explain the attributes and elements; Table 3 4128 introduces the Error Codes. 4130 4.4 General Inquiry API Calls 4132 The following calls are not necessarily assigned to a payment 4133 transaction and may be issued at any time. There are no dependencies 4134 on any other calls. 4136 4.4.1 Remove Payment Log 4138 The IOTP Application Core notifies the IOTP Payment Bridge resp. the 4139 Existing Payment Software that any record in the Payment Log file, 4140 that deals with the listed payment transaction, might be removed. 4142 Input Parameters 4144 o Party's Payment Identifier 4145 o Wallet Identifier and/or Pass Phrase 4147 XML definition: 4149 4150 4155 Output Parameters 4157 XML definition: 4159 4160 4162 Tables 4 and 5 explain the attributes and elements; Table 3 4163 introduces the Error Codes. 4165 4.4.2 Payment Instrument Inquiry 4167 This API function retrieves the properties of the Payment Instrument. 4168 The Payment Instrument Identifier could be omitted if this identifier 4169 is derived by other means, e.g., by analysis of the currently 4170 inserted chip card. If the Payment instrument could not uniquely 4171 determined, the IOTP Payment Bridge may provide suitable dialogs for 4172 user input. 4174 E.g., this API function might be used during problem resolution with 4175 the Customer Care Provider of the issuer of the payment instrument, 4176 in order to inquire payment instrument specific values. 4178 Input parameters 4180 o Brand Identifier 4181 o Payment Instrument Identifier 4182 o Protocol Identifier 4183 o Wallet Identifier and/or Pass Phrase 4184 o Property Type List - sequence of values whose language is 4185 identified by xml:lang 4186 o (Brand) PackagedContent Content - further payment brand 4187 description 4188 o Protocol Brand Content - further payment brand information 4189 o (Protocol Amount) PackagedContent Content - further payment 4190 protocol description 4191 o (Pay Protocol) PackagedContent Content - further payment 4192 protocol description 4194 The codes in the property type list are of two types: 4196 o generic codes which apply to all payment methods but might be 4197 unavailable 4198 o Payment Brand specific codes. 4200 Generic codes for the Property Type List are: 4202 Property Type Meaning 4203 Balance Current balance 4204 Limit Maximum balance 4205 PaymentLimit Maximum payment transaction limit 4206 Expiration Expiration date 4207 Identifier Issuer assigned identifier of the payment 4208 instrument. Usually, it does not match with 4209 the API's payment instrument identifier. 4210 LogEntries Number of stored payment transaction 4211 entries. The entries are numbered from 0 4212 (the most recent) to some non-negative 4213 value for the oldest entry. 4214 PayAmountn Payment Amount of the n-th recorded payment 4215 transaction, n may negative 4216 PayPartyn Remote party of the n-th payment recorded 4217 transaction, n may negative 4218 PayTimen Time of the n-th payment recorded 4219 transaction, n may negative 4221 XML definition: 4223 4227 4236 Output parameters 4238 o a list of zero or more unavailable property values whose 4239 language are identified by xml:lang. 4240 o a list of zero or more sets of "Properties Types", "Property 4241 Values" and "Property Descriptions" 4243 XML definition: 4245 4247 4251 4252 4257 Tables 4 and 5 explain the attributes and elements; Table 3 4258 introduces the Error Codes. 4260 4.4.3 Inquire Pending Payment 4262 This API function reports the party's payment identifiers of any 4263 pending payment transactions that the IOTP Payment Bridge/Existing 4264 Payment Software recommends to complete or suspend prior to the 4265 processing of new payment transactions. It does not respond further 4266 transaction details. These have to be inquired by "Inquire Process 4267 State". 4269 Note that the IOTP Payment Bridge has to respond without the 4270 supplement of any pass phrase if there exist no pending payment 4271 transaction. But if there are some pending payment transactions, the 4272 IOTP Payment Bridge may refuse the immediate response and may instead 4273 request the appropriate pass phase from the IOTP Application Core. 4275 Input Parameters 4277 o Wallet Identifier and/or PassPhrase 4279 XML definition: 4281 4282 4286 Output Parameters 4288 o Party's Payment Identifier 4290 XML definition: 4292 4294 4295 4298 Tables 4 and 5 explain the attributes and elements; Table 3 4299 introduces the Error Codes. 4301 4.5 Payment Related Inquiry API Calls 4302 4.5.1 Check Payment Receipt 4304 This function is used by the Consumer and might be used by the 4305 Payment Handler to check the consistency, validity, and integrity of 4306 IOTP payment receipts whereby any receipt might consist of Packaged 4307 Content Elements 4309 o from the IOTP Payment Receipt Component - provided by the 4310 Payment Handler's "Inquire Process State" API call shortly 4311 before payment completion, 4313 o from Payment Scheme Components being exchanged during the 4314 actual payment, or 4316 o being returned by the Consumer's "Inquire Process State" API 4317 call shortly before payment completion 4319 The IOTP Application Core has to check the PayReceiptNameRefs 4320 attribute of the IOTP Payment Receipt Component and to supply exactly 4321 the Packaged Content Elements being referred to. 4323 Failed verification is returned with a business error. 4325 Note that this Payment API assumes that any payment receipt builds 4326 upon a subset of elements w.r.t. [IOTP]. Furthermore, the Packaged 4327 Content Element have to be distinguishable by their Name attribute. 4329 Input Parameters 4331 o Party's Payment Identifier 4332 o Wallet Identifier and/or Pass Phrase 4333 o All Packaged Content Elements that build the payment receipt 4335 XML definition: 4337 4338 4343 Output Parameters 4345 XML definition: 4347 4348 4350 Tables 4 and 5 explain the attributes and elements; Table 3 4351 introduces the Error Codes. 4353 4.5.2 Expand Payment Receipt 4355 This API function expands any IOTP payment receipt into a form which 4356 may be used for display or printing purposes. "Check Payment Receipt" 4357 should be used first if there is any question of the payment receipt 4358 containing errors. 4360 There apply the same conventions to the input parameter as for "Check 4361 Payment Receipt" (cf. Section 4.5.1). 4363 Input Parameters 4365 o Party's Payment Identifier 4366 o Wallet Identifier and/or Pass Phrase 4367 o All Packaged Content Elements that build the payment receipt 4369 XML definition: 4371 4372 4377 Output Parameters 4379 o Brand Identifier 4380 o Protocol specific Brand Identifier 4381 o Payment Instrument Identifier 4382 o Currency Code and Currency Code Type 4383 o Payment Amount 4384 o Payment Direction 4385 o Time Stamp - issuance of the receipt 4386 o Protocol Identifier 4387 o Protocol specific Transaction Identifier - this is an internal 4388 reference number which identifies the payment 4389 o Consumer Description, Payment Handler Description, and a 4390 language annotation 4391 o Style Sheet Net Location 4392 o Payment Property List. A list of type/value/description triples 4393 which contains additional information about the payment which 4394 is not covered by any of the other output parameters; property 4395 descriptions have to consider the language annotation. 4397 The Style Sheet Net Location refers to a Style Sheet (e.g. [XSLT]) 4398 that contains visualization information about the reported XML 4399 encoded data. 4401 XML definition: 4403 4404 4420 4421 4426 The Existing Payment Software should return as many attributes as 4427 possible from the supplied IOTP Payment Receipt. The payment 4428 supplement define that attribute value for the payment properties. 4430 Tables 4 and 5 explain the attributes and elements; Table 3 4431 introduces the Error Codes. 4433 4.5.3 Inquire Process State 4435 This API function returns the current payment state and optionally 4436 further Packaged Content Elements that form the payment receipt. 4437 Called by the Payment Handler, the IOTP Payment Bridge might respond 4438 with data intended for inclusion in the IOTP Payment Receipt 4439 Component's Packaged Content. When the Consumer calls this function 4440 shortly before payment completion, it may respond with further items 4441 of the payment receipt. Such items might be created by a chip card. 4443 Input Parameters 4445 o Party's Payment Identifier 4446 o Wallet Identifier and/or Pass Phrase 4447 XML definition: 4449 4450 4455 Output Parameters 4457 o Current Process State and Percent Complete 4458 o Completion Code 4459 o Status Description and its language annotation 4460 o Payment Receipt Name References to all Packaged Content 4461 Elements that build the payment receipt (cf. Section 4.5.1), 4462 even if they have not been created so far (Consumer's share) 4463 o Any Packaged Content Element being available that form the 4464 payment receipt 4466 The IOTP provides a linking capability to the payment receipt 4467 delivery. Instead of encapsulating the whole payment specific data 4468 into the packaged content of the payment receipt, other Payment 4469 Scheme Components' Packaged Content might be referred to. 4471 XML definition: 4473 4475 4488 Tables 4 and 5 explain the attributes and elements; Table 3 4489 introduces the Error Codes. 4491 4.5.4 Start Payment Inquiry 4493 This API function responds any additional payment scheme specific 4494 data that is needed by the Payment Handler for Consumer initiated 4495 payment transaction inquiry processing. Probably, the IOTP Payment 4496 Bridge resp. Existing Payment Software has to determine the payment 4497 related items that were provided with the "Start Payment Consumer" 4498 API function call. 4500 Input Parameters 4502 o Consumer Payment Identifier 4503 o Wallet Identifier and/or Pass Phrase 4505 XML definition: 4507 4508 4513 Output Parameters 4515 o (Payment Scheme) Packaged Content - intended for insertion in 4516 the Payment Scheme Component of the Inquiry Request Block 4518 XML definition: 4520 4523 Tables 4 and 5 explain the attributes and elements; Table 3 4524 introduces the Error Codes. 4526 4.5.5 Inquire Payment Status 4528 The Payment Handler calls this API function for Consumer initiated 4529 inquiry processing. It differs from the previous "Inquire Process 4530 State" API function by the optional supplement of payment scheme 4531 specific data. The response may encapsulate further details about the 4532 payment transaction. 4534 Input Parameters 4536 o Payment Handler Payment Identifier 4537 o Wallet Identifier and/or Pass Phrase 4538 o (Payment Scheme) Packaged Content - copied from the Inquiry 4539 Request Block's Payment Scheme Component 4541 XML definition: 4543 4544 4549 Output Parameters 4551 o Current Process State 4552 o Completion Code 4553 o Status Description and its language annotation 4554 o (Payment Scheme) Packaged Content - intended for insertion in 4555 the Payment Scheme Component of the Inquiry Response Block 4557 XML definition: 4559 4561 4573 Tables 4 and 5 explain the attributes and elements; Table 3 4574 introduces the Error Codes. 4576 4.6 Other API Calls 4578 4.6.1 Manage Payment Software 4580 The following API function notifies the IOTP Payment Bridge about the 4581 intended registration, modification, or deletion of a payment 4582 instrument. The actual processing is up to the IOTP Payment Bridge. 4584 This API request may also be used to activate the IOTP Payment Bridge 4585 resp. Existing Payment Software for general administration purposes. 4587 Input Parameters 4589 o Brand Identifier 4590 o Protocol Identifier 4591 o Any action code: 4592 o New - add new payment method / instrument 4593 o Update - change the payment method's / instrument's data 4594 o Delete - delete a payment method / instrument 4595 o Wallet Identifier and/or Pass Phrase 4596 o (Brand) Packaged Content - further payment brand description 4597 o (Pay Protocol) Packaged Content - further payment protocol 4598 description 4599 o (Protocol Amount) Packaged Content - further payment protocol 4600 description 4602 If the Action attribute is set, the Brand and Protocol Identifier 4603 have to be set, too. The IOTP Payment Bridge has to provide the 4604 required user dialogs and selection mechanisms. E.g., updates and 4605 deletions may require the selection of the payment instrument. A new 4606 wallet might be silently generated on the supplement of a new Wallet 4607 Identifier or after an additional end user acknowledge. The IOTP 4608 Application Core should not provide any pass phrases for new wallets. 4609 Instead, the IOTP Payment Bridge has to request and verify them which 4610 may return their value to the IOTP Application Core in plain text. In 4611 addition, the IOTP Payment Bridge returns the supported 4612 authentication algorithms when a new brand and protocol pair has been 4613 registered. 4615 If the "Action" attribute is omitted, the IOTP Payment Bridge resp. 4616 Existing Payment Software pops up in a general interactive mode. 4618 XML definition: 4620 4623 4632 Output Parameters 4634 o An action code: 4636 o New - added new wallet 4637 o Update - changed wallet's configuration 4638 o Delete - removed a wallet 4639 o Wallet Identifier and/or Pass Phrase 4641 The IOTP Payment Bridge does not return any information about the set 4642 of registered payment instruments because these data items are 4643 dynamically inferred during the brand selection process at the 4644 beginning of each IOTP transaction. However, the IOTP Application 4645 Core has to be notified about new wallets and should be notified 4646 about updated and removed wallet (identifier)s". Alternatively, 4647 removed wallets can be implicitly detected during the next brand 4648 selection phase. Updated wallets do no affect the processing of the 4649 IOTP Application Core. The IOTP Payment Software resp. Existing 4650 Payment Software should only support the addition of at most one 4651 wallet because it is not able to report multiple additions at once 4652 back to the IOTP Application Core. 4654 XML definition: 4656 4657 4665 Tables 4 and 5 explain the attributes and elements; Table 3 4666 introduces the Error Codes. 4668 5. Call Back Function 4670 This API function, called by the IOTP Payment Bridge, is used to 4671 provide information for Consumer or Payment Handler notification 4672 about the progress of the payment transaction. 4674 Its use is illustrated in the diagram below. 4676 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 4677 IOTP Application ----calls---- 4678 | Core | | 4679 display | | v 4680 to <---------- Call Back <--calls--- Payment 4681 user | | Software 4682 ---------------- 4683 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 4684 Figure 9 Call Back Function 4686 Whenever this function is called, the content of the status 4687 description should be made available to the user. For example on a 4688 status bar, a pop up window, etc. 4690 A reference to the Call Back function is passed as an input parameter 4691 to the "Start Payment X" and "Resume Payment X" API function. 4692 Afterwards, this function might be called whenever the status changes 4693 or progress needs to be reported. 4695 Input Parameters 4697 o the software identifier of the caller 4698 o Party's Payment Identifier 4699 o Process State and Percent Complete 4700 o Completion Code 4701 o Status Description and its language annotation, text which 4702 provides information about the progress of the call. It should 4703 be displayed or made available to, for example, the Consumer. 4705 Examples of Status Description could be: 4707 o "Paying 12.30 USD to XYZ Inc" 4708 o "Payment completed" 4709 o "Payment aborted" 4711 The valid languages are announced in the Call Back Language List 4712 attribute in "Start Payment X" and "Resume Payment X" API function 4713 calls. 4715 XML definition: 4717 4718 4732 Output Parameters 4733 XML definition: 4735 4736 > 4738 Tables 4 and 5 explain the attributes and elements; Table 3 4739 introduces the Error Codes. 4741 Basically, the call back function accepts all input arguments or 4742 rejects the whole request. It may even accept malformed requests. 4744 Some payment schemes may support or require that the Consumer might 4745 be able to cancel the payment at any time. The Call Back function can 4746 be used to facilitate this by returning the cancellation request on 4747 the next call (using the Business Error Code and Completion Code 4748 "ConsCancelled"). 4750 Vice versa the Payment Handler's Application Core might use the 4751 similar mechanism to signal its IOTP Payment Bridges any exceptional 4752 need for a fast shutdown. These IOTP Payment Bridges may initiate the 4753 appropriate steps for terminating/canceling all pending payment 4754 transactions. 4756 Note that the "Change Process State" API function provides the second 4757 mechanism for such kind of notification. Therefore, the IOTP Payment 4758 Bridge or Existing Payment Software may ignore the details of the 4759 "Call Back" response. 4761 6. Security Consideration 4763 [T.B.D.] 4765 See also security consideration section of [IOTP]. 4767 Full Copyright Statement 4769 Copyright (C) The Internet Society 2000. 4771 This document and translations of it may be copied and furnished to 4772 others, and derivative works that comment on or otherwise explain it 4773 or assist in its implementation may be prepared, copied, published 4774 and distributed, in whole or in part, without restriction of any 4775 kind, provided that the above copyright notice and this paragraph are 4776 included on all such copies and derivative works. However, this 4777 document itself may not be modified in any way, such as by removing 4778 the copyright notice or references to the Internet Society or other 4779 Internet organizations, except as needed for the purpose of 4780 developing Internet standards in which case the procedures for 4781 copyrights defined in the Internet Standards process must be 4782 followed, or as required to translate it into languages other than 4783 English. 4785 The limited permissions granted above are perpetual and will not be 4786 revoked by the Internet Society or its successors or assigns. 4788 This document and the information contained herein is provided on an 4789 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4790 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4791 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4792 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4793 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4795 References 4797 [IOTP] - Internet Open Trading Protocol Specification, Version 1.0, 4798 April 2000, See RFC2801. 4800 [IOTPBOOK] - D. Burdett, D.E. Eastlake III, and M. Goncalves, 4801 Internet Open Trading Protocol, McGraw-Hill, 2000 4803 [HTML] - Hyper Text Mark Up Language. The Hypertext Markup Language 4804 (HTML) is a simple markup language used to create hypertext documents 4805 that are platform independent. See RFC 1866 and the World Wide Web 4806 (W3C) consortium web site at: http://www.w3.org/MarkUp/ 4808 [HTTP] - Hyper Text Transfer Protocol versions 1.0 and 1.1. See RFC 4809 1945: Hypertext Transfer Protocol - HTTP/1.0. T. Berners-Lee, R. 4810 Fielding & H. Frystyk. May 1996. and RFC 2068: Hypertext Transfer 4811 Protocol - HTTP/1.1. R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. 4812 Berners-Lee. January 1997. 4814 [ISO4217] - ISO 4217: Codes for the Representation of Currencies. 4816 Available from ANSI or ISO. 4818 [MIME] - Multipurpose Internet Mail Extensions. See RFC822, RFC2045, 4819 RFC2046, RFC2047, RFC2048 and RFC2049. 4821 [URL] - Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform 4822 Resource Locators (URL)", RFC 1738, December 1994. 4824 [SET] - SET Secure Electronic Transaction(TM) , Version 1.0, May 31, 4825 1997 4826 Book 1: Business Description 4827 Book 2: Programmer's Guide 4828 Book 3: Formal Protocol Definition 4829 Download from: . 4831 [SET/IOTP] - Yoshiaki Kawatsura "SET Supplement for IOTP" (currently 4832 draft-ietf-trade-iotp-v1.0-set-01.txt) 4834 [UTC] - Universal Time Coordinated. A method of defining time 4835 absolutely relative to Greenwich Mean Time (GMT). Typically of the 4836 form: "CCYY-MM- DDTHH:MM:SS.sssZ+n" where the "+n" defines the number 4837 of hours from GMT. See ISO DIS8601. 4839 [XML] - Extensible Mark Up Language. A W3C recommendation. See 4840 http://www.w3.org/TR/1998/REC-xml-19980210 4842 [XSLT] - Extensible Style Language Transformations 1.0, November 4843 1999, See http://www.w3.org/TR/xslt 4845 [XML-NS] - Namespaces in XML Recommendation. T. Bray, D. Hollander, 4846 A. Layman. Janaury 1999. http://www.w3.org/TR/1999/REC-xml-names- 4847 19990114 4849 Author's Address 4851 Hans-Bernhard Beykirch and Werner Hans 4852 IT Development & Coordination Center for the German Savings Banks 4853 Organization (SIZ) 4854 Konigswinterer Strase 553 4855 53227 Bonn 4856 Germany 4857 E-mail: Hans-Bernhard.Beykirch@siz.de, Werner.Hans@siz.de 4859 Masaaki Hiroya and Yoshiaki Kawatsura 4860 Hitachi, Ltd. 4861 890 Kashimada Saiwai-ku Kawasaki-shi 4862 Kanagawa, Japan 212-8567 4863 E-mail: hiroya@sdl.hitachi.co.jp, kawatura@bisd.hitachi.co.jp 4865 Expiration and File Name 4867 This draft expires March 2001. 4869 Its file name is draft-ietf-trade-iotp-v1.0-papi-01.txt.