PAX CLSS L2 API Programming Guide For Common Definition

PAX CLSS L2 API
Programming Guide
For Common Definition
Version 1.1.7
I
Copyright © 2020-2025 PAX Computer Technology (Shenzhen) Co., Ltd.
All rights reserved. No part of the contents of this document may be reproduced or
transmitted in any form without the written permission of PAX Computer Technology
(Shenzhen) Co., Ltd.
The information contained in this document is subject to change without notice.
Although PAX Computer Technology (Shenzhen) Co., Ltd. has attempted to ensure
the accuracy of the contents of this document, this document may include errors or
omissions. The examples and sample programs are for illustration only and may not
be suited for your purpose. You should verify the applicability of any example or
sample program before placing the software into productive use.
II
Revision History
Date Version Note Author

2009-10-27 v1.0.0 Create
2009-11-04 v1.0.1 1. modify explanations of some macro

define
2. Increase macro definition:
CLSS_CARD_EXPIRED
2012-09-17 V1.0.2 1. Increases return code of kernel.

2. Add the instruction of structure
Clss_PreProcInfo
3. Add AE kernel type macro definition.
4. Add one CVM method macro
definition.
yingl
RD_CVM_CONSUMER_DEVICE
5. Add two transaction sub path for Visa
payWaveMSD part.
CLSS_VISA_MSD_CVN17,
CLSS_VISA_MSD_LEGACY
2013-04-10 V1.0.3 1. Modify the Introductions of

EMV_CAPK.
2013-07-04 V1.0.4 1. Add Zip and FLASH kennel type

macro definition.
2. Add transaction type macro definition.
2013-07-22 V1.0.5 1. Add the macro definitions of the

outcome of transaction, 2.9
zhoujie
2. Modify the title of 2.7 from transaction
type to AC type.
2013-12-20 V1.0.6 1. Add the macro definitions of Outcome

Zhoujie
Parameter Set
2015-01-01 V1.0.7 1. Add the macro definitions of EFTPOS Wengfh
kernel type. Refer to 2.2.
III
2. Add the macro definitions of
JCB/D-PAS transaction mode. Refer to
2.5.
2015-06-12 V1.0.8 Add two return codes Zhou Jie

CLSS_LAST_CMD_ERR and
CLSS_API_ORDER_ERR
2015-09-23 V1.0.9 Add return code wengfh
CLSS_TRY_ANOTHER_CARD
2016-03-22 V1.1.0 1. Add return code Yingl&Zh

oujie
CLSS_TORN_CARDNUM_ERR
CLSS_TRON_AID_ERR
CLSS_TRON_AMT_ERR
CLSS_CARD_EXPIRED_REQ_ONLINE
CLSS_PAYMENT_NOT_ACCEPT
2. Add structure:
EMV_APPLIST
2017-02-22 V1.1.1 1. Add return code wengfh
CLSS_FILE_NOT_FOUND
CLSS_TRY_AGAIN
2. Add kernel type :KERNTYPE_PURE
3. Update structure Clss_PreProcInfo and
Clss_PreProcInterInfo
2017-08-10 V1.1.2 1. Add two return code, Zhoujie&

CLSS_INSERTED_ICCARD and Huyz
CLSS_SWIPED_MAGCARD
2. Add macro definition:
CLSS_MAX_COMBINATION_NUM
3. Add two kernel type definition:
KERNTYPE_PAGO and
KERNTYPE_MIR
IV
2018-10-30 V1.1.3 1. Add kernel type definition: wangsy
KERNTYPE_RUPAY
2019-02-27 V1.1.4 1. Add macro definition: sunwei

CLSS_MAX_CANDAPP_NUM
2019-04-18 V1.1.5 1. Add struct definition: zhengyq

Clss_ProgramID_II
2020-07-30 V1.1.6 1. Add CVM types: zhengyq

RD_CVM_SIG_NO_IMAGE and
RD_CVM_FAIL_CVM.
2. Add return codes:
CLSS_REQ_JUSTOUCH_APP and
CLSS_DECRYPT_FAILED
3. Add online result:
ONLINE_SWITCH
4. Add transaction mode definition:
TRANS_MODE_MAG and
TRANS_MODE_EMV
5. Add macro:
SUPPORT_EXTEND.
6. Update file format.
2021-11-17 V1.1.7 1. Add return code definition: sunwei

