RFC 3867
Payment Application Programmers Interface (API) for v1.0 Internet Open Trading Protocol (IOTP)
Pages: 106
Informational
Informational
Part 1 of 4 – Pages 1 to 12
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.
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
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.
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.
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
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.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+* 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.
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
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.
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.
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.
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)