Subject: iotpar101c.zip

From: "Donald E. Eastlake 3rd" <[email-masked]>
Date: Mon, 20 Sep 1999 23:35:10 -0400

An updated version of the IOTP Architecture and Payment API draft is
available at <ftp://ftp.pothole.com/pub/ietf-trade/iotpar101c.zip>.
This is a zipped MS Word document but has been changed greatly
from previous formats to be much closer to Internet-Draft format
including ASCII figures.

Thanks to Wernver Hans for producing the update.

Donald

=====================================================================
 Donald E. Eastlake 3rd   +1 914-276-2668     [email-masked]
 65 Shindegan Hill Road, RR#1  +1 914-784-7913(work)  [email-masked]
 Carmel, NY 10512 USA
-----------------------------------------------------------------------
Message addressed to: [email-masked]
Archive available at: http://www.elistx.com/archives/ietf-trade/
To (un)subscribe send a message with "subscribe" or "unsubscribe" in the
body to: [email-masked]

---

From: Yoshiaki KAWATSURA <[email-masked]>
Date: Tue, 21 Sep 1999 13:58:38 +0900 (JST)

Hans and Don,
We are now developing the IOTP Payment API Specification to use the
SMILE project.
This is based on the Hans' (and my) IOTP Payment API version 1.01a, but
several(many?) points of our specification has been changed or updated
for fitting the current specification, efficiency and problem
resolutions.

We want to feedback our considerations to your draft and fit them.

We will check the current IOTP Payment API and send the differences 
between them ASAP.

Regards,
----
Yoshiaki Kawatsura : E-mail [email-masked]
 Business & Information Systems Development Division, Hitachi,Ltd.
Voice: +81-44-549-1713(direct) Fax: +81-44-549-1721
-----------------------------------------------------------------------
Message addressed to: [email-masked]
Archive available at: http://www.elistx.com/archives/ietf-trade/
To (un)subscribe send a message with "subscribe" or "unsubscribe" in the
body to: [email-masked]

---

From: "Donald E. Eastlake 3rd" <[email-masked]>
Date: Tue, 21 Sep 1999 18:29:11 -0400

OK.  It would be great if we could resolve any differences and get
this into Internet-Draft form so it can be posted by mid-October,
before the cutoff for the November IETF meeting.

Thanks,
Donald

From:  Yoshiaki KAWATSURA <[email-masked]>
Message-Id:  <[email-masked]>
To:  [email-masked], [email-masked]
Cc:  [email-masked]
Cc:  [email-masked]
In-Reply-To:  Your message of "Mon, 20 Sep 1999 23:35:10 -0400"
	     	<[email-masked]>
References:  <[email-masked]>
Date:  Tue, 21 Sep 1999 13:58:38 +0900 (JST)
Sender:  Yoshiaki KAWATSURA <[email-masked]>

---

From: Yoshiaki KAWATSURA <[email-masked]>
Date: Tue, 28 Sep 1999 14:53:42 +0900 (JST)

Werner and Don,

This is a research document of the differences of the Payment APIs
between Hans' and SMILE's.  We will send the document which describes
the other topics, such as the Error Handling.

----------------------
Generic(1):
Why have you drop the ContentSoftwareId throughout your document?  I
think this ID should be set in the Payment Bridge because
PackagedContents are generated behind the Payment Bridge.

Generic(2):
We should change from AmountPackagedContents to
ProtocolAmountPackagedContents because this packaged contents is
included in ProtocolAmount Component, not in Amount Component.

-> : There ONLY exists the Element in SMILE's API.
<- : There ONLY exists the Element in Hans' API.

FindAcceptedPayBrand Function:
-> MerchantPayId
 Comment:This ID should be set in this function.

-> MerchantOrgId
 Comment:This needs when more than one Merchants exist in the IOTP
 Merchant Server (and Mall).

-> MerchantData
 Comment: This element is used to be set the Mall access keys which use 
 to get information in the Mall.

FindAcceptedPayBrandResponse Function:
-> ContentSoftwareId
 Comment: See above(Generic(2)).

