tech-invite   World Map     

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

RFC 3867

 
 
 

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

Part 3 of 4, p. 34 to 66
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 34 
3.  Mutuality

   The Payment API is formalized using the eXtensible Markup Language
   (XML).  It defines wrapper elements for both the input parameters and
   the API function's response.  In particular, the response wrapper
   provides common locations for Error Codes and Error Descriptions.

   It is anticipated that this description reflects the logical
   structure of the API parameter and might be used to derive
   implementation language specific API definitions.

   XML definition:

   <!ELEMENT IotpPaymentApiRequest (
     FindAcceptedPaymentBrand |
     FindAcceptedPaymentProtocol |
     GetPaymentInitializationData |
     FindPaymentInstrument |
     CheckPaymentPossiblity |
     StartPaymentConsumer |
     StartPaymentPaymentHandler |
     ResumePaymentConsumer |
     ResumePaymentPaymentHandler |
     ContinueProcess |
     InquireProcessState |
     ChangeProcessState |
     InquireAuthChallenge |
     Authenticate |

Top      Up      ToC       Page 35 
     CheckAuthResponse |
     CheckPaymentReceipt |
     ExpandPaymentReceipt |
     RemovePaymentLog |
     PaymentInstrumentInquiry |
     InquirePendingPayment |
     ManagePaymentSoftware |
     StartPaymentInquiry |
     InquirePaymentStatus |
     CallBack )>

   <!ATTLIST IotpPaymentApi
     xml:lang          NMTOKEN   #IMPLIED
     ContentSoftwareID CDATA     #IMPLIED
     xmlns             CDATA     #FIXED
                    "http://www.iotp.org/2000/08/PaymentAPI" >

   <!ELEMENT IotpPaymentApiResponse (ErrorResponse?, (
     FindAcceptedPaymentBrandResponse |
     FindAcceptedPaymentProtocolResponse |
     GetPaymentInitializationDataResponse |
     FindPaymentInstrumentResponse |
     CheckPaymentPossiblityResponse |
     StartPaymentConsumerResponse |
     StartPaymentPaymentHandlerResponse |
     ResumePaymentConsumerResponse |
     ResumePaymentPaymentHandlerResponse |
     ContinueProcessResponse |
     InquireProcessStateResponse |
     ChangeProcessStateResponse |
     InquireAuthChallengeResponse |
     AuthenticateResponse |
     CheckAuthResponseResponse |
     CheckPaymentReceiptResponse |
     ExpandPaymentReceiptResponse |
     RemovePaymentLogResponse |
     PaymentInstrumentInquiryResponse |
     InquirePendingPaymentResponse |
     ManagePaymentSoftwareResponse |
     StartPaymentInquiryResponse |
     InquirePaymentStatusResponse |
     CallBackResponse )?)>

   <!ATTLIST IotpPaymentApiResponse
     xml:lang          NMTOKEN #IMPLIED
     ContentSoftwareID CDATA   #IMPLIED
     xmlns             CDATA   #FIXED
                "http://www.iotp.org/2000/08/PaymentAPI" >

Top      Up      ToC       Page 36 
   <!ELEMENT ErrorResponse (ErrorLocation+,PaySchemePackagedContent*) >
   <!ATTLIST ErrorResponse
     xml:lang      NMTOKEN   #IMPLIED
     ErrorCode     NMTOKEN   #REQUIRED
     ErrorDesc     CDATA     #REQUIRED
     Severity(Warning |
       TransientError |
              HardError)     #REQUIRED
     MinRetrySecs  CDATA     #IMPLIED
     SwVendorErrorRef CDATA  #IMPLIED >

   Most of the attribute items are intended for immediate insertion in
   the IOTP Error Block.  The attribute values of the Error Location
   elements attribute have to enriched and transformed into Error
   Location Elements of the Error Component (cf. IOTP Specification).

   Attributes (cf. IOTP Specification):

   xml:lang           Defines the language used by attributes or
                      child elements within this component, unless
                      overridden by an xml:lang attribute on a child
                      element.

   ContentSoftwareId  Contains information which identifies the
                      software that generated the content of the
                      element.  Its purpose is to help resolve
                      interoperability problems that might occur as
                      a result of incompatibilities between messages
                      produced by different software.  It is a single
                      text string in the language defined by
                      "xml:lang".  It must contain, as a minimum
                      problems that might occur as a result of

                      o  the name of the software manufacturer,
                      o  the name of the software,
                      o  the version of the software, and
                      o  the build of the software.

   ErrorCode          Contains an error code which indicates the
                      nature of the error in the message in error.
                      Valid values for the Error Code are given in
                      the following section.  This mnemonic enables
                      the automatic failure resolution of the IOTP
                      Application Core which analyzes the error code
                      value in order to determine the continuation
                      alternatives.

Top      Up      ToC       Page 37 
   ErrorDesc          Contains a description of the error in the
                      language defined by xml:lang.  The content of
                      this attribute is defined by the
                      vendor/developer of the software that
                      generated the Error Response Element.
                      It is intended for user display and provides
                      detailed explanations about the failure and
                      its (out-of-band) resolution alternatives.

   Severity           Indicates the severity of the error.  Valid
                      values are:

                      o  Warning.  This indicates that although there
                         is a message in error the IOTP Transaction
                         can still continue.

                      o  TransientError.  This indicates that the
                         error in the message in error may be
                         recovered if the message in error that is
                         referred to by the "Names" attribute is
                         resent.

                      o  HardError.  This indicates that there is an
                         unrecoverable error in the message in error
                         and the IOTP Transaction must stop.

   MinRetrySecs       This attribute should be present if "Severity"
                      is set to "TransientError".  It is the minimum
                      number of whole seconds which the IOTP aware
                      application which received the message
                      reporting the error should wait before
                      resending the message in error identified by
                      the "ErrorLocation" attribute.

                      If Severity is not set to
                      "TransientError" then the value of this
                      attribute is ignored.

   SwVendorErrorRef   This attribute is a reference whose value is
                      set by the vendor/developer of the software
                      that generated the Error Element.  It should
                      contain data that enables the vendor to
                      identify the precise location in their
                      software and the set of circumstances that
                      caused the software to generate a message
                      reporting the error.

