PAX CLSS L2 API Programming Guide For Paywave Library

PAX CLSS L2 API
Programming Guide
For Paywave Library

Version 1.2.5
Copyright © 2018-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 or by any means 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 contain errors or
omissions. The examples and sample programs are for illustration only and may not
be suitable for your purpose. You should verify the applicability of any example or
sample program before placing the software into productive use.
I
Revision History
Versio
Date Note Author
n
2010-12-30 V1.0.0 Initial yingl
2011-6-10 V1.1.0 1. Delete the API

Clss_SetReaderChannel_Wave.
yingl
2. Add callback function
cPiccIsoCommand_Wave.
2012-09-13 V1.1.1 1. Add changes according to VCPS 2.1.

2. Add six functions:
Clss_ProcRestric_Wave;
Clss_IssuerAuth_Wave
Clss_IssScriptProc _Wave
Clss_GetMSDType_Wave
yingl
Clss_SetDDAOmitFlag_Wave
cClssGetUnknowTLVData_Wave
3. Support Prolin platform.
4. Debug functions are no longer used in Prolin
platform.
2012-10-12 V1.1.2 1. Modify the flow chart. Add refund

transaction type instruction.
yingl
2. Modify the flow chart. Change the MSD
transaction path
2013-11-25 V1.1.3 1. Add DRL processing instruction in 7.1. yingl
2015-05-04 V1.1.4 1. Modify the description about DRL in 7.1 Jessie Zhou
2015-06-23 V1.1.5 1. Add debug function

Clss_GetDebugInfo_Wave
2. Add the API Clss_SetDRLParam_Wave
Jessie Zhou
3. Modify the flow chart to add the calling of
Clss_SetDRLParam_Wave
4. Add a return code
II
CLSS_API_ORDER_ERR for below API,
Clss_SetReaderParam_Wave
Clss_SetTLVData_Wave
Clss_GetTLVData_Wave
Clss_SetFinalSelectData_Wave
2016-03-24 V1.1.6 1. Delete the description of return code for

Clss_SetReaderParam_Wave and Jessie Zhou
Clss_SetVisaAidParam_Wave
2016-09-23 V1.1.7 1. Add API

Clss_SetDRLParam_II_Wave
huyz
2. Add structure
Clss_ProgramID_II
2017-04-18 V1.1.8 1. Delete callback functions:

cClssGetUnknowTLVData_Wave
cPiccIsoCommand_Wave
2. Delete API
Clss_SetDebug_Wave sunping
Clss_GetICCStatus_Wave
Clss_SetEMVUnknowTLVData_Wave
(Clss_SetTLVData_Wave can take place of
it)
2017-11-29 V1.1.9 Kernel version:v351

1. Add API
Clss_SetExtendFunc_Wave sunping
2. Add the instruction about
Clss_CardAuth_Wave
2019-04-18 V1.2.0 Kernel version:v353

1. Add API
Clss_GetExtendFunc_Wave
2. Update the layout of this document
3. The description of struct
Clss_ProgramID_II is removed. Please zhengyq
refer to the description document of
CL_common.h.
4. Add description for
5. Add the function to set online ODA related
III
parameters in Clss_SetExtendFunc_Wave
with nflag value 2.
2020-12-09 V1.2.1 Kernel version v354

1. Correct reference document name to “PAX
CLSS L2 API Programming Guide For
Common Definition”.
2. Add CVM type
RD_CVM_CONSUMER_DEVICE for
function Clss_GetCvmType_Wave.
3. Add instruction for zhengyq
CLSS_REFER_CONSUMER_DEVICE
returned by Clss_Proctrans_Wave.
4. Add return code CLSS_TERMINATE for
Clss_SetTransData_Wave.
5. Add return code EMV_DATA_ERR for
Clss_CardAuth_Wave.

1. Add the instructions for
Clss_SetExtendFunc_Wave
WangSY
Clss_CoreInit_Wave
Clss_CardAuth_Wave
Clss_SetTransData_Wave

1. Update the output parameter of
Clss_Proctrans_Wave,
CLSS_VISA_WAVE2 is removed from the ZhengYQ
output value of pucTransPath.
2. Update the instruction of
Clss_nGetTrack1MapData_Wave.
2024.03.01 V1.2.4 Kernel version v357

1. Text Content Revision.
ZhengRuijia
2024.03.08 V1.2.5 Kernel version v358

