idnits 2.17.1 draft-ietf-trade-iotp-v1.0-papi-05.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-05', 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 1715 has weird spacing: '...n error that ...' == Line 1753 has weird spacing: '...ding on the n...' == Line 1764 has weird spacing: '...Content cf. T...' == Line 2811 has weird spacing: '...ontents must ...' == Line 4550 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 (April 2001) is 8405 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 1335, but not defined == Missing Reference: 'PSn' is mentioned on line 1125, but not defined == Missing Reference: 'PS2' is mentioned on line 1336, but not defined == Missing Reference: 'TLS' is mentioned on line 2616, but not defined == Unused Reference: 'HTML' is defined on line 4835, but no explicit reference was found in the text == Unused Reference: 'HTTP' is defined on line 4840, but no explicit reference was found in the text == Unused Reference: 'IOTPBOOK' is defined on line 4849, but no explicit reference was found in the text == Unused Reference: 'ISO4217' is defined on line 4853, but no explicit reference was found in the text == Unused Reference: 'MIME' is defined on line 4856, but no explicit reference was found in the text == Unused Reference: 'SET' is defined on line 4859, but no explicit reference was found in the text == Unused Reference: 'UTC' is defined on line 4872, but no explicit reference was found in the text ** Obsolete normative reference: RFC 1866 (ref. 'HTML') (Obsoleted by RFC 2854) ** Obsolete normative reference: RFC 2068 (ref. 'HTTP') (Obsoleted by RFC 2616) ** Downref: Normative reference to an Informational RFC: RFC 2801 (ref. 'IOTP') -- Possible downref: Non-RFC (?) normative reference: ref. 'IOTPBOOK' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO4217' -- Possible downref: Non-RFC (?) normative reference: ref. 'SET' ** Obsolete normative reference: RFC 1738 (ref. 'URL') (Obsoleted by RFC 4248, RFC 4266) -- Possible downref: Non-RFC (?) normative reference: ref. 'UTC' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML-NS' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSLT' Summary: 11 errors (**), 0 flaws (~~), 19 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 Yoshiaki Kawatsura 5 Hitachi 6 Masaaki Hiroya 7 Technoinfo Service 8 Expires: October 2001 April 2001 10 Payment API for v1.0 Internet Open Trading Protocol (IOTP) 11 ------- --- --- ---- -------- ---- ------- -------- ------ 12 14 Status of this Memo 16 This document is intended to become an Informational RFC. 17 Distribution of this document is unlimited. Please send comments to 18 the TRADE working group at , which may 19 be joined by sending a message with subject "subscribe" to . Discussions of the TRADE working 21 group are archived at http://lists.elistx.com/archives/ietf-trade. 23 This document is an Internet-Draft and is in full conformance with 24 all provisions of Section 10 of RFC 2026. Internet-Drafts are 25 working documents of the Internet Engineering Task Force (IETF), its 26 areas, and its working groups. Note that other groups may also 27 distribute working documents as Internet-Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet- Drafts as reference 32 material or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 Copyright 42 Copyright (C) The Internet Society 2001. 44 Abstract 46 The Internet Open Trading Protocol provides a data exchange format 47 for trading purposes while integrating existing pure payment 48 protocols seamlessly. This motivates the multiple layered system 49 architecture which consists of at least some generic IOTP application 50 core and multiple specific payment modules. 52 This document addresses a common interface between the IOTP 53 application core and the payment modules, enabling the 54 interoperability between these kinds of modules. Furthermore, such an 55 interface provides the foundations for a plug-in- mechanism in actual 56 implementations of IOTP application cores. 58 Such interfaces exist at the Consumers', the Merchants' and the 59 Payment Handlers' installations connecting the IOTP application core 60 and the payment software components/legacy systems. 62 Intended Readership 64 Software and hardware developers, development analysts, and users of 65 payment protocols. 67 Table of Contents 69 Status of this Memo........................................1 70 Copyright..................................................1 72 Abstract...................................................2 73 Intended Readership........................................2 75 Table of Contents..........................................3 76 1. Introduction............................................5 77 1.1 General payment phases................................6 78 1.2 Assumptions...........................................8 79 2. Message Flow..........................................13 80 2.1 Authentication Documentation Exchange................16 81 2.2 Brand Compilation....................................18 82 2.3 Brand Selection......................................22 83 2.4 Successful Payment...................................25 84 2.5 Payment Inquiry......................................29 85 2.6 Abnormal Transaction Processing......................30 86 2.6.1 Failures and Cancellations.........................31 87 2.6.2 Resumption.........................................32 88 2.7 IOTP Wallet Initialization...........................33 89 2.8 Payment Software Management..........................34 90 3. Mutuality.............................................34 91 3.1 Error Codes..........................................38 92 3.2 Attributes and Elements..............................48 93 3.3 Process States........................................60 94 3.3.1 Merchant............................................60 95 3.3.2 Consumer............................................62 96 3.3.3 Payment Handler.....................................64 97 4. Payment API Calls.....................................65 98 4.1 Brand Compilation Related API Calls..................65 99 4.1.1 Find Accepted Payment Brand........................65 100 4.1.2 Find Accepted Payment Protocol.....................66 101 4.1.3 Get Payment Initialization Data....................68 102 4.1.4 Inquire Authentication Challenge...................71 103 4.1.5 Authenticate.......................................72 104 4.1.6 Check Authentication Response......................73 105 4.2 Brand Selection Related API Calls....................74 106 4.2.1 Find Payment Instrument............................74 107 4.2.2 Check Payment Possibility..........................76 108 4.3 Payment Transaction Related API calls................78 109 4.3.1 Start Payment Consumer.............................78 110 4.3.2 Start Payment Payment Handler......................80 111 4.3.3 Resume Payment Consumer............................82 112 4.3.4 Resume Payment Payment Handler.....................83 113 4.3.5 Continue Process...................................84 114 4.3.6 Change Process State...............................85 115 4.4 General Inquiry API Calls............................87 116 4.4.1 Remove Payment Log.................................87 117 4.4.2 Payment Instrument Inquiry.........................88 118 4.4.3 Inquire Pending Payment............................90 119 4.5 Payment Related Inquiry API Calls....................91 120 4.5.1 Check Payment Receipt..............................91 121 4.5.2 Expand Payment Receipt.............................92 122 4.5.3 Inquire Process State..............................93 123 4.5.4 Start Payment Inquiry..............................95 124 4.5.5 Inquire Payment Status.............................95 125 4.6 Other API Calls......................................96 126 4.6.1 Manage Payment Software............................97 127 5. Call Back Function.....................................98 128 6. Security Consideration................................100 130 Full Copyright Statement.................................101 131 References...............................................101 132 Author's Addresses.......................................102 133 Expiration and File Name.................................103 135 1. Introduction 137 Common network technologies are based on standardized and established 138 Internet technologies. The Internet technologies provide mechanisms 139 and tools for presentation, application development, network 140 infrastructure, security, and basic data exchange. 142 Due to the presence of already installed trading roles' systems with 143 their own interfaces (Internet shop, order management, payment, 144 billing, and delivery management systems, or financial institute's 145 legacy systems), IOTP has been limited to the common external 146 interface over the Internet. However, some of these internal 147 interfaces might be also standardized for better integration of IOTP 148 aware components with of the existing infrastructure and its cost 149 effective reuse. 151 The typical Payment Handlers (i.e., financial institutes or near- 152 bank organizations) as well as Merchants require an IOTP aware 153 application that easily fits into their existing financial 154 infrastructure. The Payment Handler might even insist on the reuse of 155 special in-house solutions for some subtasks of the IOTP aware 156 application, e.g., reflecting their cryptography modules, gateway 157 interfaces, or physical environment. Therefore, their IOTP aware 158 implementation really requires such clear internal interfaces. 160 More important, Consumers demand modularization and clear internal 161 interfaces: Their IOTP application aims at the support of multiple 162 payment methods. Consumers prefer the flexible use of different 163 seamless integrating payment methods within one trading application 164 with nearly identical behavior and user interface. The existence of a 165 well-defined interface enables payment software developers to bolt on 166 their components to other developer's general IOTP Application Core. 168 Initially, this consideration leads to the two-level layered view of 169 the IOTP software for each role, consisting of 171 o some generic IOTP system component, the so-called IOTP application 172 core - providing IOTP based gateway services and generic business 173 logic and 175 o the trading roles' specific back-end systems implementing the 176 specific trading transaction types' functionality. 178 In order to isolate the changes on the infrastructure, the IOTP 179 trading application has been three-layered: 181 o the IOTP Application Core processes the generic parts of the IOTP 182 transaction and holds the connection to the Internet, 184 o the Existing Legacy System or Existing Payment Software which 185 processes the actual transaction type, and particular payment 186 transaction, and 188 o the IOTP Middle-ware or IOTP Payment Bridge which glues the other 189 two possibly incompatible components. It brokers between the 190 specific interface of the Existing Legacy System and the 191 standardized interfaces of the IOTP Application Core. 193 As IOTP extends payment schemes to a trading scheme, primarily, this 194 document focuses on payment modules, i.e. the interface between the 195 IOTP Payment Bridge and the IOTP Application Core. It provides a 196 standard method for exchanging payment protocol messages between the 197 parties involved in a payment. But, it does not specify any interface 198 for order or delivery processing. 200 Such a Payment Application Programmers Interface (API) must suit for 201 a broad range of payment methods: (1) software based like Credit Card 202 SET or CyberCoin, (2) chip card based like Mondex or GeldKarte, and 203 (3) mimicries of typical and traditional payment methods like money 204 transfer, direct debit, deposit, withdrawal, money exchange and value 205 points. It should support both payments with explicit consumer 206 acknowledge and automatic repeated payments, which have been consumer 207 approved in advance. 209 The following discussion focuses on the Consumer's point of view and 210 uses the associated terminology. When switching to Merchants' or 211 Delivery Handlers' IOTP aware applications, the payment related 212 components should be implicitly renamed by Existing Legacy Systems to 213 the IOTP Middle-ware. 215 The next two sub-sections describe the general payment scenario and 216 several assumptions about the coarsely sketched software components. 218 Chapter 2 illustrates the payment transaction progress and message 219 flow of different kinds of transaction behavior. Chapters 3 to 4 220 provide the details of the API functions and Chapter 5 elaborates the 221 call back interface. 223 1.1 General payment phases 225 The following table sketches the four logical steps of many payment 226 schemes. The preceding agreements about the goods, payment method, 227 purchase amount, or delivery rules are omitted. 229 Payment State Party Example Behavior 230 ------------- ----- ---------------- 232 Mutual Payment Handler Generation of identification 233 Authentication request, solvency request, or 234 and Init- some nonce 235 ialization Consumer Responses to the requests and 236 generation of own nonce 238 Authorization Payment Handler Generation of the authorization 239 request (for consumer) 240 Consumer Agreement to payment (by 241 reservation of the Consumer's 242 e-money) 243 Payment Handler Acceptance or rejection of the 244 agreement (consumer's 245 authorization response), 246 generation of the authorization 247 request (for issuer/acquirer), 248 and processing of its response 250 Capture Generation of the capture 251 request (for issuer/acquirer) 252 Consumer Is charged 253 Payment Handler Acceptance or rejection of the 254 e-money, close of the payment 255 transaction 257 Reversal On rejection (online/delayed): 258 generation of the reversal data 259 Consumer Receipt of the refund 261 However, some payment schemes 263 o limit themselves to one-sided authentication, 264 o perform off-line authorization without any referral to any 265 issuer/acquirer, 266 o apply capture processing in batch mode, or 267 o do not distinguish between authorization and capture, 268 o lack an inbound mechanism for reversals or implement a limited 269 variant. 271 This model applies not only to payments at the typical points of 272 sales but extends to refunds, deposits, withdrawals, electronic 273 cheques, direct debits, and money transfers. 275 1.2 Assumptions 277 In outline, the IOTP Payment Bridge processes some input sequence of 278 payment protocol messages being forwarded by the IOTP Application 279 Core. It (1) disassembles the messages, (2) maps them onto the 280 formats of the Existing Payment Software, (3) assembles its 281 responses, and (4) returns another sequence of payment protocol 282 messages that is mostly intended for transparent transmission by the 283 IOTP Application Core to some IOTP aware remote party. Normally, this 284 process continues between the two parties until the Payment Handler's 285 Payment API signals the payment termination. Exceptionally, each 286 system component may signal failures. 288 The relationship between the aforementioned components is illustrated 289 in the following figure. These components might be related to each 290 other in a flexible n-to-m-manner: 292 o One IOTP Application Core may manage multiple IOTP Payment 293 Bridges and the latter might be shared between multiple IOTP 294 Application Cores. 295 o Each Payment Bridge may manage multiple Existing Payment 296 Software modules and the latter might be shared between multiple 297 Payment Bridges. 298 o Each Existing Payment Software may manage multiple payment 299 schemes (e.g. SET) and the latter might be supported by multiple 300 Existing Payment Software modules. 301 o Each payment scheme may support multiple payment instruments 302 (e.g. particular card) or methods (e.g. Visa via SET) and the 303 latter might be shared by multiple Existing Payment Software 304 Components. 306 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 307 IOTP client (consumer) <---------------> IOTP server (merchant) 308 ( contains Internet ( contains 309 IOTP Application Core) IOTP Application Core) 310 ^ ^ 311 | IOTP Payment | IOTP Payment 312 | API | API 313 v v 314 IOTP Payment Bridge IOTP Payment Bridge 315 ^ ^ 316 | Existing Payment APIs, e.g., | 317 | SET, Mondex, etc. | 318 v v 319 Existing Payment Software Existing Payment Software 320 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 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. Additionally, 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 375 request, 377 o requests additional payment specific support from the Existing 378 Payment Software via the selected and registered the IOTP Payment 379 Bridge, 381 o initializes and terminates the Existing Payment Software via the 382 IOTP Payment Bridge, 384 o inquires authentication data (for subsequent request or response) 385 from the Existing Payment Software, specific authentication 386 component - omitted in this document - or Consumer (by a suitable 387 user interface), 389 o supervises the online transaction process and traces its progress, 391 o stores the transaction data being exchanged over the IOTP wire - 392 payment scheme specific data is handled transparently, 394 o relates each payment transaction with multiple payment parameters 395 (IOTP Transaction Identifier, Trading Protocol Options, Payment 396 Instrument/Method, Offer Response, IOTP Payment Bridge, and Wallet 397 Identifier, associated remote Parties). The relation might be 398 lowered to the party's Payment Identifier, IOTP Payment Bridge, 399 Wallet Identifier, and the remote parties when the actual payment 400 transaction has been successfully started. 402 o implements a payment transaction progress indicator, 404 o enables the inquiry of pending and completed payment transactions, 406 o implements generic dialogs, e.g., brand selection, payment 407 acknowledge, payment suspension / cancellation, receipt 408 visualization, basic transaction inquiry, balance inquiry, or 409 receipt validation, 411 o defers payment specific processing, supervision, validation, and 412 error resolution to the Existing Payment Software. It is expected, 413 that the Existing Payment Software will try to resolve many errors 414 first by the extended exchange of Payment Exchange messages. The 415 most significant and visible failures arise from sudden 416 unavailability or lapses of the local or opposing payment 417 component. 419 o supports the invocation of any Existing Payment Software in an 420 interactive mode, which might be used (1) for the payment scheme 421 specific post-processing of a (set of) payment transactions, (2) 422 for the analysis of a payment instrument, (3) for the registration 423 of a new payment instrument/scheme, or (4) re-configuration of a 424 payment instrument/scheme. 426 o exports call back functions for use by the IOTP Payment Bridge or 427 Existing Payment Software for progress indication. 429 In addition, the IOTP Application Core 431 o manages the IOTP message components and IOTP message blocks 432 exchanged during the transaction which may be referenced and 433 accessed during the processing of subsequent messages, e.g., for 434 signature verification. In particular, it stores named Packaged 435 Content elements exchanged during payments. 437 o manages several kinds of identifiers, i.e., transaction, message, 438 component, and block identifiers, 440 o implements a message caching mechanism, 442 o detects time-outs at the protocol and API level reflecting the 443 communication with both the IOTP aware remote party and the Payment 444 API aware local periphery, e.g., chip card (reader) may raise 445 time-outs. 447 However, the IOTP Payment Bridge and Existing Payment Software do not 448 have to rely on all of these IOTP Application Core's capabilities. 449 E.g., some Consumer's Existing Payment Software may refuse the 450 disclosure of specific payment instruments at brand selection time 451 and may delay this selection to the "Check Payment Possibility" 452 invocation using its own user interface. 454 The IOTP Payment Bridge's capabilities do not only deal with actual 455 payments between the Consumer and the Payment Handler but extend to 456 the following: 458 o translation and (dis)assemblage of messages between the formats of 459 the IOTP Payment API and those of the Existing Payment Software. 460 Payment API requests and response are strictly 1-to-1 related. 462 o Consumer's payment instrument selection by the means of an 463 unsecured/public export of the relationship of payment brands, 464 payment protocols, and payment instruments (identifiers). 465 Generally, this includes not just the brand (Mondex, GeldKarte, 466 etc.) but also which specific instance of the instrument and 467 currency to use (e.g. which specific Mondex card and which currency 468 of all those available). 470 However, some Existing Payment Software may defer the selection of 471 the payment instrument to the actual payment carrying-out or it may 472 even lack any management of payment instruments. E.g., chip card 473 based payment methods may offer - Point of Sale like - implicit 474 selection of the payment instrument by simple insertion of the chip 475 card into the chip card reader or it interrogates the inserted card 476 and requests an acknowledge (or selection) of the detected payment 477 instrument(s). 479 o payment progress checks, e.g., is there enough funds available to 480 carry out the purchase, or enough funds left for the refund, 482 o IOTP Payment Receipt checks which might be performed over its 483 Packaged Content or by other means. 485 o recoding of payment scheme specific receipts into a format which 486 can be displayed to the user or printed, 488 o cancellation of payment, even though it is not complete, 490 o suspension and resumption of payment transactions. Two kinds of 491 failures the Existing Payment Software might deal with are (1) the 492 time-out of the network connection and (2) lack of funds. For 493 resolution, the IOTP Application Core may try the suspension with a 494 view to later possible resumption. 496 o recording the payment progress and status on a database. E.g., 497 information about pending payments might be used to assist their 498 continuation when the next payment protocol message is received. 500 o payment transaction status inquiry, so that the inquirer - IOTP 501 Application Core or User - can determine the appropriate next step. 503 o balance inquiry or transaction history, e.g. consumers may 504 interrogate their chip card based payment instrument or remotely 505 administer some account in advance of a payment transaction 506 acknowledge, 508 o inquiry on abnormal interrupted payment transactions, which might 509 be used by the IOTP Application Core to resolve these pending 510 transactions at startup (after power failure). 512 o payment progress indication. This could be used to inform the end 513 user of details on what is happening with the payment. 515 o payment method specific authentication methods. 517 Existing Payment Software may not provide full support of these 518 capabilities. E.g., some payment schemes may not support or may even 519 prevent the explicit transaction cancellation at arbitrary phases of 520 the payment process. In this case, the IOTP Payment Bridge has to 521 implement at least skeletons that signal such lack of support by the 522 use of specific error codes (see below). 524 The Existing Payment Software's capabilities vary extremely. It 526 o supports payment scheme specific processing, supervision, 527 validation, and error resolution. It is expected, that many errors 528 are tried to be resolved first by the extended exchange of Payment 529 Exchange messages. 531 o provides hints for out-of-band failure resolution on failed inbound 532 resolution - inbound resolution is invisible to the IOTP 533 Application Core. 535 o may implement arbitrary transaction data management and inquiry 536 mechanisms ranging from no transaction recording, last transaction 537 recording, chip card deferred transaction recording, simple 538 transaction history to sophisticated persistent data management 539 with flexible user inquiry capabilities. The latter is required by 540 Payment Handlers for easy and cost effective failure resolution. 542 o implements the payment scheme specific dialog boxes. 544 Even the generic dialog boxes of the IOTP Application Core might be 545 unsuitable: Particular (business or scheme) rules may require some 546 dedicated appearance / structure / content or the dialog boxes, may 547 prohibit the unsecured export of payment instruments, or may 548 prescribe the pass phrase input under its own control. 550 2. Message Flow 552 The following lists all functions of the IOTP Payment API: 554 o Brand Compilation Related API Functions 556 "Find Accepted Payment Brand" identifies the accepted payment brands 557 for any indicated currency amount. 559 "Find Accepted Payment Protocol" identifies the accepted payment 560 protocols for any indicated currency amount (and brand) and returns 561 payment scheme specific packaged content for brand selection 562 purposes. 564 This function might be used in conjunction with the aforementioned 565 function or called without any brand identifier. 567 "Get Payment Initialization Data" returns additional payment scheme 568 specific packaged content for payment processing by the payment 569 handler. 571 "Inquire Authentication Challenge" returns the payment scheme 572 specific authentication challenge value. 574 "Check Authentication Response" verifies the returned payment scheme 575 specific authentication response value. 577 "Change Process State" is used (here only) for abnormal termination. 578 (cf. Payment Processing Related API Functions). 580 o Brand Selection Related API Functions 582 "Find Payment Instrument" identifies which instances of a payment 583 instrument of a particular payment brand are available for use in a 584 payment. 586 "Check Payment Possibility" checks whether a specific payment 587 instrument is able to perform a payment. 589 "Authenticate" forwards any payment scheme specific authentication 590 data to the IOTP Payment Bridge for processing. 592 "Change Process State" is used (here only) for abnormal termination. 593 (cf. Payment Processing Related API Functions). 595 o Payment Processing Related API Functions 597 "Start or Resume Payment Consumer/Payment Handler" initiate or resume 598 a payment transaction. There exist specific API functions for the two 599 trading roles Consumer and Payment Handler. 601 "Continue Process" forwards payment scheme specific data to the 602 Existing Payment Software and returns more payment scheme specific 603 data for transmission to the counter party. 605 "Change Process State" changes the current status of payment 606 transactions. Typically, this call is used for termination or 607 suspension without success. 609 o General Inquiry API Functions 611 "Remove Payment Log" notifies the IOTP Payment Bridge that a 612 particular entry has been removed from the Payment Log of the IOTP 613 Application Core. 615 "Payment Instrument Inquiry" retrieves the properties of Payment 616 Instruments. 618 "Inquire Pending Payment" reports any abnormal interrupted payment 619 transaction known by the IOTP Payment Bridge. 621 Payment Processing Related Inquiry API Functions 622 "Check Payment Receipt" checks the consistency and validity of IOTP 623 Payment Receipts, received from the Payment Handler or returned by 624 "Inquire Process State" API calls. Typically, this function is called 625 by the Consumer during the final processing of payment transactions. 626 Nevertheless, this check might be advantageous both for Consumers and 627 Payment Handlers on failure resolution. 629 "Expand Payment Receipt" expands the Packaged Content of IOTP Payment 630 Receipts as well as payment scheme specific payment receipts into a 631 form which can be used for display or printing purposes. 633 "Inquire Process State" responds with the payment state and the IOTP 634 Payment Receipt Component. Normally, this function is called by the 635 Payment Handler for final processing of the payment transaction. 637 "Start Payment Inquiry" prepares the remote inquiry of the payment 638 transaction status and responds with payment scheme specific data 639 that might be needed by the Payment Handler for the Consumer 640 initiated inquiry processing. 642 "Inquire Payment Status" is called by the Payment Handler on Consumer 643 initiated inquiry requests. This function returns the payment scheme 644 specific content of the Inquiry Response Block. 646 "Continue Process" and "Change Process State" (cf. Payment Processing 647 Related API Calls) 649 o Other API Functions 651 "Manage Payment Software" enables the immediate activation of the 652 Existing Payment Software. Further user input is under control of the 653 Existing Payment Software. 655 "Call Back" provides a general interface for the visualization of 656 transaction progress by the IOTP Application Core. 658 The following table shows which API functions must (+), should (#), 659 or might (?) be implemented by which Trading Roles. 661 API function Consumer Payment Handler Merchant 662 ------------ -------- --------------- -------- 664 Find Accepted Payment Brand + 665 Find Accepted Payment Protocol # 666 Find Payment Instrument + 668 Get Payment Initialization Data + 669 Check Payment Possibility + 671 Start Payment Consumer + 672 Start Payment Payment Handler + 673 Resume Payment Consumer # 674 Resume Payment Payment Handler # 676 Continue Process + + 677 Inquire Process State + + ? 678 Change Process State + + ? 679 Check Payment Receipt + ? 680 Expand Payment Receipt # ? 682 Remove Payment Log ? ? ? 684 Inquire Authentication Challenge ? 685 Authenticate + 686 Check Authentication Response ? 688 Payment Instrument Inquiry ? 689 Inquire Pending Payment # # 690 Start Payment Inquiry ? 691 Inquire Payment Status ? 693 Manage Payment Software # ? ? 695 Call Back # 696 Table 1: Requirements on API Functions by the Trading Roles 698 The next sections sketch the relationships and the dependencies 699 between the API functions. They provide the informal description of 700 the progress alternatives and depict the communication and 701 synchronization between the general IOTP Application Core and the 702 payment scheme specific modules. 704 2.1 Authentication Documentation Exchange 706 This section describes how the functions in this document are used 707 together to process authentication. 709 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 710 Authenticator Inquire Authentication Challenge(Alg1*) -> IPB 711 Inq. Auth. Challenge Response(Alg1,Ch1) <- IPB 712 . . . 713 Inquire Authentication Challenge(Algn*) -> IPB 714 Inq. Auth. Challenge Response(Algn,Chn) <- IPB 715 Create and transmit Authentication Request Block 716 Authenticatee Authenticate(Alg1, Ch1) -> IPB 717 AuthenticateResponse(...) <- IPB 718 . . . 719 Authenticate(Algm, Chm) -> IPB 720 AuthenticateResponse(Res) <- IPB 721 Create and transmit Authentication Response Block 722 Authenticator Check Authentication Response(Algm,Chm,Res)->IPB 723 Check Auth. Response() <-IPB 724 Create and transmit Authentication Status Block 725 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 727 Figure 2. Authentication Message Flows 729 1. (Authenticator Process) None, one or multiple IOTP Payment Bridges 730 (IPB) are requested for one or multiple authentication challenge 731 values ("Inquire Authentication Challenge"). Each value is 732 encapsulated in an IOTP Authentication Request Component. In 733 addition, the IOTP Application Core may add payment scheme 734 independent authentication methods. All of them form the final 735 IOTP Authentication Request Block, which describes the set of 736 authentication methods being supported by the authenticator and 737 from which the Authenticatee has to choose one method. 739 Note that the interface of the API function is limited to the 740 response of exactly one algorithm per call. If the IOTP 741 Application Core provides a choice of algorithms for input, this 742 choice should be reduced successively by the returned algorithm 743 ({Alg(i+1)*} is subset of {Algi*}). 745 During the registration of new Payment Instruments, the IOTP 746 Payment Bridge notifies the IOTP Application Core about the 747 supported authentication algorithms. 749 2. On the presence of an IOTP Authentication Block within the 750 received IOTP message, the Authenticatee's IOTP Application Core 751 checks whether the IOTP transaction type in the current phase 752 actually supports the authentication process. 754 For each provided Authentication Request Component, the IOTP 755 Application Core analyzes the algorithms' names, the transaction 756 context, and optionally user preferences in order to determine the 757 system components which are capable to process the authentication 758 request items. Such system components might be the IOTP 759 Application Core itself or any of the registered IOTP Payment 760 Bridges. 762 Subsequently, the IOTP Application Core requests the responses to 763 the supplied challenges from the determined system components in 764 any order. The authentication trials stop with the first 765 successful response, which is included in the IOTP Authentication 766 Response Block. 768 Alternatively, the IOTP Application might ask for a user 769 selection. This might be appropriate, if two or more 770 authentication algorithms are received that require explicit user 771 interaction, like PIN or chip card insertion. 773 The Authenticatee's organizational data is requested by an IOTP 774 Authentication Request Block without any content element. On 775 failure, the authentication (sequence) might be retried, or the 776 whole transaction might be suspended or cancelled. 778 3. (Authenticator Process) The IOTP Application Core checks the 779 presence of the IOTP Authentication Response Component in the 780 Authentication Response Block and forwards its content to the 781 generator of the associated authentication challenge for 782 verification ("Check Authentication Response"). 784 On sole organizational data request, its presence is checked. 786 Any verification must succeed in order to proceed with the 787 transaction. 789 2.2 Brand Compilation 791 The following shows how the API functions are used together so that 792 the Merchant can (1) compile the Brand List Component, (2) generate 793 the Payment Component, and (3) adjust the Order Component with 794 payment scheme specific packaged content. 796 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 797 Merchant For each registered IOTP Payment Bridge 798 | Find Accepted Payment Brand() -> IPB 799 | Find Accepted Payment Brand Response (B*) <- IPB 800 | Find Accepted Payment Protocol(B1) -> IPB 801 | Find Accepted Payment Protocol Res.(P1*) <- IPB 802 | . . . 803 | Find Accepted Payment Protocol(Bn) -> IPB 804 | Find Accepted Payment Protocol Res.(Pn*) <- IPB 805 Create one Brand List Component, ideally sharing 806 common Brand, Protocol Amount, Currency Amount, 807 and Pay Protocol Elements 808 Create Trading Protocol Options Block 809 On brand independent transactions 810 | Create Brand Selection Component, implicitly 811 | Get Payment Initialization Data(B1,P1) -> IPB 812 | Get Payment Initialization Data Res.() <- IPB 813 | Optionally 814 | | Inquire Process State() -> IPB 815 | | Inquire Process State Response(State) <- IPB 816 | Create Offer Response Block 817 Transmit newly created Block(s) 818 Consumer Consumer selects Brand (Bi)/Currency/Protocol (Pj) 819 from those that will work and generates Brand 820 Selection Component - at least logically 821 On brand dependent transaction 822 | Transmit Brand Selection Component 823 Merchant On brand dependent transaction 824 | Get Payment Initialization Data(Bi,Pj) -> IPB 825 | Get Payment Initialization Data Res.() <- IPB 826 | Optionally 827 | | Inquire Process State() -> IPB 828 | | Inquire Process State Response(State) <- IPB 829 | Create Offer Response Block 830 | Transmit newly created Block 831 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 833 Figure 3. Brand Compilation Message Flows 835 1. The Merchant's commerce server controls the shopping dialog with 836 its own mechanisms until the Consumer checks out the shopping cart 837 and indicates the payment intention. The notion shopping subsumes 838 any non-IOTP based visit of the Merchant Trading Role's (which 839 subsumes Financial Institutes) web site in order to negotiate the 840 content of the IOTP Order Component. The subsequent processing 841 switches to the IOTP based form by the activation of the 842 Merchant's IOTP aware application. 844 2. The IOTP Application Core inquires for the IOTP level trading 845 parameters (Consumer's shopping identifier, payment direction, 846 initial currency amounts, discount rates, Merchant's and Delivery 847 Handler's Net Locations, Non-Payment Handler's Organizational 848 Data, initial order information, ....). 850 3. The registered IOTP Payment Bridges are inquired by the IOTP 851 Application Core about the accepted payment brands ("Find Accepted 852 Payment Brand"). Their responses provide most of the attribute 853 values for the compilation of the Brand List Component's Brand 854 Elements. The IOTP Application Core might optionally match the 855 returned payment brands with Merchant's general preferences. 857 The IOTP Application Core must provide any wallet identifiers, if 858 they are required by the IOTP Payment Bridges which signal their 859 need by specific error codes (see below). Any signaled error that 860 could not be immediately solved by the IOTP Application Core 861 should be logged - this applies also to the subsequent API calls 862 of this section. In this case, the IOTP Application Core creates 863 an IOTP Error Block (hard error), transmits it to the Consumer, 864 and terminates the current transaction. 866 4. The IOTP Application Core interrogates the IOTP Payment Bridges 867 for each accepted payment brand about the supported payment 868 protocols ("Find Accepted Payment Protocol"). These responses 869 provide the remaining attribute values of the Brand Elements as 870 well as all attribute values for the compilation of the Brand List 871 Component's Protocol Amount and Pay Protocol Elements. 872 Furthermore, the organisational data about the Payment Handler is 873 returned. The IOTP Application Core might optionally match the 874 returned payment brands with Merchant's general preferences. 876 Alternatively, the IOTP Application Core might skip the calls of 877 "Find Accepted Payment Brands" (cf. Step 3) and issue the "Find 878 Accepted Payment Protocol" call without any Brand given on the 879 input parameter list. In this case, the IOTP Payment Bridge 880 responds to the latter call with the whole set of payment schemes 881 supported w.r.t. the other input parameters. 883 5. The steps 3 and 4 are repeated during IOTP Value Exchange 884 transactions - these steps are omitted in the previous figure. 886 6. The IOTP Application Core compiles the Brand List Component(s) and 887 the IOTP Trading Protocol Options Block. It is recommended that 888 the "equal" items returned by IOTP Payment Bridge function calls 889 are shared due to the extensive linking capabilities within the 890 Brand List Component. However, the compilation must consider 891 several aspects in order to prevent conflicts - sharing detection 892 might be textual matching (after normalization): 894 o Packaged Content Elements contained in the Brand List 895 Component (and subsequently generated Payment and Order 896 Components) might be payment scheme specific and might depend 897 on each other. 899 o Currently, IOTP lacks precise rules for the content of the 900 Packaged Content Element. Therefore, transaction / brand / 901 protocol / currency amount (in)dependent data might share the 902 same Packaged Content Element or might spread across multiple 903 Packaged Content Elements. 905 o The Consumer's IOTP Application Core transparently passes the 906 Packaged Content Elements to the IOTP Payment Bridges which 907 might not be able to handle payment scheme data of other 908 payment schemes, accurately. 910 The rules and mechanisms of how this could be accomplished are out 911 of the scope of this document. Furthermore, this document does not 912 define any further restriction to the IOTP specification. 914 7. The IOTP Application Core determines whether the IOTP message can 915 be enriched with an Offer Response Block. This is valid under the 916 following conditions: 918 o All payment alternatives share the attribute values and 919 Packaged Content Elements of the subsequently generated IOTP 920 Payment and Order Components. 922 o The subsequently generated data does not depend on any IOTP 923 BrandSelInfo Elements that might be reported by the consumer 924 within the TPO Selection Block in the brand dependent 925 variant. 927 If both conditions are fulfilled, the IOTP Application Core might 928 request the remaining payment scheme specific payment 929 initialization data from the IOTP Payment Bridge ("Get Payment 930 Initialization Data") and compile the IOTP Offer Response Block. 932 Optionally, the IOTP Application Core might request the current 933 process state from the IOTP Payment Bridge and add the inferred 934 order status to the IOTP Offer Response Block. Alternatively, IOTP 935 Application might determine the order status on its own. 937 As in step 6, the rules and mechanisms of how this could be 938 accomplished are out of the scope of this document. 940 8. The IOTP Application Core compiles the IOTP TPO Message including 941 all compiled IOTP Blocks and transmits the message to the 942 Consumer. The IOTP Application Core terminates if an IOTP Offer 943 Response Block has been created. 945 9. The Consumer performs the Brand Selection Steps (cf. Section 2.3) 946 and responds with a TPO Selection Block if no IOTP Offer Response 947 Block has been received. Otherwise, the following step is skipped. 949 10. On brand dependent transactions, the IOTP Application Core 950 requests the remaining payment scheme specific payment 951 initialization data from the IOTP Payment Bridge ("Get Payment 952 Initialization Data"), compiles the IOTP Offer Response Block, 953 transmits it to the Consumer, and terminates. Like Step 7, the 954 IOTP Application Core might access the current process state of 955 the IOTP Payment Bridge for the compilation of the order status. 957 Any error during this process raises an IOTP Error Block. 959 2.3 Brand Selection 961 This section describes the steps that happen mainly after the 962 Merchant's Brand Compilation (in a brand independent transaction). 963 However, these steps might partially interlace the previous process 964 (in a brand dependent transaction). 966 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 967 Merchant Merchant generates Brand List(s) containing 968 Brands, Payment Protocols and Currency Amounts 969 On brand independent transactions 970 | Merchant generates Offer Response Block 971 Consumer Compile set(s) of Brands B/Protocols P 972 for each set 973 | Find Payment Instrument(B, P, C) -> IPB 974 | Find Payment Instrument Response (PI*) <- IPB 975 Consumer selects Brand/Currency/Payment Instrument 976 from those that will work and generates Brand 977 Selection Component 978 For the Selection 979 | Get Payment Initialization Data(B,C,PI,P) -> IPB 980 | Get Payment Initialization Data Response()<- IPB 981 On brand dependent transaction 982 | Generate and transmit TPO Selection Block 983 Merchant On brand dependent transaction 984 | Merchant checks Brand Selection and generates 985 | and transmits Offer Response Block 986 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 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 994 Merchant's 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 999 protocols 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 1005 o infers the accepted payment brands, payment protocols, 1006 payment direction, currencies, payment amounts, any 1007 descriptions etc., and their relationships from the IOTP 1008 message, 1010 o determines the registered IOTP Payment Bridges, 1012 o compiles one or multiple sets of brand and protocol such that 1013 the join of all sets describes exactly the payment 1014 alternatives 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 1019 Payment Bridges may refuse payment instrument distinction. 1021 The payment protocol support may differ between payment 1022 instruments if the IOTP Payment Bridge supports payment instrument 1023 distinction. 1025 These API calls are used to infer the payment alternatives at the 1026 startup of any payment transaction (without user unfriendly 1027 explicit user interaction). 1029 The IOTP Application Core must provide wallet identifiers, if they 1030 are requested by the IOTP Payment Bridges which signal their need 1031 by specific error codes (see below). 1033 It is recommended that the IOTP Application Core manages wallet 1034 identifiers. But for security reasons, it should store pass 1035 phrases in plain text only in runtime memory. Developers of IOTP 1036 Payment Bridges and payment software modules should provide a thin 1037 and fast implementation - without lengthy initialization 1038 processes- for this initial inquiry step. 1040 4. The IOTP Application Core verifies the Consumer's payment 1041 capabilities with the Merchant's accepted payment brands and 1042 currencies, 1044 o displays the valid payment instruments and payment instrument 1045 independent payment brands (brand and protocol) together with 1046 their purchase parameters (payment direction, currency, 1047 amount), and 1049 o requests the Consumer's choice or derives it automatically 1050 from any configured preferences. Any selection ties one IOTP 1051 Payment Bridge with the following payment transaction. 1053 The handling and resolution of unavailable IOTP Payment Bridges 1054 during the inquiry in Step 3 is up to the IOTP Application Core. 1056 It may skip these IOTP Payment Bridges or may allow user supported 1057 resolution. 1059 Furthermore, it may offer the registration of new payment 1060 instruments when the Consumer is asked for payment instrument 1061 selection. 1063 5. The IOTP Application Core interrogates the fixed IOTP Payment 1064 Bridge whether the payment might complete with success ("Check 1065 Payment Possibility"). At this step, the IOTP Payment Bridge may 1066 issue several signals, e.g., 1068 o payment can proceed immediately, 1069 o required peripheral inclusive of some required physical 1070 payment instrument (chip card) is unavailable, 1071 o (non-IOTP) remote party (e.g. issuer, server wallet) is not 1072 available, 1073 o wallet identifier or pass phrase is required, 1074 o expired payment instrument (or certificate), insufficient 1075 funds, or 1076 o physical payment instrument unreadable. 1078 In any erroneous case, the user should be notified and offered 1079 accurate alternatives. Most probably, the user might be offered 1081 o to resolve the problem, e.g. to insert another payment 1082 instrument or to verify the periphery, 1083 o to proceed (assuming its success), 1084 o to cancel the whole transaction, or 1085 o to suspend the transaction, e.g., initiating a nested 1086 transaction for uploading an electronic purse. 1088 If the payment software implements payment instrument selection on 1089 its own, it may request the Consumer's choice at this step. 1091 If the check succeeds, it returns several IOTP Brand Selection 1092 Info Elements. 1094 6. The Steps 2 to 5 are repeated and possibly interlaced for the 1095 selection of the second payment instrument during IOTP Value 1096 Exchange transactions - this is omitted in the figure above. 1098 7. The IOTP Brand Selection Component is generated and enriched with 1099 the Brand Selection Info elements. This component is transmitted 1100 to the Merchant inside a TPO Selection Block if the received IOTP 1101 message lacks the IOTP Offer Response Block. The Merchant will 1102 then respond with an IOTP Offer Response Block (following the 1103 aforementioned compilation rules). 1105 2.4 Successful Payment 1107 An example of how the functions in this document are used together to 1108 effect a successful payment is illustrated in the Figure 5. 1110 (Technically, two payments happen during IOTP Value Exchange 1111 transactions.) 1113 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1114 Consumer Start Payment Consumer(Amount,[PS0]...) -> IPB 1115 Start Payment Cons. Res.([PS1], CS=Cont.) <- IPB 1116 Create and transmit Payment Request Block 1117 Payment Handler Start Payment Pay. Handler(Amount, [PS1]) -> IPB 1118 Start Payment PH Response(PS2, CS=Cont.) <- IPB 1119 Create and transmit Payment Exchange Block 1120 Consumer Continue Process(PS2) -> IPB 1121 Continue Process Response(PS3, CS=Cont.) <- IPB 1123 ... CONTINUE SWAPPING PAYMENT EXCHANGES UNTIL ... 1125 Payment Handler Continue Process Response([PSn], CS=End) <- IPB 1126 Request any local payment receipt 1127 | Inquire Process State() -> IPB 1128 | Inquire Proc. State Resp.(State, [Rcp.])<- IPB 1129 Create and transmit Payment Response Block 1130 Terminate transaction, actively 1131 | Change Process State(State) -> IPB 1132 | Change PS Response(State=CompletedOK) <- IPB 1133 Consumer On receipt of final payment scheme data 1134 | Continue Process(PSn) -> IPB 1135 | Continue Process Response(CS=End) <- IPB 1136 Check Payment Receipt(Receipt) -> IPB 1137 Check Payment Receipt Response() <- IPB 1138 Request any local payment receipt 1139 | Inquire Process State() -> IPB 1140 | Inquire Proc. State Resp.(State, [Rcp.])<- IPB 1141 Terminate transaction, actively 1142 | Change Process State(State) -> IPB 1143 | Change PS Response(State=CompletedOk) <- IPB 1144 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1146 Figure 5. Example Payment Message Flows 1148 1. After Brand Selection and receipt of the IOTP Offer Response 1149 Block, the Consumer switches from communicating with the Merchant 1150 to communicating with the Payment Handler. 1152 This might be a milestone requiring the renewed Consumer's 1153 agreement about the payment transaction's continuation. 1154 Particularly, this is a good moment for payment suspension (and 1155 even cancellation), which will be most probably supported by all 1156 payment schemes. Simply, because the actual payment legacy systems 1157 have not yet been involved in the current transaction. 1159 Such an agreement might be explicit per transaction or automatic 1160 based on configured preferences, e.g., early acknowledgments for 1161 specific payment limits. 1163 It is assumed, that the transaction proceeds with minimal user 1164 (Consumer and Payment Handler) interaction and that its progress 1165 is controlled by the IOTP Application Core and IOTP Payment 1166 Bridge. 1168 2. In order to open the actual payment transaction, the IOTP 1169 Application Core issues the "Start Payment Consumer" request 1170 towards the IOTP Payment Bridge. This request carries the whole 1171 initialization data of the payment transaction being referred to 1172 by the IOTP Payment Bridge for subsequent consistency checks: 1174 o payment brand and its description from the selected Brand 1175 Element of the IOTP Brand List Component, 1176 o payment instrument from preceding inquiry step, 1177 o further payment parameters (currency, amount, direction, 1178 expiration) from the selected Currency Amount element, Brand 1179 List Component, and Payment Component of the IOTP Offer 1180 Response Block, 1181 o payment protocol from the selected IOTP Pay Protocol Element, 1182 o order details contained in the IOTP Order Component which 1183 might be payment scheme specific, 1184 o payment scheme specific data inclusive of the payment 1185 protocol descriptions from the IOTP Protocol Amount Element, 1186 and IOTP Pay Protocol Element, and 1187 o payment scheme specific data inclusive of the payment 1188 protocol descriptions, in which the name attribute includes 1189 the prefix as "Payment:" from the Trading Role Data 1190 Component. 1192 Generally, the called API function re-does most checks of the 1193 "Check Payment Possibility" call due to lack of strong 1194 dependencies between both requests: There might be a significant 1195 delay between both API requests. 1197 The called API function may return further payment scheme specific 1198 data being considered as payment specific initialization data for 1199 the Payment Handler's IOTP Payment Bridge. 1201 If the fixed Existing Payment Software implements payment 1202 instrument selection on its own, it may request the Consumer's 1203 choice at this step. 1205 The IOTP Payment Bridge reports lack of capability quite similarly 1206 to the "Check Payment Possibility" request to the IOTP Application 1207 Core. The Consumer may decide to resolve the problem, to suspend, 1208 or to cancel the transaction, but this function call must succeed 1209 in order to proceed with the transaction. 1211 Developers of payment modules may decide to omit payment 1212 instrument related checks like expiration date or refunds 1213 sufficiency, if such checks are part of the specific payment 1214 protocol. 1216 If the IOTP Payment Bridge requests wallet identifiers or pass 1217 phrases anywhere during the payment process, they should be 1218 requested by this API function, too. It is recommended that the 1219 IOTP Application Core stores plain text pass phrases only in 1220 runtime memory. 1222 Finally, the IOTP Application Core generates the IOTP Payment 1223 Request Block, inserts any returned payment scheme data, and 1224 submits it to the Payment Handler's system. 1226 3. The Payment Handler's IOTP Application Core opens the payment 1227 transaction calling the "Start Payment Payment Handler" API 1228 function. The payment brand, its description, payment protocol, 1229 payment specific data, payment direction, currency and payment 1230 amount are determined quite similar to the Consumer's IOTP 1231 Application Core. Furthermore, the content of the IOTP Payment 1232 Scheme Component and the IOTP Brand Selection Info Elements are 1233 passed to this function. 1235 On success, the Payment Handler's IOTP Payment Bridge responds 1236 with payment scheme specific data. On failures, this non- 1237 interactive server application has to resolve any problems on its 1238 own or to give up aborting the payment transaction. However, the 1239 Consumer may restart the whole payment transaction. Anyway, the 1240 payment log file should reflect any trials of payments. 1242 Eventually, the Payment Handler informs the Consumer about the 1243 current IOTP Process State using the IOTP Payment Response or IOTP 1244 Error Block. 1246 Note that the "Start Payment Payment Handler" call might return 1247 the Continuation Status "End" such that payment processing 1248 proceeds with Step 7. 1250 4. The IOTP Application Core verifies the presence of the Payment 1251 Exchange Block in the IOTP message and passes the contained 1252 payment scheme specific data to the fixed IOTP Payment Bridge 1253 ("Continue Process") which returns the next IOTP Payment Scheme 1254 Component. 1256 This Payment Scheme Component is encapsulated in an IOTP Payment 1257 Exchange Block and transmitted to the Payment Handler. 1259 5. The Payment Handler's IOTP Application Core verifies the presence 1260 of the Payment Exchange Block and passes the contained payment 1261 scheme specific data to the fixed IOTP Payment Bridge ("Continue 1262 Process") which returns the next IOTP Payment Scheme Component for 1263 encapsulation and transmission to the Consumer. 1265 6. The payment process continues with IOTP Payment Exchange Block 1266 exchanges, carrying the payment scheme specific data. Each party 1267 (1) submits the embedded payment scheme specific data 1268 transparently to the appropriate IOTP Payment Bridge calling the 1269 "Continue Process" API function, (2) wraps the returned payment 1270 scheme specific data into an IOTP Payment Exchange Block, and (3) 1271 transmits this block to the counter party. 1273 However, the processing of the payment scheme specific data may 1274 fail for several reasons. These are signaled by specific error 1275 codes which are transformed to IOTP Payment Response Blocks 1276 (generated by Payment Handler) or IOTP Error Blocks (both parties 1277 may generate them) and transmitted to the counter party. 1279 7. Eventually, the Payment Handler's IOTP Payment Bridge recognizes 1280 the termination of the payment transaction and reports this by the 1281 continuation status "End" on the output parameter of "Continue 1282 Process" (or "Start Payment Payment Handler"). Then, the IOTP 1283 Application Core issues the "Inquire Process State" API call and 1284 verifies whether an IOTP Payment Receipt Component has been 1285 returned. The IOTP Application Core wraps the payment receipt, the 1286 status response, and the optional payment scheme specific data in 1287 an IOTP Payment Response Block and transmits this block to the 1288 Consumer. 1290 However, any of these API calls may fail or any response might be 1291 incomplete (e.g., lack of payment receipt). Then, the Consumer has 1292 to be notified about the failed processing by an IOTP Error Block. 1294 Finally, the Payment Handler terminates the payment transaction 1295 with the "Change Process State" API call without awaiting any 1296 further response from the Consumer. Further failures are not 1297 reported to the Consumer. 1299 Note that it might be possible that the Consumer's IOTP Payment 1300 Bridge has returned the previous payment scheme specific data with 1301 the continuation status "End". Even in the absence of this 1302 knowledge - this status is not exchanged between the Consumer and 1303 the Payment Handler - the Payment Handler must not supply any 1304 further payment scheme specific data. Such data will be rejected 1305 by the Consumer's IOTP Payment Bridge. 1307 8. The Consumer passes the optional payment scheme specific data and 1308 the payment receipt to the fixed IOTP Payment Bridge by "Continue 1309 Process" and "Check Payment Receipt" API calls. 1311 Afterwards, the IOTP Application Core issues the "Inquire Process 1312 State" API call and verifies whether extensions to the payment 1313 receipt have been returned. 1315 Finally, the transaction is terminated by calling the "Change 1316 Process State" API function which verifies and synchronizes the 1317 reported payment status with the local one and signals any 1318 inconsistencies. Any Inconsistency and returned status text should 1319 be displayed to the Consumer. 1321 At this point, the payment transaction has already been closed by 1322 the Payment Handler. Therefore, any failure has to be resolved 1323 locally or out-of-band. 1325 2.5 Payment Inquiry 1327 In Baseline IOTP, Payment inquiries are initiated by the Consumer in 1328 order to verify the current payment progress and process state at the 1329 remote Payment Handler. 1331 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1332 Consumer Start Payment Inquiry() -> IPB 1333 Start Payment Inquiry Response([PS1]) <- IPB 1334 Create and transmit Inquiry Request Trading Block 1335 Payment Handler Inquire Payment Status([PS1]) -> IPB 1336 Inquire Payment Status Res.(State, [PS2]) -> IPB 1337 Create and transmit Inquiry Response Trading 1338 Block 1339 Consumer If Payment Scheme Data present 1340 | Continue Process(PS2) -> IPB 1341 | Continue Process Response(CS=End) <- IPB 1342 Change Process State(State) -> IPB 1343 Change Process State Response(State) <- IPB 1344 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1346 Figure 6. Remote Process State Inquiry 1348 1. The Consumer might initiate a payment inquiry once the payment 1349 transaction has been opened by the IOTP Application Core, i.e., at 1350 any time after the initial submission of the IOTP Payment Request 1351 Block. The IOTP Application Core requests any additional specific 1352 payment scheme data from the IOTP Payment Bridge which has been 1353 fixed during brand selection (cf. Section 2.3) using the "Start 1354 Payment Inquiry" API request. 1356 Erroneous API responses should be reported to the Consumer and 1357 valid alternatives (typically retry and cancellation) should be 1358 presented by the IOTP Application Core. 1360 This request might perform the complete initialization, e.g. 1361 availability check of periphery or pass phrase supplement, and the 1362 IOTP Payment Bridge reports lack of capability quite similarly to 1363 the "Check Payment Possibility" request to the IOTP Application 1364 Core. 1366 If the IOTP Payment Bridge requests wallet identifiers or pass 1367 phrases anywhere during the payment process, they should be 1368 requested by this API function, too. It is recommended that the 1369 IOTP Application Core store plain text pass phrases only in 1370 runtime memory. 1372 The IOTP Application Core encapsulates any Payment Scheme 1373 Component in an IOTP Inquiry Request Block and submits the block 1374 to the Payment Handler. 1376 2. The Payment Handler analyses the IOTP Inquire Request Block, maps 1377 the Transaction Identifier to payment related attributes (brand, 1378 consumer and payment identifiers), determines the appropriate IOTP 1379 Payment Bridge, and forwards the request to the this IOTP Payment 1380 Bridge ("Inquire Payment Status"). The IOTP Application Core 1381 transforms the response to an IOTP Inquiry Response Block and 1382 transmits it to the Consumer. 1384 3. On receipt of the respective IOTP Inquiry Response Block the 1385 Consumer's IOTP Application Core submits any encapsulated payment 1386 scheme specific data to the IOTP Payment Bridge for verification 1387 ("Continue Process"). 1389 4. The IOTP Application Core passes the reported payment status 1390 (except textual descriptions) to the IOTP Payment Bridge ("Change 1391 Process State") for verification purposes and payment status 1392 change. The IOTP Payment Bridge reports any inconsistencies as 1393 well as the final payment status to the IOTP Application Core. 1395 Any additional information that might be of interest to the 1396 Consumer has to be displayed by the IOTP Payment Bridge or 1397 Existing Payment Software on their own. 1399 2.6 Abnormal Transaction Processing 1400 2.6.1 Failures and Cancellations 1402 The IOTP specification distinguishes between several classes of 1403 failures: 1405 o Business and technical errors 1406 o Error depths of transport, message and block level 1407 o Transient errors, warnings, and hard errors. 1409 Any IOTP Payment API has to deal with the receipt of failure 1410 notifications by and failure responses. This proposal has borrowed 1411 the basic mechanisms for error reporting between the IOTP Application 1412 Core and the IOTP Payment Bridge from the actual protocol: Business 1413 errors are reported by Status Components within IOTP Response Blocks 1414 while technical errors are signaled by Error Components within IOTP 1415 Error Blocks. 1417 Cancellations are mimicked as specific business errors which might be 1418 initiated by each trading party. 1420 Preferring slim interfaces, this IOTP Payment API introduces one 1421 additional Error Code value for business error indication - errors 1422 can be raised on every API call. On receipt of this value, the IOTP 1423 Application Core has to infer further details by the issuance of the 1424 API function call "Inquire Process State". 1426 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1427 Any Party Issue some API request -> IPB 1428 Error Response(Error Code) <- IPB 1429 On "Business Error" response 1430 | Inquire Process State() -> IPB 1431 | Inquire P.S. Resp.(State, Receipt) <- IPB 1432 Analyze local process state and try to resolve 1433 with optional user interaction 1434 If Process State Change needed 1435 | Change Process State (State) -> IPB 1436 | Change Process State Response(State) <- IPB 1437 If counter party's notification required 1438 | Create Error or Cancel Block (, add to next 1439 | message, ) and transmit it to counter party 1440 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1442 Figure 7. Error Response from IPB 1444 The specific Completion Codes "ConsCancelled", "MerchCancelled", and 1445 "PaymCancelled" - returned by "Inquire Process State" - determine 1446 that the IOTP Cancel Block has to be created instead of an IOTP Error 1447 Block. 1449 The rules for determining the required behavior of the IOTP 1450 Application Core are given in the IOTP specification. 1452 Note that any payment (intermediate) termination, i.e., failures, 1453 cancellations, and even successes are always reported to the IOTP 1454 Payment Bridge by the API function "Change Process State". This API 1455 function does both status changes and consistency checking / 1456 synchronization. Any suspicion of inconsistency should be reported by 1457 the IOTP Payment Bridge for display by the IOTP Application Core. 1459 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1460 Any Party Error Block or Cancel Block Received 1461 If Change Process State required 1462 | Change Process State (State) -> IPB 1463 | Change Process State Response(State) <- IPB 1464 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1466 Figure 8. Error Notification from counter party 1468 Not every failure might be visible at the IOTP layer, e.g., the 1469 processing of payment transactions might temporarily be hampered by 1470 intermediate failures at the payment scheme or protocol transport 1471 layer which might be resolved by the actual components. 1473 However, final failures or cancellations have to be reported at the 1474 IOTP layer. E.g., communication time-outs and heavily faulty 1475 communication channels may disable the transaction. 1477 Any system component may implement time-out recognition and use the 1478 aforementioned API mechanisms for the notification of process state 1479 changes. But, time-outs may happens while communicating with both the 1480 counter party and local system components, like chip card readers or 1481 IOTP Payment Bridges. Anyway, the Consumer's IOTP Application Core 1482 should notify the Consumer about the resolution alternatives, i.e., 1483 retry, suspension, and cancellation. 1485 2.6.2 Resumption 1487 Payment transaction resumption may apply at different steps of a 1488 payment transaction: 1490 o The Consumer's and Payment Handler's view of the transaction might 1491 not be synchronized: Due to different time-out values the payment 1492 transaction may not have been suspended by the counter party. 1494 Any "Resume Payment ..." API function responds with an Error Code 1495 on non-suspended payment transaction that signals a business error. 1496 Afterwards the IOTP Application Core has to issue the "Inquire 1497 Process State" API call for further analysis of the process state. 1499 o One IOTP message sent by one party might not be processed 1500 successfully or even received by the counter party. 1502 This needs to be handled by the actual payment scheme. It is 1503 expected that the IOTP Application Core will not recognize 1504 anything. 1506 o IOTP does not provide any specific signal for payment resumption. 1507 On receipt of every IOTP Payment Exchange Block, the IOTP 1508 Application Core has to decide whether this Block belongs to a 1509 pending transaction or to a suspended transaction that should be 1510 resumed. The IOTP Application Core might call the "Inquire Process 1511 State" API function to update any lack of knowledge. 1513 Any "Resume Payment" API function responds with an Error Code on 1514 non-suspended payment transaction that signals a business error. 1515 Similar, the "Continue Process" API function should report business 1516 errors on non-pending payment transactions. 1518 o The payment transaction may not have been created at the Payment 1519 Handler (early suspension and failed data transmission). In that 1520 case, the IOTP Application Core should respond with a business 1521 error that signals the repetition of the payment transaction (by 1522 the Consumer). 1524 Any "Resume Payment", "Continue Process" or "Inquire Process State" 1525 API function should return with an Error Code "AttValIllegal" on 1526 non-existent payment transaction whereby the further Error 1527 Attribute "Names" denote the payment identifier. 1529 o The IOTP Application Core should always request fresh payment 1530 scheme specific data on resumption - for synchronization purposes 1531 with the Existing Payment Software. Old data in the cache that has 1532 not been send to the counter party should not be accessed. 1534 If the Consumer does not reconnect within an acceptable amount of 1535 time, the Payment Handler's system may perform local failure 1536 resolution in order to close the transaction and to retain resources 1537 for other transactions ("Change Process State"). If the Consumer 1538 reconnect afterwards, an IOTP Payment Response or IOTP Error Block 1539 could be generated. 1541 2.7 IOTP Wallet Initialization 1543 At startup or on explicit user request the IOTP Application Core 1544 should check its IOTP Payment Bridges' internal status by searching 1545 for pending payment transactions. 1547 1. The IOTP Application Core interrogates the registered IOTP 1548 Payment Bridges about pending payment transactions. The IOTP 1549 Application Core may store indicators for pending transactions and 1550 use them for driving any subsequent inquiry ("Inquire Pending 1551 Payment"). 1553 2. If one or more IOTP Payment Bridges report the presence of pending 1554 transactions, the IOTP Application Core may try to suspend 1555 ("Change Process State") or resume (only Consumer: "Resume Payment 1556 Consumer") the pending transactions (on user request). 1558 The IOTP Payment Bridge may deny the processing of any new payment 1559 transactions until the pending transactions have been processed. Such 1560 denials are signaled by the error code "Business Error". 1562 2.8 Payment Software Management 1564 The IOTP Application Core provides only a simple and generic 1565 interface for the registration of new payment methods / instruments 1566 ("Manage Payment Software"). It receives the initial user request and 1567 defers the actual registration to the corresponding IOTP Payment 1568 Bridge. 1570 The IOTP Application Core may also activate the Existing Payment 1571 Software for further payment instrument and wallet administration. 1573 3. Mutuality 1575 The Payment API is formalized using the eXtensible Markup Language 1576 (XML). It defines wrapper elements for both the input parameters and 1577 the API function's response. In particular, the response wrapper 1578 provides common locations for Error Codes and Error Descriptions. 1580 It is anticipated that this description reflects the logical 1581 structure of the API parameter and might be used to derive 1582 implementation language specific API definitions. 1584 XML definition: 1586 1612 1618 1644 1650 1651 1661 Most of the attribute items are intended for immediate insertion in 1662 the IOTP Error Block. The attribute values of the Error Location 1663 elements attribute have to enriched and transformed into Error 1664 Location Elements of the Error Component (cf. IOTP Specification). 1666 Attributes (cf. IOTP Specification): 1668 xml:lang Defines the language used by attributes or 1669 child elements within this component, unless 1670 overridden by an xml:lang attribute on a child 1671 element. 1673 ContentSoftwareId Contains information which identifies the 1674 software that generated the content of the 1675 element. Its purpose is to help resolve 1676 interoperability problems that might occur as 1677 a result of incompatibilities between messages 1678 produced by different software. It is a single 1679 text string in the language defined by 1680 "xml:lang". It must contain, as a minimum 1681 problems that might occur as a result of 1683 o the name of the software manufacturer, 1684 o the name of the software, 1685 o the version of the software, and 1686 o the build of the software. 1688 ErrorCode Contains an error code which indicates the 1689 nature of the error in the message in error. 1690 Valid values for the Error Code are given in 1691 the following section. This mnemonic enables 1692 the automatic failure resolution of the IOTP 1693 Application Core which analyzes the error code 1694 value in order to determine the continuation 1695 alternatives. 1697 ErrorDesc Contains a description of the error in the 1698 language defined by xml:lang. The content of 1699 this attribute is defined by the 1700 vendor/developer of the software that 1701 generated the Error Response Element. 1702 It is intended for user display and provides 1703 detailed explanations about the failure and 1704 its (out-of-band) resolution alternatives. 1706 Severity Indicates the severity of the error. Valid 1707 values are: 1709 o Warning. This indicates that although there 1710 is a message in error the IOTP Transaction 1711 can still continue. 1713 o TransientError. This indicates that the 1714 error in the message in error may be 1715 recovered if the message in error that is 1716 referred to by the "Names" attribute is 1717 resent. 1719 o HardError. This indicates that there is an 1720 unrecoverable error in the message in error 1721 and the IOTP Transaction must stop. 1723 MinRetrySecs This attribute should be present if "Severity" 1724 is set to "TransientError". It is the minimum 1725 number of whole seconds which the IOTP aware 1726 application which received the message 1727 reporting the error should wait before re- 1728 sending the message in error identified by the 1729 "ErrorLocation" attribute. 1731 If Severity is not set to 1732 "TransientError" then the value of this 1733 attribute is ignored. 1735 SwVendorErrorRef This attribute is a reference whose value is 1736 set by the vendor/developer of the software 1737 that generated the Error Element. It should 1738 contain data that enables the vendor to 1739 identify the precise location in their 1740 software and the set of circumstances that 1741 caused the software to generate a message 1742 reporting the error. 1744 Content: 1746 ErrorLocation This identifies, where possible, the 1747 element and attribute in the message 1748 in error that caused the Error 1749 Element to be generated. If the 1750 "Severity" of the error is not 1751 "TransientError", more that one 1752 "ErrorLocation" may be specified as 1753 appropriate depending on the nature 1754 of the error and at the discretion of 1755 the vendor/developer of the IOTP 1756 Payment Bridge. 1758 Its definition coincides with the 1759 IOTP specification whereby the 1760 attributes "IotpMsgRef", "BlkRef" and 1761 "CompRef" are left blank, 1762 intentionally. 1764 PaySchemePackagedContent cf. Table 5 1766 3.1 Error Codes 1768 The following table lists the valid values for the ErrorCode 1769 attribute of the Error Response Element. The first sentence of the 1770 error description contains the default text that can be used to 1771 describe the error when displayed or otherwise reported. Individual 1772 implementations may translate this into alternative languages at 1773 their discretion. However, not every error code may apply to every 1774 API call. An Error Code must not be more than 14 characters long. 1776 The Error Codes have been taken from the IOTP Specification and 1777 extended by some additional codes which are highlighted by a 1778 preceding asterisk. 1780 Generally, if the corrupt values have been user supplied, the IOTP 1781 Application Core might prompt for their correction. If the renewal 1782 fails or if the IOTP Application Core skips any renewals and some 1783 notification has to be send to the counter-party, the error code is 1784 encapsulated within an IOTP Error Block. 1786 However, the IOTP server application reports business errors - 1787 visible at the IOTP layer - in the Status Component of the respective 1788 Response Block. 1790 The IOTP Application Core may add the attributes (and values) within 1791 the ErrorLocation elements that are omitted by the IOTP Payment 1792 Bridge. 1794 The following table mentions any modification from this general 1795 processing for particular error values. Furthermore, it contains 1796 hints for developers of IOTP Application Core software components 1797 about the processing of error codes. Conversely, developers of IOTP 1798 Payment Bridges get impressions about the expected behavior of the 1799 IOTP Application Core. 1801 The IOTP Payment API assumes that the IOTP Application Core 1802 implements the dialog boxes needed for error resolution. But it does 1803 not assume, that the IOTP Payment Bridge actually relies on them. 1804 Instead, the IOTP Payment Bridge may try resolution on its own, may 1805 implement specific dialog boxes, and may signal only final failures. 1807 Note: This abstract document assumes that the API parameters are 1808 exchanged XML encoded. Therefore, several error values might 1809 disappear in lower level language specific derivations. 1811 Error Value Error Description 1812 ----------- ----------------- 1814 Reserved Reserved. This error is reserved by the 1815 vendor/developer of the software. Contact 1816 the vendor/developer of the software for 1817 more information (see the SoftwareId 1818 attribute of the Message Id element in the 1819 Transaction Reference Block [IOTP]). 1821 XmlNotWellFrmd XML not well formed. The XML document is not 1822 well formed. See [XML] for the meaning of 1823 "well formed". 1825 XmlNotValid XML not valid. The XML document is well 1826 formed but the document is not valid. See 1827 [XML] for the meaning of "valid". 1828 Specifically: 1830 o the XML document does not comply with the 1831 constraints defined in the IOTP document 1832 type declaration, and 1833 o the XML document does not comply with the 1834 constraints defined in the document type 1835 declaration of any additional [XML-NS] 1836 that are declared. 1838 The Names attribute might refer some 1839 attributes and elements of the input 1840 parameter list. 1842 (*)ElNotValid Element not valid. Invalid element in terms 1843 of prescribed syntactical characteristics. 1845 The ElementRef attributes of ErrorLocation 1846 elements might refer to the corresponding 1847 elements (if they have ID attributes). 1849 The IOTP Application Core has to replace the 1850 error code with "XmlNotValid" before 1851 transmission to the counterparty. 1853 ElUnexpected Unexpected element. Although the XML 1854 document is well formed and valid, an 1855 element is present that is not expected in 1856 the particular context according to the 1857 rules and constraints contained in this 1858 specification. 1860 The ElementRef attributes of ErrorLocation 1861 elements might refer to the corresponding 1862 elements (if they have ID attributes). 1864 ElNotSupp Element not supported. Although the document 1865 is well formed and valid, an element is 1866 present that 1868 o is consistent with the rules and 1869 constraints contained in this 1870 specification, but 1871 o is not supported by the IOTP Aware 1872 Application which is processing the IOTP 1873 Message. 1875 The ElementRef attributes of ErrorLocation 1876 elements might refer to the corresponding 1877 elements (if they have ID attributes). 1879 ElMissing Element missing. Although the document is 1880 well formed and valid, an element is missing 1881 that should have been present if the rules 1882 and constraints contained in this 1883 specification are followed. 1885 The ElementRef attributes of ErrorLocation 1886 elements might refer to the corresponding 1887 elements (if they have ID attributes). 1889 ElContIllegal Element content illegal. Although the 1890 document is well formed and valid, the 1891 element contains values which do not conform 1892 the rules and constraints contained in this 1893 specification. 1895 The ElementRef attributes of ErrorLocation 1896 elements might refer to the corresponding 1897 element (if they have ID attributes). 1899 The IOTP Application Core has to replace the 1900 Error Code with "ElNotSupp" before 1901 transmission to the counter party, if the 1902 ErrorLocation elements refer to non- 1903 PackagedContent element. 1905 EncapProtErr Encapsulated protocol error. Although the 1906 document is well formed and valid, the 1907 Packaged Content of an element contains data 1908 from an encapsulated protocol which contains 1909 errors. 1911 The ElementRef attributes of ErrorLocation 1912 elements might refer to the corresponding 1913 element (if they have ID attributes). 1915 AttUnexpected Unexpected attribute. Although the XML 1916 document is well formed and valid, the 1917 presence of the attribute is not expected in 1918 the particular context according to the 1919 rules and constraints contained in this 1920 specification. 1922 The AttName attributes of ErrorLocation 1923 elements might refer to the corresponding 1924 attribute tags. 1926 (*)AttNotValid Attribute not valid. Invalid attribute value 1927 in terms of prescribed syntactical 1928 characteristics. 1930 The AttName attributes of ErrorLocation 1931 elements might refer to the corresponding 1932 attribute tags. 1934 The IOTP Application Core has to replace the 1935 error code with "XmlNotValid" before 1936 transmission to the counter party. 1938 AttNotSupp Attribute not supported. Although the XML 1939 document is well formed and valid, and the 1940 presence of the attribute in an element is 1941 consistent with the rules and constraints 1942 contained in this specification, it is not 1943 supported by the IOTP Aware Application 1944 which is processing the IOTP Message. 1946 AttMissing Attribute missing. Although the document is 1947 well formed and valid, an attribute is 1948 missing that should have been present if the 1949 rules and constraints contained in this 1950 specification are followed. 1952 The AttName attributes of ErrorLocation 1953 elements might refer to the corresponding 1954 attribute tags. 1956 If the attribute is required by the IOTP 1957 Document Type Declaration (#REQUIRED) the 1958 hints for non-valid attributes should be 1959 adopted, otherwise these for illegal 1960 attribute values. 1962 AttValIllegal Attribute value illegal. The attribute 1963 contains a value which does not conform to 1964 the rules and constraints contained in this 1965 specification. 1967 The AttName attributes of ErrorLocation 1968 elements might refer to the corresponding 1969 attribute tags - valid values are: 1971 BrandId: illegal/unknown Brand Identifier - 1972 If the brand is not recognized/known by any 1973 IOTP Payment Bridge, the IOTP Application 1974 Core may offer the registration of a new 1975 Payment Instrument. 1977 PaymentInstrumentId: illegal/unknown 1978 Payment Instrument Identifier - This 1979 indicates a serious communication problem if 1980 the attribute value has been reported by the 1981 same "wallet" on a previous inquiry 1982 requests. The IOTP Application Core has to 1983 replace the error code with 1984 "UnknownError" before transmission to the 1985 counter party. 1987 WalletId: illegal/unknown Wallet Identifier 1988 - It is assumed that the wallet identifier 1989 is checked before the pass phrase. On 1990 invalid wallet identifiers, the IOTP 1991 Application Core may open the dialog in 1992 order to request the correct wallet 1993 identifier. In addition, any pass phrase may 1994 be supplied by the user. The dialog should 1995 indicate the respective payment brand(s). 1996 The IOTP Application Core has to replace the 1997 error code with "UnknownError" before 1998 transmission to the counter party. 2000 Passphrase: illegal/unknown Pass Phrase - 2001 The IOTP Application Core may open the 2002 dialog in order to request the correct pass 2003 phrase. If the pass phrase is wallet 2004 identifier specific the dialog should 2005 display the wallet identifier. The IOTP 2006 Application Core has to replace the error 2007 code with "TransportError" before 2008 transmission to the counter party. 2010 Action: illegal / unknown / unsupported 2011 Action 2013 PropertyTypeList: lists contains illegal / 2014 unknown / unsupported Property Types - The 2015 IOTP Application Core tries only the local 2016 resolution but does never transmit any IOTP 2017 Error Block to the counter party. 2019 CurrCode: illegal/unknown/unsupported 2020 Currency Code 2022 CurrCodeType: illegal/unknown/unsupported 2023 Currency Code Type 2025 Amount: illegal/unknown/unsupported Payment 2026 Amount 2028 PayDirection: illegal/unknown/unsupported 2029 Payment Direction 2031 ProtocolId: illegal/unknown/unsupported 2032 Protocol Identifier 2034 OkFrom: illegal/unknown/unsupported OkFrom 2035 Timestamp 2037 OkTo: illegal/unknown/unsupported OkTo 2038 Timestamp 2040 ConsumerPayId: illegal/unknown Consumer 2041 Payment Identifier 2042 PaymentHandlerPayId: illegal/unknown Payment 2043 Handler Payment Identifier 2045 PayId: illegal/unknown Payment Identifier 2047 AttValNotRecog Attribute Value Not Recognized. The 2048 attribute contains a value which the IOTP 2049 Aware Application generating the message 2050 reporting the error could not recognize. 2052 The AttName attributes of ErrorLocation 2053 elements might refer to the corresponding 2054 attribute tags 2056 MsgTooLarge Message too large. The message is too large 2057 to be processed by the IOTP Payment Bridge 2058 (or IOTP Application Core). 2060 ElTooLarge Element too large. The element is too large 2061 to be processed by the IOTP Payment Bridge 2062 (or IOTP Application Core). 2064 The ElementRef attributes of ErrorLocation 2065 elements might might refer to the 2066 corresponding elements. 2068 ValueTooSmall Value too small or early. The value of all 2069 or part of an element content or an 2070 attribute, although valid, is too small. 2072 The ErrorLocation elements might refer to 2073 the corresponding attribute tags or 2074 elements. 2076 ValueTooLarge Value too large or in the future. The value 2077 of all or part of an element content or an 2078 attribute, although valid, is too large. 2080 The ErrorLocation elements might refer to 2081 the corresponding attribute tags or 2082 elements. 2084 ElInconsistent Element Inconsistent. Although the document 2085 is well formed and valid, according to the 2086 rules and constraints contained in this 2087 specification: 2089 o the content of an element is inconsistent 2090 with the content of other elements or 2091 their attributes, or 2092 o the value of an attribute is inconsistent 2093 with the value of one or more other 2094 attributes. 2096 The Error Description may contain further 2097 explanations. 2099 The ErrorLocation elements might refer to 2100 the corresponding attribute tags or elements 2101 that are inconsistent. 2103 TransportError Transport Error. This error code is used to 2104 indicate that there is a problem with the 2105 transport mechanism that is preventing the 2106 message from being received. It is typically 2107 associated with a "Transient Error". 2109 The connection to some periphery or the 2110 counter party could not be established, 2111 is erroneous, or has been lost. 2113 The Error Description may contain further 2114 narrative explanations, e.g., "chip card 2115 does not respond", "remote account manager 2116 unreachable", "Internet connection to xyz 2117 lost", "no Internet connection available", 2118 "no modem connected", or "serial port to 2119 modem used by another application". This 2120 text should be shown to the end user. If 2121 timeout has occurred at the Consumer this 2122 text should be shown and the Consumer may 2123 decide how to proceed - alternatives are 2124 retry, payment transaction suspension, and 2125 cancellation. 2127 MsgBeingProc Message Being Processed. This error code is 2128 only used with a Severity of Transient 2129 Error. It indicates that the previous 2130 message, which may be an exchange message or 2131 a request message, is being processed and, 2132 if no response is received by the time 2133 indicated by the "MinRetrySecs" attribute, 2134 then the original message should be resent. 2136 SystemBusy System Busy. This error code is only used 2137 with a Severity of Transient Error. It 2138 indicates that the IOTP Payment Bridge or 2139 Existing Payment Software that received the 2140 API request is currently too busy to handle 2141 it. If no response is received by the time 2142 indicated by the "MinRetrySecs" attribute, 2143 then the original message should be resent. 2145 The Error Description may provide further 2146 explanations, e.g., "wallet / chip card 2147 reader is unavailable or locked by another 2148 payment transaction", "payment gateway is 2149 overloaded", "unknown chip card reader", or 2150 "unrecognized chip card inserted, change 2151 chip card". 2153 The Consumer's IOTP Application Core may 2154 display the error description and ask the 2155 Consumer about the continuation - 2156 alternatives are retry, payment transaction 2157 suspension, and cancellation. 2159 UnknownError Unknown Error. Indicates that the 2160 transaction cannot complete for some reason 2161 that is not covered explicitly by any of the 2162 other errors. The Error description 2163 attribute should be used to indicate the 2164 nature of the problem. 2166 The ErrorLocation elements might refer to 2167 the corresponding attribute tags or elements 2168 that are inconsistent. 2170 (*)SyntaxError Syntax Error. An (unknown) syntax error has 2171 occurred. 2173 The ErrorLocation elements might refer to 2174 the corresponding attribute tags or elements 2175 that are inconsistent. 2177 The IOTP Application Core has to replace the 2178 error code with "XmlNotValid" or 2179 "UnknownError" before transmission to the 2180 counter party. 2182 (*)ReqRefused Request refused. The API request is 2183 (currently) refused by the IOTP Payment 2184 Bridge. The error description may provide 2185 further explanations, e.g., "wallet / chip 2186 card reader is unavailable or locked by 2187 another payment transaction", "payment 2188 gateway is overloaded", "unknown chip card 2189 reader", or "unrecognized chip card 2190 inserted, change chip card". 2192 The Consumer's IOTP Application Core may 2193 display the error description and ask the 2194 Consumer about the continuation - 2195 alternatives are retry, payment transaction 2196 suspension, and cancellation. Denials due to 2197 invalid Process States should be signaled by 2198 "BusinessError". Typically, this kind of 2199 error is not passed to the counter party's 2200 IOTP Application Core. Otherwise, it maps to 2201 "TransportError" or "UnknownError". 2203 (*)ReqNotSupp Request not supported. The API 2204 function(ality) has not been implemented in 2205 the IOTP Payment Bridge. Typically, this 2206 kind of error is not passed to the 2207 counter party's IOTP Application Core. 2208 Otherwise, it maps to "TransportError" or 2209 "UnknownError". 2211 (*)BusError Business Error. The API request has been 2212 rejected because some payment transaction 2213 has an illegal payment status. 2214 Particularly, this error code is used to 2215 signal any raise of payment business layered 2216 failures. 2218 The ErrorLocation elements may refer to 2219 payment transactions using the party's 2220 Payment Identifier - it defaults to the 2221 current transaction or might contain the 2222 current payment transaction party's Payment 2223 Identifier - identified by the ElementRef 2224 attribute while the AttName attribute is 2225 fixed with "PayId". 2227 The IOTP Application Core must inquire the 2228 IOTP Payment Bridge about the actual Process 2229 State which actually encodes the business 2230 error ("Inquire Process State"). 2231 This error code must not be 2232 passed to the counter party's IOTP 2233 Application Core. 2235 Table 2: Common Error Codes 2237 The IOTP Payment Bridge may also use the error description in order 2238 to notify the Consumer about further necessary steps for failure 2239 resolution, e.g., "sorry, your payment transaction failed. 2240 Unfortunately, you have been charged, please contact your issuer." 2242 3.2 Attributes and Elements 2244 The following table explains the XML attributes in alphabetical order 2245 - any parenthesized number after the attribute tag is a recommended 2246 maximal length of the attribute value in characters: 2248 Attribute Description 2249 --------- ----------- 2251 Amount (11) Indicates the payment amount to be paid in 2252 AmountFrom(11) whole and fractional units of the currency. 2253 AmountTo (11) For example $245.35 would be expressed 2254 "245.35". Note that values smaller than the 2255 smallest denomination are allowed. For 2256 example one tenth of a cent would be 2257 "0.001". 2259 AuthenticationId An identifier specified by the 2260 authenticator which, if returned by the 2261 organization that receives the 2262 authentication request, will enable the 2263 authenticator to identify which 2264 authentication is being referred to. 2266 BrandId (128) This contains a unique identifier for the 2267 brand (or promotional brand). It is used to 2268 match against a list of Payment Instruments 2269 which the Consumer holds to determine 2270 whether or not the Consumer can pay with the 2271 Brand. 2273 Values of BrandId are managed under 2274 procedure being described in the IOTP 2275 protocol specification. 2277 BrandLogoNetLocn The net location which can be used to 2278 download the logo for the organization (cf. 2279 IOTP Specification). 2281 The content of this attribute must conform 2282 to [URL]. 2284 BrandName This contains the name of the brand, for 2285 example "MasterCard Credit". This is the 2286 description of the Brand which is displayed 2287 to the consumer in the Consumer's language 2288 defined by "xml:lang". For example it might 2289 be "American Airlines Advantage Visa". Note 2290 that this attribute is not used for matching 2291 against the payment instruments held by the 2292 Consumer. 2294 BrandNarrative This optional attribute is 2295 used by the Merchant to indicate some 2296 special conditions or benefit which would 2297 apply if the Consumer selected that brand. 2298 For example "5% discount", "free shipping 2299 and handling", "free breakage insurance for 2300 1 year", "double air miles apply", etc. 2302 CallBackFunction A function which is called whenever there is 2303 a change of Process State or payment 2304 progress, e.g. for display updates. However, 2305 the IOTP Payment Bridge may use its own 2306 mechanisms and dialog boxes. 2308 CallBackLanguageLis A list of language codes which contain, in 2309 t order of preference, the languages in which 2310 the text passed to the Call Back function 2311 will be encoded. 2313 CompletionCode (14) Indicates how the process completed. 2314 It is required if ProcessState is set to 2315 "Failed" otherwise it is ignored. Valid 2316 values as well as recovery options are given 2317 in the IOTP specification. 2319 The IOTP Payment Bridge may also use the 2320 Status Description to notify the Consumer 2321 about further necessary steps in order to 2322 resolve some kind of business failures, 2323 e.g., 2325 o "sorry, your payment transaction failed. 2326 Unfortunately, you have been charged, 2327 please contact your issuer." 2328 o "insufficient capacity left (on your stored 2329 value card) for refund", 2330 o "payment failed/chip card error/internal 2331 error, please contact your payment 2332 instrument's issuer" 2334 ConsumerDesc A narrative description of the Consumer. 2336 ConsumerPayId (14) An unique identifier specified by the 2337 Consumer that, if returned by the Payment 2338 Handler in another Payment Scheme Component 2339 or by other means, enables the Consumer to 2340 identify which payment is being referred to. 2342 This unique identifier is generated by the 2343 IOTP Application Core and submitted to the 2344 IOTP Payment Bridge on every API call. It 2345 may equal the Payment Handler Payment 2346 Identifiers but need not necessarily be so. 2348 The uniqueness extends to multiple payment 2349 instruments, payment brands, payment 2350 protocols, wallet identifiers, and even 2351 multiple IOTP Payment Bridges. 2353 ContStatus During payment progress, this status value 2354 indicates whether the payment needs to be 2355 continued with further IOTP Payment Scheme 2356 Component exchanges with the remote party. 2357 "End" indicates that the reported payment 2358 scheme data is the last data to be exchanged 2359 with the counter party. 2361 ContentSoftwareId This contains information that identifies 2362 the software that generated the content of 2363 the element. Its purpose is to help resolve 2364 interoperability problems that might occur 2365 as a result of incompatibilities between 2366 messages produced by different software. It 2367 is a single text string in the language 2368 defined by xml:lang. It must contain, as a 2369 minimum: 2371 o the name of the software manufacturer, 2372 o the name of the software, 2373 o the version of the software, and 2374 o the build of the software. 2376 CurrCodeType (14) Indicates the domain of the CurrCode. This 2377 attribute is included so that the currency 2378 code may support nonstandard currencies 2379 such as frequent flyer point, trading 2380 stamps, etc. Its values may be 2382 o ISO-4217-A, the default, indicates the 2383 currency code is the three-letter 2384 alphabetic code that conform to ISO 4217 2386 o IOTP indicates that the values of 2387 CurrCode are managed under the procedure 2388 described in [IOTP]. 2390 CurrCode (14) A code which identifies the currency to be 2391 used in the payment. The domain of valid 2392 currency codes is defined by "CurrCodeType" 2394 MerchantPayId (14) An private identifier specified by the 2395 Merchant which will enable the Merchant to 2396 identify which payment is being referred to. 2397 It is a pure private item and is never sent 2398 to any other party. It is provided by the 2399 IOTP Payment Bridge on payment preparation 2400 during brand compilation. 2402 Cf. To "ConsumerPayId" for note about 2403 uniqueness. 2405 MerchantOrgId (64) A local item that might refer to some 2406 specific shop in a multi shop environment. 2407 This item is optional and might enrich the 2408 Wallet Identifier which itself can be used 2409 for the same purpose. 2411 Name Distinguishes between multiple occurrences 2412 of Packaged Content Elements at the same 2413 point in IOTP. For example: 2415 2416 2417 snroasdfnas934k 2418 2419 2420 dvdsjnl5poidsdsflkjnw45 2421 2422 2424 The "Name" attribute may be omitted, for 2425 example if there is only one Packaged 2426 Content element. 2428 OkFrom (30) The date and time in UTC Format range 2429 OkTo (30) indicated by the merchant in which the 2430 Payment Handler may accept the payment. 2432 Passphrase (32) Payment wallets may use pass phrase 2433 protection for transaction data and payment 2434 instruments' data. However, it is assumed 2435 that there exists a public and customizable 2436 payment instrument identifier such that 2437 these identifiers together with their 2438 relationship to payment brands, payment 2439 protocols, payment directions, and currency 2440 amounts can be queried by the IOTP 2441 application without any pass phrase 2442 knowledge. 2444 PayDirection Indicates the direction in which the 2445 payment for which a Brand is being selected 2446 is to be made. Its values may be: 2448 o Debit: The sender of the Payment Request 2449 Block (e.g. the Consumer) to which this 2450 Brand List relates will make the payment 2451 to the Payment Handler, or 2452 o Credit: The sender of the Payment Request 2453 Block to which this Brand List relates 2454 will receive a payment from the Payment 2455 Handler. 2457 PayId (14) This attribute is introduced for API 2458 simplification: 2460 o The Consumer has to identify PayId and 2461 ConsumerPayId. 2463 o The Merchant has to identify PayId and 2464 MerchantPayId. 2466 o The Payment Handler has to identify PayId 2467 and Payment Handler Pay Id. 2469 PayInstId This contains the unique identifier used 2470 internally by the IOTP Payment 2471 Bridge/Existing Payment Software. 2473 PayInstName This contains the user-defined name of the 2474 payment instrument. There exist no 2475 (technical) constraints like uniqueness. The 2476 "xml:lang" attribute denotes the language 2477 encoding of its value. 2479 PaymentHandlerDesc A narrative description of the Payment 2480 Handler. 2482 PaymentHandlerPayId An unique identifier specified by the 2483 (14) Payment Handler that, if returned by the 2484 Consumer in another Payment Scheme Component 2485 or by other means, enables the Payment 2486 Handler to identify which payment is being 2487 referred to. It is required whenever it is 2488 known. 2490 Cf. To "ConsumerPayId" for note about 2491 uniqueness. 2493 PaymentInstrumentId An identifier for a specific payment 2494 (32) instrument, e.g. "credit card", "Mondex card 2495 for English Pounds". This identifier is 2496 fully customizable. It is assumed, that it 2497 does not contain confidential information or 2498 even an indication of it. The payment 2499 instrument identifier is unique within each 2500 payment brand. It is displayed to the 2501 Consumer during brand selection. 2503 PayReceiptNameRefs Optionally contains element references to 2504 (32) other elements (containing payment scheme 2505 specific data) that together make up the 2506 receipt. Note that each payment scheme 2507 defines in its supplement the elements that 2508 must be referenced 2510 The IOTP Application Core should save all 2511 the components referenced so that the 2512 payment receipt can be reconstructed when 2513 required. 2515 PayReqNetLocn The Net Location indicating where an 2516 unsecured Payment Request message should be 2517 sent if this protocol choice is used. 2519 The content of this attribute must conform 2520 to [URL] and depends on the Transport 2521 Mechanism. 2523 PercentComplete (3) A number between 0 and 100 which indicates 2524 the progress of the payment transaction. The 2525 values range between 0 and 99 for pending 2526 and suspended transactions. 2528 ProcessState Contains a Process State Code that 2529 indicates the current state of the process 2530 being carried out. Valid values are: 2532 o NotYetStarted. The Payment Request Block 2533 has been received but processing of the 2534 Payment Request has not yet started 2536 o InProgress. The payment transaction is 2537 pending. The processing of the (Payment) 2538 Request Block has started but it is not 2539 yet complete. 2541 o (*)Suspended: The payment transaction has 2542 been suspended and can be resumed. 2544 This process state is mapped to 2545 "InProgress", if it is passed to the 2546 counter party's IOTP Application Core. 2548 o CompletedOk. The processing of the (Payment) 2549 Request Block and any following Payment 2550 Exchange Blocks has completed successfully. 2552 o Failed. The payment processing has finally 2553 failed for a Business Error. 2555 o ProcessError. This value is only used 2556 when the Status Component is being used in 2557 connection with an Inquiry Request Trading 2558 Block. It indicates there was a Technical 2559 Error in the Request Block which is being 2560 processed or some internal processing 2561 error. Each party's IOTP Payment Bridge 2562 uses this value in order to notify the 2563 IOTP Application Core about the presence 2564 of technical errors. 2566 PropertyType (14) The property type defines codes used for 2567 interrogation of specific properties about a 2568 payment instrument. They are unique for each 2569 payment brand. The predefined property "all" 2570 is used on general inquiries. However, these 2571 property types are not used during normal 2572 payment processing. E.g., they may apply to 2573 payment brand specific transactions or out- 2574 of-band failure resolution. 2576 PropertyDesc The property description carries the 2577 respective human readable property (value)'s 2578 description. 2580 PropertyValue The actual property value intends automatic 2581 post processing. 2583 ProtocolBrandId (64)This is an identifier to be used with a 2584 particular payment protocol. For example, 2585 SET and EMV have their own well defined, yet 2586 different, values for the Brand identifier 2587 to be used with each protocol. The valid values 2588 of this attribute are defined in the 2589 supplement for the payment protocol 2590 identified by "ProtocolId" that describes 2591 how the payment protocol works with IOTP. 2592 Identifier maps to at most one Protocol 2593 Brand Identifier. 2595 ProtocolId (64) An identifier for a specific payment 2596 protocol and version, e.g. "SETv1.0", 2597 "ecash". Valid values are defined by 2598 supplements to the IOTP specification and 2599 they are unique within each payment brand. 2601 ProtocolIds A sequence of Protocol Identifiers 2603 ProtocolName A narrative description of the payment 2604 protocol and its version in the language 2605 identified by "xml:lang". For example 2606 "Secure Electronic Transaction Version 1.0". 2607 Its purpose is to help provide information 2608 on the payment protocol being used if 2609 problems arise. 2611 SecPayReqNetLocn The Net Location indicating where a secured 2612 Payment Request message should be sent if 2613 this protocol choice is used. 2615 A secured payment involves the use of a 2616 secure channel such as [TLS] in order 2617 to communicate with the Payment Handler. 2619 The content of this attribute must conform 2620 to [URL]. 2622 ReceiverOrgId The Organization Identification which 2623 receives the payment bridge processing 2624 Trading Role Data PackagedContent. 2626 StatusDesc (256) An optional textual description of the 2627 current process state in the language 2628 identified by "xml:lang" that should be 2629 displayed to the Consumer. The usage of this 2630 attribute is defined in the payment 2631 supplement for the payment method being 2632 used. Particularly, it provides hints for 2633 out-of-band failure resolution. Its length 2634 is limited to 256 characters. 2636 StyleSheetNetLocn This contains the net location to a style 2637 sheet with visualisation rules for XML 2638 encoded data. 2640 TimeStamp (30) The date and time in UTC Format when the 2641 payment transaction has been started. 2643 WalletId (32) Many existing payment wallet software are 2644 multiple wallet capable. The Wallet 2645 Identifier selects the actual wallet. It is 2646 assumed, that the wallet identifier is a 2647 public item, that might be stored by the 2648 IOTP Application Core. 2650 xml:lang Defines the language used by the Process 2651 State Description attribute (cf. IOTP 2652 Specification) 2654 Table 3: Attributes 2656 The following table explains the XML elements in alphabetical 2657 order: 2659 Element Description 2660 ------- ----------- 2662 Algorithm This contains information which describes 2663 an Algorithm that may be used to generate 2664 the Authentication response. 2666 The algorithm that may be used is 2667 identified by the Name attribute (cf. IOTP 2668 Specification). 2670 AuthReqPackagedContent The Authentication Request Packaged 2671 Content originates from a Authentication 2672 (Data/Response) Component's content 2673 whereby the outermost element tags are 2674 prefixed with "AuthReq". Its declaration 2675 coincides with the Packaged Content's 2676 declaration (cf. IOTP Specification). It 2677 encapsulates the authentication challenge 2678 value. The content of this information is 2679 defined in the supplement for a payment 2680 protocol. 2682 AuthResPackagedContent The Authentication Response Packaged 2683 Content originates from a Authentication 2684 Response Component's content whereby the 2685 outermost element tags are prefixed with 2686 "AuthRes". 2688 Its declaration coincides with the 2689 Packaged Content's declaration (cf. IOTP 2690 Specification). It encapsulates the 2691 authentication response value. The 2692 content of this information is defined in 2693 the supplement for a payment protocol. 2695 BrandPackagedContent Container for further payment brand 2696 description. Its content originates from 2697 a Brand Element content whose outermost 2698 element tags are prefixed with "Brand". 2699 Its declaration coincides with the 2700 Packaged Content's declaration (cf. IOTP 2701 Specification). 2703 BrandSelBrandInfoPackagedContent 2704 This contains any additional data that 2705 may be required by a particular payment 2706 brand. It forms the content of the Brand 2707 Selection Brand Info Element. 2709 BrandSelProtocolAmountInfoPackagedContent 2710 This contains any additional data that 2711 may be required by a particular payment 2712 brand in the format. It forms the content 2713 of the Brand Selection Protocol Amount 2714 Info Element. 2716 BrandSelCurrencyAmountInfoPackagedContent 2717 This contains any additional data that is 2718 payment brand and currency specific in 2719 the format. It forms the content of the 2720 Brand Selection Currency Amount Info 2721 Element. 2723 MerchantData Any merchant related data that might be 2724 used by the IOTP Payment Bridge for 2725 different purposes, e.g., it might 2726 contain access keys to some mall keys. 2727 Its declaration coincides with the 2728 Packaged Content's declaration (cf. IOTP 2729 Specification). 2731 PackagedContent Generic Container for non-IOTP data (cf. 2732 IOTP Specification). 2734 PayProtocolPackagedContent 2735 The Pay Protocol Packaged Content 2736 originates from a Pay Protocol 2737 Element's content whereby the outermost 2738 element tags are prefixed with 2739 "PayProtocol". It contains information 2740 about the protocol which is used by 2741 the payment protocol. The content of 2742 this information is defined in the 2743 supplement for a payment protocol.Its 2744 declaration coincides with the Packaged 2745 Content's declaration (cf. IOTP 2746 Specification). 2748 PaySchemePackagedContent 2749 The PayScheme Packaged Content originates 2750 from a Payment Scheme Component's content 2751 whereby the outermost element tags are 2752 prefixed with "PayScheme". Its 2753 declaration coincides with the Packaged 2754 Content's declaration (cf. IOTP 2755 Specification). It carries the payment 2756 specific data. The content of this 2757 information is defined in the supplement 2758 for a payment protocol. 2760 ProtocolAmountPackagedContent 2761 The Protocol Amount Packaged Content 2762 originates from a Protocol Amount 2763 Element's content whereby the outermost 2764 element tags are prefixed with "Amount". 2765 Its declaration coincides with the 2766 Packaged Content's declaration (cf. IOTP 2767 Specification). It contains information 2768 about the protocol which is used by the 2769 payment protocol. The content of this 2770 information is defined in the supplement 2771 for a payment protocol. 2773 ProtocolBrandPackagedContent 2774 The Protocol Brand Packaged Content 2775 originates from a Protocol Brand 2776 Element's content whereby the outermost 2777 element tags are prefixed with 2778 "ProtocolBrand". Its declaration 2779 coincides with the Packaged Content's 2780 declaration (cf. IOTP Specification). It 2781 contains information about the brand 2782 which might be used by the payment 2783 protocol. The content of this information 2784 is defined in the supplement for a 2785 payment protocol. 2787 ResponsePackagedContent 2788 Container for authentication response 2789 data. Its content originates from a 2790 Authentication Response Component's 2791 Packaged Content whose outermost element 2792 tags are prefixed with "Response". Its 2793 declaration coincides with the Packaged 2794 Content's declaration (cf. IOTP 2795 Specification). 2797 TradingRoleDataPackagedContent 2798 The TradingRoleData Packaged Content 2799 originates from a TradingRoleData 2800 Component's content whereby the outermost 2801 element tags are prefixed with 2802 "TradingRoleData". Its declaration 2803 coincides with the Packaged Content's 2804 declaration (cf. IOTP Specification). It 2805 contains information from Merchant to 2806 Payment Handler via Consumer about the 2807 protocol which is used by the payment. 2808 The content of this information is 2809 defined in the supplement for a payment 2810 protocol. The Name attribute in this 2811 packaged contents must include prefix as 2812 "Payment:" to indicate that the payment 2813 bridge processes this, for example 2814 "Payment:SET-OD" 2816 The element's declaration coincides with 2817 the Packaged Content's declaration (cf. 2818 IOTP Specification). 2820 Table 4: Elements 2822 XML definition: 2824 2825 2827 2828 2829 2831 2833 2835 2836 2837 2838 2840 3.3 Process States 2842 The IOTP Payment API supports six different attribute values that 2843 encode the transaction status from the IOTP's point of view, i.e. the 2844 appropriate point of view at the interface between the IOTP 2845 Application Core and IOTP Payment Bridge. This point of view does not 2846 completely mimic the more detailed view on the actual payment by the 2847 actual Existing Payment Software or IOTP Payment Bridge. 2849 The following three tables distinguish between the Merchant's, 2850 Consumer's, and Payment Handlers' environment. They extend the 2851 aforementioned explanations towards the mapping between IOTP process 2852 states and the internal payment scheme related states of the Existing 2853 Payment Software/IOTP Payment Bridge. 2855 3.3.1 Merchant 2857 The Merchant's point of view of payment is limited to the local 2858 payment initiation being interlaced with order processing because 2859 IOTP assigns the actual payment processing to the Payment Handler. 2861 ProcessState Description 2862 ------------ ----------- 2864 NotYetStarted The Payment Transaction exists within the 2865 IOTP Application Core, i.e., the 2866 Merchant's shop has already signaled to 2867 the IOTP Application Core that an IOTP 2868 transaction has been initiated by the 2869 Consumer. 2871 However, neither any API call has been 2872 issued to the IOTP Payment Bridge nor has 2873 the IOTP Order Request has been created. 2875 InProgress The IOTP Application changes the process 2876 state to this value when it issues the 2877 first API call to the Payment Bridge 2878 during Brand List compilation. 2880 This value indicates that the Payment 2881 Bridge might have some knowledge about 2882 the expected payment or might have 2883 performed some preparatory tasks (even 2884 with the Payment Handler out-of-band to 2885 IOTP). 2887 However, this value does not indicate 2888 that any IOTP Order Request has been 2889 created and transmitted to the Consumer. 2891 Suspended The IOTP transaction has been suspended 2892 before the order request block has been 2893 transmitted to the Consumer. 2895 Implicitly, the payment is also deferred. 2897 CompletedOk The IOTP Order Request has been 2898 successfully created and transmitted to 2899 the Consumer. Actually, this process 2900 state indicates only that the order 2901 processing has been finished. 2903 But it contains no indication about the 2904 status of the actual payment, which is 2905 accepted by the Payment Handler. 2907 However, successful order processing 2908 signals the IOTP Application Core that a 2909 payment with some specific parameters is 2910 expected within the near future. And this 2911 signal might be used by the Existing 2912 Payment Software for similar purposes. 2913 This attribute might be interpreted as 2914 successful preparation of the payment 2915 system. 2917 Particularly, it is expected that the 2918 Existing Payment Software maps this IOTP 2919 status value to some other internal 2920 value, e.g. "NotYetStarted", that is more 2921 accurate from its point of view. 2923 As IOTP provides no communication channel 2924 between the Merchant and Payment Handler, 2925 any change of payment process state will 2926 be initiated out-of-band to IOTP, e.g. by 2927 electronic statements of account or 2928 payment scheme specific mechanisms. 2930 Failed The IOTP transaction, i.e. order 2931 processing, has failed for some 2932 (business) reason and it is known that no 2933 payment will occur. 2935 This indication might be used to clear 2936 all data about this transaction within 2937 the Existing Payment Bridge (by 2938 "RemovePaymentLog" or 2939 "ChangeProcessState") or to reverse any 2940 preparation (with the Payment Handler 2941 out-of-band to IOTP). 2943 However, the ideal point of view of IOTP 2944 suspects that the actual payment 2945 transaction has been neither started nor 2946 initiated. 2948 ProcessError The IOTP transaction, i.e. order 2949 processing, has failed for some 2950 (technical) reason and it is known that 2951 no payment will occur. 2953 This indication might be used to clear 2954 all data about this transaction within 2955 the Existing Payment Bridge (by 2956 "RemovePaymentLog" or 2957 "ChangeProcessState") or to reverse any 2958 preparation (with the Payment Handler 2959 out-of-band to IOTP). 2961 However, the ideal point of view of IOTP 2962 suspects that the actual payment 2963 transaction has been neither started nor 2964 initiated. 2965 Table 5: Merchant 2967 3.3.2 Consumer 2969 The Consumer's IOTP Application Core restricts its point of view to 2970 the payment transaction. It is assumed that the IOTP Payment Bridge 2971 handles the preceding brand selection process in a stateless manner. 2973 ProcessState Description 2974 ------------ ----------- 2976 NotYetStarted This encodes the initial process state of 2977 any IOTP payment transaction. This value 2978 is set during brand selection but it 2979 normally will not change during the whole brand 2980 selection process. 2982 InProgress With the issuance of the Start Payment 2983 Consumer API call, the IOTP Application 2984 Core changes the process state to this 2985 value. 2987 Suspended The payment transaction has been 2988 suspended. Suspension may occur anywhere 2989 during brand selection (with the 2990 Merchant) or payment processing (with the 2991 Payment Handler). On resumption, the IOTP 2992 Application Core and the IOTP Payment 2993 Bridge have to use other internal data to 2994 decide whether brand selection or actual 2995 payment processing needs to be continued, 2996 i.e., whether the process state needs to 2997 be reset to "NotYetStarted" or 2998 "InProgress". 3000 Note that the Payment API assumes 3001 stateless brand selection by the IOTP 3002 Payment Bridge. Typically, any suspension 3003 during brand selection requires the 3004 repetition of the whole process. Hereby, 3005 the IOTP Application Core might need to 3006 consider any already negotiated 3007 conditions in a brand depended purchase 3008 (brand, protocol). 3010 CompletedOk The successful payment has been 3011 acknowledged by the Payment Handler, i.e. 3012 the successful IOTP Payment Response has 3013 been received. 3015 Implicitly, this implies successful order 3016 processing. 3018 Failed The IOTP transaction, i.e. order or 3019 payment processing, has failed for some 3020 (business) reason. In either case it is 3021 known that the payment will not succeed. 3023 ProcessError The IOTP transaction, i.e. order or 3024 payment processing, has failed for some 3025 (technical) reason. 3027 However, the local process state might be 3028 different from that of Payment Handler. 3030 Table 6: Consumer 3032 3.3.3 Payment Handler 3034 The Payment Handler is responsible for the actual payment processing. 3035 New payment transactions are reported by the Consumer with the 3036 transmission of new IOTP Payment Request Blocks. IOTP Payment 3037 Exchange Block are send by the Consumer for payment transaction 3038 continuation and resumption. 3040 ProcessState Description 3041 ------------ ----------- 3043 NotYetStarted This encodes the initial process state of 3044 any payment transaction. Typically, this 3045 value will last for a short amount of 3046 time. 3048 InProgress The IOTP Application Core changes the 3049 process state changes to "InProgress" 3050 when the Payment Handler starts with the 3051 actual processing of the IOTP Payment 3052 Request Block. 3054 Note that this does not assume that the 3055 "StartPaymentPaymentHandler" API function 3056 has been called. 3058 Suspended The payment transaction has been 3059 suspended. 3061 CompletedOk The payment has been processed, 3062 successfully, i.e. the IOTP Payment 3063 Response Block was created and 3064 transmitted to the Consumer. 3066 Failed The payment transaction, has finally 3067 failed for some (business) reason. 3069 Note that this value encodes the payment 3070 state reported by the IOTP Payment Bridge 3071 on "InquireProcessState". It neither 3072 reflects whether the payment receipt has 3073 been inquired nor whether the IOTP 3074 Payment Response Block has been created 3075 and submitted to the Consumer. 3077 ProcessError The payment transaction, has finally 3078 failed for some (technical) reason. 3080 Note that this value encodes the payment 3081 state reported by the IOTP Payment 3082 Bridge. It does not reflect whether some 3083 IOTP Error Block has been created and 3084 submitted to the Consumer. 3086 Table 7: Consumer 3088 4. Payment API Calls 3090 4.1 Brand Compilation Related API Calls 3092 4.1.1 Find Accepted Payment Brand 3094 This API function determines the payment brands being accepted by the 3095 Payment Handler on behalf of the Merchant. 3097 Input Parameters 3099 o Payment Direction - provided by the IOTP Application Core 3100 o Currency Code and Currency - provided by the IOTP Application 3101 Core 3102 o Payment Amount - provided by the IOTP Application Core 3103 o Merchant Payment Identifier - Merchant's unique private 3104 reference to the payment transaction 3105 o Merchant Organisation Identifier - used for distinction between 3106 multiple merchants that share the some IOTP merchant system 3107 o Wallet Identifier - managed by the IOTP Application Core 3108 o Merchant Data - specific data used by the IOTP Payment Bridge 3109 which is managed in the IOTP Application Core. 3111 XML definition: 3113 3114 3123 Output Parameters 3125 o Payment Brand Identifier - for insertion in the Brand List 3126 Component's Brand Element 3127 o Payment Brand Name and language annotation - for insertion in 3128 the Brand List Component's Brand Element 3129 o Payment Brand Logo Net Location - for insertion in the Brand 3130 List Component's Brand Element 3131 o Payment Brand Narrative Description - for insertion in the 3132 Brand List Component's Brand Element 3133 o (Brand) Packaged Content - further payment brand description 3134 for insertion in the Brand List Component's Brand Element 3136 The Existing Payment Software returns an empty list of brand items, 3137 if it does not support any payment brand/payment protocol combination 3138 for the given payment parameters. 3140 XML definition: 3142 3143 3144 3151 Tables 4 and 5 explain the attributes and elements; Table 3 3152 introduces the Error Codes. 3154 4.1.2 Find Accepted Payment Protocol 3156 This API function determines the instances of payment protocols (and 3157 optionally the payment brands) being accepted by the Payment Handler 3158 on behalf of the Merchant. The function might be called in two 3159 variants: 3161 o With the Brand Identifier set on the input parameter list: The 3162 function responds with the payment protocols that fits to the 3163 submitted brand. 3165 o Without any Brand Identifier - that allows the omission of the 3166 "Find Accepted Payment Brand" API call (cf. Section 4.1.1): This 3167 function responds with both the supported brand identifiers and the 3168 payment protocols being specified by the Brand Elements. 3170 Input Parameters 3172 o Brand Identifier - returned by "Find Accepted Payment Brand" 3173 o Payment Direction 3174 o Currency Code and Currency 3175 o Payment Amount 3176 o Merchant Payment Identifier - Merchant's unique private 3177 reference to the payment transaction 3178 o Merchant Organisation Identifier - used for distinction between 3179 multiple merchants that share the some IOTP merchant system 3180 o Wallet Identifier - managed by the IOTP Application Core 3181 o (Brand) Packaged Content - further payment brand description; 3182 returned by "Find Accepted Payment Brand"; this elements are 3183 only provided iff the Brand Identifier is set 3184 o Merchant Data - specific data used by the IOTP Payment Bridge 3185 which is managed in the IOTP Application Core. 3187 XML definition: 3189 3191 3201 Output Parameters 3203 o Payment Protocol Identifier - for insertion in the Brand List 3204 Component's Pay Protocol Element 3205 o Protocol Brand Identifier - for insertion in the Protocol Brand 3206 Element of the Brand List Component's Brand Element 3207 o Payment Protocol Name and language annotation- for insertion in 3208 the Brand List Component's Pay Protocol Element 3209 o Payment Request Net Location - for insertion in the Brand List 3210 Component's Pay Protocol Element 3211 o Secured Payment Request Net Location - for insertion in the 3212 Brand List Component's Pay Protocol Element 3213 o Brand Item List (cf. Section 4.1.1) - there must be at least 3214 one element if no brand identifier has been provided on the 3215 input parameter list. 3216 o (Protocol Amount) Packaged Content - for insertion in the Brand 3217 List Component's Protocol Amount Element 3218 o (Pay Protocol) Packaged Content - for insertion in the Brand 3219 List Component's Pay Protocol Element 3221 o Currency Amount element - quite similar to the definition in 3222 [IOTP], that contain 3223 - refined Currency Code and Currency - for insertion in the 3224 Brand List Component's Currency Amount Element 3225 - refined Payment Amount - for insertion in the Brand List 3226 Component's Currency Amount Element 3227 o Brand - there must be at least one element in each Protocol 3228 Item if no brand identifier has been provided on the input 3229 parameter list. 3231 XML definition: 3233 3235 3238 3246 3247 3250 3251 3256 Tables 4 and 5 explain the attributes and elements; Table 3 3257 introduces the Error Codes. 3259 4.1.3 Get Payment Initialization Data 3261 This API function provides the remaining initialization data being 3262 required by the Consumer's or Payment Handler's Existing Payment 3263 Software. This function might be called both for "brand dependent" 3264 and "brand independent" transaction types. In ether case, this 3265 function is called with one particular brand. 3267 Input Parameters 3269 o Brand Identifier - returned by "Find Accepted Payment Brand" 3270 o Merchant Payment Identifier - Merchant's unique private 3271 reference to the payment transaction 3272 o Payment Direction 3273 o Currency Code and Currency - from the Brand List Component's 3274 Currency Amount Element 3275 o Payment Amount - from the Brand List Component's Currency 3276 Amount Element 3277 o Payment Protocol Identifier - from the Brand List Component's 3278 Pay Protocol Element 3279 o Protocol Brand Identifier - from the Protocol Brand Element 3280 which relates to the selected Brand Element, if any 3281 o (TradingRoleData) Receiver Organization Identifier 3282 o OkFrom, OkTo - identical to the entries of the Order Component 3284 Merchant Payment Identifier 3286 o Merchant Organisation Identifier - used for distinction between 3287 multiple merchants that share the some IOTP merchant system 3288 o Wallet Identifier and/or Pass Phrase 3290 Protocol Brand Element 3292 o (Brand) Packaged Content - further payment brand description, 3293 from the Brand List Component's Brand Element 3294 o (Protocol Amount) Packaged Content - further payment protocol 3295 description, from the Brand List Component's Protocol Amount 3296 Element 3297 o (Pay Protocol) Packaged Content - further payment protocol 3298 description, from the Brand List Component's Pay Protocol 3299 Element 3300 o (Protocol Brand) Packaged Content - further brand information, 3301 from the Protocol Brand Element of the Brand List Component 3302 which relates to the selected Brand Element, if any 3303 o (Order) Packaged Content - further order description, from the 3304 Order Element 3305 o three Brand Selection Info Packaged Content elements - copied 3306 from the Brand Selection Component on brand dependent purchases 3307 o Brand - additional data about the payment brand 3308 o Protocol Amount - additional data about the payment protocol 3309 o Currency Amount - additional payment brand and currency 3310 specific data 3311 o Merchant Data - specific data used by the IOTP Payment Bridge 3312 which is managed in the IOTP Application Core. 3314 XML definition: 3316 3325 3340 Output Parameters 3342 o OkFrom, OkTo - for insertion in the Payment Component 3343 o (TradingRoleData) Packaged Content - further payment protocol 3344 description; the Name Attribute of the packaged Content 3345 element must include "Payment:" as the prefix, 3346 for example "Payment:SET-OD". 3347 o (Order) Packaged Content - defaults to the supplied order 3348 packaged content if omitted. 3350 XML definition: 3352 3355 3359 Tables 4 and 5 explain the attributes and elements; Table 3 3360 introduces the Error Codes. 3362 4.1.4 Inquire Authentication Challenge 3364 This API function inquires any payment protocol specific 3365 authentication challenge value from the IOTP Payment Bridge. In 3366 Baseline IOTP this API function is called by the Merchant (or 3367 Financial Institution). The IOTP Application Core may propose a 3368 choice of algorithms to the IOTP Payment Bridge. However, the IOTP 3369 Payment Bridge may ignore the proposal and select some other 3370 algorithm. 3372 The inquiry is assumed to be stateless. E.g., the IOTP Application 3373 Core may check the returned algorithm and stop transaction processing 3374 without notifying the IOTP Payment Bridge. 3376 The IOTP Application Core may issue several API calls to the IOTP 3377 Payment Bridge to build up the IOTP Authentication Request Block. Any 3378 subsequently submitted choice of algorithms should be constrained by 3379 the accepted algorithms from earlier API responses. 3381 The IOTP Payment Bridge responds with the Business Error Code if it 3382 does not provide any (more) authentication algorithms and challenges. 3384 Input Parameters 3386 o Authentication Identifier - the authenticator may provide its 3387 payment identifier, i.e., Payment Handler or Merchant Payment 3388 Identifier. 3389 o Wallet Identifier and/or Pass Phrase 3390 o set of pre-selected algorithms for authentication 3392 XML definition: 3394 3395 3400 Output Parameters 3402 o list of Authentication Challenge Packaged Contents - for 3403 insertion into the IOTP Authentication Request Component 3404 o Algorithm Element - for insertion into the IOTP Authentication 3405 Request Component 3407 XML definition: 3409 3412 Tables 4 and 5 explain the attributes and elements; Table 3 3413 introduces the Error Codes. 3415 4.1.5 Authenticate 3417 The Consumer's IOTP Application Core defers payment protocol specific 3418 authentication processing and the current challenge value to the 3419 active IOTP Payment Bridge. Alternative authentication algorithms 3420 might be tried sequentially or offered to the user for selection. 3422 Note that the IOTP Application Core has to consider both the current 3423 context and the algorithm in order to determine the responsible IOTP 3424 Payment Bridge. 3426 Failed authentication is reported by the Business Error Code which 3427 might trigger the inquiry of the details ("Inquire Process State"). 3428 Final failures might be encoded by the process state "Failed". 3430 Input Parameters 3432 o Authentication Identifier 3433 o Wallet Identifier and/or Pass Phrase 3434 o Authentication Challenge Packaged Content - copied from the 3435 IOTP Authentication Request Component 3436 o Algorithm Element - copied from the IOTP Authentication Request 3437 Component 3439 XML definition: 3441 3442 3447 Output Parameters 3449 o Authentication Response Packaged Content - for insertion into 3450 the IOTP Authentication Response Component 3452 XML definition: 3454 3456 Tables 4 and 5 explain the attributes and elements; Table 3 3457 introduces the Error Codes. 3459 4.1.6 Check Authentication Response 3461 This API function verifies the Consumer's payment protocol specific 3462 authentication response. In Baseline IOTP this API function is called 3463 by the Merchant (or the Financial Institution). It is called only if 3464 the counter party has responded with an IOTP Authentication Response 3465 Component within the Authentication Response Block. Of course, the 3466 IOTP Application Core traces the need of such an response. 3468 Due to the authentication's statelessness, all parameters (algorithm, 3469 challenge and response) are submitted to the IOTP Payment Bridge. 3470 Authentication failure is reported by a Process State different from 3471 "CompletedOK". 3473 Input Parameters 3475 o Authentication Identifier 3476 o Wallet Identifier and/or Pass Phrase 3477 o Authentication Challenge Packaged Content - generated by 3478 previous "Inquire Authentication Challenge" API call 3479 o Algorithm Element 3480 o Authentication Response Packaged Content - copied from the 3481 Authentication Response Component 3483 XML definition: 3485 3487 3492 Output Parameters 3494 o Current Process (Authentication) State 3495 o Completion Code 3496 o Status Description and its language annotation 3498 XML definition: 3500 3501 3512 Tables 4 and 5 explain the attributes and elements; Table 3 3513 introduces the Error Codes. 3515 4.2 Brand Selection Related API Calls 3517 4.2.1 Find Payment Instrument 3519 This API function determines which instances of a Payment Brand, 3520 e.g., two Mondex cards, are present. The same physical card may even 3521 represent multiple payment instruments. 3523 The IOTP Application Core supplies possible payment brand and payment 3524 protocol to the IOTP Payment Bridge that has to be considered when 3525 the IOTP Payment Bridge searches for appropriate payment instruments. 3526 This set represents the (sub)set of payment alternatives being 3527 supported by the Merchant. If the IOTP Application Cote has multiple 3528 possible payment brand/protocol, it can call this function in turn. 3530 The Existing Payment Software responds with PayInstrument Elements 3531 with empty PayInstId attributes if it does not distinguish between 3532 different payment instruments for the particular payment 3533 alternatives. 3535 Note that the Payment API assumes that the values of the attributes 3536 BrandId, ProtocolId, ProtocolBrandId and the currency amount suffice 3537 for the determination of the appropriate Packaged Content Element 3538 that will be transmitted to the Payment Handler later on. 3540 Input Parameters 3542 o Brand Identifier - copied from the Brand List Component's Brand 3543 Element 3544 o Payment Protocol Identifier and associated Protocol Brand 3545 Identifier 3546 o Payment Direction - copied from the Brand List Component 3547 o Currency Code and Currency - copied from the Currency Amount 3548 Element 3549 o Payment Amount - copied from the Currency Amount Element 3550 o Consumer Payment Identifier - Consumer's unique reference to 3551 the current payment transaction 3552 o Wallet Identifier - managed by the IOTP Application Core 3553 o (Brand) Packaged Content - further payment brand description; 3554 copied from the Brand List Component's Brand Element 3556 o (Protocol Brand) Element - further information; copied from the 3557 Protocol Brand Element of the Brand List Component which 3558 relates to the Consumer selected Brand Element, if any. 3559 o (Protocol Amount) Packaged Content - further payment protocol 3560 description, copied from the Brand List Component's Protocol 3561 Amount Element 3562 o Element (Protocol) Packaged Content - further payment protocol 3563 description, copied from the Brand List Component's Pay 3564 Protocol Element 3566 XML definition: 3568 3572 3582 Output Parameters 3584 o The known Payment Instrument Identifiers, these are internal 3585 values 3586 o The user-defined names of the payment instrument and their 3587 language encoding 3589 The Existing Payment Software responds with an empty list of 3590 identifiers, either if it does not distinguish between different 3591 payment instruments or if there are no registered payment instruments 3592 available despite brand support for at least one (unspecified) 3593 payment protocol. In the latter case, the IOTP Payment Bridge has to 3594 request the registration of a suitable payment instrument at a 3595 subsequent step of the payment process. 3597 XML definition: 3599 3600 3601 3606 Tables 4 and 5 explain the attributes and elements; Table 3 3607 introduces the Error Codes. 3609 4.2.2 Check Payment Possibility 3611 This API function checks whether a payment (both debit and credit) 3612 can go ahead. It can be used, for example, to check 3614 o if there are sufficient funds available in a particular 3615 currency for an electronic cash payment brand, 3616 o whether there is sufficient value space left on the payment 3617 instrument for payment refund, 3618 o whether required system resources are available and properly 3619 configured, e.g., serial ports or baud rate, 3620 o whether environment requirements are fulfilled, e.g., chip card 3621 reader presence or Internet connection. 3623 If the payment method is based on external components, e.g., magnetic 3624 stripe or chip cards, and the check accesses the medium, the existing 3625 payment method should not mutually exclusive lock system resources, 3626 e.g., serial port or modem, that may also be required by other 3627 Existing Payment Software, e.g., multiple payment software components 3628 may share the same card reader. If this happens for API internal 3629 request processing, the function has to unlock these components prior 3630 to return. Otherwise, the payment may not proceed if the Consumer 3631 cancels immediately and decides to use another payment instrument. In 3632 this event the previous IOTP Payment Bridge is not notified about the 3633 change. 3635 This function call happens immediately after the Consumer's payment 3636 instrument selection. For example, if the payment instrument is a 3637 chip card, that is not inserted in the chip card reader, the Consumer 3638 may be prompted for its insertion. However, the Consumer should be 3639 able to hit some 'skip' button, if the payment check is part of the 3640 actual payment protocol, too. Finally, the IOTP Payment Bridge may 3641 provide only a subset of these capabilities or may even directly 3642 generate a successful response without any checks. 3644 Input Parameters 3646 o Brand Identifier - user selection 3647 o Payment Instrument Identifier - user selection 3648 o Currency Code and Currency Code Type - copied from the selected 3649 Currency Amount Element 3650 o Payment Amount - copied from the selected Currency Amount 3651 Element 3652 o Payment Direction - copied from the selected Trading Protocol 3653 Option Block 3655 o Protocol Identifier - copied from the selected Pay Protocol 3656 Element 3657 o Protocol Brand Identifier - copied from the selected Protocol 3658 Brand Element of the Brand List Component which relates to the 3659 selected Brand Element, if any 3660 o Consumer Payment Identifier - Consumer's unique reference to 3661 the current payment transaction 3662 o Wallet Identifier and/or Pass Phrase 3663 o (Brand) Packaged Content - copied from the selected Brand 3664 Element 3665 o (Protocol Amount) Packaged Content - copied from the selected 3666 Protocol Amount Element 3667 o (Protocol) Packaged Content - copied from the selected Pay 3668 Protocol Element 3669 o (Protocol Brand) Packaged Content - copied from the selected 3670 Protocol Brand Element of the Brand List Component which 3671 relates to the selected Brand Element, if any 3673 XML definition: 3675 3679 3691 Output Parameters 3693 o three Brand Selection Info Packaged Content elements - for 3694 insertion into the Brand Selection component 3695 o Brand - additional data about the payment brand 3696 o Protocol Amount - additional data about the payment protocol 3697 o Currency Amount - additional payment brand and currency 3698 specific data 3700 XML definition: 3702 3706 3708 Tables 4 and 5 explain the attributes and elements; Table 3 3709 introduces the Error Codes. 3711 4.3 Payment Transaction Related API calls 3713 These Payment API calls may be made either by the Consumer's or 3714 Payment Handler's IOTP Application Core. 3716 4.3.1 Start Payment Consumer 3718 This API function initiates the actual payment transaction at the 3719 Consumer side. The IOTP Payment Bridge and the Existing Payment 3720 Software perform all necessary initialization and preparation for 3721 payment transaction processing. This includes the reservation of 3722 external periphery. E.g., 1) the Consumer's chip card reader needs to 3723 be protected against access from other software components, 2) the 3724 insertion of the chip card may be requested, 3) the Internet 3725 connection may be re-established, or 4) the Payment Handler may open 3726 a mutual exclusive session to the security hardware. 3728 The IOTP Payment Bridge monitors the payment progress and stores the 3729 current payment states such that resumption - even after power 3730 failures - remains possible. Note that the IOTP Application Core 3731 supplies only a subset of the following input parameter to the 3732 associated resumption API function and refers to the payment 3733 transaction through the party's payment identifier. 3735 Input Parameters 3737 o Brand Identifier - copied from the selected Brand Element 3738 o Payment Instrument Identifier - the user selection 3739 o Currency Code and Currency - copied from the selected Currency 3740 Amount Element 3741 o Payment Amount - copied from the selected Currency Amount 3742 Element 3743 o Payment Direction - copied from the Brand List Component 3744 o Protocol Identifier - copied from the selected Payment Protocol 3745 Element 3746 o Protocol Brand Element - further information; copied from the 3747 Protocol Brand Element of the Brand List Component which 3748 relates to the selected Brand Element, if any 3749 o OkFrom, OkTo - copied from the Payment Component 3750 o Consumer Payment Identifier - Consumer's unique reference to 3751 the current payment transaction 3752 o Wallet Identifier and/or Pass Phrase 3753 o Call Back Function - used for end user notification/logging 3754 purposes 3755 o Call Back Language List. This list is required if the Call Back 3756 Function is set 3757 o (Brand) Packaged Content - further payment brand description; 3758 copied from the selected Brand Element's content 3759 o (Protocol Amount) Packaged Content - further payment protocol 3760 description; copied from the selected Protocol Amount Element's 3761 content 3762 o (Payment Protocol) Packaged Content - further payment protocol 3763 description; copied from the selected Pay Protocol Element's 3764 content 3765 o (Order) Packaged Content - further order description, copied 3766 from the Order Component 3768 XML definition: 3770 3775 3792 Output Parameters 3794 o Continuation Status 3795 o (Payment Scheme) Packaged Content - for insertion into the 3796 Payment Scheme Component of the IOTP Payment Request Block 3798 The IOTP Application Core is allowed to reissue this request several 3799 times on failed analyses of the response. 3801 XML definition: 3803 3805 3808 Tables 4 and 5 explain the attributes and elements; Table 3 3809 introduces the Error Codes. 3811 4.3.2 Start Payment Payment Handler 3813 This API function initializes the Consumer initiated payment 3814 transaction at the Payment Handler's side. Similar to the Consumer's 3815 system, the IOTP Payment Bridge and the Existing Payment Software 3816 perform all necessary initialization and preparation for payment 3817 transaction processing. 3819 Input Parameters 3821 o Brand Identifier - copied from the Consumer selected Brand 3822 Element 3823 o Consumer Payment Identifier - copied from the Payment Scheme 3824 Component 3825 o Currency Code and Currency - copied from the Consumer selected 3826 Currency Amount Element 3827 o Payment Amount - copied from the Consumer selected Currency 3828 Amount Element 3829 o Payment Direction - copied from the Brand List Component 3830 o Protocol Identifier - copied from the Consumer selected 3831 Payment Protocol Element 3832 o Protocol Brand Identifier - copied from the Brand Protocol 3833 Element of the Brand List Component which relates to the 3834 Consumer selected Brand Element, if any 3835 o OkFrom, OkTo - copied from the Payment Component 3836 o Payment Handler Payment Identifier - Payment Handler's unique 3837 reference to the current payment transaction 3838 o Merchant Organisation Identifier - copied from the Merchant's 3839 Organisation Element 3840 o Wallet Identifier - renaming to till identifier neglected - 3841 and/or Pass Phrase 3842 o Call Back Function - used for end user notification/logging 3843 purposes 3844 o Call Back Language List. This list is required if the call back 3845 function is set 3846 o (Brand) Packaged Content - further payment brand description; 3847 copied from the Consumer selected Brand Element's content 3848 o (Protocol Brand) Packaged Content - further information; copied 3849 from the Protocol Brand Element of the Brand List Component 3850 which relates to the Consumer selected Brand Element, if any. 3851 o (Protocol Amount) Packaged Content - further payment protocol 3852 description; copied from the Consumer selected Protocol Amount 3853 Element's content 3854 o (Protocol) Packaged Content - further payment protocol 3855 description; copied from the Consumer selected Pay Protocol 3856 Element's content 3857 o (TradingRoleData) Packaged Content - further payment protocol 3858 description; the Name Attribute of the packaged contents must 3859 include "Payment:" as the prefix, for example "Payment:SET-OD". 3860 o Three Brand Selection Info Packaged Content Elements - copied 3861 from the Brand Selection Component 3862 o Brand - additional data about the payment brand 3863 o Protocol Amount - additional data about the payment protocol 3864 o Currency Amount - additional payment brand and currency 3865 specific data 3866 o (Payment Scheme) Packaged Content. 3868 XML definition: 3870 3879 3896 Output Parameters 3898 o Continuation Status 3899 o (Payment Scheme) Packaged Content - for insertion into the 3900 Payment Scheme Component of the IOTP Payment Exchange Block 3902 The response message must contain payment schema data if the 3903 continuation status signals "Continue". The IOTP Application Core is 3904 allowed to reissue this request several times on failed analyses of 3905 the response. 3907 XML definition: 3909 3911 3914 Tables 4 and 5 explain the attributes and elements; Table 3 3915 introduces the Error Codes. 3917 4.3.3 Resume Payment Consumer 3919 This API function resumes a previously suspended payment at the 3920 Consumer side. Resumption includes the internal inquiry of the 3921 payment transaction data, e.g., payment amount, protocol identifier, 3922 and the whole initialization as it has been applied on the "Start 3923 Payment Consumer" API request. 3925 It is up to the IOTP Application Core to decide whether an IOTP 3926 Payment Request Block or a IOTP Payment Exchange Block needs to be 3927 generated. One indicator might be the receipt of a previous IOTP 3928 Payment Exchange Block from the Payment Handler, e.g., the knowledge 3929 of the Payment Handler Payment Identifier. 3931 Input Parameters 3933 o Consumer Payment Identifier 3934 o Wallet Identifier and/or Pass Phrase 3935 o Call Back Function - used for end user notification/logging 3936 purposes 3938 XML definition: 3940 3941 3948 Output Parameters 3950 o Continuation Status 3951 o (Payment Scheme) Packaged Content - for insertion in the 3952 Payment Scheme Component of the next IOTP message (Payment 3953 Exchange or Request Block). 3955 The IOTP Application Core is allowed to reissue this request several 3956 times on failed analyses of the response. However, the IOTP Payment 3957 Bridge might reject the resumption request by using the "AttNotSupp" 3958 Error Code "naming" the Consumer Payment Identifier attribute. Then 3959 the Consumer has to apply normal error processing to the current 3960 (sub-)transaction and to issue a new Payment Request Block to the 3961 Payment Handler. 3963 XML definition: 3965 3967 3970 Tables 4 and 5 explain the attributes and elements; Table 3 3971 introduces the Error Codes. 3973 4.3.4 Resume Payment Payment Handler 3975 This API function resumes a payment at the Payment Handler side. 3977 Input Parameters 3979 o Payment Handler Payment Identifier 3980 o Wallet Identifier - renaming to till identifier neglected - and 3981 Pass Phrase 3982 o Call Back Function - used for end user notification/logging 3983 purposes 3984 o Call Back Language List. This list is required if the Call Back 3985 Function is set 3986 o (Payment Scheme) Packaged Content - copied from the Payment 3987 Scheme Component of the received IOTP message (Payment Exchange 3988 or Request Block). 3990 XML definition: 3992 3994 4001 Output Parameters 4003 o Continuation Status 4004 o (Payment Scheme) Packaged Content - for insertion in the 4005 Payment Scheme Component of the next Payment Exchange Block. 4007 The response message contains payment schema specific data if the 4008 continuation status signals "Continue". The IOTP Application Core is 4009 allowed to reissue this request several times on failed analyses of 4010 the response. 4012 XML definition: 4014 4016 4019 Tables 4 and 5 explain the attributes and elements; Table 3 4020 introduces the Error Codes. 4022 4.3.5 Continue Process 4024 This API function passes one specific IOTP Payment Scheme Component, 4025 i.e., the encapsulated Packaged Content elements, received from the 4026 counter party (e.g. Consumer) to the IOTP Payment Bridge and responds 4027 with the next IOTP Payment Scheme Component for submission to the 4028 counter party. 4030 Input Parameters 4032 o Payty's Payment Identifier 4033 o Process (Transaction) Type which distinguishes between Payments 4034 and Inquiries. 4035 o Wallet Identifier and/or Pass Phrase 4036 o (Payment Scheme) Packaged Content - copied from the Payment 4037 Scheme Component of the received Payment Exchange Block or from 4038 the Error Block. 4040 Each party should set the payment identifier with the local 4041 identifier (Consumer: ConsumerPayId; Merchant: MerchantPayId; Payment 4042 Handler: PaymentHandlerPayId). 4044 XML definition: 4046 4047 4053 Output Parameters 4055 o Continuation Status 4056 o (Payment Scheme) Packaged Content - for insertion in the 4057 Payment Scheme Component of the next Payment Exchange Block or 4058 final Payment Response Block 4060 The response message contains payment schema data if the continuation 4061 status signals "Continue". The IOTP Payment Bridge must signal "End", 4062 if the payment scheme data was received within an IOTP Error Block 4063 containing an Error Component with severity HardError. 4065 XML definition: 4067 4068 4071 Tables 4 and 5 explain the attributes and elements; Table 3 4072 introduces the Error Codes. 4074 4.3.6 Change Process State 4076 The IOTP Application Core changes the current payment status by this 4077 request. The IOTP Payment Bridge may be notified about business level 4078 normal termination, cancellation, suspension, and processing errors. 4079 Notification happens by requesting the intended process state. 4081 The IOTP Payment Bridge processes the status change and reports the 4082 result. 4084 The IOTP Application Core has to analyze any returned process status 4085 in order to check whether the IOTP Payment Bridge has agreed to or 4086 declined the status switch. E.g., the submitted Process State 4087 "CompleteOk" may lead to the Payment Status "Failed" if the payment 4088 transaction has already failed. 4090 Transaction Suspension is notified by the newly introduced Process 4091 State "Suspended". The other attribute values have been taken from 4092 the IOTP specification. 4094 This API function might be called by the Consumer, Merchant, or 4095 Payment Handler for each payment transaction anytime after the 4096 issuance of "FindPaymentInstrument" to the IOTP Payment Bridge by the 4097 Consumer, the issuance of "FindAcceptedPaymentBrand" by the Merchant, 4098 or the issuance of "StartPaymentPaymentHandler" by the Payment 4099 Handler. 4101 The Process States "CompletedOk", "Failed", and "ProcessError" are 4102 final in the sense that they can not be changed on subsequent calls. 4103 However, the API function should not return with an error code if 4104 such an incompatible call has been issued. Instead it should report 4105 the old unchanged Process State. 4107 Unknown payment transactions are reported by the Error Code 4108 "AttValInvalid" pointing to the PayId attribute. 4110 Input Parameters 4112 o Party's Payment Identifier 4113 o intended Payment Status 4114 o intended Completion Code 4115 o Process (Transaction) Type which distinguishes between Payments 4116 and Inquiries. 4117 o Wallet Identifier and/or Pass Phrase 4119 XML definition: 4121 4122 4135 Output Parameters 4137 o Process State and Percent Complete 4138 o Completion Code 4139 o Status Description and its language annotation 4141 XML definition: 4143 4144 4156 Tables 4 and 5 explain the attributes and elements; Table 3 4157 introduces the Error Codes. 4159 4.4 General Inquiry API Calls 4161 The following calls are not necessarily assigned to a payment 4162 transaction and may be issued at any time. There are no dependencies 4163 on any other calls. 4165 4.4.1 Remove Payment Log 4167 The IOTP Application Core notifies the IOTP Payment Bridge and/or the 4168 corresponding Existing Payment Software via IOTP Payment Bridge that 4169 any record in the Payment Log file, that deals with the listed 4170 payment transaction, might be removed. 4172 Input Parameters 4174 o Party's Payment Identifier 4175 o Wallet Identifier and/or Pass Phrase 4177 XML definition: 4179 4180 4185 Output Parameters 4187 XML definition: 4189 4190 4192 Tables 4 and 5 explain the attributes and elements; Table 3 4193 introduces the Error Codes. 4195 4.4.2 Payment Instrument Inquiry 4197 This API function retrieves the properties of the Payment Instrument. 4198 The Payment Instrument Identifier could be omitted if this identifier 4199 is derived by other means, e.g., by analysis of the currently 4200 inserted chip card. If the Payment instrument could not uniquely 4201 determined, the IOTP Payment Bridge may provide suitable dialogs for 4202 user input. 4204 E.g., this API function might be used during problem resolution with 4205 the Customer Care Provider of the issuer of the payment instrument, 4206 in order to inquire payment instrument specific values. 4208 Input parameters 4210 o Brand Identifier 4211 o Payment Instrument Identifier 4212 o Protocol Identifier 4213 o Wallet Identifier and/or Pass Phrase 4214 o Property Type List - sequence of values whose language is 4215 identified by xml:lang 4216 o (Brand) PackagedContent Content - further payment brand 4217 description 4218 o Protocol Brand Content - further payment brand information 4219 o (Protocol Amount) PackagedContent Content - further payment 4220 protocol description 4221 o (Pay Protocol) PackagedContent Content - further payment 4222 protocol description 4224 The codes in the property type list are of two types: 4226 o generic codes which apply to all payment methods but might be 4227 unavailable 4228 o Payment Brand specific codes. 4230 Generic codes for the Property Type List are: 4232 Property Type Meaning 4233 Balance Current balance 4234 Limit Maximum balance 4235 PaymentLimit Maximum payment transaction limit 4236 Expiration Expiration date 4237 Identifier Issuer assigned identifier of the payment 4238 instrument. Usually, it does not match with 4239 the API's payment instrument identifier. 4240 LogEntries Number of stored payment transaction 4241 entries. The entries are numbered from 0 4242 (the most recent) to some non-negative 4243 value for the oldest entry. 4244 PayAmountn Payment Amount of the n-th recorded payment 4245 transaction, n may negative 4246 PayPartyn Remote party of the n-th payment recorded 4247 transaction, n may negative 4248 PayTimen Time of the n-th payment recorded 4249 transaction, n may negative 4251 XML definition: 4253 4257 4266 Output parameters 4268 o a list of zero or more unavailable property values whose 4269 language are identified by xml:lang. 4270 o a list of zero or more sets of "Properties Types", "Property 4271 Values" and "Property Descriptions" 4273 XML definition: 4275 4277 4281 4282 4287 Tables 4 and 5 explain the attributes and elements; Table 3 4288 introduces the Error Codes. 4290 4.4.3 Inquire Pending Payment 4292 This API function reports the party's payment identifiers of any 4293 pending payment transactions that the IOTP Payment Bridge/Existing 4294 Payment Software recommends be completed or suspended prior to the 4295 processing of new payment transactions. It does not respond with 4296 further transaction details. These have to be requested with "Inquire 4297 Process State". 4299 Note that the IOTP Payment Bridge has to respond without the benefit 4300 of any pass phrase if there exist no pending payment transaction. But 4301 if there are some pending payment transactions, the IOTP Payment 4302 Bridge may refuse the immediate response and may instead request the 4303 appropriate pass phase from the IOTP Application Core. 4305 Input Parameters 4307 o Wallet Identifier and/or Passphrase 4309 XML definition: 4311 4312 4316 Output Parameters 4318 o Party's Payment Identifier 4320 XML definition: 4322 4324 4325 4328 Tables 4 and 5 explain the attributes and elements; Table 3 4329 introduces the Error Codes. 4331 4.5 Payment Related Inquiry API Calls 4333 4.5.1 Check Payment Receipt 4335 This function is used by the Consumer and might be used by the 4336 Payment Handler to check the consistency, validity, and integrity of 4337 IOTP payment receipts which might consist of Packaged Content 4338 Elements 4340 o from the IOTP Payment Receipt Component - provided by the 4341 Payment Handler's "Inquire Process State" API call shortly 4342 before payment completion, 4344 o from Payment Scheme Components being exchanged during the 4345 actual payment, or 4347 o being returned by the Consumer's "Inquire Process State" API 4348 call shortly before payment completion 4350 The IOTP Application Core has to check the PayReceiptNameRefs 4351 attribute of the IOTP Payment Receipt Component and to supply exactly 4352 the Packaged Content Elements being referred to. 4354 Failed verification is returns a business error. 4356 Note that this Payment API assumes that any payment receipt builds 4357 upon a subset of elements with reference to [IOTP]. Furthermore, the 4358 Packaged Content Element have to be distinguishable by their Name 4359 attribute. 4361 Input Parameters 4363 o Party's Payment Identifier 4364 o Wallet Identifier and/or Pass Phrase 4365 o All Packaged Content Elements in the payment receipt 4367 XML definition: 4369 4370 4375 Output Parameters 4377 XML definition: 4379 4380 4382 Tables 4 and 5 explain the attributes and elements; Table 3 4383 introduces the Error Codes. 4385 4.5.2 Expand Payment Receipt 4387 This API function expands any IOTP payment receipt into a form which 4388 may be used for display or printing purposes. "Check Payment Receipt" 4389 should be used first if there is any question of the payment receipt 4390 containing errors. 4392 The same conventions apply to the input parameter as for "Check 4393 Payment Receipt" (cf. Section 4.5.1). 4395 Input Parameters 4397 o Party's Payment Identifier 4398 o Wallet Identifier and/or Pass Phrase 4399 o All Packaged Content Elements that build the payment receipt 4401 XML definition: 4403 4404 4409 Output Parameters 4411 o Brand Identifier 4412 o Protocol specific Brand Identifier 4413 o Payment Instrument Identifier 4414 o Currency Code and Currency Code Type 4415 o Payment Amount 4416 o Payment Direction 4417 o Time Stamp - issuance of the receipt 4418 o Protocol Identifier 4419 o Protocol specific Transaction Identifier - this is an internal 4420 reference number which identifies the payment 4421 o Consumer Description, Payment Handler Description, and a 4422 language annotation 4424 o Style Sheet Net Location 4425 o Payment Property List. A list of type/value/description triples 4426 which contains additional information about the payment which 4427 is not covered by any of the other output parameters; property 4428 descriptions have to consider the language annotation. 4430 The Style Sheet Net Location refers to a Style Sheet (e.g. [XSLT]) 4431 that contains presenetation information about the reported XML 4432 encoded data. 4434 XML definition: 4436 4437 4453 4454 4459 The Existing Payment Software should return as many attributes as 4460 possible from the supplied IOTP Payment Receipt. The payment 4461 supplement defines the attribute values for the payment properties. 4463 Tables 4 and 5 explain the attributes and elements; Table 3 4464 introduces the Error Codes. 4466 4.5.3 Inquire Process State 4468 This API function returns the current payment state and optionally 4469 further Packaged Content Elements that form the payment receipt. 4470 Called by the Payment Handler, the IOTP Payment Bridge might respond 4471 with data intended for inclusion in the IOTP Payment Receipt 4472 Component's Packaged Content. When the Consumer calls this function 4473 shortly before payment completion, it may respond with further items 4474 of the payment receipt. Such items might be created by a chip card. 4476 Input Parameters 4478 o Party's Payment Identifier 4479 o Wallet Identifier and/or Pass Phrase 4481 XML definition: 4483 4484 4489 Output Parameters 4491 o Current Process State and Percent Complete 4492 o Completion Code 4493 o Status Description and its language annotation 4494 o Payment Receipt Name References to all Packaged Content 4495 Elements that build the payment receipt (cf. Section 4.5.1), 4496 even if they have not been created so far (Consumer's share) 4497 o Any Packaged Content Element being available that form the 4498 payment receipt 4500 The IOTP provides a linking capability to the payment receipt 4501 delivery. Instead of encapsulating the whole payment specific data 4502 into the packaged content of the payment receipt, other Payment 4503 Scheme Components' Packaged Content might be referred to. 4505 XML definition: 4507 4509 4522 Tables 4 and 5 explain the attributes and elements; Table 3 4523 introduces the Error Codes. 4525 4.5.4 Start Payment Inquiry 4527 This API function responds with any additional payment scheme 4528 specific data that is needed by the Payment Handler for Consumer 4529 initiated payment transaction inquiry processing. Probably, the IOTP 4530 Payment Bridge (or the corresponding Existing Payment Software) has 4531 to determine the payment related items that were provided with the 4532 "Start Payment Consumer" API function call. 4534 Input Parameters 4536 o Consumer Payment Identifier 4537 o Wallet Identifier and/or Pass Phrase 4539 XML definition: 4541 4542 4547 Output Parameters 4549 o (Payment Scheme) Packaged Content - intended for insertion in 4550 the Payment Scheme Component of the Inquiry Request Block 4552 XML definition: 4554 4557 Tables 4 and 5 explain the attributes and elements; Table 3 4558 introduces the Error Codes. 4560 4.5.5 Inquire Payment Status 4562 The Payment Handler calls this API function for Consumer initiated 4563 inquiry processing. It differs from the previous "Inquire Process 4564 State" API function by the optional inclusion of payment scheme 4565 specific data. The response may encapsulate further details about the 4566 payment transaction. 4568 Input Parameters 4570 o Payment Handler Payment Identifier 4571 o Wallet Identifier and/or Pass Phrase 4572 o (Payment Scheme) Packaged Content - copied from the Inquiry 4573 Request Block's Payment Scheme Component 4575 XML definition: 4577 4578 4583 Output Parameters 4585 o Current Process State 4586 o Completion Code 4587 o Status Description and its language annotation 4588 o (Payment Scheme) Packaged Content - intended for insertion in 4589 the Payment Scheme Component of the Inquiry Response Block 4591 XML definition: 4593 4595 4607 Tables 4 and 5 explain the attributes and elements; Table 3 4608 introduces the Error Codes. 4610 4.6 Other API Calls 4611 4.6.1 Manage Payment Software 4613 The following API function notifies the IOTP Payment Bridge about the 4614 intended registration, modification, or deletion of a payment 4615 instrument. The actual processing is up to the IOTP Payment Bridge. 4617 This API request may also be used to activate the IOTP Payment Bridge 4618 (and the corresponding Existing Payment Software) for general 4619 administration purposes. 4621 Input Parameters 4623 o Brand Identifier 4624 o Protocol Identifier 4625 o Any action code: 4626 o New - add new payment method / instrument 4627 o Update - change the payment method's / instrument's data 4628 o Delete - delete a payment method / instrument 4629 o Wallet Identifier and/or Pass Phrase 4630 o (Brand) Packaged Content - further payment brand description 4631 o (Pay Protocol) Packaged Content - further payment protocol 4632 description 4633 o (Protocol Amount) Packaged Content - further payment protocol 4634 description 4636 If the Action attribute is set, the Brand and Protocol Identifier 4637 have to also be set. The IOTP Payment Bridge has to provide the 4638 required user dialogs and selection mechanisms. E.g., updates and 4639 deletions may require the selection of the payment instrument. A new 4640 wallet might be silently generated on the supplement of a new Wallet 4641 Identifier or after an additional end user acknowledge. The IOTP 4642 Application Core should not provide any pass phrases for new wallets. 4643 Instead, the IOTP Payment Bridge has to request and verify them, 4644 which may return their value to the IOTP Application Core in plain 4645 text. In addition, the IOTP Payment Bridge returns the supported 4646 authentication algorithms when a new brand and protocol pair has been 4647 registered. 4649 If the "Action" attribute is omitted, the IOTP Payment Bridge which 4650 is responsible for the Existing Payment Software pops up in a general 4651 interactive mode. 4653 XML definition: 4655 4658 4667 Output Parameters 4669 o An action code: 4670 o New - added new wallet 4671 o Update - changed wallet's configuration 4672 o Delete - removed a wallet 4673 o Wallet Identifier and/or Pass Phrase 4675 The IOTP Payment Bridge does not return any information about the set 4676 of registered payment instruments because these data items are 4677 dynamically inferred during the brand selection process at the 4678 beginning of each IOTP transaction. However, the IOTP Application 4679 Core has to be notified about new wallets and should be notified 4680 about updated and removed wallet (identifier)s". Alternatively, 4681 removed wallets can be implicitly detected during the next brand 4682 selection phase. Updated wallets do no affect the processing of the 4683 IOTP Application Core. The IOTP Payment Bridge should only support 4684 the addition of at most one wallet because it is not able to report 4685 multiple additions at once back to the IOTP Application Core. 4687 XML definition: 4689 4690 4698 Tables 4 and 5 explain the attributes and elements; Table 3 4699 introduces the Error Codes. 4701 5. Call Back Function 4703 This API function, called by the IOTP Payment Bridge, is used to 4704 provide information for Consumer or Payment Handler notification 4705 about the progress of the payment transaction. 4707 Its use is illustrated in the diagram below. 4709 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 4710 IOTP Application ----calls---- 4711 | Core | | 4712 display | | v 4713 to <---------- Call Back <--calls--- Payment 4714 user | | Software 4715 ---------------- 4716 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 4718 Figure 9. Call Back Function 4720 Whenever this function is called, the content of the status 4721 description should be made available to the user. For example on a 4722 status bar, a pop up window, etc. 4724 A reference to the Call Back function is passed as an input parameter 4725 to the "Start Payment X" and "Resume Payment X" API function. 4726 Afterwards, this function might be called whenever the status changes 4727 or progress needs to be reported. 4729 Input Parameters 4731 o the software identifier of the caller 4732 o Party's Payment Identifier 4733 o Process State and Percent Complete 4734 o Completion Code 4735 o Status Description and its language annotation, text which 4736 provides information about the progress of the call. It should 4737 be displayed or made available to, for example, the Consumer. 4739 Examples of Status Description could be: 4741 o "Paying 12.30 USD to XYZ Inc" 4742 o "Payment completed" 4743 o "Payment aborted" 4745 The valid languages are announced in the Call Back Language List 4746 attribute in "Start Payment X" and "Resume Payment X" API function 4747 calls. 4749 XML definition: 4751 4752 4766 Output Parameters 4768 XML definition: 4770 4771 > 4773 Tables 4 and 5 explain the attributes and elements; Table 3 4774 introduces the Error Codes. 4776 Basically, the call back function accepts all input arguments or 4777 rejects the whole request. It may even accept malformed requests. 4779 Some payment schemes may support or require that the Consumer might 4780 be able to cancel the payment at any time. The Call Back function can 4781 be used to facilitate this by returning the cancellation request on 4782 the next call (using the Business Error Code and Completion Code 4783 "ConsCancelled"). 4785 Vice versa the Payment Handler's Application Core might use the 4786 similar mechanism to signal its IOTP Payment Bridges any exceptional 4787 need for a fast shutdown. These IOTP Payment Bridges may initiate the 4788 appropriate steps for terminating/canceling all pending payment 4789 transactions. 4791 Note that the "Change Process State" API function provides the second 4792 mechanism for such kind of notification. Therefore, the IOTP Payment 4793 Bridge or Existing Payment Software may ignore the details of the 4794 "Call Back" response. 4796 6. Security Consideration 4798 The IOTP Payment APIs only supports security using pass phrase to 4799 access to payment Wallet. These can be protected over TLS, which 4800 provides stronger security at the transport layer, but 4801 implementations are out the scope of this document. 4803 See also security consideration section of [IOTP]. 4805 Full Copyright Statement 4807 Copyright (C) The Internet Society 2001. 4809 This document and translations of it may be copied and furnished to 4810 others, and derivative works that comment on or otherwise explain it 4811 or assist in its implementation may be prepared, copied, published 4812 and distributed, in whole or in part, without restriction of any 4813 kind, provided that the above copyright notice and this paragraph are 4814 included on all such copies and derivative works. However, this 4815 document itself may not be modified in any way, such as by removing 4816 the copyright notice or references to the Internet Society or other 4817 Internet organizations, except as needed for the purpose of 4818 developing Internet standards in which case the procedures for 4819 copyrights defined in the Internet Standards process must be 4820 followed, or as required to translate it into languages other than 4821 English. 4823 The limited permissions granted above are perpetual and will not be 4824 revoked by the Internet Society or its successors or assigns. 4826 This document and the information contained herein is provided on an 4827 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4828 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4829 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4830 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4831 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4833 References 4835 [HTML] - Hyper Text Mark Up Language. The Hypertext Markup Language 4836 (HTML) is a simple markup language used to create hypertext documents 4837 that are platform independent. See RFC 1866 and the World Wide Web 4838 (W3C) consortium web site at: http://www.w3.org/MarkUp/ 4840 [HTTP] - Hyper Text Transfer Protocol versions 1.0 and 1.1. See RFC 4841 1945: Hypertext Transfer Protocol - HTTP/1.0. T. Berners-Lee, R. 4842 Fielding & H. Frystyk. May 1996. and RFC 2068: Hypertext Transfer 4843 Protocol - HTTP/1.1. R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. 4844 Berners-Lee. January 1997. 4846 [IOTP] - Internet Open Trading Protocol Specification, Version 1.0, 4847 April 2000, See RFC2801. 4849 [IOTPBOOK] - D. Burdett, D.E. Eastlake III, and M. Goncalves, 4850 Internet Open Trading Protocol, McGraw-Hill, 2000. ISBN 0-07-135501- 4851 4. 4853 [ISO4217] - ISO 4217: Codes for the Representation of Currencies. 4854 Available from ANSI or ISO. 4856 [MIME] - Multipurpose Internet Mail Extensions. See RFC822, RFC2045, 4857 RFC2046, RFC2047, RFC2048 and RFC2049. 4859 [SET] - SET Secure Electronic Transaction(TM) , Version 1.0, May 31, 4860 1997 4861 Book 1: Business Description 4862 Book 2: Programmer's Guide 4863 Book 3: Formal Protocol Definition 4864 Download from: . 4866 [SET/IOTP] - Yoshiaki Kawatsura "SET Supplement for IOTP" (currently 4867 draft-ietf-trade-iotp-v1.0-set-02.txt) 4869 [URL] - Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform 4870 Resource Locators (URL)", RFC 1738, December 1994. 4872 [UTC] - Universal Time Coordinated. A method of defining time 4873 absolutely relative to Greenwich Mean Time (GMT). Typically of the 4874 form: "CCYY-MM- DDTHH:MM:SS.sssZ+n" where the "+n" defines the number 4875 of hours from GMT. See ISO DIS8601. 4877 [XML] - Extensible Mark Up Language (XML) 1.0 (Second Edition). A 4878 W3C recommendation. See http://www.w3.org/TR/1998/REC-xml 4880 [XML-NS] - Namespaces in XML Recommendation. T. Bray, D. Hollander, 4881 A. Layman. Janaury 1999. http://www.w3.org/TR/1999/REC-xml-names 4883 [XSLT] - Extensible Style Language Transformations 1.0, November 4884 1999, See http://www.w3.org/TR/xslt 4886 Author's Addresses 4888 Hans-Bernhard Beykirch and Werner Hans 4889 IT Development & Coordination Center for the German Savings Banks 4890 Organization (SIZ) 4891 Konigswinterer Strase 553 4892 53227 Bonn Germany 4893 E-mail: Hans-Bernhard.Beykirch@siz.de, Werner.Hans@siz.de 4895 Yoshiaki Kawatsura 4896 Hitachi, Ltd. 4897 890 Kashimada Saiwai-ku Kawasaki-shi 4898 Kanagawa, Japan 212-8567 4899 E-mail: kawatura@bisd.hitachi.co.jp 4900 Masaaki Hiroya 4901 Technoinfo Service, Inc. 4902 1155-6-206 Ichigao-cho 4903 Aoba-ku, Yokohama 4904 Kanagawa 225-0024 JAPAN 4905 Phone: +81-45-978-4522 4906 Email: hiroya@st.rim.or.jp 4908 Expiration and File Name 4910 This draft expires October 2001. 4912 Its file name is draft-ietf-trade-iotp-v1.0-papi-05.txt.