Top      Up      ToC       Page 38 
   Content:

   ErrorLocation      This identifies, where possible, the
                      element and attribute in the message
                      in error that caused the Error
                      Element to be generated.  If the
                      "Severity" of the error is not
                      "TransientError", more that one
                      "ErrorLocation" may be specified as
                      appropriate depending on the nature
                      of the error and at the discretion of
                      the vendor/developer of the IOTP
                      Payment Bridge.

                      Its definition coincides with the
                      IOTP specification whereby the
                      attributes "IotpMsgRef", "BlkRef" and
                      "CompRef" are left blank,
                      intentionally.

   PaySchemePackagedContent  cf. Table 5

3.1.  Error Codes

   The following table lists the valid values for the ErrorCode
   attribute of the Error Response Element.  The first sentence of the
   error description contains the default text that can be used to
   describe the error when displayed or otherwise reported.  Individual
   implementations may translate this into alternative languages at
   their discretion.  However, not every error code may apply to every
   API call.  An Error Code must not be more than 14 characters long.
   The Error Codes have been taken from the IOTP Specification and
   extended by some additional codes which are highlighted by a
   preceding asterisk.

   Generally, if the corrupt values have been user supplied, the IOTP
   Application Core might prompt for their correction.  If the renewal
   fails or if the IOTP Application Core skips any renewals and some
   notification has to be send to the counter-party, the error code is
   encapsulated within an IOTP Error Block.

   However, the IOTP server application reports business errors -
   visible at the IOTP layer - in the Status Component of the respective
   Response Block.

   The IOTP Application Core may add the attributes (and values) within
   the ErrorLocation elements that are omitted by the IOTP Payment
   Bridge.

Top      Up      ToC       Page 39 
   The following table mentions any modification from this general
   processing for particular error values.  Furthermore, it contains
   hints for developers of IOTP Application Core software components
   about the processing of error codes.  Conversely, developers of IOTP
   Payment Bridges get impressions about the expected behavior of the
   IOTP Application Core.

   The IOTP Payment API assumes that the IOTP Application Core
   implements the dialog boxes needed for error resolution.  But it does
   not assume, that the IOTP Payment Bridge actually relies on them.
   Instead, the IOTP Payment Bridge may try resolution on its own, may
   implement specific dialog boxes, and may signal only final failures.

   Note: This abstract document assumes that the API parameters are
   exchanged XML encoded.  Therefore, several error values might
   disappear in lower level language specific derivations.

   Error Value        Error Description
   -----------        -----------------

   Reserved           Reserved.  This error is reserved by the
                      vendor/developer of the software.  Contact
                      the vendor/developer of the software for
                      more information (see the SoftwareId
                      attribute of the Message Id element in the
                      Transaction Reference Block [IOTP]).

   XmlNotWellFrmd     XML not well formed.  The XML document is not
                      well formed.  See [XML] for the meaning of
                      "well formed".

   XmlNotValid        XML not valid.  The XML document is well
                      formed but the document is not valid.  See
                      [XML] for the meaning of "valid".
                      Specifically:

                      o  the XML document does not comply with the
                         constraints defined in the IOTP document
                         type declaration, and
                      o  the XML document does not comply with the
                         constraints defined in the document type
                         declaration of any additional [XML-NS]
                         that are declared.

                      The Names attribute might refer some
                      attributes and elements of the input
                      parameter list.

Top      Up      ToC       Page 40 
   (*)ElNotValid      Element not valid.  Invalid element in terms
                      of prescribed syntactical characteristics.

                      The ElementRef attributes of ErrorLocation
                      elements might refer to the corresponding
                      elements (if they have ID attributes).

                      The IOTP Application Core has to replace the
                      error code with "XmlNotValid" before
                      transmission to the counterparty.

   ElUnexpected       Unexpected element.  Although the XML
                      document is well formed and valid, an
                      element is present that is not expected in
                      the particular context according to the
                      rules and constraints contained in this
                      specification.

                      The ElementRef attributes of ErrorLocation
                      elements might refer to the corresponding
                      elements (if they have ID attributes).

   ElNotSupp          Element not supported.  Although the document
                      is well formed and valid, an element is
                      present that

                      o  is consistent with the rules and
                         constraints contained in this
                         specification, but
                      o  is not supported by the IOTP Aware
                         Application which is processing the IOTP
                         Message.

                      The ElementRef attributes of ErrorLocation
                      elements might refer to the corresponding
                      elements (if they have ID attributes).

   ElMissing          Element missing.  Although the document is
                      well formed and valid, an element is missing
                      that should have been present if the rules
                      and constraints contained in this
                      specification are followed.

                      The ElementRef attributes of ErrorLocation
                      elements might refer to the corresponding
                      elements (if they have ID attributes).

Top      Up      ToC       Page 41 
   ElContIllegal      Element content illegal.  Although the
                      document is well formed and valid, the
                      element contains values which do not conform
                      the rules and constraints contained in this
                      specification.

                      The ElementRef attributes of ErrorLocation
                      elements might refer to the corresponding
                      element (if they have ID attributes).

                      The IOTP Application Core has to replace the
                      Error Code with "ElNotSupp" before
                      transmission to the counter party, if the
                      ErrorLocation elements refer to
                      non-PackagedContent element.

   EncapProtErr       Encapsulated protocol error.  Although the
                      document is well formed and valid, the
                      Packaged Content of an element contains data
                      from an encapsulated protocol which contains
                      errors.

                      The ElementRef attributes of ErrorLocation
                      elements might refer to the corresponding
                      element (if they have ID attributes).

   AttUnexpected      Unexpected attribute.  Although the XML
                      document is well formed and valid, the
                      presence of the attribute is not expected in
                      the particular context according to the
                      rules and constraints contained in this
                      specification.

                      The AttName attributes of ErrorLocation
                      elements might refer to the corresponding
                      attribute tags.

   (*)AttNotValid     Attribute not valid.  Invalid attribute value
                      in terms of prescribed syntactical
                      characteristics.

                      The AttName attributes of ErrorLocation
                      elements might refer to the corresponding
                      attribute tags.

                      The IOTP Application Core has to replace the
                      error code with "XmlNotValid" before
                      transmission to the counter party.