CLSS_AUTH_CONSUMER_DEVICE
.
2. Add online result definition:
ONLINE_PINREQ.
3. Add kernel type definition:
KERNTYPE_CPACE.
4. Add struct definition:
Clss_PreProcInfoEx.
V
Contents
1 Introduction ......................................................................................................................... 1
1.1 Purpose ..................................................................................................................... 1
1.2 Abbreviation ............................................................................................................. 1
1.3 Document Conventions ............................................................................................ 1
2 Macro Definitions ................................................................................................................ 3
2.1 Return Code .............................................................................................................. 3
2.2 Kernel Application Type .......................................................................................... 7
2.3 Transaction Online Result ........................................................................................ 8
2.4 CVM Method ............................................................................................................ 8
2.5 Transaction Path Used by CLSS Kernel ................................................................... 9
2.6 Reader Supported Application Type....................................................................... 10
2.7 ACtype .................................................................................................................... 11
2.8 Other ....................................................................................................................... 11
2.9 The Outcome of Transaction .................................................................................. 12
2.10 Outcome Parameter Set Related Definition ........................................................ 12
3 Data Structure Definitions ................................................................................................. 14
3.1 EMV_CAPK ........................................................................................................... 14
3.2 EMV_REVOCLIST ............................................................................................... 15
3.3 Clss_PreProcInfo .................................................................................................... 16
3.4 Clss_PreProcInfoEx ................................................................................................ 18
3.5 Clss_PreProcInterInfo ............................................................................................. 20
3.6 Clss_TransParam .................................................................................................... 22
3.7 Clss_ReaderParam .................................................................................................. 22
3.8 Clss_SchemeID_Info .............................................................................................. 24
3.9 Clss_VisaAidParam ................................................................................................ 25
3.10 Clss_PbocAidParam ............................................................................................ 26
3.11 Clss_MCAidParam.............................................................................................. 27
VI
3.12 Clss_ProgramID .................................................................................................. 29
3.13 Clss_ProgramID_II ............................................................................................. 30
3.14 EMV_APPLIST .................................................................................................. 32
3.15 Clss_PbocTornConfig ......................................................................................... 34
VII
PAX CLSS L2 API Programming Guide
1 Introduction
1.1 Purpose
This document describe definitions of macros and data structure which are used in L2
Kernel Library JCB、PayPass、payWave、qPBOC、AE、ZIP/DPAS、Flash、EFTPOS
and so on. All of these Macros definitions are defined in CL_common.h . In order to
use these definitions, application program need to include CL_common.h.
1.2 Abbreviation
【List out the definitions of nomenclature and abbreviation in this document.】
Table 1 Abbreviation
Abbreviation Description
CLSS Contactless
1.3 Document Conventions
【List out all document conventions and the corresponding definitions.】
1
【Used for labeling common notes.】
【Used for reminding the audience to pay attention, which may

lead to exceptions or errors.】
【Used for warning the audience to be very careful, which may

lead to serious errors or damages.】
2
2 Macro Definitions
2.1 Return Code
Return code Value Remark

EMV_OK 0 All processing is successful
ICC_RESET_ERR -1 IC card reset is failed
ICC_CMD_ERR -2 IC card command is failed
ICC_BLOCK -3 IC card is blocked
EMV_RSP_ERR -4 Status Code returned by IC

card is not 9000
EMV_APP_BLOCK -5 The Application selected is

blocked
EMV_NO_APP -6 There is no AID matched

between ICC and terminal
EMV_USER_CANCEL -7 The Current operation or

transaction was canceled by
3
user
EMV_TIME_OUT -8 User’s operation is timeout
EMV_DATA_ERR -9 Data error is found
EMV_NOT_ACCEPT -10 Transaction is not accepted
EMV_DENIAL -11 Transaction is denied
EMV_KEY_EXP -12 Certification Authority Public

Key is Expired
EMV_NO_PINPAD -13 PIN enter is required, but PIN

pad is not present or not
working
EMV_NO_PASSWORD -14 PIN enter is required, PIN pad

is present, but there is no PIN
entered
EMV_SUM_ERR -15 Checksum of CAPK is error
EMV_NOT_FOUND -16 Appointed Data Element

can’t be found
EMV_NO_DATA -17 The length of the appointed

Data Element is 0
EMV_OVERFLOW -18 Memory is overflow
NO_TRANS_LOG -19 There is no Transaction log
RECORD_NOTEXIST -20 Appointed log is not existed
LOGITEM_NOTEXIST -21 Appointed Label is not

existed in current log record
ICC_RSP_6985 -22 Status Code returned by IC

card for GPO is 6985
CLSS Kernel new return code
4
CLSS_USE_CONTACT -23 Must use other interface for

the transaction
EMV_FILE_ERR -24 There is file error found
CLSS_TERMINATE -25 Must terminate the

transaction
CLSS_FAILED -26 Contactless transaction is

failed
CLSS_DECLINE -27 Transaction should be

declined.
CLSS_TRY_ANOTHER_CARD -28 Try another card(DPAS Only)
CLSS_PARAM_ERR -30 Parameter is error =

EMV_PARAM_ERR
CLSS_WAVE2_OVERSEA -31 International transaction(for

VISA AP payWaveLevel2 IC
card use)
CLSS_WAVE2_US_CARD -33 US card(for VISA AP

payWaveL2 IC card use)
CLSS_WAVE3_INS_CARD -34 Need to use IC card for the

transaction(for VISA
payWave IC card use)
CLSS_RESELECT_APP -35 Select the next AID in

candidate list
CLSS_CARD_EXPIRED -36 IC card is expired
EMV_NO_APP_PPSE_ERR -37 Select PPSE command

returns error code, or there
is no matching Application
CLSS_USE_VSDC -38 Switch to Contactless PBOC
CLSS_CVMDECLINE -39 CVM result in decline
5
CLSS_REFER_ -40 Status Code returned by IC

card is 6986, please see phone
CONSUMER_DEVICE
CLSS_LAST_CMD_ERR -41 Terminal did not receive the

response of the last command
of Read Record. (qPBOC
only)
CLSS_API_ORDER_ERR -42 APIs are called in wrong

order. Please call
Clss_GetDebugInfo_xxx to
get error codes.
CLSS_TORN_CARDNUM_ERR -43 Torn log's PAN is different

With the reselect card's pan.
CLSS_TRON_AID_ERR -44 Torn log's AID is different

with the reselect card's AID
CLSS_TRON_AMT_ERR -45 Torn log's amount is different

with the current transaction’s
amount.
CLSS_CARD_EXPIRED_REQ_ONLINE -46 Card expired and the

