tech-invite   World Map
3GPP     Specs     Glossaries     UICC       IETF     RFCs     Groups     SIP     ABNFs       T+       Search     Home

RFC 3867

Informational
Pages: 106
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: TRADE

Payment Application Programmers Interface (API) for v1.0 Internet Open Trading Protocol (IOTP)

Part 1 of 4, p. 1 to 12
None       Next RFC Part

 


Top       ToC       Page 1 
Network Working Group                                       Y. Kawatsura
Request for Comments: 3867                                       Hitachi
Category: Informational                                        M. Hiroya
                                                      Technoinfo Service
                                                             H. Beykirch
                                                             Atos Origin
                                                           November 2004


       Payment Application Programmers Interface (API) for v1.0
                 Internet Open Trading Protocol (IOTP)

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2004).

Abstract

   The Internet Open Trading Protocol (IOTP) provides a data exchange
   format for trading purposes while integrating existing pure payment
   protocols seamlessly.  This motivates the multiple layered system
   architecture which consists of at least some generic IOTP application
   core and multiple specific payment modules.

   This document addresses a common interface between the IOTP
   application core and the payment modules, enabling the
   interoperability between these kinds of modules.  Furthermore, such
   an interface provides the foundations for a plug-in-mechanism in
   actual implementations of IOTP application cores.

   Such interfaces exist at the Consumers', the Merchants' and the
   Payment Handlers' installations connecting the IOTP application core
   and the payment software components/legacy systems.

Top       Page 2 
Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
       1.1.  General payment phases . . . . . . . . . . . . . . . . .  5
       1.2.  Assumptions. . . . . . . . . . . . . . . . . . . . . . .  6
   2.  Message Flow . . . . . . . . . . . . . . . . . . . . . . . . . 12
       2.1.  Authentication Documentation Exchange. . . . . . . . . . 15
       2.2.  Brand Compilation. . . . . . . . . . . . . . . . . . . . 17
       2.3.  Brand Selection. . . . . . . . . . . . . . . . . . . . . 21
       2.4.  Successful Payment . . . . . . . . . . . . . . . . . . . 24
       2.5.  Payment Inquiry. . . . . . . . . . . . . . . . . . . . . 29
       2.6.  Abnormal Transaction Processing. . . . . . . . . . . . . 30
             2.6.1.  Failures and Cancellations . . . . . . . . . . . 30
             2.6.2.  Resumption . . . . . . . . . . . . . . . . . . . 32
       2.7.  IOTP Wallet Initialization . . . . . . . . . . . . . . . 33
       2.8.  Payment Software Management. . . . . . . . . . . . . . . 34
   3.  Mutuality. . . . . . . . . . . . . . . . . . . . . . . . . . . 34
       3.1.  Error Codes. . . . . . . . . . . . . . . . . . . . . . . 38
       3.2.  Attributes and Elements. . . . . . . . . . . . . . . . . 48
       3.3.  Process States . . . . . . . . . . . . . . . . . . . . . 61
             3.3.1.  Merchant . . . . . . . . . . . . . . . . . . . . 61
             3.3.2.  Consumer . . . . . . . . . . . . . . . . . . . . 63
             3.3.3.  Payment Handler. . . . . . . . . . . . . . . . . 65
   4.  Payment API Calls. . . . . . . . . . . . . . . . . . . . . . . 66
       4.1.  Brand Compilation Related API Calls. . . . . . . . . . . 66
             4.1.1.  Find Accepted Payment Brand. . . . . . . . . . . 66
             4.1.2.  Find Accepted Payment Protocol . . . . . . . . . 68
             4.1.3.  Get Payment Initialization Data. . . . . . . . . 70
             4.1.4.  Inquire Authentication Challenge . . . . . . . . 72
             4.1.5.  Authenticate . . . . . . . . . . . . . . . . . . 73
             4.1.6.  Check Authentication Response. . . . . . . . . . 74
       4.2.  Brand Selection Related API Calls. . . . . . . . . . . . 76
             4.2.1.  Find Payment Instrument. . . . . . . . . . . . . 76
             4.2.2.  Check Payment Possibility. . . . . . . . . . . . 78
       4.3.  Payment Transaction Related API calls. . . . . . . . . . 80
             4.3.1.  Start Payment Consumer . . . . . . . . . . . . . 80
             4.3.2.  Start Payment Payment Handler. . . . . . . . . . 82
             4.3.3.  Resume Payment Consumer. . . . . . . . . . . . . 84
             4.3.4.  Resume Payment Payment Handler . . . . . . . . . 85
             4.3.5.  Continue Process . . . . . . . . . . . . . . . . 86
             4.3.6.  Change Process State . . . . . . . . . . . . . . 88
       4.4.  General Inquiry API Calls. . . . . . . . . . . . . . . . 89
             4.4.1.  Remove Payment Log . . . . . . . . . . . . . . . 90
             4.4.2.  Payment Instrument Inquiry . . . . . . . . . . . 90
             4.4.3.  Inquire Pending Payment. . . . . . . . . . . . . 92
       4.5.  Payment Related Inquiry API Calls. . . . . . . . . . . . 93
             4.5.1.  Check Payment Receipt. . . . . . . . . . . . . . 93
             4.5.2.  Expand Payment Receipt . . . . . . . . . . . . . 94