Top      Up      ToC       Page 42 
   AttNotSupp         Attribute not supported.  Although the XML
                      document is well formed and valid, and the
                      presence of the attribute in an element is
                      consistent with the rules and constraints
                      contained in this specification, it is not
                      supported by the IOTP Aware Application
                      which is processing the IOTP Message.

   AttMissing         Attribute missing.  Although the document is
                      well formed and valid, an attribute is
                      missing that should have been present if the
                      rules and constraints contained in this
                      specification are followed.

                      The AttName attributes of ErrorLocation
                      elements might refer to the corresponding
                      attribute tags.

                      If the attribute is required by the IOTP
                      Document Type Declaration (#REQUIRED) the
                      hints for non-valid attributes should be
                      adopted, otherwise these for illegal
                      attribute values.

   AttValIllegal      Attribute value illegal.  The attribute
                      contains a value which does not conform to
                      the rules and constraints contained in this
                      specification.

                      The AttName attributes of ErrorLocation
                      elements might refer to the corresponding
                      attribute tags - valid values are:

                      BrandId: illegal/unknown Brand Identifier -
                      If the brand is not recognized/known by any
                      IOTP Payment Bridge, the IOTP Application
                      Core may offer the registration of a new
                      Payment Instrument.

                      PaymentInstrumentId: illegal/unknown
                      Payment Instrument Identifier - This
                      indicates a serious communication problem if
                      the attribute value has been reported by the
                      same "wallet" on a previous inquiry
                      requests.  The IOTP Application Core has to
                      replace the error code with
                      "UnknownError" before transmission to the
                      counter party.

Top      Up      ToC       Page 43 
                      WalletId: illegal/unknown Wallet Identifier
                      - It is assumed that the wallet identifier
                      is checked before the pass phrase.  On
                      invalid wallet identifiers, the IOTP
                      Application Core may open the dialog in
                      order to request the correct wallet
                      identifier.  In addition, any pass phrase may
                      be supplied by the user.  The dialog should
                      indicate the respective payment brand(s).
                      The IOTP Application Core has to replace the
                      error code with "UnknownError" before
                      transmission to the counter party.

                      Passphrase:   illegal/unknown Pass Phrase -
                      The IOTP Application Core may open the
                      dialog in order to request the correct pass
                      phrase.  If the pass phrase is wallet
                      identifier specific the dialog should
                      display the wallet identifier.  The IOTP
                      Application Core has to replace the error
                      code with "TransportError" before
                      transmission to the counter party.

                      Action:  illegal / unknown / unsupported
                      Action

                      PropertyTypeList:  lists contains illegal /
                      unknown / unsupported Property Types - The
                      IOTP Application Core tries only the local
                      resolution but does never transmit any IOTP
                      Error Block to the counter party.

                      CurrCode: illegal/unknown/unsupported
                      Currency Code

                      CurrCodeType: illegal/unknown/unsupported
                      Currency Code Type

                      Amount: illegal/unknown/unsupported Payment
                      Amount

                      PayDirection: illegal/unknown/unsupported
                      Payment Direction

                      ProtocolId:   illegal/unknown/unsupported
                      Protocol Identifier

Top      Up      ToC       Page 44 
                      OkFrom: illegal/unknown/unsupported OkFrom
                      Timestamp

                      OkTo:   illegal/unknown/unsupported OkTo
                      Timestamp

                      ConsumerPayId: illegal/unknown Consumer
                      Payment Identifier

                      PaymentHandlerPayId: illegal/unknown Payment
                      Handler Payment Identifier

                      PayId: illegal/unknown Payment Identifier

   AttValNotRecog     Attribute Value Not Recognized.  The
                      attribute contains a value which the IOTP
                      Aware Application generating the message
                      reporting the error could not recognize.

                      The AttName attributes of ErrorLocation
                      elements might refer to the corresponding
                      attribute tags.

   MsgTooLarge        Message too large.  The message is too large
                      to be processed by the IOTP Payment Bridge
                      (or IOTP Application Core).

   ElTooLarge         Element too large.  The element is too large
                      to be processed by the IOTP Payment Bridge
                      (or IOTP Application Core).

                      The ElementRef attributes of ErrorLocation
                      elements might refer to the corresponding
                      elements.

   ValueTooSmall      Value too small or early.  The value of all
                      or part of an element content or an
                      attribute, although valid, is too small.

                      The ErrorLocation elements might refer to
                      the corresponding attribute tags or
                      elements.

   ValueTooLarge      Value too large or in the future.  The value
                      of all or part of an element content or an
                      attribute, although valid, is too large.

Top      Up      ToC       Page 45 
                      The ErrorLocation elements might refer to
                      the corresponding attribute tags or
                      elements.

   ElInconsistent     Element Inconsistent.  Although the document
                      is well formed and valid, according to the
                      rules and constraints contained in this
                      specification:

                      o  the content of an element is inconsistent
                         with the content of other elements or
                         their attributes, or

                      o  the value of an attribute is inconsistent
                         with the value of one or more other
                         attributes.

                      The Error Description may contain further
                      explanations.

                      The ErrorLocation elements might refer to
                      the corresponding attribute tags or elements
                      that are inconsistent.

   TransportError     Transport Error.  This error code is used to
                      indicate that there is a problem with the
                      transport mechanism that is preventing the
                      message from being received.  It is typically
                      associated with a "Transient Error".

                      The connection to some periphery or the
                      counter party could not be established,
                      is erroneous, or has been lost.

                      The Error Description may contain further
                      narrative explanations, e.g., "chip card
                      does not respond", "remote account manager
                      unreachable", "Internet connection to xyz
                      lost", "no Internet connection available",
                      "no modem connected", or "serial port to
                      modem used by another application".  This
                      text should be shown to the end user.  If
                      timeout has occurred at the Consumer this
                      text should be shown and the Consumer may
                      decide how to proceed - alternatives are
                      retry, payment transaction suspension, and
                      cancellation.

Top      Up      ToC       Page 46 
   MsgBeingProc       Message Being Processed.  This error code is
                      only used with a Severity of Transient
                      Error.  It indicates that the previous
                      message, which may be an exchange message or
                      a request message, is being processed and,
                      if no response is received by the time
                      indicated by the "MinRetrySecs" attribute,
                      then the original message should be resent.

   SystemBusy         System Busy.  This error code is only used
                      with a Severity of Transient Error.  It
                      indicates that the IOTP Payment Bridge or
                      Existing Payment Software that received the
                      API request is currently too busy to handle
                      it.  If no response is received by the time
                      indicated by the "MinRetrySecs" attribute,
                      then the original message should be resent.

                      The Error Description may provide further
                      explanations, e.g., "wallet / chip card
                      reader is unavailable or locked by another
                      payment transaction", "payment gateway is
                      overloaded", "unknown chip card reader", or
                      "unrecognized chip card inserted, change
                      chip card".

                      The Consumer's IOTP Application Core may
                      display the error description and ask the
                      Consumer about the continuation -
                      alternatives are retry, payment transaction
                      suspension, and cancellation.

   UnknownError       Unknown Error.  Indicates that the
                      transaction cannot complete for some reason
                      that is not covered explicitly by any of the
                      other errors.  The Error description
                      attribute should be used to indicate the
                      nature of the problem.

                      The ErrorLocation elements might refer to
                      the corresponding attribute tags or elements
                      that are inconsistent.

   (*)SyntaxError     Syntax Error.  An (unknown) syntax error has
                      occurred.

Top      Up      ToC       Page 47 
                      The ErrorLocation elements might refer to
                      the corresponding attribute tags or elements
                      that are inconsistent.

                      The IOTP Application Core has to replace the
                      error code with "XmlNotValid" or
                      "UnknownError" before transmission to the
                      counter party.

   (*)ReqRefused      Request refused.  The API request is
                      (currently) refused by the IOTP Payment
                      Bridge.  The error description may provide
                      further explanations, e.g., "wallet / chip
                      card reader is unavailable or locked by
                      another payment transaction", "payment
                      gateway is overloaded", "unknown chip card
                      reader", or "unrecognized chip card
                      inserted, change chip card".

                      The Consumer's IOTP Application Core may
                      display the error description and ask the
                      Consumer about the continuation -
                      alternatives are retry, payment transaction
                      suspension, and cancellation.  Denials due to
                      invalid Process States should be signaled by
                      "BusinessError".  Typically, this kind of
                      error is not passed to the counter party's
                      IOTP Application Core.  Otherwise, it maps to
                      "TransportError" or "UnknownError".

   (*)ReqNotSupp      Request not supported.  The API
                      function(ality) has not been implemented in
                      the IOTP Payment Bridge.  Typically, this
                      kind of error is not passed to the
                      counter party's IOTP Application Core.
                      Otherwise, it maps to "TransportError" or
                      "UnknownError".

   (*)BusError        Business Error.  The API request has been
                      rejected because some payment transaction
                      has an illegal payment status.
                      Particularly, this error code is used to
                      signal any raise of payment business layered
                      failures.

                      The ErrorLocation elements may refer to
                      payment transactions using the party's
                      Payment Identifier - it defaults to the

Top      Up      ToC       Page 48 
                      current transaction or might contain the
                      current payment transaction party's Payment
                      Identifier - identified by the ElementRef
                      attribute while the AttName attribute is
                      fixed with "PayId".

                      The IOTP Application Core must inquire the
                      IOTP Payment Bridge about the actual Process
                      State which actually encodes the business
                      error ("Inquire Process State").
                      This error code must not be
                      passed to the counter party's IOTP
                      Application Core.

                        Table 2: Common Error Codes

   The IOTP Payment Bridge may also use the error description in order
   to notify the Consumer about further necessary steps for failure
   resolution, e.g., "Sorry, your payment transaction failed.
   Unfortunately, you have been charged, please contact your issuer."

3.2.  Attributes and Elements

   The following table explains the XML attributes in alphabetical order
   - any parenthesized number after the attribute tag is a recommended
   maximal length of the attribute value in characters:

   Attribute           Description
   ---------           -----------

   Amount    (11)      Indicates the payment amount to be paid in
   AmountFrom(11)      whole and fractional units of the currency.
   AmountTo  (11)      For example $245.35 would be expressed
                       "245.35".  Note that values smaller than the
                       smallest denomination are allowed.  For
                       example one tenth of a cent would be
                       "0.001".

   AuthenticationId    An identifier specified by the
                       authenticator which, if returned by the
                       organization that receives the
                       authentication request, will enable the
                       authenticator to identify which
                       authentication is being referred to.

Top      Up      ToC       Page 49 
   BrandId  (128)      This contains a unique identifier for the
                       brand (or promotional brand).  It is used to
                       match against a list of Payment Instruments
                       which the Consumer holds to determine
                       whether or not the Consumer can pay with the
                       Brand.

                       Values of BrandId are managed under
                       procedure being described in the IOTP
                       protocol specification.

   BrandLogoNetLocn    The net location which can be used to
                       download the logo for the organization (cf.
                       IOTP Specification).

                       The content of this attribute must conform
                       to [URL].

   BrandName           This contains the name of the brand, for
                       example "MasterCard Credit".  This is the
                       description of the Brand which is displayed
                       to the consumer in the Consumer's language
                       defined by "xml:lang".  For example it might
                       be "American Airlines Advantage Visa".  Note
                       that this attribute is not used for matching
                       against the payment instruments held by the
                       Consumer.

   BrandNarrative      This optional attribute is
                       used by the Merchant to indicate some
                       special conditions or benefit which would
                       apply if the Consumer selected that brand.
                       For example "5% discount", "free shipping
                       and handling", "free breakage insurance for
                       1 year", "double air miles apply", etc.

   CallBackFunction    A function which is called whenever there is
                       a change of Process State or payment
                       progress, e.g., for display updates.  However,
                       the IOTP Payment Bridge may use its own
                       mechanisms and dialog boxes.

   CallBackLanguageList
                       A list of language codes which contain, in
                       order of preference, the languages in which
                       the text passed to the Call Back function
                       will be encoded.

Top      Up      ToC       Page 50 
   CompletionCode (14) Indicates how the process completed.
                       It is required if ProcessState is set to
                       "Failed" otherwise it is ignored.  Valid
                       values as well as recovery options are given
                       in the IOTP specification.

                       The IOTP Payment Bridge may also use the
                       Status Description to notify the Consumer
                       about further necessary steps in order to
                       resolve some kind of business failures,
                       e.g.,

                       o  "sorry, your payment transaction failed.
                          Unfortunately, you have been charged,
                          please contact your issuer."
                       o  "insufficient capacity left (on your
                          stored value card) for refund",
                       o  "payment failed/chip card error/internal
                          error, please contact your payment
                          instrument's issuer"

   ConsumerDesc        A narrative description of the Consumer.

   ConsumerPayId (14)  An unique identifier specified by the
                       Consumer that, if returned by the Payment
                       Handler in another Payment Scheme Component
                       or by other means, enables the Consumer to
                       identify which payment is being referred to.

                       This unique identifier is generated by the
                       IOTP Application Core and submitted to the
                       IOTP Payment Bridge on every API call.  It
                       may equal the Payment Handler Payment
                       Identifiers but need not necessarily be so.

                       The uniqueness extends to multiple payment
                       instruments, payment brands, payment
                       protocols, wallet identifiers, and even
                       multiple IOTP Payment Bridges.

   ContStatus          During payment progress, this status value
                       indicates whether the payment needs to be
                       continued with further IOTP Payment Scheme
                       Component exchanges with the remote party.
                       "End" indicates that the reported payment
                       scheme data is the last data to be exchanged
                       with the counter party.

