idnits 2.17.1 draft-ietf-trade-iotp-v1.0-papi-04.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-04', 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 1714 has weird spacing: '...n error that ...' == Line 1752 has weird spacing: '...ding on the n...' == Line 1763 has weird spacing: '...Content cf. T...' == Line 2810 has weird spacing: '...ontents must ...' == Line 4549 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 (March 2001) is 8436 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 1334, but not defined == Missing Reference: 'PSn' is mentioned on line 1124, but not defined == Missing Reference: 'PS2' is mentioned on line 1335, but not defined == Missing Reference: 'TLS' is mentioned on line 2615, but not defined == Unused Reference: 'HTML' is defined on line 4834, but no explicit reference was found in the text == Unused Reference: 'HTTP' is defined on line 4839, but no explicit reference was found in the text == Unused Reference: 'IOTPBOOK' is defined on line 4848, but no explicit reference was found in the text == Unused Reference: 'ISO4217' is defined on line 4852, but no explicit reference was found in the text == Unused Reference: 'MIME' is defined on line 4855, but no explicit reference was found in the text == Unused Reference: 'SET' is defined on line 4858, but no explicit reference was found in the text == Unused Reference: 'UTC' is defined on line 4871, but no explicit reference was found in the text ** Obsolete normative reference: RFC 1866 (ref. 'HTML') (Obsoleted by RFC 2854) ** Obsolete normative reference: RFC 2068 (ref. 'HTTP') (Obsoleted by RFC 2616) ** Downref: Normative reference to an Informational RFC: RFC 2801 (ref. 'IOTP') -- Possible downref: Non-RFC (?) normative reference: ref. 'IOTPBOOK' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO4217' -- Possible downref: Non-RFC (?) normative reference: ref. 'SET' ** Obsolete normative reference: RFC 1738 (ref. 'URL') (Obsoleted by RFC 4248, RFC 4266) -- Possible downref: Non-RFC (?) normative reference: ref. 'UTC' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML-NS' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSLT' Summary: 11 errors (**), 0 flaws (~~), 19 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 TRADE Working Group Werner Hans 2 INTERNET-DRAFT Hans-Bernhard.Beykirch 3 SIZ 4 Masaaki Hiroya 5 Yoshiaki Kawatsura 6 Hitachi 7 Expires: September 2001 March 2001 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 2001. 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 a 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 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. Additionally, 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 will try 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 may 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 termination or 606 suspension without success. 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 the presence of an IOTP Authentication Block within the 749 received IOTP message, the Authenticatee's IOTP Application Core 750 checks whether the IOTP transaction type in the current phase 751 actually 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 for 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 be immediately solved by the IOTP Application Core 860 should be logged - this applies also to the subsequent API calls 861 of this section. In this case, the IOTP Application Core creates 862 an IOTP Error Block (hard error), transmits it to the Consumer, 863 and 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 to 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 the "equal" items returned by IOTP Payment Bridge function calls 888 are shared due to the extensive linking capabilities within the 889 Brand List Component. However, the compilation must consider 890 several aspects in order to prevent conflicts - sharing detection 891 might be 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 sets of brand and protocol such that 1012 the join of all sets describes exactly the 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 asked 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 of some required physical 1069 payment 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 offered 1080 o to resolve the problem, e.g. to insert another payment 1081 instrument or to verify the periphery, 1082 o to proceed (assuming its success), 1083 o to cancel the whole transaction, or 1084 o to suspend the transaction, e.g., initiating a nested 1085 transaction for uploading an electronic purse. 1087 If the payment software implements payment instrument selection on 1088 its own, it may request the Consumer's choice at this step. 1090 If the check succeeds, it returns several IOTP Brand Selection 1091 Info Elements. 1093 6. The Steps 2 to 5 are repeated and possibly interlaced for the 1094 selection of the second payment instrument during IOTP Value 1095 Exchange transactions - this is omitted in the figure above. 1097 7. The IOTP Brand Selection Component is generated and enriched with 1098 the Brand Selection Info elements. This component is transmitted 1099 to the Merchant inside a TPO Selection Block if the received IOTP 1100 message lacks the IOTP Offer Response Block. The Merchant will 1101 then respond with an IOTP Offer Response Block (following the 1102 aforementioned compilation rules). 1104 2.4 Successful Payment 1106 An example of how the functions in this document are used together to 1107 effect a successful payment is illustrated in the Figure 5. 1109 (Technically, two payments happen during IOTP Value Exchange 1110 transactions.) 1112 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1113 Consumer Start Payment Consumer(Amount,[PS0]...) -> IPB 1114 Start Payment Cons. Res.([PS1], CS=Cont.) <- IPB 1115 Create and transmit Payment Request Block 1116 Payment Handler Start Payment Pay. Handler(Amount, [PS1]) -> IPB 1117 Start Payment PH Response(PS2, CS=Cont.) <- IPB 1118 Create and transmit Payment Exchange Block 1119 Consumer Continue Process(PS2) -> IPB 1120 Continue Process Response(PS3, CS=Cont.) <- IPB 1122 ... CONTINUE SWAPPING PAYMENT EXCHANGES UNTIL ... 1124 Payment Handler Continue Process Response([PSn], CS=End) <- IPB 1125 Request any local payment receipt 1126 | Inquire Process State() -> IPB 1127 | Inquire Proc. State Resp.(State, [Rcp.])<- IPB 1128 Create and transmit Payment Response Block 1129 Terminate transaction, actively 1130 | Change Process State(State) -> IPB 1131 | Change PS Response(State=CompletedOK) <- IPB 1132 Consumer On receipt of final payment scheme data 1133 | Continue Process(PSn) -> IPB 1134 | Continue Process Response(CS=End) <- IPB 1135 Check Payment Receipt(Receipt) -> IPB 1136 Check Payment Receipt Response() <- IPB 1137 Request any local payment receipt 1138 | Inquire Process State() -> IPB 1139 | Inquire Proc. State Resp.(State, [Rcp.])<- IPB 1140 Terminate transaction, actively 1141 | Change Process State(State) -> IPB 1142 | Change PS Response(State=CompletedOk) <- IPB 1143 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1145 Figure 5. Example Payment Message Flows 1147 1. After Brand Selection and receipt of the IOTP Offer Response 1148 Block, the Consumer switches from communicating with the Merchant 1149 to communicating with the Payment Handler. 1151 This might be a milestone requiring the renewed Consumer's 1152 agreement about the payment transaction's continuation. 1153 Particularly, this is a good moment for payment suspension (and 1154 even cancellation), which will be most probably supported by all 1155 payment schemes. Simply, because the actual payment legacy systems 1156 have not yet been involved in the current transaction. 1158 Such an agreement might be explicit per transaction or automatic 1159 based on configured preferences, e.g., early acknowledgments for 1160 specific payment limits. 1162 It is assumed, that the transaction proceeds with minimal user 1163 (Consumer and Payment Handler) interaction and that its progress 1164 is controlled by the IOTP Application Core and IOTP Payment 1165 Bridge. 1167 2. In order to open the actual payment transaction, the IOTP 1168 Application Core issues the "Start Payment Consumer" request 1169 towards the IOTP Payment Bridge. This request carries the whole 1170 initialization data of the payment transaction being referred to 1171 by the IOTP Payment Bridge for subsequent consistency checks: 1173 o payment brand and its description from the selected Brand 1174 Element of the IOTP Brand List Component, 1175 o payment instrument from preceding inquiry step, 1176 o further payment parameters (currency, amount, direction, 1177 expiration) from the selected Currency Amount element, Brand 1178 List Component, and Payment Component of the IOTP Offer 1179 Response Block, 1180 o payment protocol from the selected IOTP Pay Protocol Element, 1181 o order details contained in the IOTP Order Component which 1182 might be payment scheme specific, 1183 o payment scheme specific data inclusive of the payment 1184 protocol descriptions from the IOTP Protocol Amount Element, 1185 and IOTP Pay Protocol Element, and 1186 o payment scheme specific data inclusive of the payment 1187 protocol descriptions, in which the name attribute includes 1188 the prefix as "Payment:" from the Trading Role Data 1189 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 similarly 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 such checks are part of the specific payment 1213 protocol. 1215 If the IOTP Payment Bridge requests wallet identifiers or pass 1216 phrases anywhere during the payment process, they should be 1217 requested by this API function, too. It is recommended that the 1218 IOTP Application Core stores plain text pass phrases only in 1219 runtime memory. 1221 Finally, the IOTP Application Core generates the IOTP Payment 1222 Request Block, inserts any returned payment scheme data, and 1223 submits it to the Payment Handler's system. 1225 3. The Payment Handler's IOTP Application Core opens the payment 1226 transaction calling the "Start Payment Payment Handler" API 1227 function. The payment brand, its description, payment protocol, 1228 payment specific data, payment direction, currency and payment 1229 amount are determined quite similar to the Consumer's IOTP 1230 Application Core. Furthermore, the content of the IOTP Payment 1231 Scheme Component and the IOTP Brand Selection Info Elements are 1232 passed to this function. 1234 On success, the Payment Handler's IOTP Payment Bridge responds 1235 with payment scheme specific data. On failures, this non- 1236 interactive server application has to resolve any problems on its 1237 own or to give up aborting the payment transaction. However, the 1238 Consumer may restart the whole payment transaction. Anyway, the 1239 payment log file should reflect any trials of payments. 1241 Eventually, the Payment Handler informs the Consumer about the 1242 current IOTP Process State using the IOTP Payment Response or IOTP 1243 Error Block. 1245 Note that the "Start Payment Payment Handler" call might return 1246 the Continuation Status "End" such that payment processing 1247 proceeds with Step 7. 1249 4. The IOTP Application Core verifies the presence of the Payment 1250 Exchange Block in the IOTP message and passes the contained 1251 payment scheme specific data to the fixed IOTP Payment Bridge 1252 ("Continue Process") which returns the next IOTP Payment Scheme 1253 Component. 1255 This Payment Scheme Component is encapsulated in an IOTP Payment 1256 Exchange Block and transmitted to the Payment Handler. 1258 5. The Payment Handler's IOTP Application Core verifies the presence 1259 of the Payment Exchange Block and passes the contained payment 1260 scheme specific data to the fixed IOTP Payment Bridge ("Continue 1261 Process") which returns the next IOTP Payment Scheme Component for 1262 encapsulation and transmission to the Consumer. 1264 6. The payment process continues with IOTP Payment Exchange Block 1265 exchanges, carrying the payment scheme specific data. Each party 1266 (1) submits the embedded payment scheme specific data 1267 transparently to the appropriate IOTP Payment Bridge calling the 1268 "Continue Process" API function, (2) wraps the returned payment 1269 scheme specific data into an IOTP Payment Exchange Block, and (3) 1270 transmits this block to the counter party. 1272 However, the processing of the payment scheme specific data may 1273 fail for several reasons. These are signaled by specific error 1274 codes which are transformed to IOTP Payment Response Blocks 1275 (generated by Payment Handler) or IOTP Error Blocks (both parties 1276 may generate them) and transmitted to the counter party. 1278 7. Eventually, the Payment Handler's IOTP Payment Bridge recognizes 1279 the termination of the payment transaction and reports this by the 1280 continuation status "End" on the output parameter of "Continue 1281 Process" (or "Start Payment Payment Handler"). Then, the IOTP 1282 Application Core issues the "Inquire Process State" API call and 1283 verifies whether an IOTP Payment Receipt Component has been 1284 returned. The IOTP Application Core wraps the payment receipt, the 1285 status response, and the optional payment scheme specific data in 1286 an IOTP Payment Response Block and transmits this block to the 1287 Consumer. 1289 However, any of these API calls may fail or any response might be 1290 incomplete (e.g., lack of payment receipt). Then, the Consumer has 1291 to be notified about the failed processing by an IOTP Error Block. 1293 Finally, the Payment Handler terminates the payment transaction 1294 with the "Change Process State" API call without awaiting any 1295 further response from the Consumer. Further failures are not 1296 reported to the Consumer. 1298 Note that it might be possible that the Consumer's IOTP Payment 1299 Bridge has returned the previous payment scheme specific data with 1300 the continuation status "End". Even in the absence of this 1301 knowledge - this status is not exchanged between the Consumer and 1302 the Payment Handler - the Payment Handler must not supply any 1303 further payment scheme specific data. Such data will be rejected 1304 by the Consumer's IOTP Payment Bridge. 1306 8. The Consumer passes the optional payment scheme specific data and 1307 the payment receipt to the fixed IOTP Payment Bridge by "Continue 1308 Process" and "Check Payment Receipt" API calls. 1310 Afterwards, the IOTP Application Core issues the "Inquire Process 1311 State" API call and verifies whether extensions to the payment 1312 receipt have been returned. 1314 Finally, the transaction is terminated by calling the "Change 1315 Process State" API function which verifies and synchronizes the 1316 reported payment status with the local one and signals any 1317 inconsistencies. Any Inconsistency and returned status text should 1318 be displayed to the Consumer. 1320 At this point, the payment transaction has already been closed by 1321 the Payment Handler. Therefore, any failure has to be resolved 1322 locally or out-of-band. 1324 2.5 Payment Inquiry 1326 In Baseline IOTP, Payment inquiries are initiated by the Consumer in 1327 order to verify the current payment progress and process state at the 1328 remote Payment Handler. 1330 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1331 Consumer Start Payment Inquiry() -> IPB 1332 Start Payment Inquiry Response([PS1]) <- IPB 1333 Create and transmit Inquiry Request Trading Block 1334 Payment Handler Inquire Payment Status([PS1]) -> IPB 1335 Inquire Payment Status Res.(State, [PS2]) -> IPB 1336 Create and transmit Inquiry Response Trading 1337 Block 1338 Consumer If Payment Scheme Data present 1339 | Continue Process(PS2) -> IPB 1340 | Continue Process Response(CS=End) <- IPB 1341 Change Process State(State) -> IPB 1342 Change Process State Response(State) <- IPB 1343 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1345 Figure 6. Remote Process State Inquiry 1347 1. The Consumer might initiate a payment inquiry once the payment 1348 transaction has been opened by the IOTP Application Core, i.e., at 1349 any time after the initial submission of the IOTP Payment Request 1350 Block. The IOTP Application Core requests any additional specific 1351 payment scheme data from the IOTP Payment Bridge which has been 1352 fixed during brand selection (cf. Section 2.3) using the "Start 1353 Payment Inquiry" API request. 1355 Erroneous API responses should be reported to the Consumer and 1356 valid alternatives (typically retry and cancellation) should be 1357 presented by the IOTP Application Core. 1359 This request might perform the complete initialization, e.g. 1360 availability check of periphery or pass phrase supplement, and the 1361 IOTP Payment Bridge reports lack of capability quite similarly to 1362 the "Check Payment Possibility" request to the IOTP Application 1363 Core. 1365 If the IOTP Payment Bridge requests wallet identifiers or pass 1366 phrases anywhere during the payment process, they should be 1367 requested by this API function, too. It is recommended that the 1368 IOTP Application Core store plain text pass phrases only in 1369 runtime memory. 1371 The IOTP Application Core encapsulates any Payment Scheme 1372 Component in an IOTP Inquiry Request Block and submits the block 1373 to the Payment Handler. 1375 2. The Payment Handler analyses the IOTP Inquire Request Block, maps 1376 the Transaction Identifier to payment related attributes (brand, 1377 consumer and payment identifiers), determines the appropriate IOTP 1378 Payment Bridge, and forwards the request to the this IOTP Payment 1379 Bridge ("Inquire Payment Status"). The IOTP Application Core 1380 transforms the response to an IOTP Inquiry Response Block and 1381 transmits it to the Consumer. 1383 3. On receipt of the respective IOTP Inquiry Response Block the 1384 Consumer's IOTP Application Core submits any encapsulated payment 1385 scheme specific data to the IOTP Payment Bridge for verification 1386 ("Continue Process"). 1388 4. The IOTP Application Core passes the reported payment status 1389 (except textual descriptions) to the IOTP Payment Bridge ("Change 1390 Process State") for verification purposes and payment status 1391 change. The IOTP Payment Bridge reports any inconsistencies as 1392 well as the final payment status to the IOTP Application Core. 1394 Any additional information that might be of interest to the 1395 Consumer has to be displayed by the IOTP Payment Bridge or 1396 Existing Payment Software on their own. 1398 2.6 Abnormal Transaction Processing 1399 2.6.1 Failures and Cancellations 1401 The IOTP specification distinguishes between several classes of 1402 failures: 1404 o Business and technical errors 1405 o Error depths of transport, message and block level 1406 o Transient errors, warnings, and hard errors. 1408 Any IOTP Payment API has to deal with the receipt of failure 1409 notifications by and failure responses. This proposal has borrowed 1410 the basic mechanisms for error reporting between the IOTP Application 1411 Core and the IOTP Payment Bridge from the actual protocol: Business 1412 errors are reported by Status Components within IOTP Response Blocks 1413 while technical errors are signaled by Error Components within IOTP 1414 Error Blocks. 1416 Cancellations are mimicked as specific business errors which might be 1417 initiated by each trading party. 1419 Preferring slim interfaces, this IOTP Payment API introduces one 1420 additional Error Code value for business error indication - errors 1421 can be raised on every API call. On receipt of this value, the IOTP 1422 Application Core has to infer further details by the issuance of the 1423 API function call "Inquire Process State". 1425 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1426 Any Party Issue some API request -> IPB 1427 Error Response(Error Code) <- IPB 1428 On "Business Error" response 1429 | Inquire Process State() -> IPB 1430 | Inquire P.S. Resp.(State, Receipt) <- IPB 1431 Analyze local process state and try to resolve 1432 with optional user interaction 1433 If Process State Change needed 1434 | Change Process State (State) -> IPB 1435 | Change Process State Response(State) <- IPB 1436 If counter party's notification required 1437 | Create Error or Cancel Block (, add to next 1438 | message, ) and transmit it to counter party 1439 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1441 Figure 7. Error Response from IPB 1443 The specific Completion Codes "ConsCancelled", "MerchCancelled", and 1444 "PaymCancelled" - returned by "Inquire Process State" - determine 1445 that the IOTP Cancel Block has to be created instead of an IOTP Error 1446 Block. 1448 The rules for determining the required behavior of the IOTP 1449 Application Core are given in the IOTP specification. 1451 Note that any payment (intermediate) termination, i.e., failures, 1452 cancellations, and even successes are always reported to the IOTP 1453 Payment Bridge by the API function "Change Process State". This API 1454 function does both status changes and consistency checking / 1455 synchronization. Any suspicion of inconsistency should be reported by 1456 the IOTP Payment Bridge for display by the IOTP Application Core. 1458 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1459 Any Party Error Block or Cancel Block Received 1460 If Change Process State required 1461 | Change Process State (State) -> IPB 1462 | Change Process State Response(State) <- IPB 1463 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 1465 Figure 8. Error Notification from counter party 1467 Not every failure might be visible at the IOTP layer, e.g., the 1468 processing of payment transactions might temporarily be hampered by 1469 intermediate failures at the payment scheme or protocol transport 1470 layer which might be resolved by the actual components. 1472 However, final failures or cancellations have to be reported at the 1473 IOTP layer. E.g., communication time-outs and heavily faulty 1474 communication channels may disable the transaction. 1476 Any system component may implement time-out recognition and use the 1477 aforementioned API mechanisms for the notification of process state 1478 changes. But, time-outs may happens while communicating with both the 1479 counter party and local system components, like chip card readers or 1480 IOTP Payment Bridges. Anyway, the Consumer's IOTP Application Core 1481 should notify the Consumer about the resolution alternatives, i.e., 1482 retry, suspension, and cancellation. 1484 2.6.2 Resumption 1486 Payment transaction resumption may apply at different steps of a 1487 payment transaction: 1489 o The Consumer's and Payment Handler's view of the transaction might 1490 not be synchronized: Due to different time-out values the payment 1491 transaction may not have been suspended by the counter party. 1493 Any "Resume Payment ..." API function responds with an Error Code 1494 on non-suspended payment transaction that signals a business error. 1495 Afterwards the IOTP Application Core has to issue the "Inquire 1496 Process State" API call for further analysis of the process state. 1498 o One IOTP message sent by one party might not be processed 1499 successfully or even received by the counter party. 1501 This needs to be handled by the actual payment scheme. It is 1502 expected that the IOTP Application Core will not recognize 1503 anything. 1505 o IOTP does not provide any specific signal for payment resumption. 1506 On receipt of every IOTP Payment Exchange Block, the IOTP 1507 Application Core has to decide whether this Block belongs to a 1508 pending transaction or to a suspended transaction that should be 1509 resumed. The IOTP Application Core might call the "Inquire Process 1510 State" API function to update any lack of knowledge. 1512 Any "Resume Payment" API function responds with an Error Code on 1513 non-suspended payment transaction that signals a business error. 1514 Similar, the "Continue Process" API function should report business 1515 errors on non-pending payment transactions. 1517 o The payment transaction may not have been created at the Payment 1518 Handler (early suspension and failed data transmission). In that 1519 case, the IOTP Application Core should respond with a business 1520 error that signals the repetition of the payment transaction (by 1521 the Consumer). 1523 Any "Resume Payment", "Continue Process" or "Inquire Process State" 1524 API function should return with an Error Code "AttValIllegal" on 1525 non-existent payment transaction whereby the further Error 1526 Attribute "Names" denote the payment identifier. 1528 o The IOTP Application Core should always request fresh payment 1529 scheme specific data on resumption - for synchronization purposes 1530 with the Existing Payment Software. Old data in the cache that has 1531 not been send to the counter party should not be accessed. 1533 If the Consumer does not reconnect within an acceptable amount of 1534 time, the Payment Handler's system may perform local failure 1535 resolution in order to close the transaction and to retain resources 1536 for other transactions ("Change Process State"). If the Consumer 1537 reconnect afterwards, an IOTP Payment Response or IOTP Error Block 1538 could be generated. 1540 2.7 IOTP Wallet Initialization 1542 At startup or on explicit user request the IOTP Application Core 1543 should check its IOTP Payment Bridges' internal status by searching 1544 for pending payment transactions. 1546 1. The IOTP Application Core interrogates the registered IOTP 1547 Payment Bridges about pending payment transactions. The IOTP 1548 Application Core may store indicators for pending transactions and 1549 use them for driving any subsequent inquiry ("Inquire Pending 1550 Payment"). 1552 2. If one or more IOTP Payment Bridges report the presence of pending 1553 transactions, the IOTP Application Core may try to suspend 1554 ("Change Process State") or resume (only Consumer: "Resume Payment 1555 Consumer") the pending transactions (on user request). 1557 The IOTP Payment Bridge may deny the processing of any new payment 1558 transactions until the pending transactions have been processed. Such 1559 denials are signaled by the error code "Business Error". 1561 2.8 Payment Software Management 1563 The IOTP Application Core provides only a simple and generic 1564 interface for the registration of new payment methods / instruments 1565 ("Manage Payment Software"). It receives the initial user request and 1566 defers the actual registration to the corresponding IOTP Payment 1567 Bridge. 1569 The IOTP Application Core may also activate the Existing Payment 1570 Software for further payment instrument and wallet administration. 1572 3. Mutuality 1574 The Payment API is formalized using the eXtensible Markup Language 1575 (XML). It defines wrapper elements for both the input parameters and 1576 the API function's response. In particular, the response wrapper 1577 provides common locations for Error Codes and Error Descriptions. 1579 It is anticipated that this description reflects the logical 1580 structure of the API parameter and might be used to derive 1581 implementation language specific API definitions. 1583 XML definition: 1585 1611 1617 1643 1649 1650 1660 Most of the attribute items are intended for immediate insertion in 1661 the IOTP Error Block. The attribute values of the Error Location 1662 elements attribute have to enriched and transformed into Error 1663 Location Elements of the Error Component (cf. IOTP Specification). 1665 Attributes (cf. IOTP Specification): 1667 xml:lang Defines the language used by attributes or 1668 child elements within this component, unless 1669 overridden by an xml:lang attribute on a child 1670 element. 1672 ContentSoftwareId Contains information which identifies the 1673 software that generated the content of the 1674 element. Its purpose is to help resolve 1675 interoperability problems that might occur as 1676 a result of incompatibilities between messages 1677 produced by different software. It is a single 1678 text string in the language defined by 1679 "xml:lang". It must contain, as a minimum 1680 problems that might occur as a result of 1682 o the name of the software manufacturer, 1683 o the name of the software, 1684 o the version of the software, and 1685 o the build of the software. 1687 ErrorCode Contains an error code which indicates the 1688 nature of the error in the message in error. 1689 Valid values for the Error Code are given in 1690 the following section. This mnemonic enables 1691 the automatic failure resolution of the IOTP 1692 Application Core which analyzes the error code 1693 value in order to determine the continuation 1694 alternatives. 1696 ErrorDesc Contains a description of the error in the 1697 language defined by xml:lang. The content of 1698 this attribute is defined by the 1699 vendor/developer of the software that 1700 generated the Error Response Element. 1701 It is intended for user display and provides 1702 detailed explanations about the failure and 1703 its (out-of-band) resolution alternatives. 1705 Severity Indicates the severity of the error. Valid 1706 values are: 1708 o Warning. This indicates that although there 1709 is a message in error the IOTP Transaction 1710 can still continue. 1712 o TransientError. This indicates that the 1713 error in the message in error may be 1714 recovered if the message in error that is 1715 referred to by the "Names" attribute is 1716 resent. 1718 o HardError. This indicates that there is an 1719 unrecoverable error in the message in error 1720 and the IOTP Transaction must stop. 1722 MinRetrySecs This attribute should be present if "Severity" 1723 is set to "TransientError". It is the minimum 1724 number of whole seconds which the IOTP aware 1725 application which received the message 1726 reporting the error should wait before re- 1727 sending the message in error identified by the 1728 "ErrorLocation" attribute. 1730 If Severity is not set to 1731 "TransientError" then the value of this 1732 attribute is ignored. 1734 SwVendorErrorRef This attribute is a reference whose value is 1735 set by the vendor/developer of the software 1736 that generated the Error Element. It should 1737 contain data that enables the vendor to 1738 identify the precise location in their 1739 software and the set of circumstances that 1740 caused the software to generate a message 1741 reporting the error. 1743 Content: 1745 ErrorLocation This identifies, where possible, the 1746 element and attribute in the message 1747 in error that caused the Error 1748 Element to be generated. If the 1749 "Severity" of the error is not 1750 "TransientError", more that one 1751 "ErrorLocation" may be specified as 1752 appropriate depending on the nature 1753 of the error and at the discretion of 1754 the vendor/developer of the IOTP 1755 Payment Bridge. 1757 Its definition coincides with the 1758 IOTP specification whereby the 1759 attributes "IotpMsgRef", "BlkRef" and 1760 "CompRef" are left blank, 1761 intentionally. 1763 PaySchemePackagedContent cf. Table 5 1765 3.1 Error Codes 1767 The following table lists the valid values for the ErrorCode 1768 attribute of the Error Response Element. The first sentence of the 1769 error description contains the default text that can be used to 1770 describe the error when displayed or otherwise reported. Individual 1771 implementations may translate this into alternative languages at 1772 their discretion. However, not every error code may apply to every 1773 API call. An Error Code must not be more than 14 characters long. 1775 The Error Codes have been taken from the IOTP Specification and 1776 extended by some additional codes which are highlighted by a 1777 preceding asterisk. 1779 Generally, if the corrupt values have been user supplied, the IOTP 1780 Application Core might prompt for their correction. If the renewal 1781 fails or if the IOTP Application Core skips any renewals and some 1782 notification has to be send to the counter-party, the error code is 1783 encapsulated within an IOTP Error Block. 1785 However, the IOTP server application reports business errors - 1786 visible at the IOTP layer - in the Status Component of the respective 1787 Response Block. 1789 The IOTP Application Core may add the attributes (and values) within 1790 the ErrorLocation elements that are omitted by the IOTP Payment 1791 Bridge. 1793 The following table mentions any modification from this general 1794 processing for particular error values. Furthermore, it contains 1795 hints for developers of IOTP Application Core software components 1796 about the processing of error codes. Conversely, developers of IOTP 1797 Payment Bridges get impressions about the expected behavior of the 1798 IOTP Application Core. 1800 The IOTP Payment API assumes that the IOTP Application Core 1801 implements the dialog boxes needed for error resolution. But it does 1802 not assume, that the IOTP Payment Bridge actually relies on them. 1803 Instead, the IOTP Payment Bridge may try resolution on its own, may 1804 implement specific dialog boxes, and may signal only final failures. 1806 Note: This abstract document assumes that the API parameters are 1807 exchanged XML encoded. Therefore, several error values might 1808 disappear in lower level language specific derivations. 1810 Error Value Error Description 1811 ----------- ----------------- 1813 Reserved Reserved. This error is reserved by the 1814 vendor/developer of the software. Contact 1815 the vendor/developer of the software for 1816 more information (see the SoftwareId 1817 attribute of the Message Id element in the 1818 Transaction Reference Block [IOTP]). 1820 XmlNotWellFrmd XML not well formed. The XML document is not 1821 well formed. See [XML] for the meaning of 1822 "well formed". 1824 XmlNotValid XML not valid. The XML document is well 1825 formed but the document is not valid. See 1826 [XML] for the meaning of "valid". 1827 Specifically: 1829 o the XML document does not comply with the 1830 constraints defined in the IOTP document 1831 type declaration, and 1832 o the XML document does not comply with the 1833 constraints defined in the document type 1834 declaration of any additional [XML-NS] 1835 that are declared. 1837 The Names attribute might refer some 1838 attributes and elements of the input 1839 parameter list. 1841 (*)ElNotValid Element not valid. Invalid element in terms 1842 of prescribed syntactical characteristics. 1844 The ElementRef attributes of ErrorLocation 1845 elements might refer to the corresponding 1846 elements (if they have ID attributes). 1848 The IOTP Application Core has to replace the 1849 error code with "XmlNotValid" before 1850 transmission to the counterparty. 1852 ElUnexpected Unexpected element. Although the XML 1853 document is well formed and valid, an 1854 element is present that is not expected in 1855 the particular context according to the 1856 rules and constraints contained in this 1857 specification. 1859 The ElementRef attributes of ErrorLocation 1860 elements might refer to the corresponding 1861 elements (if they have ID attributes). 1863 ElNotSupp Element not supported. Although the document 1864 is well formed and valid, an element is 1865 present that 1867 o is consistent with the rules and 1868 constraints contained in this 1869 specification, but 1870 o is not supported by the IOTP Aware 1871 Application which is processing the IOTP 1872 Message. 1874 The ElementRef attributes of ErrorLocation 1875 elements might refer to the corresponding 1876 elements (if they have ID attributes). 1878 ElMissing Element missing. Although the document is 1879 well formed and valid, an element is missing 1880 that should have been present if the rules 1881 and constraints contained in this 1882 specification are followed. 1884 The ElementRef attributes of ErrorLocation 1885 elements might refer to the corresponding 1886 elements (if they have ID attributes). 1888 ElContIllegal Element content illegal. Although the 1889 document is well formed and valid, the 1890 element contains values which do not conform 1891 the rules and constraints contained in this 1892 specification. 1894 The ElementRef attributes of ErrorLocation 1895 elements might refer to the corresponding 1896 element (if they have ID attributes). 1898 The IOTP Application Core has to replace the 1899 Error Code with "ElNotSupp" before 1900 transmission to the counter party, if the 1901 ErrorLocation elements refer to non- 1902 PackagedContent element. 1904 EncapProtErr Encapsulated protocol error. Although the 1905 document is well formed and valid, the 1906 Packaged Content of an element contains data 1907 from an encapsulated protocol which contains 1908 errors. 1910 The ElementRef attributes of ErrorLocation 1911 elements might refer to the corresponding 1912 element (if they have ID attributes). 1914 AttUnexpected Unexpected attribute. Although the XML 1915 document is well formed and valid, the 1916 presence of the attribute is not expected in 1917 the particular context according to the 1918 rules and constraints contained in this 1919 specification. 1921 The AttName attributes of ErrorLocation 1922 elements might refer to the corresponding 1923 attribute tags. 1925 (*)AttNotValid Attribute not valid. Invalid attribute value 1926 in terms of prescribed syntactical 1927 characteristics. 1929 The AttName attributes of ErrorLocation 1930 elements might refer to the corresponding 1931 attribute tags. 1933 The IOTP Application Core has to replace the 1934 error code with "XmlNotValid" before 1935 transmission to the counter party. 1937 AttNotSupp Attribute not supported. Although the XML 1938 document is well formed and valid, and the 1939 presence of the attribute in an element is 1940 consistent with the rules and constraints 1941 contained in this specification, it is not 1942 supported by the IOTP Aware Application 1943 which is processing the IOTP Message. 1945 AttMissing Attribute missing. Although the document is 1946 well formed and valid, an attribute is 1947 missing that should have been present if the 1948 rules and constraints contained in this 1949 specification are followed. 1951 The AttName attributes of ErrorLocation 1952 elements might refer to the corresponding 1953 attribute tags. 1955 If the attribute is required by the IOTP 1956 Document Type Declaration (#REQUIRED) the 1957 hints for non-valid attributes should be 1958 adopted, otherwise these for illegal 1959 attribute values. 1961 AttValIllegal Attribute value illegal. The attribute 1962 contains a value which does not conform to 1963 the rules and constraints contained in this 1964 specification. 1966 The AttName attributes of ErrorLocation 1967 elements might refer to the corresponding 1968 attribute tags - valid values are: 1970 BrandId: illegal/unknown Brand Identifier - 1971 If the brand is not recognized/known by any 1972 IOTP Payment Bridge, the IOTP Application 1973 Core may offer the registration of a new 1974 Payment Instrument. 1976 PaymentInstrumentId: illegal/unknown 1977 Payment Instrument Identifier - This 1978 indicates a serious communication problem if 1979 the attribute value has been reported by the 1980 same "wallet" on a previous inquiry 1981 requests. The IOTP Application Core has to 1982 replace the error code with 1983 "UnknownError" before transmission to the 1984 counter party. 1986 WalletId: illegal/unknown Wallet Identifier 1987 - It is assumed that the wallet identifier 1988 is checked before the pass phrase. On 1989 invalid wallet identifiers, the IOTP 1990 Application Core may open the dialog in 1991 order to request the correct wallet 1992 identifier. In addition, any pass phrase may 1993 be supplied by the user. The dialog should 1994 indicate the respective payment brand(s). 1995 The IOTP Application Core has to replace the 1996 error code with "UnknownError" before 1997 transmission to the counter party. 1999 Passphrase: illegal/unknown Pass Phrase - 2000 The IOTP Application Core may open the 2001 dialog in order to request the correct pass 2002 phrase. If the pass phrase is wallet 2003 identifier specific the dialog should 2004 display the wallet identifier. The IOTP 2005 Application Core has to replace the error 2006 code with "TransportError" before 2007 transmission to the counter party. 2009 Action: illegal / unknown / unsupported 2010 Action 2012 PropertyTypeList: lists contains illegal / 2013 unknown / unsupported Property Types - The 2014 IOTP Application Core tries only the local 2015 resolution but does never transmit any IOTP 2016 Error Block to the counter party. 2018 CurrCode: illegal/unknown/unsupported 2019 Currency Code 2021 CurrCodeType: illegal/unknown/unsupported 2022 Currency Code Type 2024 Amount: illegal/unknown/unsupported Payment 2025 Amount 2027 PayDirection: illegal/unknown/unsupported 2028 Payment Direction 2030 ProtocolId: illegal/unknown/unsupported 2031 Protocol Identifier 2033 OkFrom: illegal/unknown/unsupported OkFrom 2034 Timestamp 2036 OkTo: illegal/unknown/unsupported OkTo 2037 Timestamp 2039 ConsumerPayId: illegal/unknown Consumer 2040 Payment Identifier 2041 PaymentHandlerPayId: illegal/unknown Payment 2042 Handler Payment Identifier 2044 PayId: illegal/unknown Payment Identifier 2046 AttValNotRecog Attribute Value Not Recognized. The 2047 attribute contains a value which the IOTP 2048 Aware Application generating the message 2049 reporting the error could not recognize. 2051 The AttName attributes of ErrorLocation 2052 elements might refer to the corresponding 2053 attribute tags 2055 MsgTooLarge Message too large. The message is too large 2056 to be processed by the IOTP Payment Bridge 2057 (or IOTP Application Core). 2059 ElTooLarge Element too large. The element is too large 2060 to be processed by the IOTP Payment Bridge 2061 (or IOTP Application Core). 2063 The ElementRef attributes of ErrorLocation 2064 elements might might refer to the 2065 corresponding elements. 2067 ValueTooSmall Value too small or early. The value of all 2068 or part of an element content or an 2069 attribute, although valid, is too small. 2071 The ErrorLocation elements might refer to 2072 the corresponding attribute tags or 2073 elements. 2075 ValueTooLarge Value too large or in the future. The value 2076 of all or part of an element content or an 2077 attribute, although valid, is too large. 2079 The ErrorLocation elements might refer to 2080 the corresponding attribute tags or 2081 elements. 2083 ElInconsistent Element Inconsistent. Although the document 2084 is well formed and valid, according to the 2085 rules and constraints contained in this 2086 specification: 2088 o the content of an element is inconsistent 2089 with the content of other elements or 2090 their attributes, or 2091 o the value of an attribute is inconsistent 2092 with the value of one or more other 2093 attributes. 2095 The Error Description may contain further 2096 explanations. 2098 The ErrorLocation elements might refer to 2099 the corresponding attribute tags or elements 2100 that are inconsistent. 2102 TransportError Transport Error. This error code is used to 2103 indicate that there is a problem with the 2104 transport mechanism that is preventing the 2105 message from being received. It is typically 2106 associated with a "Transient Error". 2108 The connection to some periphery or the 2109 counter party could not be established, 2110 is erroneous, or has been lost. 2112 The Error Description may contain further 2113 narrative explanations, e.g., "chip card 2114 does not respond", "remote account manager 2115 unreachable", "Internet connection to xyz 2116 lost", "no Internet connection available", 2117 "no modem connected", or "serial port to 2118 modem used by another application". This 2119 text should be shown to the end user. If 2120 timeout has occurred at the Consumer this 2121 text should be shown and the Consumer may 2122 decide how to proceed - alternatives are 2123 retry, payment transaction suspension, and 2124 cancellation. 2126 MsgBeingProc Message Being Processed. This error code is 2127 only used with a Severity of Transient 2128 Error. It indicates that the previous 2129 message, which may be an exchange message or 2130 a request message, is being processed and, 2131 if no response is received by the time 2132 indicated by the "MinRetrySecs" attribute, 2133 then the original message should be resent. 2135 SystemBusy System Busy. This error code is only used 2136 with a Severity of Transient Error. It 2137 indicates that the IOTP Payment Bridge or 2138 Existing Payment Software that received the 2139 API request is currently too busy to handle 2140 it. If no response is received by the time 2141 indicated by the "MinRetrySecs" attribute, 2142 then the original message should be resent. 2144 The Error Description may provide further 2145 explanations, e.g., "wallet / chip card 2146 reader is unavailable or locked by another 2147 payment transaction", "payment gateway is 2148 overloaded", "unknown chip card reader", or 2149 "unrecognized chip card inserted, change 2150 chip card". 2152 The Consumer's IOTP Application Core may 2153 display the error description and ask the 2154 Consumer about the continuation - 2155 alternatives are retry, payment transaction 2156 suspension, and cancellation. 2158 UnknownError Unknown Error. Indicates that the 2159 transaction cannot complete for some reason 2160 that is not covered explicitly by any of the 2161 other errors. The Error description 2162 attribute should be used to indicate the 2163 nature of the problem. 2165 The ErrorLocation elements might refer to 2166 the corresponding attribute tags or elements 2167 that are inconsistent. 2169 (*)SyntaxError Syntax Error. An (unknown) syntax error has 2170 occurred. 2172 The ErrorLocation elements might refer to 2173 the corresponding attribute tags or elements 2174 that are inconsistent. 2176 The IOTP Application Core has to replace the 2177 error code with "XmlNotValid" or 2178 "UnknownError" before transmission to the 2179 counter party. 2181 (*)ReqRefused Request refused. The API request is 2182 (currently) refused by the IOTP Payment 2183 Bridge. The error description may provide 2184 further explanations, e.g., "wallet / chip 2185 card reader is unavailable or locked by 2186 another payment transaction", "payment 2187 gateway is overloaded", "unknown chip card 2188 reader", or "unrecognized chip card 2189 inserted, change chip card". 2191 The Consumer's IOTP Application Core may 2192 display the error description and ask the 2193 Consumer about the continuation - 2194 alternatives are retry, payment transaction 2195 suspension, and cancellation. Denials due to 2196 invalid Process States should be signaled by 2197 "BusinessError". Typically, this kind of 2198 error is not passed to the counter party's 2199 IOTP Application Core. Otherwise, it maps to 2200 "TransportError" or "UnknownError". 2202 (*)ReqNotSupp Request not supported. The API 2203 function(ality) has not been implemented in 2204 the IOTP Payment Bridge. Typically, this 2205 kind of error is not passed to the 2206 counter party's IOTP Application Core. 2207 Otherwise, it maps to "TransportError" or 2208 "UnknownError". 2210 (*)BusError Business Error. The API request has been 2211 rejected because some payment transaction 2212 has an illegal payment status. 2213 Particularly, this error code is used to 2214 signal any raise of payment business layered 2215 failures. 2217 The ErrorLocation elements may refer to 2218 payment transactions using the party's 2219 Payment Identifier - it defaults to the 2220 current transaction or might contain the 2221 current payment transaction party's Payment 2222 Identifier - identified by the ElementRef 2223 attribute while the AttName attribute is 2224 fixed with "PayId". 2226 The IOTP Application Core must inquire the 2227 IOTP Payment Bridge about the actual Process 2228 State which actually encodes the business 2229 error ("Inquire Process State"). 2230 This error code must not be 2231 passed to the counter party's IOTP 2232 Application Core. 2234 Table 2: Common Error Codes 2236 The IOTP Payment Bridge may also use the error description in order 2237 to notify the Consumer about further necessary steps for failure 2238 resolution, e.g., "sorry, your payment transaction failed. 2239 Unfortunately, you have been charged, please contact your issuer." 2241 3.2 Attributes and Elements 2243 The following table explains the XML attributes in alphabetical order 2244 - any parenthesized number after the attribute tag is a recommended 2245 maximal length of the attribute value in characters: 2247 Attribute Description 2248 --------- ----------- 2250 Amount (11) Indicates the payment amount to be paid in 2251 AmountFrom(11) whole and fractional units of the currency. 2252 AmountTo (11) For example $245.35 would be expressed 2253 "245.35". Note that values smaller than the 2254 smallest denomination are allowed. For 2255 example one tenth of a cent would be 2256 "0.001". 2258 AuthenticationId An identifier specified by the 2259 authenticator which, if returned by the 2260 organization that receives the 2261 authentication request, will enable the 2262 authenticator to identify which 2263 authentication is being referred to. 2265 BrandId (128) This contains a unique identifier for the 2266 brand (or promotional brand). It is used to 2267 match against a list of Payment Instruments 2268 which the Consumer holds to determine 2269 whether or not the Consumer can pay with the 2270 Brand. 2272 Values of BrandId are managed under 2273 procedure being described in the IOTP 2274 protocol specification. 2276 BrandLogoNetLocn The net location which can be used to 2277 download the logo for the organization (cf. 2278 IOTP Specification). 2280 The content of this attribute must conform 2281 to [URL]. 2283 BrandName This contains the name of the brand, for 2284 example "MasterCard Credit". This is the 2285 description of the Brand which is displayed 2286 to the consumer in the Consumer's language 2287 defined by "xml:lang". For example it might 2288 be "American Airlines Advantage Visa". Note 2289 that this attribute is not used for matching 2290 against the payment instruments held by the 2291 Consumer. 2293 BrandNarrative This optional attribute is 2294 used by the Merchant to indicate some 2295 special conditions or benefit which would 2296 apply if the Consumer selected that brand. 2297 For example "5% discount", "free shipping 2298 and handling", "free breakage insurance for 2299 1 year", "double air miles apply", etc. 2301 CallBackFunction A function which is called whenever there is 2302 a change of Process State or payment 2303 progress, e.g. for display updates. However, 2304 the IOTP Payment Bridge may use its own 2305 mechanisms and dialog boxes. 2307 CallBackLanguageLis A list of language codes which contain, in 2308 t order of preference, the languages in which 2309 the text passed to the Call Back function 2310 will be encoded. 2312 CompletionCode (14) Indicates how the process completed. 2313 It is required if ProcessState is set to 2314 "Failed" otherwise it is ignored. Valid 2315 values as well as recovery options are given 2316 in the IOTP specification. 2318 The IOTP Payment Bridge may also use the 2319 Status Description to notify the Consumer 2320 about further necessary steps in order to 2321 resolve some kind of business failures, 2322 e.g., 2324 o "sorry, your payment transaction failed. 2325 Unfortunately, you have been charged, 2326 please contact your issuer." 2327 o "insufficient capacity left (on your stored 2328 value card) for refund", 2329 o "payment failed/chip card error/internal 2330 error, please contact your payment 2331 instrument's issuer" 2333 ConsumerDesc A narrative description of the Consumer. 2335 ConsumerPayId (14) An unique identifier specified by the 2336 Consumer that, if returned by the Payment 2337 Handler in another Payment Scheme Component 2338 or by other means, enables the Consumer to 2339 identify which payment is being referred to. 2341 This unique identifier is generated by the 2342 IOTP Application Core and submitted to the 2343 IOTP Payment Bridge on every API call. It 2344 may equal the Payment Handler Payment 2345 Identifiers but need not necessarily be so. 2347 The uniqueness extends to multiple payment 2348 instruments, payment brands, payment 2349 protocols, wallet identifiers, and even 2350 multiple IOTP Payment Bridges. 2352 ContStatus During payment progress, this status value 2353 indicates whether the payment needs to be 2354 continued with further IOTP Payment Scheme 2355 Component exchanges with the remote party. 2356 "End" indicates that the reported payment 2357 scheme data is the last data to be exchanged 2358 with the counter party. 2360 ContentSoftwareId This contains information that identifies 2361 the software that generated the content of 2362 the element. Its purpose is to help resolve 2363 interoperability problems that might occur 2364 as a result of incompatibilities between 2365 messages produced by different software. It 2366 is a single text string in the language 2367 defined by xml:lang. It must contain, as a 2368 minimum: 2370 o the name of the software manufacturer, 2371 o the name of the software, 2372 o the version of the software, and 2373 o the build of the software. 2375 CurrCodeType (14) Indicates the domain of the CurrCode. This 2376 attribute is included so that the currency 2377 code may support nonstandard currencies 2378 such as frequent flyer point, trading 2379 stamps, etc. Its values may be 2381 o ISO-4217-A, the default, indicates the 2382 currency code is the three-letter 2383 alphabetic code that conform to ISO 4217 2385 o IOTP indicates that the values of 2386 CurrCode are managed under the procedure 2387 described in [IOTP]. 2389 CurrCode (14) A code which identifies the currency to be 2390 used in the payment. The domain of valid 2391 currency codes is defined by "CurrCodeType" 2393 MerchantPayId (14) An private identifier specified by the 2394 Merchant which will enable the Merchant to 2395 identify which payment is being referred to. 2396 It is a pure private item and is never sent 2397 to any other party. It is provided by the 2398 IOTP Payment Bridge on payment preparation 2399 during brand compilation. 2401 Cf. To "ConsumerPayId" for note about 2402 uniqueness. 2404 MerchantOrgId (64) A local item that might refer to some 2405 specific shop in a multi shop environment. 2406 This item is optional and might enrich the 2407 Wallet Identifier which itself can be used 2408 for the same purpose. 2410 Name Distinguishes between multiple occurrences 2411 of Packaged Content Elements at the same 2412 point in IOTP. For example: 2414 2415 2416 snroasdfnas934k 2417 2418 2419 dvdsjnl5poidsdsflkjnw45 2420 2421 2423 The "Name" attribute may be omitted, for 2424 example if there is only one Packaged 2425 Content element. 2427 OkFrom (30) The date and time in UTC Format range 2428 OkTo (30) indicated by the merchant in which the 2429 Payment Handler may accept the payment. 2431 Passphrase (32) Payment wallets may use pass phrase 2432 protection for transaction data and payment 2433 instruments' data. However, it is assumed 2434 that there exists a public and customizable 2435 payment instrument identifier such that 2436 these identifiers together with their 2437 relationship to payment brands, payment 2438 protocols, payment directions, and currency 2439 amounts can be queried by the IOTP 2440 application without any pass phrase 2441 knowledge. 2443 PayDirection Indicates the direction in which the 2444 payment for which a Brand is being selected 2445 is to be made. Its values may be: 2447 o Debit: The sender of the Payment Request 2448 Block (e.g. the Consumer) to which this 2449 Brand List relates will make the payment 2450 to the Payment Handler, or 2451 o Credit: The sender of the Payment Request 2452 Block to which this Brand List relates 2453 will receive a payment from the Payment 2454 Handler. 2456 PayId (14) This attribute is introduced for API 2457 simplification: 2459 o The Consumer has to identify PayId and 2460 ConsumerPayId. 2462 o The Merchant has to identify PayId and 2463 MerchantPayId. 2465 o The Payment Handler has to identify PayId 2466 and Payment Handler Pay Id. 2468 PayInstId This contains the unique identifier used 2469 internally by the IOTP Payment 2470 Bridge/Existing Payment Software. 2472 PayInstName This contains the user-defined name of the 2473 payment instrument. There exist no 2474 (technical) constraints like uniqueness. The 2475 "xml:lang" attribute denotes the language 2476 encoding of its value. 2478 PaymentHandlerDesc A narrative description of the Payment 2479 Handler. 2481 PaymentHandlerPayId An unique identifier specified by the 2482 (14) Payment Handler that, if returned by the 2483 Consumer in another Payment Scheme Component 2484 or by other means, enables the Payment 2485 Handler to identify which payment is being 2486 referred to. It is required whenever it is 2487 known. 2489 Cf. To "ConsumerPayId" for note about 2490 uniqueness. 2492 PaymentInstrumentId An identifier for a specific payment 2493 (32) instrument, e.g. "credit card", "Mondex card 2494 for English Pounds". This identifier is 2495 fully customizable. It is assumed, that it 2496 does not contain confidential information or 2497 even an indication of it. The payment 2498 instrument identifier is unique within each 2499 payment brand. It is displayed to the 2500 Consumer during brand selection. 2502 PayReceiptNameRefs Optionally contains element references to 2503 (32) other elements (containing payment scheme 2504 specific data) that together make up the 2505 receipt. Note that each payment scheme 2506 defines in its supplement the elements that 2507 must be referenced 2509 The IOTP Application Core should save all 2510 the components referenced so that the 2511 payment receipt can be reconstructed when 2512 required. 2514 PayReqNetLocn The Net Location indicating where an 2515 unsecured Payment Request message should be 2516 sent if this protocol choice is used. 2518 The content of this attribute must conform 2519 to [URL] and depends on the Transport 2520 Mechanism. 2522 PercentComplete (3) A number between 0 and 100 which indicates 2523 the progress of the payment transaction. The 2524 values range between 0 and 99 for pending 2525 and suspended transactions. 2527 ProcessState Contains a Process State Code that 2528 indicates the current state of the process 2529 being carried out. Valid values are: 2531 o NotYetStarted. The Payment Request Block 2532 has been received but processing of the 2533 Payment Request has not yet started 2535 o InProgress. The payment transaction is 2536 pending. The processing of the (Payment) 2537 Request Block has started but it is not 2538 yet complete. 2540 o (*)Suspended: The payment transaction has 2541 been suspended and can be resumed. 2543 This process state is mapped to 2544 "InProgress", if it is passed to the 2545 counter party's IOTP Application Core. 2547 o CompletedOk. The processing of the (Payment) 2548 Request Block and any following Payment 2549 Exchange Blocks has completed successfully. 2551 o Failed. The payment processing has finally 2552 failed for a Business Error. 2554 o ProcessError. This value is only used 2555 when the Status Component is being used in 2556 connection with an Inquiry Request Trading 2557 Block. It indicates there was a Technical 2558 Error in the Request Block which is being 2559 processed or some internal processing 2560 error. Each party's IOTP Payment Bridge 2561 uses this value in order to notify the 2562 IOTP Application Core about the presence 2563 of technical errors. 2565 PropertyType (14) The property type defines codes used for 2566 interrogation of specific properties about a 2567 payment instrument. They are unique for each 2568 payment brand. The predefined property "all" 2569 is used on general inquiries. However, these 2570 property types are not used during normal 2571 payment processing. E.g., they may apply to 2572 payment brand specific transactions or out- 2573 of-band failure resolution. 2575 PropertyDesc The property description carries the 2576 respective human readable property (value)'s 2577 description. 2579 PropertyValue The actual property value intends automatic 2580 post processing. 2582 ProtocolBrandId (64)This is an identifier to be used with a 2583 particular payment protocol. For example, 2584 SET and EMV have their own well defined, yet 2585 different, values for the Brand identifier 2586 to be used with each protocol. The valid values 2587 of this attribute are defined in the 2588 supplement for the payment protocol 2589 identified by "ProtocolId" that describes 2590 how the payment protocol works with IOTP. 2591 Identifier maps to at most one Protocol 2592 Brand Identifier. 2594 ProtocolId (64) An identifier for a specific payment 2595 protocol and version, e.g. "SETv1.0", 2596 "ecash". Valid values are defined by 2597 supplements to the IOTP specification and 2598 they are unique within each payment brand. 2600 ProtocolIds A sequence of Protocol Identifiers 2602 ProtocolName A narrative description of the payment 2603 protocol and its version in the language 2604 identified by "xml:lang". For example 2605 "Secure Electronic Transaction Version 1.0". 2606 Its purpose is to help provide information 2607 on the payment protocol being used if 2608 problems arise. 2610 SecPayReqNetLocn The Net Location indicating where a secured 2611 Payment Request message should be sent if 2612 this protocol choice is used. 2614 A secured payment involves the use of a 2615 secure channel such as [TLS] in order 2616 to communicate with the Payment Handler. 2618 The content of this attribute must conform 2619 to [URL]. 2621 ReceiverOrgId The Organization Identification which 2622 receives the payment bridge processing 2623 Trading Role Data PackagedContent. 2625 StatusDesc (256) An optional textual description of the 2626 current process state in the language 2627 identified by "xml:lang" that should be 2628 displayed to the Consumer. The usage of this 2629 attribute is defined in the payment 2630 supplement for the payment method being 2631 used. Particularly, it provides hints for 2632 out-of-band failure resolution. Its length 2633 is limited to 256 characters. 2635 StyleSheetNetLocn This contains the net location to a style 2636 sheet with visualisation rules for XML 2637 encoded data. 2639 TimeStamp (30) The date and time in UTC Format when the 2640 payment transaction has been started. 2642 WalletId (32) Many existing payment wallet software are 2643 multiple wallet capable. The Wallet 2644 Identifier selects the actual wallet. It is 2645 assumed, that the wallet identifier is a 2646 public item, that might be stored by the 2647 IOTP Application Core. 2649 xml:lang Defines the language used by the Process 2650 State Description attribute (cf. IOTP 2651 Specification) 2653 Table 3: Attributes 2655 The following table explains the XML elements in alphabetical 2656 order: 2658 Element Description 2659 ------- ----------- 2661 Algorithm This contains information which describes 2662 an Algorithm that may be used to generate 2663 the Authentication response. 2665 The algorithm that may be used is 2666 identified by the Name attribute (cf. IOTP 2667 Specification). 2669 AuthReqPackagedContent The Authentication Request Packaged 2670 Content originates from a Authentication 2671 (Data/Response) Component's content 2672 whereby the outermost element tags are 2673 prefixed with "AuthReq". Its declaration 2674 coincides with the Packaged Content's 2675 declaration (cf. IOTP Specification). It 2676 encapsulates the authentication challenge 2677 value. The content of this information is 2678 defined in the supplement for a payment 2679 protocol. 2681 AuthResPackagedContent The Authentication Response Packaged 2682 Content originates from a Authentication 2683 Response Component's content whereby the 2684 outermost element tags are prefixed with 2685 "AuthRes". 2687 Its declaration coincides with the 2688 Packaged Content's declaration (cf. IOTP 2689 Specification). It encapsulates the 2690 authentication response value. The 2691 content of this information is defined in 2692 the supplement for a payment protocol. 2694 BrandPackagedContent Container for further payment brand 2695 description. Its content originates from 2696 a Brand Element content whose outermost 2697 element tags are prefixed with "Brand". 2698 Its declaration coincides with the 2699 Packaged Content's declaration (cf. IOTP 2700 Specification). 2702 BrandSelBrandInfoPackagedContent 2703 This contains any additional data that 2704 may be required by a particular payment 2705 brand. It forms the content of the Brand 2706 Selection Brand Info Element. 2708 BrandSelProtocolAmountInfoPackagedContent 2709 This contains any additional data that 2710 may be required by a particular payment 2711 brand in the format. It forms the content 2712 of the Brand Selection Protocol Amount 2713 Info Element. 2715 BrandSelCurrencyAmountInfoPackagedContent 2716 This contains any additional data that is 2717 payment brand and currency specific in 2718 the format. It forms the content of the 2719 Brand Selection Currency Amount Info 2720 Element. 2722 MerchantData Any merchant related data that might be 2723 used by the IOTP Payment Bridge for 2724 different purposes, e.g., it might 2725 contain access keys to some mall keys. 2726 Its declaration coincides with the 2727 Packaged Content's declaration (cf. IOTP 2728 Specification). 2730 PackagedContent Generic Container for non-IOTP data (cf. 2731 IOTP Specification). 2733 PayProtocolPackagedContent 2734 The Pay Protocol Packaged Content 2735 originates from a Pay Protocol 2736 Element's content whereby the outermost 2737 element tags are prefixed with 2738 "PayProtocol". It contains information 2739 about the protocol which is used by 2740 the payment protocol. The content of 2741 this information is defined in the 2742 supplement for a payment protocol.Its 2743 declaration coincides with the Packaged 2744 Content's declaration (cf. IOTP 2745 Specification). 2747 PaySchemePackagedContent 2748 The PayScheme Packaged Content originates 2749 from a Payment Scheme Component's content 2750 whereby the outermost element tags are 2751 prefixed with "PayScheme". Its 2752 declaration coincides with the Packaged 2753 Content's declaration (cf. IOTP 2754 Specification). It carries the payment 2755 specific data. The content of this 2756 information is defined in the supplement 2757 for a payment protocol. 2759 ProtocolAmountPackagedContent 2760 The Protocol Amount Packaged Content 2761 originates from a Protocol Amount 2762 Element's content whereby the outermost 2763 element tags are prefixed with "Amount". 2764 Its declaration coincides with the 2765 Packaged Content's declaration (cf. IOTP 2766 Specification). It contains information 2767 about the protocol which is used by the 2768 payment protocol. The content of this 2769 information is defined in the supplement 2770 for a payment protocol. 2772 ProtocolBrandPackagedContent 2773 The Protocol Brand Packaged Content 2774 originates from a Protocol Brand 2775 Element's content whereby the outermost 2776 element tags are prefixed with 2777 "ProtocolBrand". Its declaration 2778 coincides with the Packaged Content's 2779 declaration (cf. IOTP Specification). It 2780 contains information about the brand 2781 which might be used by the payment 2782 protocol. The content of this information 2783 is defined in the supplement for a 2784 payment protocol. 2786 ResponsePackagedContent 2787 Container for authentication response 2788 data. Its content originates from a 2789 Authentication Response Component's 2790 Packaged Content whose outermost element 2791 tags are prefixed with "Response". Its 2792 declaration coincides with the Packaged 2793 Content's declaration (cf. IOTP 2794 Specification). 2796 TradingRoleDataPackagedContent 2797 The TradingRoleData Packaged Content 2798 originates from a TradingRoleData 2799 Component's content whereby the outermost 2800 element tags are prefixed with 2801 "TradingRoleData". Its declaration 2802 coincides with the Packaged Content's 2803 declaration (cf. IOTP Specification). It 2804 contains information from Merchant to 2805 Payment Handler via Consumer about the 2806 protocol which is used by the payment. 2807 The content of this information is 2808 defined in the supplement for a payment 2809 protocol. The Name attribute in this 2810 packaged contents must include prefix as 2811 "Payment:" to indicate that the payment 2812 bridge processes this, for example 2813 "Payment:SET-OD" 2815 The element's declaration coincides with 2816 the Packaged Content's declaration (cf. 2817 IOTP Specification). 2819 Table 4: Elements 2821 XML definition: 2823 2824 2826 2827 2828 2830 2832 2834 2835 2836 2837 2839 3.3 Process States 2841 The IOTP Payment API supports six different attribute values that 2842 encode the transaction status from the IOTP's point of view, i.e. the 2843 appropriate point of view at the interface between the IOTP 2844 Application Core and IOTP Payment Bridge. This point of view does not 2845 completely mimic the more detailed view on the actual payment by the 2846 actual Existing Payment Software or IOTP Payment Bridge. 2848 The following three tables distinguish between the Merchant's, 2849 Consumer's, and Payment Handlers' environment. They extend the 2850 aforementioned explanations towards the mapping between IOTP process 2851 states and the internal payment scheme related states of the Existing 2852 Payment Software/IOTP Payment Bridge. 2854 3.3.1 Merchant 2856 The Merchant's point of view of payment is limited to the local 2857 payment initiation being interlaced with order processing because 2858 IOTP assigns the actual payment processing to the Payment Handler. 2860 ProcessState Description 2861 ------------ ----------- 2863 NotYetStarted The Payment Transaction exists within the 2864 IOTP Application Core, i.e., the 2865 Merchant's shop has already signaled to 2866 the IOTP Application Core that an IOTP 2867 transaction has been initiated by the 2868 Consumer. 2870 However, neither any API call has been 2871 issued to the IOTP Payment Bridge nor has 2872 the IOTP Order Request has been created. 2874 InProgress The IOTP Application changes the process 2875 state to this value when it issues the 2876 first API call to the Payment Bridge 2877 during Brand List compilation. 2879 This value indicates that the Payment 2880 Bridge might have some knowledge about 2881 the expected payment or might have 2882 performed some preparatory tasks (even 2883 with the Payment Handler out-of-band to 2884 IOTP). 2886 However, this value does not indicate 2887 that any IOTP Order Request has been 2888 created and transmitted to the Consumer. 2890 Suspended The IOTP transaction has been suspended 2891 before the order request block has been 2892 transmitted to the Consumer. 2894 Implicitly, the payment is also deferred. 2896 CompletedOk The IOTP Order Request has been 2897 successfully created and transmitted to 2898 the Consumer. Actually, this process 2899 state indicates only that the order 2900 processing has been finished. 2902 But it contains no indication about the 2903 status of the actual payment, which is 2904 accepted by the Payment Handler. 2906 However, successful order processing 2907 signals the IOTP Application Core that a 2908 payment with some specific parameters is 2909 expected within the near future. And this 2910 signal might be used by the Existing 2911 Payment Software for similar purposes. 2912 This attribute might be interpreted as 2913 successful preparation of the payment 2914 system. 2916 Particularly, it is expected that the 2917 Existing Payment Software maps this IOTP 2918 status value to some other internal 2919 value, e.g. "NotYetStarted", that is more 2920 accurate from its point of view. 2922 As IOTP provides no communication channel 2923 between the Merchant and Payment Handler, 2924 any change of payment process state will 2925 be initiated out-of-band to IOTP, e.g. by 2926 electronic statements of account or 2927 payment scheme specific mechanisms. 2929 Failed The IOTP transaction, i.e. order 2930 processing, has failed for some 2931 (business) reason and it is known that no 2932 payment will occur. 2934 This indication might be used to clear 2935 all data about this transaction within 2936 the Existing Payment Bridge (by 2937 "RemovePaymentLog" or 2938 "ChangeProcessState") or to reverse any 2939 preparation (with the Payment Handler 2940 out-of-band to IOTP). 2942 However, the ideal point of view of IOTP 2943 suspects that the actual payment 2944 transaction has been neither started nor 2945 initiated. 2947 ProcessError The IOTP transaction, i.e. order 2948 processing, has failed for some 2949 (technical) reason and it is known that 2950 no payment will occur. 2952 This indication might be used to clear 2953 all data about this transaction within 2954 the Existing Payment Bridge (by 2955 "RemovePaymentLog" or 2956 "ChangeProcessState") or to reverse any 2957 preparation (with the Payment Handler 2958 out-of-band to IOTP). 2960 However, the ideal point of view of IOTP 2961 suspects that the actual payment 2962 transaction has been neither started nor 2963 initiated. 2964 Table 5: Merchant 2966 3.3.2 Consumer 2968 The Consumer's IOTP Application Core restricts its point of view to 2969 the payment transaction. It is assumed that the IOTP Payment Bridge 2970 handles the preceding brand selection process in a stateless manner. 2972 ProcessState Description 2973 ------------ ----------- 2975 NotYetStarted This encodes the initial process state of 2976 any IOTP payment transaction. This value 2977 is set during brand selection but it 2978 normally will not change during the whole brand 2979 selection process. 2981 InProgress With the issuance of the Start Payment 2982 Consumer API call, the IOTP Application 2983 Core changes the process state to this 2984 value. 2986 Suspended The payment transaction has been 2987 suspended. Suspension may occur anywhere 2988 during brand selection (with the 2989 Merchant) or payment processing (with the 2990 Payment Handler). On resumption, the IOTP 2991 Application Core and the IOTP Payment 2992 Bridge have to use other internal data to 2993 decide whether brand selection or actual 2994 payment processing needs to be continued, 2995 i.e., whether the process state needs to 2996 be reset to "NotYetStarted" or 2997 "InProgress". 2999 Note that the Payment API assumes 3000 stateless brand selection by the IOTP 3001 Payment Bridge. Typically, any suspension 3002 during brand selection requires the 3003 repetition of the whole process. Hereby, 3004 the IOTP Application Core might need to 3005 consider any already negotiated 3006 conditions in a brand depended purchase 3007 (brand, protocol). 3009 CompletedOk The successful payment has been 3010 acknowledged by the Payment Handler, i.e. 3011 the successful IOTP Payment Response has 3012 been received. 3014 Implicitly, this implies successful order 3015 processing. 3017 Failed The IOTP transaction, i.e. order or 3018 payment processing, has failed for some 3019 (business) reason. In either case it is 3020 known that the payment will not succeed. 3022 ProcessError The IOTP transaction, i.e. order or 3023 payment processing, has failed for some 3024 (technical) reason. 3026 However, the local process state might be 3027 different from that of Payment Handler. 3029 Table 6: Consumer 3031 3.3.3 Payment Handler 3033 The Payment Handler is responsible for the actual payment processing. 3034 New payment transactions are reported by the Consumer with the 3035 transmission of new IOTP Payment Request Blocks. IOTP Payment 3036 Exchange Block are send by the Consumer for payment transaction 3037 continuation and resumption. 3039 ProcessState Description 3040 ------------ ----------- 3042 NotYetStarted This encodes the initial process state of 3043 any payment transaction. Typically, this 3044 value will last for a short amount of 3045 time. 3047 InProgress The IOTP Application Core changes the 3048 process state changes to "InProgress" 3049 when the Payment Handler starts with the 3050 actual processing of the IOTP Payment 3051 Request Block. 3053 Note that this does not assume that the 3054 "StartPaymentPaymentHandler" API function 3055 has been called. 3057 Suspended The payment transaction has been 3058 suspended. 3060 CompletedOk The payment has been processed, 3061 successfully, i.e. the IOTP Payment 3062 Response Block was created and 3063 transmitted to the Consumer. 3065 Failed The payment transaction, has finally 3066 failed for some (business) reason. 3068 Note that this value encodes the payment 3069 state reported by the IOTP Payment Bridge 3070 on "InquireProcessState". It neither 3071 reflects whether the payment receipt has 3072 been inquired nor whether the IOTP 3073 Payment Response Block has been created 3074 and submitted to the Consumer. 3076 ProcessError The payment transaction, has finally 3077 failed for some (technical) reason. 3079 Note that this value encodes the payment 3080 state reported by the IOTP Payment 3081 Bridge. It does not reflect whether some 3082 IOTP Error Block has been created and 3083 submitted to the Consumer. 3085 Table 7: Consumer 3087 4. Payment API Calls 3089 4.1 Brand Compilation Related API Calls 3091 4.1.1 Find Accepted Payment Brand 3093 This API function determines the payment brands being accepted by the 3094 Payment Handler on behalf of the Merchant. 3096 Input Parameters 3098 o Payment Direction - provided by the IOTP Application Core 3099 o Currency Code and Currency - provided by the IOTP Application 3100 Core 3101 o Payment Amount - provided by the IOTP Application Core 3102 o Merchant Payment Identifier - Merchant's unique private 3103 reference to the payment transaction 3104 o Merchant Organisation Identifier - used for distinction between 3105 multiple merchants that share the some IOTP merchant system 3106 o Wallet Identifier - managed by the IOTP Application Core 3107 o Merchant Data - specific data used by the IOTP Payment Bridge 3108 which is managed in the IOTP Application Core. 3110 XML definition: 3112 3113 3122 Output Parameters 3124 o Payment Brand Identifier - for insertion in the Brand List 3125 Component's Brand Element 3126 o Payment Brand Name and language annotation - for insertion in 3127 the Brand List Component's Brand Element 3128 o Payment Brand Logo Net Location - for insertion in the Brand 3129 List Component's Brand Element 3130 o Payment Brand Narrative Description - for insertion in the 3131 Brand List Component's Brand Element 3132 o (Brand) Packaged Content - further payment brand description 3133 for insertion in the Brand List Component's Brand Element 3135 The Existing Payment Software returns an empty list of brand items, 3136 if it does not support any payment brand/payment protocol combination 3137 for the given payment parameters. 3139 XML definition: 3141 3142 3143 3150 Tables 4 and 5 explain the attributes and elements; Table 3 3151 introduces the Error Codes. 3153 4.1.2 Find Accepted Payment Protocol 3155 This API function determines the instances of payment protocols (and 3156 optionally the payment brands) being accepted by the Payment Handler 3157 on behalf of the Merchant. The function might be called in two 3158 variants: 3160 o With the Brand Identifier set on the input parameter list: The 3161 function responds with the payment protocols that fits to the 3162 submitted brand. 3164 o Without any Brand Identifier - that allows the omission of the 3165 "Find Accepted Payment Brand" API call (cf. Section 4.1.1): This 3166 function responds with both the supported brand identifiers and the 3167 payment protocols being specified by the Brand Elements. 3169 Input Parameters 3171 o Brand Identifier - returned by "Find Accepted Payment Brand" 3172 o Payment Direction 3173 o Currency Code and Currency 3174 o Payment Amount 3175 o Merchant Payment Identifier - Merchant's unique private 3176 reference to the payment transaction 3177 o Merchant Organisation Identifier - used for distinction between 3178 multiple merchants that share the some IOTP merchant system 3179 o Wallet Identifier - managed by the IOTP Application Core 3180 o (Brand) Packaged Content - further payment brand description; 3181 returned by "Find Accepted Payment Brand"; this elements are 3182 only provided iff the Brand Identifier is set 3183 o Merchant Data - specific data used by the IOTP Payment Bridge 3184 which is managed in the IOTP Application Core. 3186 XML definition: 3188 3190 3200 Output Parameters 3202 o Payment Protocol Identifier - for insertion in the Brand List 3203 Component's Pay Protocol Element 3204 o Protocol Brand Identifier - for insertion in the Protocol Brand 3205 Element of the Brand List Component's Brand Element 3206 o Payment Protocol Name and language annotation- for insertion in 3207 the Brand List Component's Pay Protocol Element 3208 o Payment Request Net Location - for insertion in the Brand List 3209 Component's Pay Protocol Element 3210 o Secured Payment Request Net Location - for insertion in the 3211 Brand List Component's Pay Protocol Element 3212 o Brand Item List (cf. Section 4.1.1) - there must be at least 3213 one element if no brand identifier has been provided on the 3214 input parameter list. 3215 o (Protocol Amount) Packaged Content - for insertion in the Brand 3216 List Component's Protocol Amount Element 3217 o (Pay Protocol) Packaged Content - for insertion in the Brand 3218 List Component's Pay Protocol Element 3220 o Currency Amount element - quite similar to the definition in 3221 [IOTP], that contain 3222 - refined Currency Code and Currency - for insertion in the 3223 Brand List Component's Currency Amount Element 3224 - refined Payment Amount - for insertion in the Brand List 3225 Component's Currency Amount Element 3226 o Brand - there must be at least one element in each Protocol 3227 Item if no brand identifier has been provided on the input 3228 parameter list. 3230 XML definition: 3232 3234 3237 3245 3246 3249 3250 3255 Tables 4 and 5 explain the attributes and elements; Table 3 3256 introduces the Error Codes. 3258 4.1.3 Get Payment Initialization Data 3260 This API function provides the remaining initialization data being 3261 required by the Consumer's or Payment Handler's Existing Payment 3262 Software. This function might be called both for "brand dependent" 3263 and "brand independent" transaction types. In ether case, this 3264 function is called with one particular brand. 3266 Input Parameters 3268 o Brand Identifier - returned by "Find Accepted Payment Brand" 3269 o Merchant Payment Identifier - Merchant's unique private 3270 reference to the payment transaction 3271 o Payment Direction 3272 o Currency Code and Currency - from the Brand List Component's 3273 Currency Amount Element 3274 o Payment Amount - from the Brand List Component's Currency 3275 Amount Element 3276 o Payment Protocol Identifier - from the Brand List Component's 3277 Pay Protocol Element 3278 o Protocol Brand Identifier - from the Protocol Brand Element 3279 which relates to the selected Brand Element, if any 3280 o (TradingRoleData) Receiver Organization Identifier 3281 o OkFrom, OkTo - identical to the entries of the Order Component 3283 Merchant Payment Identifier 3285 o Merchant Organisation Identifier - used for distinction between 3286 multiple merchants that share the some IOTP merchant system 3287 o Wallet Identifier and/or Pass Phrase 3289 Protocol Brand Element 3291 o (Brand) Packaged Content - further payment brand description, 3292 from the Brand List Component's Brand Element 3293 o (Protocol Amount) Packaged Content - further payment protocol 3294 description, from the Brand List Component's Protocol Amount 3295 Element 3296 o (Pay Protocol) Packaged Content - further payment protocol 3297 description, from the Brand List Component's Pay Protocol 3298 Element 3299 o (Protocol Brand) Packaged Content - further brand information, 3300 from the Protocol Brand Element of the Brand List Component 3301 which relates to the selected Brand Element, if any 3302 o (Order) Packaged Content - further order description, from the 3303 Order Element 3304 o three Brand Selection Info Packaged Content elements - copied 3305 from the Brand Selection Component on brand dependent purchases 3306 o Brand - additional data about the payment brand 3307 o Protocol Amount - additional data about the payment protocol 3308 o Currency Amount - additional payment brand and currency 3309 specific data 3310 o Merchant Data - specific data used by the IOTP Payment Bridge 3311 which is managed in the IOTP Application Core. 3313 XML definition: 3315 3324 3339 Output Parameters 3341 o OkFrom, OkTo - for insertion in the Payment Component 3342 o (TradingRoleData) Packaged Content - further payment protocol 3343 description; the Name Attribute of the packaged Content 3344 element must include "Payment:" as the prefix, 3345 for example "Payment:SET-OD". 3346 o (Order) Packaged Content - defaults to the supplied order 3347 packaged content if omitted. 3349 XML definition: 3351 3354 3358 Tables 4 and 5 explain the attributes and elements; Table 3 3359 introduces the Error Codes. 3361 4.1.4 Inquire Authentication Challenge 3363 This API function inquires any payment protocol specific 3364 authentication challenge value from the IOTP Payment Bridge. In 3365 Baseline IOTP this API function is called by the Merchant (or 3366 Financial Institution). The IOTP Application Core may propose a 3367 choice of algorithms to the IOTP Payment Bridge. However, the IOTP 3368 Payment Bridge may ignore the proposal and select some other 3369 algorithm. 3371 The inquiry is assumed to be stateless. E.g., the IOTP Application 3372 Core may check the returned algorithm and stop transaction processing 3373 without notifying the IOTP Payment Bridge. 3375 The IOTP Application Core may issue several API calls to the IOTP 3376 Payment Bridge to build up the IOTP Authentication Request Block. Any 3377 subsequently submitted choice of algorithms should be constrained by 3378 the accepted algorithms from earlier API responses. 3380 The IOTP Payment Bridge responds with the Business Error Code if it 3381 does not provide any (more) authentication algorithms and challenges. 3383 Input Parameters 3385 o Authentication Identifier - the authenticator may provide its 3386 payment identifier, i.e., Payment Handler or Merchant Payment 3387 Identifier. 3388 o Wallet Identifier and/or Pass Phrase 3389 o set of pre-selected algorithms for authentication 3391 XML definition: 3393 3394 3399 Output Parameters 3401 o list of Authentication Challenge Packaged Contents - for 3402 insertion into the IOTP Authentication Request Component 3403 o Algorithm Element - for insertion into the IOTP Authentication 3404 Request Component 3406 XML definition: 3408 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 is based 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 actual 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 be completed or suspended prior to the 4294 processing of new payment transactions. It does not respond with 4295 further transaction details. These have to be requested with "Inquire 4296 Process State". 4298 Note that the IOTP Payment Bridge has to respond without the benefit 4299 of any pass phrase if there exist no pending payment transaction. But 4300 if there are some pending payment transactions, the IOTP Payment 4301 Bridge may refuse the immediate response and may instead request the 4302 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 which might consist of Packaged Content 4337 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 returns a business error. 4355 Note that this Payment API assumes that any payment receipt builds 4356 upon a subset of elements with reference to [IOTP]. Furthermore, the 4357 Packaged Content Element have to be distinguishable by their Name 4358 attribute. 4360 Input Parameters 4362 o Party's Payment Identifier 4363 o Wallet Identifier and/or Pass Phrase 4364 o All Packaged Content Elements in the payment receipt 4366 XML definition: 4368 4369 4374 Output Parameters 4376 XML definition: 4378 4379 4381 Tables 4 and 5 explain the attributes and elements; Table 3 4382 introduces the Error Codes. 4384 4.5.2 Expand Payment Receipt 4386 This API function expands any IOTP payment receipt into a form which 4387 may be used for display or printing purposes. "Check Payment Receipt" 4388 should be used first if there is any question of the payment receipt 4389 containing errors. 4391 The same conventions apply to the input parameter as for "Check 4392 Payment Receipt" (cf. Section 4.5.1). 4394 Input Parameters 4396 o Party's Payment Identifier 4397 o Wallet Identifier and/or Pass Phrase 4398 o All Packaged Content Elements that build the payment receipt 4400 XML definition: 4402 4403 4408 Output Parameters 4410 o Brand Identifier 4411 o Protocol specific Brand Identifier 4412 o Payment Instrument Identifier 4413 o Currency Code and Currency Code Type 4414 o Payment Amount 4415 o Payment Direction 4416 o Time Stamp - issuance of the receipt 4417 o Protocol Identifier 4418 o Protocol specific Transaction Identifier - this is an internal 4419 reference number which identifies the payment 4420 o Consumer Description, Payment Handler Description, and a 4421 language annotation 4423 o Style Sheet Net Location 4424 o Payment Property List. A list of type/value/description triples 4425 which contains additional information about the payment which 4426 is not covered by any of the other output parameters; property 4427 descriptions have to consider the language annotation. 4429 The Style Sheet Net Location refers to a Style Sheet (e.g. [XSLT]) 4430 that contains presenetation information about the reported XML 4431 encoded data. 4433 XML definition: 4435 4436 4452 4453 4458 The Existing Payment Software should return as many attributes as 4459 possible from the supplied IOTP Payment Receipt. The payment 4460 supplement defines the attribute values for the payment properties. 4462 Tables 4 and 5 explain the attributes and elements; Table 3 4463 introduces the Error Codes. 4465 4.5.3 Inquire Process State 4467 This API function returns the current payment state and optionally 4468 further Packaged Content Elements that form the payment receipt. 4469 Called by the Payment Handler, the IOTP Payment Bridge might respond 4470 with data intended for inclusion in the IOTP Payment Receipt 4471 Component's Packaged Content. When the Consumer calls this function 4472 shortly before payment completion, it may respond with further items 4473 of the payment receipt. Such items might be created by a chip card. 4475 Input Parameters 4477 o Party's Payment Identifier 4478 o Wallet Identifier and/or Pass Phrase 4480 XML definition: 4482 4483 4488 Output Parameters 4490 o Current Process State and Percent Complete 4491 o Completion Code 4492 o Status Description and its language annotation 4493 o Payment Receipt Name References to all Packaged Content 4494 Elements that build the payment receipt (cf. Section 4.5.1), 4495 even if they have not been created so far (Consumer's share) 4496 o Any Packaged Content Element being available that form the 4497 payment receipt 4499 The IOTP provides a linking capability to the payment receipt 4500 delivery. Instead of encapsulating the whole payment specific data 4501 into the packaged content of the payment receipt, other Payment 4502 Scheme Components' Packaged Content might be referred to. 4504 XML definition: 4506 4508 4521 Tables 4 and 5 explain the attributes and elements; Table 3 4522 introduces the Error Codes. 4524 4.5.4 Start Payment Inquiry 4526 This API function responds with any additional payment scheme 4527 specific data that is needed by the Payment Handler for Consumer 4528 initiated payment transaction inquiry processing. Probably, the IOTP 4529 Payment Bridge (or the corresponding Existing Payment Software) has 4530 to determine the payment related items that were provided with the 4531 "Start Payment Consumer" API function call. 4533 Input Parameters 4535 o Consumer Payment Identifier 4536 o Wallet Identifier and/or Pass Phrase 4538 XML definition: 4540 4541 4546 Output Parameters 4548 o (Payment Scheme) Packaged Content - intended for insertion in 4549 the Payment Scheme Component of the Inquiry Request Block 4551 XML definition: 4553 4556 Tables 4 and 5 explain the attributes and elements; Table 3 4557 introduces the Error Codes. 4559 4.5.5 Inquire Payment Status 4561 The Payment Handler calls this API function for Consumer initiated 4562 inquiry processing. It differs from the previous "Inquire Process 4563 State" API function by the optional inclusion of payment scheme 4564 specific data. The response may encapsulate further details about the 4565 payment transaction. 4567 Input Parameters 4569 o Payment Handler Payment Identifier 4570 o Wallet Identifier and/or Pass Phrase 4571 o (Payment Scheme) Packaged Content - copied from the Inquiry 4572 Request Block's Payment Scheme Component 4574 XML definition: 4576 4577 4582 Output Parameters 4584 o Current Process State 4585 o Completion Code 4586 o Status Description and its language annotation 4587 o (Payment Scheme) Packaged Content - intended for insertion in 4588 the Payment Scheme Component of the Inquiry Response Block 4590 XML definition: 4592 4594 4606 Tables 4 and 5 explain the attributes and elements; Table 3 4607 introduces the Error Codes. 4609 4.6 Other API Calls 4610 4.6.1 Manage Payment Software 4612 The following API function notifies the IOTP Payment Bridge about the 4613 intended registration, modification, or deletion of a payment 4614 instrument. The actual processing is up to the IOTP Payment Bridge. 4616 This API request may also be used to activate the IOTP Payment Bridge 4617 (and the corresponding Existing Payment Software) for general 4618 administration purposes. 4620 Input Parameters 4622 o Brand Identifier 4623 o Protocol Identifier 4624 o Any action code: 4625 o New - add new payment method / instrument 4626 o Update - change the payment method's / instrument's data 4627 o Delete - delete a payment method / instrument 4628 o Wallet Identifier and/or Pass Phrase 4629 o (Brand) Packaged Content - further payment brand description 4630 o (Pay Protocol) Packaged Content - further payment protocol 4631 description 4632 o (Protocol Amount) Packaged Content - further payment protocol 4633 description 4635 If the Action attribute is set, the Brand and Protocol Identifier 4636 have to also be set. The IOTP Payment Bridge has to provide the 4637 required user dialogs and selection mechanisms. E.g., updates and 4638 deletions may require the selection of the payment instrument. A new 4639 wallet might be silently generated on the supplement of a new Wallet 4640 Identifier or after an additional end user acknowledge. The IOTP 4641 Application Core should not provide any pass phrases for new wallets. 4642 Instead, the IOTP Payment Bridge has to request and verify them, 4643 which may return their value to the IOTP Application Core in plain 4644 text. In addition, the IOTP Payment Bridge returns the supported 4645 authentication algorithms when a new brand and protocol pair has been 4646 registered. 4648 If the "Action" attribute is omitted, the IOTP Payment Bridge which 4649 is responsible for the Existing Payment Software pops up in a general 4650 interactive mode. 4652 XML definition: 4654 4657 4666 Output Parameters 4668 o An action code: 4669 o New - added new wallet 4670 o Update - changed wallet's configuration 4671 o Delete - removed a wallet 4672 o Wallet Identifier and/or Pass Phrase 4674 The IOTP Payment Bridge does not return any information about the set 4675 of registered payment instruments because these data items are 4676 dynamically inferred during the brand selection process at the 4677 beginning of each IOTP transaction. However, the IOTP Application 4678 Core has to be notified about new wallets and should be notified 4679 about updated and removed wallet (identifier)s". Alternatively, 4680 removed wallets can be implicitly detected during the next brand 4681 selection phase. Updated wallets do no affect the processing of the 4682 IOTP Application Core. The IOTP Payment Bridge should only support 4683 the addition of at most one wallet because it is not able to report 4684 multiple additions at once back to the IOTP Application Core. 4686 XML definition: 4688 4689 4697 Tables 4 and 5 explain the attributes and elements; Table 3 4698 introduces the Error Codes. 4700 5. Call Back Function 4702 This API function, called by the IOTP Payment Bridge, is used to 4703 provide information for Consumer or Payment Handler notification 4704 about the progress of the payment transaction. 4706 Its use is illustrated in the diagram below. 4708 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 4709 IOTP Application ----calls---- 4710 | Core | | 4711 display | | v 4712 to <---------- Call Back <--calls--- Payment 4713 user | | Software 4714 ---------------- 4715 *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 4717 Figure 9. Call Back Function 4719 Whenever this function is called, the content of the status 4720 description should be made available to the user. For example on a 4721 status bar, a pop up window, etc. 4723 A reference to the Call Back function is passed as an input parameter 4724 to the "Start Payment X" and "Resume Payment X" API function. 4725 Afterwards, this function might be called whenever the status changes 4726 or progress needs to be reported. 4728 Input Parameters 4730 o the software identifier of the caller 4731 o Party's Payment Identifier 4732 o Process State and Percent Complete 4733 o Completion Code 4734 o Status Description and its language annotation, text which 4735 provides information about the progress of the call. It should 4736 be displayed or made available to, for example, the Consumer. 4738 Examples of Status Description could be: 4740 o "Paying 12.30 USD to XYZ Inc" 4741 o "Payment completed" 4742 o "Payment aborted" 4744 The valid languages are announced in the Call Back Language List 4745 attribute in "Start Payment X" and "Resume Payment X" API function 4746 calls. 4748 XML definition: 4750 4751 4765 Output Parameters 4767 XML definition: 4769 4770 > 4772 Tables 4 and 5 explain the attributes and elements; Table 3 4773 introduces the Error Codes. 4775 Basically, the call back function accepts all input arguments or 4776 rejects the whole request. It may even accept malformed requests. 4778 Some payment schemes may support or require that the Consumer might 4779 be able to cancel the payment at any time. The Call Back function can 4780 be used to facilitate this by returning the cancellation request on 4781 the next call (using the Business Error Code and Completion Code 4782 "ConsCancelled"). 4784 Vice versa the Payment Handler's Application Core might use the 4785 similar mechanism to signal its IOTP Payment Bridges any exceptional 4786 need for a fast shutdown. These IOTP Payment Bridges may initiate the 4787 appropriate steps for terminating/canceling all pending payment 4788 transactions. 4790 Note that the "Change Process State" API function provides the second 4791 mechanism for such kind of notification. Therefore, the IOTP Payment 4792 Bridge or Existing Payment Software may ignore the details of the 4793 "Call Back" response. 4795 6. Security Consideration 4797 The IOTP Payment APIs only supports security using pass phrase to 4798 access to payment Wallet. These can be protected over TLS, which 4799 provides stronger security at the transport layer, but 4800 implementations are out the scope of this document. 4802 See also security consideration section of [IOTP]. 4804 Full Copyright Statement 4806 Copyright (C) The Internet Society 2001. 4808 This document and translations of it may be copied and furnished to 4809 others, and derivative works that comment on or otherwise explain it 4810 or assist in its implementation may be prepared, copied, published 4811 and distributed, in whole or in part, without restriction of any 4812 kind, provided that the above copyright notice and this paragraph are 4813 included on all such copies and derivative works. However, this 4814 document itself may not be modified in any way, such as by removing 4815 the copyright notice or references to the Internet Society or other 4816 Internet organizations, except as needed for the purpose of 4817 developing Internet standards in which case the procedures for 4818 copyrights defined in the Internet Standards process must be 4819 followed, or as required to translate it into languages other than 4820 English. 4822 The limited permissions granted above are perpetual and will not be 4823 revoked by the Internet Society or its successors or assigns. 4825 This document and the information contained herein is provided on an 4826 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4827 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4828 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4829 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4830 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4832 References 4834 [HTML] - Hyper Text Mark Up Language. The Hypertext Markup Language 4835 (HTML) is a simple markup language used to create hypertext documents 4836 that are platform independent. See RFC 1866 and the World Wide Web 4837 (W3C) consortium web site at: http://www.w3.org/MarkUp/ 4839 [HTTP] - Hyper Text Transfer Protocol versions 1.0 and 1.1. See RFC 4840 1945: Hypertext Transfer Protocol - HTTP/1.0. T. Berners-Lee, R. 4841 Fielding & H. Frystyk. May 1996. and RFC 2068: Hypertext Transfer 4842 Protocol - HTTP/1.1. R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. 4843 Berners-Lee. January 1997. 4845 [IOTP] - Internet Open Trading Protocol Specification, Version 1.0, 4846 April 2000, See RFC2801. 4848 [IOTPBOOK] - D. Burdett, D.E. Eastlake III, and M. Goncalves, 4849 Internet Open Trading Protocol, McGraw-Hill, 2000. ISBN 0-07-135501- 4850 4. 4852 [ISO4217] - ISO 4217: Codes for the Representation of Currencies. 4853 Available from ANSI or ISO. 4855 [MIME] - Multipurpose Internet Mail Extensions. See RFC822, RFC2045, 4856 RFC2046, RFC2047, RFC2048 and RFC2049. 4858 [SET] - SET Secure Electronic Transaction(TM) , Version 1.0, May 31, 4859 1997 4860 Book 1: Business Description 4861 Book 2: Programmer's Guide 4862 Book 3: Formal Protocol Definition 4863 Download from: . 4865 [SET/IOTP] - Yoshiaki Kawatsura "SET Supplement for IOTP" (currently 4866 draft-ietf-trade-iotp-v1.0-set-02.txt) 4868 [URL] - Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform 4869 Resource Locators (URL)", RFC 1738, December 1994. 4871 [UTC] - Universal Time Coordinated. A method of defining time 4872 absolutely relative to Greenwich Mean Time (GMT). Typically of the 4873 form: "CCYY-MM- DDTHH:MM:SS.sssZ+n" where the "+n" defines the number 4874 of hours from GMT. See ISO DIS8601. 4876 [XML] - Extensible Mark Up Language (XML) 1.0 (Second Edition). A 4877 W3C recommendation. See http://www.w3.org/TR/1998/REC-xml 4879 [XML-NS] - Namespaces in XML Recommendation. T. Bray, D. Hollander, 4880 A. Layman. Janaury 1999. http://www.w3.org/TR/1999/REC-xml-names 4882 [XSLT] - Extensible Style Language Transformations 1.0, November 4883 1999, See http://www.w3.org/TR/xslt 4885 Author's Addresses 4887 Hans-Bernhard Beykirch and Werner Hans 4888 IT Development & Coordination Center for the German Savings Banks 4889 Organization (SIZ) 4890 Konigswinterer Strase 553 4891 53227 Bonn 4892 Germany 4893 E-mail: Hans-Bernhard.Beykirch@siz.de, Werner.Hans@siz.de 4895 Masaaki Hiroya and Yoshiaki Kawatsura 4896 Hitachi, Ltd. 4897 890 Kashimada Saiwai-ku Kawasaki-shi 4898 Kanagawa, Japan 212-8567 4899 E-mail: hiroya@sdl.hitachi.co.jp, kawatura@bisd.hitachi.co.jp 4901 Expiration and File Name 4903 This draft expires September 2001. 4905 Its file name is draft-ietf-trade-iotp-v1.0-papi-04.txt.