Top      ToC       Page 3 
             4.5.3.  Inquire Process State. . . . . . . . . . . . . . 96
             4.5.4.  Start Payment Inquiry. . . . . . . . . . . . . . 97
             4.5.5.  Inquire Payment Status . . . . . . . . . . . . . 98
       4.6.  Other API Calls. . . . . . . . . . . . . . . . . . . . . 99
             4.6.1.  Manage Payment Software. . . . . . . . . . . . . 99
   5.  Call Back Function . . . . . . . . . . . . . . . . . . . . . .101
   6.  Security Considerations. . . . . . . . . . . . . . . . . . . .103
   7.  References . . . . . . . . . . . . . . . . . . . . . . . . . .103
       7.1.  Normative References . . . . . . . . . . . . . . . . . .103
       7.2.  Informative References . . . . . . . . . . . . . . . . .104
   Acknowledgement. . . . . . . . . . . . . . . . . . . . . . . . . .105
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . .105
   Full Copyright Statement . . . . . . . . . . . . . . . . . . . . .106

1.  Introduction

   Common network technologies are based on standardized and established
   Internet technologies.  The Internet technologies provide mechanisms
   and tools for presentation, application development, network
   infrastructure, security, and basic data exchange.

   Due to the presence of already installed trading roles' systems with
   their own interfaces (Internet shop, order management, payment,
   billing, and delivery management systems, or financial institute's
   legacy systems), IOTP has been limited to the common external
   interface over the Internet. However, some of these internal
   interfaces might be also standardized for better integration of IOTP
   aware components with of the existing infrastructure and its cost
   effective reuse. For more information on IOTP, see [IOTP] and
   [IOTPBOOK].

   The typical Payment Handlers (i.e., financial institutes or near-bank
   organizations) as well as Merchants require an IOTP aware application
   that easily fits into their existing financial infrastructure.  The
   Payment Handler might even insist on the reuse of special in-house
   solutions for some subtasks of the IOTP aware application, e.g.,
   reflecting their cryptography modules, gateway interfaces, or
   physical environment.  Therefore, their IOTP aware implementation
   really requires such clear internal interfaces.

   More important, consumers demand modularization and clear internal
   interfaces: Their IOTP application aims at the support of multiple
   payment methods.  Consumers prefer the flexible use of different
   seamless integrating payment methods within one trading application
   with nearly identical behavior and user interface.  The existence of
   a well-defined interface enables payment software developers to bolt
   on their components to other developer's general IOTP Application
   Core.

Top      ToC       Page 4 
   Initially, this consideration leads to the two-level layered view of
   the IOTP software for each role, consisting of:

   o  some generic IOTP system component, the so-called IOTP application
      core - providing IOTP based gateway services and generic business
      logic and

   o  the trading roles' specific back-end systems implementing the
      specific trading transaction types' functionality.

   In order to isolate the changes on the infrastructure, the IOTP
   trading application has been three-layered:

   o  the IOTP Application Core processes the generic parts of the IOTP
      transaction and holds the connection to the Internet,

   o  the Existing Legacy System or Existing Payment Software which
      processes the actual transaction type, and particular payment
      transaction, and

   o  the IOTP Middle-ware or IOTP Payment Bridge which glues the other
      two possibly incompatible components.  It brokers between the
      specific interface of the Existing Legacy System and the
      standardized interfaces of the IOTP Application Core.

   As IOTP extends payment schemes to a trading scheme, primarily, this
   document focuses on payment modules, i.e., the interface between the
   IOTP Payment Bridge and the IOTP Application Core.  It provides a
   standard method for exchanging payment protocol messages between the
   parties involved in a payment.  But, it does not specify any
   interface for order or delivery processing.

   Such a Payment Application Programmers Interface (API) must suit for
   a broad range of payment methods: (1) software based like Credit Card
   SET or CyberCoin, (2) chip card based like Mondex or GeldKarte, and
   (3) mimicries of typical and traditional payment methods like money
   transfer, direct debit, deposit, withdrawal, money exchange and value
   points.  It should support both payments with explicit consumer
   acknowledge and automatic repeated payments, which have been consumer
   approved in advance.  For more information on SET, see [SET].

   The following discussion focuses on the Consumer's point of view and
   uses the associated terminology.  When switching to Merchants' or
   Delivery Handlers' IOTP aware applications, the payment related
   components should be implicitly renamed by Existing Legacy Systems to
   the IOTP Middle-ware.