Top      Up      ToC       Page 51 
   ContentSoftwareId   This contains information that identifies
                       the software that generated the content of
                       the element.  Its purpose is to help resolve
                       interoperability problems that might occur
                       as a result of incompatibilities between
                       messages produced by different software.  It
                       is a single text string in the language
                       defined by xml:lang.  It must contain, as a
                       minimum:

                       o  the name of the software manufacturer,
                       o  the name of the software,
                       o  the version of the software, and
                       o  the build of the software.

   CurrCodeType (14)   Indicates the domain of the CurrCode.  This
                       attribute is included so that the currency
                       code may support nonstandard currencies
                       such as frequent flyer point, trading
                       stamps, etc.  Its values may be

                       o  ISO-4217-A, the default, indicates the
                          currency code is the three-letter
                          alphabetic code that conform to ISO-4217
                          [ISO4217].
                       o  IOTP indicates that the values of
                          CurrCode are managed under the procedure
                          described in [IOTP].

   CurrCode  (14)      A code which identifies the currency to be
                       used in the payment.  The domain of valid
                       currency codes is defined by "CurrCodeType"

   MerchantPayId  (14) An private identifier specified by the
                       Merchant which will enable the Merchant to
                       identify which payment is being referred to.
                       It is a pure private item and is never sent
                       to any other party.  It is provided by the
                       IOTP Payment Bridge on payment preparation
                       during brand compilation.

                       Cf. To "ConsumerPayId" for note about
                       uniqueness.

