Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3867

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

Pages: 106
Informational
Part 4 of 4 – Pages 66 to 106
First   Prev   None

Top   ToC   RFC3867 - Page 66   prevText

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