idnits 2.17.1 draft-ietf-trade-iotp-v1.0-papi-03.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-03', 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 1713 has weird spacing: '...n error that ...' == Line 1751 has weird spacing: '...ding on the n...' == Line 1762 has weird spacing: '...Content cf. T...' == Line 2809 has weird spacing: '...ontents must ...' == Line 4548 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 (November 2000) is 8563 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 1333, but not defined == Missing Reference: 'PSn' is mentioned on line 1125, but not defined == Missing Reference: 'PS2' is mentioned on line 1334, but not defined == Unused Reference: 'IOTPBOOK' is defined on line 4836, but no explicit reference was found in the text == Unused Reference: 'HTML' is defined on line 4840, but no explicit reference was found in the text == Unused Reference: 'HTTP' is defined on line 4845, but no explicit reference was found in the text == Unused Reference: 'ISO4217' is defined on line 4851, but no explicit reference was found in the text == Unused Reference: 'MIME' is defined on line 4854, but no explicit reference was found in the text == Unused Reference: 'SET' is defined on line 4860, but no explicit reference was found in the text == Unused Reference: 'UTC' is defined on line 4870, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 2801 (ref. 'IOTP') -- Possible downref: Non-RFC (?) normative reference: ref. 'IOTPBOOK' ** Obsolete normative reference: RFC 1866 (ref. 'HTML') (Obsoleted by RFC 2854) ** Obsolete normative reference: RFC 2068 (ref. 'HTTP') (Obsoleted by RFC 2616) -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO4217' ** Obsolete normative reference: RFC 1738 (ref. 'URL') (Obsoleted by RFC 4248, RFC 4266) -- Possible downref: Non-RFC (?) normative reference: ref. 'SET' -- Possible downref: Non-RFC (?) normative reference: ref. 'UTC' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSLT' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML-NS' Summary: 11 errors (**), 0 flaws (~~), 18 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 TRADE Working Group Werner Hans 2 INTERNET-DRAFT Hans-Bernhard.Beykirch 3 SIZ 4 Masaaki Hiroya 5 Yoshiaki Kawatsura 6 Hitachi 7 Expires: May 2001 November 2000 9 Payment API for v1.0 Internet Open Trading Protocol (IOTP) 10 ------- --- --- ---- -------- ---- ------- -------- ------ 11 13 Status of this Memo 15 This document is intended to become an Informational RFC. 16 Distribution of this document is unlimited. Please send comments to 17 the TRADE working group at , which may 18 be joined by sending a message with subject "subscribe" to . Discussions of the TRADE working 20 group are archived at http://www.elistx.com/archives/ietf-trade. 22 This document is an Internet-Draft and is in full conformance with 23 all provisions of Section 10 of RFC 2026. Internet-Drafts are 24 working documents of the Internet Engineering Task Force (IETF), its 25 areas, and its working groups. Note that other groups may also 26 distribute working documents as Internet-Drafts. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet- Drafts as reference 31 material or to cite them other than as "work in progress." 33 The list of current Internet-Drafts can be accessed at 34 http://www.ietf.org/ietf/1id-abstracts.txt 36 The list of Internet-Draft Shadow Directories can be accessed at 37 http://www.ietf.org/shadow.html. 39 Copyright 41 Copyright (C) The Internet Society 2000. 43 Abstract 45 The Internet Open Trading Protocol provides a data exchange format 46 for trading purposes while integrating existing pure payment 47 protocols seamlessly. This motivates the multiple layered system 48 architecture which consists of at least some generic IOTP application 49 core and multiple specific payment modules. 51 This document addresses the common interface between the IOTP 52 application core and the payment modules, enabling the 53 interoperability between these kinds of modules. Furthermore, such an 54 interface provides the foundations for a plug-in- mechanism in actual 55 implementations of IOTP application cores. 57 Such interfaces exist at the Consumers', the Merchants' and the 58 Payment Handlers' installations connecting the IOTP application core 59 and the payment software components/legacy systems. 61 Intended Readership 63 Software and hardware developers, development analysts, and users of 64 payment protocols. 66 Table of Contents 68 Status of this Memo........................................1 69 Copyright..................................................1 71 Abstract...................................................2 72 Intended Readership........................................2 74 Table of Contents..........................................3 75 1. Introduction............................................5 76 1.1 General payment phases................................6 77 1.2 Assumptions...........................................8 78 2. Message Flow..........................................13 79 2.1 Authentication Documentation Exchange................16 80 2.2 Brand Compilation....................................18 81 2.3 Brand Selection......................................22 82 2.4 Successful Payment...................................25 83 2.5 Payment Inquiry......................................29 84 2.6 Abnormal Transaction Processing......................30 85 2.6.1 Failures and Cancellations.........................31 86 2.6.2 Resumption.........................................32 87 2.7 IOTP Wallet Initialization...........................33 88 2.8 Payment Software Management..........................34 89 3. Mutuality.............................................34 90 3.1 Error Codes..........................................38 91 3.2 Attributes and Elements..............................48 92 3.3 Process States........................................60 93 3.3.1 Merchant............................................60 94 3.3.2 Consumer............................................62 95 3.3.3 Payment Handler.....................................64 96 4. Payment API Calls.....................................65 97 4.1 Brand Compilation Related API Calls..................65 98 4.1.1 Find Accepted Payment Brand........................65 99 4.1.2 Find Accepted Payment Protocol.....................66 100 4.1.3 Get Payment Initialization Data....................68 101 4.1.4 Inquire Authentication Challenge...................71 102 4.1.5 Authenticate.......................................72 103 4.1.6 Check Authentication Response......................73 104 4.2 Brand Selection Related API Calls....................74 105 4.2.1 Find Payment Instrument............................74 106 4.2.2 Check Payment Possibility..........................76 107 4.3 Payment Transaction Related API calls................78 108 4.3.1 Start Payment Consumer.............................78 109 4.3.2 Start Payment Payment Handler......................80 110 4.3.3 Resume Payment Consumer............................82 111 4.3.4 Resume Payment Payment Handler.....................83 112 4.3.5 Continue Process ..................................84 113 4.3.6 Change Process State...............................85 114 4.4 General Inquiry API Calls............................87 115 4.4.1 Remove Payment Log.................................87 116 4.4.2 Payment Instrument Inquiry.........................88 117 4.4.3 Inquire Pending Payment............................90 118 4.5 Payment Related Inquiry API Calls....................91 119 4.5.1 Check Payment Receipt..............................91 120 4.5.2 Expand Payment Receipt.............................92 121 4.5.3 Inquire Process State..............................93 122 4.5.4 Start Payment Inquiry..............................95 123 4.5.5 Inquire Payment Status.............................95 124 4.6 Other API Calls......................................96 125 4.6.1 Manage Payment Software............................97 126 5. Call Back Function.....................................98 127 6. Security Consideration................................100 129 Full Copyright Statement.................................101 130 References...............................................101 131 Author's Addresses.......................................102 132 Expiration and File Name.................................103 134 1. Introduction 136 Common network technologies are based on standardized and established 137 Internet technologies. The Internet technologies provide mechanisms 138 and tools for presentation, application development, network 139 infrastructure, security, and basic data exchange. 141 Due to the presence of already installed trading roles' systems with 142 their own interfaces (Internet shop, order management, payment, 143 billing, and delivery management systems, or financial institute's 144 legacy systems), IOTP has been limited to the common external 145 interface over the Internet. However, some of these internal 146 interfaces might be also standardized for better integration of IOTP 147 aware components with of the existing infrastructure and its cost 148 effective reuse. 150 The typical Payment Handlers (i.e., financial institutes or near- 151 bank organizations) as well as Merchants require an IOTP aware 152 application that easily fits into their existing financial 153 infrastructure. The Payment Handler might even insist on the reuse of 154 special in-house solutions for some subtasks of the IOTP aware 155 application, e.g., reflecting their cryptography modules, gateway 156 interfaces, or physical environment. Therefore, their IOTP aware 157 implementation really requires such clear internal interfaces. 159 More important, Consumers demand modularization and clear internal 160 interfaces: Their IOTP application aims at the support of multiple 161 payment methods. Consumers prefer the flexible use of different 162 seamless integrating payment methods within one trading application 163 with nearly identical behavior and user interface. The existence of a 164 well-defined interface enables payment software developers to bolt on 165 their components to other developer's general IOTP Application Core. 167 Initially, this consideration leads to the two-level layered view of 168 the IOTP software for each role, consisting of 170 o some generic IOTP system component, the so-called IOTP application 171 core - providing IOTP based gateway services and generic business 172 logic and 174 o the trading roles' specific back-end systems implementing the 175 specific trading transaction types' functionality. 177 In order to isolate the changes on the infrastructure, the IOTP 178 trading application has been three-layered: 180 o the IOTP Application Core processes the generic parts of the IOTP 181 transaction and holds the connection to the Internet, 183 o the Existing Legacy System or Existing Payment Software which 184 processes the actual transaction type, and particular payment 185 transaction, and 187 o the IOTP Middle-ware or IOTP Payment Bridge which glues the other 188 two possibly incompatible components. It brokers between the 189 specific interface of the Existing Legacy System and the 190 standardized interfaces of the IOTP Application Core. 192 As IOTP extends payment schemes to a trading scheme, primarily, this 193 document focuses on payment modules, i.e. the interface between the 194 IOTP Payment Bridge and the IOTP Application Core. It provides a 195 standard method for exchanging payment protocol messages between the 196 parties involved in a payment. But, it does not specify any interface 197 for order or delivery processing. 199 Such a Payment Application Programmers Interface (API) must suit for 200 a broad range of payment methods: (1) software based like Credit Card 201 SET or CyberCoin, (2) chip card based like Mondex or GeldKarte, and 202 (3) mimicries of typical and traditional payment methods like money 203 transfer, direct debit, deposit, withdrawal, money exchange and value 204 points. It should support both payments with explicit consumer 205 acknowledge and automatic repeated payments, which have been consumer 206 approved in advance. 208 The following discussion focuses on the Consumer's point of view and 209 uses the associated terminology. When switching to Merchants' or 210 Delivery Handlers' IOTP aware applications, the payment related 211 components should be implicitly renamed by Existing Legacy Systems to 212 the IOTP Middle-ware. 214 The next two sub-sections describe the general payment scenario and 215 several assumptions about the coarsely sketched software components. 217 Chapter 2 illustrates the payment transaction progress and message 218 flow of different kinds of transaction behavior. Chapters 3 to 4 219 provide the details of the API functions and Chapter 5 elaborates the 220 call back interface. 222 1.1 General payment phases 224 The following table sketches the four logical steps of many payment 225 schemes. The preceding agreements about the goods, payment method, 226 purchase amount, or delivery rules are omitted. 228 Payment State Party Example Behavior 229 ------------- ----- ---------------- 231 Mutual Payment Handler Generation of identification 232 Authentication request, solvency request, or 233 and Init- some nonce 234 ialization Consumer Responses to the requests and 235 generation of the own nonce 237 Authorization Payment Handler Generation of the authorization 238 request (for consumer) 239 Consumer Agreement to payment (by 240 reservation of the Consumer's 241 e-money) 242 Payment Handler Acceptance or rejection of the 243 agreement (consumer's 244 authorization response), 245 generation of the authorization 246 request (for issuer/acquirer), 247 and processing of its response 249 Capture Generation of the capture 250 request (for issuer/acquirer) 251 Consumer Is charged 252 Payment Handler Acceptance or rejection of the 253 e-money, close of the payment 254 transaction 256 Reversal On rejection (online/delayed): 257 generation of the reversal data 258 Consumer Receipt of the refund 260 However, some payment schemes 262 o limit themselves to one-sided authentication, 263 o perform off-line authorization without any referral to any 264 issuer/acquirer, 265 o apply capture processing in batch mode, or 266 o do not distinguish between authorization and capture, 267 o lack an inbound mechanism for reversals or implement a limited 268 variant. 270 This model applies not only to payments at the typical points of 271 sales but extends to refunds, deposits, withdrawals, electronic 272 cheques, direct debits, and money transfers. 274 1.2 Assumptions 276 In outline, the IOTP Payment Bridge processes some input sequence of 277 payment protocol messages being forwarded by the IOTP Application 278 Core. It (1) disassembles the messages, (2) maps them onto the 279 formats of the Existing Payment Software, (3) assembles its 280 responses, and (4) returns another sequence of payment protocol 281 messages that is mostly intended for transparent transmission by the 282 IOTP Application Core to some IOTP aware remote party. Normally, this 283 process continues between the two parties until the Payment Handler's 284 Payment API signals the payment termination. Exceptionally, each 285 system component may signal failures. 287 The relationship between the aforementioned components is illustrated 288 in the following figure. These components might be related to each 289 other in a flexible n-to-m-manner: 291 o One IOTP Application Core may manage multiple IOTP Payment 292 Bridges and the latter might be shared between multiple IOTP 293 Application Cores. 294 o Each Payment Bridge may manage multiple Existing Payment 295 Software modules and the latter might be shared between multiple 296 Payment Bridges. 297 o Each Existing Payment Software may manage multiple payment 298 schemes (e.g. SET) and the latter might be supported by multiple 299 Existing Payment Software modules. 300 o Each payment scheme may support multiple payment instruments 301 (e.g. particular card) or methods (e.g. Visa via SET) and the 302 latter might be shared by multiple Existing Payment Software 303 Components. 305 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 306 IOTP client (consumer) <---------------> IOTP server (merchant) 307 ( contains Internet ( contains 308 IOTP Application Core) IOTP Application Core) 309 ^ ^ 310 | IOTP Payment | IOTP Payment 311 | API | API 312 v v 313 IOTP Payment Bridge IOTP Payment Bridge 314 ^ ^ 315 | Existing Payment APIs, e.g., | 316 | SET, Mondex, etc. | 317 v v 318 Existing Payment Software Existing Payment Software 319 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 321 Figure 1: Relationship of the Components 323 The Payment API considers the following transaction types of Baseline 324 IOTP [IOTP]: 326 o Baseline Purchase, 327 o Baseline Refund, 328 o Baseline Value Exchange, 329 o Baseline Withdrawal, and 330 o Baseline (Payment) Inquiry. 332 First, the authors' vision of the IOTP aware application's and its 333 main components' capabilities are clarified: On the one hand, the 334 Payment API should be quite powerful and flexible for sufficient 335 connection of the generic and specific components. On the other hand, 336 the Payment API should not be overloaded with nice-to-haves being 337 unsupported by Existing Payment Software. 339 Despite the strong similarities on the processing of successful 340 payments, failure resolution and inquiry capabilities differ 341 extremely among different payment schemes. These aspects may even 342 vary between different payment instrument using the same payment 343 schemes. Eventually, the specific requirements of Consumers, 344 Merchants and Payment Handlers add variance and complexity. 345 Therefore, it is envisioned that the IOTP Application Core provides 346 only very basic inquiry mechanisms while complex and payment scheme 347 specific inquiries, failure analysis, and failure resolution are 348 fully deferred to the actual Existing Payment Software - including 349 the user interface. 351 The IOTP Application Core processes payments transparently, i.e., it 352 forwards the wrapped payment scheme specific messages to the 353 associated IOTP Payment Bridge/Existing Payment Software. The 354 Existing Payment Software might even use these messages for inbound 355 failure resolution. It reports only the final payment status to the 356 IOTP Application Core or some intermediate - might be also final - 357 status on abnormal interruption. 359 The IOTP Application Core implements the generic and payment scheme 360 independent part of the IOTP transaction processing and provides the 361 suitable user interface. Focusing on payment related tasks, it 363 o manages the registered IOTP Payment Bridges and provides a 364 mechanism for their registration - the latter is omitted by this 365 document. 367 o assumes that any IOTP Payment Bridge is a passive component, i.e., 368 it strictly awaits input data and generates one response to each 369 request, 371 o supports the payment negotiation (Consumer: selection of the actual 372 payment instrument or method; Merchant: selection of the payment 373 methods being offered to the Consumer) preceding the payment 374 request, 376 o requests additional payment specific support from the Existing 377 Payment Software via the selected and registered the IOTP Payment 378 Bridge, 380 o initializes and terminates the Existing Payment Software via the 381 IOTP Payment Bridge, 383 o inquires authentication data (for subsequent request or response) 384 from the Existing Payment Software, specific authentication 385 component - omitted in this document - or Consumer (by a suitable 386 user interface), 388 o supervises the online transaction process and traces its progress, 390 o stores the transaction data being exchanged over the IOTP wire - 391 payment scheme specific data is handled transparently, 393 o relates each payment transaction with multiple payment parameters 394 (IOTP Transaction Identifier, Trading Protocol Options, Payment 395 Instrument/Method, Offer Response, IOTP Payment Bridge, and Wallet 396 Identifier, associated remote Parties). The relation might be 397 lowered to the party's Payment Identifier, IOTP Payment Bridge, 398 Wallet Identifier, and the remote parties when the actual payment 399 transaction has been successfully started. 401 o implements a payment transaction progress indicator, 403 o enables the inquiry of pending and completed payment transactions, 405 o implements generic dialogs, e.g., brand selection, payment 406 acknowledge, payment suspension / cancellation, receipt 407 visualization, basic transaction inquiry, balance inquiry, or 408 receipt validation, 410 o defers payment specific processing, supervision, validation, and 411 error resolution to the Existing Payment Software. It is expected, 412 that the Existing Payment Software tries to resolve many errors 413 first by the extended exchange of Payment Exchange messages. The 414 most significant and visible failures arise from sudden 415 unavailability or lapses of the local or opposing payment 416 component. 418 o supports the invocation of any Existing Payment Software in an 419 interactive mode, which might be used (1) for the payment scheme 420 specific post-processing of a (set of) payment transactions, (2) 421 for the analysis of a payment instrument, (3) for the registration 422 of a new payment instrument/scheme, or (4) re-configuration of a 423 payment instrument/scheme. 425 o exports call back functions for use by the IOTP Payment Bridge or 426 Existing Payment Software for progress indication. 428 In addition, the IOTP Application Core 430 o manages the IOTP message components and IOTP message blocks 431 exchanged during the transaction which may be referenced and 432 accessed during the processing of subsequent messages, e.g., for 433 signature verification. In particular, it stores named Packaged 434 Content elements exchanged during payments. 436 o manages several kinds of identifiers, i.e., transaction, message, 437 component, and block identifiers, 439 o implements a message caching mechanism, 441 o detects time-outs at the protocol and API level reflecting the 442 communication with both the IOTP aware remote party and the Payment 443 API aware local periphery, e.g., chip card (reader) may raise 444 time-outs. 446 However, the IOTP Payment Bridge and Existing Payment Software do not 447 have to rely on all of these IOTP Application Core's capabilities. 448 E.g., some Consumer's Existing Payment Software may refuse the 449 disclosure of specific payment instruments at brand selection time 450 and may delay this selection to the "Check Payment Possibility" 451 invocation using its own user interface. 453 The IOTP Payment Bridge's capabilities do not only deal with actual 454 payments between the Consumer and the Payment Handler but extend to 455 the following: 457 o translation and (dis)assemblage of messages between the formats of 458 the IOTP Payment API and those of the Existing Payment Software. 459 Payment API requests and response are strictly 1-to-1 related. 461 o Consumer's payment instrument selection by the means of an 462 unsecured/public export of the relationship of payment brands, 463 payment protocols, and payment instruments (identifiers). 464 Generally, this includes not just the brand (Mondex, GeldKarte, 465 etc.) but also which specific instance of the instrument and 466 currency to use (e.g. which specific Mondex card and which currency 467 of all those available). 469 However, some Existing Payment Software may defer the selection of 470 the payment instrument to the actual payment carrying-out or it may 471 even lack any management of payment instruments. E.g., chip card 472 based payment methods may offer - Point of Sale like - implicit 473 selection of the payment instrument by simple insertion of the chip 474 card into the chip card reader or it interrogates the inserted card 475 and requests an acknowledge (or selection) of the detected payment 476 instrument(s). 478 o payment progress checks, e.g., is there enough funds available to 479 carry out the purchase, or enough funds left for the refund, 481 o IOTP Payment Receipt checks which might be performed over its 482 Packaged Content or by other means. 484 o recoding of payment scheme specific receipts into a format which 485 can be displayed to the user or printed, 487 o cancellation of payment, even though it is not complete, 489 o suspension and resumption of payment transactions. Two kinds of 490 failures the Existing Payment Software might deal with are (1) the 491 time-out of the network connection and (2) lack of funds. For 492 resolution, the IOTP Application Core may try the suspension with a 493 view to later possible resumption. 495 o recording the payment progress and status on a database. E.g., 496 information about pending payments might be used to assist their 497 continuation when the next payment protocol message is received. 499 o payment transaction status inquiry, so that the inquirer - IOTP 500 Application Core or User - can determine the appropriate next step. 502 o balance inquiry or transaction history, e.g. consumers may 503 interrogate their chip card based payment instrument or remotely 504 administer some account in advance of a payment transaction 505 acknowledge, 507 o inquiry on abnormal interrupted payment transactions, which might 508 be used by the IOTP Application Core to resolve these pending 509 transactions at startup (after power failure). 511 o payment progress indication. This could be used to inform the end 512 user of details on what is happening with the payment. 514 o payment method specific authentication methods. 516 Existing Payment Software may not provide full support of these 517 capabilities. E.g., some payment schemes may not support or even 518 prevent the explicit transaction cancellation at arbitrary phases of 519 the payment process. In this case, the IOTP Payment Bridge has to 520 implement at least skeletons that signal such lack of support by the 521 use of specific error codes (see below). 523 The Existing Payment Software's capabilities vary extremely. It 525 o supports payment scheme specific processing, supervision, 526 validation, and error resolution. It is expected, that many errors 527 are tried to be resolved first by the extended exchange of Payment 528 Exchange messages. 530 o provides hints for out-of-band failure resolution on failed inbound 531 resolution - inbound resolution is invisible to the IOTP 532 Application Core. 534 o may implement arbitrary transaction data management and inquiry 535 mechanisms ranging from no transaction recording, last transaction 536 recording, chip card deferred transaction recording, simple 537 transaction history to sophisticated persistent data management 538 with flexible user inquiry capabilities. The latter is required by 539 Payment Handlers for easy and cost effective failure resolution. 541 o implements the payment scheme specific dialog boxes. 543 Even the generic dialog boxes of the IOTP Application Core might be 544 unsuitable: Particular (business or scheme) rules may require some 545 dedicated appearance / structure / content or the dialog boxes, may 546 prohibit the unsecured export of payment instruments, or may 547 prescribe the pass phrase input under its own control. 549 2. Message Flow 551 The following lists all functions of the IOTP Payment API: 553 o Brand Compilation Related API Functions 555 "Find Accepted Payment Brand" identifies the accepted payment brands 556 for any indicated currency amount. 558 "Find Accepted Payment Protocol" identifies the accepted payment 559 protocols for any indicated currency amount (and brand) and returns 560 payment scheme specific packaged content for brand selection 561 purposes. 563 This function might be used in conjunction with the aforementioned 564 function or called without any brand identifier. 566 "Get Payment Initialization Data" returns additional payment scheme 567 specific packaged content for payment processing by the payment 568 handler. 570 "Inquire Authentication Challenge" returns the payment scheme 571 specific authentication challenge value. 573 "Check Authentication Response" verifies the returned payment scheme 574 specific authentication response value. 576 "Change Process State" is used (here only) for abnormal termination. 577 (cf. Payment Processing Related API Functions). 579 o Brand Selection Related API Functions 581 "Find Payment Instrument" identifies which instances of a payment 582 instrument of a particular payment brand are available for use in a 583 payment. 585 "Check Payment Possibility" checks whether a specific payment 586 instrument is able to perform a payment. 588 "Authenticate" forwards any payment scheme specific authentication 589 data to the IOTP Payment Bridge for processing. 591 "Change Process State" is used (here only) for abnormal termination. 592 (cf. Payment Processing Related API Functions). 594 o Payment Processing Related API Functions 596 "Start or Resume Payment Consumer/Payment Handler" initiate or resume 597 a payment transaction. There exist specific API functions for the two 598 trading roles Consumer and Payment Handler. 600 "Continue Process" forwards payment scheme specific data to the 601 Existing Payment Software and returns more payment scheme specific 602 data for transmission to the counter party. 604 "Change Process State" changes the current status of payment 605 transactions. Typically, this call is used for successful/- less 606 termination or suspension. 608 o General Inquiry API Functions 610 "Remove Payment Log" notifies the IOTP Payment Bridge that a 611 particular entry has been removed from the Payment Log of the IOTP 612 Application Core. 614 "Payment Instrument Inquiry" retrieves the properties of Payment 615 Instruments. 617 "Inquire Pending Payment" reports any abnormal interrupted payment 618 transaction known by the IOTP Payment Bridge. 620 Payment Processing Related Inquiry API Functions 621 "Check Payment Receipt" checks the consistency and validity of IOTP 622 Payment Receipts, received from the Payment Handler or returned by 623 "Inquire Process State" API calls. Typically, this function is called 624 by the Consumer during the final processing of payment transactions. 625 Nevertheless, this check might be advantageous both for Consumers and 626 Payment Handlers on failure resolution. 628 "Expand Payment Receipt" expands the Packaged Content of IOTP Payment 629 Receipts as well as payment scheme specific payment receipts into a 630 form which can be used for display or printing purposes. 632 "Inquire Process State" responds with the payment state and the IOTP 633 Payment Receipt Component. Normally, this function is called by the 634 Payment Handler for final processing of the payment transaction. 636 "Start Payment Inquiry" prepares the remote inquiry of the payment 637 transaction status and responds with payment scheme specific data 638 that might be needed by the Payment Handler for the Consumer 639 initiated inquiry processing. 641 "Inquire Payment Status" is called by the Payment Handler on Consumer 642 initiated inquiry requests. This function returns the payment scheme 643 specific content of the Inquiry Response Block. 645 "Continue Process" and "Change Process State" (cf. Payment Processing 646 Related API Calls) 648 o Other API Functions 650 "Manage Payment Software" enables the immediate activation of the 651 Existing Payment Software. Further user input is under control of the 652 Existing Payment Software. 654 "Call Back" provides a general interface for the visualization of 655 transaction progress by the IOTP Application Core. 657 The following table shows which API functions must (+), should (#), 658 or might (?) be implemented by which Trading Roles. 660 API function Consumer Payment Handler Merchant 661 ------------ -------- --------------- -------- 663 Find Accepted Payment Brand + 664 Find Accepted Payment Protocol # 665 Find Payment Instrument + 667 Get Payment Initialization Data + 668 Check Payment Possibility + 670 Start Payment Consumer + 671 Start Payment Payment Handler + 672 Resume Payment Consumer # 673 Resume Payment Payment Handler # 675 Continue Process + + 676 Inquire Process State + + ? 677 Change Process State + + ? 678 Check Payment Receipt + ? 679 Expand Payment Receipt # ? 681 Remove Payment Log ? ? ? 683 Inquire Authentication Challenge ? 684 Authenticate + 685 Check Authentication Response ? 687 Payment Instrument Inquiry ? 688 Inquire Pending Payment # # 689 Start Payment Inquiry ? 690 Inquire Payment Status ? 692 Manage Payment Software # ? ? 694 Call Back # 695 Table 1: Requirements on API Functions by the Trading Roles 697 The next sections sketch the relationships and the dependencies 698 between the API functions. They provide the informal description of 699 the progress alternatives and depict the communication and 700 synchronization between the general IOTP Application Core and the 701 payment scheme specific modules. 703 2.1 Authentication Documentation Exchange 705 This section describes how the functions in this document are used 706 together to process authentication. 708 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 709 Authenticator Inquire Authentication Challenge(Alg1*) -> IPB 710 Inq. Auth. Challenge Response(Alg1,Ch1) <- IPB 711 . . . 712 Inquire Authentication Challenge(Algn*) -> IPB 713 Inq. Auth. Challenge Response(Algn,Chn) <- IPB 714 Create and transmit Authentication Request Block 715 Authenticatee Authenticate(Alg1, Ch1) -> IPB 716 AuthenticateResponse(...) <- IPB 717 . . . 718 Authenticate(Algm, Chm) -> IPB 719 AuthenticateResponse(Res) <- IPB 720 Create and transmit Authentication Response Block 721 Authenticator Check Authentication Response(Algm,Chm,Res)->IPB 722 Check Auth. Response() <-IPB 723 Create and transmit Authentication Status Block 724 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 726 Figure 2. Authentication Message Flows 728 1. (Authenticator Process) None, one or multiple IOTP Payment Bridges 729 (IPB) are requested for one or multiple authentication challenge 730 values ("Inquire Authentication Challenge"). Each value is 731 encapsulated in an IOTP Authentication Request Component. In 732 addition, the IOTP Application Core may add payment scheme 733 independent authentication methods. All of them form the final 734 IOTP Authentication Request Block, which describes the set of 735 authentication methods being supported by the authenticator and 736 from which the Authenticatee has to choose one method. 738 Note that the interface of the API function is limited to the 739 response of exactly one algorithm per call. If the IOTP 740 Application Core provides a choice of algorithms for input, this 741 choice should be reduced successively by the returned algorithm 742 ({Alg(i+1)*} is subset of {Algi*}). 744 During the registration of new Payment Instruments, the IOTP 745 Payment Bridge notifies the IOTP Application Core about the 746 supported authentication algorithms. 748 2. On presence of an IOTP Authentication Block within the received 749 IOTP message, the Authenticatee's IOTP Application Core checks 750 whether the IOTP transaction type in the current phase actually 751 supports the authentication process. 753 For each provided Authentication Request Component, the IOTP 754 Application Core analyzes the algorithms' names, the transaction 755 context, and optionally user preferences in order to determine the 756 system components which are capable to process the authentication 757 request items. Such system components might be the IOTP 758 Application Core itself or any of the registered IOTP Payment 759 Bridges. 761 Subsequently, the IOTP Application Core requests the responses to 762 the supplied challenges from the determined system components in 763 any order. The authentication trials stop with the first 764 successful response, which is included in the IOTP Authentication 765 Response Block. 767 Alternatively, the IOTP Application might ask for a user 768 selection. This might be appropriate, if two or more 769 authentication algorithms are received that require explicit user 770 interaction, like PIN or chip card insertion. 772 The Authenticatee's organizational data is requested by an IOTP 773 Authentication Request Block without any content element. On 774 failure, the authentication (sequence) might be retried, or the 775 whole transaction might be suspended or cancelled. 777 3. (Authenticator Process) The IOTP Application Core checks the 778 presence of the IOTP Authentication Response Component in the 779 Authentication Response Block and forwards its content to the 780 generator of the associated authentication challenge for 781 verification ("Check Authentication Response"). 783 On sole organizational data request, its presence is checked. 785 Any verification must succeed in order to proceed with the 786 transaction. 788 2.2 Brand Compilation 790 The following shows how the API functions are used together so that 791 the Merchant can (1) compile the Brand List Component, (2) generate 792 the Payment Component, and (3) adjust the Order Component with 793 payment scheme specific packaged content. 795 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 796 Merchant For each registered IOTP Payment Bridge 797 | Find Accepted Payment Brand() -> IPB 798 | Find Accepted Payment Brand Response (B*) <- IPB 799 | Find Accepted Payment Protocol(B1) -> IPB 800 | Find Accepted Payment Protocol Res.(P1*) <- IPB 801 | . . . 802 | Find Accepted Payment Protocol(Bn) -> IPB 803 | Find Accepted Payment Protocol Res.(Pn*) <- IPB 804 Create one Brand List Component, ideally sharing 805 common Brand, Protocol Amount, Currency Amount, 806 and Pay Protocol Elements 807 Create Trading Protocol Options Block 808 On brand independent transactions 809 | Create Brand Selection Component, implicitly 810 | Get Payment Initialization Data(B1,P1) -> IPB 811 | Get Payment Initialization Data Res.() <- IPB 812 | Optionally 813 | | Inquire Process State() -> IPB 814 | | Inquire Process State Response(State) <- IPB 815 | Create Offer Response Block 816 Transmit newly created Block(s) 817 Consumer Consumer selects Brand (Bi)/Currency/Protocol (Pj) 818 from those that will work and generates Brand 819 Selection Component - at least logically 820 On brand dependent transaction 821 | Transmit Brand Selection Component 822 Merchant On brand dependent transaction 823 | Get Payment Initialization Data(Bi,Pj) -> IPB 824 | Get Payment Initialization Data Res.() <- IPB 825 | Optionally 826 | | Inquire Process State() -> IPB 827 | | Inquire Process State Response(State) <- IPB 828 | Create Offer Response Block 829 | Transmit newly created Block 830 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 832 Figure 3. Brand Compilation Message Flows 834 1. The Merchant's commerce server controls the shopping dialog with 835 its own mechanisms until the Consumer checks out the shopping cart 836 and indicates the payment intention. The notion shopping subsumes 837 any non-IOTP based visit of the Merchant Trading Role's (which 838 subsumes Financial Institutes) web site in order to negotiate the 839 content of the IOTP Order Component. The subsequent processing 840 switches to the IOTP based form by the activation of the 841 Merchant's IOTP aware application. 843 2. The IOTP Application Core inquires the IOTP level trading 844 parameters (Consumer's shopping identifier, payment direction, 845 initial currency amounts, discount rates, Merchant's and Delivery 846 Handler's Net Locations, Non-Payment Handler's Organizational 847 Data, initial order information, ....). 849 3. The registered IOTP Payment Bridges are inquired by the IOTP 850 Application Core about the accepted payment brands ("Find Accepted 851 Payment Brand"). Their responses provide most of the attribute 852 values for the compilation of the Brand List Component's Brand 853 Elements. The IOTP Application Core might optionally match the 854 returned payment brands with Merchant's general preferences. 856 The IOTP Application Core must provide any wallet identifiers, if 857 they are required by the IOTP Payment Bridges which signal their 858 need by specific error codes (see below). Any signaled error that 859 could not immediately solved by the IOTP Application Core should 860 be logged - this applies also to the subsequent API calls of this 861 section. In this case, the IOTP Application Core creates an IOTP 862 Error Block (hard error), transmits it to the Consumer, and 863 terminates the current transaction. 865 4. The IOTP Application Core interrogates the IOTP Payment Bridges 866 for each accepted payment brand about the supported payment 867 protocols ("Find Accepted Payment Protocol"). These responses 868 provide the remaining attribute values of the Brand Elements as 869 well as all attribute values for the compilation of the Brand List 870 Component's Protocol Amount and Pay Protocol Elements. 871 Furthermore, the organisational data about the Payment Handler is 872 returned. The IOTP Application Core might optionally match the 873 returned payment brands with Merchant's general preferences. 875 Alternatively, the IOTP Application Core might skip the calls of 876 "Find Accepted Payment Brands" (cf. Step 3) and issue the "Find 877 Accepted Payment Protocol" call without any Brand given on the 878 input parameter list. In this case, the IOTP Payment Bridge 879 responds on the latter call with the whole set of payment schemes 880 supported w.r.t. the other input parameters. 882 5. The steps 3 and 4 are repeated during IOTP Value Exchange 883 transactions - these steps are omitted in the previous figure. 885 6. The IOTP Application Core compiles the Brand List Component(s) and 886 the IOTP Trading Protocol Options Block. It is recommended that 887 "equal" items returned by IOTP Payment Bridge function calls are 888 shared due to the extensive linking capabilities within the Brand 889 List Component. However, the compilation must consider several 890 aspects in order to prevent conflicts - sharing detection might be 891 textual matching (after normalization): 893 o Packaged Content Elements contained in the Brand List 894 Component (and subsequently generated Payment and Order 895 Components) might be payment scheme specific and might depend 896 on each other. 898 o Currently, IOTP lacks precise rules for the content of the 899 Packaged Content Element. Therefore, transaction / brand / 900 protocol / currency amount (in)dependent data might share the 901 same Packaged Content Element or might spread across multiple 902 Packaged Content Elements. 904 o The Consumer's IOTP Application Core transparently passes the 905 Packaged Content Elements to the IOTP Payment Bridges which 906 might not be able to handle payment scheme data of other 907 payment schemes, accurately. 909 The rules and mechanisms of how this could be accomplished are out 910 of the scope of this document. Furthermore, this document does not 911 define any further restriction to the IOTP specification. 913 7. The IOTP Application Core determines whether the IOTP message can 914 be enriched with an Offer Response Block. This is valid under the 915 following conditions: 917 o All payment alternatives share the attribute values and 918 Packaged Content Elements of the subsequently generated IOTP 919 Payment and Order Components. 921 o The subsequently generated data does not depend on any IOTP 922 BrandSelInfo Elements that might be reported by the consumer 923 within the TPO Selection Block in the brand dependent 924 variant. 926 If both conditions are fulfilled, the IOTP Application Core might 927 request the remaining payment scheme specific payment 928 initialization data from the IOTP Payment Bridge ("Get Payment 929 Initialization Data") and compile the IOTP Offer Response Block. 931 Optionally, the IOTP Application Core might request the current 932 process state from the IOTP Payment Bridge and add the inferred 933 order status to the IOTP Offer Response Block. Alternatively, IOTP 934 Application might determine the order status on its own. 936 As in step 6, the rules and mechanisms of how this could be 937 accomplished are out of the scope of this document. 939 8. The IOTP Application Core compiles the IOTP TPO Message including 940 all compiled IOTP Blocks and transmits the message to the 941 Consumer. The IOTP Application Core terminates if an IOTP Offer 942 Response Block has been created. 944 9. The Consumer performs the Brand Selection Steps (cf. Section 2.3) 945 and responds with a TPO Selection Block if no IOTP Offer Response 946 Block has been received. Otherwise, the following step is skipped. 948 10. On brand dependent transactions, the IOTP Application Core 949 requests the remaining payment scheme specific payment 950 initialization data from the IOTP Payment Bridge ("Get Payment 951 Initialization Data"), compiles the IOTP Offer Response Block, 952 transmits it to the Consumer, and terminates. Like Step 7, the 953 IOTP Application Core might access the current process state of 954 the IOTP Payment Bridge for the compilation of the order status. 956 Any error during this process raises an IOTP Error Block. 958 2.3 Brand Selection 960 This section describes the steps that happen mainly after the 961 Merchant's Brand Compilation (in a brand independent transaction). 962 However, these steps might partially interlace the previous process 963 (in a brand dependent transaction). 965 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 966 Merchant Merchant generates Brand List(s) containing 967 Brands, Payment Protocols and Currency Amounts 968 On brand independent transactions 969 | Merchant generates Offer Response Block 970 Consumer Compile set(s) of Brands B/Protocols P 971 for each set 972 | Find Payment Instrument(B, P, C) -> IPB 973 | Find Payment Instrument Response (PI*) <- IPB 974 Consumer selects Brand/Currency/Payment Instrument 975 from those that will work and generates Brand 976 Selection Component 977 For the Selection 978 | Get Payment Initialization Data(B,C,PI,P) -> IPB 979 | Get Payment Initialization Data Response()<- IPB 980 On brand dependent transaction 981 | Generate and transmit TPO Selection Block 982 Merchant On brand dependent transaction 983 | Merchant checks Brand Selection and generates 984 | and transmits Offer Response Block 985 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 987 Figure 4. Brand Selection Message Flows 989 1. The Merchant's commerce server controls the shopping dialog with 990 its own mechanisms until the Consumer checks out the shopping cart 991 and indicates his payment intention. The subsequent processing 992 switches to the IOTP based form by the activation of the 993 Merchant's IOTP aware application. 995 2. The IOTP Application Core compiles the IOTP Trading Protocol 996 Options Block which contains the IOTP Brand List Component(s) 997 enumerating Merchant's accepted payment brands and payment 998 protocols and initiates the Brand Selection process. 1000 3. This first IOTP message activates the Consumer's IOTP aware 1001 application, e.g., the Web browser invokes a helper application 1002 (e.g., Java applet or external application). Its IOTP Application 1003 Core 1004 o infers the accepted payment brands, payment protocols, 1005 payment direction, currencies, payment amounts, any 1006 descriptions etc., and their relationships from the IOTP 1007 message, 1009 o determines the registered IOTP Payment Bridges, 1011 o compiles one or multiple set of brand and protocol such that 1012 the join of all set describes exactly the set of payment 1013 alternatives being offered by the Merchant. 1015 o inquires payment (protocol) support and the known payment 1016 instruments from each registered IOTP Payment Bridge for each 1017 compiled set ("Find Payment Instrument"). However, some IOTP 1018 Payment Bridges may refuse payment instrument distinction. 1020 The payment protocol support may differ between payment 1021 instruments if the IOTP Payment Bridge supports payment instrument 1022 distinction. 1024 These API calls are used to infer the payment alternatives at the 1025 startup of any payment transaction (without user unfriendly 1026 explicit user interaction). 1028 The IOTP Application Core must provide wallet identifiers, if they 1029 are requested by the IOTP Payment Bridges which signal their need 1030 by specific error codes (see below). 1032 It is recommended that the IOTP Application Core manages wallet 1033 identifiers. But for security reasons, it should store pass 1034 phrases in plain text only in runtime memory. Developers of IOTP 1035 Payment Bridges and payment software modules should provide a thin 1036 and fast implementation - without lengthy initialization 1037 processes- for this initial inquiry step. 1039 4. The IOTP Application Core verifies the Consumer's payment 1040 capabilities with the Merchant's accepted payment brands and 1041 currencies, 1043 o displays the valid payment instruments and payment instrument 1044 independent payment brands (brand and protocol) together with 1045 their purchase parameters (payment direction, currency, 1046 amount), and 1048 o requests the Consumer's choice or derives it automatically 1049 from any configured preferences. Any selection ties one IOTP 1050 Payment Bridge with the following payment transaction. 1052 The handling and resolution of unavailable IOTP Payment Bridges 1053 during the inquiry in Step 3 is up to the IOTP Application Core. 1055 It may skip these IOTP Payment Bridges or may allow user supported 1056 resolution. 1058 Furthermore, it may offer the registration of new payment 1059 instruments when the Consumer is requested for payment instrument 1060 selection. 1062 5. The IOTP Application Core interrogates the fixed IOTP Payment 1063 Bridge whether the payment might complete with success ("Check 1064 Payment Possibility"). At this step, the IOTP Payment Bridge may 1065 issue several signals, e.g., 1067 o payment can proceed immediately, 1068 o required peripheral inclusive some required physical payment 1069 instrument (chip card) is unavailable, 1070 o (non-IOTP) remote party (e.g. issuer, server wallet) is not 1071 available, 1072 o wallet identifier or pass phrase is required, 1073 o expired payment instrument (or certificate), insufficient 1074 funds, or 1075 o physical payment instrument unreadable. 1077 In any erroneous case, the user should be notified and offered 1078 accurate alternatives. Most probably, the user might be 1079 recommended 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 genuine payment legacy 1157 systems have not 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 payment protocol 1185 descriptions from the IOTP Protocol Amount Element, and IOTP 1186 Pay Protocol Element, and 1187 o payment scheme specific data inclusive payment protocol 1188 descriptions, in which the name attribute includes the prefix 1189 as "Payment:" from the Trading Role Data Component. 1191 Generally, the called API function re-does most checks of the 1192 "Check Payment Possibility" call due to lack of strong 1193 dependencies between both requests: There might be a significant 1194 delay between both API requests. 1196 The called API function may return further payment scheme specific 1197 data being considered as payment specific initialization data for 1198 the Payment Handler's IOTP Payment Bridge. 1200 If the fixed Existing Payment Software implements payment 1201 instrument selection on its own, it may request the Consumer's 1202 choice at this step. 1204 The IOTP Payment Bridge reports lack of capability quite similar 1205 to the "Check Payment Possibility" request to the IOTP Application 1206 Core. The Consumer may decide to resolve the problem, to suspend, 1207 or to cancel the transaction, but this function call must succeed 1208 in order to proceed with the transaction. 1210 Developers of payment modules may decide to omit payment 1211 instrument related checks like expiration date or refunds 1212 sufficiency, if they are part of the specific payment protocol. 1214 If the IOTP Payment Bridge requests wallet identifiers or pass 1215 phrases anywhere during the payment process, they should be 1216 requested by this API function, too. It is recommended that the 1217 IOTP Application Core stores plain text pass phrases only in 1218 runtime memory. 1220 Finally, the IOTP Application Core generates the IOTP Payment 1221 Request Block, inserts any returned payment scheme data, and 1222 submits it to the Payment Handler's system. 1224 3. The Payment Handler's IOTP Application Core opens the payment 1225 transaction calling the "Start Payment Payment Handler" API 1226 function. The payment brand, its description, payment protocol, 1227 payment specific data, payment direction, currency and payment 1228 amount are determined quite similar to the Consumer's IOTP 1229 Application Core. Furthermore, the content of the IOTP Payment 1230 Scheme Component and the IOTP Brand Selection Info Elements are 1231 passed to this function. 1233 On success, the Payment Handler's IOTP Payment Bridge responds 1234 with payment scheme specific data. On failures, this non- 1235 interactive server application has to resolve any problems on its 1236 own or to give up aborting the payment transaction. However, the 1237 Consumer may restart the whole payment transaction. Anyway, the 1238 payment log file should reflect any trials of payments. 1240 Eventually, the Payment Handler informs the Consumer about the 1241 current IOTP Process State using the IOTP Payment Response or IOTP 1242 Error Block. 1244 Note that the "Start Payment Payment Handler" call might return 1245 the Continuation Status "End" such that payment processing 1246 proceeds with Step 7. 1248 4. The IOTP Application Core verifies the presence of the Payment 1249 Exchange Block in the IOTP message and passes the contained 1250 payment scheme specific data to the fixed IOTP Payment Bridge 1251 ("Continue Process") which returns the next IOTP Payment Scheme 1252 Component. 1254 This Payment Scheme Component is encapsulated in an IOTP Payment 1255 Exchange Block and transmitted to the Payment Handler. 1257 5. The Payment Handler's IOTP Application Core verifies the presence 1258 of the Payment Exchange Block and passes the contained payment 1259 scheme specific data to the fixed IOTP Payment Bridge ("Continue 1260 Process") which returns the next IOTP Payment Scheme Component for 1261 encapsulation and transmission to the Consumer. 1263 6. The payment process continues with IOTP Payment Exchange Block 1264 exchanges, carrying the payment scheme specific data. Each party 1265 (1) submits the embedded payment scheme specific data 1266 transparently to the appropriate IOTP Payment Bridge calling the 1267 "Continue Process" API function, (2) wraps the returned payment 1268 scheme specific data into an IOTP Payment Exchange Block, and (3) 1269 transmits this block to the counter party. 1271 However, the processing of the payment scheme specific data may 1272 fail for several reasons signaled by specific error codes which 1273 are transformed to IOTP Payment Response Blocks (generated by 1274 Payment Handler) or IOTP Error Blocks (both parties may generate 1275 them) and transmitted to the counter party. 1277 7. Eventually, the Payment Handler's IOTP Payment Bridge recognizes 1278 the termination of the payment transaction and reports this by the 1279 continuation status "End" on the output parameter of "Continue 1280 Process" (or "Start Payment Payment Handler"). Then, the IOTP 1281 Application Core issues the "Inquire Process State" API call and 1282 verifies whether an IOTP Payment Receipt Component has been 1283 returned. The IOTP Application Core wraps the payment receipt, the 1284 status response, and the optional payment scheme specific data in 1285 an IOTP Payment Response Block and transmits this block to the 1286 Consumer. 1288 However, any of these API calls may fail or any response might be 1289 incomplete (e.g., lack of payment receipt). Then, the Consumer has 1290 to be notified about the failed processing by an IOTP Error Block. 1292 Finally, the Payment Handler terminates the payment transaction 1293 with the "Change Process State" API call without awaiting any 1294 further response from the Consumer. Further failures are not 1295 reported to the Consumer. 1297 Note that it might be possible that the Consumer's IOTP Payment 1298 Bridge has returned the previous payment scheme specific data with 1299 the continuation status "End". Even in the absence of this 1300 knowledge - this status is not exchanged between the Consumer and 1301 the Payment Handler - the Payment Handler must not supply any 1302 further payment scheme specific data. Such data will be rejected 1303 by the Consumer's IOTP Payment Bridge. 1305 8. The Consumer passes the optional payment scheme specific data and 1306 the payment receipt to the fixed IOTP Payment Bridge by "Continue 1307 Process" and "Check Payment Receipt" API calls. 1309 Afterwards, the IOTP Application Core issues the "Inquire Process 1310 State" API call and verifies whether extensions to the payment 1311 receipt have been returned. 1313 Finally, the transaction is terminated by calling the "Change 1314 Process State" API function which verifies and synchronizes the 1315 reported payment status with the local one and signals any 1316 inconsistencies. Any Inconsistency and returned status text should 1317 be displayed to the Consumer. 1319 At this point, the payment transaction has already been closed by 1320 the Payment Handler. Therefore, any failure has to be resolved 1321 locally or out-of-band. 1323 2.5 Payment Inquiry 1325 In Baseline IOTP, Payment inquiries are initiated by the Consumer in 1326 order to verify the current payment progress and process state at the 1327 remote Payment Handler. 1329 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1330 Consumer Start Payment Inquiry() -> IPB 1331 Start Payment Inquiry Response([PS1]) <- IPB 1332 Create and transmit Inquiry Request Trading Block 1333 Payment Handler Inquire Payment Status([PS1]) -> IPB 1334 Inquire Payment Status Res.(State, [PS2]) -> IPB 1335 Create and transmit Inquiry Response Trading 1336 Block 1337 Consumer If Payment Scheme Data present 1338 | Continue Process(PS2) -> IPB 1339 | Continue Process Response(CS=End) <- IPB 1340 Change Process State(State) -> IPB 1341 Change Process State Response(State) <- IPB 1342 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1344 Figure 6. Remote Process State Inquiry 1346 1. The Consumer might initiate a payment inquiry once the payment 1347 transaction has been opened by the IOTP Application Core, i.e., at 1348 any time after the initial submission of the IOTP Payment Request 1349 Block. The IOTP Application Core requests any additional specific 1350 payment scheme data from the IOTP Payment Bridge which has been 1351 fixed during brand selection (cf. Section 2.3) using the "Start 1352 Payment Inquiry" API request. 1354 Erroneous API responses should be reported to the Consumer and 1355 valid alternatives (typically retry and cancellation) should be 1356 presented by the IOTP Application Core. 1358 This request might perform the complete initialization, e.g. 1359 availability check of periphery or pass phrase supplement, and the 1360 IOTP Payment Bridge reports lack of capability quite similar to 1361 the "Check Payment Possibility" request to the IOTP Application 1362 Core. 1364 If the IOTP Payment Bridge requests wallet identifiers or pass 1365 phrases anywhere during the payment process, they should be 1366 requested by this API function, too. It is recommended that the 1367 IOTP Application Core stores plain text pass phrases only in 1368 runtime memory. 1370 The IOTP Application Core encapsulates any Payment Scheme 1371 Component in an IOTP Inquiry Request Block and submits the block 1372 to the Payment Handler. 1374 2. The Payment Handler analyses the IOTP Inquire Request Block, maps 1375 the Transaction Identifier to payment related attributes (brand, 1376 consumer and payment identifiers), determines the appropriate IOTP 1377 Payment Bridge, and forwards the request to the this IOTP Payment 1378 Bridge ("Inquire Payment Status"). The IOTP Application Core 1379 transforms the response to an IOTP Inquiry Response Block and 1380 transmits it to the Consumer. 1382 3. On receipt of the respective IOTP Inquiry Response Block the 1383 Consumer's IOTP Application Core submits any encapsulated payment 1384 scheme specific data to the IOTP Payment Bridge for verification 1385 ("Continue Process"). 1387 4. The IOTP Application Core passes the reported payment status 1388 (except textual descriptions) to the IOTP Payment Bridge ("Change 1389 Process State") for verification purposes and payment status 1390 change. The IOTP Payment Bridge reports any inconsistencies as 1391 well as the final payment status to the IOTP Application Core. 1393 Any additional information that might be of interest for the 1394 Consumer has to be displayed by the IOTP Payment Bridge or 1395 Existing Payment Software on their own. 1397 2.6 Abnormal Transaction Processing 1398 2.6.1 Failures and Cancellations 1400 The IOTP specification distinguishes between several classes of 1401 failures: 1403 o Business and technical errors 1404 o Error depth on transport, message and block level 1405 o Transient errors, warnings, and hard errors. 1407 Any IOTP Payment API has to deal with the receipt of failure 1408 notifications by and failure responses. This proposal has borrowed 1409 the basic mechanisms for error reporting between the IOTP Application 1410 Core and the IOTP Payment Bridge from the genuine protocol: Business 1411 errors are reported by Status Components within IOTP Response Blocks 1412 while technical errors are signaled by Error Components within IOTP 1413 Error Blocks. 1415 Cancellations are mimicked as specific business errors which might be 1416 initiated by each trading party. 1418 Preferring slim interfaces, this IOTP Payment API introduces one 1419 additional Error Code value for business error indication - errors 1420 can be raised on every API call. On receipt of this value, the IOTP 1421 Application Core has to infer further details by the issuance of the 1422 API function call "Inquire Process State". 1424 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1425 Any Party Issue some API request -> IPB 1426 Error Response(Error Code) <- IPB 1427 On "Business Error" response 1428 | Inquire Process State() -> IPB 1429 | Inquire P.S. Resp.(State, Receipt) <- IPB 1430 Analyze local process state and try to resolve 1431 with optional user interaction 1432 If Process State Change needed 1433 | Change Process State (State) -> IPB 1434 | Change Process State Response(State) <- IPB 1435 If counter party's notification required 1436 | Create Error or Cancel Block (, add to next 1437 | message, ) and transmit it to counter party 1438 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1440 Figure 7. Error Response from IPB 1442 The specific Completion Codes "ConsCancelled", "MerchCancelled", and 1443 "PaymCancelled" - returned by "Inquire Process State" - determine 1444 that the IOTP Cancel Block has to be created instead of an IOTP Error 1445 Block. 1447 The rules for determining the required behavior of the IOTP 1448 Application Core are given in the IOTP specification. 1450 Note that any payment (intermediate) termination, i.e., failures, 1451 cancellations, and even success's is always reported to the IOTP 1452 Payment Bridge by the API function "Change Process State". This API 1453 function does both status changes and consistency checking / 1454 synchronization. Any suspicion of inconsistency should be reported by 1455 the IOTP Payment Bridge for display by the IOTP Application Core. 1457 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1458 Any Party Error Block or Cancel Block Received 1459 If Change Process State required 1460 | Change Process State (State) -> IPB 1461 | Change Process State Response(State) <- IPB 1462 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1464 Figure 8. Error Notification from counter party 1466 Not every failure might be visible at the IOTP layer, e.g., the 1467 processing of payment transactions might temporarily be hampered by 1468 intermediate failures at the payment scheme or protocol transport 1469 layer which might be resolved by the genuine components. 1471 However, final failures or cancellations have to be reported at the 1472 IOTP layer. E.g., communication time-outs and heavily faulty 1473 communication channels may disable the transaction. 1475 Any system component may implement time-out recognition and use the 1476 aforementioned API mechanisms for the notification of process state 1477 changes. But, time-outs may happens while communicating with both the 1478 counter party and local system components, like chip card readers or 1479 IOTP Payment Bridges. Anyway, the Consumer's IOTP Application Core 1480 should notify the Consumer about the resolution alternatives, i.e., 1481 retry, suspension, and cancellation. 1483 2.6.2 Resumption 1485 Payment transaction resumption may apply at different steps of a 1486 payment transaction: 1488 o The Consumer's and Payment Handler's view of the transaction might 1489 not be synchronized: Due to different time-out values the payment 1490 transaction may not have been suspended by the counter party. 1492 Any "Resume Payment ..." API function responds with an Error Code 1493 on non suspended payment transaction that signals a business error. 1494 Afterwards the IOTP Application Core has to issue the "Inquire 1495 Process State" API call for further analysis of the process state. 1497 o One IOTP message sent by one party might not be processed 1498 successfully or even received by the counter party. 1500 This needs to be handled by the genuine payment scheme. It is 1501 expected that the IOTP Application Core will not recognize 1502 anything. 1504 o IOTP does not provide any specific signal for payment resumption. 1505 On receipt of every IOTP Payment Exchange Block, the IOTP 1506 Application Core has to decide whether this Block belongs to a 1507 pending transaction or to a suspended transaction that should be 1508 resumed. The IOTP Application Core might call the "Inquire Process 1509 State" API function to update any lack of knowledge. 1511 Any "Resume Payment" API function responds with an Error Code on 1512 non suspended payment transaction that signals a business error. 1513 Similar, the "Continue Process" API function should report business 1514 errors on non pending payment transactions. 1516 o The payment transaction may not have been created at the Payment 1517 Handler (early suspension and failed data transmission). In that 1518 case, the IOTP Application Core should respond with a business 1519 error that signals the repetition of the payment transaction (by 1520 the Consumer). 1522 Any "Resume Payment", "Continue Process" or "Inquire Process State" 1523 API function should return with an Error Code "AttValIllegal" on 1524 non existent payment transaction whereby the further Error 1525 Attribute "Names" denote the payment identifier. 1527 o The IOTP Application Core should always request fresh payment 1528 scheme specific data on resumption - for synchronization purposes 1529 with the Existing Payment Software. Old data in the cache that has 1530 not been send to the counter party should not be accessed. 1532 If the Consumer does not reconnect within an acceptable amount of 1533 time, the Payment Handler's system may perform local failure 1534 resolution in order to close the transaction and to retain resources 1535 for other transactions ("Change Process State"). If the Consumer 1536 reconnect afterwards, an IOTP Payment Response or IOTP Error Block 1537 could be generated. 1539 2.7 IOTP Wallet Initialization 1541 At startup or on explicit user request the IOTP Application Core 1542 should check its IOTP Payment Bridges' internal status by searching 1543 for pending payment transactions. 1545 1. The IOTP Application Core interrogates the registered IOTP 1546 Payment Bridges about pending payment transactions. The IOTP 1547 Application Core may store indicators for pending transactions and 1548 use them for driving any subsequent inquiry ("Inquire Pending 1549 Payment"). 1551 2. If one or more IOTP Payment Bridges report the presence of pending 1552 transactions, the IOTP Application Core may try to suspend 1553 ("Change Process State") or resume (only Consumer: "Resume Payment 1554 Consumer") the pending transactions (on user request). 1556 The IOTP Payment Bridge may deny the processing of any new payment 1557 transactions until the pending transactions have been processed. Such 1558 denials are signaled by the error code "Business Error". 1560 2.8 Payment Software Management 1562 The IOTP Application Core provides only a simple and generic 1563 interface for the registration of new payment methods / instruments 1564 ("Manage Payment Software"). It receives the initial user request and 1565 defers the actual registration to the corresponding IOTP Payment 1566 Bridge. 1568 The IOTP Application Core may also activate the Existing Payment 1569 Software for further payment instrument and wallet administration. 1571 3. Mutuality 1573 The Payment API is formalized using the Extensible Markup Language 1574 (XML). It defines wrapper elements for both the input parameters and 1575 the API function's response. In particular, the response wrapper 1576 provides common locations for Error Codes and Error Descriptions. 1578 It is anticipated that this description reflects the logical 1579 structure of the API parameter and might be used to derive 1580 implementation language specific API definitions. 1582 XML definition: 1584 1610 1616 1642 1648 1649 1659 Most of the attribute items are intended for immediate insertion in 1660 the IOTP Error Block. The attribute values of the Error Location 1661 elements attribute have to enriched and transformed into Error 1662 Location Elements of the Error Component (cf. IOTP Specification). 1664 Attributes (cf. IOTP Specification): 1666 xml:lang Defines the language used by attributes or 1667 child elements within this component, unless 1668 overridden by an xml:lang attribute on a child 1669 element. 1671 ContentSoftwareId Contains information which identifies the 1672 software that generated the content of the 1673 element. Its purpose is to help resolve 1674 interoperability problems that might occur as 1675 a result of incompatibilities between messages 1676 produced by different software. It is a single 1677 text string in the language defined by 1678 "xml:lang". It must contain, as a minimum 1679 problems that might occur as a result of 1681 o the name of the software manufacturer, 1682 o the name of the software, 1683 o the version of the software, and 1684 o the build of the software. 1686 ErrorCode Contains an error code which indicates the 1687 nature of the error in the message in error. 1688 Valid values for the Error Code are given in 1689 the following section. This mnemonic enables 1690 the automatic failure resolution of the IOTP 1691 Application Core which analyzes the error code 1692 value in order to determine the continuation 1693 alternatives. 1695 ErrorDesc Contains a description of the error in the 1696 language defined by xml:lang. The content of 1697 this attribute is defined by the 1698 vendor/developer of the software that 1699 generated the Error Response Element. 1700 It is intended for user display and provides 1701 detailed explanations about the failure and 1702 its (out-of-band) resolution alternatives. 1704 Severity Indicates the severity of the error. Valid 1705 values are: 1707 o Warning. This indicates that although there 1708 is a message in error the IOTP Transaction 1709 can still continue. 1711 o TransientError. This indicates that the 1712 error in the message in error may be 1713 recovered if the message in error that is 1714 referred to by the "Names" attribute is 1715 resent. 1717 o HardError. This indicates that there is an 1718 unrecoverable error in the message in error 1719 and the IOTP Transaction must stop. 1721 MinRetrySecs This attribute should be present if "Severity" 1722 is set to "TransientError". It is the minimum 1723 number of whole seconds which the IOTP aware 1724 application which received the message 1725 reporting the error should wait before re- 1726 sending the message in error identified by the 1727 "ErrorLocation" attribute. 1729 If Severity is not set to 1730 "TransientError" then the value of this 1731 attribute is ignored. 1733 SwVendorErrorRef This attribute is a reference whose value is 1734 set by the vendor/developer of the software 1735 that generated the Error Element. It should 1736 contain data that enables the vendor to 1737 identify the precise location in their 1738 software and the set of circumstances that 1739 caused the software to generate a message 1740 reporting the error. 1742 Content: 1744 ErrorLocation This identifies, where possible, the 1745 element and attribute in the message 1746 in error that caused the Error 1747 Element to be generated. If the 1748 "Severity" of the error is not 1749 "TransientError", more that one 1750 "ErrorLocation" may be specified as 1751 appropriate depending on the nature 1752 of the error and at the discretion of 1753 the vendor/developer of the IOTP 1754 Payment Bridge. 1756 Its definition coincides with the 1757 IOTP specification whereby the 1758 attributes "IotpMsgRef", "BlkRef" and 1759 "CompRef" are left blank, 1760 intentionally. 1762 PaySchemePackagedContent cf. Table 5 1764 3.1 Error Codes 1766 The following table lists the valid values for the ErrorCode 1767 attribute of the Error Response Element. The first sentence of the 1768 error description contains the default text that can be used to 1769 describe the error when displayed or otherwise reported. Individual 1770 implementations may translate this into alternative languages at 1771 their discretion. However, not every error code may apply to every 1772 API call. An Error Code must not be more than 14 characters long. 1774 The Error Codes have been taken from the IOTP Specification and 1775 extended by some additional codes which are highlighted by a 1776 preceding asterisk. 1778 Generally, if the corrupt values have been user supplied, the IOTP 1779 Application Core might prompt for their correction. If the renewal 1780 fails or if the IOTP Application Core skips any renewals and some 1781 notification has to be send to the counter-party, the error code is 1782 encapsulated within an IOTP Error Block. 1784 However, the IOTP server application reports business errors - 1785 visible at the IOTP layer - in the Status Component of the respective 1786 Response Block. 1788 The IOTP Application Core may add the attributes (and values) within 1789 the ErrorLocation elements being omitted by the IOTP Payment Bridge. 1791 The following table mentions any modification from this general 1792 processing for particular error values. Furthermore, it contains 1793 hints for developers of IOTP Application Core software components 1794 about the processing of error codes. Conversely, developers of IOTP 1795 Payment Bridges get impressions about the expected behavior of the 1796 IOTP Application Core. 1798 The IOTP Payment API assumes that the IOTP Application Core 1799 implements the dialog boxes needed for error resolution. But it does 1800 not assume, that the IOTP Payment Bridge actually relies on them. 1801 Instead, the IOTP Payment Bridge may try resolution on its own, may 1802 implement specific dialog boxes, and may signal only final failures. 1804 Note: This abstract document assumes that the API parameters are 1805 exchanged XML encoded. Therefore, several error values might 1806 disappear in lower level language specific derivations. 1808 Error Value Error Description 1809 ----------- ----------------- 1811 Reserved Reserved. This error is reserved by the 1812 vendor/developer of the software. Contact 1813 the vendor/developer of the software for 1814 more information (see the SoftwareId 1815 attribute of the Message Id element in the 1816 Transaction Reference Block [IOTP]). 1818 XmlNotWellFrmd XML not well formed. The XML document is not 1819 well formed. See [XML] for the meaning of 1820 "well formed". 1822 XmlNotValid XML not valid. The XML document is well 1823 formed but the document is not valid. See 1824 [XML] for the meaning of "valid". 1825 Specifically: 1827 o the XML document does not comply with the 1828 constraints defined in the IOTP document 1829 type declaration, and 1830 o the XML document does not comply with the 1831 constraints defined in the document type 1832 declaration of any additional [XML-NS] 1833 that are declared. 1835 The Names attribute might refer some 1836 attributes and elements of the input 1837 parameter list. 1839 (*)ElNotValid Element not valid. Invalid element in terms 1840 of prescribed syntactical characteristics. 1842 The ElementRef attributes of ErrorLocation 1843 elements might refer to the corresponding 1844 elements (if they have ID attributes). 1846 The IOTP Application Core has to replace the 1847 error code with "XmlNotValid" before 1848 transmission to the counterparty. 1850 ElUnexpected Unexpected element. Although the XML 1851 document is well formed and valid, an 1852 element is present that is not expected in 1853 the particular context according to the 1854 rules and constraints contained in this 1855 specification. 1857 The ElementRef attributes of ErrorLocation 1858 elements might refer to the corresponding 1859 elements (if they have ID attributes). 1861 ElNotSupp Element not supported. Although the document 1862 is well formed and valid, an element is 1863 present that 1865 o is consistent with the rules and 1866 constraints contained in this 1867 specification, but 1868 o is not supported by the IOTP Aware 1869 Application which is processing the IOTP 1870 Message. 1872 The ElementRef attributes of ErrorLocation 1873 elements might refer to the corresponding 1874 elements (if they have ID attributes). 1876 ElMissing Element missing. Although the document is 1877 well formed and valid, an element is missing 1878 that should have been present if the rules 1879 and constraints contained in this 1880 specification are followed. 1882 The ElementRef attributes of ErrorLocation 1883 elements might refer to the corresponding 1884 elements (if they have ID attributes). 1886 ElContIllegal Element content illegal. Although the 1887 document is well formed and valid, the 1888 element contains values which do not conform 1889 the rules and constraints contained in this 1890 specification. 1892 The ElementRef attributes of ErrorLocation 1893 elements might refer to the corresponding 1894 element (if they have ID attributes). 1896 The IOTP Application Core has to replace the 1897 Error Code with "ElNotSupp" before 1898 transmission to the counter party, if the 1899 ErrorLocation elements refer to non 1900 PackagedContent element. 1902 EncapProtErr Encapsulated protocol error. Although the 1903 document is well formed and valid, the 1904 Packaged Content of an element contains data 1905 from an encapsulated protocol which contains 1906 errors. 1908 The ElementRef attributes of ErrorLocation 1909 elements might refer to the corresponding 1910 element (if they have ID attributes). 1912 AttUnexpected Unexpected attribute. Although the XML 1913 document is well formed and valid, the 1914 presence of the attribute is not expected in 1915 the particular context according to the 1916 rules and constraints contained in this 1917 specification. 1919 The AttName attributes of ErrorLocation 1920 elements might refer to the corresponding 1921 attribute tags. 1923 (*)AttNotValid Attribute not valid. Invalid attribute value 1924 in terms of prescribed syntactical 1925 characteristics. 1927 The AttName attributes of ErrorLocation 1928 elements might refer to the corresponding 1929 attribute tags. 1931 The IOTP Application Core has to replace the 1932 error code with "XmlNotValid" before 1933 transmission to the counter party. 1935 AttNotSupp Attribute not supported. Although the XML 1936 document is well formed and valid, and the 1937 presence of the attribute in an element is 1938 consistent with the rules and constraints 1939 contained in this specification, it is not 1940 supported by the IOTP Aware Application 1941 which is processing the IOTP Message. 1943 AttMissing Attribute missing. Although the document is 1944 well formed and valid, an attribute is 1945 missing that should have been present if the 1946 rules and constraints contained in this 1947 specification are followed. 1949 The AttName attributes of ErrorLocation 1950 elements might refer to the corresponding 1951 attribute tags. 1953 If the attribute is required by the IOTP 1954 Document Type Declaration (#REQUIRED) the 1955 hints for non valid attributes should be 1956 adopted, otherwise these for illegal 1957 attribute values. 1959 AttValIllegal Attribute value illegal. The attribute 1960 contains a value which does not conform to 1961 the rules and constraints contained in this 1962 specification. 1964 The AttName attributes of ErrorLocation 1965 elements might refer to the corresponding 1966 attribute tags - valid values are: 1968 BrandId: illegal/unknown Brand Identifier - 1969 If the brand is not recognized/known by any 1970 IOTP Payment Bridge, the IOTP Application 1971 Core may offer the registration of a new 1972 Payment Instrument. 1974 PaymentInstrumentId: illegal/unknown 1975 Payment Instrument Identifier - This 1976 indicates a serious communication problem if 1977 the attribute value has been reported by the 1978 same "wallet" on a previous inquiry 1979 requests. The IOTP Application Core has to 1980 replace the error code with 1981 "UnknownError" before transmission to the 1982 counter party. 1984 WalletId: illegal/unknown Wallet Identifier 1985 - It is assumed that the wallet identifier 1986 is checked before the pass phrase. On 1987 invalid wallet identifiers, the IOTP 1988 Application Core may open the dialog in 1989 order to request the correct wallet 1990 identifier. In addition, any pass phrase may 1991 be supplied by the user. The dialog should 1992 indicate the respective payment brand(s). 1994 The IOTP Application Core has to replace the 1995 error code with "UnknownError" before 1996 transmission to the counter party. 1998 Passphrase: illegal/unknown Pass Phrase - 1999 The IOTP Application Core may open the 2000 dialog in order to request the correct pass 2001 phrase. If the pass phrase is wallet 2002 identifier specific the dialog should 2003 display the wallet identifier. The IOTP 2004 Application Core has to replace the error 2005 code with "TransportError" before 2006 transmission to the counter party. 2008 Action: illegal / unknown / unsupported 2009 Action 2011 PropertyTypeList: lists contains illegal / 2012 unknown / unsupported Property Types - The 2013 IOTP Application Core tries only the local 2014 resolution but does never transmit any IOTP 2015 Error Block to the counter party. 2017 CurrCode: illegal/unknown/unsupported 2018 Currency Code 2020 CurrCodeType: illegal/unknown/unsupported 2021 Currency Code Type 2023 Amount: illegal/unknown/unsupported Payment 2024 Amount 2026 PayDirection: illegal/unknown/unsupported 2027 Payment Direction 2029 ProtocolId: illegal/unknown/unsupported 2030 Protocol Identifier 2032 OkFrom: illegal/unknown/unsupported OkFrom 2033 Timestamp 2035 OkTo: illegal/unknown/unsupported OkTo 2036 Timestamp 2038 ConsumerPayId: illegal/unknown Consumer 2039 Payment Identifier 2041 PaymentHandlerPayId: illegal/unknown Payment 2042 Handler Payment Identifier 2043 PayId: illegal/unknown Payment Identifier 2045 AttValNotRecog Attribute Value Not Recognized. The 2046 attribute contains a value which the IOTP 2047 Aware Application generating the message 2048 reporting the error could not recognize. 2050 The AttName attributes of ErrorLocation 2051 elements might refer to the corresponding 2052 attribute tags 2054 MsgTooLarge Message too large. The message is too large 2055 to be processed by the IOTP Payment Bridge 2056 (or IOTP Application Core). 2058 ElTooLarge Element too large. The element is too large 2059 to be processed by the IOTP Payment Bridge 2060 (or IOTP Application Core). 2062 The ElementRef attributes of ErrorLocation 2063 elements might might refer to the 2064 corresponding elements. 2066 ValueTooSmall Value too small or early. The value of all 2067 or part of an element content or an 2068 attribute, although valid, is too small. 2070 The ErrorLocation elements might refer to 2071 the corresponding attribute tags or 2072 elements. 2074 ValueTooLarge Value too large or in the future. The value 2075 of all or part of an element content or an 2076 attribute, although valid, is too large. 2078 The ErrorLocation elements might refer to 2079 the corresponding attribute tags or 2080 elements. 2082 ElInconsistent Element Inconsistent. Although the document 2083 is well formed and valid, according to the 2084 rules and constraints contained in this 2085 specification: 2087 o the content of an element is inconsistent 2088 with the content of other elements or 2089 their attributes, or 2090 o the value of an attribute is inconsistent 2091 with the value of one or more other 2092 attributes. 2094 The Error Description may contain further 2095 explanations. 2097 The ErrorLocation elements might refer to 2098 the corresponding attribute tags or elements 2099 that are inconsistent. 2101 TransportError Transport Error. This error code is used to 2102 indicate that there is a problem with the 2103 transport mechanism that is preventing the 2104 message from being received. It is typically 2105 associated with a "Transient Error". 2107 The connection to some 2108 periphery or the counter party could not be 2109 established, is erroneous, or has been lost. 2111 The Error Description may contain further 2112 narrative explanations, e.g., "chip card 2113 does not respond", "remote account manager 2114 unreachable", "Internet connection to xyz 2115 lost", "no Internet connection available", 2116 "no modem connected", or "serial port to 2117 modem used by another application". This 2118 text should be shown to the end user. If 2119 timeout has occurred at the Consumer this 2120 text should be shown and the Consumer may 2121 decide how to proceed - alternatives are 2122 retry, payment transaction suspension, and 2123 cancellation. 2125 MsgBeingProc Message Being Processed. This error code is 2126 only used with a Severity of Transient 2127 Error. It indicates that the previous 2128 message, which may be an exchange message or 2129 a request message, is being processed and, 2130 if no response is received by the time 2131 indicated by the "MinRetrySecs" attribute, 2132 then the original message should be resent. 2134 SystemBusy System Busy. This error code is only used 2135 with a Severity of Transient Error. It 2136 indicates that the IOTP Payment Bridge or 2137 Existing Payment Software that received the 2138 API request is currently too busy to handle 2139 it. If no response is received by the time 2140 indicated by the "MinRetrySecs" attribute, 2141 then the original message should be resent. 2143 The Error Description may provide further 2144 explanations, e.g., "wallet / chip card 2145 reader is unavailable or locked by another 2146 payment transaction", "payment gateway is 2147 overloaded", "unknown chip card reader", or 2148 "unrecognized chip card inserted, change 2149 chip card". 2151 The Consumer's IOTP Application Core may 2152 visualize the error description and ask the 2153 Consumer about the continuation - 2154 alternatives are retry, payment transaction 2155 suspension, and cancellation. 2157 UnknownError Unknown Error. Indicates that the 2158 transaction cannot complete for some reason 2159 that is not covered explicitly by any of the 2160 other errors. The Error description 2161 attribute should be used to indicate the 2162 nature of the problem. 2164 The ErrorLocation elements might refer to 2165 the corresponding attribute tags or elements 2166 that are inconsistent. 2168 (*)SyntaxError Syntax Error. An (unknown) syntax error has 2169 occurred. 2171 The ErrorLocation elements might refer to 2172 the corresponding attribute tags or elements 2173 that are inconsistent. 2175 The IOTP Application Core has to replace the 2176 error code with "XmlNotValid" or 2177 "UnknownError" before transmission to the 2178 counter party. 2180 (*)ReqRefused Request refused. The API request is 2181 (currently) refused by the IOTP Payment 2182 Bridge. The error description may provide 2183 further explanations, e.g., "wallet / chip 2184 card reader is unavailable or locked by 2185 another payment transaction", "payment 2186 gateway is overloaded", "unknown chip card 2187 reader", or "unrecognized chip card 2188 inserted, change chip card". 2190 The Consumer's IOTP Application Core may 2191 visualize the error description and ask the 2192 Consumer about the continuation - 2193 alternatives are retry, payment transaction 2194 suspension, and cancellation. Denials due to 2195 invalid Process States should be signaled by 2196 "BusinessError". Typically, this kind of 2197 error is not passed to the counter party's 2198 IOTP Application Core. Otherwise, it maps to 2199 "TransportError" or "UnknownError". 2201 (*)ReqNotSupp Request not supported. The API 2202 function(ality) has not been implemented in 2203 the IOTP Payment Bridge. Typically, this 2204 kind of error is not passed to the 2205 counter party's IOTP Application Core. 2206 Otherwise, it maps to "TransportError" or 2207 "UnknownError". 2209 (*)BusError Business Error. The API request has been 2210 rejected because some payment transaction 2211 has an illegal payment status. 2212 Particularly, this error code is used to 2213 signal any raise of payment business layered 2214 failures. 2216 The ErrorLocation elements may refer to 2217 payment transactions using the party's 2218 Payment Identifier - it defaults to the 2219 current transaction or might contain the 2220 current payment transaction party's Payment 2221 Identifier - identified by the ElementRef 2222 attribute while the AttName attribute is 2223 fixed with "PayId". 2225 The IOTP Application Core must inquire the 2226 IOTP Payment Bridge about the actual Process 2227 State which actually encodes the business 2228 error ("Inquire Process State"). 2229 This error code must not be 2230 passed to the counter party's IOTP 2231 Application Core. 2233 Table 2: Common Error Codes 2235 The IOTP Payment Bridge may also use the error description in order 2236 to notify the Consumer about further necessary steps for failure 2237 resolution, e.g., "sorry, your payment transaction failed. 2238 Unfortunately, you have been charged, please contact your issuer." 2240 3.2 Attributes and Elements 2242 The following table explains the XML attributes in alphabetical order 2243 - any parenthesized number behind the attribute tag recommends the 2244 maximal length of the attribute value in characters: 2246 Attribute Description 2247 --------- ----------- 2249 Amount (11) Indicates the payment amount to be paid in 2250 AmountFrom(11) whole and fractional units of the currency. 2251 AmountTo (11) For example $245.35 would be expressed 2252 "245.35". Note that values smaller than the 2253 smallest denomination are allowed. For 2254 example one tenth of a cent would be 2255 "0.001". 2257 AuthenticationId An identifier specified by the 2258 authenticator which, if returned by the 2259 organization that receives the 2260 authentication request, will enable the 2261 authenticator to identify which 2262 authentication is being referred to. 2264 BrandId (128) This contains a unique identifier for the 2265 brand (or promotional brand). It is used to 2266 match against a list of Payment Instruments 2267 which the Consumer holds to determine 2268 whether or not the Consumer can pay with the 2269 Brand. 2271 Values of BrandId are managed under 2272 procedure being described in the IOTP 2273 protocol specification. 2275 BrandLogoNetLocn The net location which can be used to 2276 download the logo for the organization (cf. 2277 IOTP Specification). 2279 The content of this attribute must conform 2280 to [URL]. 2282 BrandName This contains the name of the brand, for 2283 example "MasterCard Credit". This is the 2284 description of the Brand which is displayed 2285 to the consumer in the Consumer's language 2286 defined by "xml:lang". For example it might 2287 be "American Airlines Advantage Visa". Note 2288 that this attribute is not used for matching 2289 against the payment instruments held by the 2290 Consumer. 2292 BrandNarrative This optional attribute is 2293 used by the Merchant to indicate some 2294 special conditions or benefit which would 2295 apply if the Consumer selected that brand. 2296 For example "5% discount", "free shipping 2297 and handling", "free breakage insurance for 2298 1 year", "double air miles apply", etc. 2300 CallBackFunction A function which is called whenever there is 2301 a change of Process State or payment 2302 progress, e.g. for display updates. However, 2303 the IOTP Payment Bridge may use its own 2304 mechanisms and dialog boxes. 2306 CallBackLanguageLis A list of language codes which contain, in 2307 t order of preference, the languages in which 2308 the text passed to the Call Back function 2309 will be encoded. 2311 CompletionCode (14) Indicates how the process completed. 2312 It is required if ProcessState is set to 2313 "Failed" otherwise it is ignored. Valid 2314 values as well as recovery options are given 2315 in the IOTP specification. 2317 The IOTP Payment Bridge may also use the 2318 Status Description to notify the Consumer 2319 about further necessary steps in order to 2320 resolve some kind of business failures, 2321 e.g., 2323 o "sorry, your payment transaction failed. 2324 Unfortunately, you have been charged, 2325 please contact your issuer." 2326 o "insufficient capacity left (on your card) 2327 for refund", 2328 o "payment failed/chip card error/internal 2329 error, please contact your payment 2330 instrument's issuer" 2332 ConsumerDesc A narrative description of the Consumer. 2334 ConsumerPayId (14) An unique identifier specified by the 2335 Consumer that, if returned by the Payment 2336 Handler in another Payment Scheme Component 2337 or by other means, enables the Consumer to 2338 identify which payment is being referred to. 2340 This unique identifier is generated by the 2341 IOTP Application Core and submitted to the 2342 IOTP Payment Bridge on every API call. It 2343 may equal to the Payment Handler Payment 2344 Identifiers but need not necessarily be so. 2346 The uniqueness extends to multiple payment 2347 instruments, payment brands, payment 2348 protocols, wallet identifiers, and even 2349 multiple IOTP Payment Bridges. 2351 ContStatus During payment progress, this status value 2352 indicates whether the payment needs to be 2353 continued with further IOTP Payment Scheme 2354 Component exchanges with the remote party. 2355 "End" indicates that the reported payment 2356 scheme data is the last data to be exchanged 2357 with the counter party. 2359 ContentSoftwareId This contains information that identifies 2360 the software that generated the content of 2361 the element. Its purpose is to help resolve 2362 interoperability problems that might occur 2363 as a result of incompatibilities between 2364 messages produced by different software. It 2365 is a single text string in the language 2366 defined by xml:lang. It must contain, as a 2367 minimum: 2369 o the name of the software manufacturer, 2370 o the name of the software, 2371 o the version of the software, and 2372 o the build of the software. 2374 CurrCodeType (14) Indicates the domain of the CurrCode. This 2375 attribute is included so that the currency 2376 code may support nonstandard currencies 2377 such as frequent flyer point, trading 2378 stamps, etc. Its values may be 2380 o ISO-4217-A, the default, indicates the 2381 currency code is the three-letter 2382 alphabetic code that conform to ISO 4217 2384 o IOTP indicates that the values of 2385 CurrCode are managed under the procedure 2386 described in [IOTP]. 2388 CurrCode (14) A code which identifies the currency to be 2389 used in the payment. The domain of valid 2390 currency codes is defined by "CurrCodeType" 2392 MerchantPayId (14) An private identifier specified by the 2393 Merchant which will enable the Merchant to 2394 identify which payment is being referred to. 2395 It is a pure private item and is never sent 2396 to any other party. It is provided by the 2397 IOTP Payment Bridge on payment preparation 2398 during brand compilation. 2400 Cf. To "ConsumerPayId" for note about 2401 uniqueness. 2403 MerchantOrgId (64) A local item that might refer to some 2404 specific shop in a multi shop environment. 2405 This item is optional and might enrich the 2406 Wallet Identifier which itself can be used 2407 for the same purpose. 2409 Name Distinguishes between multiple occurrences 2410 of Packaged Content Elements at the same 2411 point in IOTP. For example: 2413 2414 2415 snroasdfnas934k 2416 2417 2418 dvdsjnl5poidsdsflkjnw45 2419 2420 2422 The "Name" attribute may be omitted, for 2423 example if there is only one Packaged 2424 Content element. 2426 OkFrom (30) The date and time in UTC Format range 2427 OkTo (30) indicated by the merchant in which the 2428 Payment Handler may accept the payment. 2430 Passphrase (32) Payment wallets may use pass phrase 2431 protection for transaction data and payment 2432 instruments' data. However, it is assumed 2433 that there exists a public and customizable 2434 payment instrument identifier such that 2435 these identifiers together with their 2436 relationship to payment brands, payment 2437 protocols, payment directions, and currency 2438 amounts can be inquired by the IOTP 2439 application without any pass phrase 2440 knowledge. 2442 PayDirection Indicates the direction in which the 2443 payment for which a Brand is being selected 2444 is to be made. Its values may be: 2446 o Debit: The sender of the Payment Request 2447 Block (e.g. the Consumer) to which this 2448 Brand List relates will make the payment 2449 to the Payment Handler, or 2450 o Credit: The sender of the Payment Request 2451 Block to which this Brand List relates 2452 will receive a payment from the Payment 2453 Handler. 2455 PayId (14) This attribute is introduced for API 2456 simplification: 2458 o The Consumer has to identify PayId and 2459 ConsumerPayId. 2461 o The Merchant has to identify PayId and 2462 MerchantPayId. 2464 o The Payment Handler has to identify PayId 2465 and Payment Handler Pay Id. 2467 PayInstId This contains the unique identifier used 2468 internally by the IOTP Payment 2469 Bridge/Existing Payment Software. 2471 PayInstName This contains the user-defined name of the 2472 payment instrument. There exist no 2473 (technical) constraints like uniqueness. The 2474 "xml:lang" attribute denotes the language 2475 encoding of its value. 2477 PaymentHandlerDesc A narrative description of the Payment 2478 Handler. 2480 PaymentHandlerPayId An unique identifier specified by the 2481 (14) Payment Handler that, if returned by the 2482 Consumer in another Payment Scheme Component 2483 or by other means, enables the Payment 2484 Handler to identify which payment is being 2485 referred to. It is required whenever it is 2486 known. 2488 Cf. To "ConsumerPayId" for note about 2489 uniqueness. 2491 PaymentInstrumentId An identifier for a specific payment 2492 (32) instrument, e.g. "credit card", "Mondex card 2493 for English Pounds". This identifier is 2494 fully customizable. It is assumed, that it 2495 does not contain confidential information or 2496 even an indication to it. The payment 2497 instrument identifier is unique within each 2498 payment brand. It is displayed to the 2499 Consumer during brand selection. 2501 PayReceiptNameRefs Optionally contains element references to 2502 (32) other elements (containing payment scheme 2503 specific data) that together make up the 2504 receipt. Note that each payment scheme 2505 defines in its supplement the elements that 2506 must be referenced 2508 The IOTP Application Core should save all 2509 the components referenced so that the 2510 payment receipt can be reconstructed when 2511 required. 2513 PayReqNetLocn The Net Location indicating where an 2514 unsecured Payment Request message should be 2515 sent if this protocol choice is used. 2517 The content of this attribute must conform 2518 to [URL] and depends on the Transport 2519 Mechanism. 2521 PercentComplete (3) A number between 0 and 100 which indicates 2522 the progress of the payment transaction. The 2523 values range between 0 and 99 for pending 2524 and suspended transactions. 2526 ProcessState Contains a Process State Code that 2527 indicates the current state of the process 2528 being carried out. Valid values are: 2530 o NotYetStarted. The Payment Request Block 2531 has been received but processing of the 2532 Payment Request has not yet started 2534 o InProgress. The payment transaction is 2535 pending. The processing of the (Payment) 2536 Request Block has started but it is not 2537 yet complete. 2539 o (*)Suspended: The payment transaction has 2540 been suspended and can be resumed. 2542 This process state is mapped to 2543 "InProgress", if it is passed to the 2544 counter party's IOTP Application Core. 2546 o CompletedOk. The processing of the (Payment) 2547 Request Block and any following Payment 2548 Exchange Blocks has completed successfully. 2550 o Failed. The payment processing has finally 2551 failed for a Business Error. 2553 o ProcessError. This value is only used 2554 when the Status Component is being used in 2555 connection with an Inquiry Request Trading 2556 Block. It indicates there was a Technical 2557 Error in the Request Block which is being 2558 processed or some internal processing 2559 error. Each party's IOTP Payment Bridge 2560 uses this value in order to notify the 2561 IOTP Application Core about the presence 2562 of technical errors. 2564 PropertyType (14) The property type defines codes used for 2565 interrogation of specific properties about a 2566 payment instrument. They are unique for each 2567 payment brand. The predefined property "all" 2568 is used on general inquiries. However, these 2569 property types are not used during normal 2570 payment processing. E.g., they may apply to 2571 payment brand specific transactions or out- 2572 of-band failure resolution. 2574 PropertyDesc The property description carries the 2575 respective human readable property (value)'s 2576 description. 2578 PropertyValue The actual property value intends automatic 2579 post processing. 2581 ProtocolBrandId (64)This is an identifier to be used with a 2582 particular payment protocol. For example, 2583 SET and EMV have their own well defined, yet 2584 different, values for the Brand identifier 2585 to be used with each protocol. The valid values 2586 of this attribute are defined in the 2587 supplement for the payment protocol 2588 identified by "ProtocolId" that describes 2589 how the payment protocol works with IOTP. 2590 Identifier maps to at most one Protocol 2591 Brand Identifier. 2593 ProtocolId (64) An identifier for a specific payment 2594 protocol and version, e.g. "SETv1.0", 2595 "ecash". Valid values are defined by 2596 supplements to the IOTP specification and 2597 they are unique within each payment brand. 2599 ProtocolIds A sequence of Protocol Identifiers 2601 ProtocolName A narrative description of the payment 2602 protocol and its version in the language 2603 identified by "xml:lang". For example 2604 "Secure Electronic Transaction Version 1.0". 2605 Its purpose is to help provide information 2606 on the payment protocol being used if 2607 problems arise. 2609 SecPayReqNetLocn The Net Location indicating where a secured 2610 Payment Request message should be sent if 2611 this protocol choice is used. 2613 A secured payment involves the use of a 2614 secure channel such as [SSL]/[TLS] in order 2615 to communicate with the Payment Handler. 2617 The content of this attribute must conform 2618 to [URL]. 2620 ReceiverOrgId The Organization Identification which 2621 receives the payment bridge processing 2622 Trading Role Data PackagedContent. 2624 StatusDesc (256) An optional textual description of the 2625 current process state in the language 2626 identified by "xml:lang" that should be 2627 displayed to the Consumer. The usage of this 2628 attribute is defined in the payment 2629 supplement for the payment method being 2630 used. Particularly, it provides hints for 2631 out-of-band failure resolution. Its length 2632 is limited to 256 characters. 2634 StyleSheetNetLocn This contains the net location to a style 2635 sheet with visualisation rules for XML 2636 encoded data. 2638 TimeStamp (30) The date and time in UTC Format when the 2639 payment transaction has been started. 2641 WalletId (32) Many existing payment wallet software are 2642 multiple wallet capable. The Wallet 2643 Identifier selects the actual wallet. It is 2644 assumed, that the wallet identifier is a 2645 public item, that might be stored by the 2646 IOTP Application Core. 2648 xml:lang Defines the language used by the Process 2649 State Description attribute (cf. IOTP 2650 Specification) 2652 Table 3: Attributes 2654 The following table explains the XML elements in alphabetical 2655 order: 2657 Element Description 2658 ------- ----------- 2660 Algorithm This contains information which describes 2661 an Algorithm that may be used to generate 2662 the Authentication response. 2664 The algorithm that may be used is 2665 identified by the Name attribute (cf. IOTP 2666 Specification). 2668 AuthReqPackagedContent The Authentication Request Packaged 2669 Content originates from a Authentication 2670 (Data/Response) Component's content 2671 whereby the outermost element tags are 2672 prefixed with "AuthReq". Its declaration 2673 coincides with the Packaged Content's 2674 declaration (cf. IOTP Specification). It 2675 encapsulates the authentication challenge 2676 value. The content of this information is 2677 defined in the supplement for a payment 2678 protocol. 2680 AuthResPackagedContent The Authentication Response Packaged 2681 Content originates from a Authentication 2682 Response Component's content whereby the 2683 outermost element tags are prefixed with 2684 "AuthRes". 2686 Its declaration coincides with the 2687 Packaged Content's declaration (cf. IOTP 2688 Specification). It encapsulates the 2689 authentication response value. The 2690 content of this information is defined in 2691 the supplement for a payment protocol. 2693 BrandPackagedContent Container for further payment brand 2694 description. Its content originates from 2695 a Brand Element content whose outermost 2696 element tags are prefixed with "Brand". 2697 Its declaration coincides with the 2698 Packaged Content's declaration (cf. IOTP 2699 Specification). 2701 BrandSelBrandInfoPackagedContent 2702 This contains any additional data that 2703 may be required by a particular payment 2704 brand. It forms the content of the Brand 2705 Selection Brand Info Element. 2707 BrandSelProtocolAmountInfoPackagedContent 2708 This contains any additional data that 2709 may be required by a particular payment 2710 brand in the format. It forms the content 2711 of the Brand Selection Protocol Amount 2712 Info Element. 2714 BrandSelCurrencyAmountInfoPackagedContent 2715 This contains any additional data that 2716 payment brand and currency specific in 2717 the format. It forms the content of the 2718 Brand Selection Currency Amount Info 2719 Element. 2721 MerchantData Any merchant related data that might be 2722 used by the IOTP Payment Bridge for 2723 different purposes, e.g., it might 2724 contain access keys to some mall keys. 2725 Its declaration coincides with the 2726 Packaged Content's declaration (cf. IOTP 2727 Specification). 2729 PackagedContent Generic Container for non-IOTP data (cf. 2730 IOTP Specification). 2732 PayProtocolPackagedContent 2733 The Pay Protocol Packaged Content 2734 originates from a Pay Protocol 2735 Element's content whereby the outermost 2736 element tags are prefixed with 2737 "PayProtocol". It contains information 2738 about the protocol which is used by 2739 the payment protocol. The content of 2740 this information is defined in the 2741 supplement for a payment protocol.Its 2742 declaration coincides with the Packaged 2743 Content's declaration (cf. IOTP 2744 Specification). 2746 PaySchemePackagedContent 2747 The PayScheme Packaged Content originates 2748 from a Payment Scheme Component's content 2749 whereby the outermost element tags are 2750 prefixed with "PayScheme". Its 2751 declaration coincides with the Packaged 2752 Content's declaration (cf. IOTP 2753 Specification). It carries the payment 2754 specific data. The content of this 2755 information is defined in the supplement 2756 for a payment protocol. 2758 ProtocolAmountPackagedContent 2759 The Protocol Amount Packaged Content 2760 originates from a Protocol Amount 2761 Element's content whereby the outermost 2762 element tags are prefixed with "Amount". 2763 Its declaration coincides with the 2764 Packaged Content's declaration (cf. IOTP 2765 Specification). It contains information 2766 about the protocol which is used by the 2767 payment protocol. The content of this 2768 information is defined in the supplement 2769 for a payment protocol. 2771 ProtocolBrandPackagedContent 2772 The Protocol Brand Packaged Content 2773 originates from a Protocol Brand 2774 Element's content whereby the outermost 2775 element tags are prefixed with 2776 "ProtocolBrand". Its declaration 2777 coincides with the Packaged Content's 2778 declaration (cf. IOTP Specification). It 2779 contains information about the brand 2780 which might be used by the payment 2781 protocol. The content of this information 2782 is defined in the supplement for a 2783 payment protocol. 2785 ResponsePackagedContent 2786 Container for authentication response 2787 data. Its content originates from a 2788 Authentication Response Component's 2789 Packaged Content whose outermost element 2790 tags are prefixed with "Response". Its 2791 declaration coincides with the Packaged 2792 Content's declaration (cf. IOTP 2793 Specification). 2795 TradingRoleDataPackagedContent 2796 The TradingRoleData Packaged Content 2797 originates from a TradingRoleData 2798 Component's content whereby the outermost 2799 element tags are prefixed with 2800 "TradingRoleData". Its declaration 2801 coincides with the Packaged Content's 2802 declaration (cf. IOTP Specification). It 2803 contains information from Merchant to 2804 Payment Handler via Consumer about the 2805 protocol which is used by the payment. 2806 The content of this information is 2807 defined in the supplement for a payment 2808 protocol. The Name attribute in this 2809 packaged contents must include prefix as 2810 "Payment:" to indicate that the payment 2811 bridge processes this, for example 2812 "Payment:SET-OD" 2814 The element's declaration coincides with 2815 the Packaged Content's declaration (cf. 2816 IOTP Specification). 2817 Table 4: Elements 2819 XML definition: 2821 2824 2831 2835 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 genuine 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 the 2873 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 some 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 genuine 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 genuine 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 genuine 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 will 2979 not change during the whole brand 2980 selection process, normally. 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 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 does neither 3072 reflect 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 related 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 reduced by the 3379 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 3411 Tables 4 and 5 explain the attributes and elements; Table 3 3412 introduces the Error Codes. 3414 4.1.5 Authenticate 3416 The Consumer's IOTP Application Core defers payment protocol specific 3417 authentication processing and the current challenge value to the 3418 active IOTP Payment Bridge. Alternative authentication algorithms 3419 might be tried sequentially or offered to the user for selection. 3421 Note that the IOTP Application Core has to consider both the current 3422 context and the algorithm in order to determine the responsible IOTP 3423 Payment Bridge. 3425 Failed authentication is reported by the Business Error Code which 3426 might trigger the inquiry of the details ("Inquire Process State"). 3427 Final failures might be encoded by the process state "Failed". 3429 Input Parameters 3431 o Authentication Identifier 3432 o Wallet Identifier and/or Pass Phrase 3433 o Authentication Challenge Packaged Content - copied from the 3434 IOTP Authentication Request Component 3435 o Algorithm Element - copied from the IOTP Authentication Request 3436 Component 3438 XML definition: 3440 3441 3446 Output Parameters 3448 o Authentication Response Packaged Content - for insertion into 3449 the IOTP Authentication Response Component 3451 XML definition: 3453 3455 Tables 4 and 5 explain the attributes and elements; Table 3 3456 introduces the Error Codes. 3458 4.1.6 Check Authentication Response 3460 This API function verifies the Consumer's payment protocol specific 3461 authentication response. In Baseline IOTP this API function is called 3462 by the Merchant (or the Financial Institution). It is called only if 3463 the counter party has responded with an IOTP Authentication Response 3464 Component within the Authentication Response Block. Of course, the 3465 IOTP Application Core traces the need of such an response. 3467 Due to the authentication's statelessness, all parameters (algorithm, 3468 challenge and response) are submitted to the IOTP Payment Bridge. 3469 Authentication failure is reported by a Process State different from 3470 "CompletedOK". 3472 Input Parameters 3474 o Authentication Identifier 3475 o Wallet Identifier and/or Pass Phrase 3476 o Authentication Challenge Packaged Content - generated by 3477 previous "Inquire Authentication Challenge" API call 3478 o Algorithm Element 3479 o Authentication Response Packaged Content - copied from the 3480 Authentication Response Component 3482 XML definition: 3484 3486 3491 Output Parameters 3493 o Current Process (Authentication) State 3494 o Completion Code 3495 o Status Description and its language annotation 3497 XML definition: 3499 3500 3511 Tables 4 and 5 explain the attributes and elements; Table 3 3512 introduces the Error Codes. 3514 4.2 Brand Selection Related API Calls 3516 4.2.1 Find Payment Instrument 3518 This API function determines which instances of a Payment Brand, 3519 e.g., two Mondex cards, are present. The same physical card may even 3520 represent multiple payment instruments. 3522 The IOTP Application Core supplies possible payment brand and payment 3523 protocol to the IOTP Payment Bridge that has to be considered when 3524 the IOTP Payment Bridge searches for appropriate payment instruments. 3525 This set represents the (sub)set of payment alternatives being 3526 supported by the Merchant. If the IOTP Application Cote has multiple 3527 possible payment brand/protocol, it can call this function in turn. 3529 The Existing Payment Software responds with PayInstrument Elements 3530 with empty PayInstId attributes if it does not distinguish between 3531 different payment instruments for the particular payment 3532 alternatives. 3534 Note that the Payment API assumes that the values of the attributes 3535 BrandId, ProtocolId, ProtocolBrandId and the currency amount suffice 3536 for the determination of the appropriate Packaged Content Element 3537 that will be transmitted to the Payment Handler later on. 3539 Input Parameters 3541 o Brand Identifier - copied from the Brand List Component's Brand 3542 Element 3543 o Payment Protocol Identifier and associated Protocol Brand 3544 Identifier 3545 o Payment Direction - copied from the Brand List Component 3546 o Currency Code and Currency - copied from the Currency Amount 3547 Element 3548 o Payment Amount - copied from the Currency Amount Element 3549 o Consumer Payment Identifier - Consumer's unique reference to 3550 the current payment transaction 3551 o Wallet Identifier - managed by the IOTP Application Core 3552 o (Brand) Packaged Content - further payment brand description; 3553 copied from the Brand List Component's Brand Element 3555 o (Protocol Brand) Element - further information; copied from the 3556 Protocol Brand Element of the Brand List Component which 3557 relates to the Consumer selected Brand Element, if any. 3558 o (Protocol Amount) Packaged Content - further payment protocol 3559 description, copied from the Brand List Component's Protocol 3560 Amount Element 3561 o Element (Protocol) Packaged Content - further payment protocol 3562 description, copied from the Brand List Component's Pay 3563 Protocol Element 3565 XML definition: 3567 3571 3581 Output Parameters 3583 o The known Payment Instrument Identifiers, these are internal 3584 values 3585 o The user-defined names of the payment instrument and their 3586 language encoding 3588 The Existing Payment Software responds with an empty list of 3589 identifiers, either if it does not distinguish between different 3590 payment instruments or if there are no registered payment instruments 3591 available despite brand support for at least one (unspecified) 3592 payment protocol. In the latter case, the IOTP Payment Bridge has to 3593 request the registration of a suitable payment instrument at a 3594 subsequent step of the payment process. 3596 XML definition: 3598 3599 3600 3605 Tables 4 and 5 explain the attributes and elements; Table 3 3606 introduces the Error Codes. 3608 4.2.2 Check Payment Possibility 3610 This API function checks whether a payment (both debit and credit) 3611 can go ahead. It can be used, for example, to check 3613 o if there are sufficient funds available in a particular 3614 currency for an electronic cash payment brand, 3615 o whether there is sufficient value space left on the payment 3616 instrument for payment refund, 3617 o whether required system resources are available and properly 3618 configured, e.g., serial ports or baud rate, 3619 o whether environment requirements are fulfilled, e.g., chip card 3620 reader presence or Internet connection. 3622 If the payment method bases on external components, e.g., magnetic 3623 stripe or chip cards, and the check accesses the medium, the existing 3624 payment method should not mutually exclusive lock system resources, 3625 e.g., serial port or modem, that may also be required by other 3626 Existing Payment Software, e.g., multiple payment software components 3627 may share the same card reader. If this happens for API internal 3628 request processing, the function has to unlock these components prior 3629 to return. Otherwise, the payment may not proceed if the Consumer 3630 cancels immediately and decides to use another payment instrument. In 3631 this event the previous IOTP Payment Bridge is not notified about the 3632 change. 3634 This function call happens immediately after the Consumer's payment 3635 instrument selection. For example, if the payment instrument is a 3636 chip card, that is not inserted in the chip card reader, the Consumer 3637 may be prompted for its insertion. However, the Consumer should be 3638 able to hit some 'skip' button, if the payment check is part of the 3639 actual payment protocol, too. Finally, the IOTP Payment Bridge may 3640 provide only a subset of these capabilities or may even directly 3641 generate a successful response without any checks. 3643 Input Parameters 3645 o Brand Identifier - user selection 3646 o Payment Instrument Identifier - user selection 3647 o Currency Code and Currency Code Type - copied from the selected 3648 Currency Amount Element 3649 o Payment Amount - copied from the selected Currency Amount 3650 Element 3651 o Payment Direction - copied from the selected Trading Protocol 3652 Option Block 3654 o Protocol Identifier - copied from the selected Pay Protocol 3655 Element 3656 o Protocol Brand Identifier - copied from the selected Protocol 3657 Brand Element of the Brand List Component which relates to the 3658 selected Brand Element, if any 3659 o Consumer Payment Identifier - Consumer's unique reference to 3660 the current payment transaction 3661 o Wallet Identifier and/or Pass Phrase 3662 o (Brand) Packaged Content - copied from the selected Brand 3663 Element 3664 o (Protocol Amount) Packaged Content - copied from the selected 3665 Protocol Amount Element 3666 o (Protocol) Packaged Content - copied from the selected Pay 3667 Protocol Element 3668 o (Protocol Brand) Packaged Content - copied from the selected 3669 Protocol Brand Element of the Brand List Component which 3670 relates to the selected Brand Element, if any 3672 XML definition: 3674 3678 3690 Output Parameters 3692 o three Brand Selection Info Packaged Content elements - for 3693 insertion into the Brand Selection component 3694 o Brand - additional data about the payment brand 3695 o Protocol Amount - additional data about the payment protocol 3696 o Currency Amount - additional payment brand and currency 3697 specific data 3699 XML definition: 3701 3705 3707 Tables 4 and 5 explain the attributes and elements; Table 3 3708 introduces the Error Codes. 3710 4.3 Payment Transaction Related API calls 3712 These Payment API calls may be made either by the Consumer's or 3713 Payment Handler's IOTP Application Core. 3715 4.3.1 Start Payment Consumer 3717 This API function initiates the genuine payment transaction at the 3718 Consumer side. The IOTP Payment Bridge and the Existing Payment 3719 Software perform all necessary initialization and preparation for 3720 payment transaction processing. This includes the reservation of 3721 external periphery. E.g., 1) the Consumer's chip card reader needs to 3722 be protected against access from other software components, 2) the 3723 insertion of the chip card may be requested, 3) the Internet 3724 connection may be re-established, or 4) the Payment Handler may open 3725 a mutual exclusive session to the security hardware. 3727 The IOTP Payment Bridge monitors the payment progress and stores the 3728 current payment states such that resumption - even after power 3729 failures - remains possible. Note that the IOTP Application Core 3730 supplies only a subset of the following input parameter to the 3731 associated resumption API function and refers to the payment 3732 transaction through the party's payment identifier. 3734 Input Parameters 3736 o Brand Identifier - copied from the selected Brand Element 3737 o Payment Instrument Identifier - the user selection 3738 o Currency Code and Currency - copied from the selected Currency 3739 Amount Element 3740 o Payment Amount - copied from the selected Currency Amount 3741 Element 3742 o Payment Direction - copied from the Brand List Component 3743 o Protocol Identifier - copied from the selected Payment Protocol 3744 Element 3745 o Protocol Brand Element - further information; copied from the 3746 Protocol Brand Element of the Brand List Component which 3747 relates to the selected Brand Element, if any 3748 o OkFrom, OkTo - copied from the Payment Component 3749 o Consumer Payment Identifier - Consumer's unique reference to 3750 the current payment transaction 3751 o Wallet Identifier and/or Pass Phrase 3752 o Call Back Function - used for end user notification/logging 3753 purposes 3754 o Call Back Language List. This list is required if the Call Back 3755 Function is set 3756 o (Brand) Packaged Content - further payment brand description; 3757 copied from the selected Brand Element's content 3758 o (Protocol Amount) Packaged Content - further payment protocol 3759 description; copied from the selected Protocol Amount Element's 3760 content 3761 o (Payment Protocol) Packaged Content - further payment protocol 3762 description; copied from the selected Pay Protocol Element's 3763 content 3764 o (Order) Packaged Content - further order description, copied 3765 from the Order Component 3767 XML definition: 3769 3774 3791 Output Parameters 3793 o Continuation Status 3794 o (Payment Scheme) Packaged Content - for insertion into the 3795 Payment Scheme Component of the IOTP Payment Request Block 3797 The IOTP Application Core is allowed to reissue this request several 3798 times on failed analyses of the response. 3800 XML definition: 3802 3804 3807 Tables 4 and 5 explain the attributes and elements; Table 3 3808 introduces the Error Codes. 3810 4.3.2 Start Payment Payment Handler 3812 This API function initializes the Consumer initiated payment 3813 transaction at the Payment Handler's side. Similar to the Consumer's 3814 system, the IOTP Payment Bridge and the Existing Payment Software 3815 perform all necessary initialization and preparation for payment 3816 transaction processing. 3818 Input Parameters 3820 o Brand Identifier - copied from the Consumer selected Brand 3821 Element 3822 o Consumer Payment Identifier - copied from the Payment Scheme 3823 Component 3824 o Currency Code and Currency - copied from the Consumer selected 3825 Currency Amount Element 3826 o Payment Amount - copied from the Consumer selected Currency 3827 Amount Element 3828 o Payment Direction - copied from the Brand List Component 3829 o Protocol Identifier - copied from the Consumer selected 3830 Payment Protocol Element 3831 o Protocol Brand Identifier - copied from the Brand Protocol 3832 Element of the Brand List Component which relates to the 3833 Consumer selected Brand Element, if any 3834 o OkFrom, OkTo - copied from the Payment Component 3835 o Payment Handler Payment Identifier - Payment Handler's unique 3836 reference to the current payment transaction 3837 o Merchant Organisation Identifier - copied from the Merchant's 3838 Organisation Element 3839 o Wallet Identifier - renaming to till identifier neglected - 3840 and/or Pass Phrase 3841 o Call Back Function - used for end user notification/logging 3842 purposes 3843 o Call Back Language List. This list is required if the call back 3844 function is set 3845 o (Brand) Packaged Content - further payment brand description; 3846 copied from the Consumer selected Brand Element's content 3847 o (Protocol Brand) Packaged Content - further information; copied 3848 from the Protocol Brand Element of the Brand List Component 3849 which relates to the Consumer selected Brand Element, if any. 3850 o (Protocol Amount) Packaged Content - further payment protocol 3851 description; copied from the Consumer selected Protocol Amount 3852 Element's content 3853 o (Protocol) Packaged Content - further payment protocol 3854 description; copied from the Consumer selected Pay Protocol 3855 Element's content 3856 o (TradingRoleData) Packaged Content - further payment protocol 3857 description; the Name Attribute of the packaged contents must 3858 include "Payment:" as the prefix, for example "Payment:SET-OD". 3859 o Three Brand Selection Info Packaged Content Elements - copied 3860 from the Brand Selection Component 3861 o Brand - additional data about the payment brand 3862 o Protocol Amount - additional data about the payment protocol 3863 o Currency Amount - additional payment brand and currency 3864 specific data 3865 o (Payment Scheme) Packaged Content. 3867 XML definition: 3869 3878 3895 Output Parameters 3897 o Continuation Status 3898 o (Payment Scheme) Packaged Content - for insertion into the 3899 Payment Scheme Component of the IOTP Payment Exchange Block 3901 The response message must contain payment schema data if the 3902 continuation status signals "Continue". The IOTP Application Core is 3903 allowed to reissue this request several times on failed analyses of 3904 the response. 3906 XML definition: 3908 3910 3913 Tables 4 and 5 explain the attributes and elements; Table 3 3914 introduces the Error Codes. 3916 4.3.3 Resume Payment Consumer 3918 This API function resumes a previously suspended payment at the 3919 Consumer side. Resumption includes the internal inquiry of the 3920 payment transaction data, e.g., payment amount, protocol identifier, 3921 and the whole initialization as it has been applied on the "Start 3922 Payment Consumer" API request. 3924 It is up to the IOTP Application Core to decide whether an IOTP 3925 Payment Request Block or a IOTP Payment Exchange Block needs to be 3926 generated. One indicator might be the receipt of a previous IOTP 3927 Payment Exchange Block from the Payment Handler, e.g., the knowledge 3928 of the Payment Handler Payment Identifier. 3930 Input Parameters 3932 o Consumer Payment Identifier 3933 o Wallet Identifier and/or Pass Phrase 3934 o Call Back Function - used for end user notification/logging 3935 purposes 3937 XML definition: 3939 3940 3947 Output Parameters 3949 o Continuation Status 3950 o (Payment Scheme) Packaged Content - for insertion in the 3951 Payment Scheme Component of the next IOTP message (Payment 3952 Exchange or Request Block). 3954 The IOTP Application Core is allowed to reissue this request several 3955 times on failed analyses of the response. However, the IOTP Payment 3956 Bridge might reject the resumption request by using the "AttNotSupp" 3957 Error Code "naming" the Consumer Payment Identifier attribute. Then 3958 the Consumer has to apply normal error processing to the current 3959 (sub-)transaction and to issue a new Payment Request Block to the 3960 Payment Handler. 3962 XML definition: 3964 3966 3969 Tables 4 and 5 explain the attributes and elements; Table 3 3970 introduces the Error Codes. 3972 4.3.4 Resume Payment Payment Handler 3974 This API function resumes a payment at the Payment Handler side. 3976 Input Parameters 3978 o Payment Handler Payment Identifier 3979 o Wallet Identifier - renaming to till identifier neglected - and 3980 Pass Phrase 3981 o Call Back Function - used for end user notification/logging 3982 purposes 3983 o Call Back Language List. This list is required if the Call Back 3984 Function is set 3985 o (Payment Scheme) Packaged Content - copied from the Payment 3986 Scheme Component of the received IOTP message (Payment Exchange 3987 or Request Block). 3989 XML definition: 3991 3993 4000 Output Parameters 4002 o Continuation Status 4003 o (Payment Scheme) Packaged Content - for insertion in the 4004 Payment Scheme Component of the next Payment Exchange Block. 4006 The response message contains payment schema specific data if the 4007 continuation status signals "Continue". The IOTP Application Core is 4008 allowed to reissue this request several times on failed analyses of 4009 the response. 4011 XML definition: 4013 4015 4018 Tables 4 and 5 explain the attributes and elements; Table 3 4019 introduces the Error Codes. 4021 4.3.5 Continue Process 4023 This API function passes one specific IOTP Payment Scheme Component, 4024 i.e., the encapsulated Packaged Content elements, received from the 4025 counter party (e.g. Consumer) to the IOTP Payment Bridge and responds 4026 with the next IOTP Payment Scheme Component for submission to the 4027 counter party. 4029 Input Parameters 4031 o Payty's Payment Identifier 4032 o Process (Transaction) Type which distinguishes between Payments 4033 and Inquiries. 4034 o Wallet Identifier and/or Pass Phrase 4035 o (Payment Scheme) Packaged Content - copied from the Payment 4036 Scheme Component of the received Payment Exchange Block or from 4037 the Error Block. 4039 Each party should set the payment identifier with the local 4040 identifier (Consumer: ConsumerPayId; Merchant: MerchantPayId; Payment 4041 Handler: PaymentHandlerPayId). 4043 XML definition: 4045 4046 4052 Output Parameters 4054 o Continuation Status 4055 o (Payment Scheme) Packaged Content - for insertion in the 4056 Payment Scheme Component of the next Payment Exchange Block or 4057 final Payment Response Block 4059 The response message contains payment schema data if the continuation 4060 status signals "Continue". The IOTP Payment Bridge must signal "End", 4061 if the payment scheme data was received within an IOTP Error Block 4062 containing an Error Component with severity HardError. 4064 XML definition: 4066 4067 4070 Tables 4 and 5 explain the attributes and elements; Table 3 4071 introduces the Error Codes. 4073 4.3.6 Change Process State 4075 The IOTP Application Core changes the current payment status by this 4076 request. The IOTP Payment Bridge may be notified about business level 4077 normal termination, cancellation, suspension, and processing errors. 4078 Notification happens by requesting the intended process state. 4080 The IOTP Payment Bridge processes the status change and reports the 4081 result. 4083 The IOTP Application Core has to analyze any returned process status 4084 in order to check whether the IOTP Payment Bridge has agreed to or 4085 declined the status switch. E.g., the submitted Process State 4086 "CompleteOk" may lead to the Payment Status "Failed" if the payment 4087 transaction has already failed. 4089 Transaction Suspension is notified by the newly introduced Process 4090 State "Suspended". The other attribute values have been taken from 4091 the IOTP specification. 4093 This API function might be called by the Consumer, Merchant, or 4094 Payment Handler for each payment transaction anytime after the 4095 issuance of "FindPaymentInstrument" to the IOTP Payment Bridge by the 4096 Consumer, the issuance of "FindAcceptedPaymentBrand" by the Merchant, 4097 or the issuance of "StartPaymentPaymentHandler" by the Payment 4098 Handler. 4100 The Process States "CompletedOk", "Failed", and "ProcessError" are 4101 final in the sense that they can not be changed on subsequent calls. 4102 However, the API function should not return with an error code if 4103 such an incompatible call has been issued. Instead it should report 4104 the old unchanged Process State. 4106 Unknown payment transactions are reported by the Error Code 4107 "AttValInvalid" pointing to the PayId attribute. 4109 Input Parameters 4111 o Party's Payment Identifier 4112 o intended Payment Status 4113 o intended Completion Code 4114 o Process (Transaction) Type which distinguishes between Payments 4115 and Inquiries. 4116 o Wallet Identifier and/or Pass Phrase 4118 XML definition: 4120 4121 4134 Output Parameters 4136 o Process State and Percent Complete 4137 o Completion Code 4138 o Status Description and its language annotation 4140 XML definition: 4142 4143 4155 Tables 4 and 5 explain the attributes and elements; Table 3 4156 introduces the Error Codes. 4158 4.4 General Inquiry API Calls 4160 The following calls are not necessarily assigned to a payment 4161 transaction and may be issued at any time. There are no dependencies 4162 on any other calls. 4164 4.4.1 Remove Payment Log 4166 The IOTP Application Core notifies the IOTP Payment Bridge and/or the 4167 corresponding Existing Payment Software via IOTP Payment Bridge that 4168 any record in the Payment Log file, that deals with the listed 4169 payment transaction, might be removed. 4171 Input Parameters 4173 o Party's Payment Identifier 4174 o Wallet Identifier and/or Pass Phrase 4176 XML definition: 4178 4179 4184 Output Parameters 4186 XML definition: 4188 4189 4191 Tables 4 and 5 explain the attributes and elements; Table 3 4192 introduces the Error Codes. 4194 4.4.2 Payment Instrument Inquiry 4196 This API function retrieves the properties of the Payment Instrument. 4197 The Payment Instrument Identifier could be omitted if this identifier 4198 is derived by other means, e.g., by analysis of the currently 4199 inserted chip card. If the Payment instrument could not uniquely 4200 determined, the IOTP Payment Bridge may provide suitable dialogs for 4201 user input. 4203 E.g., this API function might be used during problem resolution with 4204 the Customer Care Provider of the issuer of the payment instrument, 4205 in order to inquire payment instrument specific values. 4207 Input parameters 4209 o Brand Identifier 4210 o Payment Instrument Identifier 4211 o Protocol Identifier 4212 o Wallet Identifier and/or Pass Phrase 4213 o Property Type List - sequence of values whose language is 4214 identified by xml:lang 4215 o (Brand) PackagedContent Content - further payment brand 4216 description 4217 o Protocol Brand Content - further payment brand information 4218 o (Protocol Amount) PackagedContent Content - further payment 4219 protocol description 4220 o (Pay Protocol) PackagedContent Content - further payment 4221 protocol description 4223 The codes in the property type list are of two types: 4225 o generic codes which apply to all payment methods but might be 4226 unavailable 4227 o Payment Brand specific codes. 4229 Generic codes for the Property Type List are: 4231 Property Type Meaning 4232 Balance Current balance 4233 Limit Maximum balance 4234 PaymentLimit Maximum payment transaction limit 4235 Expiration Expiration date 4236 Identifier Issuer assigned identifier of the payment 4237 instrument. Usually, it does not match with 4238 the API's payment instrument identifier. 4239 LogEntries Number of stored payment transaction 4240 entries. The entries are numbered from 0 4241 (the most recent) to some non-negative 4242 value for the oldest entry. 4243 PayAmountn Payment Amount of the n-th recorded payment 4244 transaction, n may negative 4245 PayPartyn Remote party of the n-th payment recorded 4246 transaction, n may negative 4247 PayTimen Time of the n-th payment recorded 4248 transaction, n may negative 4250 XML definition: 4252 4256 4265 Output parameters 4267 o a list of zero or more unavailable property values whose 4268 language are identified by xml:lang. 4269 o a list of zero or more sets of "Properties Types", "Property 4270 Values" and "Property Descriptions" 4272 XML definition: 4274 4276 4280 4281 4286 Tables 4 and 5 explain the attributes and elements; Table 3 4287 introduces the Error Codes. 4289 4.4.3 Inquire Pending Payment 4291 This API function reports the party's payment identifiers of any 4292 pending payment transactions that the IOTP Payment Bridge/Existing 4293 Payment Software recommends to complete or suspend prior to the 4294 processing of new payment transactions. It does not respond further 4295 transaction details. These have to be inquired by "Inquire Process 4296 State". 4298 Note that the IOTP Payment Bridge has to respond without the 4299 supplement of any pass phrase if there exist no pending payment 4300 transaction. But if there are some pending payment transactions, the 4301 IOTP Payment Bridge may refuse the immediate response and may instead 4302 request the appropriate pass phase from the IOTP Application Core. 4304 Input Parameters 4306 o Wallet Identifier and/or Passphrase 4308 XML definition: 4310 4311 4315 Output Parameters 4317 o Party's Payment Identifier 4319 XML definition: 4321 4323 4324 4327 Tables 4 and 5 explain the attributes and elements; Table 3 4328 introduces the Error Codes. 4330 4.5 Payment Related Inquiry API Calls 4332 4.5.1 Check Payment Receipt 4334 This function is used by the Consumer and might be used by the 4335 Payment Handler to check the consistency, validity, and integrity of 4336 IOTP payment receipts whereby any receipt might consist of Packaged 4337 Content Elements 4339 o from the IOTP Payment Receipt Component - provided by the 4340 Payment Handler's "Inquire Process State" API call shortly 4341 before payment completion, 4343 o from Payment Scheme Components being exchanged during the 4344 actual payment, or 4346 o being returned by the Consumer's "Inquire Process State" API 4347 call shortly before payment completion 4349 The IOTP Application Core has to check the PayReceiptNameRefs 4350 attribute of the IOTP Payment Receipt Component and to supply exactly 4351 the Packaged Content Elements being referred to. 4353 Failed verification is returned with a business error. 4355 Note that this Payment API assumes that any payment receipt builds 4356 upon a subset of elements w.r.t. [IOTP]. Furthermore, the Packaged 4357 Content Element have to be distinguishable by their Name attribute. 4359 Input Parameters 4361 o Party's Payment Identifier 4362 o Wallet Identifier and/or Pass Phrase 4363 o All Packaged Content Elements that build the payment receipt 4365 XML definition: 4367 4368 4373 Output Parameters 4375 XML definition: 4377 4378 4380 Tables 4 and 5 explain the attributes and elements; Table 3 4381 introduces the Error Codes. 4383 4.5.2 Expand Payment Receipt 4385 This API function expands any IOTP payment receipt into a form which 4386 may be used for display or printing purposes. "Check Payment Receipt" 4387 should be used first if there is any question of the payment receipt 4388 containing errors. 4390 There apply the same conventions to the input parameter as for "Check 4391 Payment Receipt" (cf. Section 4.5.1). 4393 Input Parameters 4395 o Party's Payment Identifier 4396 o Wallet Identifier and/or Pass Phrase 4397 o All Packaged Content Elements that build the payment receipt 4399 XML definition: 4401 4402 4407 Output Parameters 4409 o Brand Identifier 4410 o Protocol specific Brand Identifier 4411 o Payment Instrument Identifier 4412 o Currency Code and Currency Code Type 4413 o Payment Amount 4414 o Payment Direction 4415 o Time Stamp - issuance of the receipt 4416 o Protocol Identifier 4417 o Protocol specific Transaction Identifier - this is an internal 4418 reference number which identifies the payment 4419 o Consumer Description, Payment Handler Description, and a 4420 language annotation 4422 o Style Sheet Net Location 4423 o Payment Property List. A list of type/value/description triples 4424 which contains additional information about the payment which 4425 is not covered by any of the other output parameters; property 4426 descriptions have to consider the language annotation. 4428 The Style Sheet Net Location refers to a Style Sheet (e.g. [XSLT]) 4429 that contains visualization information about the reported XML 4430 encoded data. 4432 XML definition: 4434 4435 4451 4452 4457 The Existing Payment Software should return as many attributes as 4458 possible from the supplied IOTP Payment Receipt. The payment 4459 supplement define that attribute value for the payment properties. 4461 Tables 4 and 5 explain the attributes and elements; Table 3 4462 introduces the Error Codes. 4464 4.5.3 Inquire Process State 4466 This API function returns the current payment state and optionally 4467 further Packaged Content Elements that form the payment receipt. 4468 Called by the Payment Handler, the IOTP Payment Bridge might respond 4469 with data intended for inclusion in the IOTP Payment Receipt 4470 Component's Packaged Content. When the Consumer calls this function 4471 shortly before payment completion, it may respond with further items 4472 of the payment receipt. Such items might be created by a chip card. 4474 Input Parameters 4476 o Party's Payment Identifier 4477 o Wallet Identifier and/or Pass Phrase 4479 XML definition: 4481 4482 4487 Output Parameters 4489 o Current Process State and Percent Complete 4490 o Completion Code 4491 o Status Description and its language annotation 4492 o Payment Receipt Name References to all Packaged Content 4493 Elements that build the payment receipt (cf. Section 4.5.1), 4494 even if they have not been created so far (Consumer's share) 4495 o Any Packaged Content Element being available that form the 4496 payment receipt 4498 The IOTP provides a linking capability to the payment receipt 4499 delivery. Instead of encapsulating the whole payment specific data 4500 into the packaged content of the payment receipt, other Payment 4501 Scheme Components' Packaged Content might be referred to. 4503 XML definition: 4505 4507 4520 Tables 4 and 5 explain the attributes and elements; Table 3 4521 introduces the Error Codes. 4523 4.5.4 Start Payment Inquiry 4525 This API function responds any additional payment scheme specific 4526 data that is needed by the Payment Handler for Consumer initiated 4527 payment transaction inquiry processing. Probably, the IOTP Payment 4528 Bridge (or the corresponding Existing Payment Software) has to 4529 determine the payment related items that were provided with the 4530 "Start Payment Consumer" API function call. 4532 Input Parameters 4534 o Consumer Payment Identifier 4535 o Wallet Identifier and/or Pass Phrase 4537 XML definition: 4539 4540 4545 Output Parameters 4547 o (Payment Scheme) Packaged Content - intended for insertion in 4548 the Payment Scheme Component of the Inquiry Request Block 4550 XML definition: 4552 4555 Tables 4 and 5 explain the attributes and elements; Table 3 4556 introduces the Error Codes. 4558 4.5.5 Inquire Payment Status 4560 The Payment Handler calls this API function for Consumer initiated 4561 inquiry processing. It differs from the previous "Inquire Process 4562 State" API function by the optional supplement of payment scheme 4563 specific data. The response may encapsulate further details about the 4564 payment transaction. 4566 Input Parameters 4568 o Payment Handler Payment Identifier 4569 o Wallet Identifier and/or Pass Phrase 4570 o (Payment Scheme) Packaged Content - copied from the Inquiry 4571 Request Block's Payment Scheme Component 4573 XML definition: 4575 4576 4581 Output Parameters 4583 o Current Process State 4584 o Completion Code 4585 o Status Description and its language annotation 4586 o (Payment Scheme) Packaged Content - intended for insertion in 4587 the Payment Scheme Component of the Inquiry Response Block 4589 XML definition: 4591 4593 4605 Tables 4 and 5 explain the attributes and elements; Table 3 4606 introduces the Error Codes. 4608 4.6 Other API Calls 4609 4.6.1 Manage Payment Software 4611 The following API function notifies the IOTP Payment Bridge about the 4612 intended registration, modification, or deletion of a payment 4613 instrument. The actual processing is up to the IOTP Payment Bridge. 4615 This API request may also be used to activate the IOTP Payment Bridge 4616 (and the corresponding Existing Payment Software) for general 4617 administration purposes. 4619 Input Parameters 4621 o Brand Identifier 4622 o Protocol Identifier 4623 o Any action code: 4624 o New - add new payment method / instrument 4625 o Update - change the payment method's / instrument's data 4626 o Delete - delete a payment method / instrument 4627 o Wallet Identifier and/or Pass Phrase 4628 o (Brand) Packaged Content - further payment brand description 4629 o (Pay Protocol) Packaged Content - further payment protocol 4630 description 4631 o (Protocol Amount) Packaged Content - further payment protocol 4632 description 4634 If the Action attribute is set, the Brand and Protocol Identifier 4635 have to be set, too. The IOTP Payment Bridge has to provide the 4636 required user dialogs and selection mechanisms. E.g., updates and 4637 deletions may require the selection of the payment instrument. A new 4638 wallet might be silently generated on the supplement of a new Wallet 4639 Identifier or after an additional end user acknowledge. The IOTP 4640 Application Core should not provide any pass phrases for new wallets. 4641 Instead, the IOTP Payment Bridge has to request and verify them which 4642 may return their value to the IOTP Application Core in plain text. In 4643 addition, the IOTP Payment Bridge returns the supported 4644 authentication algorithms when a new brand and protocol pair has been 4645 registered. 4647 If the "Action" attribute is omitted, the IOTP Payment Bridge which 4648 is responsible for the Existing Payment Software pops up in a general 4649 interactive mode. 4651 XML definition: 4653 4656 4665 Output Parameters 4667 o An action code: 4668 o New - added new wallet 4669 o Update - changed wallet's configuration 4670 o Delete - removed a wallet 4671 o Wallet Identifier and/or Pass Phrase 4673 The IOTP Payment Bridge does not return any information about the set 4674 of registered payment instruments because these data items are 4675 dynamically inferred during the brand selection process at the 4676 beginning of each IOTP transaction. However, the IOTP Application 4677 Core has to be notified about new wallets and should be notified 4678 about updated and removed wallet (identifier)s". Alternatively, 4679 removed wallets can be implicitly detected during the next brand 4680 selection phase. Updated wallets do no affect the processing of the 4681 IOTP Application Core. The IOTP Payment Bridge should only support 4682 the addition of at most one wallet because it is not able to report 4683 multiple additions at once back to the IOTP Application Core. 4685 XML definition: 4687 4688 4696 Tables 4 and 5 explain the attributes and elements; Table 3 4697 introduces the Error Codes. 4699 5. Call Back Function 4701 This API function, called by the IOTP Payment Bridge, is used to 4702 provide information for Consumer or Payment Handler notification 4703 about the progress of the payment transaction. 4705 Its use is illustrated in the diagram below. 4707 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 4708 IOTP Application ----calls---- 4709 | Core | | 4710 display | | v 4711 to <---------- Call Back <--calls--- Payment 4712 user | | Software 4713 ---------------- 4714 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 4716 Figure 9. Call Back Function 4718 Whenever this function is called, the content of the status 4719 description should be made available to the user. For example on a 4720 status bar, a pop up window, etc. 4722 A reference to the Call Back function is passed as an input parameter 4723 to the "Start Payment X" and "Resume Payment X" API function. 4724 Afterwards, this function might be called whenever the status changes 4725 or progress needs to be reported. 4727 Input Parameters 4729 o the software identifier of the caller 4730 o Party's Payment Identifier 4731 o Process State and Percent Complete 4732 o Completion Code 4733 o Status Description and its language annotation, text which 4734 provides information about the progress of the call. It should 4735 be displayed or made available to, for example, the Consumer. 4737 Examples of Status Description could be: 4739 o "Paying 12.30 USD to XYZ Inc" 4740 o "Payment completed" 4741 o "Payment aborted" 4743 The valid languages are announced in the Call Back Language List 4744 attribute in "Start Payment X" and "Resume Payment X" API function 4745 calls. 4747 XML definition: 4749 4750 4764 Output Parameters 4766 XML definition: 4768 4769 > 4771 Tables 4 and 5 explain the attributes and elements; Table 3 4772 introduces the Error Codes. 4774 Basically, the call back function accepts all input arguments or 4775 rejects the whole request. It may even accept malformed requests. 4777 Some payment schemes may support or require that the Consumer might 4778 be able to cancel the payment at any time. The Call Back function can 4779 be used to facilitate this by returning the cancellation request on 4780 the next call (using the Business Error Code and Completion Code 4781 "ConsCancelled"). 4783 Vice versa the Payment Handler's Application Core might use the 4784 similar mechanism to signal its IOTP Payment Bridges any exceptional 4785 need for a fast shutdown. These IOTP Payment Bridges may initiate the 4786 appropriate steps for terminating/canceling all pending payment 4787 transactions. 4789 Note that the "Change Process State" API function provides the second 4790 mechanism for such kind of notification. Therefore, the IOTP Payment 4791 Bridge or Existing Payment Software may ignore the details of the 4792 "Call Back" response. 4794 6. Security Consideration 4796 The IOTP Payment APIs only supports security using pass phrase to 4797 access to payment Wallet. These can be protected over TLS, which 4798 provides stronger security at the transport layer, but 4799 implementations are out the scope of this document. 4801 See also security consideration section of [IOTP]. 4803 Full Copyright Statement 4805 Copyright (C) The Internet Society 2000. 4807 This document and translations of it may be copied and furnished to 4808 others, and derivative works that comment on or otherwise explain it 4809 or assist in its implementation may be prepared, copied, published 4810 and distributed, in whole or in part, without restriction of any 4811 kind, provided that the above copyright notice and this paragraph are 4812 included on all such copies and derivative works. However, this 4813 document itself may not be modified in any way, such as by removing 4814 the copyright notice or references to the Internet Society or other 4815 Internet organizations, except as needed for the purpose of 4816 developing Internet standards in which case the procedures for 4817 copyrights defined in the Internet Standards process must be 4818 followed, or as required to translate it into languages other than 4819 English. 4821 The limited permissions granted above are perpetual and will not be 4822 revoked by the Internet Society or its successors or assigns. 4824 This document and the information contained herein is provided on an 4825 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4826 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4827 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4828 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4829 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4831 References 4833 [IOTP] - Internet Open Trading Protocol Specification, Version 1.0, 4834 April 2000, See RFC2801. 4836 [IOTPBOOK] - D. Burdett, D.E. Eastlake III, and M. Goncalves, 4837 Internet Open Trading Protocol, McGraw-Hill, 2000. ISBN 0-07-135501- 4838 4. 4840 [HTML] - Hyper Text Mark Up Language. The Hypertext Markup Language 4841 (HTML) is a simple markup language used to create hypertext documents 4842 that are platform independent. See RFC 1866 and the World Wide Web 4843 (W3C) consortium web site at: http://www.w3.org/MarkUp/ 4845 [HTTP] - Hyper Text Transfer Protocol versions 1.0 and 1.1. See RFC 4846 1945: Hypertext Transfer Protocol - HTTP/1.0. T. Berners-Lee, R. 4847 Fielding & H. Frystyk. May 1996. and RFC 2068: Hypertext Transfer 4848 Protocol - HTTP/1.1. R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. 4849 Berners-Lee. January 1997. 4851 [ISO4217] - ISO 4217: Codes for the Representation of Currencies. 4852 Available from ANSI or ISO. 4854 [MIME] - Multipurpose Internet Mail Extensions. See RFC822, RFC2045, 4855 RFC2046, RFC2047, RFC2048 and RFC2049. 4857 [URL] - Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform 4858 Resource Locators (URL)", RFC 1738, December 1994. 4860 [SET] - SET Secure Electronic Transaction(TM) , Version 1.0, May 31, 4861 1997 4862 Book 1: Business Description 4863 Book 2: Programmer's Guide 4864 Book 3: Formal Protocol Definition 4865 Download from: . 4867 [SET/IOTP] - Yoshiaki Kawatsura "SET Supplement for IOTP" (currently 4868 draft-ietf-trade-iotp-v1.0-set-02.txt) 4870 [UTC] - Universal Time Coordinated. A method of defining time 4871 absolutely relative to Greenwich Mean Time (GMT). Typically of the 4872 form: "CCYY-MM- DDTHH:MM:SS.sssZ+n" where the "+n" defines the number 4873 of hours from GMT. See ISO DIS8601. 4875 [XML] - Extensible Mark Up Language (XML) 1.0 (Second Edition). A 4876 W3C recommendation. See http://www.w3.org/TR/1998/REC-xml 4878 [XSLT] - Extensible Style Language Transformations 1.0, November 4879 1999, See http://www.w3.org/TR/xslt 4881 [XML-NS] - Namespaces in XML Recommendation. T. Bray, D. Hollander, 4882 A. Layman. Janaury 1999. http://www.w3.org/TR/1999/REC-xml-names 4884 Author's Addresses 4886 Hans-Bernhard Beykirch and Werner Hans 4887 IT Development & Coordination Center for the German Savings Banks 4888 Organization (SIZ) 4889 Konigswinterer Strase 553 4890 53227 Bonn 4891 Germany 4892 E-mail: Hans-Bernhard.Beykirch@siz.de, Werner.Hans@siz.de 4894 Masaaki Hiroya and Yoshiaki Kawatsura 4895 Hitachi, Ltd. 4896 890 Kashimada Saiwai-ku Kawasaki-shi 4897 Kanagawa, Japan 212-8567 4898 E-mail: hiroya@sdl.hitachi.co.jp, kawatura@bisd.hitachi.co.jp 4900 Expiration and File Name 4902 This draft expires May 2001. 4904 Its file name is draft-ietf-trade-iotp-v1.0-papi-03.txt.