Top      Up      ToC       Page 52 
   MerchantOrgId  (64) A local item that might refer to some
                       specific shop in a multi shop environment.
                       This item is optional and might enrich the
                       Wallet Identifier which itself can be used
                       for the same purpose.

   Name                Distinguishes between multiple occurrences
                       of Packaged Content Elements at the same
                       point in IOTP.  For example:

                       <ABCD>
                         <PackagedContent Name='FirstPiece'>
                           snroasdfnas934k
                         </PackagedContent>
                         <PackagedContent Name='SecondPiece'>
                           dvdsjnl5poidsdsflkjnw45
                         </PackagedContent>
                       </ABCD>

                       The "Name" attribute may be omitted, for
                       example if there is only one Packaged
                       Content element.

   OkFrom  (30)        The date and time in UTC Format range
   OkTo  (30)          indicated by the merchant in which the
                       Payment Handler may accept the payment.
                       For more information, see [UTC].

   Passphrase  (32)    Payment wallets may use pass phrase
                       protection for transaction data and payment
                       instruments' data.  However, it is assumed
                       that there exists a public and customizable
                       payment instrument identifier such that
                       these identifiers together with their
                       relationship to payment brands, payment
                       protocols, payment directions, and currency
                       amounts can be queried by the IOTP
                       application without any pass phrase
                       knowledge.

   PayDirection        Indicates the direction in which the
                       payment for which a Brand is being selected
                       is to be made.  Its values may be:

                       o  Debit: The sender of the Payment Request
                          Block (e.g., the Consumer) to which this
                          Brand List relates will make the payment
                          to the Payment Handler, or

Top      Up      ToC       Page 53 
                       o  Credit: The sender of the Payment Request
                          Block to which this Brand List relates
                          will receive a payment from the Payment
                          Handler.

   PayId (14)          This attribute is introduced for API
                       simplification:

                       o  The Consumer has to identify PayId and
                          ConsumerPayId.

                       o  The Merchant has to identify PayId and
                          MerchantPayId.

                       o  The Payment Handler has to identify PayId
                          and Payment Handler Pay Id.


   PayInstId           This contains the unique identifier used
                       internally by the IOTP Payment
                       Bridge/Existing Payment Software.

   PayInstName         This contains the user-defined name of the
                       payment instrument.  There exist no
                       (technical) constraints like uniqueness.  The
                       "xml:lang" attribute denotes the language
                       encoding of its value.

   PaymentHandlerDesc  A narrative description of the Payment
                       Handler.

   PaymentHandlerPayId An unique identifier specified by the
     (14)              Payment Handler that, if returned by the
                       Consumer in another Payment Scheme Component
                       or by other means, enables the Payment
                       Handler to identify which payment is being
                       referred to.  It is required whenever it is
                       known.

                       Cf. To "ConsumerPayId" for note about
                       uniqueness.

   PaymentInstrumentId An identifier for a specific payment
     (32)              instrument, e.g., "credit card", "Mondex card
                       for English Pounds".  This identifier is
                       fully customizable.  It is assumed, that it
                       does not contain confidential information or
                       even an indication of it.  The payment