FindAcceptedPaymentProtocol Function:
->MerchantData
 Comment: See above description of MerchantData.

FindAcceptedPaymentProtocolResponse Function:
->ContentSoftwareId
 Comment: See above(Generic(2)).

GetPaymentInitializationData Function:
->MerchantOrgId
 Comment:This needs when some Merchants exist in the IOTP Merchant Server
 (and Mall).

->MerchantData
Comment: See above description of MerchantData.

GetPaymentInitializationDataResponse Function:
->ContentSoftwareId
 Comment: See above(Generic(2)).

FindPaymentInstrument and FindPaymentProtocol Function:
 Comment:We merged FindPaymentInstrument and FindPaymentProtocol into
 FindPaymentInstrument and dropped the FindPaymentProtocol API because
 ProtocolBrandId depends on both Payment Brand and Payment Protocol and
 it may invite unnecessary processes.

 Our FindPaymentInstrument function is as follows:
 <!ELEMENT FindPaymentInstrument (BrandPackagedContent*,
       ProtocolBrandPackagedContent*,ProtocolPackagedContent*,
       ProtocolAmountPackagedContent*) >
 <!ATTLIST FindPaymentInstrument
  BrandId	CDATA	#REQUIRED
  ProtocolId	CDATA	#REQUIRED
  ProtocolBrandId	CDATA	#IMPLIED
  PayDirection	(Debit|Credit)	#REQUIRED
  CurrCodeType	NMTOKEN	'ISO4217-A'
  CurrCode	CDATA	#REQUIRED
  Amount	CDATA	#REQUIRED
  WalletID	CDATA	#IMPLIED>

FindPaymentInstrumentResponse Function is same both APIs.

CheckPaymentPossibilityResponse Function:
->ProtocolAmountPackagedContent
<-AmountPackagedContent
 Comment: See above comment(Generic(2))

StartPaymentConsumer Function:
->objectNameTobeCalledBack
<-CallBackFunction
<-CallBackLanguageList
 Comment:Call Back function depends on implementation. For example, The
 interfaces between COM and CORBA(IDL) are different because COM needs
 to set two parameters, class ID and interface ID, on the other hand,
 CORBA(IDL) needs to set single parameter, object name. I suggest
 we add the new element, CallBack in this element and the attributes
 (parameters) of CallBack element should be set in the implementation
  specific API such as COM and CORBA(IDL).

<-DatabaseFunction
 Comment:To unify and manage the database of Payment Bridge is actually
 impossible though this is ideal, because we can not foresee the all
 elements to use in the every payment bridges. I suggest this should be
 dropped.

StartPaymentConsumerResponse Function:
->ContentSoftwareId
 Comment: See above(Generic(1)).

StartPaymentPaymentHandler Function:
->MerchantOrgId
 Comment: This needs when we want to manage the payment fee for
 each account of Merchant by Scheme Specific Payment Servers.

->ObjectTobeCalledBack
<-CallBackFunction
<-CallBackLanguageList
<-DatabaseFunction
 Comment:See above comment in StartPaymentConsumer.

StartPAymentPaymentHandlerResponse Function:
->ContentSoftwareId
 Comment: See above(Generic(2)).

ContinueProcess Function:
->ProcessType
 Comment:We need to distinct between "Inquiry" and "Payment", because
 we can not distinguish both transaction if the Inquiry Transaction has
  processed while the Payment Transaction, which has the same
 transaction id with the Inquiry Transaction, is in progress.  There is
 a problem when the Inquiry Transaction is occurred error for any
 reasons.

--
<!ATTLIST ContinueProcess
...
ProcessType	NMTOKEN   #REQUIRED
... >

ProcessType can select "Inquiry" or "Payment".
--

->ContentSoftwareId
 Comment: See above(Generic(2)).

ResumePaymentConsumer Function:
<-DatabaseFunction
 Comment:See above comment in StartPaymentConsumer.

ResumePaymentConsumerResponse Function:
->ContentSoftwareId
 Comment: See above(Generic(2)).