1. Updated the return values of the
Clss_ReadVerInfo_Wave
ZhengRuijia
Clss_ProcRestric_Wave and
Clss_Proctrans_Wave functions.
2. Updated Clss_SetRdSchemeInfo_Wave
IV
Clss_GetSchemeInfo_Wave
Clss_nGetTrack1MapData_Wave
Clss_nGetTrack2MapData_Wave and
Clss_GetMSDType_Wave functions as expired
functions.
3. Updated the parameter description of the
Clss_SetExtendFunc_Wave and
Clss_GetExtendFunc_Wave functions.
4. Added the instructions for VCTKS in section
3.
5. Deleted MSD related in the flowchart.
V
Contents
1 Introduction ......................................................................................................................... 1
1.1 Abbreviation ............................................................................................................. 1
1.2 Document Conventions ............................................................................................ 1
2 Kernel Comparison of CLSS and EMV ........................................................................... 3
3 Example of Application Programming for payWave .......................................................... 4
4 Parameters and Data Management ................................................................................... 9
4.1 Clss_CoreInit_Wave ................................................................................................. 9
4.2 Clss_ReadVerInfo_Wave ......................................................................................... 9
4.3 Clss_GetTLVData_Wave ....................................................................................... 10
4.4 Clss_SetTLVData_Wave ........................................................................................ 10
4.5 Clss_GetReaderParam_Wave ................................................................................. 11
4.6 Clss_SetReaderParam_Wave ................................................................................. 11
4.7 Clss_SetRdSchemeInfo_Wave ............................................................................... 12
4.8 Clss_GetSchemeInfo_Wave ................................................................................... 12
4.9 Clss_SetVisaAidParam_Wave ............................................................................... 13
4.10 Clss_SetDRLParam_Wave ................................................................................. 13
4.11 Clss_SetDRLParam_II_Wave ............................................................................. 14
4.12 Clss_SetExtendFunc_Wave ................................................................................ 14
4.13 Clss_GetExtendFunc_Wave................................................................................ 15
5 Certification Authority (CA) Public Key Management .................................................... 17
5.1 Clss_AddCAPK_Wave........................................................................................... 17
5.2 Clss_DelCAPK_Wave ............................................................................................ 18
5.3 Clss_GetCAPK_Wave ............................................................................................ 18
5.4 Clss_DelAllCAPK_Wave....................................................................................... 18
6 Terminal Issuer Public Key Certification Revocation List Management .......................... 20
6.1 Clss_AddRevocList_Wave ..................................................................................... 20
6.2 Clss_DelRevocList_Wave ...................................................................................... 21
6.3 Clss_DelAllRevocList_Wave ................................................................................. 21
VI
7 Transaction Processing Functions ..................................................................................... 22
7.1 Clss_SetFinalSelectData_Wave ............................................................................. 22
7.2 Clss_SetTransData_Wave ...................................................................................... 23
7.3 Clss_Proctrans_Wave ............................................................................................. 24
7.4 Clss_GetMSDType_Wave ..................................................................................... 25
7.5 Clss_CardAuth_Wave ............................................................................................ 26
7.6 Clss_GetCvmType_Wave ...................................................................................... 26
7.7 Clss_nGetTrack1MapData_Wave .......................................................................... 27
7.8 Clss_nGetTrack2MapData_Wave .......................................................................... 27
7.9 Clss_ProcRestric_Wave ......................................................................................... 28
7.10 Clss_IssuerAuth_Wave ....................................................................................... 28
7.11 Clss_IssScriptProc_Wave ................................................................................... 29
7.12 Clss_SetDDAOmitFlag_Wave............................................................................ 29
8 Debug Function ................................................................................................................. 31
8.1 Clss_GetDebugInfo_Wave ..................................................................................... 31
VII
Table List
Table 1 Abbreviation .......................................................................................................... 1
VIII
PAX CLSS L2 API Programming Guide
1 Introduction
1.1 Abbreviation
【List out the definitions of the nomenclatures and abbreviations used in this document.】
Table 1 Abbreviation
Abbreviation Description
CLSS Contactless
1.2 Document Conventions
【List out all document conventions and the corresponding definitions.】
【Used for labelling common notes.】
【Used for reminding the audience some place may have to pay
attention to, which may lead to exceptions or errors.】
www.paxtechnology.com. 1
【Used for warning the audience some place must be very

careful, which may lead to very serious errors or damages.】
2 Kernel Comparison of
CLSS and EMV
1. In the CLSS kernel, the parameters including AID list, CA Public Keys, terminal type
and so on. These parameters imported from the application program will not be saved
after power off.
2. Notice that the AID operator functions (Add, Delete) in the CLSS kernel are different
from which in the EMV kernel.
3. The CLSS kernel can set 1 CA Public Key at a time, and this key cannot be saved after
power off. Therefore, the application program must save the CA Public Keys itself, and
set one or a group of corresponding Public Keys according to the CA Public Key index or
RID for each transaction.
3 Example of Application
Programming for payWave
Kernel Initialization
Clss_CoreInit_Wave
Activate TapToPhone mode

Is T2P transaction? Y
Clss_SetExtendFunc_Wave
Set Parameters
EntryPoint processing
(Transaction Preprocessing,
Application Selection)
Y
KernelType ==payWave? N Other transaction
Set Final Select data

Clss_SetFinalSelectData_Wave
DRL is supported and Matching Set DRL parameter

Y
Program ID found? Clss_SetDRLParam_Wave
N
Set parameters corresponding to AID

Clss_SetVisaAidParam_Wave
Set related parameters for

payWave transaction
Clss_SetTransData_Wave
Main flow of payWave transaction

processing Error CLSS_RESELECT_APP?
Clss_Proctrans_Wave
N
Prompt cardholder to remove
card Error processing
Transaction
ACType is AAC? Y
completion
N
ACType is TC? Y Exception file check
Clss_ProcRestric_Wave
Set data of Certificate Revocation List

Clss_AddRevocList_Wave
Set data of CAPK

Clss_AddCAPK_Wave
Offline data authentication

Clss_CardAuth_Wave
Get CVM type and perform

CVM processing
Clss_GetCvmType_Wave
CVM is online PIN

Or ACType is ARQC？
Online processing
Issuer Authentication Data or

Issuer script was received
Prompt cardholder to
represent card
N Application shall send a

select command to select the
card AID of current
transaction
N
Clss_IssuerAuth_Wave
Clss_IssScriptProc_Wave
Prompt cardholder to
remove card
Transaction
completion
Fig.1 Flow chart of application programming for PayWave
Instructions for VCTKS:

Based on the above process, VCTKS has the following differences:
1. When calling Clss_AddAidList_Entry, the bit 4 of the third parameter "ucSelFlg" shall be
set to 1.
2. Before calling Clss_AppSlt_Entry,
 The value of tags (9F02,8B, 9F1A, 5F2A, 9F15) shall be set to the kernel by
