Request for Comments: 3538 Hitachi
Category: Informational June 2003
Secure Electronic Transaction (SET) Supplement for the
v1.0 Internet Open Trading Protocol (IOTP)
Status of this Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved.
Abstract
This document describes detailed Input/Output parameters for the
Internet Open Trading Protocol (IOTP) Payment Application Programming
Interface (API). It also describes procedures in the Payment Bridge
for the use of SET (SET Secure Electronic Transaction) as the payment
protocol within Version 1.0 of the IOTP.
Table of Contents
1. Introduction....................................................3
1.1 Objectives of this Document.................................3
1.2 Scope of this specification.................................3
1.2.1 The version of IOTP specification.....................3
1.2.2 The version of SET specification......................4
1.2.3 The version of IOTP Architecture document.............4
1.3 Audience....................................................4
1.4 Notation....................................................4
1.5 Terminology.................................................4
2. Requirements & Development Policy...............................4
3. Business Models.................................................5
3.1 Entity models between SET and IOTP..........................5
3.2 Role of Participants........................................5
3.3 Scope of Transaction Types..................................6
3.4 Types of transaction not in scope...........................6
4. Architecture of SET/IOTP........................................7
5. Trading Types of SET/IOTP.......................................7
5.1 Baseline Purchase...........................................7
5.2 Cash Advances...............................................8
5.3 Status Inquiry .............................................8
6. General Flow of SET/IOTP........................................8
6.1 Baseline Purchase...........................................9
6.1.1 Brand Independent Baseline Purchase...................9
6.1.2 Brand Dependent Baseline Purchase....................13
6.2 Cash Advances..............................................14
6.3 Status Inquiry.............................................15
7. IOTP Payment APIs..............................................16
7.1 Brand Compilation Related API Calls........................16
7.1.1 Find Accepted Payment Brand..........................16
7.1.2 Find Accepted Payment Protocol.......................17
7.1.3 Get Payment Initialization Data......................18
7.1.4 Inquire Authentication Challenge.....................19
7.1.5 Authenticate.........................................19
7.1.6 Check Authentication Response........................19
7.2 Brand Selection Related API Calls..........................20
7.2.1 Find Payment Instrument..............................20
7.2.2 Check Payment Possibility............................21
7.3 Payment Transaction Related API Calls......................22
7.3.1 Start Payment Consumer...............................22
7.3.2 Start Payment Payment Handler........................23
7.3.3 Resume Payment Consumer..............................24
7.3.4 Continue Process.....................................25
7.3.5. Change Process State................................26
7.4 General Inquiry API Calls..................................26
7.4.1 Payment Instrument Inquiry...........................26
7.4.2 Inquire Pending Payment..............................26
7.4.3 Remove Payment Log...................................27
7.5 Payment Related Inquiry API Calls..........................27
7.5.1 Check Payment Receipt................................27
7.5.2 Expand Payment Receipt...............................27
7.5.3 Inquire Process State................................28
7.5.4 Start Payment Inquiry................................29
7.5.5 Inquire Payment Status...............................30
8. SET dependent Process..........................................30
8.1 Relationships between them for IOTP Purchase/Cash Advances.30
8.2 Definition of Identifiers..................................31
8.2.1 Definition of BrandId................................31
8.2.2 Definition of ProtocolBrandId........................31
8.2.3 Definition of ProtocolId.............................33
8.2.4 Relationship between Ids.............................33
8.3 Process prior to Payment...................................34
8.3.1 FindAcceptedPaymentProtocol Function.................34
8.3.2 FindPaymentInstrument Function.......................35
8.3.3 GetPaymentInitializationData Function................36
8.4 Process of Payment.........................................37
8.4.1 StartPaymentConsumer Function........................37
8.4.2 StartPaymentPaymentHandler Function..................41
8.4.3 ContinueProcess Function (Consumer Side).............42
8.4.4 ContinueProcess Function (Payment Handler Side)......43
8.4.5 InquireProcessState Function.........................45
8.5 Payment Receipt............................................45
8.5.1 CheckPayReceipt Function.............................45
8.5.2 ExpandPayReceipt Function............................45
8.6 Status Inquiry.............................................46
8.7 Resume Process.............................................47
8.8 SET Scheme Specific Authentication on IOTP.................47
8.9 SET Bridge ProcessState....................................48
8.9.1 SET Bridge ProcessState of Consumer..................48
8.9.2 SET Bridge ProcessState of Payment Handler...........49
8.10 Relationship between Pay Step and Deliv Step on SET/IOTP..49
8.11 Completion Code...........................................50
8.12 PercentComplete...........................................50
8.13 Severity..................................................51
9. Error Handling.................................................51
9.1 Types of Errors............................................51
9.2 IOTP Level Error (OAC Error)...............................52
9.3 IOTP Level Error (SET Bridge Error)........................52
9.4 SET Level Error (SET Technical Error)......................52
9.4.1 SET Initiation Error.................................52
9.4.2 SET Transaction Error................................53
9.5 SET Level Error (SET Business Error).......................53
10. Security Considerations.......................................54
11. References....................................................54
12. IANA Considerations...........................................55
13. Acknowledgement...............................................55
14. Author's Address..............................................55
15. Full Copyright Statement......................................56
1. Introduction
This chapter describes the outline of this document.
1.1 Objectives of this Document
This document describes how SET (SET Secure Electronic Transaction)
works within the IOTP (Internet Open Trading Protocol).
1.2 Scope of this specification
1.2.1 The version of IOTP specification
This document is written based on IOTP Version 1.0 [RFC2801].
1.2.2 The version of SET specification
This document is written based on SET Version 1.0 [SET].
1.2.3 The version of IOTP Architecture document
This document is written based on IOTP Payment API document Version
1.0 [IOTP Payment API].
1.3 Audience
This document is indented for readers who are familiar with the
following documents:
1) IOTP Specification Version 1.0 [RFC2801]
2) SET Specification, in particular Book 2:Programmer's Guide and
Book3:Formal Protocol Definition,
3) External Interface Guide to SET Secure Electronic Transaction
4) Internet Open Trading Supplement: Architecture and Payment API
[IOTP API]
1.4 Notation
SET Messages and Elements are described with the prefix "SET".
Examples:
SET PRes
SET OD
SET SaleDetail
1.5 Terminology
This document uses the following terms:
SET/IOTP The specification described in this document.
SET related message Both SET Messages and SET Initiation Messages
2. Requirements & Development Policy
This chapter describes the requirements and development policies of
SET/IOTP.
The requirements of SET/IOTP are as follows:
o To be based on SET specifications. Interoperability at the
payment level must be maintained.
o To not enforce modifications which are specific to SET/IOTP.
General features of IOTP should not be tampered with to cater to a
particular payment method.
o To keep integrity between IOTP and SET. Inconstancy must not be
raised between IOTP and SET elements when they have the same
meaning.
The development policy of SET/IOTP is as follows:
o To minimize the number of message round trips
o To minimize the length of messages
3. Business Models
This chapter describes the difference in entity models between SET
and IOTP, the definitions of Trading Roles in SET/IOTP, and the scope
of SET/IOTP.
3.1 Entity models between SET and IOTP
The following table describes how SET and IOTP entities correspond to
each other.
| IOTP Entity SET Entity |
| ------------------------------------------------ |
| Consumer <---> Card Holder |
| Merchant <---> Merchant (Initiation) |
| Payment Handler <---> Merchant (Payment) |
| Delivery Handler<---> None |
| None <---> Acquirer |
Figure 1 Entity Models between SET and IOTP
3.2 Role of Participants
The following table describes the trading roles in SET/IOTP.
Trading Roles Role
-------------------------------------------------------------
Consumer An Individual who purchases goods and/or
services, and pays for the value received
by choosing a SET Transaction. This
individual corresponds with the
CardHolder in SET.
Merchant An organization that provides goods and/or
services for purchase, accepts payment
methods, delivers invoices and triggers
payment processes.
Payment Handler An organization that processes negotiations on
payments including SET payment transactions.
Delivery Handler An Organization that ships digital or physical
goods to the Consumer.
Customer Care The same as in [RFC2801].
Provider
Merchant Care The same as in [RFC2801].
Provider
3.3 Scope of Transaction Types
The types of IOTP transactions that are supported in this document
are as follows:
o Brand Independent Baseline Purchase when SET is used for payment
o Brand Dependent Baseline Purchase when SET is used for payment
o Cash Advances (Brand Independent and Brand Dependent case)
o Status Inquiry on SET payments
3.4 Types of transaction not in scope
The types of transactions that are NOT covered in this document are
as follows:
o Credit Reversal Process
o Customer Care Service with Consumer Related SET Certificate
Registration
o Customer Care Service with Consumer Related SET Certificate
Registration Inquiry
4. Architecture of SET/IOTP
SET/IOTP Architecture is as follows:
IOTP client (Consumer) <---------------> IOTP server (Merchant)
^ Internet ^
| IOTP Payment | IOTP Payment
| API | API
v v
IOTP/Payment Bridge IOTP/Payment Bridge
^ ^
| Existing Payment APIs, e.g., |
| SET, Mondex, etc. |
v v
Existing Payment Software Existing Payment Software
Figure 2 SET/IOTP Architecture
IOTP Application Core (OAC): Software that processes IOTP messages.
IOTP Payment Bridge (OPB): Interface between OAC and Existing Payment
Software. SET Bridge is also an interface between OAC and SET Core.
Existing Payment Software (EPS): Existing Software that processes
Payments. The SET Core is software that supports mechanisms in SET
specification from Book1 to Book3. EPS does NOT necessarily have to
implement the SET Initiation Processor, which is specified in SET
EIG. SET Related Module Both SET related OPB and EPS.
5. Trading Types of SET/IOTP
This chapter describes the outline of SET/IOTP trading types.
5.1 Baseline Purchase
Three steps will take place in a Baseline Purchase in the following
order:
(1) Offer Step
Consumer selects goods/services over the Internet, for instance on
the web, and then chooses the payment method (SET is selected), the
SET brand, the payment currency, and then confirms the invoice.
There are two Offer Process types, Brand Independent and Brand
Dependent.
(1-a) Brand Independent Purchase
In a Brand Independent Purchase, the Merchant sends the TPO Block and
Offer Response Block simultaneously after the consumer's purchase
decision. The Brand Independent Purchase has the merit of
eliminating one round of messages compared with the Brand Dependent
Purchase because the contents of the Offer Response Block (for
example, the description on the invoice) do not change based on the
selected brand.
(1-b) Brand Dependent Purchase
Brand Dependent Purchase is used when the contents of the Offer
Response Block are dependent on the selected Payment Brand. With
this method, the currency selection and discounts based on payment
method can be implemented.
(2) Payment Step
The Consumer confirms the order and then pays for the order with a
SET Transaction. The SET Transaction messages will be encapsulated
in IOTP Messages.
(3) Delivery Step
After completing the Payment, the Consumer receives the
goods/services via either on-line or physical delivery.
5.2 Cash Advances
Cash Advances can be made via a Value Exchange Transaction in IOTP. A
first Payment by SET and a second Payment by some other payment
mechanism is supported in Baseline IOTP. The Cash Advance has two
types - Brand Independent and Brand Dependent Cases.
5.3 Status Inquiry
A Consumer can send a SET Payment Inquiry in IOTP. The SET Message
is encapsulated in an IOTP Message.
6. General Flow of SET/IOTP
This chapter illustrates the general SET/IOTP message flows.
6.1 Baseline Purchase
Baseline purchases consist of two types, Brand Independent Purchase
and Brand Dependent Purchase. Each type is illustrated in the charts
below.
6.1.1 Brand Independent Baseline Purchase
The general flow of a Brand Independent Purchase is as follows:
(1) Consumer Side (Before PayRequest Message)
SET Core SET Bridge OAC
| | | TPO & OfferResp message
| | |<------------------- From
| |<------------| Merchant
| | FindPayment |
| | Instrument|
| |------------>|
| | Response |
| |<------------|
| | CheckPayment|
| | Possibility|
| |------------>|
| | Response |
| |<------------|
|<------------| StartPayment|
|------------>| Consumer|
| |------------>| PayRequest Message
| | Response |-------------------> To Payment
(SET Init Resp/ Handler
SET PInitReq)
Figure 3 Consumer Side for Brand Independent (1)
(2) Consumer Side (After PayRequest Message)
SET Core SET Bridge OAC
| | | Pay Exch Message
| | |<------------------- From
| SET PInitRes|<------------| (SET PInitRes) P.H.
|<------------| Continue |
|------------>| Process |
| SET PReq |------------>| Pay Exch Message
| | Response |-------------------> To P.H.
| | | (SET PReq)
| | | Pay Exch Message
| | |<------------------ From P.H.
| SET PRes |<------------| (SET PRes)
|<------------| Continue |
|------------>| Process |
| |------------>|
| |Response[END]|
| |<------------|
| | CheckPayment|
| | Receipt |
| |------------>|
| | Response |
| |<------------|
| |ExpandPayment|
| | Receipt |
| |------------>|
| | Response |
| |<------------|
| |ChangeProcess|
| | State |
| |------------>|
| | Response |
Figure 4 Consumer Side flow for Brand Independent (2)
(3) Merchant Side
OAC SET Bridge
|--------------->|
|FindAccepted |
| PaymentBrand |
|<---------------|
| Response |
|--------------->|
|FindAccepted |
| PaymentProtocol|
|<---------------|
| Response |
|--------------->|
|GetPaymentInit- |
| lizationData |
TPO & Offer Resp Msg. |<---------------|
<------------------------| Response |
To Consumer
Figure 5 Merchant Side flow for Brand Independent
(4) Payment Handler Side.
OAC SET Bridge SET Core
PayRequest Message | | |
From ---------------------->| | |
Consumer (SET Init Res/ |--------------->| |
SET PInitReq) |StartPayment |------------>|
| PaymentHandler |<------------|
PayExch Message |<---------------| |
To <----------------------| Response | |
Consumer (SET Init Req/ . . .
SET PInitRes) . . .
PayExch Mssage | | |
---------------------->| | |
From Consumer (SET PReq) |--------------->| SET PReq |
| Continue |------------>|
| Process |<------------|
|<---------------| SET PRes |
| Response | |
|--------------->| |
| Inquire | |
| ProcessState | |
|<---------------| |
| Response | |
|--------------->| |
| ChangeProcess | |
| State | |
PayResponse Message |<---------------| |
<------------------------| Response | |
To Consumer (SET PRes)
Figure 6 Payment Handler side flow for Brand Independent
6.1.2 Brand Dependent Baseline Purchase
The general flow of a Brand Dependent Purchase is as follows:
(1) Consumer Side (Before PayRequest Message)
SET Core SET Bridge OAC
| | | TPO message
| | |<------------------- From
| |<------------| Merchant
| | FindPayment |
| | Instrument|
| |------------>|
| | Response |
| |<------------|
| | CheckPayment|
| | Possibility|
| |------------>| TPO Selection Msg.
| | Response |-------------------> To Merchant
| | |<------------------ From Merchant
| |<------------| Offer Response Msg.
|<------------| StartPayment|
|------------>| Consumer|
| |------------>| PayRequest Message
| | Response |-------------------> To Payment
(SET Init Resp/ Handler
SET PInitReq)
Figure 7 Consumer Side flow for Brand Dependent (1)
(2) Consumer Side (After PayRequest Message)
This flow is the same as Brand Independent.
(3) Merchant Side
OAC SET Bridge
|--------------->|
|FindAccepted |
| PaymentBrand |
|<---------------|
| Response |
|--------------->|
|FindAccepted |
| PaymentProtocol|
TPO Message |<---------------|
<------------------------| Response |
To Consumer | |
TPO Selection Message | |
------------------------>| |
From Consumer |--------------->|
|GetPaymentInit- |
| lizationData |
Offer Response Message |<---------------|
<------------------------| Response |
To Consumer
Figure 8 Merchant Side flow for Brand Dependent (1)
(4) Payment Handler Side
This flow is the same as Brand Independent.
6.2 Cash Advances
IOTP Cash Advances processes can be made with a credit card using an
IOTP Value Exchange Transaction. In Cash Advances a first Payment by
a SET Transaction, and a second Payment by some other payment
mechanism, is supported in Baseline IOTP. The general flow is
omitted.
6.3 Status Inquiry
The general flow of a Status Inquiry is as follows:
(1) Consumer Side
SET Core SET Bridge OAC
| | |
| | |
| |<------------|
|<------------| StartPayment|
|------------>| Inquiry|
| SET InqReq |------------>| Inquiry Request
| | Response |-------------------> To P.H.
| | | (SET InqReq)
| | |
| | | Inquiry Response
| | |<------------------- From P.H.
| | | (SET InqRes)
| SET Inq Res |<------------|
|<------------| Continue |
|------------>| Process|
| SET InqReq |------------>|
| | [End] |
| |ChangeProcess|
| | State|
| |<------------|
|<------------|
Figure 9 Consumer Side flow for Status Inquiry
(2) Payment Handler Side
OAC SET Bridge SET Core
InquiryReq message | | |
From ------------------------>| | |
Consumer (SET InqReq) |------------->| |
|InquirePayment|------------>|
| Status| SET InqReq |
| |<------------|
| | SET InqRes |
InquiryResp message |<-------------| |
To <------------------------| Response | |
Consumer (SET InqRes) |
Figure 10 Payment Handler Side flow for Status Inquiry
7. IOTP Payment APIs
This section provides a summary of SET/IOTP interactions with API
calls as in [IOTP Payment API].
The description of parameters hereafter are written as follows:
Parameter name : Mandatory (M) or Optional (O) : Description
For more details on the IOTP Payment APIs, see [IOTP Payment API].
"-" in the Description is the same as description in the [IOTP
Payment API].
Notice: Status is the status of SET/IOTP. Though some Fields are
specified "#IMPLIED" in [IOTP Payment API], if the fields must be
used in SET/IOTP, this document specifies the status as Mandatory,
(M).
7.1 Brand Compilation Related API Calls
7.1.1 Find Accepted Payment Brand
Receive the payment scheme specific packaged data to generate Brand
Component. In this version of SET/IOTP, This API must be called
before Find Accepted Payment Protocol function.
Input Parameters
----------------
PayDirection : M : This must be set "Debit".
CurrCodeType : M : This should be set "ISO4217-A".
CurrCode : M : -
Amount : M : -
MerchantPayId : M : -
MerchantOrgId : M : -
WalletId : O : -
MerchantData : O : The details are not specified in
this document.
Output Parameters
-----------------
BrandItem : M : See NOTE below.
NOTE: Parameters of BrandItem
-----------------------------
BrandId : M : This is defined in the section 8.2.1.
xml:lang : M : -
BrandName : M : Brand Name, such as "MasterCard".
BrandLogoNetLocn : M : -
BrandNarrative : O : This is not specified in this document.
BrandPackaged : O : This is not used in the SET/IOTP.
Content
7.1.2 Find Accepted Payment Protocol
Receive the payment scheme specific packaged data to generate the
PayProtocol Component.
Input Parameters
----------------
BrandId : M : This is defined in the section 8.2.1.
PayDirection : M : This must be set "Debit".
CurrCodeType : M : This should be set "ISO4217-A".
CurrCode : M : -
Amount : M : -
MerhcantPayId : M : -
MercahntOrgId : M : -
WalletId : O : -
BrandPackaged : O : This is not used in the SET/IOTP.
Content
MerchantData : O : This is not specified in the SET/IOTP.
Output Parameters
-----------------
ProtocolItem : M : See NOTE below.
BrandItem : M : -
NOTE Parameters of ProtocolItem
-------------------------------
ProtocolId : M : This is set "SETv1.0".
ProtocolBrandId : M : This is set the Payment Protocol Specific
ID corresponding to the BrandId as Input
Parameter and ProtocolId as the
Output Parameter. For the detail,
see 8.2.2.
xml:lang : M : -
ProtocolName : M : This is not specified in this document
but must be included the protocol name
and its version at least.
PayReqNetLocn : O : The Net Location indicating where a
unsecured Payment Request Message should
be sent if this protocol choice is used.
SecPayReqNetLocn : O : The Net Location indicating where
a secured Payment Request Message
should be sent if this protocol choice
is used.
ProtocolAmount : O : This is not used in the SET/IOTP.
PackagedContent
PayProtocol : M : The XML Packaged Data, which includes
PackagedContent the information for the 1st SET
Initiation Process. See for the details
to section 8.3.1.
Brand : M : In this document, BrandId, which is the
same as Input Parameter,must be set ONLY.
See NOTE below.
CurrencyAmount : M : See NOTE below.
ProtocolBrand : M : Multiple Components are not arrowed in
the current version of SET/IOTP.
Note Parameters of CurrencyAmount
---------------------------------
CurrCodeType : M : This should be set "ISO4217-A".
CurrCode : M : -
Amount : M : -
Note Parameters of Brand
------------------------
BrandId : M : -
7.1.3 Get Payment Initialization Data
This API is used to get the packaged content in Payment Component.
Input Parameters
----------------
BrandId : M : See the details of section 8.2.1.
MerchantPayId : M : -
PayDirection : M : This is set "Debit".
CurrCodeType : M : This is set "ISO5217-A".
CurrCode : M : -
Amount : M : -
OkFrom : M : -
OkTo : M : -
ReceiverOrgId : M : Organization ID which is used to get
TradingRolePackagedContents, which
depend on the organizations for each.
MerchantOrgId : M : -
ProtocolId : M : This field must be set "SETv1.0".
WalletId : O : -
PassPhrase : O : -
ProtocolBrand : M : -
BrandPackaged : O : This is not used in the current version
Content of SET/IOTP.
ProtocolAmount : O : This is not used in the current version
PackagedContent of SET/IOTP.
PayProtocolPackaged: M : This field is copied from the
Content PayProtocol Component.
OrderPackaged : M : Packaged Data regarding the Order data,
Content which the Merchant's OAC sets.
BrandSelBrandInfo : O : This is not used in the current
PackagedContent version of SET/IOTP.
BrandSelProtocol : O : This is not used in the
AmountInfoPackaged current version of SET/IOTP.
Content
BrandSelCurrency : O : This is not used in the
AmountInfo current version of SET/IOTP.
PackagedContent
Output Parameters
-----------------
OkFrom : M : -
OkTo : M : -
OrderPackaged : M :Changed OrderPackagedContent if
Content it rewrites the order information.
Otherwise, passed the same input
data to OAC.
TradingRole : O : The receiver depended
PackagedContent TradingRolePackagedContent. The Name
Attribute of the packaged contents
must include "Payment:" as the prefix,
for example "Payment:SET-OD". Multiple
TradingRoleData may be returned.
7.1.4 Inquire Authentication Challenge
This is not used in the current version of SET/IOTP.
7.1.5 Authenticate
This is not used in the current version of SET/IOTP.
7.1.6 Check Authentication Response
This is not used in the current version of SET/IOTP.
7.2 Brand Selection Related API Calls
7.2.1 Find Payment Instrument
This API is used to get the Payment Instruments that can be accepted
by the Payment Handler on behalf of the Merchant.
Input Parameters
----------------
BrandId : M : See the details of section 8.2.2.
ProtocolId : M : This must be set "SETv1.0".
PayDirection : M : This must be set "Debit".
CurrCodeType : M : This should be set "ISO5217-A".
CurrCode : M : -
Amount : M : -
ConsumerPayId : M : -
WalletId : O : -
ProtocolBrand : M : -
BrandPackaged : O : This is not used in the current
Content version of SET/IOTP.
ProtocolAmount : O : This is not used in the current
PackagedContent version of SET/IOTP.
PayProtocolPackaged: M : See details for section 8.3.1.
Content
Output Parameters
-----------------
PayInstrument : M : Multiple PayInstrument Ids may
be returned. See NOTE below.
NOTE Parameters of PayInstrument
--------------------------------
Id : M : This must be unique each SET
Certificates which the
Consumer can use.
xml:lang : M : -
PayInstName : M : -
7.2.2 Check Payment Possibility
If the SET Bridge receives this API Message, the SET Bridge returns
three packaged content fields.
Input Parameters
----------------
BrandId : M : This is set the consumer selected
BrandId.
PaymentInstrumentId: M : This is set the consumer selected
PaymentInstrumentID.
PayDirection : M : This is set "Debit".
CurrCodeType : M : This is set "ISO4217-A".
CurrCode : M : -
Amount : M : -
ProtocolId : M : This must be set "SETv1.0".
WalletId : O : -
Passphrase : O : -
ConsumerPayId : M : -
ProtocolBrand : M : This is set the consumer selected
ProtocolBrand Component.
BrandPackaged : O : This is not used in the current
Content version of SET/IOTP.
ProtocolAmount : O : This is not used in the current
PackagedContent version of SET/IOTP.
PayProtocol : M : This field is copied from the PayProtocol
PackagedContent Component
Output Parameter
---------------
BrandSelBrandInfo : O : This is not used in the current
PackagedContent version of SET/IOTP.
BrandSelProtocol : O : This is not used in the
AmountInfoPackaged current version of SET/IOTP.
Content
BrandSelCurrency : O : This is not used in the
AmountInfoPackaged current version of SET/IOTP.
Content
7.3 Payment Transaction Related API Calls
7.3.1 Start Payment Consumer
In SET/IOTP, this API is used for the Consumer's SET Bridge to
process the 1st SET Initiation and any subsequent SET messages.
Input Parameters
----------------
BrandId : M : ID for the consumer selected
Brand. See the details of
section 8.2.1.
PaymentInstrumentId: M : ID for the consumer selected
Instrument.
CurrCodeType : M : The consumer selected CurrCodeType.
CurrCode : M : The consumer selected CurrCode.
Amount : M : The consumer selected Amount.
PayDirection : M : Indicates the payment direction
from the Consumer's prospective.
ProtocolId : M : The consumer selected ProtocolId.
OkFrom : M : -
OkTo : M : -
ConsumerPayId : M : -
WalletID : O : -
Passphrase : O : -
CallBackFunction : O : This is not used in the SET/IOTP.
CallBackLanguage : O : This is not used in the SET/IOTP.
List
ProtocolBrand : M : ID for the consumer selected
Protocol dependent Brand information.
BrandPackaged : O : This is not used in the current
Content version of SET/IOTP.
ProtocolAmount : O : This is not used in the current
PackagedContent version of SET/IOTP.
PayProtocolPackaged : M : See section 8.2.2.
Content
Output Parameters
-----------------
ContStatus : M : "Continue" must be set if there is
in no problem
PaySchemePackaged : M : See section 6.5.1.
Content
7.3.2 Start Payment Payment Handler
This API is used to initiate a payment on the Payment Handler's side.
The SET Related Module does a payment initialization. The SET
Related Module processes SET Message received and returns the
appropriate SET Message (e.g., 2nd SET Initiation or SET PinitRes
message).
Input Parameters
----------------
BrandId : M : ID for the consumer selected Brand.
See the details of section 8.2.1.
ConsumerPayId : O : ID for the consumer generated payment
transaction.
CurrCodeType : M : The consumer selected CurrCodeType.
This should be set "ISO4217-A".
CurrCode : M : The consumer selected CurrCode.
Amount : M : The consumer selected Amount.
PayDirection : M : This is set "Debit".
ProtocolId : M : The consumer selected ProtocolId.
This must be set "SETv1.0".
OkFrom: : M : -
OkTo : M : -
PaymentHandlerPayId: M : -
MerchantOrgId : M : -
WalletID : O : -
Passphrase : O : -
CallBackFunction : O : This is not used in the SET/IOTP.
CallBackLanguage : O : This is not used in the SET/IOTP.
List
BrandPackaged : O : This is not used in the current
Content version of SET/IOTP.
ProtocolAmountP : O : This is not used in the current
PackagedContent version of SET/IOTP.
PayProtocolPackaged: M : -
Content
ProtocolBrand : M : Information for the consumer selected
Protocol dependent Brand.
BrandSelBrandInfo : O : This is not used in the current
PackagedContent version of SET/IOTP.
BrandSelProtocol : O : This is not used in the
AmountInfo current version of SET/IOTP.
PackagedContent
BrandSelCurrency : O : This is not used in the
AmountInfo current version of SET/IOTP.
PackagedContent
TradingRolePackaged: O : Copied from the TradingRoleData
Content Component. The Name Attribute of
the packaged contents must include
"Payment:" as the prefix,
for example "Payment:SET-OD".
PaySchemePackaged : M : See section 6.5.2.
Content
Output Parameters
-----------------
PaySchemePackaged : M : See section 6.5.2.
Content
ContStatus : M : "Continue" must be set if there
is no problem.
7.3.3 Resume Payment Consumer
This API is used to restart a payment transaction when the
transaction is suspended for some reason such as a time out. The
last SET Message relevant to this suspended transaction is returned
as the Response.
Input Parameters
----------------
ConsumerPayId : M : -
WalletId : O : -
PassPhrase : O : -
CallBackFunction : O : This is not used in the current version
of SET/IOTP.
CallBack : O : This is not used in the current version
LanguageList of SET/IOTP.
Output Parameters
-----------------
ContStatus : M : -
PaySchamePackaged : M : See section 8.7.
Content
7.3.4 Continue Process
This API is used to pass a SET related message, received from the
counter party, to the SET Bridge, and accept the next SET message as
a response.
(1) Consumer Side Payment Bridge
Input Parameters
----------------
PayId : M : Set ConsumerPayId
WalletId : O : -
PassPhrase : O : -
PaySchemePackaged : M : See section 8.4.3.
Content
Output Parameters
-----------------
ContStatus : M : Set "End" if SET PRes message is
received in the PaySchemePackagedContent
as the input parameter, otherwise set
"Continue".
PaySchemePackaged : O : If ContStatus is set "End", this is not
Content used. See 8.4.3.
(2) Payment Handler Side Payment Bridge
Input Parameters
----------------
PayId : M : Set PaymentHandlerPayId
WalletId : O : -
PassPhrase : O : -
PaySchemePackaged : M : See section 8.4.4.
Content
Output Parameters
-----------------
ContStatus : M : Set "End" if SET PRes message is
received in the
PaySchemePackagedContent as the
output parameter, otherwise set
"Continue".
PaySchemePackaged : M : See section 8.4.4.
Content
7.3.5. Change Process State
This API is used by the OAC to change the Process State of the OPB.
For instance, it is used to change the Payment Status after a SET
Payment Transaction was completed. When an error or suspend happens,
this API is also used.
(1) Consumer Side Payment Bridge
Input Parameters
----------------
PayId : M : Set ConsumerPayId
ProcessState : M : -
CompletionCode : M : -
ProcessType : M : -
WalletID : O : -
PassPhrase : O : -
Output Parameters
-----------------
ProcessState : M : -
CompletionCode : M : -
PercentComplete : O : See section 8.13.
xml:lang : O : -
StatusDesc : O : This field is not specified in SET/IOTP.
7.4 General Inquiry API Calls
7.4.1 Payment Instrument Inquiry
This API is not used in the current version of SET/IOTP.
7.4.2 Inquire Pending Payment
This API is used to check whether the payment Bridge or its wallet is
currently in use, or not.
Input Parameters
----------------
WalletID : O : -
Output Parameters
-----------------
PayId : M : -
7.4.3 Remove Payment Log
This API is used both Consumer and Payment Handler.
Input Parameters
----------------
PayId : M : -
WallerId : O : -
Passphrase : O : -
There is no output parameters.
7.5 Payment Related Inquiry API Calls
7.5.1 Check Payment Receipt
This API is used to check a Payment Receipt. However since the
current SET specification does not support Receipts, SET/IOTP sends
its own visual information of a Receipt to the SET Bridge.
Input Parameters
----------------
PayId : M : -
WalletId : O : -
PassPhrase : O : -
PaySchemePackaged : M : See section 8.5.1.
Content
Output Parameters
-----------------
There is no output Parameter.
7.5.2 Expand Payment Receipt
This expands an IOTP Payment Receipt Component packaged data into a
form which may be used for display or printing purposes.
Input Parameters
----------------
PayId : M : -
WalletId : O : -
PassPhrase : O : -
PackagedContent : M : See section 8.5.2.
Output Parameters
-----------------
BrandId : M : -
ProtocolBrandId : M : -
PayInstrumentId : M : -
PaySchemePayId : M : LID_M in the SET PRes message is
set. (The format of this value must
be same as SET Initiation.)
Amount : M : Amount * AuthRatio (or CapRatio if
available). CapRatio should be the
high priority than AuthRatio.
CurrCodeType : M : -
CurrCode : M : -
PayDirection : M : -
ProtocolId : M : -
ProtocolTransId : O : -
TimeStamp : M : This value should be used the
Date field of MessageWrapper in the
SET PRes message
xml:lang : O : This is not used in the SET/IOTP.
ConsumerDesc : O : This is not used in the SET/IOTP.
PaymentHandlerDesc : O : This is not used in the SET/IOTP.
StyleNetLocn : O : This is not used in the SET/IOTP.
PaymentProperty : O : This is not used in the SET/IOTP.
7.5.3 Inquire Process State
This API is used to check the payment status. For example, when the
OAC receives a Continue Payment Response API, it uses this API if the
ContStatus is set to "End". This API can be used at anytime.
(1) Consumer Payment Bridge
Input Parameters
----------------
PayId : M : Set ConsumerPayId
WalletId : O : -
PassPhrase : O : -
Output Parameters
-----------------
ProcessState : M : -
PercentComplete : O : See 8.13 for the guideline of
setting value.
CompletionCode : O : See section 8.12.
xml:lang : O : -
StatusDesc : O : -
PayReceiptNameRefs : O : This is not used in the SET/IOTP.
PayReceiptPackConts: O : This is not used in the SET/IOTP.
(2) Payment Handler Payment Bridge
Input Parameters
----------------
PayId : M : Set PaymentHandlerPayId
WalletId : O : -
PassPhrase : O : -
Output Parameters
-----------------
ProcessState : M : -
PercentComplete : O : See section 8.13 for the guideline
of setting value.
CompletionCode : O : See section 8.12.
xml:lang : O : -
StatusDesc : O : -
PayReceiptNameRefs : O : This is set "PRes".
PayReceiptPackConts: O : This is not used in the SET/IOTP.
7.5.4 Start Payment Inquiry
This API call returns the SET InqReq Message in order to process a
SET Inquiry.
Input Parameters
----------------
ConsumerPayId : M : -
WalletId : O : -
Passphrase : O : -
Output Parameters
-----------------
PaySchemePackaged : M: Packaged Data to include SET
Content InqReq message. See section 8.6.
7.5.5 Inquire Payment Status
The Payment Handler uses this API request for Consumer initiated
inquiry processing. In SET/IOTP, the Payment Handler's SET Bridge
receives a SET InqReq message in an InquirePaymentDetail API. The
SET Core processes it, and creates a SET InqRes message. The
response encapsulates the SET InqRes message.
Input Parameters
----------------
PaymentHandlerPayId: M : -
WalletID : O : -
PassPhrase : O : -
PaySchemePackaged : M : See section 8.6.
Content
Output Parameters
-----------------
PaymentHandlerPayId: M : -
ProcessState : M : -
CompletionCode : O : -
xml:lang : O : -
StatusDesc : O : -
PaySchamePackaged : M : See section 8.6.
Content
8. SET dependent Process
This chapter describes the core concepts for the development of
SET/IOTP.
8.1 Relationships between them for IOTP Purchase/Cash Advances
This document describes SET Initiation Messages based on the [SET
EIG]. Merchant sends the 1st SET Initiation Message to the Consumer
in order to activate a SET payment transaction. After this message,
the other SET Initiation Messages (JPO, etc.) and the SET payment
Transaction (SET PinitReq message, etc.) are exchanged between the
Consumer and the Payment Handler.
+------------+ +----------+
| | | |
| |<----------------| Merchant |
| | 1st SET InitMsg | |
| | +----------+
| Consumer | +----------+
| | | |
| |<--------------->| P.H. |
| | Other SET Init/ | |
+------------+ SET Message +----------+
Figure 11 Relationship between IOTP Messages and SET Messages
When the Merchant sends any data (e.g., SET SaleDetail) except a SET
Related messages (e.g., SET PinitRes message), it can send it by two
different methods:
(a) The Merchant sends the data via the Consumer.
(b) The Merchant sends the data out-of-band.
In case (a), the Merchant sends the data by encapsulating it into
TradingRoleData.PackagedContent inside the Offer Response Block sent
to Consumer. The data is copied to the Payment Request Block and
sent to the Payment Handler. This case assumes that the format of
the data is already agreed upon between the Merchant and the Payment
Handler.
This document does not specify case (b).
8.2 Definition of Identifiers
8.2.1 Definition of BrandId
BrandId should be used registered identification for IANA. Now, the
following BrandIds have registered:
Amex, Dankort, JCB, Maestro, MasterCard, MICOS, VISA, atCredits,
EZpay, GeldKarte, Mondex, paybox
8.2.2 Definition of ProtocolBrandId
ProtocolBrandID is defined as follows:
<Premise> SET BrandID is defined as brand[:Product]. ([] is indicated
as optional.) In SET, The brandID is a brand name, which corresponds
to the brand of the payment card. Additionally the Product is a
product name, which is defined as the type of product within the
specific brand such as Gold Card.
Set IOTP ProtocolBrandId as follows:
brand:Product:PCN
In here,
o The brand above is the same as the sub data of SET BrandID, as
Brand Name (brand), defined in SET.
o Product above is the same as the sub data of SET BrandID, as
Product Name (Product), defined in SET.
o PCN above is the Promotional Card Name, and is written in the SET
Certificates.
Example:
Visa:Gold:WalMart
Since SET Brand ID has a colon between brand and Product, the two
colons should be able to delimit Brand, Product, and PCN.
Product and PCN can omit if necessary. For the detail of these
definitions are follows:
(1) The case of omitting Product
Definition: brand::PCN
Example: VISA::UC_VISA
(2) The case of omitting PCN
Definition: brand:Product
Example: VISA:Gold
(3) The case of omitting Product, PCN
Definition: brand
Example: VISA
Invalid Examples:
VISA:Gold:
VISA::
VISA:
ProtocolBrandId which there is no brand.
8.2.3 Definition of ProtocolId
Protocolld defines as follows:
ProtocolId := SETName + Version
SETName := "SET"
Version := "v" + version + "." + revision
Where the version is number matching a major SET version, and the
revision is the number matching a minor SET revision.
Example:
"SETv1.0","SETv2.0"
NOTE: In the current version of SET/IOTP, "SETv1.0" is fixed as
ProtocolId.
8.2.4 Relationship between Ids
ProtocolBrandId must be unique and depends on BrandId and ProtocolId.
The followings are map among BrandId and ProtocolId, which have
registered in IANA, and ProtocolBrandId.
BrandId ProtocolId ProtocolBrandId
-----------------------------------------
Amex SETv1.0 Amex
Dankort SETv1.0 Dankort
JCB SETv1.0 JCB
MasterCard SETv1.0 MasterCard
Nicos SETv1.0 Amex
VISA SETv1.0 VISA
Regarding to the BrandIds except above, the BrandId registrant (e.g.,
credit card company) MUST register it in order to be able to map one
to one between ProtocolBrandId and the pair of BrandId and
ProtocolId.
8.3 Process prior to Payment
8.3.1 FindAcceptedPaymentProtocol Function
(1) Parameter of PayProtocolPackagedContent
Name : O : This is not used in SET/IOTP.
Content : M : This should be set "PCDATA".
Transform : M : This is set "BASE64".
ContentData : M : SET specific protocol data. Includes data
that is used to create the 1st SET Initiation
Message that is not contained in other
IOTP elements.
(2) Parameter in the ContentData
Parameters of ContentData are described below. The Field Values
follow the [SET EIG].
Field Required
------------------------------------
MIME-Version Optional
Content-Transfer-Encoding Mandatory
SET-Initiation-Type Mandatory
SET-LID-M Optional
SET-InstallTotalTrance Optional
SET-Recurring Optional
SET-Ext-OID Optional
SET-Ext-Data Optional
SET-Ext-Mandatory Optional
SET-Echo-In-Response Optional
SET-Echo-In-Request Optional
For Example:
MIME-Version: 1.0
Content-Transfer-Encoding: Binary
SET-Initiation-Type: Payment-Initiation
SET-Recurring: 31 19960223
SET-Service-URL: http://www.custcare.com/index.html
SET-LID-M: 515A533033363632594B
Note: The contents in ProtoclPackagedContent must be US-ASCII and
encoded by BASE64.
8.3.2 FindPaymentInstrument Function
(1) Information of PayInstrument
Returns a list of Payment Instrument IDs related to the BrandId and
ProtocolBrandId. In this document, BrandId and ProtocolId are
defined in section 8.2.
In this document, Brand has two recognized meanings in SET/IOTP, as
follows:
Brand as Primary Brand:
The Primary Brand is the Brand which is defined as brand in SET,
such as VISA, MasterCard, Nicos.
Brand as Dual Brand or Promotional Brand:
The Dual Brand is the payment instrument which has two Brand, such
as UC-VISA (UC Card and VISA Card) This style is popular in Japan.
A Promotional Brand means that, if the Consumer pays with that
Brand, then the Consumer will receive some additional benefit such
as discount or frequent flyer point.
1. ProtocolBrandId as a Primary Brand
Example:
"MasterCard", "MasterCard::UC", "MasterCard:Gold:" and
"MasterCard::WalMart" are all MasterCard Brands.
2. ProtocolBrandId as a Dual Brand or a Promotional Brand
Example:
"MasterCard::UC" is Dual Brand of "MasterCard" and "UC".
"SET:MasterCard::WalMart" is Promotional Brand of MasterCard-
WallMart.
The SET Bridge receives the ProtocolBrandId from the OAC in the
FindPaymentInstrument Function,
(1) If the accepted ProtocolBrandId is XXX:YYY
The SET Related Module searches for ProtocolBrandIds with the
string "XXX:YYY:*" (* is wild card), the corresponding
PaymentInstrumentIds of all ProtocolBrandIds with the matching
Primary Brand (regardless of also being a Dual Brand or
Promotional Brand) will be returned to the OAC, for the Consumer
to select from.
(2) If the accepted ProtocolBrandId is XXX:YYY:ZZZ
The SET Related Module searches for ProtocolBrandIDs with the
string "XXX:YYY:ZZZ", only the corresponding PaymentInstrumentIds
of the ProtocolBrandIds that match the Dual Brand or Promotional
Brand will be returned to OAC, for the Consumer to select from.
Example:
Assume ProtocolBrandIds are correspond to PaymentInstrumentIds in
the SET Bridge as follows,
ProtocolBrandId PaymentInstrumentId
------------------------------------------
MasterCard 1
MasterCard::UC 2
MasterCard::WallMart 3
VISA::UC 4
If the SET Bridge receives a ProtocolBrandId as "MasterCard" in
the FindPaymentInstrument Function, the SET Bridge will return