tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search

RFC 3867

 
 
 

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

Part 4 of 4, p. 66 to 106
Prev RFC Part

 


prevText      Top      Up      ToC       Page 66 
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.

Top      Up      ToC       Page 67 
   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.

Top      Up      ToC       Page 68 
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 >

Top      Up      ToC       Page 69 
   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 >

Top      Up      ToC       Page 70 
   <!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

Top      Up      ToC       Page 71 
   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 >

Top      Up      ToC       Page 72 
   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.

Top      Up      ToC       Page 73 
   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".

Top      Up      ToC       Page 74 
   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".

Top      Up      ToC       Page 75 
   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.

Top      Up      ToC       Page 76 
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

Top      Up      ToC       Page 77 
   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.

Top      Up      ToC       Page 78 
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

Top      Up      ToC       Page 79 
   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

Top      Up      ToC       Page 80 
   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

Top      Up      ToC       Page 81 
   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 >

Top      Up      ToC       Page 82 
   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

Top      Up      ToC       Page 83 
   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

Top      Up      ToC       Page 84 
     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

Top      Up      ToC       Page 85 
   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

Top      Up      ToC       Page 86 
   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.

Top      Up      ToC       Page 87 
   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.

Top      Up      ToC       Page 88 
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

Top      Up      ToC       Page 89 
   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.

Top      Up      ToC       Page 90 
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

Top      Up      ToC       Page 91 
   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

Top      Up      ToC       Page 92 
     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

Top      Up      ToC       Page 93 
   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.

Top      Up      ToC       Page 94 
   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

Top      Up      ToC       Page 95 
   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

Top      Up      ToC       Page 96 
     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)

Top      Up      ToC       Page 97 
   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

Top      Up      ToC       Page 98 
   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

Top      Up      ToC       Page 99 
   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

Top      Up      ToC       Page 100 
   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,

Top      Up      ToC       Page 101 
   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.

Top      Up      ToC       Page 102 
   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.

Top      Up      ToC       Page 103 
   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.

Top      Up      ToC       Page 104 
   [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/xslt

7.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.

Top      Up      ToC       Page 105 
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

Top      Up      ToC       Page 106 
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.