Top      Up      ToC       Page 54 
                       instrument identifier is unique within each
                       payment brand.  It is displayed to the
                       Consumer during brand selection.

   PayReceiptNameRefs  Optionally contains element references to
     (32)              other elements (containing payment scheme
                       specific data) that together make up the
                       receipt.  Note that each payment scheme
                       defines in its supplement the elements that
                       must be referenced

                       The IOTP Application Core should save all
                       the components referenced so that the
                       payment receipt can be reconstructed when
                       required.

   PayReqNetLocn       The Net Location indicating where an
                       unsecured Payment Request message should be
                       sent if this protocol choice is used.

                       The content of this attribute must conform
                       to [URL] and depends on the Transport
                       Mechanism.

   PercentComplete (3) A number between 0 and 100 which indicates
                       the progress of the payment transaction.  The
                       values range between 0 and 99 for pending
                       and suspended transactions.

   ProcessState        Contains a Process State Code that
                       indicates the current state of the process
                       being carried out.  Valid values are:

                       o  NotYetStarted.  The Payment Request Block
                          has been received but processing of the
                          Payment Request has not yet started

                       o  InProgress.  The payment transaction is
                          pending.  The processing of the (Payment)
                          Request Block has started but it is not
                          yet complete.

                       o  (*)Suspended: The payment transaction has
                          been suspended and can be resumed.

                       This process state is mapped to
                       "InProgress", if it is passed to the
                       counter party's IOTP Application Core.

Top      Up      ToC       Page 55 
                       o  CompletedOk.  The processing of the (Payment)
                          Request Block and any following Payment
                          Exchange Blocks has completed successfully.

                       o  Failed.  The payment processing has finally
                          failed for a Business Error.

                       o  ProcessError.  This value is only used
                          when the Status Component is being used in
                          connection with an Inquiry Request Trading
                          Block.  It indicates there was a Technical
                          Error in the Request Block which is being
                          processed or some internal processing
                          error.  Each party's IOTP Payment Bridge
                          uses this value in order to notify the
                          IOTP Application Core about the presence
                          of technical errors.

   PropertyType  (14)  The property type defines codes used for
                       interrogation of specific properties about a
                       payment instrument.  They are unique for each
                       payment brand.  The predefined property "all"
                       is used on general inquiries.  However, these
                       property types are not used during normal
                       payment processing.  E.g., they may apply to
                       payment brand specific transactions or
                       out-of-band failure resolution.

   PropertyDesc        The property description carries the
                       respective human readable property (value)'s
                       description.

   PropertyValue       The actual property value intends automatic
                       post processing.

   ProtocolBrandId (64)This is an identifier to be used with a
                       particular payment protocol.  For example,
                       SET and EMV have their own well defined, yet
                       different, values for the Brand identifier
                       to be used with each protocol.  The valid values
                       of this attribute are defined in the
                       supplement for the payment protocol
                       identified by "ProtocolId" that describes
                       how the payment protocol works with IOTP.
                       Identifier maps to at most one Protocol
                       Brand Identifier.

Top      Up      ToC       Page 56 
   ProtocolId  (64)    An identifier for a specific payment
                       protocol and version, e.g., "SETv1.0",
                       "ecash".  Valid values are defined by
                       supplements to the IOTP specification and
                       they are unique within each payment brand.

   ProtocolIds         A sequence of Protocol Identifiers

   ProtocolName        A narrative description of the payment
                       protocol and its version in the language
                       identified by "xml:lang".  For example
                       "Secure Electronic Transaction Version 1.0".
                       Its purpose is to help provide information
                       on the payment protocol being used if
                       problems arise.

   SecPayReqNetLocn    The Net Location indicating where a secured
                       Payment Request message should be sent if
                       this protocol choice is used.

                       A secured payment involves the use of a
                       secure channel such as [TLS] in order
                       to communicate with the Payment Handler.

                       The content of this attribute must conform
                       to [URL].

   ReceiverOrgId       The Organization Identification which
                       receives the payment bridge processing
                       Trading Role Data PackagedContent.

   StatusDesc  (256)   An optional textual description of the
                       current process state in the language
                       identified by "xml:lang" that should be
                       displayed to the Consumer.  The usage of this
                       attribute is defined in the payment
                       supplement for the payment method being
                       used.  Particularly, it provides hints for
                       out-of-band failure resolution.  Its length
                       is limited to 256 characters.

   StyleSheetNetLocn   This contains the net location to a style
                       sheet with visualisation rules for XML
                       encoded data.

   TimeStamp  (30)     The date and time in UTC Format when the
                       payment transaction has been started.
                       For more information on UTC, see [UTC].

Top      Up      ToC       Page 57 
   WalletId  (32)      Many existing payment wallet software are
                       multiple wallet capable.  The Wallet
                       Identifier selects the actual wallet.  It is
                       assumed, that the wallet identifier is a
                       public item, that might be stored by the
                       IOTP Application Core.

   xml:lang            Defines the language used by the Process
                       State Description attribute (cf. IOTP
                       Specification)

                            Table 3: Attributes

   The following table explains the XML elements in alphabetical order:

   Element             Description
   -------             -----------

   Algorithm           This contains information which describes
                       an Algorithm that may be used to generate
                       the Authentication response.

                       The algorithm that may be used is
                       identified by the Name attribute (cf. IOTP
                       Specification).

   AuthReqPackagedContent   The Authentication Request Packaged
                       Content originates from a Authentication
                       (Data/Response) Component's content
                       whereby the outermost element tags are
                       prefixed with "AuthReq".  Its declaration
                       coincides with the Packaged Content's
                       declaration (cf. IOTP Specification).  It
                       encapsulates the authentication challenge
                       value.  The content of this information is
                       defined in the supplement for a payment
                       protocol.

   AuthResPackagedContent   The Authentication Response Packaged
                       Content originates from a Authentication
                       Response Component's content whereby the
                       outermost element tags are prefixed with
                       "AuthRes".

                       Its declaration coincides with the
                       Packaged Content's declaration (cf. IOTP
                       Specification).  It encapsulates the

