PAX EMV Kernel API Programming Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 74
| Download | |
| Open PDF In Browser | View PDF |
PAX EMV Kernel API
Programming Guide
V 6.0.2
PAX Computer Technology（Shenzhen）Co., Ltd.
Copyright © 2013-2020 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.
I
Revision History
Date
2011-07-06
2011-07-25
2011-12-02
2012-02-14
2012-06-14
2012-06-08
2012-06-15
2012-08-30
Version
Note
1. Resolve a problem that Scripts are
processed error when there are data 71 or
72 contained in script.
V4.1.2
2. Add processing of NULL point for all
functions with point parameters.
3. The version is updated to v412.
Add support for Contactless PBOC,
including:
1. Add CLSS function.
2. Add macro definitions CLSS_SLOT and
CONTACT_SLOT.
V4.1.2_T1 3. Add CLSS transaction parameter
structure Clss_TransParam.
4. Add
call-back
function
cEMVPiccIsoCommand.
5. Add API interface EMVSwitchClss.
6. The version is updated to v412_T1.
1. Add API EMVGetMCKParam.
2. Add API EMVInitTLVData for Clss
V4.1.3
PBOC.
3. The version is updated to v413
V4.1.3_T1 Change the internal value setting for Terminal
Capability and Transaction.
V4.1.4
Modify the range of random number.
Based on v414,
1. Update the kernel according to the latest
EMV 4.3a Specification.
V5.0.0
2. Update the generation algorithm of UN
3. Add API EMVSetAmount to allow large
amount setting (larger than 0xFFFFFFFF).
V5.0.0_T1 1. Revise the large amount setting issues.
1. Update the structure definition for
ELEMENT_ATTR. Please take attention
to the parameter setting of function
EMVAddIccTag().
2. Add support for the PAX Prolin software
platform, including:
V5.0.1
Add call-back functions:
cEMVIccIsoCommand.
cEMVPedVerifyPlainPin.
cEMVPedVerifyCipherPin.
The following functions are not provided:
EMVSetDebug
II
Author
3.
4.
1.
2013-5-7
V5.0.3
2.
3.
1.
2.
2013-06-21
V5.0.3_T1
2013-06-27
V5.0.3_T2
1.
1.
2013-07-18
V5.0.4
2.
3.
EMVProcTrans
cEMVOnlineProc
EMVCoreVersion
EMVGetICCStatus
EMVSetPCIModeParam
EMVClearTransLog
AID list, CA public key, EMV parameters
are no longer stored by the kernel. The
application must store all these
parameters.
Please note the significant change for the
usage
of
the
function
cEMVUnknowTLVData.
When the platform is prolin, it is
necessary to add the head file
“emvlib_prolin.h”.
Add SM and Loading log for PBOC 3.0
requirement.
These parts add APIs below:
EMVReadSingleLoadLog
EMVGetSingleLoadLogItem
EMVReadAllLoadLogs
cEMVSM2Verify.
cEMVSM3
EMVSetScriptProcMethod function is
added to distinguish the Union pay special
script process from EMV. This is for
requirement of Union Pay network
authentication.
Expand the number of terminal AIDs
supported.
Add return value definition
EMV_FILE_ERR
Increase the operation if the old terminal
application file exists then converted it to
the new format. Fix the bug of V503; V503
due to the format of kernel’s terminal
supported application file has been
updated, it will lead to if not rebuild the file
system, the terminal supported application
file format error occurs and cannot be
loaded correctly.
Modify the description of EMVStartTrans
and EMVCompleteTrans
Modify
the
description
of
EMVCompleteTrans.
Add the description of the macro-definition
of AC type.
Modify
the
description
of
FloorLimitCheck,
RandTransSel
and
III
1.
2.
2013-08-16
V5.0.4_T1
3.
1.
2013-09-05
2013-12-13
V5.0.4_T2
V5.0.5
2.
VelocityCheck of EMV_APPLIST.
Add API function EMVGetLogData to get
log data.
Add
API
function
EMVGetVerifyICCStatus to get the
response status word SWA and SWB of
PIN Verify command.
Delete the process of Terminal Action
Analysis whether the transaction should be
rejected immediately in EMVCardAuth.
Add API EMVDelAllApp to remove all
applications from terminal application list.
Change the process of EMVDelApp to
make sure that the order of the terminal
application list is the same as the old
version before v503 of EMV kernel.
1. An online-only terminal need not support
SDA or DDA or CDA. Individual payment
systems will define rules for this case, the
kernel will execute offline data authentication
according to Terminal Capabilities.
1. Add API EMVGetDebugInfo to get debug
information for offline data authentication.
2. Modify the descriptions of
EMV_REVOCLIST and EMVSetAmount.
3. Modify return codes or parameter of
callback functions for appendix A.
2014-06-26
V6.0.0
Modify the value for REFER_APPROVE、
REFER_DENIAL、ONLINE_APPROVE、
ONLINE_FAILED、ONLINE_REFER、
ONLINE_DENIAL and
ONLINE_ABORT.
1. Add EMVGetParamFlag to get the flag for
signature and advice.
2015-03-20
V6.0.2
2. Modify the descriptions for function
EMVSetConfigFlg’s parameter.
The default kernel supports advice.
3. Modify the descriptions for EMV_CAPK.
IV
V
Contents
Revision History ...................................................................................................................... II
Contents .................................................................................................................................. VI
1
Example of Application Programming for EMV .............................................................................. 1
2
Parameter and Data Management ........................................................................................ 1
3
4
2.1
EMVCoreInit ......................................................................................................... 1
2.2
EMVCoreVersion.................................................................................................. 2
2.3
EMVGetParameter ................................................................................................ 2
2.4
EMVSetParameter ................................................................................................. 2
2.5
EMVGetTLVData ................................................................................................. 2
2.6
EMVSetTLVData.................................................................................................. 3
2.7
EMVGetScriptResult ............................................................................................ 3
2.8
EMVSetPCIModeParam ....................................................................................... 4
2.9
EMVReadVerInfo ................................................................................................. 4
2.10
EMVClearTransLog .............................................................................................. 5
2.11
EMVAddIccTag .................................................................................................... 5
2.12
EMVSetScriptProcMethod.................................................................................... 5
2.13
EMVGetMCKParam ............................................................................................. 6
2.14
EMVSetMCKParam.............................................................................................. 6
2.15
EMVSetTmECParam ............................................................................................ 7
2.16
EMVSetConfigFlag............................................................................................... 7
2.17
EMVGetParamFlag ............................................................................................... 8
Certification Authority (CA) Public Key Management ...................................................... 9
3.1
EMVAddCAPK .................................................................................................... 9
3.2
EMVDelCAPK...................................................................................................... 9
3.3
EMVGetCAPK.................................................................................................... 10
3.4
EMVCheckCAPK ............................................................................................... 10
Terminal Application List Management........................................................................................ 11
4.1
EMVAddApp ...................................................................................................... 11
VI
5
6
7
4.2
EMVGetApp ....................................................................................................... 11
4.3
EMVDelApp ....................................................................................................... 12
4.4
EMVGetFinalAppPara ........................................................................................ 12
4.5
EMVModFinalAppPara ...................................................................................... 12
4.6
EMVGetLabelList ............................................................................................... 13
4.7
EMVDelAllApp .................................................................................................. 13
Terminal Revoked Issuer Public Key Certification List Management.............................. 14
5.1
EMVAddRevocList ............................................................................................. 14
5.2
EMVDelRevocList .............................................................................................. 14
5.3
EMVDelAllRecovList ......................................................................................... 15
Transaction Processing ...................................................................................................... 16
6.1
EMVInitTLVData ............................................................................................... 16
6.2
EMVAppSelect ................................................................................................... 16
6.3
EMVReadAppData ............................................................................................. 17
6.4
EMVCardAuth .................................................................................................... 18
6.5
EMVProcTrans.................................................................................................... 18
6.6
EMVAppSelectForLog ....................................................................................... 19
6.7
ReadLogRecord ................................................................................................... 19
6.8
GetLogItem ......................................................................................................... 20
6.9
EMVGetCardECBalance .................................................................................... 21
6.10
EMVStartTrans ................................................................................................... 21
6.11
EMVCompleteTrans ........................................................................................... 22
6.12
EMVSwitchClss .................................................................................................. 23
6.13
EMVSetAmount .................................................................................................. 24
6.14
EMVReadSingleLoadLog ................................................................................... 24
6.15
EMVGetSingleLoadLogItem .............................................................................. 25
6.16
EMVReadAllLoadLogs ...................................................................................... 26
6.17
EMVGetLogData ................................................................................................ 26
Callback Functions ............................................................................................................ 27
7.1
cEMVWaitAppSel .............................................................................................. 27
VII
7.2
cEMVInputAmount ............................................................................................. 28
7.3
cEMVGetHolderPwd .......................................................................................... 28
7.4
cEMVReferProc .................................................................................................. 30
7.5
cEMVOnlineProc ................................................................................................ 30
7.6
cEMVAdviceProc ............................................................................................... 31
7.7
cEMVVerifyPINOK............................................................................................ 31
7.8
cEMVUnknowTLVData ..................................................................................... 32
7.9
cCertVerify .......................................................................................................... 32
7.10
cEmvSetParam .................................................................................................... 33
7.11
cEMVPiccIsoCommand ...................................................................................... 33
7.12
cEMVIccIsoCommand ........................................................................................ 34
7.13
cEMVPedVerifyPlainPin .................................................................................... 35
7.14
cEMVPedVerifyCipherPin.................................................................................. 36
PED_RET_ERR_NO_PIN_INPUT ......................................................................................... 36
8
9
7.15
cEMVSM2Verify ................................................................................................ 37
7.16
cEMVSM3 .......................................................................................................... 37
Debug Interface ................................................................................................................. 39
8.1
EMVSetDebug .................................................................................................... 39
8.2
EMVGetICCStatus .............................................................................................. 39
8.3
EMVGetVerifyICCStatus ................................................................................... 40
8.4
EMVGetDebugInfo ............................................................................................. 40
Appendix ........................................................................................................................... 45
A Return codes of the kernel and other macro definitions ............................................... 45
B EMV_PARAM ............................................................................................................. 47
C EMV_CAPK................................................................................................................. 49
D EMV_APPLIST ........................................................................................................... 50
E EMV_REVOCLIST...................................................................................................... 52
F ELEMENT_ATTR........................................................................................................ 52
G APPLABEL_LIST ....................................................................................................... 53
H EMV_EXTMPARAM.................................................................................................. 54
VIII
I EMV_MCKPARAM ..................................................................................................... 55
J EMV_TMECPARAM ................................................................................................... 55
K APPLABEL_LIST ....................................................................................................... 56
L Clss_TransParam .......................................................................................................... 56
M RSA_PINKEY ............................................................................................................. 57
N APDU_SEND ............................................................................................................... 58
O APDU_RESP................................................................................................................ 58
IX
PAX EMV Kernel API Programming Guide
1 Example of Application Programming f
or EMV
PAX Computer Technology (Shenzhen) Co., Ltd.
1
PAX EMV Kernel API Programming Guide
Kernel
initialization
EMVCoreInit
Set Terminal Parameters
EMVSetParameter，
Set data of CAPK
EMVAddCAPK，
Add data of Application
EMVAddApp
Prompt cardholder to insert
card
N
Detect card？
N
Time out?
Y
Y
Application Selection,
Create Candidate list,
Cardholder selection,
Final Selection and GPO
EMVAppSelect
Errors
Read Application Data
EMVReadAppData
Errors
C
Delete issuer
certificate public key
recovery list
EMVDelAllRevocList
Add recovery list
EMVAddRevocList
Card data authentication
EMVCardAuth
Add failed
Errors
B
Error
processing
A
Figure1: EMV processing flow
PAX Computer Technology (Shenzhen) Co., Ltd.
2
PAX EMV Kernel API Programming Guide
A
Processing restrictions,
Cardholder verification,
Terminal risk management
And First GAC
EMVStartTrans
Online？
Y
Online processing
External
authentication,
Script processing
and second GAC
EMVCompleteTrans
Errors
B
N
Process transation
according AC Type
（AAC,TC）
Transaction
completion
Figure2: EMV processing flow2（for monitor and prolin platform）
PAX Computer Technology (Shenzhen) Co., Ltd.
3
PAX EMV Kernel API Programming Guide
A
Processing restrictions, Cardholder
verification, Terminal risk management,
Online processing and Script processing
EMVProcTrans
Process transation
according AC Type
（AAC,TC）
Transaction
completion
Figure3: EMV processing flow2（only for monitor platform）
PAX Computer Technology (Shenzhen) Co., Ltd.
4
PAX EMV Kernel API Programming Guide
EntryPoint related
processing
qPBOC related
processing
N
TransPath is
Contactless?
qPBOC other
processing
Y
Kernel
initialization
EMVCoreInit
Set Terminal Parameters
EMVSetParameter，
Set data of CAPK
EMVAddCAPK，
Add data of Application
EMVAddApp
Initialize kernel
data elements
EMVInitTLVData
Switch to Contactless
EMVSwitchClss
C
Figure4: Contactless processing flow
PAX Computer Technology (Shenzhen) Co., Ltd.
5
PAX EMV Kernel API Programming Guide
2 Parameter and Data Management
Functions of parameter and data management of EMV kernel are described in this part.
2.1 EMVCoreInit
Prototype
int EMVCoreInit(void);
Function
EMV kernel initialization.
Parameters
Return
Instruction
None
EMV_OK
Initialization succeeds.
EMV_KEY_EXP There’s expired key in the EMV kernel.
EMV_FILE_ERR File error
1. It initializes all the EMV data elements.
2. This function must be called once each time when the terminal
powers on.
3. If there is expired key, the application can check it through
function EMVCheckCAPK and use the key management
functions to delete the expired key and/or add the new key.
4. If the return value is EMV_FILE_ERR, it means that there is
problem when transfer the terminal supported application file
from old format to new one. In this case terminal may need
rebuild file system, and reset all parameters including CAPK,
Applications and so on into terminal.
PAX Computer Technology (Shenzhen) Co., Ltd.
1
PAX EMV Kernel API Programming Guide
2.2 EMVCoreVersion
Prototype
int EMVCoreVersion(void);
Function
Query the version of EMV kernel.
Parameters
Return
Instruction
None
Version number. For example, 25 means version 2.5.
The function is Not Used for the Prolin software platform.
2.3 EMVGetParameter
Prototype
void EMVGetParameter(EMV_PARAM *Param);
Function
Get terminal parameter.
The pointer pointing to terminal parameter. Refer
Param[output]
Parameters
Return
to appendix for structure EMV_PARAM.
None
Instruction
2.4 EMVSetParameter
Prototype
void EMVSetParameter(EMV_PARAM *Param);
Function
Set terminal parameter.
The pointer pointing to terminal parameter. Refer
Param[input]
Parameters
Return
to appendix for structure EMV_PARAM.
None
Instruction
2.5 EMVGetTLVData
Prototype
Function
Parameters
int EMVGetTLVData(unsigned short Tag, unsigned char
*DataOut, int *DataLen);
Get the value of the data element by specifying the tag.
Tag of EMV standard or extended data
Tag[input]
element.
The value of the data element specified by the
DataOut[output]
tag.
DataLen[output]
PAX Computer Technology (Shenzhen) Co., Ltd.
The length of the data element.
2
PAX EMV Kernel API Programming Guide
Return
Instruction
EMV_OK
Succeed.
EMV_NO_DATA
Tag data not founded
EMV_PARAM_E
Parameter error.
RR
EMV library can store all of the EMV standard data elements; it can
also store up to 64 data elements which are defined by issuer. After
executing the function of read application data, the application can
call this function to get the value of the data element by specifying
the tag.
Refer to appendix A for the macro definition of the return values,
same as below.
2.6 EMVSetTLVData
Prototype
Function
Parameters
int EMVSetTLVData(unsigned short Tag, unsigned char
*DataIn, int DataLen);
Set the value of the data element by specifying the tag.
Tag of EMV standard or extended data
Tag[input]
element.
The value of the data element specified by the
DataIn[input]
tag.
DataLen[input]
Return
Instruction
The length of the data element.
EMV_OK
Succeed.
EMV_DATA_ERR Parameter error.
The value of the standard or priority data element can be modified or
set by the application. In this way, the application can satisfy the
requirement in some special environment. For example, EMV library
do not support blacklist check, but if the application needs to support
it, there must be a function to set the value of TVR in EMV library.
Normally, it’s not necessary to call this function.
2.7 EMVGetScriptResult
Prototype
int EMVGetScriptResult(unsigned char *Result, int *RetLen);
Function
Gets issuer script processing result.
Result[output]
The issuer script processing result.
The length of the issuer script processing
RetLen[output]
result.
EMV_OK
Succeed.
EMV_NO_DATA
There is no issuer script processing result.
EMV_PARAM_ERR Parameter error.
Parameters
Return
PAX Computer Technology (Shenzhen) Co., Ltd.
3
PAX EMV Kernel API Programming Guide
Instruction
As the issuer script processing result has no relevant TLV tag, there
must be a special function to get the value.
2.8 EMVSetPCIModeParam
Prototype
int EMVSetPCIModeParam(unsigned char ucPciMode, unsigned
char *pucExpectPinLen, unsigned long ulTimeoutMs);
Function
Set whether the kernel uses PCI verify offline PIN interface or not.
Parameters
Return
ucPciMode[input]
1 – Use PCI verify offline PIN interface.
0 – not use.
pucExpectPinLen[inp
ut]
When the kernel uses PCI verify offline PIN
interface, this parameter is to set the allowed
length of PIN. It is a string of the
enumeration of 0-12 and separated by ‘,’.
For example, ‘0,4,6’ means it is allowed to
input 4 or 6 digits for PIN, and to directly
press Enter without input PIN.
ulTimeoutMs[input]
Timeout of input PIN, unit: ms, maximum
300,000 ms.
EMV_OK
Succeed.
EMV_DATA_ERR
Parameter error.
1.
2.
Instruction
3.
The default setting is that the kernel does not use PCI verify
offline PIN interface.
If setting the kernel to use PCI verify offline PIN interface,
please notice the value of the 3rd parameter *pin in the call back
function cEMVGetHolderPwd. Refer to the notes of that
function for detail.
The function is Not Used for the Prolin software platform.
2.9 EMVReadVerInfo
Prototype
int EMVReadVerInfo(char *paucVer);
Function
Get the version of EMV kernel and the release date.
Version and release date of kernel with the
paucVer[output]
maximum length of 20 bytes. For example,
“v26 2008.10.09”.
EMV_OK
Succeed.
EMV_PARAM_ERR Parameter error.
Parameters
Return
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
4
PAX EMV Kernel API Programming Guide
2.10 EMVClearTransLog
Prototype
int EMVClearTransLog(void);
Function
Clear the transaction log of kernel.
Parameters
Return
None
EMV_OK
Instruction
1. Kernel will record the amount of the last 8 transactions after
calling EMVCoreInit. When performing terminal risk
management, kernel will add the amount of current transaction
with the amount of the last transaction found in the log giving that
the PAN is same and the result will be used for floor limit check.
This function is provided for application to erase this log after
settlement or other cases when necessary.
2. The function is Not Used for the Prolin software platform.
Succeed.
2.11 EMVAddIccTag
Prototype
int EMVAddIccTag(ELEMENT_ATTR tEleAttr, int nAddNum);
Function
Add Issuer Proprietary Data Element.
List of issuer proprietary data elements. The
structure adds two new variables. Refer to
tEleAttr[input]
appendix for structure ELEMENT
_ATTR.
Number of issuer proprietary data elements
nAddNum[input]
to add.
EMV_OK
Succeed.
Parameter error, the number of data
EMV_PARAM_ERR
elements to add can’t exceed 30.
1. Kernel only supports EMV defined standard data element. This
function is used to add the list of any proprietary data elements to
kernel so it will save the corresponding ones. Thus the
application can access the data through EMVGetTLVData.
2. The number in the list must equal nAddNum. MaxLen and Tag
must not be zero. Otherwise, parameter error will be returned.
3. Each time calling this function, kernel will replace the original
list.
4. If data duplicate happens when reading ICC, the latest data will
be used.
Parameters
Return
Instruction
2.12 EMVSetScriptProcMethod
Prototype
void EMVSetScriptProcMethod (uchar ucScriptMethodIn);
PAX Computer Technology (Shenzhen) Co., Ltd.
5
PAX EMV Kernel API Programming Guide
Function
Set the special script process flag.
EMV_SCRIPT_PROC_UNIONPAY: Union pay
Parameters
ucScriptMethodIn
[input]
script process method.
EMV_SCRIPT_PROC_NORMAL:
Normal
EMV script process.(Default value)
Return
Instruction
NULL
1. The Union Pay Network Authentication requires when there is no
response with script command, the script result should be set as script
not performed, while the EMVCo requires the script result should be
set as script processing failed in this case.
2. This function is only used when there is special requirement from
Union Pay Network Authentication.
2.13 EMVGetMCKParam
Prototype
int EMVGetMCKParam(EMV_MCKPARAM *pMCKParam)
Function
Get the kernel MCK parameter.
Parameters
Return
Instruction
pMCKParam[output]
Output the MCK parameter. Refer to
appendix
for
structure
EMV_MCKPARAM.
EMV_OK
Setting successful.
EMV_DATA_ERR
Parameter error.
Before calling function EMVSetMCKParam to modify MCK
parameter, call this function to get the MCK parameter first in order
to avoid that the parameter is set to 0 by mistake.
2.14 EMVSetMCKParam
Prototype
int EMVSetMCKParam(EMV_MCKPARAM *pMCKParam);
Function
Set MCK parameter.
Parameters
pMCKParam[input]
MCK parameter.Refer to appendix for
structure EMV_MCKPARAM.
EMV_OK
EMV_DATA_ERR
Succeed
Parameter is error
Return
Instruction
Before calling this function to modify MCK parameters, please call
EMVGetMCKParam to get the parameter. This method can avoid
other parameters in this structure being changed to zero mistakely.
Example：
EMV_EXTMPARAM ExTmParam;
EMV_MCKPARAM MCKParam;
PAX Computer Technology (Shenzhen) Co., Ltd.
6
PAX EMV Kernel API Programming Guide
memset(&ExTmParam,0,sizeof(EMV_EXTMPARAM));
memset(&MCKParam,0,sizeof(EMV_MCKPARAM));
ExTmParam.ucUseTermAIPFlg=1;
ExTmParam.aucTermAIP[0]=0x08;//Terminal is forced to
perform TRM.
MCKParam.pvoid = &ExTmParam;
EMVSetMCKParam(&MCKParam);
2.15 EMVSetTmECParam
Prototype
int EMVSetTmECParam(EMV_TMECPARAM *pParam);
Function
Set the terminal electronic cash related parameters.
Parameters
Return
pParam[input]
The electronic cash parameters which need
to be set. Refer to appendix for
structure EMV_TMECPARAM.
EMV_OK
Setting successful.
EMV_DATA_ERR
Parameter error.
EMV_TMECPARAM structure specification：
1.
Instruction
Setting specification：
Only when the ucECTSIFlg = 1，the value of TSI and TTL can
be set.
2. This function is used for PBOC only.
2.16 EMVSetConfigFlag
Prototype
void EMVSetConfigFlag(int_nConfigflag);
Function
Set configuration.
Parameters
Return
nConfigflag[input]
Only bit 1(the lowest one) & bit 2 are
valid at moment.
bit 1: 1 = support advice (default)
0 = not support
bit 2: 1= always asking
user to
confirm amount even no PIN
input is required
0 = does not ask user to confirm
when no PIN input is required
(default)
bit 3:
1 = support transaction log
0 = not support transaction log
None
PAX Computer Technology (Shenzhen) Co., Ltd.
7
PAX EMV Kernel API Programming Guide
Instruction
2.17 EMVGetParamFlag
Prototype
int EMVGetParamFlag(unsigned char ucParam, int *pnFlg)
Function
Get the flag for signature and advice.
ucParam [input]
Parameters
pnFlg[Output]
Indicate the flag to be gotten.
0x01 – Signature
0x02 – advice
The flag got from kernel.
0 – NO
1- YES
EMV_OK
Succeed.
EMV_PARAM_ERR
Parameter error.
Return
Instruction
1. After EMVStartTrans and EMVCompleteTrans are executed,
the application shall call this function to get the flag of advice,
and send an advice if the flag indicates YES.
2. After EMVCompleteTrans is executed, the application shall call
this function to get the flag of Signature, and require signature if
the flag indicates YES.
PAX Computer Technology (Shenzhen) Co., Ltd.
8
PAX EMV Kernel API Programming Guide
3
Certification Authority (CA) Public
Key Management
3.1 EMVAddCAPK
Prototype
int EMVAddCAPK(EMV_CAPK *capk );
Function
Add a new CA public key.
Parameters
Return
Instruction
The pointer pointing to the public key.
Refer to appendix for structure
EMV_CAPK.
EMV_OK
Succeed.
EMV_SUM_ERR
Checksum error.
Memory overflows (EMV Kernel supports
EMV_OVERFLOW
MAX_KEY_NUM CA public keys in
maximum).
EMV_PARAM_ERR
Parameter error.
1. If the public key already exists, the new key will replace the old
one.
2. CA public key is provided by acquirer. Sometimes, the key is not
assigned with the structure of EMV_CAPK. In that case, the
application may need to convert the public key before it can be
added to the EMV library.
capk[input]
3.2 EMVDelCAPK
Prototype
int EMVDelCAPK(unsigned char KeyID, unsigned char *RID);
Function
Delete a CA public key.
PAX Computer Technology (Shenzhen) Co., Ltd.
9
PAX EMV Kernel API Programming Guide
Parameters
Return
KeyID[input]
RID[input]
EMV_OK
EMV_NOT_FOUND
EMV_PARAM_ERR
The index of the key.
Registered Application Provider Identifier.
Succeed.
The key does not exist.
Parameter error.
Instruction
3.3 EMVGetCAPK
Prototype
int EMVGetCAPK(int Index, EMV_CAPK *capk );
Function
Get a CA public key.
Index[input]
Parameters
Return
Instruction
capk[output]
The
key
storage
index,
range(0
MAX_KEY_NUM).
The pointer pointing to the key. Refer to appendix
for structure EMV_CAPK.
EMV_OK
Succeed.
EMV_NOT_FOUND The key does not exist.
EMV_PARAM_ERR Parameter error.
The application can get all the keys and then delete them. An example
is like below:
for(i=0;i< MAX_KEY_NUM; i ++)
{
if(EMVGetCAPK(i, &capk )== EMV_OK)
{
EMVDelCAPK(capk.KeyID, capk.RID);
}
}
3.4 EMVCheckCAPK
Prototype
Function
Parameters
Return
Instruction
int EMVCheckCAPK(unsigned char *KeyID, unsigned char
*RID);
Check the validity of the public keys.
*KeyID[output]
The index of the expired key.
*RID[output]
The RID of the expired key.
EMV_OK
All the keys are valid.
EMV_KEY_EXP
One key is expired.
EMV_PARAM_ERR Parameter error
Only one expired key will be returned when calling this function.
When the function returns EMV_KEY_EXP, the application should
handle it and then continually call this function until it returns
EMV_OK.
PAX Computer Technology (Shenzhen) Co., Ltd.
10
PAX EMV Kernel API Programming Guide
4 Terminal Application List Management
4.1 EMVAddApp
Prototype
int EMVAddApp(EMV_APPLIST *App);
Function
Add an EMV application to terminal application list.
The pointer pointing to an application. Refer
App[input]
Parameters
Return
Instruction
to appendix for structure EMV_APPLIST.
EMV_OK
Succeed.
EMV_OVERFLOW
Memory overflows.
EMV_PARAM_ERR Parameter error.
EMV_FILE_ERR
File error
If the application already exists, the new application will replace the
old one.
4.2 EMVGetApp
Prototype
int EMVGetApp(int Index, EMV_APPLIST *App);
Function
Get an application from the terminal application list.Refer to
appendix for structure EMV_APPLIST.
Parameters
Return
App[output]
The application storage index, range(0 - MAX_
APP _NUM)
The pointer pointing to an application.
EMV_OK
EMV_NOT_FOUND
EMV_PARAM_ERR
EMV_FILE_ERR
Succeed.
The application does not exist.
Parameter error.
File error
Index[input]
PAX Computer Technology (Shenzhen) Co., Ltd.
11
PAX EMV Kernel API Programming Guide
Instruction
The application can get all the applications from the list and then
delete them. An example is like below:
for(i=0;i< MAX_APP_NUM; i ++)
{
if(EMVGetApp(i, &App)== EMV_OK)
{
EMVDelApp(App.AID, App.AidLen);
}
}
4.3 EMVDelApp
Prototype
int EMVDelApp(unsigned char *AID, int AidLen);
Function
Delete an application from the application list.
Application ID, compressed BCD, not more
AID[input]
than 16 bytes.
AidLen[input]
The length of AID, it must be bigger than 0.
EMV_OK
Succeed.
EMV_NOT_FOUND The application does not exist.
EMV_PARAM_ERR Parameter error.
EMV_FILE_ERR
File error
Parameters
Return
Instruction
4.4 EMVGetFinalAppPara
Prototype
int EMVGetFinalAppPara(EMV_APPLIST *ptEMV_APP);
Function
Get the parameter of current finally selected application.
The pointer pointing to the parameter of
ptEMV_APP[output] current finally selected application. Refer to
appendix for structure EMV_APPLIST.
EMV_OK
Succeed.
EMV_NO_APP
No selected application.
EMV_PARAM_ERR Parameter error.
Parameters
Return
Instruction
4.5 EMVModFinalAppPara
Prototype
int EMVModFinalAppPara(EMV_APPLIST *ptEMV_APP);
Function
Modify the parameter of current finally selected application.
The pointer pointing to the parameter of the
ptEMV_APP[input]
application. Refer to appendix for
Parameters
PAX Computer Technology (Shenzhen) Co., Ltd.
12
PAX EMV Kernel API Programming Guide
Return
EMV_OK
EMV_NO_APP
EMV_NOT_FOUND
EMV_PARAM_ERR
structure EMV_APPLIST.
Succeed.
No selected application.
Specified application not found.
Parameter error.
Instruction
4.6 EMVGetLabelList
Prototype
Function
Parameters
Return
Instruction
int EMVGetLabelList(APPLABEL_LIST *ptAppLabel, int *
pnAppNum);
Get the label list of the application candidate list.
The label list. Refer to appendix for structure
ptAppLabel[output]
APPLABEL_LIST.
pnAppNum[output]
The number of application in the candidate.
EMV_OK
Succeed.
EMV_NO_DATA
No data available.
EMV_PARAM_ERR Parameter error.
The terminal application can call this function in cEMVWaitAppSel
to get the label list corresponding to current application candidate.
4.7 EMVDelAllApp
Prototype
int EMVDelAllApp(void);
Function
Remove all application from terminal application list.
Parameters
Return
Null
EMV_OK
Succeed.
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
13
PAX EMV Kernel API Programming Guide
5
Terminal Revoked Issuer Public
Key Certification List Management
5.1 EMVAddRevocList
Prototype
Function
Parameters
Return
Instruction
int EMVAddRevocList(EMV_REVOCLIST *pRevocList );
Add a revoked issuer public key certification to revoked certification
list.
The pointer pointing to the revoked issuer
pRevocList[input]
public key certification. Refer to appendix
for structure EMV_REVOCLIST.
EMV_OK
Succeed.
EMV_DATA_ERR
Input data error (the pointer is null).
Memory overflows (Kernel supports 30
EMV_OVERFLOW
revoked issuer public key certifications in
maximum).
1. If the revoked issuer public key certification already exists, this
function directly returns succeeding.
2. The structure of the revoked issuer public key certification.
5.2 EMVDelRevocList
Prototype
Function
Parameters
int EMVDelRevocList(unsigned char ucIndex, unsigned char
*pucRID);
Delete a revoked issuer public key certification.
ucIndex[input]
The corresponding CA public key index of
PAX Computer Technology (Shenzhen) Co., Ltd.
14
PAX EMV Kernel API Programming Guide
pucRID[input]
Return
EMV_OK
EMV_DATA_ERR
EMV_NOT_FOUND
the revoked issuer public key certification.
The corresponding RID of the revoked
issuer public key certification.
Succeed.
Input data error(the pointer is null)
The specified certification not found.
Instruction
5.3 EMVDelAllRecovList
Prototype
void EMVDelAllRecovList(void);
Function
Delete all revoked issuer public key certifications.
Parameters
Return
None
None
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
15
PAX EMV Kernel API Programming Guide
6 Transaction Processing
EMV transaction processing functions are described in this part.
6.1 EMVInitTLVData
Prototype
void EMVInitTLVData(void);
Function
Initialize the EMV kernel data element storage structure.
Parameters
Return
Instruction
None
None
The function need to be called before the start of every transaction,
for instance, before the application selection, to initialize the EMV
kernel data element storage structure.
This function is used for contactless PBOC only.
6.2 EMVAppSelect
Prototype
int EMVAppSelect(int Slot, unsigned long TransNo);
Function
EMV application selection.
Slot[input]
Card slot number.
TransNo[input]
The sequence number of the transaction.
EMV_OK
Succeed.
ICC_RESET_ERR
IC card reset failed.
ICC_CMD_ERR
IC card command failed.
ICC_BLOCK
IC card has been blocked.
EMV_NO_APP
There is no IC card application supported by
Parameters
Return
PAX Computer Technology (Shenzhen) Co., Ltd.
16
PAX EMV Kernel API Programming Guide
Instruction
terminal.
EMV_APP_BLOCK
The EMV application has been blocked.
EMV_DATA_ERR
IC card data format error.
EMV_TIME_OUT
Application selection timeout.
EMV_USER_CANC Application selection is canceled by user.
ICC_RSP_6985
IC card responses with 6985 when GPO.
EMV_FILE_ERR
File error
1. Before calling this function, the EMV IC card must be in the
specified card slot which can be detected.
2. According to the EMV specification, if it returns EMV_NO_APP
or EMV_DATA_ERR ， application must prompt for ‘Swipe
card’.(The application can decide how to do according to the
actual requirement)
3. EMV_USER_CANCEL and EMV_TIME_OUT are returned by
callback function cEMVWaitAppSel. If the function
cEMVWaitAppSel doesn’t return these two values, the function
EMVAppSelect does not return them either.(Refer to
cEMVWaitAppSel)
4. ICC_RSP_6985 is returned when GPO responses 6985 and
there’s no application left in the application candidate list, the
terminal application should then decide whether to terminate the
transaction or to fallback.
6.3 EMVReadAppData
Prototype
int EMVReadAppData(void);
Function
Read the selected application’s data, transaction amount, etc.
Parameters
Return
Instruction
None
EMV_OK
Succeed.
ICC_CMD_ERR
IC card command failed.
EMV_RSP_ERR
IC card response code error.
EMV_DATA_ERR
IC card data format error.
EMV_TIME_OUT
Input amount timeout.
EMV_USER_CANC Input amount is canceled by user.
1. EMV_USER_CANCEL and EMV_TIME_OUT are returned by
callback function cEMVInputAmount. If the function
cEMVInputAmount doesn’t return these two values, this
function
does
not
return
them
either.(Refer
to
cEMVInputAmount)
2. If this function does not return EMV_OK, the transaction should
be terminated.
PAX Computer Technology (Shenzhen) Co., Ltd.
17
PAX EMV Kernel API Programming Guide
6.4 EMVCardAuth
Prototype
int EMVCardAuth(void);
Function
IC card data authentication.
Parameters
Return
Instruction
None
EMV_OK
Complete.
ICC_CMD_ERR
IC card command failed.
EMV_RSP_ERR
IC card response code error.
1. This function returning EMV_OK does not stand for data
authentication succeeded. The application can get the result of
the authentication through function EMVGetTLVData and
query the value of TVR. If the authentication method is CDA,
this function just recovers the IC card private key. The
authentication will not be done until performing Generate AC
command.
2. If this function does not return EMV_OK, the transaction should
be terminated.
6.5 EMVProcTrans
Prototype
int EMVProcTrans(void);
Function
Process EMV transaction.
Parameters
Return
Instruction
None
EMV_OK
Succeed.
ICC_CMD_ERR
IC card command failed.
EMV_RSP_ERR
IC card response code error.
EMV_DATA_ERR
IC card data format error.
EMV_NOT_ACCEPT
Transaction cannot be accepted.
EMV_DENIAL
Transaction denied.
EMV_TIME_OUT
Input PIN timeout.
EMV_USER_CANCEL Transaction is canceled by user.
ICC_RSP_6985
ICC response 6985 in GAC.
1. EMV_USER_CANCEL and EMV_TIME_OUT are returned by
callback function cEMVGetHolderPwd. If the function
cEMVGetHolderPwd doesn’t return these two values, this
function does not return them either.(Refer to EMVAppSelect)
2. Both EMV_NOT_ACCEPT and EMV_DENIAL stand for
transaction failed. According to the EMV specification,
EMV_NOT_ACCEPT will be returned on condition that the
service does not accepted, and EMV_DENIAL will be returned
on other conditions.
3. If this function does not return EMV_OK or ICC_RSP_6985, the
transaction should be terminated.
4. ICC_RSP_6985 is returned when GAC responses 6985, the
PAX Computer Technology (Shenzhen) Co., Ltd.
18
PAX EMV Kernel API Programming Guide
terminal application should then decide whether to terminate the
transaction or to fallback.
5.
The function is Not Used for the Prolin software platform.
6.6 EMVAppSelectForLog
Prototype
int EMVAppSelectForLog(int Slot, unsigned char ucFlg);
Function
Read the card’s transaction log。
Parameters
Return
Instruction
Slot[input]
Card slot number.
ucFlg[input]
Decide whether the block application will be
added to candidate list or not.
0-Add, 1-Not add (The default is 0)
EMV_OK
Succeed.
ICC_RESET_ERR
IC card reset failed.
ICC_CMD_ERR
IC card command failed.
ICC_BLOCK
IC card has been blocked.
EMV_NO_APP
No EMV
supported.
EMV_DATA_ERR
Card data format error.
EMV_TIME_OUT
Application selection timeout.
application
that
terminal
EMV_USER_CANC
Application selection is canceled by user.
EL
This function is similar with the function EMVAppSelect. The
difference between them is that this function can add the block
application to candidate list base on the different parameter setting
when the application selection is done.
6.7 ReadLogRecord
Prototype
int ReadLogRecord(int RecordNo);
Function
Read transaction log
Parameters
Return
Instruction
RecordNo[input]
Record number.
EMV_OK
Transaction processing successful.
EMV_DATA_ERR
Card data error.
RECORD_NOTEXI
ST
The specified log record doesn’t exist.
After the application finished the application selection with function
PAX Computer Technology (Shenzhen) Co., Ltd.
19
PAX EMV Kernel API Programming Guide
EMVAppSelectForLog, this function can be called to read the
transaction log of the selected application.
RecordNo, Record number begins at 1, the application can read all
the transaction log by following code:
Reco＝1；
while(1){
ret=ReadLogRecord(Reco);
if(ret==RECORD_NOTEXIST){
if(Reco==1) return NO_TRANS_LOG;
else break;
}
/*Read the specific log by the function GetLogItem. */
Reco++;
}
This function can only read the transaction log to the EMV kernel
buffer. Application can read the specific log by the function
GetLogItem, such as transaction amount, transaction time and so on.
6.8 GetLogItem
Prototype
int GetLogItem(unsigned short Tag, unsigned char *TagData, int
*TagLen);
Function
Read the data items of transaction log(PBOC compatible EMV2)。
Parameters
Return
Instruction
Tag[input]
The tag of data items that need to read.
TagData[output]
The return value of the data items.
TagLen[output]
The return length of the value of the data
items.
EMV_OK
Transaction processing successful.
EMV_DATA_ERR
Card data error.
LOGITEM_NOTEXI
The specified log record doesn’t exist.
ST
For each transaction log record that was read by function
ReadLogRecord, application can read the specific log information
by this function. For instance, if want to read transaction amount, you
can call the function as follows:
GetLogItem(0x9F02, AmtStr, AmtStrLen);
/*0x9F02 is the tag of amount（Please refer to the EMV Tag list）*/
PAX Computer Technology (Shenzhen) Co., Ltd.
20
PAX EMV Kernel API Programming Guide
6.9 EMVGetCardECBalance
Prototype
int EMVGetCardECBalance(unsigned long *plBalance);
Function
Read the electronic cash balance from card.
Parameters
Return
Instruction
plBalance[output]
The electronic cash balance read from card.
EMV_OK
Get data succeed.
EMV_DATA_ERR
Get data failed.
EMV_PARAM_ERR
Parameter error.
This function is used for PBOC only.
6.10 EMVStartTrans
Prototype
Function
Parameters
Return
Instruction
int EMVStartTrans (ulong ulAuthAmt, ulong ulCashBackAmt,
uchar *pACType);
Performing process restrict, cardholder verification, terminal risk
management & 1st GAC.
This authorization amount will overwrite
ulAuthAmt[input]
the value input in cEMVInputAmount.
It must be input.
This cashback amount will overwrite the
ulCashBackAmt[input]
value input in cEMVInputAmount. It
must be input.
Output. AC type which could be:
pACType[output]
AC_TC / AC_AAC / AC_ARQC
EMV_OK
Succeed.
EMV_DENIAL
Transaction denied.
EMV_DATA_ERR
IC card data format error.
EMV_NOT_ACCEPT
Transaction is not accepted.
ICC_CMD_ERR
IC card command failed.
ICC_RSP_6985
ICC response 6985 in 1st GAC.
EMV_RSP_ERR
IC card response code error.
EMV_PARAM_ERR
Parameter error.
1. If the return code is EMV_DENIAL or EMV_NOT_ACCEPT,
the application should get the CID (9F27) from kernel, and check
if the advice message is needed.
2. If the return code is EMV_OK, pACType shall be checked. If
pACType is AC_TC, the transaction shall be approved. If
pACType is AC_ARQC, the transaction shall go online and then
EMVCompleteTrans must to be called.
PAX Computer Technology (Shenzhen) Co., Ltd.
21
PAX EMV Kernel API Programming Guide
6.11 EMVCompleteTrans
Prototype
Function
Parameters
Return
Instruction
int EMVCompleteTrans(int nCommuStatus, unsigned char
*paucScript, int *pnScriptLen, uchar *pACType);
Performing online data processing (issuer authentication, script
processing, etc) & 2nd GAC.
Input. Online status which could be:
ONLINE_APPROVE - Online approved
or online referral approved.
ONLINE_FAILED - Online failed.
nCommuStatus[input]
ONLINE_DENIAL – Online rejected or
online referral rejected.
If the online status is out of these ranges,
the application should reject the
transaction.
*paucScript[input]
Input. Issuer script data in TLV format.
*pnScriptLen[input]
Input. The length of issuer script data.
Output: AC type which could be:
AC_TC Transaction approved
AC_AAC Terminal requests TC, but
pACType[output]
rejected by ICC.
AC_AAC_HOST Transaction rejected by
issuer.
EMV_OK
Succeed.
EMV_DENIAL
Transaction denied.
EMV_DATA_ERR
IC card data format error.
EMV_NOT_ACCEPT
Transaction is not accepted.
ICC_CMD_ERR
IC card command failed.
ICC_RSP_6985
ICC response 6985 in 2nd GAC.
EMV_RSP_ERR
IC card response code error.
EMV_PARAM_ERR
Parameter error.
1. The following data element, if exists, must be sent to kernel
through EMVSetTLVData before calling this function:
ARC – 8A
AC – 89
IAD – 91
2. If the return code is EMV_DENIAL or EMV_NOT_ACCEPT,
Application should get the CID (9F27) from kernel, and check if
the advice message is needed.
3. If the return code is EMV_DENIAL, and the transaction is online
data captured, and the online result is ONLINE_APPROVE, then
application shall send a reversal message to host.
4. If the return code is not EMV_OK, EMVGetScriptResult must
be called, and if EMVGetScriptResult returns EMV_OK ，
Application should send a advice message if advice is supported.
PAX Computer Technology (Shenzhen) Co., Ltd.
22
PAX EMV Kernel API Programming Guide
6.12 EMVSwitchClss
Prototype
int EMVSwitchClss(Clss_TransParam *ptTransParam,uchar
*pucSelData, int nSelLen, uchar *pucGPOData, int nGPOLen);
Function
Set response data of final selection and GPO command into EMV
kernel.
ptTransParam[input]
Transaction related parameters. Please refer
to the contactless common data instruction
documentation for the parameter structure.
Refer to appendix for structure
Clss_TransParam.
Parameters
Return
Instruction
pucSelData[input]
Response data of final selection
command.,which need to be got by
Clss_GetFinalSelectData_Entry in Entry
library.
nSelLen[input]
The data length return by final selection
command, which need to be got by
Clss_GetFinalSelectData_Entry in Entry
library.
pucGPOData[input]
The data of GPO command and response,
which need to be got by
Clss_GetGPOData_Pboc in qPBOC
library.
nGPOLen[input]
The data length of GPO command and
response, which need to be got by
Clss_GetGPOData_Pboc in qPBOC
library.
EMV_OK
Succeed.
EMV_PARAM_ERR
Parameter error.
EMV_NO_APP
There is no application at candidate list.
EMV_DATA_ERR
Data error.
This function is only used for contactless PBOC application.
PAX Computer Technology (Shenzhen) Co., Ltd.
23
PAX EMV Kernel API Programming Guide
6.13 EMVSetAmount
Prototype
int EMVSetAmount(unsigned char * szAuthAmount, unsigned char *
szCashBackAmount)；
Function
Set transaction amount and cashback amount bigger than 0xffffffff,.
szAuthAmount[input]
Parameters
Return
szCashBackAmount[i
nput]
Authorised Amount (Tag 9F02, n12)
Other Amount(Tag 9F03, n12)
If Other Amount does not exist, the value
should be NULL.
EMV_OK
Succeed.
EMV_DATA_ERR
Data error.
If the amount exceeds 0xffffffff, please use this function to set the
amount to kernel.
Please call this function before EmvProcTrans or EmvStartTrans.
If use this function to set amount, please make cEMVInputAmount
return two zero amount.
Instruction
For example:
cEMVInputAmount（unsigned long *AuthAmt, unsigned long *CashBackAmt）
{
// if transaction type = CashBack
*AuthAmt = 0;
*CashBackAmt = 0;
return 0;
}
Note: If the amount is smaller than 0xffffffff, this amount will be overwrited
by the amount input in EMVStartTrans.
6.14 EMVReadSingleLoadLog
Prototype
int EMVReadSingleLoadLog (int nRecordNoIn);
Function
Read single loading log (PBOC3.0).
Parameters
Return
nRecordNoIn[input
]
Record number.
EMV_OK
Transaction processing successful.
EMV_DATA_ERR
Card data error.
PAX Computer Technology (Shenzhen) Co., Ltd.
24
PAX EMV Kernel API Programming Guide
RECORD_NOTEXI
ST
The specified log record doesn’t exist.
This function can be called to read the loading log of the selected
application. And it should be called after the function
EMVAppSelectForLog.
RecordNo, Record number begins at 1, the application can read all
the loading logs by following code:
Reco＝1；
Instruction
while(1){
ret=EMVReadSingleLoadLog (Reco);
if(ret==RECORD_NOTEXIST){
if(Reco==1) return NO_TRANS_LOG;
else break;
}
/*Read the specific
log by the function
EMVGetSingleLoadLogItem. */
Reco++;
}
This function only save the loading log to the EMV kernel buffer.
Application could read the specific log item by the function
EMVGetSingleLoadLogItem, such as transaction amount,
transaction time and so on.
6.15 EMVGetSingleLoadLogItem
Prototype
int EMVGetSingleLoadLogItem(unsigned short usTagIn, unsigned char
*paucDataOut, int *pnLenOut);
Function
Read the data item of loading log (PBOC3.0).
Parameters
Return
Instruction
usTagIn[input]
The tag of data item to be read.
paucDataOut[output]
Pointer to the value of the data item.
pnLenOut[output]
Pointer to the length of data item.
EMV_OK
Transaction processing successful.
EMV_DATA_ERR
Card data error.
LOGITEM_NOTEXI
ST
The specified log record doesn’t exist.
NO_TRANS_LOG
The entry of loading log doesn’t exist.
For each loading log record that was read by function
EMVReadSingleLoadLog, application can read the specific log
information by this function. For example, if want to read save
transaction amount, you can call the function as follows:
EMVGetSingleLoadLogItem(0x9F02, AmtStr, AmtStrLen);
PAX Computer Technology (Shenzhen) Co., Ltd.
25
PAX EMV Kernel API Programming Guide
/*0x9F02 is the tag of amount（Please refer to the EMV Tag list）*/
6.16 EMVReadAllLoadLogs
Prototype
int EMVReadAllLoadLogs(unsigned char *paucLogDataOut, int
*pnLenOut);
Function
Read all loading logs (PBOC3.0).
Parameters
Return
Instruction
paucLogDataOut[o
utput]
Pointer to the loading log data.
pnLenOut[output]
Pointer to the length of the loading log data.
EMV_OK
Transaction processing successful.
EMV_DATA_ERR
Card data error.
RECORD_NOTEXI
The specified log record doesn’t exist.
ST
This function can read out all the loading transaction logs in one time,
and saves them into the EMV kernel buffer. Please refer to table 12
and 13 in PBOC 3.0 book 13 for the format of the loading log.
6.17 EMVGetLogData
Prototype
int EMVGetLogData (unsigned char *paucLogDataOut, int *pnLenOut);
Function
Get the log data which is read from card.
Parameters
Return
Instruction
paucLogDataOut[o
utput]
Pointer to the log data.
pnLenOut[output]
Pointer to the length of the log data.
EMV_OK
Transaction processing successful.
EMV_PARAM_ER
R
The parameter is error.
NO_TRANS_LOG
There is no log data.
1. If the application read loading log before calling this function, the
log data which is got by this function is loading log data. Please
refer to PBOC 3.0 Book 13 for the format of the loading log data.
2. If the application read transaction log before calling this function,
the log data which is got by this function is transaction log data.
Please refer to PBOC 3.0 Book 13 for the format of the
transaction log data.
PAX Computer Technology (Shenzhen) Co., Ltd.
26
PAX EMV Kernel API Programming Guide
7 Callback Functions
The interface of the callback functions which kernel needs to call are described in this
part. The terminal application needs to implement these functions.
7.1 cEMVWaitAppSel
Prototype
Function
Parameters
Return
int cEMVWaitAppSel(int TryCnt, EMV_APPLIST List[], int
AppNum);
Wait for user to select an application from the application candidate
list. If there is only one application in the application list and it
doesn’t require cardholder confirmation, this function will not be
called.
TryCnt=0 means it is called for the first
time, otherwise, it has been called more
than one time. (According to the EMV
specification, if this function has been
TryCnt[input]
called more than one time, terminal
should prompt for ‘APP NOT ACCEPTS,
TRY AGAIN’ or some other word like
that.).
Application candidate list. Refer to
List[][input]
appendix for the structure of
EMV_APPLIST.
AppNum[input]
The number of the application in the list.
The sequence number selected by the
>=0
user (For example: 0 stands for List[0]
was selected).
EMV_USER_CANCEL Application selection is canceled by user.
PAX Computer Technology (Shenzhen) Co., Ltd.
27
PAX EMV Kernel API Programming Guide
EMV_TIME_OUT
Application selection timeout.
The application is listed in the sequence according to the EMV
specification. As the List is also used for output parameter, so if there
is any modification to the list, directly operate to the pointer.
Instruction
Refer to EMVAppSelect for the purpose of EMV_USER_CANCEL
and EMV_TIME_OUT.
7.2 cEMVInputAmount
Prototype
int cEMVInputAmount(unsigned long *AuthAmt, unsigned long
*CashBackAmt);
Function
Input transaction amount.
AuthAmt[output]
Parameters
Return
Instruction
CashBackAmt[output]
Transaction amount.
Cashback amount. If CashBackAmt is NULL,
there is no need to input the amount. If
CashBackAmt is not NULL, input the amount
or set it as 0.
EMV_OK
Input succeeds.
EMV_USER_CANCEL
Amount input is canceled by user.
EMV_TIME_OUT
Amount input timeout.
Refer to EMVAppSelect for the purpose of EMV_USER_CANCEL
and EMV_TIME_OUT.
7.3 cEMVGetHolderPwd
Prototype
int cEMVGetHolderPwd(int TryFlag, int RemainCnt, char *pin);
Function
Wait for cardholder to input PIN.
0: It’s the first time calling this function
to get the cardholder’s PIN in this
transaction.
1: It’s not the first time calling this
function to get the cardholder’s PIN in
TryFlag[input]
this transaction. (It appears only when
verifying the offline PIN and failing)
2: PIN is not required, calling this
function to allow the cardholder to
confirm the amount only. RemainCnt is
set as 0 and pin is set as NULL.
Parameters
PAX Computer Technology (Shenzhen) Co., Ltd.
28
PAX EMV Kernel API Programming Guide
1.
Return
Instruction
The chance remained to verify the
PIN. If RemainCnt equals 1, it means
only one chance remained to verify
the PIN, and if the following PIN
verification is still failed, the PIN
will be blocked.
RemainCnt[input]
2. If the parameter pin is NULL, it
means to input online PIN. In this
case, TryFlag and RemainCnt don’t
make sense; the PIN will be
encrypted and stored by the terminal
application and send to host when
online, and then verified by the host.
1. If PCI verify offline PIN interface is
not used, this parameter is output.
The application should return
plaintext PIN in it with string ended
with ’\x00’.
2. If PCI verify offline PIN interface is
used, this parameter is input. The
application doesn’t need to return
Pin[input/output]
anything in it. The possible value of
pin[0] in this condition could be:
EMV_PED_WAIT: PIN input
interval not enough.
EMV_PED_TIMEOUT:
PIN
input timeout.
EMV_PED_FAIL: PED locked
or other failure.
EMV_OK
Succeed.
There is no pinpad or pinpad does not
EMV_NO_PINPAD
work.
No PIN or cardholder doesn’t want to
EMV_NO_PASSWORD
input PIN.
EMV_USER_CANCEL PIN input is canceled by user.
EMV_TIME_OUT
PIN input timeout.
1. The application can flexibly arrange PIN input interface which
fulfill user’s requirement. The mode of PIN input can be freely
controlled by the application, at the same time it must be
compatible with the EMV security specification.
2. Refer
to
EMVProcTrans
for
the
purpose
of
EMV_USER_CANCEL and EMV_TIME_OUT.
3. From version V25_T4, if this function is used for PCI compliant
products
such
as
S80/S90/SP30,
interface
EMVSetPCIModeParam should be used to set the kernel using
PCI verify offline PIN interface or not.
4. In monitor platform, if setting kernel to use PCI verifies offline
PIN interface. In prolin platform, the operation of offline PIN is
completed by callback function cEMVPedVerifyCipherPin.
This function does not need to implement the operation of PIN
PAX Computer Technology (Shenzhen) Co., Ltd.
29
PAX EMV Kernel API Programming Guide
5.
input, but still need to display the prompt information to
cardholder such as transaction amount and “Please input PIN”.
If setting the kernel to use PCI verify offline PIN interface, when
input PIN fail, the 1st byte of the 3rd parameter *pin is used to
carry the failure information. The possible values of pin[0]
include EMV_PED_WAIT, EMV_PED_TIMEOUT and
EMV_PED_FAIL.
7.4 cEMVReferProc
Prototype
int cEMVReferProc(void);
Function
Process referral activated by the issuer.
Parameters
Return
Instruction
None
REFER_APPROVE
Referral approved.
REFER_DENIAL
Referral denied.
1. For the referral activated by the issuer, the function only returns
REFER_DENIAL or REFER_APPROVE.
2. If the acquirer doesn’t support referral processing, the application
can directly return REFER_DENIAL according to the acquirer’s
requirement.
3. The function is Not Used for the Prolin software platform.
7.5 cEMVOnlineProc
Prototype
int cEMVOnlineProc(unsigned char *RspCode, unsigned char
*AuthCode, int *AuthCodeLen, unsigned char *IAuthData, int
*IAuthDataLen, unsigned char *script, int *ScriptLen);
Function
Online transaction.
RspCode[output]
AuthCode[output]
AuthCodeLen[output]
IAuthData[output]
Parameters
IAuthDataLen[output]
Script[output]
ScriptLen[output]
Return
ONLINE_APPROVE
PAX Computer Technology (Shenzhen) Co., Ltd.
Authorization response code, 2 bytes. Set
RspCode[0] as 0 in case of online failed.
Authorization code，6 bytes.
The length of the AuthCode. Set it as 0
when there is no AuthCode.
Issuer authentication data returned from
host.
The length of the IAuthData. Set it as 0
when there is no IAuthData.
Issuer script. If the scripts are not sent in
one 8583 field, then put all the scripts
together and return by this parameter.
The length of the script. Set it as 0 when
there is no script.
Online transaction approved (host
approve the transaction).
30
PAX EMV Kernel API Programming Guide
Online transaction denied (host denied
the transaction).
Online transaction referral (Issuer
ONLINE_REFER
referral).
ONLINE_FAILED
Online transaction failed.
Online transaction aborted (PBOC
ONLINE_ABORT
requirement).
1. This function processes as below:
Firstly, it gets the IC card transaction data required by online
processing and assembles data package;
Secondly, it connects the host to perform data communication.
At last, it returns the data received from host to the EMV library
through the parameter.
If online failed, for example, connection failed or receiving data
failed, it must return ONLINE_FAILED.
The application need to handle automatic reversal by itself.
2. The function is Not Used for the Prolin software platform.
ONLINE_DENIAL
Instruction
7.6 cEMVAdviceProc
Prototype
void cEMVAdviceProc(void);
Function
Online or offline advice processing.
Parameters
Return
Instruction
None
None
1. Whether supporting advice processing or not is determined by
the acquirer (or issuer). Directly return if it does not support.
2. Whether to send the data package to the host immediately or
store it for later sending online is determined by the acquirer (or
issuer).
3. The application can get the data in the advice data package which
may be useful through the function EMVGetTLVData.
7.7 cEMVVerifyPINOK
Prototype
void cEMVVerifyPINOK(void);
Function
Prompt for “PIN OK”.
Parameters
Return
Instruction
None
None
1. When EMV library verify PIN failed, it will call the function
cEMVGetHolderPwd to prompt for error massage.
2. When EMV library verifies PIN and passes, it will call this
function. The terminal application may prompt for ‘PIN OK’ in this
function. If this is not necessary, the function can directly return.
PAX Computer Technology (Shenzhen) Co., Ltd.
31
PAX EMV Kernel API Programming Guide
7.8 cEMVUnknowTLVData
Prototype
Function
Parameters
int cEMVUnknowTLVData(unsigned short Tag, unsigned char
*dat, int len);
Get the data of the unknown tag.
Tag. It may be not defined by EMV or
Tag[input]
defined by EMV but can’t be found in the
IC card.
The value of the tag, filled by the
Dat[output]
application.
The length of the tag according to the
DOL requirement.
Len[output]
-1
Return
The application offers nothing for the tag.
The application offers the value of the
tag.
0
1.For the Prolin software platform, the kernel will obtain the
following Tags’ value by this function:
Unpredictable Number (9F37)
Transaction Date (9A).
Transaction Time (9F21)
Instruction
(IFD) Serial Number (9F1E)
Last transaction amount of current PAN & PANSN (FF01)
2. If EMV library doesn’t recognize a tag when processing DOL, it
will call this callback function and require application to return the
value of the tag. If the application cannot provide, it can directly
return -1.This function is also provided to satisfy the special
application which is out of scope of EMV requirement. It returns -1
normally.
7.9 cCertVerify
Prototype
int cCertVerify(void);
Function
Cardholder credential verify(PBOC)
Parameters
Return
None
-1
PAX Computer Technology (Shenzhen) Co., Ltd.
Verify failed.
32
PAX EMV Kernel API Programming Guide
0
Instruction
Verify succeeded.
PBOC adds the CVM, which is for cardholder credential verify.
During the transaction, when the EMV kernel finds that the current
used PBOC card need to do the cardholder verify, it will call this
function. The application should call the function EMVGetTLVData
to read the credential number and credential type, and provide the
relevant information to the operator.
This function is only used for PBOC.
7.10 cEmvSetParam
Prototype
int cEmvSetParam(void);
Function
Set parameter after application selection.
Parameters
Return
Instruction
None
EMV_OK
Succeed.
Others
Abort/Terminate current transaction.
1. This function is used to set some AID specific parameter after
performing application selection and before GPO. Application
can call EMVSetTLVData in this function to set these
parameters.
2. When the return value of this function is not EMV_OK, kernel
will abort the current transaction.
3. If the terminal support SM, application shall set DF69 with value
1, length 1 in this function.
7.11 cEMVPiccIsoCommand
Prototype
unsigned char cEMVPiccIsoCommand (unsigned char cid,APDU_SEND
*ApduSend,APDU_RESP *ApduRecv);
Function
Data exchange between the contactless reader and the contactless
card.
cid[input]
Specify the logical channel of card. The
logical channel is output by the CID
parameter of PiccDetect(). The channel
number range from 0 to 14, and the current
values are 0.
ApduSend [input]
The command data structure send to
PICC.(Refer to appendix for the data
structure of APDU_SEND )
Parameters
PAX Computer Technology (Shenzhen) Co., Ltd.
33
PAX EMV Kernel API Programming Guide
ApduRecv [output]
Return
Instruction
The data structure received by PICC.( Refer
to appendix for the data structure of
APDU_RESP)
Please refer to Products Application Developer Guide of PAX for
the PICC operation. The kernel only cares about the PICC operation
succeed or not. If succeed, return 0x00, others return 0x01.
1. This function is only used for contactless PBOC. If the kernel is
only used for the contact application, you can set this callback
function to an empty function.
2. Parameters cid and pucSelData are controlled by application. The
kernel only uses the output parameter and return value.
7.12 cEMVIccIsoCommand
Prototype
uchar cEMVIccIsoCommand(uchar slot,
APDU_SEND *ApduSend,
APDU_RESP *ApduRecv);
Function
IC card operating function.
Parameters
Slot [Input]
Specify the logical channel of card. The
logical channel is output by IccDetect and
its current values are 0.
ApduSend [Input]
The command data structure send to
ICC.(Refer to appendix for the data
structure of APDU_SEND )
ApduRecv [Output]
The data structure received by ICC.( Refer
to appendix for the data structure of
APDU_RESP)
Return
Please refer to products Application Developer Guide of PAX for the
ICC operation. The kernel only cares about the ICC operation
succeed or not. If succeed, return 0x00, others return 0x01.
Instruction
1. Interactive with IC card to get the relevant information of
command.
2. The function is only used for the Prolin software platform.
3. Parameters slot and ApduSend are controlled by application. The
kernel only uses the output parameter and return value.
PAX Computer Technology (Shenzhen) Co., Ltd.
34
PAX EMV Kernel API Programming Guide
7.13 cEMVPedVerifyPlainPin
Prototype
int cEMVPedVerifyPlainPin (uchar IccSlot,
uchar *ExpPinLenIn,
uchar *IccRespOut,
uchar Mode,
ulong TimeoutMs);
Function
Get offline plaintext PIN and verify offline plaintext PIN.
Parameters
IccSlot [Input]
IC card slot.
ExpPinLenIn [Input]
The input string which has the valid length.
IccRespOut [Output]
The status code of IC card response.
Mode [Input]
IC card command mode.
TimeoutMs [Input]
The timeout for enter PIN.
Application need to transform the return value to the following six
return values, which can refer to products Application Developer
Guide of PAX:
PED_RET_ERR_NO_PIN_INPUT
PED_RET_ERR_INPUT_CANCEL
Return
PED_RET_ERR_ICC_NO_INIT
PED_RET_ERR_NO_ICC
PED_RET_ERR_WAIT_INTERVAL
PED_RET_OK
Other return values can return without any transform.
Instruction
1. The function is only used for the Prolin software platform.
2. Parameters ExpPinLenIn and TimeoutMs are controlled by the
application, other parameters are input by EMV kernel.
3. If there is an external PINPAD, the application should construct
the PIN block and do PIN verify in this callback function.
Please refer to section 6.5.12 of EMV book 3 for PIN block
construction and verification.
PAX Computer Technology (Shenzhen) Co., Ltd.
35
PAX EMV Kernel API Programming Guide
7.14 cEMVPedVerifyCipherPin
Prototype
int cEMVPedVerifyCipherPin (uchar IccSlot,
uchar *ExpPinLenIn,
RSA_PINKEY *RsaPinKeyIn,
uchar *IccRespOut,
uchar Mode,
ulong TimeoutMs);
Function
Get offline enciphered PIN and verify offline enciphered PIN.
IccSlot [Input]
IC card slot.
ExpPinLenIn [Input]
The input string which has the valid length.
RsaPinKeyIn [Input]
The data structure required by
encryption.(Refer to the appendix for the
data structure RSA_PINKEY)
Mode [Input]
IC card command mode.
IccRespOut [Output]
The status code of IC card response.
TimeoutMs [Input]
The timeout for enter PIN.
Parameters
Application need to transform the return value to following six return
values, which can refer to products Application Developer Guide of
PAX:
PED_RET_ERR_NO_PIN_INPUT
PED_RET_ERR_INPUT_CANCEL
Return
PED_RET_ERR_ICC_NO_INIT
PED_RET_ERR_NO_ICC
PED_RET_ERR_WAIT_INTERVAL
PED_RET_OK
Other return values can return without any transform.
Instruction
1. The function is only used for the Prolin software platform.
2. Parameters ExpPinLenIn and TimeoutMs are controlled by the
application, other parameters are input by EMV kernel.
3. If there is an external PINPAD, the application should construct
the PIN block, PIN encrypts and verification in this callback
functions.
Please refer to section 6.5.12 of EMV book 3 for PIN block
construction and verification.
PAX Computer Technology (Shenzhen) Co., Ltd.
36
PAX EMV Kernel API Programming Guide
Please refer to section 7.2 of EMV book 2 for PIN encrypt.
7.15 cEMVSM2Verify
Prototype
unsigned char cEMVSM2Verify(unsigned char *paucPubkeyIn,unsigned
char *paucMsgIn,int nMsglenIn, unsigned char *paucSignIn, int
nSignlenIn);
Function
SM2 verification.
Parameters
Return
paucPubkeyIn [input]
Pointer to the public key.
paucMsgIn [input]
Pointer to the message buffer.
nMsglenIn [input]
Length of the message.
paucSignIn [input]
Pointer to the signature of the message.
nSignlenIn [input]
Length of the signature of the message.
EMV_OK
Success
Other
Fail
Example:
#define ENTLA "\x00\x80"
#define IDA
"\x31\x32\x33\x34\x35\x36\x37\x38\x31\x32\x33\x34\x35\x36\x
37\x38"
Instruction
unsigned char cEMVSM2Verify(unsigned char
*paucPubkeyIn,unsigned char *paucMsgIn,int nMsglenIn, unsigned
char *paucSignIn, int nSignlenIn)
{
Gen_Za(ENTLA, 2, IDA, 16, aucPubKey);
return SM2_Verify(aucPubKey, aucInputData, nInputLen,
aucSigData, nSigLen);
}
7.16 cEMVSM3
Prototype
unsigned char cEMVSM3(unsigned char * paucMsgIn, int
nMsglenIn,unsigned char * paucResultOut);
Function
SM3 hash calculation.
Parameters
paucMsgIn [Input]
PAX Computer Technology (Shenzhen) Co., Ltd.
Pointer to message buffer.
37
PAX EMV Kernel API Programming Guide
paucMsgIn [Input]
paucResultOut
[Output]
Return
Instruction
EMV_OK
Pointer to length of message.
Pointer to output hash result buffer.
Success
Example:
unsigned char cEMVSM3(unsigned char * paucMsgIn, int
nMsglenIn,unsigned char * paucResultOut)
{
sm3(input,ilen,output);
return EMV_OK;
}
PAX Computer Technology (Shenzhen) Co., Ltd.
38
PAX EMV Kernel API Programming Guide
8 Debug Interface
8.1 EMVSetDebug
Prototype
void EMVSetDebug(int EnableFlag);
Function
Enable/Disable debug state.
Parameters
Return
Instruction
EnableFlag[input]
1 － Enable debug state.
0 － Disable debug state.
None
1. After enabling debug state, kernel will send all the commands and
data which it sent to and received from the IC card through COM1
with the baud rate of 115200, 8, n, 1. Then developer can receive
them and analyze by hyper terminal or other tools.
The default debug state of kernel is 0 (Disabled).
2. The function is Not Used for the Prolin software platform.
8.2 EMVGetICCStatus
Prototype
Function
Parameters
Return
Instruction
void EMVGetICCStatus(unsigned char *SWA, unsigned char
*SWB);
Read the response status word of the last ICC command of a failed
transaction.
SWA[output]
SWA.
SWB[output]
SWB.
None
The function is Not Used for the Prolin software platform.
PAX Computer Technology (Shenzhen) Co., Ltd.
39
PAX EMV Kernel API Programming Guide
8.3 EMVGetVerifyICCStatus
Prototype
Function
Parameters
Return
Instruction
int EMVGetVerifyICCStatus(unsigned char *pucSWA, unsigned
char *pucSWB);
Read the response status word of the PIN Verify command.
pucSWA[output]
Pointer to SWA.
pucSWB[output]
Pointer to SWB.
EMV_OK
Successful.
EMV_NO_DATA
There is no PIN verify command in this
transaction.
EMV_PARAM_ERR
The parameter is error.
None
8.4 EMVGetDebugInfo
Prototype
Function
Parameters
Return
Instruction
int EMVGetDebugInfo(int nExpAssistInfoLen, uchar
*paucAssistInfo, int *pnErrorCode)
Get the debug information.
nExpAssistInfoLen
RFU
[input]
paucAssistInfo[output] RFU
The error code.
pnErrorCode[output]
EMV_OK
Successful.
EMV_PARAM_ERR
The parameters are error.
1. This function is only used to get the debug information when a
transaction is failed.
2. So far, it only can be used to get the error code of offline data
authorization.
Value
Retrieval of Issuer Public Key Error
Suggestion
1
Authority Public Key Index is not present.
Check the card data
2
Issuer Public Key Certificate is not present.
Check the card data
3
Issuer Public key Exponent is not present.
Check the card data
4
The CAPK indicated by Authority Public Key
Index is not present in kernel.
Check if the CAPK indicated
by Authority Public Key Index
has been added in kernel by
PAX Computer Technology (Shenzhen) Co., Ltd.
40
PAX EMV Kernel API Programming Guide
EMVAddCAPK.
Issuer Public Key Certificate has a length
different from the length of the Certification
Authority Public Key Modulus
Recovered Data Header is not equal to '6A',
Check CAPK data and the card
data
Certificate Format is not equal to '02'
Check the card data
Recovered Data Trailer is not equal to 'BC'
Check the card data
9
The Length of Issuer Public Key recovered is not
equal to actual length
Check the card data
10
The hash result calculated is not equal to the hash
result recovered.
Check CAPK data and the card
data
Issuer Identifier does not match the leftmost 3-8
PAN digits
The issuer public key certificate has expired
Check the card data
Hash Algorithm Indicator or Issuer Public Key
Algorithm Indicator is not recognized
Check the card data
The CAPK is in the revocation list
Check the revocation list
5
6
7
8
11
12
13
14
Check the card data
Check the card data
Retrieval of ICC Public Key Error
21
ICC Public Key Certificate is not present.
Check the card data
22
ICC Public Key Exponent is not present.
Check the card data
23
ICC Public Key Certificate has a length different
from the length of the Issuer Public Key Modulus
obtained in the previous section.
Check the card data
24
Recovered Data Header is not equal to '6A',
Check the card data
25
Certificate Format
Check the card data
26
Recovered Data Trailer is not equal to 'BC'
Check the card data
27
The Length of ICC Public Key recovered is not
equal to actual length
Check the card data
is not equal to '04'
PAX Computer Technology (Shenzhen) Co., Ltd.
41
PAX EMV Kernel API Programming Guide
28
Static Data Authentication Tag List is present and
contains tags other than '82'
Check the card data
29
The hash result calculated is not equal to the hash
result recovered.
Check the card data
30
Recovered PAN is not the same as the Application
PAN read from the ICC.
Check the card data
31
The ICC public key certificate has expired
Check the card data
32
ICC Public Key Algorithm Indicator is not
recognized
Check the card data
SDA Verification Error
41
Signed Static Application Data is not present.
Check the card data
42
Signed Static Application Data has a length
different from the length of the Issuer Public Key
Modulus
Check the card data
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
45
Recovered Data Trailer is not equal to 'BC'
Check the card data
46
The Static Data Authentication Tag List is present
and contains tags other than '82'.
Check the card data
The hash result calculated is not equal to the hash
result recovered. EMV Book 2, 5.4 steps 7.
Check the card data
47
CDA Verification Error
61
Signed Dynamic Application Data is not present.
Check the card data
62
Signed Dynamic Application Data has a length
different from the length of the ICC Public Key
Modulus
Check the card data
63
Recovered Data Header is not equal to '6A'.
Check the card data
PAX Computer Technology (Shenzhen) Co., Ltd.
42
PAX EMV Kernel API Programming Guide
64
Signed Data Format is not equal to '05'
Check the card data
65
Recovered Data Trailer is not equal to 'BC'
Check the card data
66
Cryptogram Information Data retrieved from the
ICC Dynamic Data is not the same as the
Cryptogram Information Data obtained from the
response to the GENERATE AC command.
Check the card data
67
The hash result calculated is not equal to the hash
result recovered. EMV Book 2, 6.6.2 step 9.
Check the card data
68
The hash result calculated is not equal to the hash
result recovered. EMV Book 2, 6.6.2 step 12.
Check the card data
DDA Verification Error
The DDOL in the ICC does not include the
Unpredictable Number.
Check the card data
The ICC does not contain a DDOL and the
terminal does not contain a default DDOL.
The application shall set a
default DDOL into kernel.
The ICC does not contain a DDOL and the default
DDOL in the terminal does not include the
Unpredictable Number.
Check the default DDOL of
terminal.
DDOL related data filling error.
Check the data required in
DDOL
INTERNAL AUTHENTICATE command send or
receive error
Check the return code of
callback function to send the
command.
86
The TLV format of response data of INTERNAL
AUTHENTICATE is error.
Check the response data of the
command.
87
The response data of INTERNAL
AUTHENTICATE is not ‘80’ or ‘77’
Check the card data
88
There is no data in template ‘80’.
Check the card data
89
The length of ‘80’ is error.
Check the card data
81
82
83
84
85
PAX Computer Technology (Shenzhen) Co., Ltd.
43
PAX EMV Kernel API Programming Guide
There is no Signed Dynamic Application Data in
the response data of INTERNAL
AUTHENTICATE
Check the card data
The Signed Dynamic Application Data has a
length different from the length of the ICC Public
Key Modulus
Check the card data
92
Recovered Data Header is not equal to '6A'.
Check the card data
93
Signed Data Format is not equal to '05'
Check the card data
94
Recovered Data Trailer is not equal to 'BC'
Check the card data
95
The hash result calculated is not equal to the hash
result recovered. EMV Book 2, 6.5.2 step 7.
Check the card data
ICC Dynamic Data Length recovered is bigger
than 8
Check the card data
90
91
96
PAX Computer Technology (Shenzhen) Co., Ltd.
44
PAX EMV Kernel API Programming Guide
9 Appendix
A Return codes of the kernel and other macro definitions
（1） Return codes of the kernel
Return code
EMV_OK
ICC_RESET_ERR
ICC_CMD_ERR
ICC_BLOCK
EMV_RSP_ERR
EMV_APP_BLOCK
Value
0
-1
-2
-3
-4
-5
EMV_NO_APP
-6
EMV_USER_CANCEL
EMV_TIME_OUT
EMV_DATA_ERR
EMV_NOT_ACCEPT
EMV_DENIAL
EMV_KEY_EXP
EMV_NO_PINPAD
-7
-8
-9
-10
-11
-12
-13
EMV_NO_PASSWORD
-14
EMV_SUM_ERR
EMV_NOT_FOUND
EMV_NO_DATA
-15
-16
-17
PAX Computer Technology (Shenzhen) Co., Ltd.
Remark
Operation succeeds.
IC card reset failed.
IC card command failed.
IC card has been blocked.
IC card response code error.
The EMV application has been
blocked.
There is no EMV application
supported by terminal.
Transaction is canceled by user.
User operation timeout.
IC card data format error.
Transaction does not accept.
Transaction denied.
Key expired.
There is no pinpad or pinpad
does not work.
No PIN or user doesn’t want to
input PIN.
Check sum error of key.
The data element does not exist.
No value for the data element.
45
PAX EMV Kernel API Programming Guide
EMV_OVERFLOW
NO_TRANS_LOG
-18
-19
Memory overflow.
No transaction log.
RECORD_NOTEXIST
-20
LOGITEM_NOTEXIST
-21
ICC_RSP_6985
-22
EMV_FILE_ERR
-24
Specified log record does not
exist.
Specified item does not exist in
the log.
ICC response with 6985 when
GAC or GPO.
File error
EMV_PARAM_ERR
-30
Parameter error.
（2） Return codes or parameter of callback functions
Return code
Value
Remark
REFER_APPROVE
REFER_DENIAL
ONLINE_APPROV
0x01
0x02
0x00
Referral transaction approval.
Referral transaction denial.
Online transaction approval.
ONLINE_FAILED
ONLINE_REFER
ONLINE_DENIAL
ONLINE_ABORT
0x01
0x02
0x03
0x04
Online transaction failed.
Online transaction referral.
Online transaction denial.
Online transaction abort.
E
（3） Other macro definitions
Return code
MAX_APP_NUM
MAX_KEY_NUM
Value
100
64
7
MAX_REVOCLIST_NUM
30
PART_MATCH
0x00
FULL_MATCH
0x01
EMV_CASH
EMV_GOODS
EMV_SERVICE
EMV_CASHBACK
EMV_PED_TIMEOUT
0x01
0x02
0x04
0x08
0x01
PAX Computer Technology (Shenzhen) Co., Ltd.
Remark
Maximum number of application list.
Maximum number of public key
stored in CA public key list of kernel
for None Prolin platform.
Maximum number of public key
stored in CA public key list of kernel
for Prolin platform.
Maximum number of revoked Issuer
public key certification stored in
kernel.
Application selection matching flag
(partial matching).
Application selection matching flag
(full matching).
Transaction type (cash).
Transaction type (goods).
Transaction type (service).
Transaction type (cashback)
PCI verify offline PIN, PIN input
46
PAX EMV Kernel API Programming Guide
EMV_PED_WAIT
0x02
EMV_PED_FAIL
0x03
ATTR_N
ATTR_B
ATTR_CN
ATTR_AN
ATTR_ANS
0x04
0x08
0x10
0x20
0x40
AC_AAC
AC_TC
AC_ARQC
AC_AAC_HOST
0x00
0x01
0x02
0x03
timeout.
Corresponding PED return code:
PED_RET_ERR_INPUT_TIMEOUT
PCI verify offline PIN, PIN input
interval not enough.
Corresponding PED return code:
PED_RET_ERR_WAIT_INTERVAL
PCI verify offline PIN, other failure
Corresponding PED return code:
Other error codes
n: numeric
b: binary
cn: compressed numeric
an: alphabet and numeric
ans: alphabet, numeric and special
character
The AC type is AAC
The AC type is TC
The AC type is ARQC
The AC type is AAC since the online
result is ONLINE_DENIAL, (only for
VISA online)
All the function prototype and macros are defined in emvlib.h. So,
if the application includes the emvlib.h, it can call all the functions
and macros in the kernel.
B EMV_PARAM
EMV_PARAM
typedef struct{
unsigned char MerchName[256];
unsigned char MerchCateCode[2];
unsigned char MerchId[15];
unsigned char TermId[8];
unsigned char TerminalType;
unsigned char Capability[3];
unsigned char ExCapability[5];
unsigned char TransCurrExp;
unsigned char ReferCurrExp;
unsigned char ReferCurrCode[2];
unsigned char CountryCode[2];
PAX Computer Technology (Shenzhen) Co., Ltd.
47
PAX EMV Kernel API Programming Guide
unsigned char TransCurrCode[2];
unsigned long ReferCurrCon;
unsigned char TransType;
unsigned char ForceOnline;
unsigned char GetDataPIN;
unsigned char SurportPSESel;
}EMV_PARAM；
Name
Description
MerchName[256]
merchant name
(usually no need to set)
MerchCateCode[2]
merchant catalog code
(usually no need to set)
MerchInd[15]
merchant identification
(should be set)
TermInd[8]
terminal identification
(should to be set)
TerminalType
terminal type
Capability[3]
terminal capability
ExCapability[5]
terminal extended capability
CountryCode[2]
terminal country code (default : “\x08\x40”)
USA : “\x08\x40”
China :
“\x01\x56”
Korea : “\x04\x10”
Singapore : “\x07\x02”
TransCurrCode[2]
transaction currency code (default : “\x08\x40”)
USA: “\x08\x40”
China:
“\x01\x56”
Korea: “\x04\x10”
Singapore: “\x07\x02”
TransCurrExp
transaction currency exponent (default : 0x02)
For example : RMB, USD, HKD: 0x02
Korean WON: 0x00
ReferCurrCode[2]
reference currency code (default: “\x08\x40”)
ReferCurrExp
reference currency exponent (default: “0x02”)
ReferCurrCon
the conversion quotients between transaction currency and
reference currency (default : 1000)
(the exchange rate of transaction currency to reference currency
*1000)
TransType
set current transaction type
EMV_CASH or EMV_GOODS or EMV_SERVICE or
EMV_GOODS& EMV_CASHBACK or EMV_SERVICE&
EMV_CASHBACK
(refer to appendix A for macro definitions)
ForceOnline
merchant force online (1 means always online transaction)
PAX Computer Technology (Shenzhen) Co., Ltd.
48
PAX EMV Kernel API Programming Guide
GetDataPIN
read the IC card PIN retry counter before verify the PIN or not (1 :
read, 0 : not read, default : 1)
SurportPSESel
support PSE selection mode or not
(1 : support, 0 : not support, default : 1)
After kernel initialized, the parameters above had been set by
default value. The application can call the function
EMVGetParameter(EMV_PARAM *tParam) to get the default
value of the kernel, and modify some of them which need to or
must be modified, and then store them in the kernel by calling
EMVSetParameter(EMV_PARAM *tParam). The kernel will store
the modified parameters in the file system, so they are still valid
when the terminal power-on next time.
C 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 ExpLen;
unsigned char Exp[3];
unsigned char ExpDate[3];
unsigned char CheckSum[20];
}EMV_CAPK；
Name
Description
RID[5]
Registered Application Provider Identifier
KeyID
key index
HashInd
HASH arithmetic index
ArithInd
RSA arithmetic index
ModulLen
module length
Modul[248]
module
PAX Computer Technology (Shenzhen) Co., Ltd.
49
PAX EMV Kernel API Programming Guide
ExpLen
exponent length (1 or 3)
Exp[3]
exponent ("\x03" or "\x01\x00\x01")
ExpDate[3]
the expire date of the key (format : YYMMDD)
CheckSum[20]
key check sum
D EMV_APPLIST
EMV_APPLIST
typedef struct{
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 AcquierId[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.
PAX Computer Technology (Shenzhen) Co., Ltd.
50
PAX EMV Kernel API Programming Guide
If AppName[0]=0, terminal will prompt for the application label
or application prferred name.
If AppName is set with a 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 searchs application according to
the AID.)
AidLen
the length of AID
SelFlag
Application selection flag (partial matching PART_MATCH or
full matching FULL_MATCH)
(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)
(Refer to the risk management in EMV specification.)
FloorLimitCheck
For the online only terminal , check the floor limit or not (1:
check, 0 : not check，default:1)
RandTransSel
For the online only or offline only terminal , perform random
transaction selection or not (1: perform, 0 : not perform,
default : 1)
VelocityCheck
For the online only terminal , perform velocity check or not (1 :
perform, 0 not perform, default : 1)
FloorLimit
Floor limit (provided by acquirer)
(Refer to the risk management in EMV specification.)
Threshold
Threshold (provided by acquirer)
(Refer to the risk management in EMV specification)
Notes: If TargetPer=99 and Threshold=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))
(It must be set if acquirer provides it.)
ActDefault[6]
Terminal action code – default
(default : "\xD8\x40\x00\xA8\x00" (Visa140))
(It must be set if acquirer provides it.)
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
PAX Computer Technology (Shenzhen) Co., Ltd.
51
PAX EMV Kernel API Programming Guide
dDOL[0] is the length of DDOL, the others are the value of
DDOL.
(default : "\x03\x9F\x37\x04" (Visa140))
(It must be set if acquirer provides it.)
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))
(It must be set if acquirer provides it.)
Version[3]
application version
(It’s returned by ICC, so nothing needs to be done by
application)
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.)
E EMV_REVOCLIST
EMV_REVOCLIST
typedef struct
{
unsigned char
ucRid[5];
unsigned char
ucIndex;
unsigned char
ucCertSn[3];
}EMV_REVOCLIST;
NAME
DESCRIPTION
ucRid[5]
Registered Application.
ucIndex
Certification Authenticate Public Key Index.
ucCertSn
Issuer Certificate Serial Number.
F ELEMENT_ATTR
ELEMENT_ATTR
PAX Computer Technology (Shenzhen) Co., Ltd.
52
PAX EMV Kernel API Programming Guide
typedef struct{
int MaxLen;
unsigned short Tag;
unsigned short Attr;
unsigned short usTemplate[2];
unsigned char ucSource;
}ELEMENT_ATTR；
Name
Description
MaxLen
The maximum length for this tag.
Tag
Tag
Attr
The format of this data
#define ATTR_N
0x04
:numeric
#define ATTR_B
0x08
:binary
#define ATTR_CN
0x10
:compressed numeric
#define ATTR_AN
0x20
:alphabet and numric
#define ATTR_ANS
special character
0x40
:alphabet, numeric and
usTemplate
The template which this tag belongs, 0 if none
ucSource
The source of data element.
#define EMV_SRC_TM
1
/* Terminal */
#define EMV_SRC_ICC
0
/* ICC */
#define EMV_SRC_ISS
2
/* Issuer */
G APPLABEL_LIST
APPLABEL_LIST
PAX Computer Technology (Shenzhen) Co., Ltd.
53
PAX EMV Kernel API Programming Guide
typedef struct{
unsigned char aucAppPreName[17];
unsigned char aucAppLabel[17];
unsigned char aucIssDiscrData[244];
unsigned char aucAID[17];
unsigned char ucAidLen;
}APPLABEL_LIST；
Name
Description
aucAppPreName[17]
Application preferred name, ending with "\0"
aucAppLabel[17]
Application label, end with "\0"
aucIssDiscrData[244]
Data in template "BFOC" or "73", in the format of length+value,
where 1 byte for length and other bytes for value
aucAID[17]
AID of ICC
ucAidLen
Length of AID of ICC
H EMV_EXTMPARAM
EMV_EXTMPARAM
typedef struct{
unsigned char ucUseTermAIPFlg;
unsigned char aucTermAIP[2];
unsigned char ucBypassAllFlg;
} EMV_EXTMPARAM;
Name
Description
ucUseTermAIPFlg
0-TRM is based on AIP of card, 1-TRM is based on
AIP of Terminal, the default value is 0.
aucTermAIP[2]
The bit4 of byte1 decide whether force to perform TRM, “08
00 “- Yes; “00 00 “- No. Default value is “00 00”.
ucBypassAllFlg
Whether bypass all other pin when one pin has been
bypassed 1-Yes, 0-No
PAX Computer Technology (Shenzhen) Co., Ltd.
54
PAX EMV Kernel API Programming Guide
I EMV_MCKPARAM
EMV_MCKPARAM
typedef struct{
unsigned char ucBypassPin;
unsigned char ucBatchCapture;
void *pvoid;
}EMV_MCKPARAM;
Name
Description
ucBypassPin
0- Not supported，1-Supported. Default value is 1
ucBatchCapture
0- ODC, 1-BDC. Default value is BDC
(ODC: Online Data Capture; BDC: Batch Data Capture)
pvoid
J EMV_TMECPARAM
APPLABEL_LIST
typedef struct{
unsigned char ucECTSIFlg;
unsigned char ucECTSIVal;
unsigned char ucECTTLFlg;
unsigned long ulECTTLVal;
}EMV_TMECPARAM;
Name
Description
ucECTSIFlg
TSI flag is exit or not.
TSI-Electronic cash terminal support indicator.
ucECTSIVal
TSI value.
ucECTTLFlg
TTL flag is exit or not.
PAX Computer Technology (Shenzhen) Co., Ltd.
55
PAX EMV Kernel API Programming Guide
TTL-Electronic cash terminal transaction limit.
ulECTTLVal
TTLvalue
K APPLABEL_LIST
APPLABEL_LIST
typedef struct{
unsigned char aucAppPreName[17];
unsigned char aucAppLabel[17];
unsigned char aucIssDiscrData[244];
unsigned char aucAID[17];
unsigned char ucAidLen;
}APPLABEL_LIST；
Name
Description
aucAppPreName[17]
Application preferred name, ending with "\0"
aucAppLabel[17]
Application label, end with "\0"
aucIssDiscrData[244]
Data in template "BFOC" or "73", in the format of length+value,
where 1 byte for length and other bytes for value
aucAID[17]
AID of ICC
ucAidLen
Length of AID of ICC
L Clss_TransParam
Clss_TransParam
typedef struct{
unsigned long ulAmntAuth;
unsigned long ulAmntOther;
unsigned long ulTransNo;
unsigned char ucTransType;
unsigned char aucTransDate[4];
unsigned char aucTransTime[4];
PAX Computer Technology (Shenzhen) Co., Ltd.
56
PAX EMV Kernel API Programming Guide
}Clss_TransParam；
NAME
DESCRIPTION
ulAmntAuth
Authorize amount(unsigned long), for cash back, the amount
required to include the amount of ulAmntOther.
ulAmntOther
Other amount(unsigned long)
ulTransNo
Transaction Sequence Counter(4 BYTE)
ucTransType
Transaction type'9C', 0-Consumer/Services 1-Cash/Cash back
aucTransDate[4]
Transaction Date YYMMDD
aucTransTime[4]
Transaction time HHMMSS
M RSA_PINKEY
RSA_PINKEY
typedef struct
{
unsigned int
modlen;
unsigned char mod[256];
unsigned char exp[4];
unsigned char iccrandomlen;
unsigned char iccrandom[8];
}RSA_PINKEY;
NAME
DESCRIPTION
modlen
PIN encryption key modulus.
mod[256]
PIN encryption key modulus, high byte first, low byte after,
insufficient bit complement 0.
exp[4]
PIN encryption public key index, high byte first, low byte after,
insufficient bit complement 0.
iccrandomlen
The random number length obtained from card.
iccrandom[8]
The random number obtained from card.
PAX Computer Technology (Shenzhen) Co., Ltd.
57
PAX EMV Kernel API Programming Guide
N APDU_SEND
APDU_SEND
typedef struct
{
uchar
ushort
uchar
ushort
}APDU_SEND;
Command[4];
Lc;
DataIn[512];
Le;
NAME
DESCRIPTION
Command[4]
Command[] = {CLA, INS, P1, P2}.
Lc
The length of DataIn.
DataIn[512]
The data pointer which is sent to IC card.
Le
The expect length receive from IC card. The actual length is related
to the specific command, which can get from the parameter LenOut
in response structure APDU_RESP.
O APDU_RESP
APDU_RESP
typedef struct
{
ushort
uchar
uchar
uchar
}APDU_RESP;
LenOut;
DataOut[512];
SWA;
SWB;
NAME
DESCRIPTION
LenOut
The actual length receives from IC card.
DataOut[512]
The pointer receives from IC card.
SWA
Status word A.
SWB
Status word B.
PAX Computer Technology (Shenzhen) Co., Ltd.
58
PAX EMV Kernel API Programming
Guide
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf Linearized : No XMP Toolkit : XMP Core 5.4.0 Company : 百富计算机技术(深圳)有限公司 Source Modified : D:20150319095323 Title : PAX EMV Kernel API Programming Guide Creator : WangFen(王芬/深圳) Format : application/pdf Description : V 412_T1 Metadata Date : 2015:03:19 18:37+08:00 Create Date : 2015:03:19 18:36:08+08:00 Modify Date : 2015:03:19 18:37+08:00 Creator Tool : Acrobat PDFMaker 9.0 Word 版 Instance ID : uuid:4e8c610b-18c5-4676-92ef-f4d9702837ba Subject : 201 Document ID : uuid:7292c7de-685e-49bf-9740-c7cc0c650cc5 Headline : V 412_T1 Producer : Adobe PDF Library 9.0 Page Count : 74 PDF Version : 1.4 Author : WangFen(王芬/深圳)EXIF Metadata provided by EXIF.tools