CYNOVO Kivvi Device SDK User Manual V2.1.9
CYNOVO%20KivviDeviceSDK%20user%20manual%20v2.1.9
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 31
| Download | |
| Open PDF In Browser | View PDF |
CYNOVO Kivvi Payment Device
The third party applications interface
specification
V 2.1.9
CYNOVO, Inc.
2017/06/19
Version Infomation
Version
Date
Modify
Instructions
2.0.0
2016.06.22
吴娟（Joyce）
The first draft
2.0.1
2016.07.07
陈俊俊（George）
Improve the
instruction
interface
definition
and
2.0.2
2016.07.11
郁丽（Lucy）
Improve the
instruction
interface
definition
and
2.0.3
2016.07.28
陈俊俊（George）
"Search card", "trade request" and "EMV
trade" instructions to increase track data
encryption.
2.0.4
2016.10.28
陈俊俊（George）
Improving the key management system
2.0.5
2016.11.11
陈俊俊（George）
Increase the isbusy instructions and led
control;
Password input increase password-less
directly confirm the configuration parameters
noPinFormat;
Perfect apdu command function, support IC
card
2.0.6
2016.12.17
杨东林(Neil)
Increase pinFormat parameters in pinprocess
instructions "PLAIN_TEXT" plaintext password
valid values
Increase the qrcode optional parameters in
the instruction of payType, used for displaying
payment type LOGO in the middle of the qr
code
2.0.7
2017.01.03
陈俊俊（George）
Increase the
instructions
2.1.0
2017.03.09
朱广伟（Scott）
Bank card, EMV Instruction parameter part
redefined, increase support to the function of
electronic cash, including electronic cash
balance inquiries and transaction records
query function.
2.1.1
2017.03.13
朱勇敏(Eddard)
Add a serial port instructions
2.1.2
2017.03.23
杨东林(Neil)
Add the flow chart of how to load and use
MSSK and DUKPT
2.1.3
2017.03.24
朱广伟(Scott)
Transact command,add”transFlow”
2.1.4
2017.03.27
杨东林(Neil)
Add Key distribution management
2.1.5
2017.04.01
朱广伟(Scott)
Add load terminal param in load EMV
parameters part
2.1.6
2017.04.05
金晖(Martin)
Add digital signature capabilities fuction on
DUKPT
KSN
operating
small screen. The LOGO and carousel pictures
supports 256-color bitmap format. Add EMV
parameter configruation fuction.
2.1.7
2017.04.06
朱广伟(Scott)
Add “appId” for Load EMV Parameter
2.1.8
2017.04.17
朱勇敏(Eddard)
Add Printer busy command
2.1.9
2017.06.19
金晖(Martin)
Update instruction parameter configuration
instructions.
Add AppID assignment description.
1. Overview
These Interfaces are for CYNOVO smart terminal（Par6 and Par10）
，in Instruction
to develop upper layer application.
2. Class and Interface
2.1.
Result listener Interface class : KivviDeviceRespListener
public interface KivviDeviceRespListener {
void onResponse(KivviDeviceResp kivviDeviceResp);
}
Result class：KivviDeviceResp
Only have one member now：int ErrCode（*）
*About error message，please refer to 4th quarter : Error Message Definition.
2.2.
Device Class : KivviDevice
Prototype
definition
int Set(String key, Object value)
Function
Param Setting
key
Param name *
value
Param value。Only have 3 types are supported inclued String、int and byte[]
Param
Return
Error message
* About Param name，please refer to 2nd Param definition &Examples
Prototype
definition
int Action(String cmd [, final KivviDeviceRespListener listener])
Function
Do device action
cmd
Device Command
listener
asynchronous command result listener
Param
Return
Error message
Prototype
definition
Object Get(String key [, int exParam])
Function
Read result
key
Result data name
exParam
Extra Param（option）
Param
Return
Result data ObjectObject，if inexsistence Return null
Prototype
definition
String GetString(String key [, int exParam])
Function
Read String type result。
（Extension in Getmethod）
key
Result data name
exParam
Result data extra Param（optional）
Param
Return
Result data StringObject，if inexsitence Returnnull
Prototype
definition
byte[] GetByteArray(String key [, int exParam])
Function
Read byte[] type result。
（Extension in Getmethod）
key
Result data name
exParam
Result data extra Param（optional）
Param
Return
Result data byte[]Object，if inexsitence Return null
Prototype
definition
intGetInt(String key [, int exParam])
Function
Read int type result（Extension in Getmethod）
key
Result data name
exParam
Result data extra Param（optional）
Param
Return
Result data int Object，if inexsitence throw exception
Prototype
definition
boolean GetBool(String key [, int exParam])
Function
Read boolean type result（Extension in GetIntmethod）
key
Result data name
exParam
Result data extra Param（optional）
Param
Return
Result data boolean Object，if inexsitence throw exception
Prototype
definition
boolean Has(String key [, int exParam])
Function
Judge If there is key
Param
key
Result data name
exParam
Return
Result data extra Param（optional）
Visibal Returntrue，if inexsitence Returnfalse
3. Operational definition
3.1 Type of instruction
Instruction
Type
Card
operation
Instruction
definition
“card.”
Authority require
Function Introduction
KIVVI_CARD
Bank card and trade operation
PINPAD
operation
“pinpad.”
KIVVI_PINPAD
Pinpad operation like input key,data
encryption and decryption,MAC calculation
and so on
File Storage
“storage.”
KIVVI_STORAGE
File storage operation 、storage EMV Param、
clean EMV Param......
Screen
Display
“exscreen.”
KIVVI_EXSCREEN
Show QR code、show customer information
Basic
operation
“basic.”
At least include one of
above anthority
Get time ,set time , get version and so on
Printer
operation
“printer.”
KIVVI_PRINTER
Printer detection operation 、print operation
*Ps: When you using the instruction, you mast config the apply permissions in the
AndroidManifest.xml file, the code like :
“”
Example: config the screen display permissions.
3.2 Instruction List
Type
basicopera
tion
Instruction
name
Instruction
Suggestion
way
Function Introduction
Read version
"basic.cmd.version"
sequential
execution
Read all version
Time
operation
"basic.cmd.time"
sequential
execution
Read or set time
System
operation
"basic.cmd.system"
sequential
execution
System operation ，like reboot
Read BUSY
state
"basic.cmd.isbusy"
sequential
execution
If firmware is busy
LED contol
"basic.cmd.led"
sequential
execution
Control Led light
Search card
“card.cmd.search”
Bank Card
EMV trade
“card.cmd.emv_process”
asynchronous
execution
asynchronous
execution
remind and wait customer
search card
EMV trade request
asynchronous
execution
Bank card trade，remind and
wait customer search card or
input key
“card.cmd.issuer_process”
sequential
execution
EMV issuing bank data manage
Detect IC slot
“card.cmd.detect_ic_slot”
sequential
execution
Detect if IC slot has card
Mifare card
operation
"card.cmd.mifare"
sequential
execution
Mifare card authority and read
or write
APDUoperati
on
"card.cmd.apdu"
sequential
execution
APDU interact operation
Trade request
“card.cmd.transact”
Issuing bank
data manage
e-cash
off-line
balance
enquiry
PINPAD
File
Storage
e-cash off-line balance enquiry
"emv.cmd.balance"
sequential
execution
（please do
“card.cmd.search”Instruction
first）
"emv.cmd.log"
sequential
execution
IC card trace record（please do
“card.cmd.search”Instruction
first）
EMV
parameter
configuration
"emv.cmd.paramset"
sequential
execution
Config Country Code&Currency
Code
Load key
“pinpad.cmd.loadkey”
sequential
execution
Load KPK、master key、work key
Input key
“pinpad.cmd.pinprocess”
encryption
and
decryption
“pinpad.cmd.crypto”
sequential
execution
Test encryption and decryption
Function
Calculate
MAC
”pinpad.cmd.mac”
sequential
execution
Calculate MAC
Create
random
"pinpad.cmd.random"
sequential
execution
Create random
sensitive
information
confirm
"pinpad.cmd.confirm"
asynchronous
execution
Read /update
KSN
"pinpad.cmd.ksn"
sequential
execution
Read /update KSN
Digital
signature
"pinpad.mpr.handwrite"
sequential
execution
Sign your Name
Save file
“storage.mpw.write_file”
sequential
execution
Save file
Read file
“storage.mpr.read_file”
sequential
execution
Read file
IC card trace
record
asynchronous
execution
remind and wait customer
search card
sensitive information confirm
like balance
Screen
display
Print
operation
Delete file
“storage.cmd.delete_file”
sequential
execution
Delete file
Load
EMVParam
“storage.cmd.load_emvpara
ms”
sequential
execution
Load EMVParam
Save picture
“storage.mpw.load_bitmap”
sequential
execution
Save bitmap or logo
Stand by
“exscreen.cmd.idle”
sequential
execution
Exscreen stand by Logo
Show QR
code
“exscreen.cmd.qrcode”
sequential
execution
Exscreen show QR code
slide show
“exscreen.cmd.bitmap”
sequential
execution
Exscreen slide show
show
customer
message
“exscreen.cmd.custom_msg
”
sequential
execution
Exscreen show customer
message
Paper out test
“printer.cmd.paperout”
sequential
execution
Paper out test
Feed paper
“printer.cmd.feed”
sequential
execution
Feed paper
Print text
“printer.cmd.text”
sequential
execution
print text
print picture
“printer.cmd.photo”
sequential
execution
print picture
print QR code
“printer.cmd.qrcode”
sequential
execution
print QR code
print bar
code
“printer.cmd.obcode”
sequential
execution
print bar code
3.3 Instruction and Param details Introduction
Param name : the Param name that this Instruction can set or get
Type：
STR String； INT int； BIN byte[]
Length：the length of value，VAR is elongate
Default value：if not Set the Param value，use the default value
request：input form Param，before Action，can be setted
response：output Param，after Action，can be getted
3.3.1 Basic Operation
3.3.1.1 Read Version number
Instruction："basic.cmd.version"
Parameter list：
Parameter
Type
Length
Request
NULL
Effective/Default
Value
Description
Response
“ret”
INT
4
“result”
STR
VAR
Error Description
"hwVer"
STR
VAR
"fwVer"
STR
VAR
Hardware Version
Number Version
Software
"serialNo"
STR
VAR
“KivviDeviceSN”
STR
VAR
“KivviDeviceHardwareVersion”
STR
VAR
“SdkVerison”
STR
VAR
"KivviDeviceVerison"
STR
VAR
"KivviDevicePlatform"
STR
VAR
Reference code：action/basic/ActionGetVersion.java
Error Code
Number
Financial Module
SN
Master Device SN
Master Device
Version
SDK Version
KivviDevice
Version
KivviDevice
Platform
3.3.1.2 Time Operation
Instruction："basic.cmd.time"
Parameter list：
Parameter
Type
Length
Effective/Default Value
Description
Request
"operate"
STR
VAR
"datetime"
STR
19
"GET"（default）
"SET"
Read Time
“yyyy/mm/dd/hh/mm/ss”
Only ”SET” used
Set Time
Response
“ret”
INT
4
“result”
STR
VAR
"datetime"
STR
19
Error Code
Error Description
“yyyy/mm/dd/hh/mm/ss”
Reference code：action/basic/ActionGetTime.java 和 ActionSetTime.java
3.3.1.3 System Operation
Instruction："basic.cmd.system"
Parameter list：
Parameter
Type
Length
Effective/Default Value
Description
Request
" operate"
STR
VAR
"reboot"
Reboot Financial Module
Response
“ret”
INT
4
“result”
STR
VAR
Error Code
Error Description
Reference code：action/basic/ActionRebootPos.java
3.3.1.4 Read BUSY State
Instruction："basic.cmd.isbusy"
Parameter list：
Parameter
Type
Length
Effective/Default
Value
Description
Request
NULL
Response
“ret”
INT
4
Error Code
“result”
STR
VAR
"isbusy"
INT
4
Error Description
0 for “Free”；1 for “Busy”
3.3.1.5 LED Control
Instruction："basic.cmd.led"
Parameter list：
Parameter
Type
Length
Effective/Default Value
Description
Request
"led"
STR
VAR
" operate"
STR
VAR
"RED"、"GREEN"、"YELLOW"、
"BLUE" 、 "DRED"
and
"DGREEN"
Ps: devided by “|”
"ON""OFF"
on / off
Response
“ret”
INT
4
“result”
STR
VAR
Error Code
Error Description
3.3.2 Bank Card
3.3.2.1 Search Card
Command："card.cmd.search"
Parameter：
Lengt
Parameter
Type
h
"cardType"
"trackMode"
STR
STR
VAR
VAR
Effective/Default Value
Description
Request
"MSR" or "IC" or "NFC" ，
separate by '|', Default:
"MSR|IC|NFC"
Card Type
"plain"(Default)
Plain of Track Data
"entype0"
Cipher of Track Data，
REF 6.2
"Unionpay"
Cipher
of
Track
Data(Unionpay ECB)
"MKSK"(Default)
"DUKPT"
"FIXED"
"JF"
Key Management Type
"keyMng"
STR
VAR
"appId"
INT
4
0x01~0x0F Default(0x01)
When track data need
encrypt
"timeout"
INT
4
10~120
Unit: Second
Default(60)
Response
"ret"
INT
4
"result"
STR
VAR
"cardType"
STR
VAR
"isICCard"
INT
4
0: Not IC Card; 1:IC Card
"cardType" must be "IC"
"nfcType"
STR
VAR
"typeA"、"typeB"、"M1"
"cardType" must be
"NFC"
"track1"
STR
Error Code
Error Description
"MSR"
"NFC"
or
"IC"
or
VAR
Track 1 Data;
"cardType" must be
"MSR"
"track2"
STR
VAR
Track 2 Data;
"cardType" must be
"MSR"
"track3"
STR
VAR
Track3 Data; "cardType"
must be "MSR"
VAR
Primary Account
Number; "cardType"
must be "MSR"
VAR
Expiration Date;
"cardType" must be
"MSR"
"pan"
"expDate"
"withIC"
STR
STR
INT
4
0: Card without IC; 1: Card
with IC
Card with IC ?;
"cardType" must be
"MSR"
Reference Code：action/card/ActionSearch.java
3.3.2.2 EMV Process
Command："card.cmd.emv_process"
Parameter：
Parameter
Type
Length
Effective/Default Value
Description
Request
"amount"
"amountOther"
“transType”
STR
STR
INT
VAR
Amount
Auth(Optional)
VAR
Amount
Other(Optional
)
4
1.Consumption
2.Revocation
3.Return
4.Online Balance Query
5.Pre-authorization
6.Pre-Authorization revocation
7.Pre-Authorization Completion request
Transaction
type Code
8.Pre-Authorization Completion notice
9.Pre-Authorization Complete
revocation
11.E-Cash Balance Enquiry
12.E-Cash Deposit
13.E-Cash consumption
14.E-Cash non-specified account circle
15.E-Cash designated account deposit
"transFlow"
"keyMng"
"pinFormat"
"trackMode"
INT
STR
STR
STR
1：Complete Flow
2：Simple Flow(Just Get ICC Data From
Card)
Transaction
Flow
VAR
"MKSK"(Default)
"DUKPT"
"FIXED"
"JF"(Customer Definition)
Key
Management
Type
VAR
"FORMAT0"(Default)
"FORMAT1"
"FORMAT3"
PINBLOCK
Format
"plain"(Default)
Plain of Track
Data
"entype0"
Cipher of Track
Data，REF 6.2
"Unionpay"
Cipher of Track
Data(Unionpay
ECB)
4
VAR
"appId"
INT
4
0x01~0x0F Default(0x01)
"timeout"
INT
4
10~120
"pinMinLen"
INT
4
4~12 Default( 4)
PIN Minmum
Length
"pinMaxLen"
INT
4
4~12 Default( 12)
PIN Maxmum
Length
4
0: Not Force Online(Default)
1: Force Online
Force Online
Flag(REF:
If
transaction is
not Electronic
Cash,
this
param
must
set to 1)
Electronic Cash
Transaction
Flag
CVM
Flag
"isForceOnline"
INT
Default(60)
"isSupportEC"
INT
4
0: Not Electronic Cash(Default)
1: Electronic Cash Transaction
"isSupportCVM
"
INT
4
0: CVM NOT Executed
1: CVM Executed(Default)
Unit: Second
Execute
1: Input PIN Controlled by EMV
Kernel(Default)
"isUsePinpad"
"reqTagList"
INT
STR
4
0: Input PIN Controlled by Application,
The
Deveopler
must
call
"pinpad.cmd.pinprocess" command
Input
PIN
Controlled by
EMV Kernel or
User
Application
EMV Tag List,
Separate
by
'|'(Optional)
VAR
Response
"ret"
INT
4
Error Code
"result"
STR
VAR
Error
Description
"pan"
STR
VAR
Primary
Account
Number
"track2"
STR
VAR
Track 2 Data
"seqNo"
STR
2
Sequence
Number of IC
Card
"expDate"
STR
VAR
Expiration Date
"pinBlock"
BIN
8
"pinpadResult"
STR
VAR
"cvmType"
STR
VAR
"OK": Cal Pinblock Succ
"FAIL": Cal Pinblock Fail
"USER CANCEL": User Cancel
"TIMEOUT": Enter PIN Timeout
"NO PIN": User NOT Enter PIN, Just
Press "ENTER"
Pinpad Result
"ONLINE_PIN"
Online PIN
"SIGN"
Signature
"REQUEST: Indicate The Transaction Is
Online
"emvDataType"
STR
VAR
"CONFIRM: Indicate The Transaction is
Offline
EMV Data Type
"REVERSAL": Indicate The Transaction
Should Be Reversal
"emvData"
VAR
B
I
N
Reference Code：action/card/ActionEmvProc.java
3.3.2.3 Transaction
Command："card.cmd.transact"
Parameter：
EMVData(Field
55)
Parameter
Type
Lengt
h
Effective/Default Value
Description
Request
"amount"
STR
VAR
Amount Auth(Optional)
"amountOther"
STR
VAR
Amount Other(Optional)
“transType”
“transFlow”
"cardType"
"keyMng"
"pinFormat"
"trackMode"
"appId"
INT
INT
STR
STR
STR
STR
INT
4
1.Consumption
2.Revocation
3.Return
4.Online Balance Query
5.Pre-authorization
6.Pre-Authorization revocation
7.Pre-Authorization
Completion request
8.Pre-Authorization
Completion notice
9.Pre-Authorization Complete
revocation
11.E-Cash Balance Enquiry
12.E-Cash Deposit
13.E-Cash consumption
14.E-Cash non-specified
account circle
15.E-Cash designated account
deposit
4
1:Complete process
2:Streamline processes
(Chip card only read card
number and other parameters)
VAR
"MSR" or "IC" or "NFC" ，
separate by '|' ， Default:
"MSR|IC|NFC"
VAR
"MKSK"(DDefault)
"DUKPT"
"FIXED"
"JF"
Key Management Type
VAR
"FORMAT0"(Default)
"FORMAT1",
"FORMAT3"
“PLAIN_TEXT”
PINBLOCK Format
"plain"(Default)
Plain of Track Data
"entype0"
Cipher of Track Data，
REF 6.2
"Unionpay"
Cipher
of
Track
Data(Unionpay ECB)
VAR
4
0x01~0x0F Default(0x01)
"timeout"
INT
4
10~120
Default(60)
Unit: Second
"msrPinProc"
INT
4
0:NotEnter PIN
1:Enter PIN
Whether Enter PIN after
Swipe Card
"pinMinLen"
INT
4
4~12 Default is 4
PIN Minmum Length
"pinMaxLen"
INT
4
4~12 Default is 12
PIN Maxmum Length
"allowFallback"
INT
4
0:not allowed
1:allowed
Allow Fallback Flag
"isForceOnline"
INT
4
0: Not Force Online(Default)
1: Force Online
Force Online Flag(REF: If
transaction
is
not
Electronic Cash, this
param must set to 1)
"isSupportEC"
INT
4
0: Not Electronic Cash(Default)
1: Electronic Cash Transaction
Electronic
Transaction Flag
"isSupportCVM"
INT
4
0: CVM NOT Executed
1: CVM Executed(Default)
CVM Execute Flag
Cash
1: Input PIN Controlled by EMV
Kernel(Default)
"isUsePinpad"
INT
4
"reqTagList"
STR
VAR
0: Input PIN Controlled by
Application, The Deveopler
must
call
"pinpad.cmd.pinprocess"
command
Input PIN Controlled by
EMV Kernel or User
Application
EMV Tag List, Separate
by '|'(Optional)
Response
"ret"
INT
4
"result"
STR
VAR
"cardType"
STR
VAR
"pan"
STR
VAR
Primary
Number
"track1"
STR
VAR
Track 1 Data
"track2"
STR
VAR
Track 2 Data
"track3"
STR
VAR
Track 3 Data
"seqNo"
STR
2
"expDate"
STR
VAR
"pinBlock"
BIN
8
"pinpadResult"
STR
VAR
Error Code
Error Description
"MSR" or "IC" or "NFC"
Card Type
Account
Sequence Number of IC
Card
Expiration Date
PIN BLOCK
"OK": Cal Pinblock Succ
"FAIL": Cal Pinblock Fail
"USER CANCEL": User Cancel
"TIMEOUT": Enter PIN Timeout
"NO PIN": User NOT Enter PIN,
Just Press "ENTER"
Pinpad Result
"cvmType"
"emvDataType"
STR
STR
VAR
VAR
"ONLINE_PIN"
Online PIN
"SIGN"
Signature
"REQUEST:
Indicate
Transaction Is Online
The
"CONFIRM:
Indicate
Transaction is Offline
The
EMV Data Type
"REVERSAL": Indicate The
Transaction Should Be Reversal
"emvData"
BIN
VAR
EMVData(Field 55)
Reference Code：action/card/ActionTransact.java
3.3.2.4 Issuer Data Process
Command："card.cmd.issuer_process"
Parameter：
Lengt
Parameter
Type
Effective/Default Value
h
Request
"respCode"
STR
Description
2
Response Code From
Acquire, When SUCC,
usually is "00", When
FAIL, other code
"issuerData"
BIN
VAR
Data
From
Issuer,
Sometimes Include Script
of 71, 72
"reqTagList"
STR
VAR
EMV Tag List, Separate by
'|'(Optional)
Response
"ret"
INT
4
"result"
STR
VAR
Error Code
Error Description
"REQUEST": Indicate The
Transaction Is Online
"emvDataType"
STR
VAR
"CONFIRM": Indicate The
Transaction is Offline
EMVData Type
"REVERSAL": Indicate The
Transaction Should Be
Reversal
"emvData"
BIN
VAR
EMV Data(Field 55)
Reference Code：action/card/ActionEmvIssuerProc.java
3.3.2.5 IC Card Detect
Command："card.cmd.detect_ic_slot"
Parameter：
Lengt
Parameter
Type
Effective/Default Value
h
Request
Description
"isICCard"
INT
0: Test it When not Power
On
1: Test it When Power On
4
IC Card Test
Response
"ret"
INT
4
Error Code
"result"
STR
VAR
"cardInSlot"
INT
4
0: Card NOT In Slot
1: Card In Slot
Whether Card Is In Slot
"isICCard"
INT
4
0: Card Is Not IC
1: Card Is IC
Whether Card is IC Card
Error Description
Reference Code：action/card/ActionIcslot.java
3.3.2.6 Mifare Card
Command："card.cmd.mifare"
Parameter：
Lengt
Parameter
Type
h
"operate"
STR
VAR
"block"
INT
4
"authKeyType"
STR
4
"authKey"
BIN
Effective/Default Value
Description
Request
"AUTH"
Authorization
"INCREASE"
Increasement
"DECREASE"
Decresement
"READ"
Read Data
"WRITE"
Write Data
Block Index
“KeyA”
When
"AUTH"
"operate"
is
6
When
"AUTH"
"operate"
is
is
or
is
“KeyB”
"num"
INT
4
When
"operate"
"INCREASE"
"DECREASE"
"data"
BIN
VAR
When
"operate"
"WRITE"
Response
"ret"
INT
4
Error Code
"result"
STR
VAR
Error Description
"data"
BIN
VAR
When
"READ"
"operate"
Reference Code：action/card/ActionMifare*.java
3.3.2.7 APDU
Command："card.cmd.apdu"
Parameter：
Lengt
Parameter
Type
h
Effective/Default Value
Description
is
Request
"cardType"
"operate"
STR
STR
VAR
"IC"
"NFC"(Default)
"OPEN"
When Card Type is "IC":
Power On Card; When
Card Type is "NFC": Field
On
"CLOSE"
When Card Type is "IC":
Power Off Card; When
Card Type is "NFC": Field
Off
"EXCHANGE"(Default)
Exchange APDU
VAR
"data"
BIN
VAR
"timeout"
INT
4
APDU of Request
10~120
Default value: 60
Unit: Second
Response
"ret"
INT
4
Error Code
"result"
STR
VAR
Error Description
"data"
BIN
VAR
APDU of Response
Reference Code：action/card/ActionNfcApdu.java
3.3.2.8 Get Offline Balance
Command："emv.cmd.balance"
Parameter：
Parameter
Type
Lengt
h
Effective/Default Value
Description
Request
NULL
Response
"ret"
"data"
INT
4
Error Code
ASCII
12
Offline Balance of IC Card
Reference Code：action/card/ActionEmvBalance.java
3.3.2.9 Get Transaction Log
Command："emv.cmd.log"
Parameter：
Parameter
Type
Lengt
h
Effective/Default Value
Description
Request
NULL
Response
"ret"
INT
4
"data"
BIN
VAR
Transaction Log of IC Card
"logCount"
INT
4
Transaction Log Count of
IC Card(>= 0 && <= 10)
Reference Code：action/card/ActionEmvLog.java
Error Code
3.3.2.10 Configuration parameters of EMV
Command：" emv.cmd.paramset "
Parameter
Type
Length
Effective/Default Value
Description
Request
NULL
Response
"ret"
INT
4
Error Code
Reference Code：action/emv/ActionStoreEmvParams.java
Note：This command can only set country code(9F1A) and currency code(5F2A) by customer
screen.
3.3.3 PINPAD Operation
3.3.3.1 Load keys
Instruction：”pinpad.cmd.loadkey”
Parameter
"appId"
"keyMng"
Type
INT
STR
Lengt
h
Effective/Default Value
4
0x01~0x0F default: 0x01
VAR
Description
Request
"MKSK"
"DUKPT"
"FIXED"
(default)
"KPK"
key manage type
Key protect key
"MASTER_KEY"
"keyType"
STR
VAR
"PIN_KEY"
"MAC_KEY"
"TD_KEY"
“format”
STR
VAR
"INIT_KEY"
Just for DUKPT
"plain"
Plain text
"EnByTK"
Encrypted
terminal key
"EnByKPK"
Encrypted by KPK
"EnByMK"
Encrypted
Master key
by
by
Key
data
format
"TR31"
“key”
BIN
8/16
“checkValue”
BIN
4
“ksn”
BIN
VAR
Key data
Check value (optional)
Just for DUKPT
Response
“ret”
INT
4
“result”
STR
VAR
Error Code
Error Description
Reference Code ： action/pinpad/ActionLoadKpk.java 、 ActionLoadMkey.java
ActionLoadWkey.java
和
MK/SK load key process：
With TK,KPK
Load KPK
Set( keyType , KPK );
Set( format , EnByTK );
Set( keyType , KPK );
Set( format , Plain );
With KPK，with
TK
No KPK，no TK
Set( keyType ,MASTER_KEY);
Set( format , EnByKPK );
Set( keyType ,MASTER_KEY);
Set( format , EnByKPK );
Set( keyType , MASTER_KEY );
Set( format , EnByTK );
Set( keyType , MASTER_KEY );
Set( format , Plain );
Load MasterKey
Load KPK
With KPK，no TK
*Introductions：Following processes are owned by all green boxes:
1、Set( appId , i);
2、Set( key ,F.HexStringToByteArray(KeyData));
3、Action( pinpad.cmd.loadkey )
PS:1、The i at appId is number 1 to 5
2、Action must after all Set
3、KeyData is 8 or 16 bytes key
4、check Value is 4 bytes these are 8 bytes 0 which is encrypted by
Cleartext work-key
Load workKey
Set( KeyType , PIN_KEY );
Set( keyType ,TD_KEY);
Set( keyType , MAC_KEY );
Set( format , EnByMK );
Set( checkValue ,F.HexStringToByteArray(checkValue));
DUKPT load key process：
DUKPT
Load init_key and KSN
Check current KSN
Set( appId ,i);
Set( operate , GET );
Action( pinpad.cmd.ksn );
Set( appId ,i);
Set( keyMng , DUKPT );
Set( keyType , INIT_KEY );
Set( format , plain );
Set( key ,F.HexStringToByteArray(dbgDMK));
Set( ksn ,F.HexStringToByteArray(dbgKSN));
Action( pinpad.cmd.loadkey );
Update KSN
Set( appId ,i);
Set( operate , UPDATE );
Action( pinpad.cmd.ksn );
INIT_KEY and KSN create
OutPut_Key1
Update KSN
OutPut_Key1 create
Work_Key1
OutPut_Key1
OutPut_Key1 and new
KSN create next
OutPut_Key2
Repeat oprattions of dotted box ,create every
new Work_key by init KSN and derived
OutPut_Key
OutPut_Key2 create
Work_Key2
3.3.3.2 Password input
Instruction：”pinpad.cmd.pinprocess”
Parameter
Type
Lengt
h
Effective/Default Value
Description
Request
“pan”
STR
VAR
(optional)
"amount"
STR
VAR
(optional)
"keyMng"
"pinFormat"
STR
STR
VAR
"MKSK"
"DUKPT"
"FIXED"
(default)
VAR
"FORMAT0" (default)
"FORMAT1",
"FORMAT3",
”PLAIN_TEXT”
PINBLOCK format
Return pinblock or all
zero when no password
inputted
key manage type
"noPinFormat",
STR
VAR
"ZERO" (default) 8bytes
0x00
"PINBLOCK"
"appId"
INT
4
0x01~0x0F (default 0x01)
"timeout"
INT
4
10~120
"pinMinLen"
INT
4
4~12 (default 4)
Password min length
"pinMaxLen"
INT
4
4~12 (default 12)
Password max length
(default 60)
(seconds)
Response
“ret”
INT
4
“result”
STR
VAR
“pinBlock”
BIN
8
Error Code
Error Description
Reference Code：action/pinpad/ActionGetPin.java
3.3.3.3 Encrypt and Decrypt
Instruction：”pinpad.cmd.crypto”
Lengt
Parameter
Type
h
“operate”
STR
VAR
"algorithm"
STR
VAR
"padding"
"appId"
STR
INT
VAR
4
"keyMng"
STR
VAR
"keyType"
STR
4
"data"
BIN
VAR
Effective/Default Value
Description
Request
"ENCRYPT"、"DECRYPT"
"DES_ECB"
algorithm
“NULL”
No padding
“M1”
Padding with 0x00
“M2”
Padding with 80 00[n]
0x01~0x0F (default 0x01)
"MKSK"
"DUKPT"
"FIXED"
(default)
key manage type
default "TD_KEY"
Data length < 3K bytes
Response
“ret”
INT
4
Error Code
“result”
STR
VAR
Error Description
“data”
BIN
VAR
result
Reference Code：action/pinpad/ActionTestCrypt.java
3.3.3.4 MAC calculate
Instruction：”pinpad.cmd.mac”
Parameter
Type
Lengt
h
Effective/Default Value
Description
Request
"X99"
“macType”
STR
VAR
"ECB"
"Unionpay_ECB"
“keyMng”
STR
VAR
"appId"
INT
4
“data”
BIN
VAR
"MKSK"
"DUKPT"
"FIXED"
(default)
key manage type
0x01~0x0F (default 0x01)
Data length < 3K bytes
Response
“ret”
INT
4
“result”
STR
VAR
“mac”
BIN
8/16
Error Code
Error Description
Reference Code：action/pinpad/ActionCaculateMac.java
3.3.3.5 Random generate
Instruction：”pinpad.cmd.random”
Parameter
“length”
Type
INT
Lengt
h
Effective/Default Value
Description
Request
4
need length (1~3072)
Response
“ret”
INT
4
Error Code
“result”
STR
VAR
Error Description
“data”
BIN
VAR
result
Reference Code：action/pinpad/ActionGetRandom.java
3.3.3.6 Get and update KSN (Just for DUKPT)
Instruction：”pinpad.cmd.ksn”
Lengt
Parameter
Type
h
“operate”
STR
VAR
"appId"
INT
4
Effective/Default Value
Description
Request
"GET" (default)
"UPDATE"
0x01~0x0F (default 0x01)
Response
“ret”
INT
4
“result”
STR
VAR
Error Code
Error Description
“ksn”
BIN
VAR
Current KSN value
Reference Code：action/pinpad/ActionGetKsn.java 和 action/pinpad/ActionUpdateKsn.java
3.3.3.7 Digital signature
Instruction：” pinpad.mpr.handwrite”
Parameter
Type
Length
Effective/Default Value
Description
Request
none
Response
“ret”
INT
4
“result”
STR
VAR
“fileLen”
INT
4
Error Code
Error Description
Bmp File Lenth
Reference Code：action/pinpad/ActionHandWrite.java
3.3.3.8 Message Confirm
Instruction：”pinpad.cmd.confirm”
Lengt
Parameter
Type
Effective/Default Value
h
Request
Description
“dataType”
STR
VAR
"BALANCE"
“data”
STR
VAR
Display content
“data2”
STR
VAR
When datatype is “TEXT”,
the message will display at
second line.
"timeout"
INT
4
10~120
(default 60)
(seconds)
Response
“ret”
INT
4
“result”
STR
VAR
Error Code
Error Description
Reference Code：action/pinpad/ActionDispBalance.java
3.3.4 File storage
3.3.4.1 Save the file
Instruction：”storage.mpw.write_file”
Parameters list：
Parameter
Type
Length
Effective/Default Value
Description
Request
“fileType”
STR
VAR
“CERT”, “TEXT”, “BIN”
File type
“fileName”
STR
VAR
Within the limit of 63 bytes
in length
File name
"filePath"
STR
VAR
File path
“fileData”
BIN
VAR
File data
Response
“ret”
INT
4
“result”
STR
VAR
Error code
Error Description
* “filePath” and ”fileData” mast have one of them.
Reference code：action/storage/ActionStoreFile.java 和 ActionStoreFile2.java
3.3.4.2 Read the file
Instruction：”storage.mpr.read_file”
Parameters list：
Parameter
type
length
Effective/Default Value
Description
Request
“fileType”
STR
VAR
“CERT”, “TEXT”, “BIN”
File type
“fileName”
STR
VAR
Within the limit of 63 bytes
in length
File name
Response
“ret”
INT
4
Error code
“result”
STR
VAR
Error Description
“fileData”
BIN
VAR
File data
Reference code：action/storage/ActionReadFile.java
3.3.4.3 Delete the file
Instruction：”storage.cmd.delete_file”
Parameters list：
Parameter
type
length
Effective/Default Value
Description
Request
“fileType”
STR
VAR
“CERT”, “TEXT”, “BIN”, “ALL”
File type
“fileName”
STR
VAR
Within the limit of 63 bytes
in length
File name
Response
“ret”
INT
4
“result”
STR
VAR
Error code
Error Description
* when “fileType” and ”fileName” are both set to ”ALL”，it will delete all files（Initialization
file storage area）
Reference code：action/storage/ActionDeleteFile.java
3.3.4.4 Save the picturesBitmap）
Instruction：”storage.mpw.load_bitmap”
Parameters list：
Parameter
type
length
Effective/Default Value
Description
Request
“type”
STR
VAR
“NORMAL”（default）
The
regular
pictures
“LOGO”
The standby logo
carousel
Picture index，it only be
needed when the
“type” is set to
“NORMAL”.
“index”
INT
4
"filePath"
STR
VAR
File path
“fileData”
BIN
VAR
File data
Response
“ret”
INT
4
“result”
STR
VAR
Error code
Error Description
* “filePath” and ”fileData” mast have one of them.
Reference code：action/storage/ActionStoreBitmap.java 和 ActionStoreLogo.java
3.3.4.5 Load EMV parameters
Instruction：”storage.cmd.load_emvparams”
Parameters list：
Parameter
type
length
Effective/Default Value
Description
Request
“operate”
STR
VAR
"appId"
INT
4
“type”
STR
VAR
"data"
BIN
VAR
“ADD” (default)
Load parameters
“CLEAN”
Clear parameters
0x01~0x0F Default(0x01)
app use
appId
independent
"TERM", "AID", "CAPK",
Parameter Type
"CARD", "CERT"
it only be needed when
"operate" is set to
"ADD".
Response
“ret”
INT
4
“result”
STR
VAR
Error code
Error Description
Reference code：action/storage/ActionStoreEmvParams.java
Note: When “type” is “TERM”, User can config the terminal parameters such as country
code(9F1A), currency code(5F2A), terminal capability(9F33),
Example:”9F1A0208405F2A0208409F3303E0E8C0”
3.3.5 Screen Display
3.3.5.1 Display Stand-by Logo
Instruction：”exscreen.cmd.idle”
Parameter list：
Parameter
Type
Length
Effective/Default Value
Description
Request
NULL
Response
“ret”
INT
4
Error Code
“result”
STR
VAR
Error Description
Reference code：action/exscreen/ActionDisplayIdle.java
3.3.5.2 Display carousel Pictures
Instruction：”exscreen.cmd.bitmap”
Parameter list：
Parameter
Type
Length
Effective/Default Value
Description
Request
“interval”
INT
4
Default : 5s
Interval time (s)
“beginIdx”
INT
4
The Starting picture
“palyNum”
INT
4
Number of Pictures
Response
“ret”
INT
4
“result”
STR
VAR
Error Code
Error Description
Reference code：action/exscreen/ActionImageCarousel.java
3.3.5.3 Display Customer data
Instruction：”exscreen.cmd.custom_msg”
Parameter list：
Parameter
Type
Length
Effective/Default Value
Description
Request
“data”
BIN
Customer data，line feed
by ’&’
VAR
Response
“ret”
INT
4
“result”
STR
VAR
Error Code
Error Description
Reference code：action/exscreen/ActionDisplayCustomMsg.java
3.3.5.4 Display QR code
Instruction：”exscreen.cmd.qrcode”
Parameter list：
Parameter
Type
Length
Effective/Default Value
Description
Request
“data”
“payType”
BIN
STR
UTF8 format String
VAR
VAR
“ALIPAY”: AliPay Logo
“WECHATPAY”:
Wechat
Logo
Optional Field
Response
“ret”
INT
4
“result”
STR
VAR
Reference code：action/exscreen/ActionDisplayQR.java
3.3.6
Print operation
Error Code
Error Description
3.3.6.1 Out of paper checks
Instruction：”printer.cmd.paperout”
Parameters list：
Parameter
Type
Length
Effective/Default Value
Description
Request
none
Response
“ret”
INT
4
Error code
“result”
STR
VAR
Error description
Reference Code：action/printer/ActionPrintCheckpaper.java
3.3.6.2 Print text
Instruction：”printer.cmd.text”
Parameters list：
Parameter
type
Length
Effective/Default Value
Description
Request
“data”
STR
VAR
“size”
INT
4
“fonttype”
INT
4
Print content
Greater than 0，defalue is 24
Font size
android.graphics.Typeface.NORMAL（default）
android.graphics.Typeface.BOLD
Normal
android.graphics.Typeface.ITALIC
Ltalic
android.graphics.Typeface.BOLD_ITALIC
Bold<alic
Bold
“linegap”
INT
4
Greater than 0，defalue is 6
Line spacing
“leftmargin”
INT
4
Greater than or equal to 0, default is 0
The left margin
of page
“rightmargin”
INT
4
Greater than or equal to 0, default is 0
The right margin
of page
“typeface”
STR
VAR
Eg:”/mnt/sdcard/kaiti.ttf”（optional）
The custom font
file path
Response
“ret”
INT
4
“result”
STR
VAR
Error code
Error Description
Reference Code：action/printer/ActionPrintText.java
3.3.6.3 Paper feed
Instruction：”printer.cmd.feed”
Parameters list：
parameter
type
length
Effective/Default Value
Description
Request
"lines"
INT
4
Paper feed lines
Response
“ret”
INT
4
“result”
STR
VAR
Error code
Error Description
Reference Code：action/printer/ActionPrintText.java
3.3.6.4 Print OB code
Instruction：”printer.cmd.obcode”
Parameters list：
parameter
type
length
Effective/Default Value
Descripton
Request
“data”
STR
VAR
Print content
Response
“ret”
INT
4
“result”
STR
VAR
Error code
Error Description
Reference Code：action/printer/ActionPrintObcode.java
3.3.6.5 Print QR codes
Instruction：”printer.cmd.qrcode”
Parameters list：
Parameter
Type
Length
Effective/Default Value
Description
Request
“data”
STR
VAR
Print content
Response
“ret”
INT
4
“result”
STR
VAR
Error code
Error Description
Reference Code：action/printer/ActionPrintQrcode.java
3.3.6.6 Print pictures
Instruction：”printer.cmd.photo”
Parameters list：
Parameter
Type
Length
Effective/Default Value
Description
Request
“data”
Bitmap
VAR
Picture data
Response
“ret”
INT
4
“result”
STR
VAR
Error code
Error description
Reference Code：action/printer/ActionPrintPhoto.java
3.3.6.7 Printer busy
Instruction: ”printer.cmd.busy”
Parameters list：
Parameter
Type
Length
Effective/Default Value
Description
Request
Response
“ret”
INT
4
Error code
“result”
STR
VAR
Error description
Reference Code：action/printer/ActionPrintBusy.java
3.3.7 Serial Operation
3.3.7.1 Open Serial
Instruction:"usbserial.cmd.serialopen"
Parameter
“serialconfig”
Typ
e
Length
STR
VAR
Effective/Default Value
Description
Request
eg:"115200,n,8,1"( Optional Field
)
Serial init param（Baud rate，check
code，data bits，stop bit）
Response
“ret”
INT
4
“result”
STR
VAR
Error Code
Error Description
Reference code：action/serial/ActionOpen.java
3.3.7.2 Close Serial
Instruction:"usbserial.cmd.serialclose"
Parameter
Typ
e
Length
Effective/Default Value
Description
Request
NULL
Response
“ret”
INT
4
“result”
STR
VAR
Error Code
Error Description
Reference code：action/serial/ActionClose.java
3.3.7.3 Receive Data
Instruction:"usbserial.cmd.serialrx"
Typ
e
Length
maxDataLen
INT
4
>0，<=1024
Max data Length
Timeout_ms
INT
4
>0，<=10000
Response
Reading data Timeout (ms)
“ret”
INT
4
“result”
STR
VAR
Error Description
"data"
BIN
VAR
Receive data
Parameter
Effective/Default Value
Description
Request
Error Code
Reference code：action/serial/ActionRx.java
3.3.7.4 Send Data
Instruction:"usbserial.cmd.serialtx"
Typ
e
Length
data
BIN
VAR
dataLen
INT
4
Parameter
Effective/Default Value
Description
Request
Sending data
>0，<=>1024
Length of sending data
Response
“ret”
INT
4
“result”
STR
VAR
Error Code
Error Description
Reference code：action/serial/ActionTx.java
4. Error message define
Define
Value（HEX）
Value
Introduction
（DEC）
KV.RET.OK
0x00
0
success
KV.RET.DATA_ERROR
0x10
16
Communicate data error
KV.RET.CMD_ERROR
0x11
17
Instruction error
KV.RET.PARAM_ERR
0x12
18
Param error
KV.RET.FAILED
0x20
32
Instruction done failed
KV.RET.BUSY
0x21
33
Doing another Instruction
KV.RET.PROCESSING
0x22
34
Instruction is doing
KV.RET.TIMEOUT
0x23
35
Instruction doing wait timeout
KV.RET.CANCELED
0x24
36
Customer stop operation
KV.RET.EMV_FAILED
0x30
48
EMV error
KV.RET.COMMUNICATE_ERROR
0x40
64
Communicate failed
KV.RET.DEVICE_ERROR
0x50
80
Device abnormal
KV.RET.OPEN_FAILED
0x51
81
Device open failed
5. Keys distribution and management rules
This is used to illustrate the Kivvi payment terminals (Par6, Par10), each application (App)
key distribution and use of the rules.
5.1 Keys amount
Kivvi payment terminals (Par6, Par10)include 15 keys independent of each other
5.2 Keys allocation rules
5.2.1 Keys mutual independence
Keys are divided by each App, each App uses it self’s keys.
5.2.2 keys number of each App
Each app include 0-5 keys. If it has one key ,the app ID is “1”.If it has two keys, the app ID are
“1” and “2”,and so on.
5.2.3 The initial position of Keys
If an app include at least one key, the number of app ID begin with “1”,different app uses
different key even if they have same app ID.
5.2.4 Permissions and key Assignments
It must add pinpad action permissions first when you want get the appId distribution.
Premission Fetch code :
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.7 Linearized : No Page Count : 31 Language : zh-CN Tagged PDF : Yes XMP Toolkit : 3.1-701 Producer : Microsoft® Word 2016 Creator : Hai Wang Creator Tool : Microsoft® Word 2016 Create Date : 2017:06:20 10:50:44+08:00 Modify Date : 2017:06:20 10:50:44+08:00 Document ID : uuid:8FA703EA-27E6-4E6E-A096-CC805CF85F60 Instance ID : uuid:8FA703EA-27E6-4E6E-A096-CC805CF85F60 Author : Hai WangEXIF Metadata provided by EXIF.tools