Top      ToC       Page 5 
   The next two sub-sections describe the general payment scenario and
   several assumptions about the coarsely sketched software components.

   Section 2 illustrates the payment transaction progress and message
   flow of different kinds of transaction behavior.  Sections 3 to 4
   provide the details of the API functions and Section 5 elaborates the
   call back interface.

1.1.  General payment phases

   The following table sketches the four logical steps of many payment
   schemes.  The preceding agreements about the goods, payment method,
   purchase amount, or delivery rules are omitted.

   Payment State  Party             Example Behavior
   -------------  -----             ----------------

   Mutual         Payment Handler   Generation of identification
   Authentication                   request, solvency request, or
   and                              some nonce
   Initialization Consumer          Responses to the requests and
                                    generation of own nonce

   Authorization  Payment Handler   Generation of the authorization
                                    request (for consumer)
                  Consumer          Agreement to payment (by
                                    reservation of the Consumer's
                                    e-money)
                  Payment Handler   Acceptance or rejection of the
                                    agreement (consumer's
                                    authorization response),
                                    generation of the authorization
                                    request (for issuer/acquirer),
                                    and processing of its response

   Capture                          Generation of the capture
                                    request (for issuer/acquirer)
                  Consumer          Is charged
                  Payment Handler   Acceptance or rejection of the
                                    e-money, close of the payment
                                    transaction

   Reversal                         On rejection (online/delayed):
                                    generation of the reversal data
                  Consumer          Receipt of the refund

Top      ToC       Page 6 
   However, some payment schemes:

   o  limit themselves to one-sided authentication,
   o  perform off-line authorization without any referral to any
      issuer/acquirer,
   o  apply capture processing in batch mode, or
   o  do not distinguish between authorization and capture,
   o  lack an inbound mechanism for reversals or implement a limited
      variant.

   This model applies not only to payments at the typical points of
   sales but extends to refunds, deposits, withdrawals, electronic
   cheques, direct debits, and money transfers.

1.2.  Assumptions

   In outline, the IOTP Payment Bridge processes some input sequence of
   payment protocol messages being forwarded by the IOTP Application
   Core.  It (1) disassembles the messages, (2) maps them onto the
   formats of the Existing Payment Software, (3) assembles its
   responses, and (4) returns another sequence of payment protocol
   messages that is mostly intended for transparent transmission by the
   IOTP Application Core to some IOTP aware remote party.  Normally,
   this process continues between the two parties until the Payment
   Handler's Payment API signals the payment termination.
   Exceptionally, each system component may signal failures.

   The relationship between the aforementioned components is illustrated
   in the following figure.  These components might be related to each
   other in a flexible n-to-m-manner:

   o  One IOTP Application Core may manage multiple IOTP Payment Bridges
      and the latter might be shared between multiple IOTP Application
      Cores.
   o  Each Payment Bridge may manage multiple Existing Payment Software
      modules and the latter might be shared between multiple Payment
      Bridges.
   o  Each Existing Payment Software may manage multiple payment schemes
      (e.g., SET) and the latter might be supported by multiple Existing
      Payment Software modules.  For more information on SET see [SET].

   o  Each payment scheme may support multiple payment instruments
      (e.g., particular card) or methods (e.g., Visa via SET) and the
      latter might be shared by multiple Existing Payment Software
      Components.