Clss_SetTLVDataList_Entry.
 Clss_SetExtendFunction_Entry shall be set to enable the SPI(SEND POI
INFORMATION).
3. After calling Clss_FinalSelect_Entry, it is necessary to call Clss_SetTLVData_Wave to
set the value of 8B to the kernel.
4. Before calling Clss_SetTransData_Wave, TTQ is required to set by
Clss_SetTLVData_Wave. And the value of B1b1 shall be 1 and B1b5 shall be 0.
5.VCTKS not support Pre-Processing and DRL. Below functions are not required to call.
Clss_SetPreProcInfo_Entry
Clss_SetPreProcInfoEx_Entry
Clss_DelPreProcInfo_Entry
Clss_DelAllPreProcInfo
Clss_PreTransProc_Entry
Clss_GetPreProcInterFlg_Entry
Clss_GetPreProcInterFlgByAid_Entry
Clss_GetPreProcInfo_Entry
Clss_GetPreProcInfoEx_Entry
Clss_SetDRLParam_II_Wave
6. For transit transaction, the application may be required to send some results of the
transaction to the acquirer, which includes,
Online Required by Reader Indicator,
Decline Required by Reader Indicator,
Application expired.
Please call Clss_GetExtendFunc_Wave to obtain the results if required.
7.RF Field Power Down
As a part of normal terminal processing, the contactless terminal may be required to

power down its RF field. For example, the RF field is powered down when the terminal is idle,
after a pre-defined timeout period, upon receipt of a GPO response SW = '6986', and at the
completion of reading the contactless card. However, this power down of the RF field may
not be suitable in some transit acceptance environments where high consumer throughput is
required.
To support terminals in these environments, transit terminals may choose not to power
down the RF field when required in [VCPS] and [EMV CL]. Transit terminals that do not
power down the RF field in these cases must ensure that the card is removed by the
cardholder before attempting to proceed with another transaction. Doing otherwise may result
in the transit terminal "looping" and continuously attempting to transact with the same card.
4 Parameters and Data

Management
4.1 Clss_CoreInit_Wave
Prototype int Clss_CoreInit_Wave (void);

Function payWave kernel initialization.
Parameters None
Return EMV_OK Initialization completed.
1. It initializes all data elements and global variables.
2. This function shall be called each time before a transaction starts.
Instruction 3. This function MUST be called again at the end of each
transaction to clear all transaction related data.
4.2 Clss_ReadVerInfo_Wave
Prototype int Clss_ReadVerInfo_Wave(char *paucVer);

Function Query the version number of the payWave kernel.
Version number.
Parameters paucVer(output) For example v305 2015.06.23 (date at the
rear).
Return EMV_OK Successful.

CLSS_PARAM_ERR Parameter error.

Instruction None
4.3 Clss_GetTLVData_Wave
int Clss_GetTLVData_Wave (unsigned short Tag, unsigned char

Prototype *DataOut, int *nDataLen);
Function Get the data element specified by the tag.
Tag(input) Tag of EMV standard or extended data.
The value of the data element specified by

Parameters DataOut(output)
the tag.
nDataLen(output) The length of the data element.
EMV_OK Successful.
The order of the API called is error. The
CLSS_API_ORDER_
Return detailed error code can be obtained with
ERR
EMV_NO_DATA Cannot find the tag or no data.
1. The CLSS library can store all the EMV standard data elements;
it also can store up to 64 data elements which are defined by the
issuer. After reading the application data, the application
developer can call this function to get the data element specified
Instruction by the tag.
2. This function should be called after
Clss_SetFinalSelectData_Wave. Or the data retrieved may not
be the final data used in the transaction.
4.4 Clss_SetTLVData_Wave
int Clss_SetTLVData_Wave (unsigned short usTag, unsigned

Prototype char * pucDtIn, int nDtLen);
Function Set the data element specified by the tag.
EMV standard or extended data element
usTag(input)
Tag.
Parameters
The value of the data element specified by
pucDtIn(input)
the tag.
nDtLen(input) The length of the data element.
EMV_OK Successful.
CLSS_API_ORDER_
ERR
EMV_DATA_ERR nDtLen error.
1. The value of the standard or priority data element can be modified
or set by the application program. In this way, the application can
satisfy the requirement in some special conditions. Normally, it’s
Instruction not necessary to call this function.
Clss_SetFinalSelectData_Wave, or the data set will be
initialized.
4.5 Clss_GetReaderParam_Wave
int Clss_GetReaderParam_Wave (Clss_ReaderParam

Prototype *ptParam);
Function Get related parameters of the reader.
Data pointer to the reader’s relative
parameters. Please refer to the document
Parameters ptParam(output) “PAX CLSS L2 API Programming Guide
For Common Definition” for the structure
definition of Clss_ReaderParam.
EMV_OK Successful.
Return
CLSS_PARAM_ERR Parameter error.(Null pointer)
Instruction None
4.6 Clss_SetReaderParam_Wave
Prototype int Clss_SetReaderParam_Wave (Clss_ReaderParam *ptParam);

Function Set related parameters of the card reader.
Data pointer reader’s relative parameters.
ptParam(input) Please refer to the document “PAX CLSS