transaction should go online.
CLSS_FILE_NOT_FOUND -47 ICC return 6A82 (File not

found) in response to the
SELECT command
CLSS_TRY_AGAIN -48 Try again
CLSS_REQ_JUSTOUCH_APP -49 Request execution of

JUSTOUCH APP
CLSS_DECRYPT_FAILED -50 Decrypting data is failed
CLSS_AUTH_CONSUMER_DEVICE -51 In case that consumer device

without display respond 6987
to GPO command, message
6
"Please authenticate yourself

to your device and try again"
need to be shown on terminal.
CLSS_PAYMENT_NOT_ACCEPT -200 Payment Type Not Accepted

for flash
CLSS_INSERTED_ICCARD -301 IC card is detected during

contactless transaction
CLSS_SWIPED_MAGCARD -302 Magnetic stripe card is

detected during contactless
transaction
2.2 Kernel Application Type
Return code or Parameter Value Remark

KERNTYPE_DEF 0x00 Default Value(Kernel classify
base on RID)
KERNTYPE_JCB 0x01 JCB
KERNTYPE_MC 0x02 MasterCard
KERNTYPE_VIS 0x03 VISA
KERNTYPE_PBOC 0x04 PBOC
KERNTYPE_AE 0x05 American Express
KERNTYPE_ZIP 0x06 Zip/DPAS
KERNTYPE_FLASH 0x07 Flash
KERNTYPE_EFT 0x08 EFTPOS
KERNTYPE_PURE 0x09 PURE(Malaysian)
KERNTYPE_PAGO 0x0A PAGO(Italy)
7
KERNTYPE_MIR 0x0B MIR(Russia)
KERNTYPE_RUPAY 0x0C RUPAY
KERNTYPE_WISE 0x0D WISE
KERNTYPE_JUSTOUCH 0x0E JUSTOUCH
KERNTYPE_CPACE 0x0F CPACE
KERNTYPE_RFU 0xFF RFU
2.3 Transaction Online Result

REFER_APPROVE 0x01 Reference Return code (Choose Approved)
REFER_DENIAL 0x02 Reference Return code (Choose Denial)
ONLINE_APPROVE 0x00 Online Return code (Online Approved)
ONLINE_FAILED 0x01 Online Return code (Online Failed)
ONLINE_REFER 0x02 Online Return code (Online Reference)
ONLINE_DENIAL 0x03 Online Return code (Online Denial)
ONLINE_ABORT 0x04 Compatible PBOC(Transaction Terminate)
ONLINE_SWITCH 0x05 Online Return code (Try another interface if

supported)
ONLINE_PINREQ 0x06 Issuer requests Online PIN (Online Pin)
2.4 CVM Method

RD_CVM_NO 0x00 No CVM
8
RD_CVM_SIG 0x10 Signature
RD_CVM_ONLINE_PIN 0x11 Online PIN
RD_CVM_OFFLINE_PIN 0x12 Offline PIN
RD_CVM_SIG_NO_IMAGE 0x13 Signature(Signature image is not

included)
RD_CVM_CONSUMER_DEVICE 0x1F Refer to consumer device
RD_CVM_FAIL_CVM 0x2F Fail CVM
RD_CVM_REQ_SIG 0x01 When amount greater than CVM