Top      ToC       Page 7 
   *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
   IOTP client (consumer)  <--------------->  IOTP server (merchant)
   (      contains             Internet       (      contains
   IOTP Application Core)                     IOTP Application Core)
         ^                                          ^
         | IOTP Payment                             | IOTP Payment
         |    API                                   |    API
         v                                          v
   IOTP Payment Bridge                        IOTP Payment Bridge
        ^                                           ^
        | Existing Payment APIs, e.g.,              |
        | SET, Mondex, etc.                         |
        v                                           v
   Existing Payment Software               Existing Payment Software
   *+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*

                 Figure 1: Relationship of the Components

   The Payment API considers the following transaction types of Baseline
   IOTP:

      o  Baseline Purchase,
      o  Baseline Refund,
      o  Baseline Value Exchange,
      o  Baseline Withdrawal, and
      o  Baseline (Payment) Inquiry.

   For more information on Baseline IOTP, see [IOTP] and [IOTPBOOK].

   First, the authors' vision of the IOTP aware application's and its
   main components' capabilities are clarified: On the one hand, the
   Payment API should be quite powerful and flexible for sufficient
   connection of the generic and specific components.  On the other
   hand, the Payment API should not be overloaded with nice-to-haves
   being unsupported by Existing Payment Software.

   Despite the strong similarities on the processing of successful
   payments, failure resolution and inquiry capabilities differ
   extremely among different payment schemes.  These aspects may even
   vary between different payment instrument using the same payment
   schemes.  Additionally, the specific requirements of Consumers,
   Merchants and Payment Handlers add variance and complexity.
   Therefore, it is envisioned that the IOTP Application Core provides
   only very basic inquiry mechanisms while complex and payment scheme
   specific inquiries, failure analysis, and failure resolution are
   fully deferred to the actual Existing Payment Software - including
   the user interface.

Top      ToC       Page 8 
   The IOTP Application Core processes payments transparently, i.e., it
   forwards the wrapped payment scheme specific messages to the
   associated IOTP Payment Bridge/Existing Payment Software.  The
   Existing Payment Software might even use these messages for inbound
   failure resolution.  It reports only the final payment status to the
   IOTP Application Core or some intermediate - might be also final -
   status on abnormal interruption.

   The IOTP Application Core implements the generic and payment scheme
   independent part of the IOTP transaction processing and provides the
   suitable user interface.  Focusing on payment related tasks, it

   o  manages the registered IOTP Payment Bridges and provides a
      mechanism for their registration - the latter is omitted by this
      document.

   o  assumes that any IOTP Payment Bridge is a passive component, i.e.,
      it strictly awaits input data and generates one response to each
      request,

   o  supports the payment negotiation (Consumer: selection of the
      actual payment instrument or method; Merchant: selection of the
      payment methods being offered to the Consumer) preceding the
      payment request,

   o  requests additional payment specific support from the Existing
      Payment Software via the selected and registered the IOTP Payment
      Bridge,

   o  initializes and terminates the Existing Payment Software via the
      IOTP Payment Bridge,

   o  inquires authentication data (for subsequent request or response)
      from the Existing Payment Software, specific authentication
      component - omitted in this document - or Consumer (by a suitable
      user interface),

   o  supervises the online transaction process and traces its progress,

   o  stores the transaction data being exchanged over the IOTP wire -
      payment scheme specific data is handled transparently,

   o  relates each payment transaction with multiple payment parameters
      (IOTP Transaction Identifier, Trading Protocol Options, Payment
      Instrument/Method, Offer Response, IOTP Payment Bridge, and Wallet
      Identifier, associated remote Parties).  The relation might be

Top      ToC       Page 9 
      lowered to the party's Payment Identifier, IOTP Payment Bridge,
      Wallet Identifier, and the remote parties when the actual payment
      transaction has been successfully started.

   o  implements a payment transaction progress indicator,

   o  enables the inquiry of pending and completed payment transactions,

   o  implements generic dialogs, e.g., brand selection, payment
      acknowledge, payment suspension / cancellation, receipt
      visualization, basic transaction inquiry, balance inquiry, or
      receipt validation,

   o  defers payment specific processing, supervision, validation, and
      error resolution to the Existing Payment Software.  It is
      expected, that the Existing Payment Software will try to resolve
      many errors first by the extended exchange of Payment Exchange
      messages.  The most significant and visible failures arise from
      sudden unavailability or lapses of the local or opposing payment
      component.

   o  supports the invocation of any Existing Payment Software in an
      interactive mode, which might be used (1) for the payment scheme
      specific post-processing of a (set of) payment transactions, (2)
      for the analysis of a payment instrument, (3) for the registration
      of a new payment instrument/scheme, or (4) re-configuration of a
      payment instrument/scheme.

   o  exports call back functions for use by the IOTP Payment Bridge or
      Existing Payment Software for progress indication.

   In addition, the IOTP Application Core

   o  manages the IOTP message components and IOTP message blocks
      exchanged during the transaction which may be referenced and
      accessed during the processing of subsequent messages, e.g., for
      signature verification.  In particular, it stores named Packaged
      Content elements exchanged during payments.

   o  manages several kinds of identifiers, i.e., transaction, message,
      component, and block identifiers,

   o  implements a message caching mechanism,

   o  detects time-outs at the protocol and API level reflecting the
      communication with both the IOTP aware remote party and the
      Payment API aware local periphery, e.g., chip card (reader) may
      raise time-outs.