Parameters
L2 API Programming Guide For Common
Definition” for the structure definition of
Clss_ReaderParam.
EMV_OK Successful.
CLSS_API_ORDER_
ERR
This function must be called between Clss_CoreInit_Wave and
Clss_SetFinalSelectData_Wave to set the reader’s relative
Instruction parameters.
The TLV data of the parameters related to Clss_ReaderParam can
only be obtained after Clss_SetFinalSelectData_Wave.
4.7 Clss_SetRdSchemeInfo_Wave
void Clss_SetRdSchemeInfo_Wave (unsigned char ucNum,

Prototype Clss_SchemeID_Info *pInfo);
Function Set one or several application types supported by the reader.
The number of application types supported
ucNum(input)
by the reader.
Parameters
Data pointer to the application types
pInfo(input)
supported by the reader.
Return None
Instruction This function is not used, it is reserved for compatibility only.
4.8 Clss_GetSchemeInfo_Wave
void Clss_GetSchemeInfo_Wave (unsigned char *pNum,

Prototype Clss_SchemeID_Info *pInfo);
Function Get application types supported by the reader.
The number of application types supported
ucNum(output)
by the reader.
Parameters
Data pointer to the application types
pInfo(output)
supported by the reader.
Return None
Instruction This function is not used, it is reserved for compatibility only.
4.9 Clss_SetVisaAidParam_Wave
int Clss_SetVisaAidParam_Wave (Clss_VisaAidParam

Prototype *ptParam);
Set the payWave application related parameters corresponding to the
Function AID.
Data pointer to payWave application related
parameters; Please refer to the document
Parameters ptParam(input) “PAX CLSS L2 API Programming Guide
For Common Definition” for the structure
definition.
EMV_OK Successful.
Return
Instruction This function shall be called before Clss_Proctrans_Wave.
4.10 Clss_SetDRLParam_Wave
Prototype int Clss_SetDRLParam_Wave(Clss_ProgramID tDRLParam);

Function Set DRL parameters.
DRL parameters;
tDRLParam (input) Please refer to the document “PAX CLSS

Parameters
Definition” for the structure definition.

1. If DRL is supported, the application shall add the DRL parameter
indicated by the program ID (9F5A) into the kernel with this
function, the kernel will execute DRL processing if the DRL
Instruction parameter is present.
2. Please note that this function must be called before
Clss_Proctrans_Wave.
3. If DRL is not supported. This function shall not be called.
4.11 Clss_SetDRLParam_II_Wave
int Clss_SetDRLParam_II_Wave (Clss_ProgramID_II

Prototype tDRLParam);
Function Set DRL parameters.
DRL parameters;
Parameters tDRLParam (input) Please refer to chapter 9 for the definition of
the Clss_ProgramID_II structure.

1. If DRL is supported, the application shall add the DRL parameter
indicated by the program ID (9F5A) into the kernel with this
function, the kernel will execute DRL processing if the DRL
parameter is present.
2. Please note that this function must be called before
Clss_Proctrans_Wave.
Instruction 3. If DRL is not supported. This function shall not be called.
4. This API is similar to Clss_SetDRLParam_Wave in
functionality but with the difference of setting the limit value
formatted as "n 12". Clss_SetDRLParam_II_Wave supports
limits greater than 0xFFFFFFFF
5. This API can totally take the place of
Clss_SetDRLParam_Wave.
4.12 Clss_SetExtendFunc_Wave
int Clss_SetExtendFunc_Wave(int nFlag, unsigned char

Prototype *paucDataIn, int nDataInLen);
Function Extend function to set additional information.
0x01 - Set the behavior of AUC processing
for cash and cashback transactions.
nFlag (input) 0x02 - Reserved.

0x03 - Set Tap to Phone is enabled or not.
Parameters Other: RFU
(1). If nFlag is 1, 2 Bytes shall be set.

Byte 1: AUC is checked for Cash
paucDataIn(input) transaction. 0x00 – no; 0x01 – Yes
(default).
Byte 2: AUC is checked for Cashback
transaction. 0x00 - no; 0x01 - Yes

(default).
(2). If nFlag is 3, 1 byte shall be set.
Byte 1:
0x00 - POS (default);
0x01 - Tap To Phone.
The length of paucDataIn input.

(1). If nFlag is 1: The length shall be 2.
nDataInLen(input) (2). If nFlag is 3: The length shall be 1.
(3). Other values will not be allowed.
EMV_OK Successful.
Return
If necessary, this function shall be called between Clss_CoreInit_Wave
Instruction
and Clss_Proctrans_Wave .
4.13 Clss_GetExtendFunc_Wave
int Clss_GetExtendFunc_Wave(int nFlag, unsigned char

Prototype *paucDataOut, int nExDataOutLen);
Function Extend function to get additional information..
0x01 -Reserved.
0x02 - Obtained the indicator for decline,
nFlag (input) online and application expired.( VCTKS
only)
Other RFU
First byte indicates the length and the

Parameters following is the data.
If nFlag is 2:
paucDataOut(ouput) paucDataOut[1] - decline required by reader

indicator.
paucDataOut[2] - online required by reader
indicator.
paucDataOut[3] - application expired
indicator.
nExDataOutLen(input
Expected length of the output data.
)
EMV_OK Successful.
paucExDataOut or nExDataOutLen is not
Return EMV_OVERFLOW
long enough.
For transit transaction, the application may be required to send some
results of the transaction to the acquirer, which includes,
Online Required by Reader Indicator,
Instruction Decline Required by Reader Indicator,
Application expired.
Please call this function to obtain the results if required.
5 Certification Authority (CA)

Public Key Management
5.1 Clss_AddCAPK_Wave
Prototype int Clss_AddCAPK_Wave (EMV_CAPK *capk );