Top      Up      ToC       Page 58 
                       authentication response value.  The
                       content of this information is defined in
                       the supplement for a payment protocol.

   BrandPackagedContent     Container for further payment brand
                       description.  Its content originates from
                       a Brand Element content whose outermost
                       element tags are prefixed with "Brand".
                       Its declaration coincides with the
                       Packaged Content's declaration (cf. IOTP
                       Specification).

   BrandSelBrandInfoPackagedContent
                       This contains any additional data that
                       may be required by a particular payment
                       brand.  It forms the content of the Brand
                       Selection Brand Info Element.

   BrandSelProtocolAmountInfoPackagedContent
                       This contains any additional data that
                       may be required by a particular payment
                       brand in the format.  It forms the content
                       of the Brand Selection Protocol Amount
                       Info Element.

   BrandSelCurrencyAmountInfoPackagedContent
                       This contains any additional data that is
                       payment brand and currency specific in
                       the format.  It forms the content of the
                       Brand Selection Currency Amount Info
                       Element.

   MerchantData        Any merchant related data that might be
                       used by the IOTP Payment Bridge for
                       different purposes, e.g., it might
                       contain IDs to access some mall data,
                       but not cryptographic keys.  Its Packaged
                       declaration coincides with the Content's
                       declaration (cf. IOTP Specification).

   PackagedContent     Generic Container for non-IOTP data (cf.
                       IOTP Specification).

   PayProtocolPackagedContent
                       The Pay Protocol Packaged Content
                       originates from a Pay Protocol
                       Element's content whereby the outermost
                       element tags are prefixed with

Top      Up      ToC       Page 59 
                       "PayProtocol".  It contains information
                       about the protocol which is used by
                       the payment protocol.  The content of
                       this information is defined in the
                       supplement for a payment protocol.  Its
                       declaration coincides with the Packaged
                       Content's declaration (cf. IOTP
                       Specification).

   PaySchemePackagedContent
                       The PayScheme Packaged Content originates
                       from a Payment Scheme Component's content
                       whereby the outermost element tags are
                       prefixed with "PayScheme".  Its
                       declaration coincides with the Packaged
                       Content's declaration (cf. IOTP
                       Specification).  It carries the payment
                       specific data.  The content of this
                       information is defined in the supplement
                       for a payment protocol.

   ProtocolAmountPackagedContent
                       The Protocol Amount Packaged Content
                       originates from a Protocol Amount
                       Element's content whereby the outermost
                       element tags are prefixed with "Amount".
                       Its declaration coincides with the
                       Packaged Content's declaration (cf. IOTP
                       Specification).  It contains information
                       about the protocol which is used by the
                       payment protocol.  The content of this
                       information is defined in the supplement
                       for a payment protocol.

   ProtocolBrandPackagedContent
                       The Protocol Brand Packaged Content
                       originates from a Protocol Brand
                       Element's content whereby the outermost
                       element tags are prefixed with
                       "ProtocolBrand".  Its declaration
                       coincides with the Packaged Content's
                       declaration (cf. IOTP Specification).  It
                       contains information about the brand
                       which might be used by the payment
                       protocol.  The content of this information
                       is defined in the supplement for a
                       payment protocol.

Top      Up      ToC       Page 60 
   ResponsePackagedContent
                       Container for authentication response
                       data.  Its content originates from a
                       Authentication Response Component's
                       Packaged Content whose outermost element
                       tags are prefixed with "Response".  Its
                       declaration coincides with the Packaged
                       Content's declaration (cf. IOTP
                       Specification).

   TradingRoleDataPackagedContent
                       The TradingRoleData Packaged Content
                       originates from a TradingRoleData
                       Component's content whereby the outermost
                       element tags are prefixed with
                       "TradingRoleData".  Its declaration
                       coincides with the Packaged Content's
                       declaration (cf. IOTP Specification).  It
                       contains information from Merchant to
                       Payment Handler via Consumer about the
                       protocol which is used by the payment.
                       The content of this information is
                       defined in the supplement for a payment
                       protocol.  The Name attribute in this
                       packaged contents must include prefix as
                       "Payment:" to indicate that the payment
                       bridge processes this, for example
                       "Payment:SET-OD".  See [SET/IOTP] for
                       more information.

                       The element's declaration coincides with
                       the Packaged Content's declaration (cf.
                       IOTP Specification).

                             Table 4: Elements

   XML definition:

   <!ENTITY % AuthReqPackagedContent       "PackagedContent">
   <!ENTITY % AuthResPackagedContent       "PackagedContent">

   <!ENTITY % BrandPackagedContent         "PackagedContent">
   <!ENTITY % BrandSelInfoPackagedContent  "PackagedContent">
   <!ENTITY % BrandSelProtocolAmountPackagedContent
                                           "PackagedContent">
   <!ENTITY % BrandSelCurrencyAmountPackagedContent
                                           "PackagedContent">
   <!ENTITY % ProtocolAmountPackagedContent

Top      Up      ToC       Page 61 
                                           "PackagedContent">
   <!ENTITY % PayProtocolPackagedContent   "PackagedContent">
   <!ENTITY % TradingRoleDataPackagedContent "PackagedContent">
   <!ENTITY % MerchantData "PackagedContent">
   <!ENTITY % PaySchemePackagedContent     "PackagedContent">

3.3.  Process States

   The IOTP Payment API supports six different attribute values that
   encode the transaction status from the IOTP's point of view, i.e.,
   the appropriate point of view at the interface between the IOTP
   Application Core and IOTP Payment Bridge.  This point of view does
   not completely mimic the more detailed view on the actual payment by
   the actual Existing Payment Software or IOTP Payment Bridge.

   The following three tables distinguish between the Merchant's,
   Consumer's, and Payment Handlers' environment.  They extend the
   aforementioned explanations towards the mapping between IOTP process
   states and the internal payment scheme related states of the Existing
   Payment Software/IOTP Payment Bridge.

3.3.1.  Merchant

   The Merchant's point of view of payment is limited to the local
   payment initiation being interlaced with order processing because
   IOTP assigns the actual payment processing to the Payment Handler.

   ProcessState        Description
   ------------        -----------

   NotYetStarted       The Payment Transaction exists within the
                       IOTP Application Core, i.e., the
                       Merchant's shop has already signaled to
                       the IOTP Application Core that an IOTP
                       transaction has been initiated by the
                       Consumer.

                       However, neither any API call has been
                       issued to the IOTP Payment Bridge nor has
                       the IOTP Order Request has been created.

   InProgress          The IOTP Application changes the process
                       state to this value when it issues the
                       first API call to the Payment Bridge
                       during Brand List compilation.