ResumePaymentPaymentHandler Function:
<-DatabaseFunction
 Comment:See above comment in StartPaymentConsumer.

ExpandPaymentReceiptResponse Function:
->protocolBrandId
->ProtocolTransId

 Comment: ProtrocolBrandId, and ProtocolTransId which is the scheme
 specific transaction ID such as SET LID_M, should be added because
 these may be used to display. ProtocolTrandId may be used the
 content of Payment Receipt Component.

-- See IOTP Spec 7.11(PayReceipt Component):
  Typically the content of a Payment Receipt Component will contain data
  which describes:
      o internal reference numbers which identify the payment to
        the payment system
--

InquireProcessStateResponse Function:
->ContentsSoftwareId
 Comment: See above(Generic(2)).

ChangeProcessState Function:
->ProcessType
 Comment: See above description in ContinueProcess.

RemovePaymentLog API:
(*This API exist in the SMILE document ONLY.*)
 Comment: This API needs to remove the payment related logs in the
 Payment Bridges.

PaymentInstrumentInquiry Function:
->xml:lang
 Comment:This needs to apply the language code to Value of
 unavailablePropertyList or/and the Property Description in
 payInstProperties.

QuitPaymentInstrument API:
(*This API exist in the SMILE document ONLY.*)
 Comment:This API needs to quit the Payment Instrument(Existing
 Software), especially when the Existing Software is implement 
as execution module(such that *.exe style).

CancelPayment API:
(*This API exist in the SMILE document ONLY.*)
 Comment:In some payment scheme, the Merchant server needs to notify
 the Payment server before sending an OfferResp message in order to
 make the Payment server ready for payment.
 If the Client cancels the transaction when the invoice(Content of
 Order Component) is displayed, the Merchant server needs to notify
 the Payment server that the payment is cancelled.  This is why the
 CancelPayment function is necessary in the Merchant payment bridge.

SetParentWindow API:
(*This API exist in the SMILE document ONLY.*)
 Comment:This function is passed the handle of the window of an IOTP
 Core Application to Payment Bridges. All windows of the Payment
 Bridges will be the children of the IOTP window.

ManagePaymentSoftware API: We dropped this.
CallBack API: We dropped this.
AccessDataBase API: We dropped this.

>>>>> Tue, 21 Sep 1999 18:29:11 -0400,

---

From: Werner Hans <[email-masked]>
Date: Tue, 28 Sep 1999 17:13:44 +0200

Hi Yoshiaki,

thanks for your remarks. You find my comments below.
Further discussion is needed on the topics marked with "deferred".

Werner

-----Ursprüngliche Nachricht-----
Von: Yoshiaki KAWATSURA [mailto:[email-masked]]Im Auftrag
von Yoshiaki KAWATSURA
Gesendet: Dienstag, 28. September 1999 07:54
An: [email-masked]; [email-masked]
Cc: [email-masked]; [email-masked]
Betreff: Re: iotpar101c.zip

Werner and Don,

----------------------
Generic(1):
Why have you drop the ContentSoftwareId throughout your document?  I
think this ID should be set in the Payment Bridge because
PackagedContents are generated behind the Payment Bridge.
***This attribute is returned by the Payment Bridge in the top level wrapper
"IotpPaymentAPIResponse" (cf. Chapter 9).***

Generic(2):

-> : There ONLY exists the Element in SMILE's API.
<- : There ONLY exists the Element in Hans' API.
***Agreed. In the past I thought this name would be too long.***

***Agreed.***

-> MerchantOrgId
 Comment:This needs when more than one Merchants exist in the IOTP
 Merchant Server (and Mall).
***Deferred. Do we really need this item? Separation between merchants is
possible by different wallet identifiers. At the client side, multiple
consumers might use the same SET wallet. They as well as their data are
distinguished by different wallet identifiers.
MerchantOrgds might be encoded in these identifiers.***

-> MerchantData

***Deferred. Does the IOTP Payment Bridge resp. Existing Payment Software
directly access the mall system? I believe, that this has to be done by the
IOTP Application Core.***
FindAcceptedPayBrandResponse Function:
-> ContentSoftwareId
 Comment: See above(Generic(2)).