Function Add a new CA public key.
The pointer to the public key.
Please refer to the document “PAX CLSS L2
Parameters capk(input) API Programming Guide For Common
Definition” for the structure definition of the
EMV_CAPK.
EMV_OK Successful.
EMV_SUM_ERR Check sum error.
Return Memory overflows
EMV_OVERFLOW (The maximum number of CAPK supported
is CLSS_MAX_KEY_NUM).
1. It is suggested to delete all CA Public Keys in the kernel at the
beginning of each transaction, and set the CA Public Key
according to the current application’s requirements. In this way,
Instruction the application only needs to set one CA Public Key each time.
2. If the public key is already exists, the new key will replace the
old one.
3. The CA public key is provided by acquire. Sometimes, the key is

not assigned with the structure of EMV_CAPK. In this case, the
application must convert the public key before adding it.
5.2 Clss_DelCAPK_Wave
int Clss_DelCAPK_Wave (unsigned char KeyID, unsigned char

Prototype *RID);
Function Delete a CA public key.
KeyID(input) The index of the key.
Parameters
RID(input) Registered Application Provider Identifier.
EMV_OK Successful.
Return
EMV_NOT_FOUND The specified key is not found.
Instruction None
5.3 Clss_GetCAPK_Wave
Prototype int Clss_GetCAPK_Wave (int Index, EMV_CAPK *capk );

Function Get a CA public key.
The key storage index, range (0 -
Index(input)
MAX_KEY_NUM).
Parameters
capk(output) The pointer of the key.
EMV_OK Successful.
Return
EMV_NOT_FOUND The specified key is not found.
Instruction None
5.4 Clss_DelAllCAPK_Wave
Prototype void Clss_DelAllCAPK_Wave (void);

Function Delete all CA public keys.
Parameters None
Return None
Instruction It is suggested to call this function to delete all CA Public Keys in the
kernel at the beginning of each transaction, and set the CA Public

Key according to the current application’s requirements. In this way,
the application only needs to set one CA Public Key each time.
6 Terminal Issuer Public

Key Certification Revocation
List Management
6.1 Clss_AddRevocList_Wave
int Clss_AddRevocList_Wave (EMV_REVOCLIST

Prototype *pRevocList);
Add a revoked issuer public key certificate to the certificate
Function revocation list.
The pointer to the revoked issuer public key
certificate.
pRevocList(input) Please refer to the document “PAX CLSS L2

Parameters
API Programming Guide For Common
EMV_REVOCLIST.
EMV_OK Successful.
EMV_DATA_ERR Input data error (the pointer is null).
Return Memory overflows
EMV_OVERFLOW (The maximum number of revoked issuer
public key certificates supported is
MAX_REVOCLIST_NUM )
If the revoked issuer public key certificate already exists, this
Instruction function directly returns success.
6.2 Clss_DelRevocList_Wave
int Clss_DelRevocList_Wave (unsigned char ucIndex, unsigned

Prototype char *pucRID);
Function Delete a revoked issuer public key certificate.
The corresponding CA public key index of
ucIndex(input)
the revoked issuer public key certificate.
Parameters
The corresponding RID of the revoked
pucRID(input)
issuer public key certificate (5 bytes).
EMV_OK Successful.
Return EMV_DATA_ERR Input data error (the pointer is null).
EMV_NOT_FOUND The specified certificate is not found.
Instruction None
6.3 Clss_DelAllRevocList_Wave
Prototype void Clss_DelAllRevocList_Wave (void);

Function Delete all revoked issuer public key certificates.
Parameters None
Return None
Instruction None
7 Transaction Processing
Functions
7.1 Clss_SetFinalSelectData_Wave
int Clss_SetFinalSelectData_Wave(unsigned char *paucDtIn, int

Prototype nDtLen);
Initialize all data elements of the kernel and Set the data returned
Function from the card during the final selection.
Pointer to the data returned from the card
paucDtIn(input)
during the final selection.
Parameters
nDtLen(input) Length of data.
EMV_OK Successful.
Return The order of the API called is error. The

CLSS_API_ORDER_
detailed error code can be obtained with
ERR
EMV_DATA_ERR Data format error.
This function should be called after Clss_CoreInit_Wave.
Instruction After calling this function, if DRL is supported, the application shall
check if there is a matching DRL parameter with Program ID 9F5A ,
if yes, please choose oneof the two methods below for DRL
processing.
(Both full matches and partial match are allowed for the program ID
comparison, for example: the program ID saved in the terminal is 01
02, it can be matched by the value 01 02 or 01 02 03 of the program
ID (9F5A), while it cannot be matched by the value 01 of the
program ID (9F5A))
1. Kernel execute DRL processing:(new method) Set the DRL
parameter into the kernel with Clss_SetDRLParam_Wave. The
kernel will execute the DRL processing.
2. Applicaiton execute DRL processing:(old method)
 a. Delete all pre-processing parameters with
Clss_DelAllPreProcInfo.
 b. Add the DRL parameter to the Entry kernel with
Clss_SetPreProcInfo_Entry.
 c. Call Clss_PreTransProc_Entry to redo the
pre-processing. The return code of
Clss_PreTransProc_Entry shall be ignored.
Please note that It is necessary to set the pre-processing
parameters of all AIDs into the entry kernel again before
calling Clss_PreTransProc_Entry for the first time for the
next transaction.
7.2 Clss_SetTransData_Wave
int Clss_SetTransData_Wave (Clss_TransParam

Prototype *ptTransParam, Clss_PreProcInterInfo *ptInfo);
Set the transaction related parameters and the result of the
Function Pre-processing.
Pointer to the related parameters of the
transaction.
ptTransParam(input) Please refer to the document “PAX CLSS

parameters.
Parameters
Pointer to the result of Pre-processing.
Please refer to the document “PAX CLSS
ptInfo(input) L2 API Programming Guide For Common
parameters.
CLSS_PARAM_ERR Parameter error(the pointer is null).