Top      Up      ToC       Page 62 
                       This value indicates that the Payment
                       Bridge might have some knowledge about
                       the expected payment or might have
                       performed some preparatory tasks (even
                       with the Payment Handler out-of-band to
                       IOTP).

                       However, this value does not indicate
                       that any IOTP Order Request has been
                       created and transmitted to the Consumer.

   Suspended           The IOTP transaction has been suspended
                       before the order request block has been
                       transmitted to the Consumer.

                       Implicitly, the payment is also deferred.

   CompletedOk         The IOTP Order Request has been
                       successfully created and transmitted to
                       the Consumer.  Actually, this process
                       state indicates only that the order
                       processing has been finished.

                       But it contains no indication about the
                       status of the actual payment, which is
                       accepted by the Payment Handler.

                       However, successful order processing
                       signals the IOTP Application Core that a
                       payment with some specific parameters is
                       expected within the near future.  And this
                       signal might be used by the Existing
                       Payment Software for similar purposes.
                       This attribute might be interpreted as
                       successful preparation of the payment
                       system.

                       Particularly, it is expected that the
                       Existing Payment Software maps this IOTP
                       status value to some other internal
                       value, e.g., "NotYetStarted", that is more
                       accurate from its point of view.

                       As IOTP provides no communication channel
                       between the Merchant and Payment Handler,
                       any change of payment process state will

Top      Up      ToC       Page 63 
                       be initiated out-of-band to IOTP, e.g., by
                       electronic statements of account or
                       payment scheme specific mechanisms.

   Failed              The IOTP transaction, i.e., order
                       processing, has failed for some
                       (business) reason and it is known that no
                       payment will occur.

                       This indication might be used to clear
                       all data about this transaction within
                       the Existing Payment Bridge (by
                       "RemovePaymentLog" or
                       "ChangeProcessState") or to reverse any
                       preparation (with the Payment Handler
                       out-of-band to IOTP).

                       However, the ideal point of view of IOTP
                       suspects that the actual payment
                       transaction has been neither started nor
                       initiated.

   ProcessError        The IOTP transaction, i.e., order
                       processing, has failed for some
                       (technical) reason and it is known that
                       no payment will occur.

                       This indication might be used to clear
                       all data about this transaction within
                       the Existing Payment Bridge (by
                       "RemovePaymentLog" or
                       "ChangeProcessState") or to reverse any
                       preparation (with the Payment Handler
                       out-of-band to IOTP).

                       However, the ideal point of view of IOTP
                       suspects that the actual payment
                       transaction has been neither started nor
                       initiated.

                             Table 5: Merchant

3.3.2.  Consumer

   The Consumer's IOTP Application Core restricts its point of view to
   the payment transaction.  It is assumed that the IOTP Payment Bridge
   handles the preceding brand selection process in a stateless manner.

Top      Up      ToC       Page 64 
   ProcessState        Description
   ------------        -----------

   NotYetStarted       This encodes the initial process state of
                       any IOTP payment transaction.  This value
                       is set during brand selection but it
                       normally will not change during the whole brand
                       selection process.

   InProgress          With the issuance of the Start Payment
                       Consumer API call, the IOTP Application
                       Core changes the process state to this
                       value.

   Suspended           The payment transaction has been
                       suspended.  Suspension may occur anywhere
                       during brand selection (with the
                       Merchant) or payment processing (with the
                       Payment Handler).  On resumption, the IOTP
                       Application Core and the IOTP Payment
                       Bridge have to use other internal data to
                       decide whether brand selection or actual
                       payment processing needs to be continued,
                       i.e., whether the process state needs to
                       be reset to "NotYetStarted" or
                       "InProgress".

                       Note that the Payment API assumes
                       stateless brand selection by the IOTP
                       Payment Bridge.  Typically, any suspension
                       during brand selection requires the
                       repetition of the whole process.  Hereby,
                       the IOTP Application Core might need to
                       consider any already negotiated
                       conditions in a brand depended purchase
                       (brand, protocol).

   CompletedOk         The successful payment has been
                       acknowledged by the Payment Handler, i.e.,
                       the successful IOTP Payment Response has
                       been received.

                       Implicitly, this implies successful order
                       processing.

Top      Up      ToC       Page 65 
   Failed              The IOTP transaction, i.e., order or
                       payment processing, has failed for some
                       (business) reason.  In either case it is
                       known that the payment will not succeed.

   ProcessError        The IOTP transaction, i.e., order or
                       payment processing, has failed for some
                       (technical) reason.

                       However, the local process state might be
                       different from that of Payment Handler.

                             Table 6: Consumer

3.3.3.  Payment Handler

   The Payment Handler is responsible for the actual payment processing.
   New payment transactions are reported by the Consumer with the
   transmission of new IOTP Payment Request Blocks.  IOTP Payment
   Exchange Block are send by the Consumer for payment transaction
   continuation and resumption.

   ProcessState        Description
   ------------        -----------

   NotYetStarted       This encodes the initial process state of
                       any payment transaction.  Typically, this
                       value will last for a short amount of
                       time.

   InProgress          The IOTP Application Core changes the
                       process state changes to "InProgress"
                       when the Payment Handler starts with the
                       actual processing of the IOTP Payment
                       Request Block.

                       Note that this does not assume that the
                       "StartPaymentPaymentHandler" API function
                       has been called.

   Suspended           The payment transaction has been
                       suspended.

   CompletedOk         The payment has been processed,
                       successfully, i.e., the IOTP Payment
                       Response Block was created and
                       transmitted to the Consumer.

Top      Up      ToC       Page 66 
   Failed              The payment transaction, has finally
                       failed for some (business) reason.

                       Note that this value encodes the payment
                       state reported by the IOTP Payment Bridge
                       on "InquireProcessState".  It neither
                       reflects whether the payment receipt has
                       been inquired nor whether the IOTP
                       Payment Response Block has been created
                       and submitted to the Consumer.

   ProcessError        The payment transaction, has finally
                       failed for some (technical) reason.

                       Note that this value encodes the payment
                       state reported by the IOTP Payment
                       Bridge.  It does not reflect whether some
                       IOTP Error Block has been created and
                       submitted to the Consumer.

                             Table 7: Consumer



(page 66 continued on part 4)

Next RFC Part