->MerchantData

***Design decision: The serialization by two calls was intended to decrease
the possible huge complexity of finding the valid payment instruments at the
client side. The first function should filter out IOTP Payment Bridges that
do not support a brand for any payment protocol. E.g., having three Payment
Bridges each for Mondex(-Mondex), Mastercard-SET, and Mastercard-SCCD. With
your proposal, you have to issue three calls to each of the three Payment
Bridges but only six calls to infer the supported brands and one further
call for Mondex or two for the other schemes with the previous scheme. The
situation might get even worse with more payment alternatives and more
registered payment bridges. However, in situations with few Payment Bridges
your design performs better.
Note that the internal complexity of the first call is at the implementer's
choice.
Another design decision deals with your input parameter ProtocolId. By
providing this as an input parameter, the API function must be called for
each accepted payment protocol. E.g., one Payment Bridge supporting both
Mastercard-SET and Mastercard-SCCD must be requested twice while one call
suffices in the previous approach.
The time of presentment of the ProtocolBrandId seems to be a pure design
decision, due to the one to one relationship with the ProtocolId, if
present. I deferred the presentment to GetPaymentInitializationData because
such this ID might be stored in a chip card whose insertion should be
deferred as long as possible for user friendliness.
Other opinions?***

***How do you manage/encode the CallBackLanguageList? This (logical)
attribute does not depend on the actual implementation technique. Do you
have something like a InterfaceSchemePackagedContent in mind?***

<-DatabaseFunction

***Maybe, I am not sure about this.***

->ObjectTobeCalledBack
<-CallBackFunction
<-CallBackLanguageList
<-DatabaseFunction

***Although I believe, that the Payment Bridge will be able to distinguish
between both cases by the analysis of the packaged scheme specific data -
e.g., in SET, I will apply your proposal, i.e. ProcessType (Payment|Inquiry)
'Payment'.***

->ContentSoftwareId

***Agreed. When adding protocol related items, I suggest to add ProtocolId,
too.***

RemovePaymentLog API:

***This function is subsumed by the AcessDataBase function.***

***Agreed.***

CancelPayment API:

***Both functions seem to be subsumable by the ChangeProcessState function
because they define a final process state. I assume that
QuitPaymentInstrument is used to close a successful or successless
payment/inquiry. ChangeProcessState might even be used by the merchant to
cancel a transaction. The subsequent behaviour seems to be payment scheme
specific. I added possible support of this function by the Merchant to Table
2.***

SetParentWindow API:

***This seems to be very OS specific, although it enables seamless
integration of the Payment Bridge's user interface.***

***Deferred: How do you support the registration of new payment instruments
or their management - even in the absence of any payment. Does the user have
to access the native Existing Payment Software or can they use some kind of
invocation mechanism of the IOTP Application Core?***

CallBack API: We dropped this.
***Maybe. Progress indication has to be visualized by the Payment Bridge
with the risk that each Payment Bridge uses its own mechanisms for
visualization with the worst result the visual appearance differs with each
payment scheme (brand).***

AccessDataBase API: We dropped this.
***Maybe.
I applied all the agreed changes but will await your comments on error
reporting and failure processing. You will recognize that I scaled down the
discussion and rely extremely on the discussion of the function
specification. Another open topic from my point is the detailed processing
of resumption, particular synchronisation of both parties' points of view.
Maybe, I will drop this topic, completely.***

---

From: Yoshiaki KAWATSURA <[email-masked]>
Date: Wed, 29 Sep 1999 17:07:15 +0900 (JST)

Werner,
My comments are embedded between  **YK** and **YK END**.

(No.1)
---------------------------

-> MerchantData

**YK**
Some Payment Specific Systems need the Merchant Related Data in the
Initiation (and this data is included in the ProtocolPackagedContent
Component).  We separate the MerchantOrgId from MerchantData because
this is common attribute.  As to the MerchantPayId which is in
StartPaymentPaymnetHandler, the WalletId may be able to use instead.
**YK END**
----------------------------