CLSS_TERMINATE This transaction type is not supported.
1. This function must be called to set related transaction parameters
before Clss_Proctrans_Wave.
Instruction 2. According to the requirement of VCPS, online ODA should be
supported ONLY for Transit scenarios. So Byte1 bit1 of TTQ
shall be set to 0 for non-transit scenarios.
7.3 Clss_Proctrans_Wave
int Clss_Proctrans_Wave(unsigned char *pucTransPath,

Prototype unsigned char *pucACType);
This function includes the processing of GPO and record reading of
Function qVSDC.
Type of transaction path (it is effective
pucTransPath(output) only when EMV_OK is returned)
CLSS_VISA_QVSDC: qVSDC
AC type
Parameters (It is effective only when EMV_OK is
returned):
pucACType(output)
AC_ AAC: Decline
AC_ TC: Offline Approve
AC_ ARQC: Online Request
EMV_OK Successful.
Contactless transaction limit is exceeded
or GPO response code is 6985.
CLSS_RESELECT_APP Delete the current application from the
candidate list, and then execute final
Return selection again to select the next
application.
Terminate the CLSS transaction and use
CLSS_USE_CONTACT the contact interface to process the
transaction instead.
CLSS_REFER_CONSU The reader shall indicate to the cardholder

MER_DEVICE to refer to their payment device for
further instructions and immediately
power down the contactless interface.

After a duration of between 1000ms and
1500ms, the reader shall power up the
contactless interface and return to
Discovery Processing.
CLSS_API_ORDER_ER
detailed error code can be obtained with
R
Clss_GetDebugInfo_Wave.
The reader shall terminate contactless
CLSS_INSERTED_ICC
transaction and perform contact
ARD
transaction
The reader shall terminate contactless
CLSS_SWIPED_MAGC
transaction and perform magstripe
ARD
transaction
L2 API Programming Guide For
Other
Common Definition” for the macro
definition of the return codes.
Clss_SetFinalSelectData_Wave.
2. When this function is successfully performed, if the AC type is
TC, the application need to judge whether to do offline
authentication, processing restriction checking or exception file
Instruction checking according to the transaction path. While if the AC type
is AAC or ARQC, offline rejection or online authorization shall
be performed immediately.
3. If the AC type is TC, the application shall check the exception
files immediately. While if the PAN is in the exception file list, it
need to be rejected offline.
7.4 Clss_GetMSDType_Wave
unsigned char Clss_GetMSDType_Wave(unsigned char

Prototype *ucMSDType);
Function Get MSD type.
MSD type:
CLSS_VISA_MSD_CVN17：CVN 17
Parameters ucMSDType (output)
CLSS_VISA_MSD_LEGACY: CVN
Legacy
Return EMV_NOT_FOUND This function is not used.

Instruction This function is not used, since MSD is no longer supported, it is
reserved for compatibility only.
7.5 Clss_CardAuth_Wave
int Clss_CardAuth_Wave(unsigned char *pucACType, unsigned

Prototype char *pucDDAFailFlg);
Function Perform offline data authentication and return AC type.
AC type:
pucACType(output) (value: AC_ AAC, AC_ TC, or AC_
ARQC)
Failure flag of DDA authentication:

1: fail
Parameters
0: success
pucDDAFailFlg(output) (If VOQOS is supported:
0: fDDA success 1: fDDA fail
2: SDA success 3: SDA fail
4: ODA is not performed)
EMV_OK Successful.
CLSS_USE_CONTACT Use other transaction interface.
EMV_DATA_ERR Data Error.
Return
Other
definition of the return code.
1. After this function is successfully performed, the application shall
continue with the subsequence process according to the AC type
Instruction returned in pucACType. (Such as offline approval, offline
decline, or online authorization).
2. If pucACType is AC_ AAC, decline the transaction immediately.
7.6 Clss_GetCvmType_Wave
Prototype int Clss_GetCvmType_Wave(unsigned char *pucType);

Function Get CVM Type
CVM Type
RD_CVM_NO: No CVM.
RD_CVM_ONLINE_PIN: Online PIN
RD_CVM_SIG: Signature
RD_CVM_CONSUMER_DEVICE: See
Parameters pucType(output)
your phone (Look at the mobile device to
obtain further instructions).
Please refer to document “PAX CLSS L2
API Programming Guide For Common
Definition” for the macro definition of
the CVM method.
EMV_OK Successful.
CLSS_DECLINE Decline the transaction.
Return Please refer to the document “PAX CLSS
Other
Instruction For online PIN, the application should perform online processing.
7.7 Clss_nGetTrack1MapData_Wave
int Clss_nGetTrack1MapData_Wave(unsigned char

Prototype *pTrackData, int *pLen);
Function Get mapped TRACK1 data.
pTrackData(output) Mapped TRACK1 data.
Parameters
pLen(output) Length of the mapped TRACK1 data.
Return EMV_NOT_FOUND This function is not used.

This function is not used, since MSD is no longer supported, it is
Instruction reserved for compatibility only.
7.8 Clss_nGetTrack2MapData_Wave
int Clss_nGetTrack2MapData_Wave(unsigned char

Prototype *pTrackData, int *pLen);
Function Get mapped TRACK2 data

pTrackData(output) Mapped TRACK2 data.
Parameters
pLen(output) Length of mapped TRACK2 data.
Return EMV_NOT_ FOUND This function is not used.

This function is not used, since MSD is no longer supported, it is
Instruction reserved for compatibility only.
7.9 Clss_ProcRestric_Wave
Prototype int Clss_ProcRestric_Wave (void)；

