UnionPay International Simulator Guide
(Version 2.0)
Chapter IV: Configuration Guide of Issuers
May 2015
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
Content
1. Configuration of Communication Parameters ................................................. 2
2. Acquirer Parameter Configuration ................................................................. 10
3. Issuer Parameter Configuration ..................................................................... 12
4. Other parameter Configuration ................................................................... 17
5. Summary: ....................................................................................................... 19
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
Chapter IV: Configuration Guide of Issuers
This chapter only introduces issuer parameter configuration. Acquirer configuration
method is descripted in Chapter II.
After users double click the ‘simulator.exe’ file, welcome page will pop out. Licensed
IIN will be displayed at the lower left corner of the page, which is unique for each
forwarding Institution.
The welcome page is showed as picture 0-1, Users should click the left button to
enter ‘Issuer Test Mode’. ‘Acquirer Test Mode’ on the right side is for acquirers only.
Picture 0-1: Simulator Welcome Page
1. Configuration of Communication Parameters
The first thing need to be done after entering Issuer Test Mode is competing
communication parameters. In order to do this, users shall open the communication
parameter page via ‘Main menu->Communication->Communication Parameter’ (see
the picture 1-1).
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
Picture 1-1: Communication Parameter Entry
Step 1: Click “Add Line” button to add a line (see the picture 1-2):
Picture 1-2: Communication Parameter Page
Step 2: The line configuration box pops out (picture 1-3). Users should be clear about
the communication attributes of their own system. Based on this, users can start
configuring parameters on simulator side.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
Picture 1-3: Line Configuration Box
Generally, the connection attribute of member’s system shall be one of the following
types:
1) A line of duplex active connection;
2) A line of duplex passive connection;
3) A line of simplex active connection and a line of simplex passive connection.
More specific description are summarized in following table:
Connection Type of Connection Type of Simulator
Member Host
Duplex Active Mode Duplex Passive Mode:
Select Type as ‘1-Sever’ and Mode as ‘2-Duplex’.
In this mode, the IP address showed on simulator will
automatically turn to 127.0.0.1 (Loopback Address), and the
port have to be defined by users themselves. After that, click
‘save’ button to create the line. Other configurations have to
be done at the remote members’ system side.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
On the member’s system side, the port configuration need
point to the configured port at the simulator, and IP should
point to the PC’s IP that simulator locates.
Attentions: Few of the users enter the simulator IP address as
127.0.0.1 when they configure the line on their own acquiring
system. This is a typical mistake because such configuration
only can properly work when simulator and tested system are
located on a same PC. For the situation of that acquiring
system is located on a different IP with simulator, users have
to enter the external IP1 of the PC that simulator locates
instead of the loopback Address, 127.0.0.1.
Duplex Passive Duplex Active Mode:
Mode
Choose Type as “0-Client” and Mode as “2-Duplex”.
In this mode, users need fill their own system’s IP and
indicated port into the line configuration box. After the
configuration is done, press ‘save’ to create the line.
1 A way of checking external IP: Click Windows Start Menu->input ‘cmd’ in search bar->open ‘cmd.exe’->input
command ‘ipconfig’->check the IPv4 address. Attention: For some institutions whose network did NAP, their IPs
may change. In that case, simulator users have to ask their network team for more details.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
Simplex mode : Simplex mode:
1) Active Line 1) Passive Line
Choose Type as ‘1-Server’ and Mode as ‘0-Simplex Recv’.
This is a passive line waiting for the connection request from
remote system. Thereby, the IP information is pre-defined as
Loopback Address, 127.0.0.1. Users have to define port by
themselves, and ensure their own system is configured as the
corresponding port.
Attentions: Few of the users enter the simulator IP address as
127.0.0.1 when they configure the line on their own acquiring
system. This is a typical mistake because such configuration
only can properly work when simulator and tested system are
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
located on a same PC. For the situation of that acquiring
system is located on a different IP with simulator, users have
to enter the external IP2 of the PC that simulator locates
instead of the loopback Address, 127.0.0.1.
2) Active Line
2) Passive Line Choose Type as ‘0-Client’ and Mode as ‘0-Simplex Send’.
This line will actively connect with the listening port of the
remote system. Users should fill their own system’s IP address
in to the IP frame, and fill the port that remote system opens
to simulator into the port frame.
Attention: The two ports of simplex sending and receiving line
cannot be duplicate. Otherwise, it will lead conflict of
connections.
Step 3: Click ‘Start All Lines’ to check the connection of lines:
After all lines have been properly configured, click ‘Start All Lines’ button, the
simulator will attempt to connect the remote member’s system. When ‘1-Connected’
is displayed at the ‘status’ column, it means connection has successfully established
(please refer picture 1_4: Communication Parameters). Picture 1-4: Communication
Parameters
Excepted ‘1-connected’, the status of ‘listening and connecting’ both means
2 A way of checking external IP: Click Windows Start Menu->input ‘cmd’ in search bar->open ‘cmd.exe’->input
command ‘ipconfig’->check the IPv4 address. Attention: For some institutions whose network did NAP, their IPs
may change. In that case, simulator users have to ask their network team for more details.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
connection has not yet established (please refer picture 1_5: Abnormal Connection
Status). If users met this problem, they might ask network team to check the local
network configuration or environment, such as firewall, NAP setting and so on.
Picture 1-5: Abnormal Connection Status
Step 4 (optional): Select a ‘Duplex Line’ or a ‘Simplex Sending Line’, and click the ‘Line
Test’ button to send an ‘idle message’. This message is used to detect and maintain
line connections in UPI online test and production environment instead of ‘Echo Test’
since it saves transmission and storage resources. More details can be find in UPI
Technical Specifications on Bankcard Interoperability (Version 2.1) Part
V-Communication Interface, Section 6.3.4.5 Idle Connection Processing.
Moreover, the simulator allows users sending self-edited character strings (in either
ASCII or HEX format) through one Duplex or Simplex Sending line.
The Line log window will display the latest messages sent or received through the
selected line in real time, allowing users to observe whether the selected line is
working properly. Please refer picture 1_6 for the sending steps.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
Picture 1-6: Steps of Sending an Idle Message or Self-edited Character String
Attention: ‘Echo Test’ may not be able to perform successfully at this stage because
configurations have not been fully completed in present.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
2. Acquirer Parameter Configuration
After completing communication configuration, the next step is configuring Acquirer
Institution parameters. The interface is showed as picture 2-1:
Picture 2-1: Acquirer Institution Configuration
Significant parameters of this page include:
Parameters Descriptions
Institution ‘Institution Code’ in this page refers to Field 33 in online messages
code, (forwarding institution code), and the ‘Sub-institution Code’ refers
Sub-institution to Field 32 in online messages (acquirer institution Code).
code
Simulator will not check the validity of these two parameters in
Issuer test mode, thereby users can enter any 8-digit IINs at these
frames excepted for ‘00000000’ and ‘00010344’. In following test
period, users will find these values appearing at Field 32 and 33 of
the request messages simulator sends out.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
Transaction This parameter refers to the initiated transaction currency for
currency creating new case scripts.
Settlement This parameter is equivalent to the acquirer’s settlement currency
currency in real UPI settlement system. Users shall select a currency based on
their demands. This parameter will not affect test since the acquirer
settlement currency is irrelevant to issuer’s test.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
3. Issuer Parameter Configuration
After completing the Acquirer Institution Parameters, the next step is configuring
Issuer Institution parameters. The interface is showed as picture 3-1:
Picture 3-1: Issuer Institution Parameters
Significant parameters of this page include:
Parameters Descriptions
Institution The ‘Institution Code’ is equivalent to Receiving Institution Code
code, (Field 100); and the ‘Sub-institution Code’ is equivalent to the Issuer
Sub-institutio Institution Code.
n code
For the ‘institution code’ parameter, it must be filled as same as the
IIN of member’s license. Available IIN of the license can be check via
‘Simulator Main Menu-> Help->About’ (see picture as below).
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
Attention: in the subsequent message testing, the value of Field 100
in the response message replied by issuers must be same with this
parameter as well. Otherwise, simulator will prompt ‘illegal
institution code’ and quit.
Master Key, Master Key3:
PIN Key and
In online environment, master keys are generated based on the
MAC Key
manual entry or by a security machine at random, and are stored in
the hardware security machines or the hosts. In the current offline
test, testers need confirm the master key in simulator is exactly
same with the master key in their own systems.
The pre-stored value 1023457689BADCEF0132546798ABCDFE in
simulator is a plaintext key recommended by UPI. Member
Institutions can use other keys instead of the pre-stored key but
shall ensure the master key in their hardware security machine or
the host is exactly same with the master key in simulator.
PIN Key 4 : This frame displays the plaintext PIK in use of the
simulator. Users can skip configuring this parameter at the current
stage since PIK can be randomly generated and exchanged by PIK
exchange messages which will be tested in the subsequent message
3 Member Master Key (MMK): Member master key is a key encryption key which is used to encrypt MAK and PIK.
For more information, please refer to UPI Technical Specifications on Bankcard Interoperability V2.1, Part IV Data
Transmission Security Control, Section 4 Key Management and Control.
4 PIK Key: the key used to encrypt PIN block.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
test stage. For the members who only test transactions without
PINs, they can skip the PIK exchange test.
MAC Key5: Similarly with PIK, this frame displays the plaintext MAK
in use of the simulator. Users can skip this parameter at the current
configuration stage since this key can be randomly generated and
exchanged between the simulator and the member system by MAC
exchange messages which will be tested in the subsequent message
test stage. For the members who do not use MAC verification (Field
128), they can skip MAK exchange test.
PIN block According to UPI Technical Specifications on Bankcard
format Interoperability V2.16, ‘the PIN Block format shall be complied with
the format with PAN information published in ISO ANSI X9.8’.
Therefore, this parameter shall be selected as ‘2-withPAN’ if without
other special reasons. For the members who only test messages
without PINs, this parameter will not affect tests.
PIN Key length According to UPI Technical Specifications on Bankcard
Interoperability V2.17, ‘for Members outside Mainland of China,
double length key algorithm is mandatory’. Therefore, this
parameter shall be select as ‘6-Double_Length_3DES_Algorithm’ if
without other special reasons. For the members who only test
messages without PINs, this parameter will not affect tests.
MAC Key Since there is not special requirement on MAK length, users can
length select either single length or double length based on their demands.
For the members who do not use MAC (Field 128 in online
messages), they have to close the ‘MAC verification switch’ which
can be found at the lower left corner of the simulator main interface
(see picture as below). As a consequence, this parameter will not
affect their test.
5 MAC Key: MAC key is a key used to generate message authentication code (MAC) data.
6 Part IV Data Transmission Security Control, Section 5.1.3-PIN Block.
7 Part IV Data Transmission Security Control, Section 5.1.4 PIN Encryption Method.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
MAC verification status is showed at the bottom bar of the main
interface (see the picture as below).
Settlement This parameter is equivalent to the Issuer’s settlement currency in
currency real UPI settlement system. Users can select a currency based on
their demands.
Message flag This parameter is significant. Users must select corresponding
message flag (single/dual) based on their real situations.
For the users who do not familiar with the definition of single/dual
messages, please refer the following contents cited from UPI
Technical Specification:
The Single Message refers to ‘A transaction mode under which the
acquirer submits transaction information to the issuer，and then
CUPS does settlement based on the log and the acquirer does not
need to submit presentment files.’ The Single Message Transaction
refers to ‘a transaction is transmitted only once for authorization,
clearing and settlement, which is also called comprehensive
financial transaction, i.e. authorization, clearing and settlement all
take place online.’
The Dual Message refers to ‘a transaction mode under which the
acquirer first submits authorization request to the issuer, and then
submits settlement information to the issuer collectively in the form
of presentment file at some time afterwards.’ The Dual-Message
Transaction refers to ‘a transaction is transmitted twice. For the first
time, it is only for authorization, and for the second time, the
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
additional information is for clearing and settlement, i.e. real-time
authorization processing and non-real-time clearing and settlement
processing.’8
A specific transaction type can be defined by a combination of
‘message type field, Field 3, Field 18, Field 25, and Field 60.2.5’.
Please refer UPI Technical Specifications on Bankcard
Interoperability V2.1, Part VI-Annex, Appendixes B.1 and B.2 for
more details. Single and dual messages are separately defined in the
appended table.
8 UPI Technical Specifications on Bankcard Interoperability V2.1: Part I-Transaction Processing, Section 3 Terms
and Definitions.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
4. Other parameter Configuration
After completing the Issuer Institution Parameters, the next step is configuring Other
Parameters. The interface is showed as below:
Picture 4-1: Other Parameter Configuration
Significant parameters of this page include:
Parameters Descriptions
Time Out This parameter is the time that the Simulator waits for a
response message from the Institution. If the response interval
is longer than configured time, it will be deemed as time out by
the simulator.
Message Version Users must select a correct message version according to their
messages sent to simulator. Otherwise, simulator will declined
messages by rejected code ‘00025’.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
Method for checking the Message Version:
Message version is defined by field 2 value of message header.
This field only include one 8-bit binary data. The first bit of this
binary data represents:
0 indicating a production message;
1 indicating a testing message.
The last 7 bits define the message format version: 000 0001
indicating 2.0 message version;
000 0010 indicating 2.1 message version.
Attention: New UPI members have to use 2.1 version since it is
based on the updated technical specifications after April 20119.
Old members can remain 2.0 version doing test.
Settlement Date This frame shows the current settlement date. The date will
scroll backwards one day after a cut-off was successfully
processed. In following message test stage, users will find this
date appearing at Field 15 in the response messages sent by
the simulator.
CUPS ID The IIN of UPI Switch, pre-defined and cannot be changed.
Auto Cut-off and Auto Cut-off switch. When this parameter is selected as ‘auto’,
Cut-off Time that means the simulator will automatically initiated a
settlement date cut-off at the indicated time daily.
Initial Data Default value for creating new cases, can be leaved as blanks.
File Directory This parameter refers to the storage path of the files generated
by simulator. These files include: card account list, configuration
script, case scripts and test reports, etc.
9More details can be found in UPI Technical Specifications on Bankcard Interoperability V2.1, Part II-Online
Messages, Section 4.2.2.2 Field 2-Header Flag and Version.
UPI Simulator Guide-Chapter IV: Configuration Guide of Issuers
5. Summary:
Users have completed all basic configuration according to this manual. Lastly, one
this should be noticed is that there is a pair of ‘import’ and ‘export’ buttons at the
lower left corner. It is used for export and import configuration parameters. Based on
these two functional buttons, users can quickly copy all configured parameters to a
new simulator program.
To continue the following test, please read ‘UPI Simulator Guide, Chapter 5: Test
Operation Guide for Issuers’.