(2)
----------------------------

**YK**
The PaymentBrandId depends on both Protocol and Brand.  In SET, this
ID needs for getting the Instrument ID so this has to be passed it in
FindPaymentInstrument. so The time of presentment of the
ProtocolBrandId is not a pure design decision evenif these have the
one to one relationship with the ProtocolId. So I strongly suggest
these API should merge.
**YK END**

FindPaymentInstrumentResponse Function is same both APIs.
---------------------------

(3)
--------------------------

**YK**
Yes. I think CallBackLanguageList is one of the method of the callback 
object.
**YK END**
--------------------------

(4)
-------------------------

***Although I believe, that the Payment Bridge will be able to distinguish
between both cases by the analyse of the packaged scheme specific data -
e.g., in SET, I will apply your proposal, i.e. ProcessType (Payment|Inquiry)
'Payment'.***

ProcessType can select "Inquiry" or "Payment".
--
**YK**
The Payment Bridge may be not able to analysis of the packaged data
when payment protocol message are encripted by the payment system.
**YK END**

------------------------

(5)
-----------------------
RemovePaymentLog API:

**YK**
Yes, but the AccessDataBase function should be dropped.
**YK END**

-------------------------

(6)
-------------------------

CancelPayment API:

**YK**
No. 
For QuitPaymentInstrument API,
we assume that the Consumer want to cancel or Error is occurred before
the IOTP Application Core calls the StartPaymentConsumer function to the
Payment Bridge.  Then, then the IOTP Application Core can not call the
ChangeProcessState to the Payment Bridge because IOTP Application Core
has not created the ConsumerPayId yet. So, this API is used by the
Consumer ONLY before the IOTP Application Core send the
StartPaymentConsumer message to the Payment Bridge.

For CancelPayment API,
this API is used by Merchant ONLY. The Merchant cannot use 
the ChangeProcessState API because there is no MerchantPayId element in 
the ChangeProcessState Function. 
On the other aspect, if the Payment Bridge receives the
ChangeProcessState function which is not included the ConsumerPayId or
is included new ConsumerPayId, the Payment Bridge return error message
to OAC.
**YK END**

-----------------------

(7)
----------------------
SetParentWindow API:

**YK**
Yes, it's very OS specific, but some APIs have to be OS
dependent. Such APIs should be defined for each OS.
**YK END**
------------------------

(8)
-----------------------

**YK**
In fact, we cannot understand how to use this function because it
seems to make the IOTP core registers ProtocolId and BrandId, etc. to
Payment Bridges, but Payment Bridges must know which Brands and
Protocol can be handled.  Therefore, we use the Windows registry to
register payment bridge information such as object names or object
identifier especially to create payment bridge objects before calling
them.
**YK END**
------------------------

**
specification. 
**
**YK**
O.K.
**YK END**

**
Another open topic from my point is the detailed processing
of resumption, particular synchronisation of both parties' points of view.
Maybe, I will drop this topic, completely
**
**YK**
Agreed.
**YK END**

----

>>>>> Tue, 28 Sep 1999 17:13:44 +0200,

---

From: Yoshiaki KAWATSURA <[email-masked]>
Date: Thu, 30 Sep 1999 19:36:40 +0900 (JST)

The followings are the (current) SMILE specific Payment API.
All API functions have empty response functions.

<!ELEMENT QuitPaymentInstrument EMPTY>
<!ATTLIST QuitPaymentInstrument
     PaymentInstrumentId	CDATA	#REQUIRED>

<!ELEMENT CancelPayment EMPTY>
<!ATTLIST CancelPayment
          MerchantPayId   CDATA   #REQUIRED
          ProcessState    (Failed |
			   ProcessError)	#REQUIRED >
         CompletionCode  NMTOKEN #IMPLIED>

<!ELEMENT RemovePaymentLog EMPTY>
<!ATTLIST RemovePaymentLog
          PayId  CDATA  #REQUIRED>

Thanks,
----