This function is used to perform restrictions, including Application
Function
Expired Check and Application Usage Control.
Parameters None
EMV_OK Successful.
Return L2 API Programming Guide For
Other
1. The exception files checking is implemented by the application.
When the card returns TC, the application should first check the
exception file. If the PAN is in the exception file, the application
Instruction should decline the transaction immediately, otherwise, call this
function.
2. This function shall be called after Clss_Proctrans_Wave
7.10 Clss_IssuerAuth_Wave
int Clss_IssuerAuth_Wave (unsigned char *pIAuthData, int

Prototype nIAuthDataLen);
Function Issuer authentication.
pIAuthData (input) Issuer Authentication data
Parameters
nIAuthDataLen (input) Length of Issuer Authentication data
EMV_OK Successful.
Return Please refer to the document “PAX CLSS

Other L2 API Programming Guide For

1. If issuer authentication data is received, please call this function
to perform Issuer authentication.
2. The application should send the SELECT command first to select
Instruction the Final AID(tag “4F”) of the current transaction by using
DEVICE_IccCommand. Please refer to the transaction flow on
section 3.1.
7.11 Clss_IssScriptProc_Wave
int Clss_IssScriptProc_Wave(unsigned char *pucScript, int

Prototype nScriptLen);
Function Issuer script process.
pucScript (input) Script data.
Parameters
nScriptLen (input) Script data length
EMV_OK Successful.
Return L2 API Programming Guide For
Other
1. If an issuer script is received, please call this function to process
the script.
2. The application should send the SELECT command first to select
the Final AID(tag “4F”) of the current transaction by using
Instruction DEVICE_IccCommand. Please refer to the transaction flow in
section 3.1. If it has been done before the issuer authentication
processing, there is no need to send the SELECT command again.
3. The Issuer Script Result can be obtained by calling
Clss_GetTLVData_Wave to get the value of tag 9F5B.
7.12 Clss_SetDDAOmitFlag_Wave
Prototype void Clss_SetDDAOmitFlag_Wave(unsigned char ucOmitFlag);

This function is used to set flags to indicate whether to omit the hash
Function validation of the ICC certificate during the DDA process.
1: HK old version card processing, that is
Parameters ucOmitFlag (input) omit the hash validation.
0: Normal processing, that is not omit.
Return None.
This function is only for Visa payWave HK old version card

Instruction requirement. Normally this function is should not be used.
8 Debug Function
8.1 Clss_GetDebugInfo_Wave
int Clss_GetDebugInfo_Wave(int nExpAssistInfoLen, unsigned

Prototype char *paucAssistInfo, int *pnErrorCode);
Function Get the debug information.
nExpAssistInfoLen
RFU(0 can be used)
(input)
Parameters paucAssistInfo
RFU (NULL can be used)
(output)
pnErrorCode (output ) The error code.
EMV_OK Successful
Return
EMV_PARAM_ERR The parameters are error.
1. This function is only used to obtain the debug information when
a transaction is failed.
Instruction 2. So far, it only can be used to obtain the error code of offline data
authorization and CLSS_API_ORDER_ERR.
(1) Error code for offline data authentication.
Value Retrieval of Issuer Public Key Error Suggestion
1 Authority Public Key Index does not exist. Check the card data
2 Issuer Public Key Certificate does not exist. Check the card data
3 Issuer Public key Exponent does not exist. Check the card data
4 The CAPK indicated by Authority Public Key Check if the CAPK indicated
Index does not exist in the kernel. by the Authority Public Key
Index has been added in the
kernel by
Clss_AddCAPK_Wave
Issuer Public Key Certificate has a length Check CAPK data and the card
5
different from the length of the Certification data
Authority Public Key Modulus
Recovered Data Header is not equal to '6A', Check the card data
6
Certificate Format is not equal to '02' Check the card data

7
Recovered Data Trailer is not equal to 'BC' Check the card data
8
9 The Length of the Issuer Public Key recovered is Check the card data
not equal to the actual length
10 The hash result calculated is not equal to the hash Check CAPK data and the card
result recovered. data
Issuer Identifier does not match the left 3-8 PAN Check the card data
11
digits
The issuer public key certificate has expired Check the card data
12
13 Hash Algorithm Indicator or Issuer Public Key Check the card data
Algorithm Indicator is not recognized
The CAPK is in the revocation list Check the revocation list

14
Retrieval of ICC Public Key Error
21 ICC Public Key Certificate does not exist. Check the card data
22 ICC Public Key Exponent does not exist. Check the card data
23 ICC Public Key Certificate has a length different Check the card data
from the length of the Issuer Public Key Modulus
obtained in the previous section.
24 Recovered Data Header is not equal to '6A', Check the card data
25 Certificate Format is not equal to '04' Check the card data
26 Recovered Data Trailer is not equal to 'BC' Check the card data
27 The Length of the ICC Public Key recovered is Check the card data
not equal to the actual length
28 Static Data Authentication Tag List exists and Check the card data
contains tags other than '82'
29 The hash result calculated is not equal to the hash Check the card data
result recovered.
30 Recovered PAN is not the same as the Application Check the card data
PAN read from the ICC.
31 The ICC public key certificate has expired Check the card data
32 ICC Public Key Algorithm Indicator is not Check the card data
recognized
SDA Verification Error
41 Signed Static Application Data does not exist. Check the card data
42 Signed Static Application Data has a length Check the card data
different from the length of the Issuer Public Key
Modulus
43 Recovered Data Header is not equal to '6A'. Check the card data
44 Signed Data Format is not equal to '03' Check the card data
The Static Data Authentication Tag List exists and