Top      ToC       Page 10 
   However, the IOTP Payment Bridge and Existing Payment Software do not
   have to rely on all of these IOTP Application Core's capabilities.
   E.g., some Consumer's Existing Payment Software may refuse the
   disclosure of specific payment instruments at brand selection time
   and may delay this selection to the "Check Payment Possibility"
   invocation using its own user interface.

   The IOTP Payment Bridge's capabilities do not only deal with actual
   payments between the Consumer and the Payment Handler but extend to
   the following:

   o  translation and (dis)assemblage of messages between the formats of
      the IOTP Payment API and those of the Existing Payment Software.
      Payment API requests and response are strictly 1-to-1 related.

   o  Consumer's payment instrument selection by the means of an
      unsecured/public export of the relationship of payment brands,
      payment protocols, and payment instruments (identifiers).
      Generally, this includes not just the brand (Mondex, GeldKarte,
      etc.) but also which specific instance of the instrument and
      currency to use (e.g., which specific Mondex card and which
      currency of all those available).

   However, some Existing Payment Software may defer the selection of
   the payment instrument to the actual payment carrying-out or it may
   even lack any management of payment instruments.  E.g., chip card
   based payment methods may offer - Point of Sale like - implicit
   selection of the payment instrument by simple insertion of the chip
   card into the chip card reader or it interrogates the inserted card
   and requests an acknowledge (or selection) of the detected payment
   instrument(s).

   o  payment progress checks, e.g., is there enough funds available to
      carry out the purchase, or enough funds left for the refund,

   o  IOTP Payment Receipt checks which might be performed over its
      Packaged Content or by other means.

   o  recoding of payment scheme specific receipts into a format which
      can be displayed to the user or printed,

   o  cancellation of payment, even though it is not complete,

   o  suspension and resumption of payment transactions.  Two kinds of
      failures the Existing Payment Software might deal with are (1) the
      time-out of the network connection and (2) lack of funds.  For
      resolution, the IOTP Application Core may try the suspension with
      a view to later possible resumption.

Top      ToC       Page 11 
   o  recording the payment progress and status on a database.  E.g.,
      information about pending payments might be used to assist their
      continuation when the next payment protocol message is received.

   o  payment transaction status inquiry, so that the inquirer - IOTP
      Application Core or User - can determine the appropriate next
      step.

   o  balance inquiry or transaction history, e.g., consumers may
      interrogate their chip card based payment instrument or remotely
      administer some account in advance of a payment transaction
      acknowledge,

   o  inquiry on abnormal interrupted payment transactions, which might
      be used by the IOTP Application Core to resolve these pending
      transactions at startup (after power failure).

   o  payment progress indication.  This could be used to inform the end
      user of details on what is happening with the payment.

   o  payment method specific authentication methods.

   Existing Payment Software may not provide full support of these
   capabilities.  E.g., some payment schemes may not support or may even
   prevent the explicit transaction cancellation at arbitrary phases of
   the payment process.  In this case, the IOTP Payment Bridge has to
   implement at least skeletons that signal such lack of support by the
   use of specific error codes (see below).

   The Existing Payment Software's capabilities vary extremely.  It

   o  supports payment scheme specific processing, supervision,
      validation, and error resolution.  It is expected, that many
      errors are tried to be resolved first by the extended exchange of
      Payment Exchange messages.

   o  provides hints for out-of-band failure resolution on failed
      inbound resolution - inbound resolution is invisible to the IOTP
      Application Core.

   o  may implement arbitrary transaction data management and inquiry
      mechanisms ranging from no transaction recording, last transaction
      recording, chip card deferred transaction recording, simple
      transaction history to sophisticated persistent data management
      with flexible user inquiry capabilities.  The latter is required
      by Payment Handlers for easy and cost effective failure
      resolution.

Top      ToC       Page 12 
   o  implements the payment scheme specific dialog boxes.

   Even the generic dialog boxes of the IOTP Application Core might be
   unsuitable: Particular (business or scheme) rules may require some
   dedicated appearance / structure / content or the dialog boxes, may
   prohibit the unsecured export of payment instruments, or may
   prescribe the pass phrase input under its own control.



(page 12 continued on part 2)

Next RFC Part