limit, Cardholder verification
methods ask for process
signature (Only for VISA
Application）
RD_CVM_REQ_ONLINE_PIN 0x02 When amount greater than CVM

limit, Cardholder verification
methods ask for process Online
PIN(Only for VISA
Application）
2.5 Transaction Path Used by CLSS Kernel

CLSS_VISA_MSD 1 MSD Path (Used for qPBOC and
Visa payWave)
CLSS_VISA_QVSDC 2 qPBOC/qVSDCPath (Used for

qPBOC and Visa payWave)
CLSS_VISA_VSDC 3 Contactless PBOC Path
CLSS_VISA_CONTACT 4 Contact EMV Path
CLSS_MC_MAG 5 MasterCard PayPass MagStripe Path
9
CLSS_MC_MCHIP 6 MasterCard PayPassM/ChipPath
CLSS_VISA_WAVE2 7 VISA AP Wave2 Path
CLSS_JCB_WAVE2 8 SCHEME_JCB_WAVE_2Path
CLSS_VISA_MSD_CVN17 9 MSD CVN 17 for Visa payWave
CLSS_VISA_MSD_LEGACY 10 MSD legacy for Visa payWave
CLSS_JCB_MAG 11 JCB Mag Stripe Path(J/Speedy)
CLSS_JCB_EMV 12 JCB EMV Path(J/Speedy)
CLSS_JCB_LEGACY 13 JCB Legacy Path(J/Speedy)
CLSS_DPAS_MAG 14 D-PAS Mag Stripe Path
CLSS_DPAS_EMV 15 D-PAS EMV Path
CLSS_DPAS_ZIP 16 D-PAS ZIP Path
TRANS_MODE_MAG 17 Magstripe Mode
TRANS_MODE_EMV 18 EMV mode
2.6 Reader Supported Application Type
(Only fit for VISA and JCB Application)

SCHEME_VISA_WAVE_2 0x16 VISA Wave2 Application
SCHEME_VISA_WAVE_3 0x17 VISA Wave3 Application
SCHEME_VISA_MSD_20 0x18 VISA MSD Application
SCHEME_JCB_WAVE_1 0x19 JCB wave 1 Application
10
2.7 ACtype

AC_AAC 0x00 AAC
AC_TC 0x01 TC
AC_ARQC 0x02 ARQC
2.8 Other

MAX_APP_NUM 100 Maximum number of
application number saved by
EMV L2 Kernel Library
Application List
MAX_REVOCLIST_NUM 30 Maximum number of Issuer

Public Key Certificate
Recover List saved by EMV
L2 kernel Library
CLSS_MAX_KEY_NUM 7 Maximum number of

Certification Authenticate
Public Key supported by
CLSS Kernel
CLSS_MAX_AIDLIST_NUM 32 Maximum number of AID

supported by CLSS Kernel
CLSS_MAX_COMBINATION_NUM 64 Maximum number of

Combinations for contactless
kernel (for Entry Point)
CLSS_MAX_CANDAPP_NUM 17 Maximum number of candidate

application number for
contactless kernel
11
PART_MATCH 0x00 Application Select matching

flag (Partial match)
FULL_MATCH 0x01 Application Select matching

flag (Exact match)
SUPPORT_EXTEND 0x02 Extended Selection is supported

by terminal.
2.9 The Outcome of Transaction

CLSS_DECLINED 0x00 Transaction is declined
CLSS_APPROVE 0x01 Transaction is approved
CLSS_ONLINE_REQUEST 0x02 Transaction shall send online request
CLSS_TYR_ANOTHER_INTERFACE 0x03 Try another interface
CLSS_END_APPLICATIION 0x04 Transaction is terminated, please end

application
2.10 Outcome Parameter Set Related Definition

CLSS_OC_APPROVED 0x10 Byte 1 b8-5 (Status) is APPROVED
CLSS_OC_DECLINED 0x20 Byte 1 b8-5 (Status) is DECLINED
CLSS_OC_ONLINE_REQUEST 0x30 Byte 1 b8-5 (Status) is ONLINE

REQUEST
CLSS_OC_END_APPLICATION 0x40 Byte 1 b8-5 (Status) is END

APPLICATION
12
CLSS_OC_SELECT_NEXT 0x50 Byte 1 b8-5 (Status) is TRY AGAIN
CLSS_OC_TRY_ANOTHER_INTERFACE 0x60 Byte 1 b8-5 (Status) is TRY

ANOTHER INTERFACE
CLSS_OC_TRY_AGAIN 0x70 Byte 1 b8-5 (Status) is TRY AGAIN
CLSS_OC_NA 0xF0 NA
CLSS_OC_A 0x00 Byte 2 b8-5 (Start) is A
CLSS_OC_B 0x10 Byte 2 b8-5 (Start) is B
CLSS_OC_C 0x20 Byte 2 b8-5 (Start) is C
CLSS_OC_D 0x30 Byte 2 b8-5 (Start) is D
CLSS_OC_NO_CVM 0x00 Byte 4 b8-5 (CVM) is NO CVM
CLSS_OC_OBTAIN_SIGNATURE 0x10 Byte 4 b8-5 (CVM) is SIGNATURE
CLSS_OC_ONLINE_PIN 0x20 Byte 4 b8-5 (CVM) is ONLINE PIN
CLSS_OC_CONFIRM_CODE_VER 0x30 Byte 4 b8-5 (CVM) is

CONFIRMATION CODE VERIFIED
13
3 Data Structure Definitions
3.1 EMV_CAPK
EMV_CAPK
typedef struct{
unsigned char RID[5];
unsigned char KeyID;
unsigned char HashInd;
unsigned char ArithInd;
unsigned char ModulLen;
unsigned char Modul[248];
unsigned char ExponentLen;
unsigned char Exponent[3];
unsigned char ExpDate[3];
unsigned char CheckSum[20];
}EMV_CAPK；
Parameters Description
14
RID Registered Application Provider Identifier
KeyID Key Index
HashInd Hash arithmetic indicator
ArithInd RSA arithmetic indicator
ModulLen Length of Module
Modul Module
ExponentLen Length of exponent
Exponent Exponent
ExpDate Expiration Date (YYMMDD)
CheckSum CheckSum of Key
3.2 EMV_REVOCLIST
EMV_REVOCLIST
typedef struct{
unsigned char ucRid[5];
unsigned char ucIndex;
unsigned char ucCertSn[3];
}EMV_REVOCLIST；
ucRid RID : Registered Application Provider Identifier
ucIndex Certification Authenticate Public Key Index
ucCertSn Issuer Certificate Serial Number
15
3.3 Clss_PreProcInfo
Clss_PreProcInfo
typedef struct CLSS_PREPROCINFO
{
unsigned long ulTermFLmt;
unsigned long ulRdClssTxnLmt;
unsigned long ulRdCVMLmt;
unsigned long ulRdClssFLmt;
unsigned char aucAID[17];
unsigned char ucAidLen;
unsigned char ucKernType;
unsigned char ucCrypto17Flg;
unsigned char ucZeroAmtNoAllowed;
unsigned char ucStatusCheckFlg;
unsigned char aucReaderTTQ[5];
unsigned char ucTermFLmtFlg;
unsigned char ucRdClssTxnLmtFlg;
unsigned char ucRdCVMLmtFlg;
unsigned char ucRdClssFLmtFlg;
unsigned char aucRFU[5];
}Clss_PreProcInfo;
ulTermFLmt Terminal Offline limit
ulRdClssTxnLmt Reader contactless transaction limit
ulRdCVMLmt Reader CVM limit
ulRdClssFLmt Reader contactless Offline limit
aucAID Application Identifier
ucAidLen Length of AID
ucKernType Kernel Type.

KERNTYPE_DEF: Kernel do match according to RID
16
KERNTYPE_JCB: JCB.
KERNTYPE_MC: MASTERCARD.
KERNTYPE_VIS: VISA.
KERNTYPE_PBOC: qPBOC.
KERNTYPE_AE: American Express.
KERNTYPE_ZIP: ZIP/DPAS
KERNTYPE_FLASH: Flash
KERNTYPE_EFT: EFT POS
ucCrypto17Flg MSD CVN17 support flag(PayWave/qPBOC)

0- not support
1- support
ucZeroAmtNoAllowed Amount, Authorized of Zero Check flag

0- Flag activated, online required
1- Flag activated, amount zero not allowed
2-Flag deactivated
ucStatusCheckFlg Status check support flag

0- not support
1- support
aucReaderTTQ Terminal Transaction Qualifiers
ucTermFLmtFlg Terminal Offline limit check flag

0- Deactivated
1- Active and exist
2- Active but not exist
ucRdClssTxnLmtFlg Reader contactless transaction limit check flag

0- Deactivated
1- Active and exist
ucRdCVMLmtFlg Card reader CVM limit check flag

0- Deactivated
1- Active and exist
17
ucRdClssFLmtFlg Card reader contactless Offline limit check flag

0- Deactivated
1- Active and exist
aucRFU Reserved for Future Use
3.4 Clss_PreProcInfoEx
Clss_PreProcInfo
typedef struct CLSS_PREPROCINFOEX
{
unsigned char aucTermFLmt[6];
unsigned char aucRdClssTxnLmt[6];
unsigned char aucRdCVMLmt[6];
unsigned char aucRdClssFLmt[6];
unsigned char ucKernType;
unsigned char ucZeroAmtNoAllowed;
}Clss_PreProcInfoEx;
aucTermFLmt Terminal Offline limit
aucRdClssTxnLmt Reader contactless transaction limit
18
aucRdCVMLmt Reader CVM limit
aucRdClssFLmt Reader contactless Offline limit
aucAID Application Identifier
ucAidLen Length of AID
ucKernType Kernel Type.

KERNTYPE_DEF: Kernel do match according to RID
KERNTYPE_JCB: JCB.
KERNTYPE_MC: MASTERCARD.
KERNTYPE_VIS: VISA.
KERNTYPE_PBOC: qPBOC.
KERNTYPE_AE: American Express.
KERNTYPE_ZIP: ZIP/DPAS
KERNTYPE_FLASH: Flash
KERNTYPE_EFT: EFT POS
ucCrypto17Flg MSD CVN17 support flag(PayWave/qPBOC)

2- not support
3- support
ucZeroAmtNoAllowed Amount, Authorized of Zero Check flag

2-Flag deactivated

2- not support
3- support
aucReaderTTQ Terminal Transaction Qualifiers

3- Deactivated
4- Active and exist
19

3- Deactivated
4- Active and exist

3- Deactivated
4- Active and exist

3- Deactivated
4- Active and exist
3.5 Clss_PreProcInterInfo
CLSS_PREPROC_INTER_FLAG_INFO
typedef struct{
unsigned char ucZeroAmtFlg;
unsigned char ucCLAppNotAllowed;
unsigned char ucTermFLmtExceed;
unsigned char ucRdCLTxnLmtExceed;
unsigned char ucRdCVMLmtExceed;
unsigned char ucRdCLFLmtExceed;
20
unsigned char ucRandomSelect;

}Clss_PreProcInterInfo；
aucAID AID: Application Identifier
ucAidLen Application Identifier length
ucZeroAmtFlg 0- Transaction amount is not equal to 0

1- Transaction amount is equal to 0
ucStatusCheckFlg Status Check Flag
aucReaderTTQ Terminal Transaction Qualifiers, used for

VISA/qPBOC, tag equal to’9F66’
ucCLAppNotAllowed 1-this AID can’t progress contactless transaction
ucTermFLmtExceed Terminal Offline limit exceed flag
0-not exceed，1-exceed
ucRdCLTxnLmtExceed Reader contactless transaction limit exceed flag
ucRdCVMLmtExceed Reader CVM limit exceed flag
ucRdCLFLmtExceed; Reader contactless Offline limit exceed flag
0-not exceed，1- exceed
ucTermFLmtFlg Terminal Offline limit present flag
0-not present，1- present
aucTermFLmt Terminal Offline limit
21
ucCrypto17Flg; PayWave crypto 17 flag
ucRandomSelect Random Transaction Selection
3.6 Clss_TransParam
Clss_TransParam
typedefstruct{
unsigned long ulAmntAuth;
unsigned long ulAmntOther;
unsigned long ulTransNo;
unsigned char ucTransType;
unsigned char aucTransDate[4];
unsigned char aucTransTime[4];
}Clss_TransParam；
ulAmntAuth Authority Amount
ulAmntOther Amount Other
ulTransNo Transaction Sequence Counter(4 BYTE)
ucTransType Transaction Type '9C'
aucTransDate Transaction Date YYMMDD
aucTransTime Transaction Time HHMMSS
3.7 Clss_ReaderParam
Clss_ReaderParam
22
typedefstruct{
unsigned long ulReferCurrCon;
unsigned short usMchLocLen;
unsigned char aucMchNameLoc[257];
unsigned char aucMerchCatCode[2];
unsigned char aucMerchantID[15];
unsigned char AcquierId[6];
unsigned char aucTmID[8];
unsigned char ucTmType;
unsigned char aucTmCap[3];
unsigned char aucTmCapAd[5];
unsigned char aucTmCntrCode [2];
unsigned char aucTmTransCur[2];
unsigned char ucTmTransCurExp;
unsigned char aucTmRefCurCode[2];
unsigned char ucTmRefCurExp;
}Clss_ReaderParam；
ulReferCurrCon Reference currency code and transaction code’s

transform modulus (transaction currency to Reference
currency exchange rate *1000)
usMchLocLen Merchant name and location data field’s length
aucMchNameLoc Merchant name and location(1-256 Byte)
aucMerchCatCode Merchant classify code'9F15'(2 Byte)
aucMerchantID Merchant Identifier (15 Byte)
AcquierId Acquirer Identifier
aucTmID Terminal Identifier (Terminal Number)
ucTmType Terminal Type
aucTmCap Terminal capability
23
aucTmCapAd Terminal additional capability
aucTmCntrCode Terminal country code
aucTmTransCur Terminal Transaction currency code '5F2A'(2 Byte)
ucTmTransCurExp Terminal Transaction currency exponent '5F36'

(1Byte)
aucTmRefCurCode Terminal Transaction Reference currency code

'9F3C'(2 Byte)
ucTmRefCurExp Terminal Transaction Reference currency exponent

'9F3D' (1Byte)
3.8 Clss_SchemeID_Info
Clss_SchemeID_Info
typedefstruct{
unsigned char ucSchemeID;
unsigned char ucSupportFlg;
unsigned char ucRFU[2];
}Clss_SchemeID_Info；
ucSchemeID Reference Application type parameter Macro

definition
#define SCHEME_VISA_WAVE_2 0x16
#define SCHEME_VISA_WAVE_3 0x17
#define SCHEME_VISA_MSD_20 0x18
24
#define SCHEME_JCB_WAVE_1 0x60

ucSupportFlg 1-support; 0-not support
ucRFU Reserved for Future Use
Presently this Structure only used in VISA and JCB Application.
3.9 Clss_VisaAidParam
Clss_VisaAidParam
typedefstruct{
unsigned char ucDomesticOnly;
unsigned char ucCvmReqNum;
unsigned char aucCvmReq[5];
unsigned char ucEnDDAVerNo;
}Clss_VisaAidParam；
ulTermFLmt Floor Limit – the same as contact EMV Floor Limit
ucDomesticOnly 0x01(default): only support domestic contactless

transaction
0x00: support domestic and international contactless
transaction
ucCvmReqNum the number of supported CVM type(number of

aucCvmReq[] type)
aucCvmReq when the amount greater than contactless CVM Limit，

CVM types which need to process
25
0x01-Signature 0x02-Online PIN
ucEnDDAVerNo 0x00-Default value, Reader support all DDA version

IC card offline transaction
0x01-Only support'01' version of DDA’s IC card
offline transaction
1. ucDomesticOnly, ucCvmReqNum and aucCvmReq are

Visa AP wave 2 Application proprietary parameter.
2. As the R50 and R30 support neither signature nor PIN
Entry, so parameter ucCvmReqNum can set to 0,
aucCvmReq should set to 0.
3. In Visa L2 kernel, only ucDomesticOnly member of
structure Clss_VisaAidParam default value is 1, other is
0.
3.10 Clss_PbocAidParam
PBOC_AID_PARAM
typedefstruct{
}Clss_PbocAidParam；
ulTermFLmt Floor Limit – the same as contact EMV Floor Limit
26
3.11 Clss_MCAidParam
MC_AID_PARAM
typedefstruct{
unsigned long FloorLimit;
unsigned long Threshold;
unsigned short usUDOLLen;
unsigned char uDOL[256];
unsigned char TargetPer;
unsigned char MaxTargetPer;
unsigned char FloorLimitCheck;
unsigned char RandTransSel;
unsigned char VelocityCheck;
unsigned char TACDenial[6];
unsigned char TACOnline[6];
unsigned char TACDefault[6];
unsigned char dDOL[256];
unsigned char tDOL[256];
unsigned char Version[3];
unsigned char ForceOnline;
unsigned char MagAvn[3];
unsigned char ucMagSupportFlg;
unsigned char ucRFU;
}Clss_MCAidParam；
FloorLimit Floor Limit. The same as contact EMV Floor Limit
Threshold Threshold
usUDOLLen Length of UDOL
uDOL Terminal Default UDOL
TargetPer Target Percentage
27
MaxTargetPer Maximum Target Percentage
FloorLimitCheck Weather process the Floor Limit

(1-process,0-no process)
RandTransSel Weather process the Random Transaction

Selection(1-process)
VelocityCheck Weather process the Velocity Checking

(1-process,0-no process)
TACDenial[6] Terminal Action Code (Denial)
TACOnline[6] Terminal Action Code (Online)
TACDefault[6] Terminal Action Code (Default)
AcquierId Acquirer Identity
dDOL Terminal Default DDOL
tDOL Terminal Default TDOL
Version Application Version Number
ForceOnline Transaction is forced Online by Merchant

(1- Transaction is always Online)
MagAvn Application Version Number for MagStripe
ucMagSupportFlg 1-Reader support MagStripe 0-No support
ucRFU Reserved for Future Use
PayPass L2’ Kernel should set the default value of

Clss_MCAidParam all bits to 0.
28
3.12 Clss_ProgramID
Clss_ProgramID
typedefstruct CLSS_PROGRAMID_INFO
{
unsigned long ulRdClssTxnLmt;
unsigned long ulRdCVMLmt;
unsigned long ulRdClssFLmt;
unsigned char aucProgramId[17];
unsigned char ucPrgramIdLen;
unsigned char ucAmtZeroNoAllowed;
}Clss_ProgramID;
ulRdClssTxnLmt Reader Contactless Transaction Limit
ulRdCVMLmt Reader CVM Limit
ulRdClssFLmt Reader Contactless Offline Floor Limit
ulTermFLmt Terminal Offline Floor Limit
aucProgramId Application Program ID
ucPrgramIdLen Length of Application Program ID

0- Deactivated
1- Active and exist
29
0- Deactivated
1- Active and exist

0- Deactivated
1- Active and exist

0- Deactivated
1- Active and exist

0- not support
1- support
ucAmtZeroNoAllowed Amount, Authorized of Zero Check flag

2- Flag deactivated
3.13 Clss_ProgramID_II
Clss_ProgramID_II
typedef struct CLSS_PROGRAMID_II
{
unsigned char aucRdClssTxnLmt[6];
unsigned char aucRdCVMLmt[6];
unsigned char aucRdClssFLmt[6];
unsigned char aucProgramId[17];
unsigned char ucPrgramIdLen;
30

unsigned char ucAmtZeroNoAllowed;
unsigned char ucDynamicLimitSet;
unsigned char ucRFU;;
}Clss_ProgramID_II;
aucRdClssTxnLmt Reader Contactless Transaction Limit
aucRdCVMLmt Reader CVM Limit
aucRdClssFLmt Reader Contactless Floor Limit
aucTermFLmt Terminal Floor Limit
aucProgramId Application Program ID
ucPrgramIdLen Length of Application Program ID
ucRdClssFLmtFlg aucRdClssFLmt is present or not
ucRdClssTxnLmtFlg aucRdClssTxnLmt is present or not
ucRdCVMLmtFlg aucRdCVMLmt is present or not
ucTermFLmtFlg aucTermFLmt is present or not
ucStatusCheckFlg Support Status Check or not
ucAmtZeroNoAllowed Amount 0 Check
ucDynamicLimitSet Dynamic Limit Set Id. 0xFF - Default DRL Set. Only
used in AMEX transaction.
aucRFU Reserved for future use
31
3.14 EMV_APPLIST
EMV_APPLIST
typedefstruct{
unsigned char AppName[33];
unsigned char AID[17];
unsigned char AidLen;
unsigned char SelFlag;
unsigned char Priority;
unsigned char TargetPer;
unsigned char MaxTargetPer;
unsigned char FloorLimitCheck;
unsigned char RandTransSel;
unsigned char VelocityCheck;
unsigned long FloorLimit;
unsigned long Threshold;
unsigned char TACDenial[6];
unsigned char TACOnline[6];
unsigned char TACDefault[6];
unsigned char dDOL[256];
unsigned char tDOL[256];
unsigned char Version[3];
unsigned char RiskManData[10];
}EMV_APPLIST；
Name Description
AppName[33] Local application name. The string ends with '\x00' and is
32 bytes in maximum.
Terminal can prompt for the application label or
application preferred name of the IC card EMV application
to let the cardholder to choose. But the language of the
application label or application preferred name may be
English and not convenient for the operator. In order to
display the application name in local language, the kernel
offers the setting of AppName.
If AppName[0]=0, terminal will prompt for the application
label or application preferred name.
32
If AppName is set with an application name, for example,

“银联 EMV 卡”，the application name on the terminal will
be prompted as “银联 EMV 卡”.
AID[17] Application ID, 16 bytes in maximum. (AID is
corresponding to the AppName. The kernel searches
application according to the AID.)
AidLen the length of AID
SelFlag Application selection flag (partial matching
PART_MATCH, full matching FULL_MATCH or
Extended Selection SUPPORT_EXTEND)
(Refer to the macro definition in appendix A.)
Priority priority indicator
(It’s returned by ICC, so nothing needs to be done by
application.)
TargetPer Target percent (0 – 99) (provided by acquirer)
(Refer to the risk management in EMV specification.)
MaxTargetPer Max target percent(0 – 99) (provided by acquirer)
FloorLimitCheck For the online terminal , check the floor limit or not (1:
check(default), 0 : not check)
RandTransSel For the online and offline terminal , perform random
transaction selection or not (1: perform(default), 0 : not
perform)
VelocityCheck For the online terminal , perform velocity check or not (1 :
perform(default), 0 not perform)
FloorLimit Floor limit (provided by acquirer)
Threshold Threshold (provided by acquirer)
(Refer to the risk management in EMV specification)
Notes: If Target percent is 99 and Threshold is 0xffffffff,
all the transaction will be done online.
ActDenial[6] Terminal action code - denial
(default : "\x00\x10\x00\x00\x00" (Visa140))
(It must be set if acquirer provides it.)
ActOnline[6] Terminal action code – online
(default : "\xD8\x40\x04\xF8\x00" (Visa140))
ActDefault[6] Terminal action code – default
33
(default : "\xD8\x40\x00\xA8\x00" (Visa140))

AcquierId[6] Acquirer identifier ( length between 6 to 11, compressed
BCD format, pending ‘F’ on the right)
(It must be set if acquirer provides it, otherwise set 0x0.)
dDOL[256] terminal default DDOL
dDOL[0] is the length of DDOL, the others are the value of
DDOL.
(default : "\x03\x9F\x37\x04" (Visa140))
tDOL[256] terminal default TDOL
tDOL[0] is the length of TDOL, the others are the value of
TDOL.
(default : "\x0F\x9F\x02\x06\x5F\x2A\x02\x9A\x03\x9C
\x01\x95\x05\x9F\x37\x04" (Visa140))
Version[3] Application Version Number(Terminal)
RiskManData[10] Risk management data
RiskManData[0] is the length of Risk management data,
the others are the value of Risk management data.
(RiskManData[0] default : 0)
(It needn’t be set unless issuer requires.)
3.15 Clss_PbocTornConfig
Clss_PbocTornConfig
typedefstruct PBOC_TORN_CONFIG
{
long lTornMaxLifeTime;
unsigned short usTornLogMaxNum;
unsigned short usTornSupport; //1 -Support torn Log; 0 - Not
Support.
unsigned char ucTornRFU[4]; //RFU
}Clss_PbocTornConfig;
34
lTornMaxLifeTime Torn Max life Time(unit: Second)
usTornLogMaxNum Max number for torn Log
usTornSupport Torn log support flag

1: Support
0: Not support
35

PAX CLSS L2 API Programming Guide For Common Definition

Uploaded by

PAX CLSS L2 API Programming Guide For Common Definition

Uploaded by

PAX CLSS L2 API

Date Version Note Author

2009-11-04 v1.0.1 1. modify explanations of some macro

2012-09-17 V1.0.2 1. Increases return code of kernel.

2013-04-10 V1.0.3 1. Modify the Introductions of

2013-07-04 V1.0.4 1. Add Zip and FLASH kennel type

2013-07-22 V1.0.5 1. Add the macro definitions of the

2013-12-20 V1.0.6 1. Add the macro definitions of Outcome

2015-01-01 V1.0.7 1. Add the macro definitions of EFTPOS Wengfh

kernel type. Refer to 2.2.

2015-06-12 V1.0.8 Add two return codes Zhou Jie

2015-09-23 V1.0.9 Add return code wengfh

2016-03-22 V1.1.0 1. Add return code Yingl&Zh

2017-02-22 V1.1.1 1. Add return code wengfh

2017-08-10 V1.1.2 1. Add two return code, Zhoujie&

2019-02-27 V1.1.4 1. Add macro definition: sunwei

2019-04-18 V1.1.5 1. Add struct definition: zhengyq

2020-07-30 V1.1.6 1. Add CVM types: zhengyq

2021-11-17 V1.1.7 1. Add return code definition: sunwei

【List out the definitions of nomenclature and abbreviation in this document.】

1.3 Document Conventions

【List out all document conventions and the corresponding definitions.】

【Used for labeling common notes.】

【Used for reminding the audience to pay attention, which may

【Used for warning the audience to be very careful, which may

2.1 Return Code

Return code Value Remark

ICC_RESET_ERR -1 IC card reset is failed

ICC_CMD_ERR -2 IC card command is failed

ICC_BLOCK -3 IC card is blocked

EMV_RSP_ERR -4 Status Code returned by IC

EMV_APP_BLOCK -5 The Application selected is

EMV_NO_APP -6 There is no AID matched

EMV_USER_CANCEL -7 The Current operation or

EMV_TIME_OUT -8 User’s operation is timeout

EMV_DATA_ERR -9 Data error is found

EMV_NOT_ACCEPT -10 Transaction is not accepted

EMV_DENIAL -11 Transaction is denied

EMV_KEY_EXP -12 Certification Authority Public

EMV_NO_PINPAD -13 PIN enter is required, but PIN

EMV_NO_PASSWORD -14 PIN enter is required, PIN pad

EMV_SUM_ERR -15 Checksum of CAPK is error

EMV_NOT_FOUND -16 Appointed Data Element

EMV_NO_DATA -17 The length of the appointed

EMV_OVERFLOW -18 Memory is overflow

NO_TRANS_LOG -19 There is no Transaction log

RECORD_NOTEXIST -20 Appointed log is not existed

LOGITEM_NOTEXIST -21 Appointed Label is not

ICC_RSP_6985 -22 Status Code returned by IC

CLSS Kernel new return code

CLSS_USE_CONTACT -23 Must use other interface for

EMV_FILE_ERR -24 There is file error found

CLSS_TERMINATE -25 Must terminate the

CLSS_FAILED -26 Contactless transaction is

CLSS_DECLINE -27 Transaction should be

CLSS_TRY_ANOTHER_CARD -28 Try another card(DPAS Only)

CLSS_PARAM_ERR -30 Parameter is error =

CLSS_WAVE2_OVERSEA -31 International transaction(for

CLSS_WAVE2_US_CARD -33 US card(for VISA AP

CLSS_WAVE3_INS_CARD -34 Need to use IC card for the

CLSS_RESELECT_APP -35 Select the next AID in

CLSS_CARD_EXPIRED -36 IC card is expired

EMV_NO_APP_PPSE_ERR -37 Select PPSE command

CLSS_USE_VSDC -38 Switch to Contactless PBOC

CLSS_CVMDECLINE -39 CVM result in decline

CLSS_REFER_ -40 Status Code returned by IC

CLSS_LAST_CMD_ERR -41 Terminal did not receive the

CLSS_API_ORDER_ERR -42 APIs are called in wrong

CLSS_TORN_CARDNUM_ERR -43 Torn log's PAN is different

CLSS_TRON_AID_ERR -44 Torn log's AID is different

CLSS_TRON_AMT_ERR -45 Torn log's amount is different

CLSS_CARD_EXPIRED_REQ_ONLINE -46 Card expired and the

CLSS_FILE_NOT_FOUND -47 ICC return 6A82 (File not

CLSS_TRY_AGAIN -48 Try again

CLSS_REQ_JUSTOUCH_APP -49 Request execution of

CLSS_DECRYPT_FAILED -50 Decrypting data is failed