46 Check the card data
contains tags other than '82'.
47 The hash result calculated is not equal to the hash Check the card data
result recovered. EMV Book 2, 5.4 steps 7.
DDA Verification Error
85 INTERNAL AUTHENTICATE command send or Check the return code of the

receive error callback function used to send
the command.
The TLV format of response data of the

86 Check the response data of the
INTERNAL AUTHENTICATE is error.
command.
The response data of INTERNAL

AUTHENTICATE is not ‘80’ or ‘77’
There is no data in template ‘80’.
The length of ‘80’ is error.

90 The response data is ‘77’, and the TLV format is Check the card data
error
91 The Signed Dynamic Application Data has a Check the card data
length different from the length of the ICC Public
Key Modulus
93 Signed Data Format is not equal to '05' Check the card data
The hash result calculated is not equal to the hash

result recovered. EMV Book 2, 6.5.2 step 7.
96 ICC Dynamic Data Length recovered is greater Check the card data
than 8
fDDA Fail
108 The Length Of Signed Dynamic Application Check the card data
Data(9F4B) Is Not Equal To The Length Of
Card’s Public Key
Signed Data Format is not equal to '05'

112 Hash Value Validation Errors Check the card data
113 The ICC Dynamic Data Length recovered is Check the card data
greater than 8
114 fDDA version is not v01 Check the card data
(2) Error code for API call
Value Error code for API call Suggestion
301 Clss_CoreInit_Wave has not been called. This function must be called after
Clss_CoreInit_Wave.
302 Clss_SetFinalSelectData_Wave has not been This function must be called after
called. Clss_SetFinalSelectData_Wave.

PAX CLSS L2 API Programming Guide For Paywave Library

Uploaded by

PAX CLSS L2 API Programming Guide For Paywave Library

Uploaded by

PAX CLSS L2 API

For Paywave Library

2011-6-10 V1.1.0 1. Delete the API

2012-09-13 V1.1.1 1. Add changes according to VCPS 2.1.

2012-10-12 V1.1.2 1. Modify the flow chart. Add refund

2013-11-25 V1.1.3 1. Add DRL processing instruction in 7.1. yingl

2015-06-23 V1.1.5 1. Add debug function

2016-03-24 V1.1.6 1. Delete the description of return code for

2016-09-23 V1.1.7 1. Add API

2017-04-18 V1.1.8 1. Delete callback functions:

2017-11-29 V1.1.9 Kernel version:v351

2019-04-18 V1.2.0 Kernel version:v353

2020-12-09 V1.2.1 Kernel version v354

2021-09-09 V1.2.2 Kernel version v355

2022-07-11 V1.2.3 Kernel version v356

2024.03.01 V1.2.4 Kernel version v357

2024.03.08 V1.2.5 Kernel version v358

Table 1 Abbreviation .......................................................................................................... 1

1.2 Document Conventions

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

【Used for labelling common notes.】

【Used for warning the audience some place must be very

Activate TapToPhone mode

Set Final Select data

DRL is supported and Matching Set DRL parameter

Set parameters corresponding to AID

Set related parameters for

Main flow of payWave transaction

ACType is TC? Y Exception file check

Set data of Certificate Revocation List

Set data of CAPK

Offline data authentication

Get CVM type and perform

CVM is online PIN

Issuer Authentication Data or

N Application shall send a

Fig.1 Flow chart of application programming for PayWave

Instructions for VCTKS:

As a part of normal terminal processing, the contactless terminal may be required to

4 Parameters and Data

Prototype int Clss_CoreInit_Wave (void);

Prototype int Clss_ReadVerInfo_Wave(char *paucVer);

Return EMV_OK Successful.

CLSS_PARAM_ERR Parameter error.

int Clss_GetTLVData_Wave (unsigned short Tag, unsigned char

The value of the data element specified by

nDataLen(output) The length of the data element.

int Clss_SetTLVData_Wave (unsigned short usTag, unsigned

nDtLen(input) The length of the data element.

int Clss_GetReaderParam_Wave (Clss_ReaderParam

Prototype int Clss_SetReaderParam_Wave (Clss_ReaderParam *ptParam);

ptParam(input) Please refer to the document “PAX CLSS

void Clss_SetRdSchemeInfo_Wave (unsigned char ucNum,

void Clss_GetSchemeInfo_Wave (unsigned char *pNum,

Instruction This function is not used, it is reserved for compatibility only.

int Clss_SetVisaAidParam_Wave (Clss_VisaAidParam

Prototype int Clss_SetDRLParam_Wave(Clss_ProgramID tDRLParam);

tDRLParam (input) Please refer to the document “PAX CLSS

Return EMV_OK Successful.

int Clss_SetDRLParam_II_Wave (Clss_ProgramID_II

Return EMV_OK Successful.

int Clss_SetExtendFunc_Wave(int nFlag, unsigned char

nFlag (input) 0x02 - Reserved.

(1). If nFlag is 1, 2 Bytes shall be set.

transaction. 0x00 - no; 0x01 - Yes

The length of paucDataIn input.

int Clss_GetExtendFunc_Wave(int nFlag, unsigned char

First byte indicates the length and the

paucDataOut(ouput) paucDataOut[1] - decline required by reader

5 Certification Authority (CA)

Prototype int Clss_AddCAPK_Wave (EMV_CAPK *capk );

3. The CA public key is provided by acquire. Sometimes, the key is

int Clss_DelCAPK_Wave (unsigned char KeyID, unsigned char

Prototype int Clss_GetCAPK_Wave (int Index, EMV_CAPK *capk );

Prototype void Clss_DelAllCAPK_Wave (void);

kernel at the beginning of each transaction, and set the CA Public