RFC 3867
Payment Application Programmers Interface (API) for v1.0 Internet Open Trading Protocol (IOTP)
Pages: 106
Informational
Informational
Part 4 of 4 – Pages 66 to 106
4. Payment API Calls
4.1. Brand Compilation Related API Calls
4.1.1. Find Accepted Payment Brand
This API function determines the payment brands being accepted by the Payment Handler on behalf of the Merchant. Input Parameters o Payment Direction - provided by the IOTP Application Core o Currency Code and Currency - provided by the IOTP Application Core o Payment Amount - provided by the IOTP Application Core o Merchant Payment Identifier - Merchant's unique private reference to the payment transaction o Merchant Organisation Identifier - used for distinction between multiple merchants that share the some IOTP merchant system o Wallet Identifier - managed by the IOTP Application Core o Merchant Data - specific data used by the IOTP Payment Bridge which is managed in the IOTP Application Core.
XML definition:
<!ELEMENT FindAcceptedPaymentBrand (MerchantData*) >
<!ATTLIST FindAcceptedPaymentBrand
PayDirection (Debit|Credit) #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
MerchantPayId CDATA #REQUIRED
MerchantOrgId CDATA #IMPLIED
WalletID CDATA #IMPLIED >
Output Parameters
o Payment Brand Identifier - for insertion in the Brand List
Component's Brand Element
o Payment Brand Name and language annotation - for insertion in
the Brand List Component's Brand Element
o Payment Brand Logo Net Location - for insertion in the Brand
List Component's Brand Element
o Payment Brand Narrative Description - for insertion in the
Brand List Component's Brand Element
o (Brand) Packaged Content - further payment brand description
for insertion in the Brand List Component's Brand Element
The Existing Payment Software returns an empty list of brand items,
if it does not support any payment brand/payment protocol combination
for the given payment parameters.
XML definition:
<!ELEMENT FindAcceptedPaymentBrandResponse (BrandItem*) >
<!ELEMENT BrandItem (BrandPackagedContent*) >
<!ATTLIST BrandItem
BrandId CDATA #REQUIRED
xml:lang NMTOKEN #IMPLIED
BrandName CDATA #REQUIRED
BrandLogoNetLocn CDATA #REQUIRED
BrandNarrative CDATA #IMPLIED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.1.2. Find Accepted Payment Protocol
This API function determines the instances of payment protocols (and optionally the payment brands) being accepted by the Payment Handler on behalf of the Merchant. The function might be called in two variants: o With the Brand Identifier set on the input parameter list: The function responds with the payment protocols that fits to the submitted brand. o Without any Brand Identifier - that allows the omission of the "Find Accepted Payment Brand" API call (cf. Section 4.1.1): This function responds with both the supported brand identifiers and the payment protocols being specified by the Brand Elements. Input Parameters o Brand Identifier - returned by "Find Accepted Payment Brand" o Payment Direction o Currency Code and Currency o Payment Amount o Merchant Payment Identifier - Merchant's unique private reference to the payment transaction o Merchant Organisation Identifier - used for distinction between multiple merchants that share the some IOTP merchant system o Wallet Identifier - managed by the IOTP Application Core o (Brand) Packaged Content - further payment brand description; returned by "Find Accepted Payment Brand"; this elements are only provided if the Brand Identifier is set o Merchant Data - specific data used by the IOTP Payment Bridge which is managed in the IOTP Application Core. XML definition: <!ELEMENT FindAcceptedPaymentProtocol (BrandPackagedContent*, MerchantData?) > <!ATTLIST FindAcceptedPaymentProtocol BrandId CDATA #IMPLIED PayDirection (Debit|Credit) #REQUIRED CurrCodeType NMTOKEN 'ISO4217-A' CurrCode CDATA #REQUIRED Amount CDATA #REQUIRED MerchantPayId CDATA #REQUIRED MerchantOrgId CDATA #IMPLIED WalletID CDATA #IMPLIED >
Output Parameters
o Payment Protocol Identifier - for insertion in the Brand List
Component's Pay Protocol Element
o Protocol Brand Identifier - for insertion in the Protocol Brand
Element of the Brand List Component's Brand Element
o Payment Protocol Name and language annotation- for insertion in
the Brand List Component's Pay Protocol Element
o Payment Request Net Location - for insertion in the Brand List
Component's Pay Protocol Element
o Secured Payment Request Net Location - for insertion in the
Brand List Component's Pay Protocol Element
o Brand Item List (cf. Section 4.1.1) - there must be at least
one element if no brand identifier has been provided on the
input parameter list.
o (Protocol Amount) Packaged Content - for insertion in the Brand
List Component's Protocol Amount Element
o (Pay Protocol) Packaged Content - for insertion in the Brand
List Component's Pay Protocol Element
o Currency Amount element - quite similar to the definition in
[IOTP], that contain
- refined Currency Code and Currency - for insertion in the
Brand List Component's Currency Amount Element
- refined Payment Amount - for insertion in the Brand List
Component's Currency Amount Element
o Brand - there must be at least one element in each Protocol
Item if no brand identifier has been provided on the input
parameter list.
XML definition:
<!ELEMENT FindAcceptedPaymentProtocolResponse (ProtocolItem+,
BrandItem*) >
<!ELEMENT ProtocolItem (ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*
CurrencyAmount+, Brand*,ProtocolBrand*)>
<!ATTLIST ProtocolItem
ProtocolId CDATA #REQUIRED
ProtocolBrandId CDATA #IMPLIED
xml:lang NMTOKEN #IMPLIED
ProtocolName CDATA #REQUIRED
PayReqNetLocn CDATA #IMPLIED
SecPayReqNetLocn CDATA #IMPLIED >
<!ELEMENT Brand EMPTY >
<!ATTLIST Brand
BrandId CDATA #REQUIRED >
<!ELEMENT CurrencyAmount EMPTY >
<!ATTLIST CurrencyAmount
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #IMPLIED
Amount CDATA #IMPLIED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.1.3. Get Payment Initialization Data
This API function provides the remaining initialization data being
required by the Consumer's or Payment Handler's Existing Payment
Software. This function might be called both for "brand dependent"
and "brand independent" transaction types. In either case, this
function is called with one particular brand.
Input Parameters
o Brand Identifier - returned by "Find Accepted Payment Brand"
o Merchant Payment Identifier - Merchant's unique private
reference to the payment transaction
o Payment Direction
o Currency Code and Currency - from the Brand List Component's
Currency Amount Element
o Payment Amount - from the Brand List Component's Currency
Amount Element
o Payment Protocol Identifier - from the Brand List Component's
Pay Protocol Element
o Protocol Brand Identifier - from the Protocol Brand Element
which relates to the selected Brand Element, if any
o (TradingRoleData) Receiver Organization Identifier
o OkFrom, OkTo - identical to the entries of the Order Component
Merchant Payment Identifier
o Merchant Organisation Identifier - used for distinction between
multiple merchants that share the some IOTP merchant system
o Wallet Identifier and/or Pass Phrase
Protocol Brand Element
o (Brand) Packaged Content - further payment brand description,
from the Brand List Component's Brand Element
o (Protocol Amount) Packaged Content - further payment protocol
description, from the Brand List Component's Protocol Amount
Element
o (Pay Protocol) Packaged Content - further payment protocol
description, from the Brand List Component's Pay Protocol
Element
o (Protocol Brand) Packaged Content - further brand information,
from the Protocol Brand Element of the Brand List Component
which relates to the selected Brand Element, if any
o (Order) Packaged Content - further order description, from the
Order Element
o three Brand Selection Info Packaged Content elements - copied
from the Brand Selection Component on brand dependent purchases
o Brand - additional data about the payment brand
o Protocol Amount - additional data about the payment protocol
o Currency Amount - additional payment brand and currency
specific data
o Merchant Data - specific data used by the IOTP Payment Bridge
which is managed in the IOTP Application Core.
XML definition:
<!ELEMENT GetPaymentInitializationData (ProtocolBrand?
BrandPackagedContent*
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*,
OrderPackagedContent*,
BrandSelBrandInfoPackagedContent*,
BrandSelProtocolAmountInfoPackagedContent*,
BrandSelCurrencyAmountInfoPackagedContent*,
MerchantData*) >
<!ATTLIST GetPaymentInitializationData
BrandId CDATA #REQUIRED
MerchantPayId CDATA #REQUIRED
PayDirection (Debit|Credit) #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
ProtocolId CDATA #REQUIRED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
ReceiverOrgId CDATA #IMPLIED
MerchantOrgId CDATA #IMPLIED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o OkFrom, OkTo - for insertion in the Payment Component
o (TradingRoleData) Packaged Content - further payment protocol
description; the Name Attribute of the packaged Content
element must include "Payment:" as the prefix,
for example "Payment:SET-OD". For more information, see
[SET/IOTP].
o (Order) Packaged Content - defaults to the supplied order
packaged content if omitted.
XML definition:
<!ELEMENT GetPaymentInitializationDataResponse
(OrderPackagedContent*,
TradingRoleDataPackagedContent*) >
<!ATTLIST GetPaymentInitializationDataResponse
OkFrom CDATA #IMPLIED
OkTo CDATA #IMPLIED>
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.1.4. Inquire Authentication Challenge
This API function inquires any payment protocol specific
authentication challenge value from the IOTP Payment Bridge. In
Baseline IOTP this API function is called by the Merchant (or
Financial Institution). The IOTP Application Core may propose a
choice of algorithms to the IOTP Payment Bridge. However, the IOTP
Payment Bridge may ignore the proposal and select some other
algorithm.
The inquiry is assumed to be stateless. E.g., the IOTP Application
Core may check the returned algorithm and stop transaction processing
without notifying the IOTP Payment Bridge.
The IOTP Application Core may issue several API calls to the IOTP
Payment Bridge to build up the IOTP Authentication Request Block.
Any subsequently submitted choice of algorithms should be constrained
by the accepted algorithms from earlier API responses.
The IOTP Payment Bridge responds with the Business Error Code if it
does not provide any (more) authentication algorithms and challenges.
Input Parameters
o Authentication Identifier - the authenticator may provide its
payment identifier, i.e., Payment Handler or Merchant Payment
Identifier.
o Wallet Identifier and/or Pass Phrase
o set of pre-selected algorithms for authentication
XML definition:
<!ELEMENT InquireAuthChallenge (Algorithm*) >
<!ATTLIST InquireAuthChallenge
AuthenticationId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o list of Authentication Challenge Packaged Contents - for
insertion into the IOTP Authentication Request Component
o Algorithm Element - for insertion into the IOTP Authentication
Request Component
XML definition:
<!ELEMENT InquireAuthChallengeResponse (AuthReqPackagedContent*,
Algorithm) >
4.1.5. Authenticate
The Consumer's IOTP Application Core defers payment protocol specific
authentication processing and the current challenge value to the
active IOTP Payment Bridge. Alternative authentication algorithms
might be tried sequentially or offered to the user for selection.
Note that the IOTP Application Core has to consider both the current
context and the algorithm in order to determine the responsible IOTP
Payment Bridge.
Failed authentication is reported by the Business Error Code which
might trigger the inquiry of the details ("Inquire Process State").
Final failures might be encoded by the process state "Failed".
Input Parameters
o Authentication Identifier
o Wallet Identifier and/or Pass Phrase
o Authentication Challenge Packaged Content - copied from the
IOTP Authentication Request Component
o Algorithm Element - copied from the IOTP Authentication Request
Component
XML definition:
<!ELEMENT Authenticate (Algorithm, AuthReqPackagedContent*) >
<!ATTLIST Authenticate
AuthenticationId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o Authentication Response Packaged Content - for insertion into
the IOTP Authentication Response Component
XML definition:
<!ELEMENT AuthenticateResponse (AuthResPackagedContent*) >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.1.6. Check Authentication Response
This API function verifies the Consumer's payment protocol specific
authentication response. In Baseline IOTP this API function is
called by the Merchant (or the Financial Institution). It is called
only if the counter party has responded with an IOTP Authentication
Response Component within the Authentication Response Block. Of
course, the IOTP Application Core traces the need of such an
response.
Due to the authentication's statelessness, all parameters (algorithm,
challenge and response) are submitted to the IOTP Payment Bridge.
Authentication failure is reported by a Process State different from
"CompletedOK".
Input Parameters
o Authentication Identifier
o Wallet Identifier and/or Pass Phrase
o Authentication Challenge Packaged Content - generated by
previous "Inquire Authentication Challenge" API call
o Algorithm Element
o Authentication Response Packaged Content - copied from the
Authentication Response Component
XML definition:
<!ELEMENT CheckAuthResponse (Algorithm, AuthReqPackagedContent*,
AuthResPackagedContent*) >
<!ATTLIST CheckAuthResponse
AuthenticationId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o Current Process (Authentication) State
o Completion Code
o Status Description and its language annotation
XML definition:
<!ELEMENT CheckAuthResponseResponse EMPTY >
<!ATTLIST CheckAuthResponseResponse
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError)#REQUIRED
CompletionCode NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
StatusDesc CDATA #IMPLIED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.2. Brand Selection Related API Calls
4.2.1. Find Payment Instrument
This API function determines which instances of a Payment Brand, e.g., two Mondex cards, are present. The same physical card may even represent multiple payment instruments. The IOTP Application Core supplies possible payment brand and payment protocol to the IOTP Payment Bridge that has to be considered when the IOTP Payment Bridge searches for appropriate payment instruments. This set represents the (sub)set of payment alternatives being supported by the Merchant. If the IOTP Application Cote has multiple possible payment brand/protocol, it can call this function in turn. The Existing Payment Software responds with PayInstrument Elements with empty PayInstId attributes if it does not distinguish between different payment instruments for the particular payment alternatives. Note that the Payment API assumes that the values of the attributes BrandId, ProtocolId, ProtocolBrandId and the currency amount suffice for the determination of the appropriate Packaged Content Element that will be transmitted to the Payment Handler later on. Input Parameters o Brand Identifier - copied from the Brand List Component's Brand Element o Payment Protocol Identifier and associated Protocol Brand Identifier o Payment Direction - copied from the Brand List Component o Currency Code and Currency - copied from the Currency Amount Element o Payment Amount - copied from the Currency Amount Element o Consumer Payment Identifier - Consumer's unique reference to the current payment transaction o Wallet Identifier - managed by the IOTP Application Core o (Brand) Packaged Content - further payment brand description; copied from the Brand List Component's Brand Element o (Protocol Brand) Element - further information; copied from the Protocol Brand Element of the Brand List Component which relates to the Consumer selected Brand Element, if any. o (Protocol Amount) Packaged Content - further payment protocol description, copied from the Brand List Component's Protocol Amount Element
o Element (Protocol) Packaged Content - further payment protocol
description, copied from the Brand List Component's Pay
Protocol Element
XML definition:
<!ELEMENT FindPaymentInstrument (BrandPackagedContent*,
ProtocolBrand?,
PayProtocolPackagedContent*,
ProtocolAmountPackagedContent*) >
<!ATTLIST FindPaymentInstrument
BrandId CDATA #REQUIRED
ProtocolId CDATA #REQUIRED
PayDirection (Debit|Credit) #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
ConsumerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED >
Output Parameters
o The known Payment Instrument Identifiers, these are internal
values
o The user-defined names of the payment instrument and their
language encoding
The Existing Payment Software responds with an empty list of
identifiers, either if it does not distinguish between different
payment instruments or if there are no registered payment
instruments available despite brand support for at least one
(unspecified) payment protocol. In the latter case, the IOTP
Payment Bridge has to request the registration of a suitable
payment instrument at a subsequent step of the payment process.
XML definition:
<!ELEMENT FindPaymentInstrumentResponse (PayInstrument*) >
<!ELEMENT PayInstrument EMPTY >
<!ATTLIST PayInstrument
Id CDATA #REQUIRED
xml:lang NMTOKEN #IMPLIED
PayInstName CDATA #REQUIRED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.2.2. Check Payment Possibility
This API function checks whether a payment (both debit and credit) can go ahead. It can be used, for example, to check o if there are sufficient funds available in a particular currency for an electronic cash payment brand, o whether there is sufficient value space left on the payment instrument for payment refund, o whether required system resources are available and properly configured, e.g., serial ports or baud rate, o whether environment requirements are fulfilled, e.g., chip card reader presence or Internet connection. If the payment method is based on external components, e.g., magnetic stripe or chip cards, and the check accesses the medium, the existing payment method should not mutually exclusive lock system resources, e.g., serial port or modem, that may also be required by other Existing Payment Software, e.g., multiple payment software components may share the same card reader. If this happens for API internal request processing, the function has to unlock these components prior to return. Otherwise, the payment may not proceed if the Consumer cancels immediately and decides to use another payment instrument. In this event the previous IOTP Payment Bridge is not notified about the change. This function call happens immediately after the Consumer's payment instrument selection. For example, if the payment instrument is a chip card, that is not inserted in the chip card reader, the Consumer may be prompted for its insertion. However, the Consumer should be able to hit some 'skip' button, if the payment check is part of the actual payment protocol, too. Finally, the IOTP Payment Bridge may provide only a subset of these capabilities or may even directly generate a successful response without any checks. Input Parameters o Brand Identifier - user selection o Payment Instrument Identifier - user selection o Currency Code and Currency Code Type - copied from the selected Currency Amount Element o Payment Amount - copied from the selected Currency Amount Element o Payment Direction - copied from the selected Trading Protocol Option Block o Protocol Identifier - copied from the selected Pay Protocol Element
o Protocol Brand Identifier - copied from the selected Protocol
Brand Element of the Brand List Component which relates to the
selected Brand Element, if any
o Consumer Payment Identifier - Consumer's unique reference to the
current payment transaction
o Wallet Identifier and/or Pass Phrase
o (Brand) Packaged Content - copied from the selected Brand Element
o (Protocol Amount) Packaged Content - copied from the selected
Protocol Amount Element
o (Protocol) Packaged Content - copied from the selected Pay
Protocol Element
o (Protocol Brand) Packaged Content - copied from the selected
Protocol Brand Element of the Brand List Component which relates
to the selected Brand Element, if any
XML definition:
<!ELEMENT CheckPaymentPossibility (BrandPackagedContent*,
ProtocolBrand?
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*>
<!ATTLIST CheckPaymentPossibility
BrandId CDATA #REQUIRED
PaymentInstrumentId CDATA #IMPLIED
PayDirection (Debit|Credit) #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
ProtocolId CDATA #REQUIRED
ConsumerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o three Brand Selection Info Packaged Content elements - for
insertion into the Brand Selection component
o Brand - additional data about the payment brand
o Protocol Amount - additional data about the payment protocol
o Currency Amount - additional payment brand and currency specific
data
XML definition:
<!ELEMENT CheckPaymentPossibilityResponse
(BrandSelBrandInfoPackagedContent*,
BrandSelProtocolAmountInfoPackagedContent*,
BrandSelCurrencyAmountInfoPackagedContent*) >
<!ATTLIST CheckPaymentPossibilityResponse >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.3. Payment Transaction Related API calls
These Payment API calls may be made either by the Consumer's or
Payment Handler's IOTP Application Core.
4.3.1. Start Payment Consumer
This API function initiates the actual payment transaction at the
Consumer side. The IOTP Payment Bridge and the Existing Payment
Software perform all necessary initialization and preparation for
payment transaction processing. This includes the reservation of
external periphery. E.g., 1) the Consumer's chip card reader needs
to be protected against access from other software components, 2) the
insertion of the chip card may be requested, 3) the Internet
connection may be re-established, or 4) the Payment Handler may open
a mutual exclusive session to the security hardware.
The IOTP Payment Bridge monitors the payment progress and stores the
current payment states such that resumption - even after power
failures - remains possible. Note that the IOTP Application Core
supplies only a subset of the following input parameter to the
associated resumption API function and refers to the payment
transaction through the party's payment identifier.
Input Parameters
o Brand Identifier - copied from the selected Brand Element
o Payment Instrument Identifier - the user selection
o Currency Code and Currency - copied from the selected Currency
Amount Element
o Payment Amount - copied from the selected Currency Amount
Element
o Payment Direction - copied from the Brand List Component
o Protocol Identifier - copied from the selected Payment Protocol
Element
o Protocol Brand Element - further information; copied from the
Protocol Brand Element of the Brand List Component which
relates to the selected Brand Element, if any
o OkFrom, OkTo - copied from the Payment Component
o Consumer Payment Identifier - Consumer's unique reference to
the current payment transaction
o Wallet Identifier and/or Pass Phrase
o Call Back Function - used for end user notification/logging
purposes
o Call Back Language List. This list is required if the Call Back
Function is set
o (Brand) Packaged Content - further payment brand description;
copied from the selected Brand Element's content
o (Protocol Amount) Packaged Content - further payment protocol
description; copied from the selected Protocol Amount Element's
content
o (Payment Protocol) Packaged Content - further payment protocol
description; copied from the selected Pay Protocol Element's
content
o (Order) Packaged Content - further order description, copied
from the Order Component
XML definition:
<!ELEMENT StartPaymentConsumer (BrandPackagedContent*,
ProtocolBrand?
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*,
OrderPackagedContent*) >
<!ATTLIST StartPaymentConsumer
BrandId CDATA #REQUIRED
PaymentInstrumentId CDATA #IMPLIED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
PayDirection (Debit|Credit) #REQUIRED
ProtocolId CDATA #REQUIRED
ProtocolBrandId CDATA #IMPLIED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
ConsumerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED
CallBackFunction CDATA #IMPLIED
CallBackLanguageList NMTOKENS #IMPLIED >
Output Parameters
o Continuation Status
o (Payment Scheme) Packaged Content - for insertion into the
Payment Scheme Component of the IOTP Payment Request Block
The IOTP Application Core is allowed to reissue this request several
times on failed analyses of the response.
XML definition:
<!ELEMENT StartPaymentConsumerResponse
(PaySchemePackagedContent*) >
<!ATTLIST StartPaymentConsumerResponse
ContStatus (End|Continue) #REQUIRED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.3.2. Start Payment Payment Handler
This API function initializes the Consumer initiated payment
transaction at the Payment Handler's side. Similar to the Consumer's
system, the IOTP Payment Bridge and the Existing Payment Software
perform all necessary initialization and preparation for payment
transaction processing.
Input Parameters
o Brand Identifier - copied from the Consumer selected Brand
Element
o Consumer Payment Identifier - copied from the Payment Scheme
Component
o Currency Code and Currency - copied from the Consumer selected
Currency Amount Element
o Payment Amount - copied from the Consumer selected Currency
Amount Element
o Payment Direction - copied from the Brand List Component
o Protocol Identifier - copied from the Consumer selected
Payment Protocol Element
o Protocol Brand Identifier - copied from the Brand Protocol
Element of the Brand List Component which relates to the
Consumer selected Brand Element, if any
o OkFrom, OkTo - copied from the Payment Component
o Payment Handler Payment Identifier - Payment Handler's unique
reference to the current payment transaction
o Merchant Organisation Identifier - copied from the Merchant's
Organisation Element
o Wallet Identifier - renaming to till identifier neglected -
and/or Pass Phrase
o Call Back Function - used for end user notification/logging
purposes
o Call Back Language List. This list is required if the call
back function is set
o (Brand) Packaged Content - further payment brand description;
copied from the Consumer selected Brand Element's content
o (Protocol Brand) Packaged Content - further information; copied
from the Protocol Brand Element of the Brand List Component
which relates to the Consumer selected Brand Element, if any.
o (Protocol Amount) Packaged Content - further payment protocol
description; copied from the Consumer selected Protocol Amount
Element's content
o (Protocol) Packaged Content - further payment protocol
description; copied from the Consumer selected Pay Protocol
Element's content
o (TradingRoleData) Packaged Content - further payment protocol
description; the Name Attribute of the packaged contents must
include "Payment:" as the prefix, for example "Payment:SET-OD".
For more information, see [SET/IOTP].
o Three Brand Selection Info Packaged Content Elements - copied
from the Brand Selection Component
o Brand - additional data about the payment brand
o Protocol Amount - additional data about the payment protocol
o Currency Amount - additional payment brand and currency
specific data
o (Payment Scheme) Packaged Content.
XML definition:
<!ELEMENT StartPaymentPaymentHandler (BrandPackagedContent*,
ProtocolBrand?,
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*,
BrandSelBrandInfoPackagedContent*,
BrandSelProtocolAmountInfoPackagedContent*,
BrandSelCurrencyAmountInfoPackagedContent*,
TradingRoleDataPackagedContent*,
PaySchemePackagedContent*) >
<!ATTLIST StartPaymentPaymentHandler
BrandId CDATA #REQUIRED
ConsumerPayId CDATA #IMPLIED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
PayDirection (Debit|Credit) #REQUIRED
ProtocolId CDATA #REQUIRED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
PaymentHandlerPayId CDATA #REQUIRED
MerchantOrgId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED
CallBackFunction CDATA #IMPLIED
CallBackLanguageList NMTOKENS #IMPLIED >
Output Parameters
o Continuation Status
o (Payment Scheme) Packaged Content - for insertion into the
Payment Scheme Component of the IOTP Payment Exchange Block
The response message must contain payment schema data if the
continuation status signals "Continue". The IOTP Application Core is
allowed to reissue this request several times on failed analyses of
the response.
XML definition:
<!ELEMENT StartPaymentPaymentHandlerResponse
(PaySchemePackagedContent*) >
<!ATTLIST StartPaymentPaymentHandlerResponse
ContStatus (End|Continue) #REQUIRED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.3.3. Resume Payment Consumer
This API function resumes a previously suspended payment at the
Consumer side. Resumption includes the internal inquiry of the
payment transaction data, e.g., payment amount, protocol identifier,
and the whole initialization as it has been applied on the "Start
Payment Consumer" API request.
It is up to the IOTP Application Core to decide whether an IOTP
Payment Request Block or a IOTP Payment Exchange Block needs to be
generated. One indicator might be the receipt of a previous IOTP
Payment Exchange Block from the Payment Handler, e.g., the knowledge
of the Payment Handler Payment Identifier.
Input Parameters
o Consumer Payment Identifier
o Wallet Identifier and/or Pass Phrase
o Call Back Function - used for end user notification/logging
purposes
XML definition:
<!ELEMENT ResumePaymentConsumer EMPTY >
<!ATTLIST ResumePaymentConsumer
ConsumerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED
CallBackFunction CDATA #IMPLIED
CallBackLanguageList NMTOKENS #IMPLIED >
Output Parameters
o Continuation Status
o (Payment Scheme) Packaged Content - for insertion in the
Payment Scheme Component of the next IOTP message (Payment
Exchange or Request Block).
The IOTP Application Core is allowed to reissue this request several
times on failed analyses of the response. However, the IOTP Payment
Bridge might reject the resumption request by using the "AttNotSupp"
Error Code "naming" the Consumer Payment Identifier attribute. Then
the Consumer has to apply normal error processing to the current
(sub-)transaction and to issue a new Payment Request Block to the
Payment Handler.
XML definition:
<!ELEMENT ResumePaymentConsumerResponse
(PaySchemePackagedContent*) >
<!ATTLIST ResumePaymentConsumerResponse
ContStatus (End|Continue) #REQUIRED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.3.4. Resume Payment Payment Handler
This API function resumes a payment at the Payment Handler side.
Input Parameters
o Payment Handler Payment Identifier
o Wallet Identifier - renaming to till identifier neglected - and
Pass Phrase
o Call Back Function - used for end user notification/logging
purposes
o Call Back Language List. This list is required if the Call Back
Function is set
o (Payment Scheme) Packaged Content - copied from the Payment
Scheme Component of the received IOTP message (Payment Exchange
or Request Block).
XML definition:
<!ELEMENT ResumePaymentPaymentHandler
(PaySchemePackagedContent*) >
<!ATTLIST ResumePaymentPaymentHandler
PaymentHandlerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED
CallBackFunction CDATA #IMPLIED
CallBackLanguageList NMTOKENS #IMPLIED >
Output Parameters
o Continuation Status
o (Payment Scheme) Packaged Content - for insertion in the
Payment Scheme Component of the next Payment Exchange Block.
The response message contains payment schema specific data if the
continuation status signals "Continue". The IOTP Application Core is
allowed to reissue this request several times on failed analyses of
the response.
XML definition:
<!ELEMENT ResumePaymentPaymentHandlerResponse
(PaySchemePackagedContent*) >
<!ATTLIST ResumePaymentPaymentHandlerResponse
ContStatus (End|Continue) #REQUIRED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.3.5. Continue Process
This API function passes one specific IOTP Payment Scheme Component,
i.e., the encapsulated Packaged Content elements, received from the
counter party (e.g., Consumer) to the IOTP Payment Bridge and
responds with the next IOTP Payment Scheme Component for submission
to the counter party.
Input Parameters
o Payty's Payment Identifier
o Process (Transaction) Type which distinguishes between Payments
and Inquiries.
o Wallet Identifier and/or Pass Phrase
o (Payment Scheme) Packaged Content - copied from the Payment
Scheme Component of the received Payment Exchange Block or from
the Error Block.
Each party should set the payment identifier with the local
identifier (Consumer: ConsumerPayId; Merchant: MerchantPayId; Payment
Handler: PaymentHandlerPayId).
XML definition:
<!ELEMENT ContinueProcess (PaySchemePackagedContent+) >
<!ATTLIST ContinueProcess
PayId CDATA #REQUIRED
ProcessType (Payment | Inquiry) 'Payment'
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o Continuation Status
o (Payment Scheme) Packaged Content - for insertion in the
Payment Scheme Component of the next Payment Exchange Block or
final Payment Response Block
The response message contains payment schema data if the continuation
status signals "Continue". The IOTP Payment Bridge must signal
"End", if the payment scheme data was received within an IOTP Error
Block containing an Error Component with severity HardError.
XML definition:
<!ELEMENT ContinueProcessResponse (PaySchemePackagedContent*) >
<!ATTLIST ContinueProcessResponse
ContStatus (End|Continue) #REQUIRED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.3.6. Change Process State
The IOTP Application Core changes the current payment status by this request. The IOTP Payment Bridge may be notified about business level normal termination, cancellation, suspension, and processing errors. Notification happens by requesting the intended process state. The IOTP Payment Bridge processes the status change and reports the result. The IOTP Application Core has to analyze any returned process status in order to check whether the IOTP Payment Bridge has agreed to or declined the status switch. E.g., the submitted Process State "CompleteOk" may lead to the Payment Status "Failed" if the payment transaction has already failed. Transaction Suspension is notified by the newly introduced Process State "Suspended". The other attribute values have been taken from the IOTP specification. This API function might be called by the Consumer, Merchant, or Payment Handler for each payment transaction anytime after the issuance of "FindPaymentInstrument" to the IOTP Payment Bridge by the Consumer, the issuance of "FindAcceptedPaymentBrand" by the Merchant, or the issuance of "StartPaymentPaymentHandler" by the Payment Handler. The Process States "CompletedOk", "Failed", and "ProcessError" are final in the sense that they can not be changed on subsequent calls. However, the API function should not return with an error code if such an incompatible call has been issued. Instead it should report the old unchanged Process State. Unknown payment transactions are reported by the Error Code "AttValInvalid" pointing to the PayId attribute. Input Parameters o Party's Payment Identifier o intended Payment Status o intended Completion Code o Process (Transaction) Type which distinguishes between Payments and Inquiries. o Wallet Identifier and/or Pass Phrase
XML definition:
<!ELEMENT ChangeProcessState EMPTY >
<!ATTLIST ChangeProcessState
PayId CDATA #REQUIRED
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError) #REQUIRED
CompletionCode NMTOKEN #IMPLIED
ProcessType (Payment | Inquiry) 'Payment'
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o Process State and Percent Complete
o Completion Code
o Status Description and its language annotation
XML definition:
<!ELEMENT ChangeProcessStateResponse EMPTY >
<!ATTLIST ChangeProcessStateResponse
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError) #REQUIRED
PercentComplete CDATA #IMPLIED
CompletionCode NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
StatusDesc CDATA #IMPLIED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.4. General Inquiry API Calls
The following calls are not necessarily assigned to a payment
transaction and may be issued at any time. There are no dependencies
on any other calls.
4.4.1. Remove Payment Log
The IOTP Application Core notifies the IOTP Payment Bridge and/or the corresponding Existing Payment Software via IOTP Payment Bridge that any record in the Payment Log file, that deals with the listed payment transaction, might be removed. Input Parameters o Party's Payment Identifier o Wallet Identifier and/or Pass Phrase XML definition: <!ELEMENT RemovePaymentLog EMPTY > <!ATTLIST RemovePaymentLog PayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters XML definition: <!ELEMENT RemovePaymentLogResponse EMPTY > <!ATTLIST RemovePaymentLogResponse > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.4.2. Payment Instrument Inquiry
This API function retrieves the properties of the Payment Instrument. The Payment Instrument Identifier could be omitted if this identifier is derived by other means, e.g., by analysis of the currently inserted chip card. If the Payment instrument could not uniquely determined, the IOTP Payment Bridge may provide suitable dialogs for user input. E.g., this API function might be used during problem resolution with the Customer Care Provider of the issuer of the payment instrument, in order to inquire payment instrument specific values. Input parameters o Brand Identifier o Payment Instrument Identifier o Protocol Identifier
o Wallet Identifier and/or Pass Phrase
o Property Type List - sequence of values whose language is
identified by xml:lang
o (Brand) PackagedContent Content - further payment brand
description
o Protocol Brand Content - further payment brand information
o (Protocol Amount) PackagedContent Content - further payment
protocol description
o (Pay Protocol) PackagedContent Content - further payment
protocol description
The codes in the property type list are of two types:
o generic codes which apply to all payment methods but might be
unavailable
o Payment Brand specific codes.
Generic codes for the Property Type List are:
Property Type Meaning
Balance Current balance
Limit Maximum balance
PaymentLimit Maximum payment transaction limit
Expiration Expiration date
Identifier Issuer assigned identifier of the payment
instrument. Usually, it does not match with
the API's payment instrument identifier.
LogEntries Number of stored payment transaction
entries. The entries are numbered from 0
(the most recent) to some non-negative
value for the oldest entry.
PayAmountn Payment Amount of the n-th recorded payment
transaction, n may negative
PayPartyn Remote party of the n-th payment recorded
transaction, n may negative
PayTimen Time of the n-th payment recorded
transaction, n may negative
XML definition:
<!ELEMENT PaymentInstrumentInquiry (BrandPackagedContent*,
ProtocolBrand?,
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*) >
<!ATTLIST PaymentInstrumentInquiry
BrandId CDATA #REQUIRED
PaymentInstrumentId CDATA #IMPLIED
ProtocolId CDATA #REQUIRED
PropertyTypeList NMTOKENS #REQUIRED
xml:lang NMTOKEN #IMPLIED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output parameters
o a list of zero or more unavailable property values whose
language are identified by xml:lang.
o a list of zero or more sets of "Properties Types", "Property
Values" and "Property Descriptions"
XML definition:
<!ELEMENT PaymentInstrumentInquiryResponse
(PaymentInstrumentProperty*) >
<!ATTLIST PaymentInstrumentInquiryResponse
xml:lang NMTOKEN #REQUIRED
UnavailablePropertyList NMTOKENS #IMPLIED >
<!ELEMENT PaymentInstrumentProperty EMPTY >
<!ATTLIST PaymentInstrumentProperty
PropertyType NMTOKEN #REQUIRED
PropertyValue CDATA #REQUIRED
PropertyDesc CDATA #REQUIRED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.4.3. Inquire Pending Payment
This API function reports the party's payment identifiers of any
pending payment transactions that the IOTP Payment Bridge/Existing
Payment Software recommends be completed or suspended prior to the
processing of new payment transactions. It does not respond with
further transaction details. These have to be requested with
"Inquire Process State".
Note that the IOTP Payment Bridge has to respond without the benefit
of any pass phrase if there exist no pending payment transaction.
But if there are some pending payment transactions, the IOTP Payment
Bridge may refuse the immediate response and may instead request the
appropriate pass phase from the IOTP Application Core.
Input Parameters
o Wallet Identifier and/or Passphrase
XML definition:
<!ELEMENT InquirePendingPayment EMPTY >
<!ATTLIST InquirePendingPayment
WalletId CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o Party's Payment Identifier
XML definition:
<!ELEMENT InquirePendingPaymentResponse (PaymentId*) >
<!ELEMENT PaymentId EMPTY >
<!ATTLIST PaymentId
PayId CDATA #REQUIRED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.5. Payment Related Inquiry API Calls
4.5.1. Check Payment Receipt
This function is used by the Consumer and might be used by the
Payment Handler to check the consistency, validity, and integrity of
IOTP payment receipts which might consist of Packaged Content
Elements
o from the IOTP Payment Receipt Component - provided by the Payment
Handler's "Inquire Process State" API call shortly before payment
completion,
o from Payment Scheme Components being exchanged during the actual
payment, or
o being returned by the Consumer's "Inquire Process State" API call
shortly before payment completion
The IOTP Application Core has to check the PayReceiptNameRefs
attribute of the IOTP Payment Receipt Component and to supply exactly
the Packaged Content Elements being referred to.
Failed verification is returns a business error.
Note that this Payment API assumes that any payment receipt builds upon a subset of elements with reference to [IOTP]. Furthermore, the Packaged Content Element have to be distinguishable by their Name attribute. Input Parameters o Party's Payment Identifier o Wallet Identifier and/or Pass Phrase o All Packaged Content Elements in the payment receipt XML definition: <!ELEMENT CheckPaymentReceipt (PackagedContent*) > <!ATTLIST CheckPaymentReceipt PayId CDATA #REQUIRED WalletID CDATA #IMPLIED Passphrase CDATA #IMPLIED > Output Parameters XML definition: <!ELEMENT CheckPaymentReceiptResponse EMPTY > <!ATTLIST CheckPaymentReceiptResponse > Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.4.5.2. Expand Payment Receipt
This API function expands any IOTP payment receipt into a form which may be used for display or printing purposes. "Check Payment Receipt" should be used first if there is any question of the payment receipt containing errors. The same conventions apply to the input parameter as for "Check Payment Receipt" (cf. Section 4.5.1). Input Parameters o Party's Payment Identifier o Wallet Identifier and/or Pass Phrase o All Packaged Content Elements that build the payment receipt
XML definition:
<!ELEMENT ExpandPaymentReceipt (PackagedContent*) >
<!ATTLIST ExpandPaymentReceipt
PayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o Brand Identifier
o Protocol specific Brand Identifier
o Payment Instrument Identifier
o Currency Code and Currency Code Type
o Payment Amount
o Payment Direction
o Time Stamp - issuance of the receipt
o Protocol Identifier
o Protocol specific Transaction Identifier - this is an internal
reference number which identifies the payment
o Consumer Description, Payment Handler Description, and a
language annotation
o Style Sheet Net Location
o Payment Property List. A list of type/value/description triples
which contains additional information about the payment which
is not covered by any of the other output parameters; property
descriptions have to consider the language annotation.
The Style Sheet Net Location refers to a Style Sheet (e.g., [XSLT])
that contains presentation information about the reported XML encoded
data.
XML definition:
<!ELEMENT ExpandPaymentReceiptResponse (PaymentProperty*) >
<!ATTLIST ExpandPaymentReceiptResponse
BrandId CDATA #IMPLIED
PaymentInstrumentId CDATA #IMPLIED
Amount CDATA #IMPLIED
CurrCodeType NMTOKEN #IMPLIED
CurrCode CDATA #IMPLIED
PayDirection (Debit|Credit) #IMPLIED
TimeStamp CDATA #IMPLIED
ProtocolId CDATA #IMPLIED
ProtocolBrandId CDATA #IMPLIED
ProtocolTransId CDATA #IMPLIED
xml:lang NMTOKEN #IMPLIED
ConsumerDesc CDATA #IMPLIED
PaymentHandlerDesc CDATA #IMPLIED
StyleSheetNetLocn CDATA #IMPLIED>
<!ELEMENT PaymentProperty EMPTY >
<!ATTLIST PaymentProperty
PropertyType NMTOKEN #REQUIRED
PropertyValue CDATA #REQUIRED
PropertyDesc CDATA #REQUIRED >
The Existing Payment Software should return as many attributes as
possible from the supplied IOTP Payment Receipt. The payment
supplement defines the attribute values for the payment properties.
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.5.3. Inquire Process State
This API function returns the current payment state and optionally
further Packaged Content Elements that form the payment receipt.
Called by the Payment Handler, the IOTP Payment Bridge might respond
with data intended for inclusion in the IOTP Payment Receipt
Component's Packaged Content. When the Consumer calls this function
shortly before payment completion, it may respond with further items
of the payment receipt. Such items might be created by a chip card.
Input Parameters
o Party's Payment Identifier
o Wallet Identifier and/or Pass Phrase
XML definition:
<!ELEMENT InquireProcessState EMPTY >
<!ATTLIST InquireProcessState
PayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o Current Process State and Percent Complete
o Completion Code
o Status Description and its language annotation
o Payment Receipt Name References to all Packaged Content
Elements that build the payment receipt (cf. Section 4.5.1),
even if they have not been created so far (Consumer's share)
o Any Packaged Content Element being available that form the
payment receipt
The IOTP provides a linking capability to the payment receipt
delivery. Instead of encapsulating the whole payment specific data
into the packaged content of the payment receipt, other Payment
Scheme Components' Packaged Content might be referred to.
XML definition:
<!ELEMENT InquireProcessStateResponse
(PackagedContent*) >
<!ATTLIST InquireProcessStateResponse
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError) #REQUIRED
PercentComplete CDATA #IMPLIED
CompletionCode NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
StatusDesc CDATA #IMPLIED
PayReceiptNameRefs NMTOKENS #IMPLIED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.5.4. Start Payment Inquiry
This API function responds with any additional payment scheme
specific data that is needed by the Payment Handler for Consumer
initiated payment transaction inquiry processing. Probably, the IOTP
Payment Bridge (or the corresponding Existing Payment Software) has
to determine the payment related items that were provided with the
"Start Payment Consumer" API function call.
Input Parameters
o Consumer Payment Identifier
o Wallet Identifier and/or Pass Phrase
XML definition:
<!ELEMENT StartPaymentInquiry EMPTY >
<!ATTLIST StartPaymentInquiry
ConsumerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o (Payment Scheme) Packaged Content - intended for insertion in
the Payment Scheme Component of the Inquiry Request Block
XML definition:
<!ELEMENT StartPaymentInquiryResponse
(PaySchemePackagedContent*) >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.5.5. Inquire Payment Status
The Payment Handler calls this API function for Consumer initiated
inquiry processing. It differs from the previous "Inquire Process
State" API function by the optional inclusion of payment scheme
specific data. The response may encapsulate further details about
the payment transaction.
Input Parameters
o Payment Handler Payment Identifier
o Wallet Identifier and/or Pass Phrase
o (Payment Scheme) Packaged Content - copied from the Inquiry
Request Block's Payment Scheme Component
XML definition:
<!ELEMENT InquirePaymentStatus (PaySchemePackagedContent*) >
<!ATTLIST InquirePaymentStatus
PaymentHandlerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o Current Process State
o Completion Code
o Status Description and its language annotation
o (Payment Scheme) Packaged Content - intended for insertion in
the Payment Scheme Component of the Inquiry Response Block
XML definition:
<!ELEMENT InquirePaymentStatusResponse
(PaySchemePackagedContent*) >
<!ATTLIST InquirePaymentStatusResponse
PaymentHandlerPayId CDATA #REQUIRED
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError) #REQUIRED
CompletionCode NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
StatusDesc CDATA #IMPLIED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
4.6. Other API Calls
4.6.1. Manage Payment Software
The following API function notifies the IOTP Payment Bridge about the
intended registration, modification, or deletion of a payment
instrument. The actual processing is up to the IOTP Payment Bridge.
This API request may also be used to activate the IOTP Payment Bridge
(and the corresponding Existing Payment Software) for general
administration purposes.
Input Parameters
o Brand Identifier
o Protocol Identifier
o Any action code:
o New - add new payment method / instrument
o Update - change the payment method's / instrument's data
o Delete - delete a payment method / instrument
o Wallet Identifier and/or Pass Phrase
o (Brand) Packaged Content - further payment brand description
o (Pay Protocol) Packaged Content - further payment protocol
description
o (Protocol Amount) Packaged Content - further payment protocol
description
If the Action attribute is set, the Brand and Protocol Identifier
have to also be set. The IOTP Payment Bridge has to provide the
required user dialogs and selection mechanisms. E.g., updates and
deletions may require the selection of the payment instrument. A new
wallet might be silently generated on the supplement of a new Wallet
Identifier or after an additional end user acknowledge. The IOTP
Application Core should not provide any pass phrases for new wallets.
Instead, the IOTP Payment Bridge has to request and verify them,
which may return their value to the IOTP Application Core in plain
text. In addition, the IOTP Payment Bridge returns the supported
authentication algorithms when a new brand and protocol pair has been
registered.
If the "Action" attribute is omitted, the IOTP Payment Bridge which
is responsible for the Existing Payment Software pops up in a general
interactive mode.
XML definition:
<!ELEMENT ManagePaymentSoftware (BrandPackagedContent*,
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*) >
<!ATTLIST ManagePaymentSoftware
BrandId CDATA #IMPLIED
ProtocolId CDATA #IMPLIED
Action (New |
Update |
Delete) #IMPLIED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >
Output Parameters
o An action code:
o New - added new wallet
o Update - changed wallet's configuration
o Delete - removed a wallet
o Wallet Identifier and/or Pass Phrase
The IOTP Payment Bridge does not return any information about the set
of registered payment instruments because these data items are
dynamically inferred during the brand selection process at the
beginning of each IOTP transaction. However, the IOTP Application
Core has to be notified about new wallets and should be notified
about updated and removed wallets (identifier). Alternatively,
removed wallets can be implicitly detected during the next brand
selection phase. Updated wallets do no affect the processing of the
IOTP Application Core. The IOTP Payment Bridge should only support
the addition of at most one wallet because it is not able to report
multiple additions at once back to the IOTP Application Core.
XML definition:
<!ELEMENT ManagePaymentSoftwareResponse EMPTY >
<!ATTLIST ManagePaymentSoftwareResponse
Action (New |
Update |
Delete) #IMPLIED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED
AuthNames NMTOKENS #REQUIRED >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
5. Call Back Function
This API function, called by the IOTP Payment Bridge, is used to
provide information for Consumer or Payment Handler notification
about the progress of the payment transaction.
Its use is illustrated in the diagram below.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
IOTP Application ----calls----
| Core | |
display | | v
to <---------- Call Back <--calls--- Payment
user | | Software
----------------
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Figure 9. Call Back Function
Whenever this function is called, the content of the status
description should be made available to the user. For example on a
status bar, a pop up window, etc.
A reference to the Call Back function is passed as an input parameter
to the "Start Payment X" and "Resume Payment X" API function.
Afterwards, this function might be called whenever the status changes
or progress needs to be reported.
Input Parameters
o the software identifier of the caller
o Party's Payment Identifier
o Process State and Percent Complete
o Completion Code
o Status Description and its language annotation, text which
provides information about the progress of the call. It should be
displayed or made available to, for example, the Consumer.
Examples of Status Description could be:
o "Paying 12.30 USD to XYZ Inc"
o "Payment completed"
o "Payment aborted"
The valid languages are announced in the Call Back Language List
attribute in "Start Payment X" and "Resume Payment X" API function
calls.
XML definition:
<!ELEMENT CallBack EMPTY >
<!ATTLIST CallBack
ContentSoftwareID CDATA #IMPLIED
PayId CDATA #REQUIRED
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError) #IMPLIED
PercentComplete CDATA #IMPLIED
CompletionCode NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
StatusDesc CDATA #IMPLIED >
Output Parameters
XML definition:
<!ELEMENT CallBackResponse EMPTY >
<!ATTLIST CallBackResponse <!-- see below --> >
Tables 4 and 5 explain the attributes and elements; Table 3
introduces the Error Codes.
Basically, the call back function accepts all input arguments or rejects the whole request. It may even accept malformed requests. Some payment schemes may support or require that the Consumer might be able to cancel the payment at any time. The Call Back function can be used to facilitate this by returning the cancellation request on the next call (using the Business Error Code and Completion Code "ConsCancelled"). Vice versa the Payment Handler's Application Core might use the similar mechanism to signal its IOTP Payment Bridges any exceptional need for a fast shutdown. These IOTP Payment Bridges may initiate the appropriate steps for terminating/cancelling all pending payment transactions. Note that the "Change Process State" API function provides the second mechanism for such kind of notification. Therefore, the IOTP Payment Bridge or Existing Payment Software may ignore the details of the "Call Back" response.6. Security Consideration
The IOTP Payment APIs only supports security using pass phrase to access to payment Wallet. These can be protected over TLS, which provides stronger security at the transport layer, but implementations are out the scope of this document. See also security consideration section of [IOTP].7. References
7.1. Normative References
[IOTP] Burdett, D., "Internet Open Trading Protocol - IOTP version 1.0", RFC 2801, April 2000. [ISO4217] ISO 4217: Codes for the Representation of Currencies. Available from ANSI or ISO. [URL] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, December 1994. [UTC] Universal Time Coordinated. A method of defining time absolutely relative to Greenwich Mean Time (GMT). Typically of the form: "CCYY-MM- DDTHH:MM:SS.sssZ+n" where the "+n" defines the number of hours from GMT. See ISO DIS8601.
[XML] Extensible Mark Up Language (XML) 1.0 (Third Edition). A W3C recommendation. See http://www.w3.org/TR/REC-xml [XML-NS] Namespaces in XML Recommendation. T. Bray, D. Hollander, A. Layman. Janaury 1999. http://www.w3.org/TR/REC-xml- names [XSLT] Extensible Style Language Transformations 1.0, November 1999, See http://www.w3.org/TR/xslt7.2. Informative References
[IOTPBOOK] D. Burdett, D.E. Eastlake III, and M. Goncalves, Internet Open Trading Protocol, McGraw-Hill, 2000. ISBN 0-07- 135501-4. [SET] SET Secure Electronic Transaction(TM) , Version 1.0, May 31, 1997 Book 1: Business Description Book 2: Programmer's Guide Book 3: Formal Protocol Definition [SET/IOTP] Kawatsura, Y., "Secure Electronic Transaction (SET) Supplement for the v1.0 Internet Open Trading Protocol (IOTP)", RFC 3538, June 2003. [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999.
Acknowledgement
The contributions of Werner Hans of Atos Origin are gratefully acknowledged.Authors' Addresses
Hans-Bernhard Beykirch EMail: hbbeykirch@web.de Yoshiaki Kawatsura Hitachi, Ltd. 890 Kashimada Saiwai-ku Kawasaki-shi Kanagawa, Japan 212-8567 EMail: ykawatsu@itg.hitachi.co.jp Masaaki Hiroya Technoinfo Service, Inc. 333-2-718 Uchikoshi-machi Hachioji-shi Tokyo 192-0911 JAPAN EMail: hiroya@st.rim.or.jp
Full Copyright Statement Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf- ipr@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society.