Verix/Verix V EMV Module

Reference Manual

Verifone Part Number 23271, Revision T

Verix/Verix V EMV Module Reference Manual
© 2016 Verifone Systems
All rights reserved. No part of the contents of this document may be reproduced or transmitted in any form without the
written permission of Verifone Systems.
The information contained in this document is subject to change without notice. Although Verifone 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. This document, including without
limitation the examples and software programs, is supplied “As-Is.”

PINpad Verifone, the Verifone logo, Omni, VeriCentre, Verix, Verix V and ZonTalk are registered trademarks of Verifone. Other brand
names or trademarks associated with Verifone’s products and services are trademarks of Verifone Systems.
All other brand names and trademarks appearing in this manual are the property of their respective holders.

Comments? Please e-mail all comments on this document to your local Verifone Support Team.

Verifone Inc.
1-800-Verifone
www.verifone.com
Verifone Part Number 23271, Revision T
CONTENTS

PREFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Target Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Document Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Conventions, Acronyms and Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

CHAPTER 1
EMV Module EMV Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Architecture Advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Multi-Config Certification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

CHAPTER 2
Verix/Verix V EMV Data Table Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Module Data EST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Tables MVT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Sample Configuration Data Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Editing the EST/MVT Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Building EST Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Building MVT Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

CHAPTER 3
Verix/Verix V EMV Higher Level Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Module Function inVXEMVAPSCInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Calls inVXEMVAPTransInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
inVXEMVAPCardPresent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
inVXEMVAPCardInit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
inVXEMVAPCheckFallback() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
inVXEMVAPSelectApplication() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
inVXEMVAPPerformGPO() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
inVXEMVAPProcessAFL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
inVXEMVAPDataAuthentication() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
inVXEMVAPProcRisk() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
inVXEMVAPVerifyCardholder() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
inVXEMVAPFirstGenerateAC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
inVXEMVAPUseHostData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
inVXEMVAPGetCardConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
inVXEMVAPRemoveCard() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
inVXEMVAPKeyRevocation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
inVXEMVAPSetFunctionality() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
inVXEMVAPSetDisplayPINPrompt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
inVXEMVAPInitCardslot() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
inVXEMVAPCloseCardslot() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
inVXEMVAPKeyRollOver() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Lower Level Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
inVXEMVAPProcRestrictions() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
inVXEMVAPTermRisk() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 3

C ONTENTS

inVXEMVAPGetCAPK() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
inVXEMVAPSecondGenerateAC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
inVXEMVAPProcessScript() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
inVXEMVAPAuthIssuer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
inVXEMVAPAPDU() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
inVXEMVAPSetDefDDOL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
inVXEMVAPSetDefTDOL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
inVXEMVAPSetTACs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
inVXEMVAPSetROSParams() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
usVXEMVAPGetVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
vdSetCAPKExpiryCheck() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
vdSetConfigOption() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Data Object Collection Access Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
usEMVGetTxnStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
usEMVSetTxnStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
usEMVAddTLVToCollxn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
usEMVGetTLVFromColxn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
usEMVUpdateTLVInCollxn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
usEMVRetrieveTLVFromColxn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

CHAPTER 4
EMV Library getLastTxnAmt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Callback Function getTerminalParam() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Calls getCapkExp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
getUsrPin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
getXUsrPin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
usEMVDisplayErrorPrompt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
usEMVPerformSignature() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
usEMVPerformOnlinePIN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
usEMVIssAcqCVM(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
displayPINPrompt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
bIsMultipleOccurencesAllowed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
usGetBypassDecsn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
usGetTermAVN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
usGetExtAuthDecision() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
usGetPOSDecsn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
vdSelPreferredLang() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
usPinInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

CHAPTER 5
EMV Module bIsCardBlackListed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Callback Function bIsCSNValid(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Calls inGetPTermID() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
inMenuFunc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
usAmtEntryFunc(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
usCandListModify(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
vdPromptManager() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

CHAPTER 6
Building an EMV Setting the Transaction Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Application TVR/TSI Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Proprietary Data Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

4 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

C ONTENTS

Batch File Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Foreign Language Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Terminal-to-Host Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Terminal-to-Host Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Host-to-Terminal Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Failure to Go Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

CHAPTER 7
Implementation Transaction Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Online Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Notes on Online General Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

APPENDIX A
File Formats for . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Storing CAPKs

APPENDIX B
File Formats for . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Revoked Issuer PK
CSNs

APPENDIX C
Function Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
of the Callback
Function

APPENDIX D
Second . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Application
Version Number in
EST

APPENDIX E
Generic Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Returned by the
Library

APPENDIX F
Sample Files EST and MVT Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
ADK Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
XML Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

APPENDIX G
Relevant EMV Data Application Interchange Profile (AIP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Objects Application Usage Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Terminal Verification Results (TVR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Transaction Status Information (TSI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Terminal Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Additional Terminal Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Terminal Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Cardholder Verification Rule Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
VERIX/VERIX V EMV MODULE REFERENCE MANUAL 5
C ONTENTS

APPENDIX H
Terminal Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Code

APPENDIX I
EMV Configuration inVXEMVAPConvertConfigData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Data Update inVxEMVAPUpdateConfigData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
usModifyESTXML() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
usModifyMVTXML() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
usModifyKEYSXML() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
inVXEMVAPGetLastErrCode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
ICCKey File Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
ICCData File Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Backward Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

APPENDIX J
Sample Format Config File as Text Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Files ICCKeys.key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
ICCData File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Config File as XML Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
EST.XML File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Keys.XML File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
MVT.XML File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Config File as ADK File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
EMV_ApplicationsXML File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
EMV_Keys XML File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
EMV_Terminal XML File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

APPENDIX K
Configurable CDA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Mode for Online
Transactions

APPENDIX L
PIN Bypass and . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
PIN Cancel
Initiated from POS/
External Device

APPENDIX M
Double PIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Bypass Support

6 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

PREFACE

This is the Module Reference Manual for Vx EMV Module 8.0.0. EMV Module is a
suite that comprises of EMV Module, EMV Library and CardSlot Libraries. EMV
Module acts as an interface between the application and EMV Library. The
application developers can develop EMV based solutions using the EMV Module.
The Test Harness application is packaged along with the suite where application
developers can use it as a reference to create their own applications.
EMV Module supports EMV ICC card functionality on all Verix and Verix V-based
terminals. The function calls are platform independent, and are easily portable to
any Verix and Verix V-based terminals where the EMV Library is available.
The EMV Module supports entire EMV functionality.

Target This document is intended to the application developers who can develop the
Audience EMV based solutions.

Document The organization of the manual is as given in Table 1:

Organization Table 1 Document Organization
Chapter Description
Chapter 1, EMV Module Lists the EMV components and describes the
Architecture architecture.
Chapter 2, Verix/Verix V EMV Describes the EST and MVT data table structures,
Module Data Tables and provides the steps to edit and build the EST and
MVT files.
Chapter 3, Verix/Verix V EMV Describes all the EST related high level, low level
Module Function Calls and data object collection access functions calls.
Chapter 4, EMV Library Lists the EMV Library callback function calls.
Callback Function Calls
Chapter 5, EMV Module Describes the Verix/Verix V EMV Module functions
Callback Function Calls calls.
Chapter 6, Building an EMV Lists the steps to configure and build an EMV
Application application.
Chapter 7, Implementation Describes the procedure to implement the Verix/
Verix V EMV Module into a payment application.
Appendix A, File Formats for Describes the file formats for storing CAPKs.
Storing CAPKs
Appendix B, File Formats for Describes the file formats for revoked issuer PK
Revoked Issuer PK CSNs CAPKs.
Appendix C, Function Pointers Lists and explains the function pointers of the
of the Callback Function callback functions which are to be set with EMV
Library using the inVXEMVAPSetFunctionality() API.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 7

P REFACE
Conventions, Acronyms and Terminology

Table 1 Document Organization (continued)

Chapter Description
Appendix D, Second Describes the second application version number in
Application Version Number in EST.
EST
Appendix E, Generic Values Lists the library return values on the specific card
Returned by the Library condition.
Appendix F, Sample Files Provides sample EST and MVT.
Appendix G, Relevant EMV Provides relevant EMV data objects that control the
Data Objects transaction flow in the terminal.
Appendix H, Terminal Category Lists the Terminal Category Code values and their
Code descriptions.
Appendix I, EMV Configuration Describes the EMV Configuration data.
Data Update
Appendix J, Sample Format Provides sample ICCKeys.key and ICCData files.
Files
Appendix K, Configurable CDA Lists and describes the configurable CDA modes.
Mode for Online Transactions
Appendix L, PIN Bypass and Describes the PIN Bypass and PIN Cancel initiated
PIN Cancel Initiated from POS/ features.
External Device
Appendix M, Double PIN Describes the Double PIN Bypass feature.
Bypass Support

Conventions, The following conventions assist the reader to distinguish between different kinds
Acronyms and of information.
Terminology • The courier typeface is used for code entries, filenames, and anything that
might require typing at the DOS prompt or from the terminal keypad.
• The italic typeface indicates book title or emphasis.
• Text in blue indicates terms that are cross-referenced. When the pointer is
placed over these references the pointer changes to the finger pointer,
indicating a link. Click on the link to view the topic.

NOTE
Note points out interesting and useful information.

CAUTION
Caution points out potential programming problems.

8 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

P REFACE
Conventions, Acronyms and Terminology

Table 2 presents acronyms and their definitions.

Table 2 Acronym Definitions
Acronym Definition
AAC Application Authentication Cryptogram
AC Application Cryptogram
ACC Application Currency Code
AFL Application File Locator
AID Application IDentifier
AIP Application Interchange Profile
APDU Application Protocol Data Unit
API Application Programming Interface
ARC Authorization Response Code
ARQC Authorization Request Cryptogram
ATR Answer To Reset
AVN Application Version Number
BCD Binary Coded Decimal
CAPK Certification Authority Public Key
CDDA Combined Dynamic Data Authentication
CID Cryptogram Identifier
CRC Cyclic Redundancy Check
CSN Certificate Serial Number
CVM Cardholder Verification Method
DDA Dynamic Data Authentication
DDOL Dynamic Data authentication data Object List
DOC Data Object Collection
EMV EuroPay, MasterCard, Visa
EST EMV Card Scheme Table
GPO Get Processing Options
IC Integrated Circuit
ICC Integrated Circuit Card
ISO International Standards Organization
MVT General EMV Configuration Data Table
PAN Primary Account Number
PDOL Processing options Data Object List
PIN Personal Identification Number
POS Point Of Service or Sale
PSE Payment System Environment
RFU Reserved for Future Use
RID Registered application provider IDentifier
SCR Smartcard Reader
SC Device Smart Card Device
SDA Static Data Authentication

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 9

P REFACE
References

Table 2 Acronym Definitions (continued)

Acronym Definition
TAA Transaction Action Analysis
TAC Terminal Action Code
TC Transaction Certificate
TCC Transaction Currency Code
TDOL Transaction certificate Data Object List
TLV Tag Length Value
TRM Terminal Risk Management
TSI Transaction Status Information
TVR Terminal Verification Results
UI User Interface
VIS VISA ICC Specification

Table 3 defines terminology used throughout this document.

Table 3 Terminology
Term Definition
Command A message sent by the terminal to the ICC that initiates an action and
solicits a response from the ICC.
Cryptogram The result of a cryptographic operation.
Message A string of bytes is sent by the terminal to the card (or vice versa). The
message excludes transmission control characters.
Online Implies online to the issuer or to a host system representing the issuer.
Script A command or a string of commands transmitted by the issuer to the
terminal for the purpose of being sent serially to the ICC as commands.
Warm A reset of the ICC occurring when the reset signal (RST) is applied to the
Reset ICC with the clock and supply voltage lines active.

References The following documents are referenced in this manual:

1 EMV 4.3 Integrated Circuit Card Specifications for Payment Systems:
• Book 1 - ICC to Terminal Interface Requirements
• Book 2 - Security and Key Management
• Book 3 - Application Selection
• Book 4 - Cardholder, Attendant and Acquirer Interfaces Requirements

2 Verix/Verix V EMV Library Programmers Manual, VDN 23272

3 Verix/Verix V CardSlot Library Programmers Guide, VDN 23288
4 Verix/Verix V EMV Module Implementation Examples Guide, VDN 23270

10 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

CHAPTER 1

EMV Module Architecture

This chapter describes the high-level architecture of EMV solution offered by

Verifone for Verix and Verix V-based POS (Point Of Sale or Service) terminals.
EMV Module architecture is based on layers and is categorized into application,
EMV Module, EMV Library and CardSlot Libraries. These layers operate in
synergy to define a full-fledged EMV application.

Figure 1 EMV Module Architecture

EMV functionality is split into the EMV Library and EMV Module. The application-
related functionality is built in the application component. The CardSlot Library
defines additional layer abstraction in accessing smartcard readers and the
smartcards.
The CardSlot Library, EMV Library and EMV Module are built as libraries that can
be used by an application developer to build an EMV-based application.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 11

EMV M ODULE A RCHITECTURE
EMV Components

EMV The following are the EMV components:

Components
Application
This component is responsible for the following:
• Managing:
• UI
• Menu
• Displaying messages and prompts. Verix and Verix V-based terminals
support graphics display and different languages.
• Printing receipts, reports, etc.
• Maintaining the batch files.
• Communicating with the host involves online approvals, downloading
blacklisted card files, and settlements.
• Implementing other transaction types, for example, sale.
• Implementing issuer-specific and acquirer-specific features. For example,
sending the data to the host, getting the host data and copying it into
respective files. This data will be used by the EMV Module for the
transaction.
• Interacting with the EMV Module, EMV Library, CardSlot Library, and the
APIs provided by them.

EMV Module
• Defines and mandates EMV transaction flow.
• Defines table-driven approach for maintaining configurable parameters.
Refer to the Verix/Verix V EMV Module Data Tables chapter for more
details.
• Defines the function calls for performing an EMV transaction.
• Implements few library callback functions. Refer to the EMV Library
Callback Function Calls chapter for more details.
• Defines callback APIs that have to be implemented by the application.
Refer to the EMV Module Callback Function Calls chapter for more details.
• Interacts with the application to obtain required data (for example, risk
management data).
• Interacts with the EMV Library for various steps such as, application
selection, data authentication, etc.
• Defines default implementation that can be overridden by the application
for certain features (for example, blacklisted card support, split sales or
fallback processing).

12 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV M ODULE A RCHITECTURE
EMV Components

EMV Library
• Implements the EMV 4.3 specification.
• Defines standard function calls to develop EMV-based applications.
• Defines the callback functions that should be implemented by the
application. For example, to obtain the PIN from the user, the library calls
getUsrPin() API. This API should be implemented by the application to
handle the UI. Some EMV Library callback APIs are implemented by the
EMV Module.
• Maintains the data such as, TVR/TSI and DOLs by the EMV Library.
• Interacts with the CardSlot Library to communicate with smartcards.

NOTE EMV Library uses the following data files, DUP.dat, LT.dat, MAN.dat,
SAT.dat, TAG.dat, TEMT.dat during the transaction flow for parsing and
validating the card responses. It is mandated that these data files should be
downloaded to the terminal along with the libraries and kernel application binaries
to complete the transaction successfully. These data files are present under the
location C:\VerixAps\VXEMVAP\Resources folder.

CardSlot Library
• Provides a standard way to communicate with synchronous and
asynchronous cards.
• Defines the standard function calls for application to communicate with
smartcard reader and smartcards.
• Masks device-level functionality from the higher layers.
• Implements ISO and EMV standards to communicate with smartcards,
using the device-level drivers.

Advantages • The generic EMV Module need not be changed to implement issuer-specific
or acquirer-specific implementations.
• Applications can customize bank-specific and issuer-specific operations that
do not affect the EMV transaction flow.

For example, if there is a change in modem hardware or if TCP/IP is used to

communicate with the host, it is entirely handled by application component.
This does not affect other layers.
• Layer of separation helps to separately maintain a certified EMV Module and
EMV Library.
• Printing the receipt (For example, to print a logo or advertisement) can be
customized/localized to the application component.
• The application component can be further vertically layered, like the receipt
printing module, UI module, host communication module, etc. This promotes
re-using application components.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 13

EMV M ODULE A RCHITECTURE
Multi-Config Certification

Multi-Config EMVCo allows application providers to define, submit and test application kernels
Certification for multiple pre-defined configurations with the same test submission. While an
initial baseline configuration will be fully tested, all subsequent pre-defined
configurations will be subjected to limited incremental and regression testing.
EMVCo requires a checksum (4-20 characters) to be generated and associated
with each kernel configuration. The method or algorithm used to generate the
checksum is left to the discretion of the vendor, provided that, it results in a unique
value per kernel configuration. For example, the checksum could be derived from
only the configuration settings or the entire kernel. This value should be easily
retrievable in the application kernel for comparison. (A supported algorithm
example might be SHA-1.) This requirement is applicable to both static and
configurable kernels.
Following are the identified additional pre-requisites for an application provider to
obtain an approval for a multiple configuration kernel:
• The kernel should have configurable options.
• Changing the options should not require any re-compilation or linkage of the
application kernel code.
• The laboratory must be able to change the configuration easily.
• The vendor shall generate a unique checksum for each supported
configuration. The method or algorithm used for generating this checksum is
left to the discretion of the vendor, provided, it produces a unique value per
configuration. This checksum associated with the configuration in use should
be stored in the application kernel and should be easily retrievable for
examination.

14 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

CHAPTER 2

Verix/Verix V EMV Module Data Tables

The EMV Module is architected with a data driven approach. The EMV Module
provides a set of configurable data tables to support different combinations of
scheme data. The application specific data is stored in the EST (EMV Card
Scheme Table), and the transaction specific data is stored in the MVT (General
EMV Configuration data table).
EMV Module allows the EST.dat file to have multiple EST records configured for
the same RID, which contain different set of AIDs of the same scheme. These
multiple EST records are configured to the same or different MVT records based
on the requirement. This allows configuring different set of scheme specific values
to different set of AIDs of the same scheme.
A set of functions (refer to the Lower Level Function Calls and Editing the EST/
MVT Fields sections for more details) are also provided to enable the applications
to directly modify the fields of the table. This chapter discusses in detail about the
definition of the table and the way it is used by the application.

Data Table This section describes the EST and MVT structures.
Structures

EST The EST consists of EMV-related data that are categorized according to card
scheme (Visa, MasterCard, Amex, etc.). The EST can have multiple records with
each record specifying one supported card scheme. A single scheme may have
multiple records if the supported CAPK files are more than 15 or the supported
AIDs are more than 10 per scheme. All the records are read to find the matching
CAPK or supported AIDs. The scheme data should be stored in the EST.txt file
and should be converted to EST.dat data file using the gendata.exe File
Conversion Tool, which is available as a part of the package.

NOTE
Upon start-up, the EST record 0 is loaded. After selecting the application, the
appropriate EST record with the matching AID is loaded.

Refer to the Sample Files chapter for the EST.dat file that is packaged with the
EMV Module. The EST.txt file is built and the EST.dat data file is downloaded
to the terminal along with the application. The EMV Module loads the EST.dat
data file to the memory once the card is inserted. During application selection, the
data is read from the records of the EST.dat data file. The data of the matching
record is stored in an internal structure and used for the rest of the transaction.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 15

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

The data table consists of the following fields:

Table 4 EST Configuration
Change Length in Data
Fields Range Description
Yes/No Bytes Type
lnNbrOfTransactions No 4 long 0 Specifies the number of
transactions.
Note: lnNbrOfTransactions field is not used.

Scheme label Yes 34 char* 0-16 This field is used to identify the
bytes card scheme name. For example,
Visa, MasterCard etc.
Note: By default, record 1 is VISA, record 2 is MASTERCARD and record 3 is JCB.

RID Yes 12 char* 5 bytes This field is used to store the RID
(Registered application provider
Identifier) specific to the card
scheme name. For example, Visa
scheme RID is A000000003, and
MasterCard scheme RID is
A000000004. This is used to
perform any scheme specific data
handling/operations recommended
by the issuer/acquirer.

Note: The RID is specific to a scheme. If the user changes the default record from VISA to MASTERCARD, then
the RID should be changed to A000000004.
CAPK File Details
CAPK file1- CAPK file Yes The next set of fields, CAPK File
15 Index, CAPK file name and Expiry
Date, provide the data to access
the CAPK files used for data
authentication. These keys can be
quite large (up to 248 bytes), so the
keys are not stored in the EST.
User can configure up to 15 CAPK
files per scheme. This field has 3
sub fields.

Note: The CAPK File Index, CAPK file name and Expiry Date can be changed for the CAPK files that are
supported for the scheme. Only 15 CAPK files per record are allowed. Ensure that the CAPK Index is a
decimal equivalent of the CAPK File Index.

For example, if the CAPK Index in the card is 0xF8, then the field for CAPK Index in the EST will be 248.
CAPK file name should be the same as the one that is downloaded to the terminal.

16 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 4 EST Configuration (continued)

Change Length in Data
Fields Range Description
Yes/No Bytes Type
CAPK File Index1- 2 short 0-255 Defines CAPK File Index. This is
CAPK File Index15 the decimal value of the CAPK
Index (for example, if the CAPK
Index is EA, the value should be
specified in the EST.txt file as
234).

CAPK file name1- 32 char* 16 bytes Defines the file name exponent of
CAPK file name15 Certificate Authority. Refer to the
File Formats for Storing CAPKs
chapter for the format of the file.
Expiry Date1-Expiry 8 char* 3 bytes Defines the expiry date of the
Date15 CAPK file.
The expiry date is in dd/mm/yy
format.
Note: This is not a mandatory
field.
Application Identifier Details
Supported AID1- Yes 34 char* 5-16 Used to store the AID supported by
AID10 bytes the application. For example, for
the RID, A000000003, the
possible supported AIDs are
A0000000031010 and
A0000000032020.

Note:
• For example, for VISA scheme, one of the supported AIDs can be A0000000031010. Users can change as per
their requirements ensuring that the RID should be same as the first 5 bytes of the supported AID. Currently, 10
AIDs per record are supported.
• If the partial name selection is enabled, then no two AIDs can have the same partial name. For example,
A000000003101003 and A000000003101004 are not allowed.

PartialNameAllowedFl Yes 2 short 1 or 2 Specifies if the partial name

ag1-10 selection is allowed/not allowed for
the AID as mentioned below:
• If partial name selection is not
allowed for the AID, then the
partial name allowed flag
should be set to 1.
• If partial name selection is
supported for the AID, then the
partial name allowed flag
should be set to 2.

Note: A value of 1 indicates that partial name selection is not allowed for this AID. A value of 2 indicates that the
partial name selection is allowed for this AID.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 17

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 4 EST Configuration (continued)

Change Length in Data
Fields Range Description
Yes/No Bytes Type
Terminal Application Yes 6 char* 2 bytes Specifies the terminal version
Version Number1-10 number for this AID.
For example, 008C.

Note: This value can be changed by the user. But the user should ensure that the terminal version number and
the card version number matches.
SecondTerminal Yes 6 char* 2 bytes Used to store the second possible
Application Version terminal AVN for the AID.
Number1-10
Refer to Second Application Version Number in EST appendix for more details.

RecommendedAppNa Yes 16 char* 0-7 bytes Specifies the recommended

meAID1-10 application name. If the card does
not have an application label or
application preferred name for the
specified AID, then this field will be
used as an application name for
display and printing purposes. For
example, "MCI APP 01".

Note: This field is used for displaying the AID name for cardholder confirmation, only if the application label and
the application preferred name are not present in the card.

EMVTableRecord Yes 2 short Actual Specifies the number of the MVT

record record that specifies data for the
number scheme. For example, VISA
in the scheme record in EST might have
MVT a corresponding record in MVT at
record #3.

Note: This field cannot have a value of -1.

18 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 4 EST Configuration (continued)

Change Length in Data
Fields Range Description
Yes/No Bytes Type
CSN List file Yes 32 char* 0-15 The CSN file contains the revoked
bytes issuer certificate serial numbers
belonging to this scheme. This file
is used during data authentication.
It enables an issuer to revoke an
issuer public key before it expires
(refer to the EMV Specification
Documents listed in the
References section for more
details). If the issuer certificate
serial number appears in this file,
the data authentication fails (static
or dynamic). Appropriate TVR bits
are set during the data
authentication. The format of the
CSN file is described in Appendix
B. Refer to the Verix/Verix V EMV
Implementation Examples Guide
and bIsCSNValid() API for more
details on CSN Validation.
Note: This field is not used. The CSN file name will be constructed by the EMV Module from the finally selected
AID as [RID].CSN.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 19

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

MVT The MVT contains all general EMV-related configuration data. Each record
contains the information required by a particular entity. The entities involved are:
• card scheme
• card issuer
• card acquirer
• terminal
The terminal record specifies all data that is independent of scheme, issuer or
acquirer. The user can have different records for different schemes. In the
scheme-specific records, the user should fill in the scheme-specific details.
The data in each record can be specific to an issuer/acquirer or a scheme. The
records can be chained (each record has an index that can point to another
record). For example, an issuer may have just one entry point into the table but
can have several records chained together, one for each card scheme.

NOTE The MVT record number 0 is loaded on start-up. Once the application is selected,
the appropriate MVT as referenced in the EST is loaded. Refer to
EMVTableRecord field under EST for more details.

Table 5 consists of related fields:

Table 5 MVT Configuration
Lengt
Change Data
Fields h in Range Default Description
Yes/No Type
Bytes
Reference Indices
Scheme Yes 2 short Any value -1 Specifies the card scheme to be
Reference that used for which the scheme
correspond reference value is required. This
s to a record scheme number should match the
number in record number of the EST that
the MVT.h has the RID for the scheme.
file or -1. Then, the data for the transaction
is read from the scheme specific
record in the MVT file.
If this value is set to -1, then the
data is read from MVT record as
reference in the EST.

20 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 5 MVT Configuration (continued)

Lengt
Change Data
Fields h in Range Default Description
Yes/No Type
Bytes
Issuer Yes 2 short Any value -1 Specifies the card issuer to be
Reference that used for which the Issuer
correspond Reference value is needed. This
s to a record issuer reference number should
# in the match with the record number of
MVT.h file the EST that has the RID for the
or -1 scheme. Then, the data for the
transaction is read from the
scheme specific record in the
MVT file.
If this value is set to -1, then the
data is read from the MVT record
as referenced in the EST.
Risk Management Data
TRM Data No 2 short 0 or 1 1 This flag is used to enable or
Present disable the risk management
Flag parameters.
Specifies if the next four terminal
risk management parameters are
to be used in a transaction. If this
flag is set to 0, then the terminal
risk management parameters are
ignored. If the value is set to 1,
then the parameters are used
during the transaction.
Note: TRM Data Present flag cannot be changed since the terminal risk management parameters are required
to perform terminal risk management. Else, the values will be taken as 0.
EMV Floor Yes 4 long any value 1000 Specifies the limit set by the
Limit issuer/acquirer for the transaction
amount to be approved offline. If
the value of the current
transaction amount and the
previous transaction amount
exceeds or is equal to this value,
the terminal opts to obtain online
approval. If the transaction
amount is greater than or equal to
the floor limit value, the TVR byte
4, bit 8 is set during risk
management.
Random Yes 4 long any value 0 Specifies the threshold value for
Selection biased random selection which
Threshold should be of range 0 to less than
floor limit.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 21

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 5 MVT Configuration (continued)

Lengt
Change Data
Fields h in Range Default Description
Yes/No Type
Bytes
Target Yes 2 short 0-99 0 Specifies the random selection
Random percentage value. This is the
Selection target percentage used for
Percent random selection and is of range
0 to 99.
Maximum Yes 2 short 0-99 0 Specifies the maximum target
Target random selection value used for
Random biased random selection and is of
Selection range 0 to 99. This value should
Percent be greater than or equal to the
target percentage for random
online selection. This value is
used in conjunction with the
random number generated during
the transaction to decide on
selecting the online transaction
randomly.
Generic Data
Merchant Yes 2 short 0 or 1 1 Specifies the support for forced
Forced online transaction.
Online flag • If this flag is set to 0, the user
will not be prompted to force
the transaction to go online.
• If this flag is set to 1, the user
may be prompted to force the
transaction online.
Blacklisted Yes 2 short 0 or 1 0 Specifies the validation support
Card for blacklisted cards.
Support • If this flag is set to 1, the
Flag checking is performed for
blacklisted cards. However, the
user has to download a file with
the list of blacklisted cards.
• If this flag is set to 0, the
blacklisted card checking is not
performed.

22 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 5 MVT Configuration (continued)

Lengt
Change Data
Fields h in Range Default Description
Yes/No Type
Bytes

Terminal Action Codes

TAC Default Yes 11 char* 5 bytes D84000A80 Specifies the acquirer's conditions
0 that cause a transaction to be
rejected if it might have been
approved online, but the terminal
is unable to process the
transaction online.
Note: TAC Default is dependent on the application user.

TAC Denial Yes 11 char* 5 bytes 0010000000 Specifies the acquirer's conditions
that cause the denial of a
transaction without attempting to
go online.
Note: TAC Denial is dependent on the application user.

TAC Online Yes 11 char* 5 bytes D84000F80 Specifies the acquirer's conditions
0 that cause a transaction to go
online.
Based on the values mentioned in
the denial and online, the
transaction will go online, or
decline or approve. The values
mentioned are compared with the
TVR status and the Issuer Action
Code (IAC) values.
For example,
"D84000A800" "TAC
Default"
"0010000000" "TAC Denial"
"D84000F800" "TAC Online"
The terminal’s decision to
approve or decline a transaction
is sent as the result of the TAC.
Finally, the card decides on the
status of the transaction.
Note: TAC Online is dependent on the application user.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 23

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 5 MVT Configuration (continued)

Lengt
Change Data
Fields h in Range Default Description
Yes/No Type
Bytes

TDOL and DDOL

Default Yes 256 char* 0 - 128 9F1A02950 The TDOL (Terminal Data Object
TDOL bytes 59A039C01 List) is a data list that provides a
list of data objects to be used in
generating the TC hash value.
The default TDOL in the terminal
(specified by the payment
system) is used when the TDOL
is not present in the ICC. To
create the hash value, the
terminal can use the TDOL (if
present) or the default TDOL, to
create the appropriate value for
input to the hash algorithm. If the
default TDOL is used, Default
TDOL used bit is set to 1 in the
TVR.
For example,
"9F1A0295059A039C01"

Default Yes 256 char* 0 - 128 9F3704 DDOL (Dynamic data

DDOL bytes authentication Data Object List) is
used for constructing the
INTERNAL AUTHENTICATE
command. It is mandatory that
the DDOL contains the
unpredictable number generated
by the terminal (9F37 tag, 4 bytes
binary). In case the DDOL is not
present in the card, the default
DDOL will be used.
For example, "9F3704"

Generic Data
Fallback Yes 2 short 0 or 1 0 Specifies the value of the flag. If
allowed flag this is set to 1, fallback is allowed.

24 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 5 MVT Configuration (continued)

Lengt
Change Data
Fields h in Range Default Description
Yes/No Type
Bytes
Next Record Yes 2 short 0 or the -1 Specifies that there is another
appropriate record available for the same
record. scheme. The next record can
have values different from the
previous record. Refer to the
Figure 2 for more details. If this
value is 0, then the chain of
records is terminated. Application
users should ensure that there is
no infinite looping with the next
record.

Note: Ensure that the value of this field is not set to -1 and that the next record value does not have the same
record number as the record that has called it. For example, record 1 cannot have the next record value as
1. Also, if record 1 has the next record field as 2, record 2 should not have the next record field as 1.

EMV No 4 unsigned 0 0 This field is used by the EMV

Counter long Module to track the number of
transactions.

Note: EMV Counter should not be updated.

Application No 2 short 0 0 This field is used for auto

selection application selection.
flag
Terminal-related data
EMV Yes 6 char* 2 bytes 0840 Specifies the code of the country
Terminal where this terminal is being used.
Country For example, "0840"
Code

EMV Yes 6 char* 2 bytes 0840 Specifies the terminal currency

Terminal code in which the account is
Currency managed according to ISO 4217.
Code For example, "0840"

Terminal Yes 2 short 1 bytes 2 Specifies the implied position of

Currency the decimal point from the right of
Exponent the account represented
according to ISO 4217. For
example, 2

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 25

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 5 MVT Configuration (continued)

Lengt
Change Data
Fields h in Range Default Description
Yes/No Type
Bytes
EMV No 8 char* 3 bytes e0f8c8 Specifies the terminal capability
Terminal which is a three byte value that
Capabilities defines the capabilities of the
terminal like: card data input,
CVM and security capabilities of
the terminal. For example, E0 F8
C8. Refer to the Terminal
Capabilities section for more
details on the significance of each
bit.

Note: EMV Terminal Capabilities should not be changed as the EMV Module is certified based on the terminal
capabilities.

EMV Yes 12 char* 5 bytes F000F0A00 Specifies the data input and
Terminal 1 output capabilities of the terminal.
Additional This is a five bytes value which
Capabilities defines the additional capabilities
of the terminal. For example, F0
00 F0 F0 01. Refer to the
Additional Terminal Capabilities
section for more details on the
significance of each bit.

Note: EMV Terminal Additional Capabilities can be changed if the user wants to add support for advice.

EMV No 4 char* 1 byte 22 Specifies the environment of the

Terminal terminal, its communication
Type capability, and its operational
control. For example, "22" refers
to Attended, merchant controlled
POS terminal with offline and
online capabilities. Refer to the
EMV specifications listed in
References section for more
details.

Merchant Yes 6 char* 2 bytes 2701 Specifies the merchant category

Category code. This classifies the type of
Code business being done by the
merchant represented according
to ISO 8583:1993 for Card
Acceptor Business Code. This will
be provided by the issuer/acquirer
depending on the type of
business.

26 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 5 MVT Configuration (continued)

Lengt
Change Data
Fields h in Range Default Description
Yes/No Type
Bytes
Terminal Yes 4 char* 2 bytes R Specifies the Terminal Category
Category Code. This is a MasterCard
Code defined data element that assists
with Card Risk Management. This
field can use the values
mentioned in the Appendix H.

Modify Yes 2 short 0 or 1 0 This flag allows the application to

candidate modify the candidate list. Refer to
list the Verix/Verix V EMV
Implementation Examples Guide
for more details.
• If this value is set to 0, then
modifying the candidate list is
not allowed.
• If this value is set to 1, then
modifying the candidate list is
allowed.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 27

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 5 MVT Configuration (continued)

Lengt
Change Data
Fields h in Range Default Description
Yes/No Type
Bytes
Additional fields
RFU1 2 short 0 0 Note: If BIT8 RFU1 data is
SET, "128" (Decimal
equivalent for 0x0080)
should be entered in
MVT.txt file default
record.

28 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Table 5 MVT Configuration (continued)

Lengt
Change Data
Fields h in Range Default Description
Yes/No Type
Bytes
RFU2 2 short 0 0 RFU
RFU3 2 short 0 0 RFU
String RFU1 21 char* 0-21 RFU
characters
String RFU2 21 char* 0-21 RFU
characters
String RFU3 21 char* 0-21 RFU
characters
Note: The extra fields can be used by the application for customizing. The application can customize these fields
by calling the set() and get() functions provided in the EMV Module.
The fields with data types, ‘short’ should be set to ‘-1’ and ‘string’ should be set to ““““, if the application does
not want a value of a particular field in the MVT to be used.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 29

VERIX /VERIX V EMV M ODULE D ATA TABLES
Data Table Structures

Figure 2A - Chaining of Records

30 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE D ATA TABLES
Sample Configuration Data Files

Figure 2B - Chaining of Records

Sample Sample configuration data files are included as a part of the Test Harness
Configuration application. Refer to the Test Harness application for using the sample EST.dat
Data Files and MVT.dat files. The sample EST and MVT files are available in the following
location:
C:\VerixAps\VXEMVAP\Resources, where C:\VerixAps\VXEMVAP is the
default installation directory.

Editing the Verifone has provided a set of function calls for changing the EST/MVT structure
EST/MVT values. The selected EST/MVT structure variables can be modified by using the
Fields set() functions provided for each field. If the application needs to get a value for
a particular variable from the structure, use the get() functions provided in the
EMV Module.
For example,

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 31

VERIX /VERIX V EMV M ODULE D ATA TABLES
Editing the EST/MVT Fields

• to get the forced online flag from the loaded MVT structure, call
inGetMerchantForcedOnlineFlag() API.
• to set the forced online flag for the particular transaction, call
vdSetMerchantForcedOnlineFlag(flag) API.
The function prototypes are in the mvtfuncs.h and estfuncs.h include files.

Building EST Files Application developer can make required changes to EST.txt file. The EST.txt
file should be converted to EST.dat data file using gendata.exe File
Conversion Tool.
Execute the following statement to convert the text file to binary. It is assumed that
both gendata.exe and EST.txt file are available in the same location.

Usage - Verix platform:

gendata -q -s EST.txt

Usage - Verix V platform:

gendata -q -A EST.txt

After execution, EST.dat file is generated. This file should be downloaded along
with the application.

Building MVT Files Application developer can make required changes to MVT.txt file. The MVT.txt
file should be converted to MVT.dat file using gendata.exe File Conversion
Tool.
Execute the following statement to convert the text file to binary. It is assumed that
both gendata.exe and MVT.txt file are available in the same location.

Usage - Verix platform:

gendata -q -s MVT.txt

Usage - Verix V platform:

gendata -q -A MVT.txt

After execution, MVT.dat file is generated; this file should be downloaded along
with the application.

32 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

CHAPTER 3

Verix/Verix V EMV Module Function Calls

This chapter lists the APIs that can be used by an application to perform an EMV
based transaction. The required steps to perform an EMV transaction are
summarized in Figure 3.
A successful EMV transaction mandates that specific activities should be carried
out in a specific order by the application.
The amount entry should be implemented appropriately. The application should
examine the data object cryptogram information data (9F27 tag) to decide going
online, offline accepted, and offline declined.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 33

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS

DETECT CARD

SELECT APPLICATION

READ APPLICATION
DATA

DATA
AUTHENTICATION

PROCESSING
RESTRICTIONS

TRM

CARDHOLDER
VERIFICATION

TERMINAL ACTION
ANALYSIS

CARD GENERATES
FIRST CRYPTOGRAM

Y ONLINE PROCESSING AND

ONLINE
ISSUER AUTHENTICATION

TRANSACTION SCRIPT PROCESSING AND

COMPLETE SECOND CRYPTOGRAM

TERMINATE
CARDSLOT

Figure 3 Typical Transaction Flow

34 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

Higher Level All these function calls return SUCCESS (0) or an error condition (a non-zero
Function Calls value). The error values are defined in VXEMVAPDEF.H header file.
When new tagged EMV data is extracted from the card or assigned by the EMV
Module as configuration data, it is placed in a DOC data structure maintained by
the EMV Library. The application may modify some of the tagged data objects.
This can be performed using Data Object Collection Access Functions.
For some of these functions, a prompt manager function must be provided to
handle all required messages and error conditions. It is assumed that there is
usually one general prompt manager that handles all conditions required for an
EMV transaction. The prompt manager function always expects an integer
argument that corresponds to the prompt or error condition that needs to be
displayed.
The higher level function calls listed below are included in the VXEMVAP.H header
file.

inVXEMVAPSCInit()

This function opens the smartcard reader, initializes the EMV configuration data
and builds a list of supported applications from the Card Scheme data table. This
function also validates if the terminal is Vx700 and returns an error as EMV kernel
doesn’t support Vx700 terminal and external smartcard reader. This validation is
not supported for Vx UPT EMV Modules.

NOTE
inVXEMVAPSCInit() API should be called only once after the terminal reboot.

Prototype int inVXEMVAPSCInit(void);

Parameters None

Return Values
Success: 0

Failure: NO_AID_FOUND This value is returned when no AID was found

in the EST.

Vx700_NO_SUPPORT This value is returned if the terminal is Vx700.

EMV_FAILURE This value is returned if the loading of EST

records or any of the six mandatory tables
(DUP.DAT, LT.DAT, MAN.DAT, SAT.DAT,
TAG.DAT and TEMT.DAT) fails.

TERM_AID_CNT_EXEED This value is returned if the number of AIDs

configured in the EST file is greater than 99.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 35

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPTransInit()

This function takes the configuration data that is not specific to any particular card,
and places it in the DOC along with the date and time.

NOTE • inVXEMVAPTransInit() API should be called at the beginning of every

transaction. This API initializes the DOC maintained by the EMV kernel.
• inVXEMVAPTransInit() API will always consider the first record of the MVT as
the default record.

Prototype int inVXEMVAPTransInit(int inTerminalRecord, int (*inGetTermID)(char *));

Parameters
Input: inTerminalRecord Index of the MVT record that has to be
loaded. Default record (0) will be loaded if
the index is invalid.
inGetTermID() Changes the terminal ID as required by
the application. This is not a mandatory
parameter. To use the default system ID,
pass null value for this value.

Return Values
Success: 0

Failure: DATA_FILE_NOT_FOUND This value is returned when the MVT file is

not found.

INVALID_INDEX This value is returned when an invalid

index is passed to load the record from
MVT and also if the default record is not
available to load.

EMV_FAILURE This value is returned if the data addition

to the DOC is not successful.

36 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPCardPresent()

This function detects the presence of a smartcard in the smartcard reader.

Prototype int inVXEMVAPCardPresent(void);

Parameters None

Return Values
Success: 0 This value is returned when the card is
present.

Failure: SLOT_INITIALIZE_ERROR This value is returned when there is an

error in initializing the slot.

SLOT_SELECT_ERROR This value is returned when there is error

in selecting the slot.

EMV_FAILURE This value is returned when no card is

present.

CARD_REMOVED This value is returned when the card is

removed from the terminal in the middle
of the transaction.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 37

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPCardInit()

This API establishes communication with an EMV card and powers ON the card.
inVXEMVAPCardInit() API sets the appropriate terminal-to-card communication
parameters.
inVXEMVAPCardInit() API fails, if the card is a non-EMV card.

Prototype int inVXEMVAPCardInit(void);

Parameters None

Return Values
Success: 0 This value is returned when the initialization
is successful.

Failure: CHIP_ERROR This value is returned if the reader receives

an unsuccessful communication from the
card. For example, time-out has happened,
response from the card is not clear.

NO_ATR This value is returned when the reset of the

card is successful, but no ATR bytes were
returned.

EMV_FAILURE This value is returned when the

communication with the card is not
established successfully.

CARD_REMOVED This value is returned if the card is not

present.

38 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPCheckFallback()

This function applies to magnetic stripe transactions.

It examines the service code from the track 2 data. If the service code indicates
that the card has an EMV card on it and the Previous Chip Failed flag
(maintained by the EMV Module) is not set, an error condition is passed to the
prompt manager indicating to display the “Use Chip” message.
Also, an “Override Chip Requirement?” message is displayed asking the
user’s decision to continue the transaction. If no “Override Chip
Requirement” prompt is required, vdPromptManager parameter should be set to
null.
As the conditions for allowing fallback varies with the issuer/acquirer, the EMV
Module cannot define the conditions for fallback. As fallback is handled by the
application, it decides the conditions for allowing fallback.

Prototype int inVXEMVAPCheckFallback(char *szServiceCode,

int (*inOverrideChipScreen)(void),
void (*vdPromptManager)
(unsigned short inCondition));

Parameters
Input: inOverrideChipScreen() Displays a message. For example,
“Override Chip Requirement? Yes/
No”.
Returns success if the operator chooses
Yes (i.e., continue with the magnetic stripe
transaction).
szServiceCode Indicates whether to use a magnetic card/
chip card or not.
vdPromptManager() Displays the appropriate error messages.
incondition Parameter of vdPromptManager() function.
Refer to the usCandListModify() function for
more details.

Return Values
Success: 0 This value is returned if the terminal is
continuing with the magnetic stripe
transaction.

Failure: INVALID_PARAMETER This value is returned upon receiving an

invalid pointer as the function argument.

EMV_FAILURE This value is returned if no card is present.

NOTE Application can decide to support fallback or not by setting the Fallback
Allowed flag to either 1 or 0 in the MVT. Refer to the Verix/Verix V EMV Module
Data Tables chapter for more details on MVT.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 39

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPSelectApplication()

This function selects the EMV application and searches for the PSE file on the
card. If the file is found, the application is selected, else explicit option is used
(refer to the EMV documents listed in References section for more details). This
function uses the list of supported applications built in inVXEMVAPSCInit() API.
If the bit 8 of the short RFU1 field is set in the MVT default record, then
inVXEMVAPSelectApplication() API performs the application selection and
returns back to the application. In this scenario the application can fetch the finally
selected AID from the collection and can decide on further processing. If the
application wants to continue with the EMV processing, then the application can
invoke inVXEMVAPPerformGPO() API that is new.
If the bit 8 of the short RFU1 field is not set in the default record of MVT, then the
existing inVXEMVAPSelectApplication() API performs both application selection
and GPO.
If the selected application is Easy Entry (as defined in VIS), the Easy Entry
condition value is returned.

Prototype int inVXEMVAPSelectApplication(int inSelectMethodFlag,

int (*inMenuFunc)(char **, int),
void (*vdPromptManager)
(unsigned short incondition),
unsigned short(*usAmtEntryFunc)
(unsigned long *),
unsigned short(*usCandListModify)
(srAIDList *psrCandidateList));

Parameters
Input: inSelectMethodFlag The EMV auto application selection flag
value from the MVT should be passed. The
recommended value is 0.
Note: The value for this parameter is taken from
the default record of the MVT. This data is
not scheme specific.

40 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inMenuFunc A menu function is required to allow the operator

to select a card application when more than one
application is supported.
Should be of the format of:
int inMenuFunc(char **labels, int
num_labels)
where,
• labels is an array of pointers to strings
(names for the menu options).
• num_labels is the number of names on the
list.
It should return an integer corresponding to the
item selected from the array (starting from 1).
Refer to the EMV Module Callback Function Calls
chapter for more details.
Note: The application displays a menu from the
list of labels sent by the module. The
index of the selected label is returned
back to the module.
vdPromptManager() Displays the appropriate error message. Refer to
the sample program for details on default
implementation.
incondition Parameter of vdPromptManager() function. Refer
to the usCandListModify() function for more
details.
usAmtEntryFunc The amount entry function is required to obtain the
transaction amount and the account type from the
application. The EMV Module calls this function to
obtain the amount. To add the amount at a later
part of the transaction, it is the responsibility of the
application to obtain the amount and update it in
the collection. To update it in the collection, use
usEMVAddAmtToCollxn() API. The amount
entry function should prompt for, and return, the
sale amount, plus any cashback amount.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 41

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

usCandListModify Allows the application to modify the candidate list

to meet specific requirements. This function is
called only if the Modify candidate list flag
is enabled in the MVT (that is, set to 1). Refer to
the MVT for more details.
The application can use this function to exclude
some of the smartcards displayed or selected by
the EMV Module.
To exclude an AID, the application should set the
bExcludedAID field in the srAIDList structure
to 1. The EMV Module does not include AIDs with
the bExcludedAID field set to 1.
If the application does not need to modify the
candidate list, pass null value in this parameter of
the form:
unsigned short usCandListModify(srAIDList
*candidateList)
By default, the EMV Module includes all AIDs
supported by the card for application selection.
psrCandidateList This is the candidate list that has been filled by the
EMV Library for the PSE selection or list of AIDs
selection.

CAUTION
Extreme care should be taken while modifying the srAIDList structure.
Transaction may be affected if the candidate list is not handled carefully.

Return Values
Success: 0 This value is returned when the
application selection is successful.

Failure: CARD_REMOVED This value is returned when the card is

removed from the terminal in the middle
of the transaction.

CARD_BLOCKED This value is returned when the card

has been blocked by the issuer.

INVALID_PARAMETER This value is returned upon receiving an

invalid pointer as the function argument.

BAD_ICC_RESPONSE This value is returned if a bad response

is received from card.
For example, if the response contains
format and length errors.

CANDIDATELIST_EMPTY This value is returned if the matching

applications are not found. This value is
also returned when GPO returns the
status word as 0x6985 for the
application selected and there is no
more AID present in the candidate list.

42 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

CHIP_ERROR This value is returned if the reader

receives an unsuccessful
communication from the card.
For example, time-out has happened,
response from the card is not clear.

BAD_DATA_FORMAT This value is returned when the chip

data is invalid.
For example, if there are invalid tags in
the response.

TRANS_CANCELLED This value is returned when the user

cancels the transaction.

EASY_ENTRY_APPL This value is returned when the Easy

Entry application is selected.

E_EXPLICIT_SELEC_REQD This value is returned if the explicit

selection is required.

NOTE If the return value from inVXEMVAPSelectApplication() API is

“CANDIDATELIST_EMPTY”, the application can use the
usEMVGetAllAIDStatus() EMV Library API to know the status of AIDs. This
is required to find the blocked applications in the candidate list. Refer to the Verix/
Verix V EMV Library Programmers Manual for more details.

See also Generic Values Returned by the Library

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 43

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPPerformGPO()

This API initiates the application selected on the card by sending a GPO
command. This API should be called only if the short RFU1 field of default record
in MVT has the bit 8 set and the application wants to continue the EMV
transaction flow. If the bit 8 of the short RFU1 field in the MVT default record is set,
then inVXEMVAPSelectApplication() API only performs the application selection.
The prerequisite for this API is that the application should have called the
inVXEMVAPSelectApplication() API and the MVT's default record has bit 8 set for
the short RFU1 field.
This API performs the following:
1 If the PDOL has requested for amount or account type, then invoke
usAmtEntryFunc() application callback API to accept the same.
2 Initiate the application by sending the GPO command.
3 If the card has returned the status word as 0x6985 (SW1,SW2) for the GPO
command, then this API performs the final application selection after
removing the specific AID from the candidate list for which GPO command
has returned the status word as 0x6985. After successful final application
selection, GPO is performed by the EMV Module.

Prototype inVXEMVAPPerformGPO (void);

Parameters
None

Return Values
Success: EMV_SUCCESS This value is returned when get processing
options are completed successfully.

Failure: CARD_REMOVED This value is returned if the card is removed

in between a transaction.

CARD_BLOCKED This value is returned if the card returns the

status word 0x6A81 (card blocked) for GPO
command.

APPL_BLOCKED This value is returned if the application in the

ICC is blocked.

CHIP_ERROR This value is returned if the reader receives

an unsuccessful communication from the
card. For example, if time-out has occurred
or response from the card is not clear.

CANDIDATELIST_EMPTY This value is returned when the candidate

list does not have any applications that can
be selected after the GPO has returned the
status word as 0x6985.

44 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

TRANS_CANCELLED This value is returned when the application

has canceled the transaction during the
cardholder confirmation phase of the
application selection.

EMV_FAILURE This value is returned in cases other than

the one listed above.

EASY_ENTRY_APPL This value is returned if the application

selected is an easy entry application.

NOTE If the application invokes inVXEMVAPPerformGPO() API even after the failure
of inVXEMVAPSelectApplication() API, then the EMV kernel sends the
GPO command that results in a failure.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 45

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPProcessAFL()

This function obtains the AFL from the DOC and uses it to locate the files
associated with the selected card application. This function then reads all
appropriate records from these files, extracts the data, and places it in the DOC.
This function checks for the presence of mandatory data objects. It also ensures
that a data object does not occur more than once. It also builds up the
concatenated static data required for data authentication (refer to the EMV
specifications listed in References section for more details).

Prototype int inVXEMVAPProcessAFL(void);

Parameters None

Return Values
Success: 0 This value is returned if the read
application data command is successful.

Failure: BAD_ICC_RESPONSE This value is returned if a bad response is

received from the card.
For example, if the response contains
format and length errors.

CHIP_ERROR This value is returned if the reader receives

an unsuccessful communication from the
card.
For example, time-out has happened,
response from the card is not clear or if the
card is not present.

EMV_FAILURE This value is returned if the read data is

failed.

See also Generic Values Returned by the Library

46 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPDataAuthentication()

This function obtains the relevant cryptographic data from the DOC and uses it to
perform SDA (Static Data Authentication), DDA (Dynamic Data Authentication), or
CDDA (Combined DDA/AC), as required, as described in the EMV specifications
listed in References section. inVXEMVAPDataAuthentication() API obtains the
relevant CAPK from the appropriate configuration file (refer to the File Formats for
Storing CAPKs chapter for more details) and checks the issuer public key
certificate serial number against the list of revoked serial numbers stored in the file
(refer to the File Formats for Revoked Issuer PK CSNs chapter for more details). It
appropriately adjusts the values of the TVR and TSI in the DOC.
If the card does not support SDA, DDA or CDDA,
inVXEMVAPDataAuthentication() API returns SUCCESS, and set the TVR bits for
Data authentication not performed.
inVXEMVAPDataAuthentication() API invokes the following library callback
functions:
• getCapkExp()
• getTerminalParam()
• usEMVDisplayErrorPrompt()

Prototype int inVXEMVAPDataAuthentication(unsigned short (*bIsCSNValid)

(unsigned char *CardCSN));

Parameters
Input: bIsCSNValid() Checks the CSN details in the CSN List (a field in
the EST) file.
This function should be implemented to accomplish
validation, otherwise pass a null value.
CardCSN EMV Library fills the CardCSN parameter with the
card serial number.

Return Values
Success: 0 This value is returned if the SDA, DDA, or CDDA is
successfully performed.

Failure: CHIP_ERROR This value is returned if the reader receives an

unsuccessful communication from the card.
For example, time-out has happened, or response
from the card is not clear or if the card is not present.

EMV_FAILURE This value is returned if an abnormal error is

encountered while performing Data Authentication.
For example, if the mandatory data is missing in the
response field of Internal Authenticate command, in
case of DDA.

See also Generic Values Returned by the Library

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 47
VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPProcRisk()

This function obtains the relevant data from the DOC (which should include the
transaction amount) and uses it to perform both the processing restrictions and
Terminal Risk Management procedures according to the EMV specifications listed
in References section. This function appropriately adjusts the values of the TVR
and TSI in the DOC.
The EMV kernel always performs Terminal Risk Management, irrespective of the
AIP bit setting for ‘TRM to be performed’ in the card.

NOTE
inVXEMVAPProcRisk() API should be called after amount has been entered.

inVXEMVAPProcRisk() API invokes the getLastTxnAmt() library callback function.

Prototype int inVXEMVAPProcRisk(EMVBoolean (*bIsCardBlackListed)(unsigned char *,

unsigned short, unsigned char *,unsigned short));

Parameters
Input: bIsCardBlackListed() Checks the card details in the exception file.
This function should be implemented to
accomplish validation, else pass a null value.

Return Values
Success: 0

Failure: EMV_FAILURE This value is returned if Terminal Risk

Management is unsuccessful.

See also Generic Values Returned by the Library

48 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPVerifyCardholder()

This function obtains the relevant data from the DOC (mainly, the CVM list, refer to
the Cardholder Verification Rule Format section for more details) and performs
cardholder verification (as described in the EMV specifications listed in
References section). This function then appropriately adjusts the values of the
TVR and TSI in the DOC. If the card does not support cardholder verification, this
function returns SUCCESS and the Cardholder Verification Performed
bit is not set in the TSI.
This function invokes the following library callback functions:
• getCapkExp()
• getUsrPin()
• getXUsrPin()
• usEMVDisplayErrorPrompt()
• usEMVPerformSignature()
• usEMVPerformOnlinePIN()
• usEMVIssAcqCVM()
• usGetBypassDecsn()
• usGetPOSDecsn()
For Vx UPT EMV Modules, usGetBypassDecsn() and usGetPOSDecsn()
callback functions are not invoked during PIN entry.
As part of cardholder verification:
• The EMV kernel supports POS/External Device initiated PIN Bypass and PIN
Cancel during a secure PIN Entry. Refer to Appendix L for more details
regarding this feature. This feature is not supported for Vx UPT EMV Modules.
• The EMV kernel supports double PIN bypass during secure PIN Entry. Refer
to Appendix M for more details regarding this feature. This feature is not
supported for Vx UPT EMV Modules.
• The EMV kernel is enhanced such that the application can enable or disable
the backspace key press during the PIN entry feature, that is if the backspace
key is pressed on the PIN Entry prompt and if the number of PIN digits entered
is zero, then the EMV kernel will return
E_USR_BACKSPACE_KEY_PRESSED value back to the application, so that
the application can go back to the previously prompted menu. Refer to
usEMVSetBackSpaceKeyFnlty() API in Verix/Verix V EMV Library
Programmers Manual for more details. This API need not be called for Vx UPT
EMV Modules.
• The EMV kernel is enhanced to provide an option to the application to get the
number of PIN digits entered during the PIN entry process so that the
application can provide this to the ECR/POS to display the respective number

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 49

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

of echo characters on its display. Refer to usEMVGetEchoCount() API in

Verix/Verix V EMV Library Programmers Manual for more details. This feature
is not supported for Vx UPT EMV Modules.

Prototype int inVXEMVAPVerifyCardholder(unsigned short (*bIsCSNValid)

(unsigned char *CardCSN));

Parameters
Input: bIsCSNValid() Checks the CSN details in the CSN List (a
field in the EST) file.
This function should be implemented to
accomplish validation, otherwise pass a null
value.
CardCSN EMV Library fills the CardCSN parameter with
the card serial number.

Return Values
Success: 0 This value is returned if the cardholder
verification is successful.

Failure: CHIP_ERROR This value is returned if the reader receives an

unsuccessful communication from the card.
For example, time-out has happened,
response from the card is not clear or if the
card is not present.

BAD_DATA_FORMAT This value is returned if a bad data is returned

from card during a PIN-related operation.
For example, if there are invalid tags in the
response.

E_USR_BACKSPACE_K This value is returned by the application from

EY_PRESSED the callback function to the kernel when
backspace key is pressed with no PIN entered.
When the kernel receives this return value, it
returns the control to the application. In such a
scenario any TVR/TSI bits set during the PIN
entry will not be reset by the kernel.

See also Generic Values Returned by the Library

50 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPFirstGenerateAC()

This function enforces the merchant forced online option and performs TAA to
decide the type of cryptogram to request (refer to the EMV specification listed in
the References section for more details). It then updates the ARC tag based on
the TAA result.
The EMV Module updates the Cryptogram Information Data (CID, 9F27 tag) in
the DOC. The application will check the CID to decide on how to proceed with the
transaction (refer to the EMV specification listed in References section for more
details). For example, if the transaction is to be declined offline.
inVXEMVAPFirstGenerateAC() function invokes the getTerminalParam() library
callback function.
If CDDA is supported, it is performed as a part of Generate AC.

Prototype int inVXEMVAPFirstGenerateAC(int inTerminalDecision);

Parameters
Input: inTerminalDecision Enables the application to force the
transaction online or offline, or decline the
transaction. If the merchant is suspicious, they
can force online and contact the host for
approval. Valid values are:
• FORCED_ONLINE: enabled only when the
Merchant Forced Online flag is set in
the MVT for that particular scheme. If the
flag is disabled in the MVT, the merchant
cannot force the transaction online.
• FORCED_DECLINE: the merchant can
force decline the transaction using this
value.
• 0: no decision.

Return Values
Success: TC, AAC or ARQC is returned.

Failure: CHIP_ERROR This value is returned when the card is

removed from the terminal in the middle of
the transaction.

BAD_DATA_FORMAT This value is returned when the tags are

invalid or used improper template.
For example, if there are invalid tags in the
response.

EMV_FAILURE This value is returned when any discrepancy

occurs while building DOLs.

E_CDA_ARQC_FAILED This value is returned if CDA has failed after

first GenerateAC and the card has returned
ARQC.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 51

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

See also Generic Values Returned by the Library

inVXEMVAPUseHostData()

This function obtains the data returned by the host after a transaction has gone
online and uses the data to perform the steps required to complete the
transaction. This always involves performing the Second Generate AC and can
also involve issuer authentication and issuer script processing, depending on the
data returned by the host and the processes supported by the card (refer to the
EMV specifications listed in References section for more details).
This function appropriately adjusts the values of the TVR and TSI in the DOC. The
application should check the CID to decide on how to complete the transaction.
All scripts returned by the host are written to the buffers.

NOTE If the card response for the Second Generate AC command is not valid, then the
EMV kernel terminates the transaction. But the 0x9F26 tag present in the DOC
will have the value received for the First Generate AC command response.

Prototype int inVXEMVAPUseHostData(int inHostDecision, byte *pIssuerScriptResults,

int *pinNumScripts, byte* pScript71, ushort usScript71Len, byte*
pScript72, ushort usScript72Len);

Parameters
Input: inHostDecision Host decision. Valid values are:
• HOST_AUTHORISED
• HOST_DECLINED
• FAILED_TO_CONNECT

pIssuerScriptResults Buffer to contain issuer script results (refer to

the EMV specifications listed in References
section for more details). Minimum size is 5
bytes for every script processed.
pinNumScripts Pointer to the integer to contain number of
scripts processed.
pScript71 Buffer to contain script 71.
usScript71Len Length of script 71.
pScript72 Buffer to contain script 72.
usScript72Len Length of script 72.

Return Values
Success: 0 This value is returned when the transaction is
successfully completed.

52 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

Failure: CHIP_ERROR This value is returned if the reader receives

an unsuccessful communication from the
card.
For example, time-out has happened,
response from the card is not clear or when
the card is removed from the terminal.

BAD_DATA_FORMAT This value is returned when the tags are

invalid.
For example, if there are invalid tags in the
response.

EMV_FAILURE This value is returned if invalid data is

received from the card.

INVALID_PARAMETER This value is returned upon receiving an

invalid pointer as the function argument.

See also Generic Values Returned by the Library

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 53

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPGetCardConfig()

This API is called by the application to load an MVT record that is different from
the one that gets loaded after the final application selection. At least one of the
function arguments should be -1.
This function performs the following:
1 If the function argument inAquirerNumber is equal to x, where x is not
equal to -1 and inIssuerNumber is equal to -1, then it loads the MVT
record which has the issuer reference value as x. This forms the base record.
Then it perform the steps from a to c mentioned below.
2 If the function argument inIssuerNumber is equal to y, where y is not equal
to -1 and inAquirerNumber is equal to -1, then it loads the MVT record
which has the scheme reference value as y. This forms the base record.
Then it performs the steps from a to c as mentioned below.
a Checks if the newly loaded MVT record has MVT chaining enabled with a
value other than -1 for the inNextRecord field. If chaining is enabled, the
terminal loads the chained MVT record and updates the base record which
has default values as 0 or -1 or "" (NULL string) with the valid values
present in the chained record.
b Loads the MVT record pointed by the EST record, which has the finally
selected AID. Updates the latest base record for the fields with default
values as 0 or -1 or "" (NULL string) from the newly loaded MVT record,
which has valid values present. Check for the chaining of the record. If
chaining is available, load the chained record and update the latest base
record for the fields with default values as 0 or -1 or "" (NULL string) from
the newly loaded MVT record which has valid values present.
c Loads the default record present in MVT. Updates the latest base record
for the fields with default values as 0 or -1 or "" (NULL string) from the
newly loaded MVT record which has valid values present.
3 If both the function arguments are greater than 0 or are equal to -1, only then
steps b and c are performed.

Prototype int inVXEMVAPGetCardConfig(int inIssuerNumber, int inAcquirerNumber);

Parameters
Input: inIssuerNumber Maps to the field "Scheme Reference" in MVT.
inAquirerNumber Maps to the field "Issuer Reference" in MVT.

Return Values
Success: 0 This value is returned upon successful execution of
this API.

Failure: EMV_FAILURE This value is returned while updating a tag to the

collection fails.

54 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPRemoveCard()

This function displays an appropriate message, prompting card removal when the
transaction is complete.

Prototype int inVXEMVAPRemoveCard(void (*vdPromptManager)

(unsigned short inCondition));

Parameters
Input: vdPromptManager() Displays the “Remove Card” message.
incondition Parameter of vdPromptManager() function.
Refer to the usCandListModify() function for
more details.

Return Values
Success: 0 This value is returned when the message is
successfully displayed.

Failure: INVALID_PARAMETER This value is returned upon receiving an invalid

pointer as the function argument.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 55

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPKeyRevocation()

This API reads each record of the EST.dat file and validates the CAPK expiry
date field with the terminal date. If the terminal date is greater than the CAPK
expiry date field, then the fields of that CAPK file (Index, File name and Expiry
date) are updated with null values and are saved into the EST.dat file. This API
will also remove this particular CAPK from the terminal if it is present, and the
terminal will be rebooted.

NOTE
Applications following XML approach of configuration need not call
inVXEMVAPKeyRevocation() API.

For example, in one of the EST records, if there is a CAPK with the following
fields:
248, /* "CAPK Index" */
"A000000004.F8", /* "CAPK File" */
"311206", /* "CAPK Expiry Date" */
and if the system date is the current date (090807), then the Key revocation API
will do the revocation process and update the above three fields to the following
values,
256, /* "CAPK Index" */
"", /* "CAPK File" */
"", /* "CAPK Expiry Date" */
and saves back in the EST.dat file.
The terminal will reboot after updating the CAPK fields to achieve contiguous
memory locations.

Prototype int inVXEMVAPKeyRevocation(void);

Parameters
None

Return Value:
Success: VS_SUCCESS This value is returned when there is no CAPK
to revocate based on expiry date in the EST
file. It reboots the terminal when it finds an
expired CAPK field in the EST after updating
and saving the fields with null values, and also
removes the CAPK files from the terminal
RAM.

Failure: None

56 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPSetFunctionality()

This function is used to set the function pointer of EMV Library callback functions
mentioned in EMV Library Callback Function Calls chapter. This API is called
during application initialization.
The application should call inVXEMVAPSetFunctionality() API only if any specific
functionality is required. The EMV Module will have default implementations for
each of the callback functions. However, for handling any specific application
functionality, the application should be changed to include a call to the
inVXEMVAPSetFunctionality() API with appropriate codes. The application should
also ensure that the correct functions are assigned to each of the codes that are
used.

Prototype unsigned short inVxEMVAPSetFunctionality(unsigned short usCode, (void

*)fnPtrSet);

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 57

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

Parameters
Input: usCode This value specifies the functionality for
which the API is being used.
Valid values are:
• GET_LAST_TXN_AMT
• GET_TERMINAL_PARAMETER
• GET_CAPK_DATA
• GET_USER_PIN
• IS_CSN_VALID
• DISPLAY_ERROR_PROMPT
• PERFORM_SIGNATURE
• PERFORM_ONLINE_PIN
• PERFORM_ISS_ACQ_CVM
• IS_CARD_BLACKLISTED
• IS_PARTIAL_SELECT_ALLOWED
• PERFORM_LANGUAGE_SEL
• GET_TERMINAL_AVN
• GET_TXN_AMT
• Get_EXT_AUTH_DECISION
• GET_POS_CVM_DECISION
• GET_BYPASS_DECISION
• GET_PIN_INFO
• GET_X_USER_PIN
Refer to the Function Pointers of the
Callback Function appendix for the
codes and associated functions.
fnPtrSet Pointer to the function that has been
implemented in the application.

Return Values
Success: EMV_SUCCESS This value is returned if the function
code is set correctly.

Failure: E_WRONG_FUNCTION_CODE This value is returned if the function

code is set incorrect. If the kernel
returns this error for
inVXEMVAPSetFunctionality() API,
then application decides on the further
action.

58 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPSetDisplayPINPrompt()

This function is used to set the function pointer of the EMV Library callback
function displayPINPrompt(). This API should be called before calling
inVXEMVAPVerifyCardholder() API.

Prototype int inVXEMVAPSetDisplayPINPrompt( void (*fptr) (void) );

Parameters
Input: fptr Pointer to displayPINPrompt() API in the application.

Return Values
Success: SUCCESS This value is returned if the function code is set
correctly.

NOTE
This API is not applicable for Vx UPT EMV Modules.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 59

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPInitCardslot()

This function is used to open the primary smartcard reader.

Prototype int inVXEMVAPInitCardslot(void);

Parameters
None

Return Values
Success: SUCCESS This value is returned if the CardSlot
initialization is successful.

Failure: FAILURE This value is returned when the card

initialization failed.

Backward Compatibility
All applications using Vx EMV Module should call inVXEMVAPInitCardslot() API
to open the CardSlot, as inVXEMVAPSCInit() API does not open the CardSlot.

NOTE The application has an option to:

• open the smartcard reader at the terminal reboot and keep it open till the
terminal is powered OFF or
• open the smartcard reader and close the smartcard device only while
performing an ICC transaction to conserve the battery power.

60 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPCloseCardslot()

This function is used to close the primary smartcard reader.

Prototype int inVXEMVAPCloseCardslot(void);

Parameters
None

Return Values
Success: SUCCESS This value is returned if the CardSlot is closed
successfully.

Failure: FAILURE This value is returned if the CardSlot is not

closed.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 61

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Higher Level Function Calls

inVXEMVAPKeyRollOver()

The key rollover functionality is replaced from inVXEMVAPSCInit() API to

newly added inVXEMVAPKeyRollOver() API. Applications that require key
rollover feature can invoke inVXEMVAPKeyRollOver() API.
The kernel maintains an internal list of all the CAPK file names specified in the
EST. If the EST file is partially downloaded to the terminal with some CAPK
entries removed, then this function validates the CAPK entries with its internal
stored list and identifies the CAPKs removed from the partially downloaded EST
file and removes the same from the terminal's memory. The list of CAPK file
names is stored in Filelist.dat file.

NOTE
Applications following XML approach of configuration need not call
inVXEMVAPKeyRollOver() API.

Prototype int inVXEMVAPKeyRollOver(void);

Parameters
None

Return Values
Success: SUCCESS If the key rollover is performed successfully.

Failure: FAILURE If there is an error occurred during the key

rollover.

Backward Compatibility
No change is required for applications that do not require key rollover functionality.
Applications that need to use the key rollover functionality should call
inVXEMVAPKeyRollOver() API separately.

62 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

Lower Level This section lists and describes the function calls which are not mandatory while
Function Calls implementing EMV transaction. Whereas these function calls can be used to
implement EMV transaction for more flexibility.
For example, when an application does not require all of the EMV functionality or
where customer-specific card commands should be added.
All of these functions return SUCCESS (0) or an error condition (a non-zero
value). All error conditions are defined in VXEMVAPDEF.H header file.

inVXEMVAPProcRestrictions()

This function obtains the relevant data from the DOC and uses it to perform the
processing restrictions (as described in the EMV specifications listed in
References section). It also appropriately adjusts the value of the TVR in the
DOC.

Prototype int inVXEMVAPProcRestrictions(void);

Parameters
None

Return Values
Success: 0 This value is returned if the processing restrictions are
successful.

Failure: None

See also Generic Values Returned by the Library

As a part of processing restrictions:
• the terminal application version number is checked against the card’s
application version number.
• the application usage control is checked to allow the proper services for the
card.
• the expiry date or effective date validation is performed.

NOTE
inVXEMVAPProcRestrictions() API should be used only when
inVXEMVAPProcRisk() API is not being used.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 63

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

inVXEMVAPTermRisk()

This function obtains the relevant data from the DOC and uses it to perform
Terminal Risk Management (as described in the EMV specifications listed in
References section). It appropriately adjusts the values of the TVR and TSI in the
DOC.

NOTE
inVXEMVAPTermRisk() API should be called after amount has been entered.

This function invokes the getLastTxnAmt() library callback function.

Prototype int inVXEMVAPTermRisk(EMVBoolean (*bIsCardBlackListed)

(unsigned char *,unsigned short, unsigned char *,
unsigned short));

Parameters
Input: bIsCardBlackListed() Checks the card details in the exception file.
This function should be implemented to
accomplish validation, otherwise pass a null
value.

Return Values
Success: 0 This value is returned if Terminal Risk
Management is successfully performed.

Failure: EMV_FAILURE This value is returned if Terminal Risk

Management is unsuccessful.

See also Generic Values Returned by the Library

This function performs:
• floor limit validation.
• random online transaction selection.
• velocity checking.

NOTE • The terminal risk parameters can be changed using

inVXEMVAPSetROSParams() API before calling inVXEMVAPTermRisk() API.
• inVXEMVAPTermRisk() API should not be called if inVXEMVAPProcRisk()
API is already called.

64 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

inVXEMVAPGetCAPK()

This function obtains the appropriate CAPK Modulus and Exponent required for
SDA, DDA or CDDA. It accomplishes this by opening the relevant CAPK
configuration file (refer to the File Formats for Storing CAPKs chapter for more
details), and extracting the key in binary form.

NOTE
inVXEMVAPGetCAPK() API may be called if the application is using an SDA,
DDA, or CDDA module different from that provided in the EMV Module.

Verix Platform int inVXEMVAPGetCAPK(unsigned char *pAID, unsigned char pCAPKIndex,

Prototype unsigned char *pCAPK, int *pinCAPKLen, unsigned char
*pCAPKExp, int *pinCAPKExpLen);

Verix V Platform int inVXEMVAPGetCAPK(unsigned char *pAID, unsigned char pCAPKIndex,

Prototype unsigned char *pCAPK, short *pinCAPKLen, unsigned
char *pCAPKExp, short *pinCAPKExpLen);

Parameters
Input: pAID AID of selected card application.
pCAPKIndex CAPK Index (8F tag) specified by the
card application.

Output: pCAPK Buffer to store the returned CAPK

Modulus.
pinCAPKLen Pointer for returning the CAPK length.
pCAPKExp Buffer to store the returned CAPK
Exponent.
pinCAPKExpLen Pointer for returning the CAPK Exponent
length.

Return Values
Success: 0 This value is returned if all the CAPK
elements are obtained successfully.

Failure: CONFIG_FILE_NOT_FOUND This value is returned if the CAPK file is

invalid or CAPK file is not found.

INVALID_PARAMETER This value is returned upon receiving an

invalid pointer as the function argument.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 65

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

inVXEMVAPSecondGenerateAC()

This function performs the Second Generate AC operation. The application

should decide on the CID on how to proceed with the transaction (refer to the
EMV specifications listed in References section for more details).

NOTE • inVXEMVAPSecondGenerateAC() API should be used only when

inVXEMVAPUseHostData() API is not being used.
• If the card returns 0x9F26 tag with length as 0x00 in the Second Generate
AC response, then the EMV kernel returns an error. But the global TLV
collection will contain 0x9F26 tag, which was returned as part of the First
Generate AC response.

Prototype int inVXEMVAPSecondGenerateAC(int inHostDecision);

Parameters
Input: inHostDecision Host decision. Valid values are:
• HOST_AUTHORISED
• HOST_DECLINED
• FAILED_TO_CONNECT
• OFFLINE_TERMINAL

Return Values
Success: 0 This value is returned when the Generate AC
command is generated successfully.

Failure: CHIP_ERROR This value is returned if the reader receives an

unsuccessful communication from the card.
For example, time-out has happened, response
from the card is not clear or if the card is
removed from the terminal.

BAD_DATA_FORMAT This value is returned when the tags are invalid.

For example, if there are invalid tags in the
response.

VS_ERROR This value is returned if inHostDecision is

other than OFFLINE_TERMINAL for an offline
only terminal.

See also Generic Values Returned by the Library

NOTE The application has to call inVXEMVAPSecondGenerateAC() API with

inHostDecision as OFFLINE_TERMINAL, when the terminal type is 0x23 or
0x26 and the card requested an ARQC for the First Generated AC.

66 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

inVXEMVAPProcessScript()

This function obtains an issuer script received from the host and sends it to the
card (refer to the EMV specifications listed in References section for more
details). The application should ensure that scripts (71 and 72) received from the
host are written to buffers.

NOTE
inVXEMVAPProcessScript() API should be used only when
inVXEMVAPUseHostData() API is not being used.

Prototype int inVXEMVAPProcessScript(unsigned char *pScript, unsigned char

*pIssuerScriptResults);

Parameters
Input: pScript Issuer script.

Output: pIssuerScriptResults Buffer to contain the issuer script results (refer

to the EMV specifications listed in References
section for more details). Minimum value for
this parameter is 5 bytes.

Return Values
Success: 0 This value is returned if the script processing
is successful.

Failure: BAD_SCRIPT This value is returned if the script has

incorrect format.

INVALID_PARAMETER This value is returned upon receiving an

invalid pointer as the function argument.

See also Generic Values Returned by the Library

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 67

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

inVXEMVAPAuthIssuer()

This function obtains the issuer authentication data that the application received
from the host after going online, and performs issuer authentication (refer to the
EMV specifications listed in References section for more details). This function
then appropriately adjusts the values of the TVR and the TSI in the DOC. If issuer
authentication is not supported, inVXEMVAPAuthIssuer() API returns SUCCESS.
It is assumed that the issuer authentication data (0x91 tag) is in the DOC.

NOTE • Application has to ensure that the issuer authentication data received from
the host is updated in the 0x91 tag.
• inVXEMVAPAuthIssuer() API should be used only when
inVXEMVAPUseHostData() API is not being used.

Prototype int inVXEMVAPAuthIssuer(void);

Parameters
None

Return Values
Success: 0 This value is returned if the issuer
authentication is successful.

Failure: CHIP_ERROR This value is returned if the reader receives

an unsuccessful communication from the
card.
For example, time-out has happened,
response from the card is not clear or if the
card is removed from the terminal.

EMV_FAILURE This value is returned if the authentication is

failed.

See also Generic Values Returned by the Library

68 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

inVXEMVAPAPDU()

This function enables a standard ICC APDU command (EMV or non EMV) to be
sent to the card, as required. This function can be used to send non EMV
commands to the card. For example, any proprietary commands to be sent.

NOTE
inVXEMVAPAPDU() API can be called any time after the card has been powered
ON (by inVXEMVAPCardInit() API).

Prototype int inVXEMVAPAPDU(unsigned char *Header, unsigned char Lc, unsigned char
*SendData, unsigned char Le, unsigned
char *pReceiveDataLen, unsigned char *ReceivedData);

Parameters
Input: Header Four byte header, per ISO definition - CLA, INS,
P1, P2.
Lc Length of data sent to card.
SendData Buffer containing data to be sent. Can be null if
there is no data to be sent.
Le Maximum number of data bytes expected to be
received from card.

Output: pReceiveDataLen Pointer to the unsigned char to contain the length

of data received from the card. It is at least 2
bytes length because of SW1 and SW2 bytes.
ReceivedData Buffer to hold the data received from the card.

Return Values
Success: 0 This value is returned if the EMV commands are
successfully sent.

Failure: CHIP_ERROR This value is returned if the reader receives an

unsuccessful communication from the card.
For example, time-out has happened, response
from the card is not clear or the card is removed
from the terminal.

INVALID_PARAMETER This value is returned upon receiving an invalid

pointer as the function argument.

See also Generic Values Returned by the Library

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 69

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

inVXEMVAPSetDefDDOL()

This function sets the default DDOL directly. This function is used when the
configuration data handling mechanism provided in the EMV Module is not
appropriate.

Prototype int inVXEMVAPSetDefDDOL(unsigned charunsigned char *pDefDDOL, int

inLenDefDDOL);

Parameters
Input: pDefDDOL Buffer containing the default DDOL.
inLenDefDDOL Length of the default DDOL.

Return Values
Success: 0 This value is returned if the DDOL is set
successfully.

Failure: INVALID_PARAMETER This value is returned upon receiving an invalid

pointer as the function argument.

NOTE
inVXEMVAPSetDefDDOL() API is not required if the default DDOL is updated in
the MVT.

70 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

inVXEMVAPSetDefTDOL()

This function sets the default TDOL directly. This function is used when the
configuration data handling mechanism provided in the EMV Module is not
appropriate.

Prototype int inVXEMVAPSetDefTDOL(unsigned char *pDefTDOL, int inLenDefTDOL);

Parameters
Input: pDefTDOL Buffer containing the default TDOL.
inLenDefTDOL Length of the default TDOL.

Return Values
Success: 0 This value is returned if the TDOL is set
successfully.

Failure: INVALID_PARAMETER This value is returned upon receiving an invalid

pointer as the function argument.

NOTE
inVXEMVAPSetDefTDOL() API is not required when TDOL is updated in the
MVT.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 71

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

inVXEMVAPSetTACs()

This function sets the TACs directly. It is used where the configuration data
handling mechanism provided in the EMV Module is not appropriate.

Prototype int inVXEMVAPSetTACs(unsigned char *pTACDecline, unsigned char *pTACOnline

unsigned char *pTACDefault);

Parameters
Input: pTACDecline Buffer containing the TAC decline (5 bytes).
pTACOnline Buffer containing the TAC online (5 bytes).
pTACDefault Buffer containing the TAC default (5 bytes).

Return Values
Success: 0 This value is returned if the TAC is set
successfully.

Failure: INVALID_PARAMETER This value is returned upon receiving an invalid

pointer as the function argument.

NOTE • inVXEMVAPSetTACs() API is not required if the TAC values are set in the
MVT.
• inVXEMVAPSetTACs() API may be required when the TACs frequently
change the First Generate AC.

72 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

inVXEMVAPSetROSParams()

This function sets the parameters for random online selection in the global
collection. It is used where the configuration data handling mechanism provided in
the EMV Module is not appropriate and should be changed for a particular
transaction.
The modified values are used only for that particular transaction and then revert to
their original values (obtained from the MVT) for the next transaction.

Prototype int inVXEMVAPSetROSParams(unsigned long ulFloorLimit,

unsigned long ulRSThreshold, int inRSTarget,
int inRSMax);

Parameters
Input: ulFloorLimit Floor limit.
ulRSThreshold Threshold value for biased random selection.
inRSTarget Target percentage for biased random selection.
inRSMax Maximum target percentage for biased random
selection.

Return Values
Success: 0 This value is returned if the risk management
parameters are set successfully.

Failure: None

NOTE • Use inVXEMVAPSetROSParams() API to change the Terminal Risk

Management parameters dynamically, if needed.
• Do not use inVXEMVAPSetROSParams() API if Terminal Risk Management
parameters are set in the MVT as it can be used for the entire transaction.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 73

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

usVXEMVAPGetVersion()

This function obtains the EMV Module version number. This can be used for
debugging purposes.

Prototype unsigned short usVXEMVAPGetVersion(char * szVersionNo);

Parameters
Output: szVersionNo EMV Module fills the version number in this
buffer. Minimum size of the buffer should be 12
chars.

Return Values
Success: 0 This value is returned if the version number is
successfully copied.

Failure: INVALID_PARAMETER This value is returned upon receiving an invalid

pointer as the function argument.

74 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Lower Level Function Calls

vdSetCAPKExpiryCheck()

The CAPK expiry date check is configurable. Applications will be able to enable/
disable CAPK expiry date check using this API. By default, the kernel will not
perform the CAPK expiry date check.

Prototype vdSetCAPKExpiryCheck(int flag);

Parameters
Output: flag Indicator to enable/disable CAPK expiry date.
1 – to enable CAPK expiry date check.
0 – to disable CAPK expiry date check.

Return Values None

vdSetConfigOption()

The config file format is configurable. Applications will be able to set the config file
format using this API. By default, the kernel uses est.dat and mvt.dat
approach.

Prototype void vdSetConfigOption(short shConfigOption);

Parameters
Input: shConfigOption Indicator to set the config file format.
TYPE_XML – enforces kernel to use XML file
format (EST.XML, MVT.XML, and KEYS.XML).

Return Values None

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 75

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Data Object Collection Access Functions

Data Object The functions in this section are needed when an application access or
Collection manipulate a tagged EMV data object in the DOC, or add a new data object to the
Access DOC.
Functions These functions are provided by the EMV Library and the descriptions are from
the Verix/Verix V EMV Library Programmers Manual.
To make changes to the TVR or TSI, use usEMVGetTxnStatus() API or
usEMVSetTxnStatus() API instead of usEMVUpdateTLVInCollxn() API, as the
update functions do not work for the TVR or the TSI.
The return values are defined in the file EMVResult.hpp header file, which is a
part of the EMV Library. Refer to the sample code in Building an EMV Application
chapter for more details.

76 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Data Object Collection Access Functions

usEMVGetTxnStatus()

This API obtains the TVR/TSI bytes from the collection.

Prototype unsigned short usEMVGetTxnStatus(srTxnResult *psrTVR_TSI);

Parameters
Input: None

Output: psrTVR_TSI Contains the TVR and TSI bytes from

the collection.

Return Values
Success: EMV_SUCCESS (0) This value is returned if the TVR and TSI
tags are found, and data is copied
correctly to the output buffer.

Failure: E_TAG_NOT_FOUND This value is returned if the tags are not

found in the collection.

E_INVALID_PARAM This value is returned when the pointer

value is invalid.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 77

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Data Object Collection Access Functions

usEMVSetTxnStatus()

This API sets the TVR and TSI bytes in the collection.

Prototype unsigned short usEMVSetTxnStatus(srTxnResult *psrTVR_TSI);

Parameters
Input: psrTVR_TSI Structure containing the TVR and TSI bytes to
update in the collection.

Return Values
Success: EMV_SUCCESS (0) This value is returned if the TVR/TSI bytes are
set correctly.

Failure: EMV_FAILURE This value is returned if the TVR/TSI bytes are

not set correctly.

E_INVALID_PARAM This value is returned when the pointer value is

invalid.

78 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Data Object Collection Access Functions

The Vx EMV Module is enhanced to support multi-byte tags. To support this, the
following APIs are modified accordingly:

usEMVAddTLVToCollxn()

This API adds a TLV object with tag, data and length to the TLV collection
maintained by the library.

Prototype unsigned short usEMVAddTLVToCollxn(const unsigned short tag, unsigned char

*pData, unsigned short dLen, unsigned
char* multiTag, unsigned short tagLen);

Parameters
Input tag Tag coded in 1 or 2 bytes to be added to
the collection.
pData Value of the TLV object to be added to
the collection.
dLen Length of the data pData.
multiTag Tag coded in more than 2 bytes to be
added to the collection.
tagLen Length of the multiTag tag name.

Output None

Return Values
Success: EMV_SUCCESS This value is returned if the data
object is added to the collection.

Failure: E_TAG_ALREADY_PRESENT This value is returned if the tag is

already present in the collection.
Note: Use
usEMVUpdateTLVInCollx
n() API if the tag is already
present in the collection.

EMV_FAILURE This value is returned when the

addition of the tag to the collection
fails.

E_TLVCOLLECTION_FULL This value is returned when the

collection is full and unable to store
the tag.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 79

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
Data Object Collection Access Functions

E_INVALID_PARAM This value is returned in any of

these following two scenarios:
• If the value of tag is 0x00 and
the length of multiTag tag
name, tagLen is not greater
than 2.
• If the value of any of the function
arguments pData, dLen and
multiTag is sent as NULL.

E_TAG_CHANGE_NOT_ALLOWED This value is returned if the tag to

be added is an ICC sourced tag.

NOTE • It is required to provide only three parameters (tag, pData and dLen) while
adding 1 or 2 byte(s) tags to the collection.
• If the application needs to add a multi-byte tag, then the value of the tag
should be 0x00 and the multiTag tag name and the length of the
multiTag tag name tagLen should be passed in addition to the tag,
pData and dLen parameters.

80 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
usEMVGetTLVFromColxn()

usEMVGetTLVFromColxn()

This API retrieves a TLV object from the collection.

Prototype unsigned short usEMVGetTLVFromColxn(const unsigned short tag, unsigned

char *pData, unsigned short *dLen,
unsigned char* multiTag, unsigned
short tagLen);

Parameters
Input tag Tag coded in 1 or 2 bytes to be obtained from the
collection.
multiTag Tag coded in more than 2 bytes to be obtained
from the collection.
tagLen Length of the multiTag tag name.

Output pData Value of the TLV object to be retrieved from the

collection.
dLen Length of the data retrieved.

Return Values
Success: EMV_SUCCESS This value is returned if the tag is found in the
collection.

Failure: E_TAG_NOTFOUND This value is returned if the tag is not found in the
collection.

E_INVALID_PARAM This value is returned in any of these following

two scenarios:
• If the value of tag is 0x00 and the length of
multiTag tag name, tagLen is not greater
than 2.
• If the value of any of the function arguments
pData, dLen and multiTag is sent as NULL.

NOTE • It is required to provide only three parameters (tag, pData and dLen)
while retrieving 1 or 2 byte(s) tags from the collection.
• When the application needs to retrieve a multi-byte tag, then the value of the
tag should be 0x00 and the multiTag tag name and the length of the
multiTag tag name tagLen should be passed in addition to the tag,
pData and dLen parameters.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 81

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
usEMVGetTLVFromColxn()

usEMVUpdateTLVInCollxn()

This API updates TLV object in the collection. If the TLV object is not found in the
collection, then it is added.

Prototype unsigned short usEMVUpdateTLVInCollxn(const unsigned short tag, unsigned

char *pData, unsigned short dLen,
unsigned char* multiTag, unsigned
short tagLen);

Parameters
Input tag Tag coded in 1 or 2 bytes to be updated to
the collection.
pData Value of the TLV object to be updated to
the collection.
dLen Length of the data pData.
multiTag Tag coded in more than 2 bytes to be
updated to the collection.
tagLen Length of the multiTag tag name.

Output None

82 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
usEMVGetTLVFromColxn()

Return Values
Success: EMV_SUCCESS This value is returned if the tag is
updated successfully.

Failure: E_TAG_NOT_SUPPORTED This value is returned if the user

tries to update the TVR/TSI bytes.

EMV_FAILURE This value is returned when

updation of the tag to the collection
fails.

E_TLVCOLLECTION_FULL This value is returned when the

collection is full and the tag cannot
be stored.

E_INVALID_PARAM This value is returned in any of

these following two scenarios:
• If the value of tag is 0x00 and
the length of multiTag tag
name, tagLen is not greater
than 2.
• If the value of any of the function
arguments pData, dLen and
multiTag is sent as NULL.

E_TAG_CHANGE_NOT_ALLOWED This value is returned if the tag to

be updated is an ICC sourced tag.

NOTE • It is required to provide only three parameters (tag, pData and dLen) while
updating 1 or 2 byte(s) tags to the collection.
• When the application needs to update a multi-byte tag, then the value of tag
should be 0x00 and the multiTag tag name and the length of the
multiTag tag name tagLen should be passed in addition to the tag,
pData and dLen parameters.

usEMVRetrieveTLVFromColxn()

This API is used by the application to retrieve a tag from the TLV collection. This
API is similar to the existing usEMVGetTLVFromColxn() API except that, the
application passes the length of the buffer to this API to get the value of the tag.

Prototype unsigned short usEMVRetrieveTLVFromColxn (const unsigned short tag,

unsigned char *pData, int iDataLen, unsigned short *dLen, unsigned char*
multiTag, unsigned short tagLen);

Parameters
Input tag Tag coded in 1 or 2 bytes to be obtained from the
collection.
iDataLen Size of the buffer pData (to be provided by the
application).

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 83

VERIX /VERIX V EMV M ODULE F UNCTION C ALLS
usEMVGetTLVFromColxn()

multiTag Tag coded in more than 2 bytes to be obtained from

the collection.
tagLen Length of the multiTag tag name.

Output pData Value of the TLV object, to be obtained from the

collection.
dLen Length of the data retrieved.

Return Values
Success: EMV_SUCCESS This value is returned if the tag is found in the
collection.

Failure: E_TAG_NOTFOUND This value is returned if the tag is not found in the
collection.

E_INSUFFICIENT_ This value is returned if the size of the buffer is less

BUFF_SIZE than the length of the tag value to be copied. When
this value is returned, the dLen will be updated
with the minimum required buffer size for this tag.

E_INVALID_PARAM This value is returned in any of these following two

scenarios:
• If the value of tag is 0x00 and the length of
multiTag tag name, tagLen is not greater
than 2.
• If the value of any of the function arguments
pData, dLen and multiTag is sent as NULL.

84 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

CHAPTER 4

EMV Library Callback Function Calls

This chapter lists and describes the callback functions implemented by the
application. These calls are used when the library requests the application for
some information to complete the execution of a function.
If the callback functions should be used by EMV Library during the course of the
transaction, then the function pointers for the following EMV Library callback
functions have to be set with EMV Module using inVXEMVAPSetFunctionality() as
an interface API:
• getLastTxnAmt()
• getTerminalParam()
• getCapkExp()
• getUsrPin()
• getXUsrPin()
• usEMVDisplayErrorPrompt()
• usEMVPerformSignature()
• usEMVPerformOnlinePIN()
• usEMVIssAcqCVM()
• displayPINPrompt()
• bIsMultipleOccurencesAllowed()
• usGetBypassDecsn()
• usGetTermAVN()
• usGetExtAuthDecision()
• usGetPOSDecsn()
• vdSelPreferredLang()
• usPinInfo()

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 85

EMV L IBRARY C ALLBACK F UNCTION C ALLS
getLastTxnAmt()

getLastTxnAmt()

This API returns the last transaction amount for a card with the same PAN as the
card inserted for the current transaction, and returns an amount equal to 0 if the
record does not exist for the same PAN.
getLastTxnAmt() API is used in the EMV Library to check if the sum of the
transaction amount and the last transaction amount is greater than or equal to the
terminal floor limit during Terminal Risk Management. Refer to the EMV
Specifications listed in References section for more details.
getLastTxnAmt() API is called when the user calls inVXEMVAPProcRisk() and
inVXEMVAPTermRisk() APIs. The function pointer for getLastTxnAmt() API
should be set using inVXEMVAPSetFunctionality() API with the respective
functionality code. Refer to the Function Pointers of the Callback Function chapter
for the functionality code.
The application should implement:
• split sales function,
• obtain the last transaction value on the same PAN from the log file, and
• pass the value as a part of the return value.
If the same PAN entry is not found in the log file, it should return zero.
Refer to the EMVUI.C test sample file for the example implementation.

Prototype unsigned short getLastTxnAmt(unsigned long *pulAmt);

Parameters
Input: None

Output: pulAmt Pointer to an unsigned long that returns the last

transaction amount.

Return Values
Success: EMV_SUCCESS This value is returned when the processing is
completed successfully.

Failure: Any other return value terminates the EMV transaction.

86 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV L IBRARY C ALLBACK F UNCTION C ALLS
getTerminalParam()

getTerminalParam()

This API provides all the required data for TAC and also contains data for the
default DDOL and default TDOL.
getTerminalParam() API is used in the library during data authentication to obtain
the default DDOL, and during card risk management to obtain the default TDOL.
This API is also used during TAA for obtaining the TAC. Refer to the EMV 4.3
Integrated Circuit Card Application Specification for Payment Systems for more
details.
This callback function is called when the user calls
inVXEMVAPDataAuthentication() and inVXEMVAPFirstGenerateAC() APIs. The
function pointer for getTerminalParam() API should be set using
inVXEMVAPSetFunctionality() API with the respective syntax. Refer to the
Function Pointers of the Callback Function chapter for the syntax.

Prototype unsigned short getTerminalParam(unsigned short id, unsigned char *pdata,

unsigned short *pRetLen);

Parameters
Input: id ID of the data to be retrieved. Valid IDs are:
• TAC_DEFAULT
• TAC_ONLINE
• TAC_DENIAL
• TAG_97_TDOL
• TAG_9F49_DDOL

Output: pdata Pointer to a buffer to hold the data

corresponding to the requested ID.
pRetLen Pointer to a short to return the length of the data.

Return Values
Success: EMV_SUCCESS This value is returned when the processing is
completed successfully.

Failure EMV_FAILURE This value is returned when the ID is other than

valid IDs or when the default DDOL is not
available.

INVALID_PARAMETER This value is returned upon receiving an invalid

pointer as the function argument.

NOTE
getTerminalParam() API is implemented in the EMV Module. The application
developer need not implement this function.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 87

EMV L IBRARY C ALLBACK F UNCTION C ALLS
getCapkExp()

getCapkExp()

This API obtains the CAPK Modulus and Exponent required for SDA, DDA, CDDA
and enciphered PIN offline. It does this by opening the relevant CAPK
configuration file and extracting the key in binary form.
This API also gets the expiry date of the CAPK from the EST file (if present) and
checks if the expiry date is valid.
This callback function is called when the user calls:
• inVXEMVAPDataAuthentication()
• inVXEMVAPVerifyCardholder()
• inVXEMVAPFirstGenerateAC()
• inVXEMVAPUseHostData()
• inVXEMVAPSecondGenerateAC().
The function pointer for getCapkExp() API should be set using
inVXEMVAPSetFunctionality() API with the respective functionality code. Refer to
the Function Pointers of the Callback Function chapter for the functionality code.
Prototype EMVResult getCapkExp(const unsigned char *aid, const unsigned char
capkIndex, unsigned char *pstCapk, short *pCapkLen,
unsigned char *pstCapkExp, short *pCapkExplen);

Parameters
Input: aid Pointer to a buffer that contains the
AID of the selected card application.
capkIndex CAPK Index (0x8F) specified by the
card application.

Output: pstCapk Pointer to a buffer to store the

returned CAPK Modulus.
pCapkLen Pointer to a short to return the CAPK
length.
pstCapkExp Pointer to a buffer to store the
returned CAPK Exponent.
pCapkExplen Pointer to a short to return the CAPK
Exponent length.

88 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV L IBRARY C ALLBACK F UNCTION C ALLS
getCapkExp()

Return Values
Success EMV_SUCCESS This value is returned when the CAPK
file is found, and the data to be used
for the rest of the transaction is
correct.

Failure EMV_FAILURE This value is returned:

• if the CAPK file is not found.
• if the checksum is found and it is
incorrect.
• if the Modulus and Exponent of the
CAPK file are incorrect.

E_CAPK_FILE_NOT_FOUND This value is returned if the CAPK file

is not present in the terminal.

E_CAPK_FILE_EXPIRED This value is returned if the CAPK is

expired.

INVALID_PARAMETER This value is returned upon receiving

an invalid pointer as the function
argument.

NOTE
getCapkExp() API is implemented in the EMV Module. The application developer
need not implement this function.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 89

EMV L IBRARY C ALLBACK F UNCTION C ALLS
getUsrPin()

getUsrPin()

This API is called as a part of CVM. It obtains the PIN to complete CVM
processing. The application handles the UI to obtain the PIN from the cardholder.
Application should return E_PERFORM_SECURE_PIN for getUsrPin() API to
perform secure PIN entry.
The function pointer for getUsrPin() API should be set using
inVXEMVAPSetFunctionality() API with the respective functionality code. Refer to
the Function Pointers of the Callback Function chapter for the functionality code.

Prototype unsigned short getUsrPin(unsigned char *ucPin);

Parameters
Input: None

Output: ucPin This field is pointed to NULL as no PIN

value is expected in secure kernel.

Return Values
Success: Returns the PIN length if the PIN is entered successfully. ucPin has the PIN
value.

E_PERFORM_SECURE_PIN This value is returned by the application

during secure PIN entry. In this case
ucPin should be ignored.
Note:
• This return value is not applicable for
Vx UPT EMV Modules.
• Application should call
usEMVSetPinParams() API before
calling usEMVCardholderVerify()
API, which in turn invokes the callback
function getUsrPin().
• Application should also set the function
pointer for the callback function
displayPINPrompt() before calling
usEMVCardholderVerify() API.

Failure: E_USR_PIN_BYPASSED This value is returned by the application if

the PIN is bypassed.

E_USR_PIN_CANCELLED This value is returned by the application if

the PIN processing is canceled. Upon
time-out, the application returns this value.

E_USR_ABORT This value is returned by the application if

the PIN entry is canceled and the
transaction has to be aborted.

E_PP_ABSENT This value is returned by the application if

the PINpad is absent.

90 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV L IBRARY C ALLBACK F UNCTION C ALLS
getXUsrPin()

getXUsrPin()

This API is called as a part of CVM. The EMV kernel supports secure PIN on
Vx520 connected to a PP1000seV3. The kernel invokes callback function
getXUsrPIN() upon receiving X_PERFORM_SECURE_PIN from
getUsrPIN() API. The application should provide the encrypted PIN block
received from the external PINpad (PP1000seV3) to the kernel through this
callback function.
It obtains the PIN to complete CVM processing. The application handles the UI to
obtain the PIN from the cardholder.
The function pointer for getXUsrPin() API should be set using
usEMV_Set_Functionality() API (Refer to the Verix/Verix V EMV Library
Programmers Manual for more details on this API).

NOTE
This callback function is not applicable for Vx UPT EMV Modules.

Prototype unsigned short getXUsrPin(int *Mode , unsigned char **PinBlock);

Parameters
Input None

Output Mode This is required by the OS to load the

encrypted PIN block in the secure
memory. Application should pass 0x00.
PinBlock Pointer to the 8-byte encrypted PIN block.

Return Values
Success: X_PIN_SUCCESS PIN block successfully received from
PP1000seV3. PinBlock points to the 8-
byte PIN block and Mode is set to
appropriate value.

Failure: E_USR_PIN_CANCELLED This value is returned by the application if

the PIN processing is canceled. Upon
time-out, the application returns this value.

E_USR_PIN_BYPASSED This value is returned by the application if

the PIN is bypassed.

E_PP_ABSENT This value is returned by the application if

the PINpad is absent.

E_USR_ABORT This value is returned by the application if

the PIN entry is canceled and the
transaction has to be aborted.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 91

EMV L IBRARY C ALLBACK F UNCTION C ALLS
getXUsrPin()

E_USR_BACKSPACE_KEY_ This value is returned by the application to

PRESSED the kernel when backspace key is pressed
with no PIN entered during the online PIN
entry. When the kernel receives this return
value, it returns the control to the
application. The kernel will not reset any
TVR/TSI bit that is set during the PIN
entry.

EMV_FAILURE Any other error condition.

92 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usEMVDisplayErrorPrompt()

usEMVDisplayErrorPrompt()

This API should be implemented by the application.

The EMV Library uses this API when the application should display a message to
warn the user. For example, when an invalid PIN is detected, or an invalid CAPK
is received, or if the PIN try limit is exceeded, and so on.
This API is called when the user calls inVXEMVAPDataAuthentication() and
inVXEMVAPVerifyCardholder() APIs.
The function pointer for usEMVDisplayErrorPrompt() API should be set using
inVXEMVAPSetFunctionality() API with the respective functionality code. Refer to
the Function Pointers of the Callback Function chapter for the functionality code.
Refer to the EMVUI.C test sample file for the example implementation.

Prototype void usEMVDisplayErrorPrompt (unsigned short errorID);

Parameters
Input:
errorID Contains a list of values used by the library to notify the application to
display a message. Valid values of the error IDs are:

• E_PIN_REQD Sent from the library to the

application if PIN entry is required,
but not entered.

• E_LAST_PIN_TRY Sent from the library to the

application if the PIN entry has
reached the last counter. Assuming
PIN try counter is 3 and the first 2
PIN entries failed, the next time PIN
entry is requested, this message is
displayed to avoid blocking of the
card.

• E_INVALID_CAPK Sent from the library to the

application if the CAPK is invalid.

• E_CAPK_NOT_FOUND Sent from the library to the

application if the CAPK file is not
found in the terminal.

• E_CAPK_WRONG_CHECKSUM Sent from the library to the

application when the CAPK
checksum is wrong.

• E_USR_PIN_CANCELLED Sent from the library to the

application if the user canceled the
PIN entry process.

• E_USR_PIN_BYPASSED Sent from the library to the

application if the user bypassed the
PIN entry process.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 93

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usEMVDisplayErrorPrompt()

• E_PIN_SESSION_COMPLETE Used to display the message after

the PIN session is completed.

• E_PIN_SESSION_IN_PROGRESS Used to display the message when

the PIN session is in progress.

The following values are applicable only for secure PIN:

• E_PIN_TRY_LT_EXCEED Sent from the library to the

application if the PIN try limit is
exceeded and the card gets
blocked.

• E_PIN_BLOCKED Used for displaying the message if

the verify command returns 0x6983
or 0x6984.

• E_ICC_BLOCKED Used to display when the ICC card

is blocked.

• E_INVALID_PIN Sent from the library to the

application if the PIN is invalid.

• E_EXT_PIN_BYPASSED Sent from the library to the

application, if the PIN bypass is
from POS/external device.

• E_EXT_PIN_CANCELLED Sent from the library to the

application, if the PIN cancel is from
POS/external device.

Return Values
None

NOTE • The error IDs are defined in the EMVResult.hpp header file.
• usEMVDisplayErrorPrompt() API can use any error ID if the application
defines these IDs.

94 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usEMVPerformSignature()

usEMVPerformSignature()

This API should be implemented by the application. The EMV Library uses this
API when the CVM is Signature and the terminal supports Signature verification.
The application should print a signature line on the receipt. This API is called
when the user calls inVXEMVAPVerifyCardholder() API.
The function pointer for usEMVPerformSignature() API should be set using
inVXEMVAPSetFunctionality() API with the respective functionality code. Refer to
the Function Pointers of the Callback Function chapter for the functionality code.
Refer to the EMVUI.C test sample file for the example implementation.

Prototype unsigned short usEMVPerformSignature(void);

Parameters
None

Return Values
Success: EMV_SUCCESS This value is returned if the signature verification is
successful.

Failure: EMV_FAILURE This value is returned if the signature verification is

failed. If the card has any other CVM, it is performed
as a part of the cardholder verification.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 95

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usEMVPerformOnlinePIN()

usEMVPerformOnlinePIN()

This API should be implemented by the application. The library uses this API
when the CVM is online enciphered PIN and the terminal supports online
enciphered PIN verification. The application should request for PIN entry from the
user, encrypt the PIN and send the PIN to the host for verification. The library sets
the TVR/TSI bits and the CVM results based on the return value from the
application.
This API is called when the user calls inVXEMVAPVerifyCardholder() API.
The function pointer for usEMVPerformOnlinePIN() API should be set using
inVXEMVAPSetFunctionality() API with the respective functionality code. Refer to
the Function Pointers of the Callback Function chapter for the functionality code.
Refer to the EMVUI.C test sample file for the example implementation.

Prototype unsigned short usEMVPerformOnlinePIN(void);

Parameters
None

Return Values
Success: EMV_SUCCESS This value is returned if online PIN
is obtained successfully.

Failure: EMV_FAILURE This value is returned if online PIN

is not obtained successfully. If the
card has any other CVM, it is
performed as a part of cardholder
verification.

E_CVM_NOT_PERFORMED This value is returned if online PIN

CVM is not performed.

E_USR_BACKSPACE_KEY_PRESSED This value is returned by the

application from
usEMVPerformOnlinePIN()
callback function to the kernel when
backspace key is pressed with no
PIN entered during the online PIN
entry. When the kernel receives this
return value, it returns the control to
the application. The kernel will not
reset any TVR/TSI bit that is set
during the PIN entry.

96 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usEMVIssAcqCVM()

usEMVIssAcqCVM()

This API should be implemented by the application.

The library uses this API during cardholder verification. If the condition codes
specified by the card is in the issuer-specific or acquirer-specific ranges (refer to
the EMV 4.3 Specification, book 3, Annex C.3 for more details), issuer-specific or
acquirer-specific CVMs should be performed. The library sets the TVR/TSI bits
and CVM results based on the return value from the application and the code filled
by the application.
The function pointer for usEMVIssAcqCVM() API should be set using
inVXEMVAPSetFunctionality() API with the respective functionality code. Refer to
the Function Pointers of the Callback Function chapter for the functionality code.
This API is called when the user calls inVXEMVAPVerifyCardholder() API.

Prototype EMVResult usEMVIssAcqCVM(unsigned short issacq, unsigned short *code);

Parameters
Input: issacq Specifies if the CVM is issuer or acquirer.
The library has two #defined values to
recognize if the CVM is issuer-specific or
acquirer-specific. Valid values are:
• ACQ_CVM: The card returned a CVM
in the acquirer-specific CVM range.
• ISS_CVM: The card returned a CVM in
the issuer-specific CVM range.
code Input/output parameter. The module sends
the exact value of CVM received from the
card.

Note: With issacq and code parameters, the application should be

able to decide on the method of cardholder verification to be
performed.

Output: code Should be filled by the application to

denote the type of cardholder verification
performed. This value is used for setting
the CVM results.

Return Values
Success EMV_SUCCESS This value is returned if the cardholder
verification is successful.

Failure EMV_FAILURE This value is returned if the issuer/acquirer

CVM is unsuccessful. The application
performed all necessary tasks, and then
returned failure. The transaction is
terminated.

E_CVM_NOT_PERFORMED This value is returned if the CVM is not

performed.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 97

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usEMVIssAcqCVM()

E_CVM_FAILED This value is returned if the issuer/acquirer

CVM is failed. This value should be
returned by the application if the next
CVM in the CVM list (returned by the card)
should be performed (if present and
allowed).

E_CVM_NOT_SUPPORTED This value should be returned if the

issuer/ acquirer CVM code is not
supported.

98 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV L IBRARY C ALLBACK F UNCTION C ALLS
displayPINPrompt()

displayPINPrompt()

This callback function is used to display a message for accepting the PIN from the
user. displayPINPrompt() API is used by the library only when secure PIN
processing has to be performed.
If the EMV Module is used, the application calls the existing
inVXEMVAPSetDisplayPINPrompt() API to set the function pointer for
displayPINPrompt() API. If the application is not using any specific display PIN
prompt function, the EMV Module has a default implementation, and the
application can pass null value for the *fptr parameter in the
inVXEMVAPSetDisplayPINPrompt() API.
If the EMV Module is used and the inVXEMVAPSetDisplayPINPrompt() API
is not called, there will not be any message displayed for the user to enter the PIN.
However, users will be able to enter the PIN.

Prototype void displayPINPrompt(void);

Parameters
None

Return Values
None

NOTE
This API is not applicable for Vx UPT EMV Modules.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 99

EMV L IBRARY C ALLBACK F UNCTION C ALLS
bIsMultipleOccurencesAllowed()

bIsMultipleOccurencesAllowed()

This API is used by the library during the application selection to allow partial
selection of AIDs. This API should be implemented by the application.
The function pointer for bIsMultipleOccurencesAllowed() API should be set using
inVXEMVAPSetFunctionality() API with the respective function code referred in
Appendix C.

Prototype bool bIsMultipleOccurencesAllowed(byte *pAid);

Parameters
Input: pAid The AID that is being sent to the card for
selection.

Return Values
Success EMV_TRUE This value is returned if the partial name
selection is allowed for the AID.

Failure EMV_FALSE This value is returned if the partial name

selection is not allowed for the AID.

INVALID_PARAMETER This value is returned upon receiving an

invalid pointer as the function argument.

100 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usGetBypassDecsn()

usGetBypassDecsn()

This function is invoked by the library for secure PIN, when the OS indicates that a
PIN bypass key is pressed. The application can display the required message in
the callback function and return a specific value PIN_MANDATORY to the kernel
to indicate if the PIN session should be continued.
The function pointer for usGetBypassDecsn() API should be set using
inVXEMVAPSetFunctionality() API with the respective function code. Refer
to Appendix M for more details.

Prototype unsigned short usGetBypassDecsn(void);

Parameters
None

Return Values
PIN_MANDATORY The EMV kernel will continue to prompt for the PIN entry,
discarding the cardholder PIN bypass.

For any other return values, the kernel will allow the cardholder PIN bypass and will
continue with the PIN bypass transaction flow.

NOTE
This API is not applicable for Vx UPT EMV Modules.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 101

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usGetTermAVN()

usGetTermAVN()

This callback function should be set by the application using

inVXEMVAPSetFunctionality() API, if this callback is to be invoked by the module.
If the application sets this function pointer, then the terminal application version
numbers present in the EST.dat are not used. Applications that do not support
more than two application version numbers should not set this function pointer.

Prototype unsigned short usGetTermAVN(srMultiAVN *pszTermAVN, int *iCount);

Parameters
Input/ iCount This is an input-output parameter. The kernel
Output provides the number of instances of pszTermAVN.
Application can fill the number of terminal application
version numbers it copies into pszTermAVN
parameter.

Output pszTermAVN Array of structures that the kernel creates and passes
to the application. The application needs to fill this
array with the terminal application version numbers.
Note: The module supports up to 10 application
version numbers.

Return Values
Success: EMV_SUCCESS This value is returned if the processing is completed
successfully.

Failure: EMV_FAILURE This value is returned if the application fails to get the
terminal application version numbers.

102 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usGetTermAVN()

Scenarios Expected Behavior

When: “ICC and terminal have different AVNs” (TVR byte 2
• usGetTermAVN() callback bit 8) bit is set to 0.
API is not set to NULL.
• the return value of this
callback API is
EMV_SUCCESS.
• the application version
number of the card matches
with one of the application
version numbers provided
by the application.
When: “ICC and terminal have different AVNs” (TVR byte 2
• usGetTermAVN() callback bit 8) bit is set to 1.
API is not set to NULL.
• the return value of this
callback API is
EMV_SUCCESS.
• the application version
number of the card does not
match with any of the
application version numbers
provided by the application.
When: EMV kernel uses the AVNs of EST.dat for AVN
• usGetTermAVN() callback comparison, between the terminal and the card.
API is not set to NULL.
• the return value of this
callback API is
EMV_FAILURE.
When usGetTermAVN() EMV kernel uses the AVNs of EST.dat for AVN
callback API is set to NULL. comparison, between the terminal and the card.
When: EMV kernel uses the AVNs of EST.dat for AVN
• usGetTermAVN() callback comparison, between the terminal and the card.
API is not set to NULL.
• iCount is <= 0.
When: EMV kernel uses the AVNs of EST.dat for AVN
• usGetTermAVN() callback comparison, between the terminal and the card.
API is not set to NULL.
• iCount is > 10.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 103

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usGetExtAuthDecision()

usGetExtAuthDecision()

This callback function is used by the library to get the application's decision
whether to terminate or continue with the transaction on receiving the status word
as 0x6985 for the external authenticate command. This API should be
implemented by the application.
The function pointer for usGetExtAuthDecision() API should be set using
inVXEMVAPSetFunctionality() API with the respective function code. Refer to
Appendix C for more details.

Prototype Ushort usGetExtAuthDecision(unsigned short usStatusWord);

Parameters
Input: usStatusWord The status word in response of the external
authenticate command.

Return Values
Success: EMV_SUCCESS This value is returned if the application wants
to continue with the transaction.

Failure: EMV_FAILURE This value is returned if the application wants

to terminate the transaction.

104 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usGetPOSDecsn()

usGetPOSDecsn()

This callback function is used by the library for secure PIN, to get the application's
decision on whether to cancel or bypass the PIN CVM from POS/external device.
The function pointer for usGetPOSDecsn() API should be set using
inVXEMVAPSetFunctionality() API with the respective function code. Refer
to Appendix L for more details.

Prototype unsigned short usGetPOSDecsn (void);

Parameters
None

Return Values
EXT_PIN_CNCL To cancel the PIN.

EXT_PIN_BYPASS To bypass the PIN.

NOTE
This API is not applicable for Vx UPT EMV Modules.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 105

EMV L IBRARY C ALLBACK F UNCTION C ALLS
vdSelPreferredLang()

vdSelPreferredLang()

This API is used to perform the language selection for the transaction.
• If the language preference tag is provided and if the terminal supports the
languages mentioned, then the language with the highest preference is
selected.
• If the language preference tag is not present or if the terminal does not have a
matching language with the language preference tag and if the terminal has
more than one supported language, then the terminal displays the supported
languages to the cardholder for selection.
• If the language preference tag is not present or if the terminal does not have a
matching language with the language preference tag and if the terminal
supports one language, then the terminal displays the messages in that
language.
Language selection should be performed before the GPO command is issued to
the card.
This API is used by the library after application selection and before GPO for
language selection. This API should be implemented by the application.
The function pointer for vdSelPreferredLang() API should be set using
inVXEMVAPSetFunctionality() API with the respective function code referred in
Appendix C. EMV kernel invokes this callback after the application selection is
carried out successfully and before the GPO command is issued.

Prototype void vdSelPreferredLang(void);

Parameters
None

Return Values
None

NOTE • inVXEMVAPSelectApplication() EMV kernel API performs both application

selection and GPO, unless specified to split the functionality to perform only
application selection, by setting the MVT short RFU1 field's bit 8. If the
application has chosen to perform application selection and GPO separately,
then the application can perform the language selection prior calling
inVXEMVAPPerformGPO() API.
• The EMV kernel does not support any default implementation for the
language selection process. Hence, it is mandatory that the application sets
the function pointer for language selection, if the kernel is performing
application selection and GPO together.

106 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usPinInfo()

usPinInfo()

The EMV kernel is enhanced to allow PIN bypass even when PIN digits are
present. This is performed by providing the key press information along with the
number of PIN digits entered to the application through this callback function. The
application can indicate if the PIN needs to be bypassed. The kernel invokes this
callback to pass on key press information along with the number of PIN digits
entered.
The function pointer for usPinInfo() API should be set using
inVXEMVAPSetFunctionality() API with the respective function code. Refer to
Appendix C for more details.

Prototype ushort usPinInfo(uchar ucNumOfPINDigits, ushort

usLastNonNumericKeyPressed);

Parameters
Input: ucNumOfPINDigits Number of PIN digits entered.
usLastNonNumericKeyPressed The last non-numeric key pressed.

Output: None

Return Values
CONTINUE Kernel continues with the PIN session.

BYPASS The PIN is bypassed.

CANCEL The PIN entry is canceled.

NOTE • The application must first register the callback with the kernel to use this
feature.
• This API is not applicable for Vx UPT EMV Modules.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 107

EMV L IBRARY C ALLBACK F UNCTION C ALLS
usPinInfo()

108 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

CHAPTER 5

EMV Module Callback Function Calls

This chapter lists and describes the EMV Module callback functions. In addition to
the EMV Module, examples are provided to implement the UI and other auxiliary
functions required for an application to make use of the EMV Module functions.
Refer to the EMVTEST.C file for an example of a test program that uses the
Higher Level Function Calls to carry out an EMV transaction from card insertion to
transaction completion.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 109

EMV M ODULE C ALLBACK F UNCTION C ALLS
bIsCardBlackListed()

bIsCardBlackListed()

The EMV Module provides default implementation for this library callback
function. The default implementation does not perform any checking because it is
an optional feature. This function is implemented only when you want to perform
blacklisted card check.
To override the default implementation, provide an implementation and pass the
function pointer to the EMV Module. The application uses the PAN and PAN
sequence number to determine if the inserted card is a blacklisted card. This is
performed by checking the PAN and sequence number against a card exception
file that is present in the terminal. If the card is found in the exception file, the
user-defined function returns EMV_TRUE and the card found in exception
file bit is set in the TVR by the EMV Library. Otherwise, the user-defined
function returns EMV_FALSE. The terminal should have a proper exception file in
the memory.
The user should pass the user-defined function (when blacklisted card checking is
implemented) as a parameter when calling inVXEMVAPProcRisk() API or this API
is called only when the Black Listed Card Support flag is enabled in the
MVT for the specific scheme.
If the application does not require specific blacklisted card validation, the EMV
Module has a default implementation. The application has to pass null value to
*bIsCardBlackListed parameter in the inVXEMVAPProcRisk() API for the
default implementation.
Refer to the EMVUI.C test sample file for the example implementation.

Prototype EMVBoolean bIsCardBlackListed(unsigned char *pan, unsigned short panLen,

unsigned char *panSeqNo,
unsigned short panSeqLen);

Parameters
Input: pan PAN of the card.
panLen Number of digits of the PAN.
panSeqNo PAN sequence number of the card.
panSeqLen Number of digits of the PAN sequence number.

Return Values
EMV_TRUE This value is returned when the inserted card’s PAN is found in the
exception file.

EMV_FALSE This value is returned when the inserted card’s PAN is not found in the
exception file.

NOTE
Checking blacklisted cards is optional. The blacklisted checking is performed
only if the existing file is found in the terminal.

110 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV M ODULE C ALLBACK F UNCTION C ALLS
bIsCSNValid()

bIsCSNValid()

Checking CSN validity is optional. The EMV Module provides default

implementation for the library callback function. The default implementation
validates the concatenation of RID, the CAPK Index and the CSN. The CSN is a 3
byte number that is a part of the decrypted certificate. If this is not valid, data
authentication fails.
To override default implementation, provide an implementation and pass the
function pointer to the EMV Module. This is performed only if the file with a list of
revoked CSNs is available in the terminal.
This API should be passed as a parameter while calling
inVXEMVAPDataAuthentication() or inVXEMVAPVerifyCardholder() API.
If the application does not require specific CSN validation, the EMV Module has a
default implementation. The application has to pass null value for *bIsCSNValid
parameter in the inVXEMVAPDataAuthentication() and
inVXEMVAPVerifyCardholder() APIs for the default implementation.

NOTE By default, EMV Module checks the validity of the CSN, which is invoked if the
application does not set and pass the function pointer to the EMV Module. By
default, the name of the CSN file is used with the RID and .CSN as the extension.
For example, if the RID is A000000003, then the CSN file name should be
A000000003.CSN.

Prototype unsigned short bIsCSNValid(unsigned char *CardCSN);

Parameters
Input: CardCSN EMV Library fills the CardCSN parameter with
the card serial number.

Return Values
Output: EMV_SUCCESS This value is returned if the certificate serial
number processing is validated successfully.

EMV_FAILURE This value is returned if the certificate serial

number processing is failed.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 111

EMV M ODULE C ALLBACK F UNCTION C ALLS
inGetPTermID()

inGetPTermID()

This API provides an application-specific terminal ID to the EMV Library for

processing. The EMV Module uses inGetPTermID() API during initialization and
adds the same to the DOC. inGetPTermID() API is an optional function. To use the
system terminal ID, this function should be implemented.
Refer to the EMVUI.C test sample file for the example implementation.

Prototype int inGetPTermID(char *ptid);

Parameters
Input: ptid Buffer to store the terminal ID.

Return Values
Output: EMV_SUCCESS This value is returned if the terminal ID is obtained
from the terminal and added to the global collection.

EMV_FAILURE This value is returned if the terminal ID is not obtained

from the terminal.

112 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV M ODULE C ALLBACK F UNCTION C ALLS
inMenuFunc()

inMenuFunc()

This API is required to allow the operator to choose a card application when more
than one card application is supported. The EMV Module calls inMenuFunc() API
during application selection.

Prototype int inMenuFunc(char **labels, int numLabels);

Parameters
Input: labels An array of pointers to strings (names for the menu
options).
numLabels Number of names in the list.

Return Values
An integer that corresponds to the item selected from the array (starting from 1).

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 113

EMV M ODULE C ALLBACK F UNCTION C ALLS
usAmtEntryFunc()

usAmtEntryFunc()

This API is implemented in the application. The EMV Module calls

usAmtEntryFunc() API during the application selection to display the Amount
Entry menu for transaction amount and cashback amount, if the PDOL requests
for the amount. It also displays the Account Type Entry menu. This API is invoked
if the values for transaction amount, cashback amount and account type are
present in the collection. This API is called by the EMV Module before processing
the Get Processing command option, otherwise the application should call this
function before data authentication, to obtain the transaction amount and
cashback amount.
The application needs to update the amount (transaction amount and cashback
amount) and account type (0x5F57 tag) in the collection by calling
usEMVAddAmtToCollxn() and usEMVAddTLVToCollxn() EMV Library APIs
respectively, if not updated by the EMV Module.
If the selected transaction type is Sale with Cashback, the amount should also
include the cashback value. Refer to the EMVUI.C test sample file for the example
implementation. The function pointer for this API is set as a part of the
inVXEMVAPSelectApplication() API.

Prototype unsigned short usAmtEntryFunc (unsigned long *ulTxnAmt);

Parameters
ulTxnAmt This parameter is an input - output parameter.
The values for ulTxnAmt and the implementation for each of them is as
follows:

AMT_ACCT_TYPE_REQD When the usAmtEntryFunc() API

is called with this value set for
the ulTxnAmt parameter, then
the application will:
• accept the amount and
account type from the user,
• update the ulTxnAmt
parameter with the transaction
amount entered,
• add the account type to the
collection as 0x5F57 tag.

ACCT_TYPE_REQD When the usAmtEntryFunc() API

is called with
ACCT_TYPE_REQD set for the
ulTxnAmt parameter, then the
application will accept the
account type, and adds it to the
collection as 0x5F57 tag.

114 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV M ODULE C ALLBACK F UNCTION C ALLS
usAmtEntryFunc()

AMT_CASHBACK_ACCT_TYPE_REQD When the usAmtEntryFunc() API

is called with
AMT_CASHBACK_ACCT_TYPE
_REQD set for the ulTxnAmt
parameter, then the application
will:
• accept the transaction
amount, cashback amount
and account type from the
user,
• update the values for 0x9F02,
0x81, 0x9F03, 0x9F04 and
0x5F57 tags to the collection.

CASHBACK_ACCT_TYPE_REQD When the usAmtEntryFunc() API

is called with
CASHBACK_ACCT_TYPE_REQ
D set for the ulTxnAmt
parameter, then the application
will:
• accept the cashback amount
and account type from the
user,
• update the ulTxnAmt
parameter with the cashback
amount entered,
• add the account type to the
collection as 0x5F57 tag.
The EMV Module will update
0x9F03 and 0x9F04 tags in the
collection.

CASHBACK_REQD When the usAmtEntryFunc() API

is called with
CASHBACK_REQD set for the
ulTxnAmt parameter, then the
application will:
• accept the cashback amount
from the user,
• update the ulTxnAmt
parameter with the cashback
amount entered,
• send ulTxnAmt to the EMV
Module.
The EMV Module will update
0x9F03 and 0x9F04 tags in the
collection.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 115

EMV M ODULE C ALLBACK F UNCTION C ALLS
usAmtEntryFunc()

AMT_CASHBACK_REQD When the usAmtEntryFunc() API

is called with
AMT_CASHBACK_REQD set for
the ulTxnAmt parameter, then
the application will:
• accept the transaction amount
and cashback amount from
the user,
• update 0x9F02, 0x81, 0x9F03
and 0x9F04 tags to the
collection.

AMT_REQD When the usAmtEntryFunc() API

is called with AMT_REQD set for
the ulTxnAmt parameter, then
the application will:
• accept the amount from the
user.
• update the ulTxnAmt
parameter with the amount
entered.
The EMV Module will update
tags 0x9F02 and 0x81 in the
collection.

Return Values
Success: EMV_SUCCESS This value is returned if the
amount and account type are
accepted and successfully
added to the collection.

Failure: Any Other Value The transaction is aborted.

116 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV M ODULE C ALLBACK F UNCTION C ALLS
usCandListModify()

usCandListModify()

The EMV Module allows the application to modify the candidate list to meet
requirements. This function is called only if the Modify candidate list flag is
enabled in the MVT (that is, set to 1). Refer to the MVT for more details.
The application can use this function to exclude some of the smart cards
displayed or selected by the EMV Module. To exclude an AID, the application
should set the bExcludedAID field in the srAIDList structure to 1. The EMV
Module does not include AIDs with the bExcludedAID field set to 1. By default,
the EMV Module includes all AIDs supported by the card for application selection.

Prototype unsigned short usCandListModify(srAIDList *candidateList);

Parameters
candidateList Structure of srAIDList.

Return Values
None

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 117

EMV M ODULE C ALLBACK F UNCTION C ALLS
vdPromptManager()

vdPromptManager()

The EMV Module uses this function when the application has to display a
message to warn or inform the user.
Refer to the EMVUI.C test sample file for the example implementation.

Prototype void vdPromptManager(unsigned short inCondition);

Parameters
Input:
inCondition Contains a list of values used by the EMV Module to notify the
application to display a message. Valid values are:
• APPL_NOT_AVAILABLE
• APPL_BLOCKED
• BAD_ICC_RESPONSE
• BAD_DATA_FORMAT
• CARD_BLOCKED
• CANDIDATELIST_EMPTY
• CARD_REMOVED
• CHIP_ERROR
• CONFIG_FILE_NOT_FOUND
• EASY_ENTRY_APPL
• EMV_CHIP_ERROR
• E_TAG_NOTFOUND
• EMV_FAILURE
• FAILURE
• FAILED_TO_CONNECT
• INSERT_CARD
• ICC_DATA_MISSING
• INVALID_CAPK_FILE
• NONEMV
• OFFLINE_APPROVED
• OFFLINE_DECLINED
• OFFLINE_NOTALLOWED
• REMOVE_CARD
• SELECT_FAILED
• TRANS_APPROVED
• TRANS_DECLINED
• TRANS_CANCELLED
• USE_CHIP
• USE_MAG_CARD

Return Values
None

118 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

CHAPTER 6

Building an EMV Application

The application should call the EMV Module functions in the appropriate order and
should also perform other application-specific EMV-related actions. This can be
classified in the following two operations:
1 Extract data objects from the DOC (using the EMV Library functions) for
processing application-specific code.
2 Insert data objects into the DOC for processing using the EMV Module
functions.
The two operations can occur in the following scenarios:
• Setting the transaction type.
• Processing of proprietary data objects on a card.
• Batch file data.
• Foreign language support.
• Terminal-to-host communications.

Setting the A data object should be created to record the transaction type (9C tag) being
Transaction performed (for example, sale, cashback, etc.). It consists of one byte, which is a
Type BCD representation of the first two digits of the ISO 8583:1987 (section 4.3.8)
processing code. The relevant values for EMV debit/credit transactions are:

Transaction Type Value

Sale 00
Cash 01
Sale with Cashback 09

The following is a code fragment for a Sale with cashback transaction:

unsigned char ucTransType;
ucTransType = 0x09;
usEMVAddTLVToCollxn(TAG_9C00_TRAN_TYPE, (unsigned char *)&ucTransType,
1);

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 119

B UILDING AN EMV A PPLICATION
TVR/TSI Changes

TVR/TSI When an application has to change the TVR/TSI settings that are not changed by
Changes the EMV Module, the TVR/TSI should be extracted from the DOC, change the bit
setting, and update the DOC.

NOTE
It is recommended that the application should avoid changing the TVR/TSI
directly. Required changes are done by the EMV Module and the EMV Library.

The following code fragment shows how to set the Forced Online bit in the
TVR.
srTxnResult TVRTSI;

usEMVGetTxnStatus(&TVRTSI);
// Set bit in tvr for online forced by merchant
TVRTSI.stTVR[3] |= 0x8;
usEMVSetTxnStatus(&TVRTSI);

The EMV Library provides an API for setting the forced online bit in the TVR/TSI.
Refer to the Verix/Verix V EMV Library Programmers Manual for details.

Proprietary EMV allows data objects on cards that are not defined in the EMV specification.
Data Objects For example, data objects in the range 9F50–9F7F are reserved for payment
systems. Refer to the EMV specifications listed in References section for more
details. If these data objects are found in a card’s file structure, they are extracted
by the application, and placed in the DOC like any other data object.
If a proprietary data object of tag value 0x9F55 with a maximum length of 32 bytes
is to examined or processed, the following code fragment is necessary:
unsigned char ProprietaryData[32];
unsigned short Len;

// Get copy of Proprietary Data Object from Data Object Collection

usEMVGetTLVFromColxn(0x9F55, ProprietaryData, &Len);

// Now process the data

Batch File Data Obtaining data for the batch file (if one is required) consists of using API to extract
relevant data objects from the DOC. The minimum data required for an EMV
batch record is described in the EMV Specifications listed in References section.

120 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

B UILDING AN EMV A PPLICATION
Foreign Language Support

Foreign EMV-compliant terminals have the optional capability to print receipts and display
Language text to the cardholder in the preference language indicated by the card. They can
Support also optimally display the name of applications (for cardholder selection or
confirmation) in the character set (alphabet) indicated by the card.
There are two data objects used in these options: language preference (5F2D tag)
and the issuer code table index (9F11 tag). These data objects can be extracted
from the DOC in the normal way.
Language preference is a list of up to four languages (indicated by two alpha
characters, according to ISO 639), in decreasing order of preference. For
example, a card might contain a language preference that looks like esenfrde.
This indicates that Spanish (es) is the preferred language. If Spanish is not
available, English (en) is acceptable, followed by French (fr) and German (de).
This data object can be accessed any time after application selection.
It is not normally necessary for the application to access the issuer code table
index. It is only necessary if the application supports more than one non-ASCII
character set and can switch fonts according to the language requirements of the
card. The terminal uses one font, making use of an ISO 8859 character set (for
example, ISO 8859-1 that enables the representation of all Western European
languages). The possession of this character set should be reflected in additional
terminal capabilities in the terminal configuration.
As the language selection should be performed before the GPO command is sent
to the card, the application should set the function pointer in the EMV kernel.
Refer to the inVxEMVAPSetFunctionality(PERFORM_LANGUAGE_SEL,
(void*)&vdSelPreferredLang) callback API for more details.

Terminal-to-Host To communicate with a host, the application should perform the following:
Communications
• Copy data objects from the DOC to incorporate them in terminal-to-host data
packets.
• Extract data objects from the host-to-terminal data packets and add them to
the DOC so that the EMV Module function calls can perform Second Generate
AC and external authentication.

Script processing has its own additional data structures that should be filled
correctly.
The minimum requirements for data to be exchanged between the terminal and
the host are set out in the Acquirer Interface section of the EMV Terminal
specification document mentioned in the References section. But there are
additional data objects required by particular terminal-to-host protocols.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 121

B UILDING AN EMV A PPLICATION
Terminal-to-Host Communications

Terminal-to-Host A terminal-to-host packet (authorization or financial transaction request) typically

Packets contains all data required by the CDOL1 data object list (refer to the EMV
Specifications listed in References section for more details), plus the application
cryptogram (9F26 tag) and cryptogram information data (9F27 tag). All of these
data objects can be extracted from the DOC using API.
In addition to authorization or financial transaction request packets, it may
sometimes be necessary to send an online advice message. This occurs when
the transaction is completed offline, but need to inform the host. If an online
advice message is required, the card indicates it by setting a bit in CID (refer to
the EMV Specifications listed in References section for more details).

Host-to-Terminal A host-to-terminal packet (authorization or financial transaction response) always

Packets potentially contains the following three data objects:
• authorization response code (mandatory),
• issuer authentication data (optional), and
• issuer script(s) (optional).
These objects should be extracted and made available for
inVXEMVAPUseHostData() API or a combination of lower level functions.
The ARC (two ASCII characters), which represents the host decision about the
transaction, should be written to the DOC as 0x8A tag using API.
The issuer authentication data (8–16 bytes), which enables the card to
authenticate the issuer, should be written to the DOC as 0x91 tag using API.
Issuer scripts are strings of card commands to be executed sequentially by the
terminal. They enable the issuer to perform operations such as, blocking a card,
changing the frequency with which it goes online, or changing a PIN. Scripts come
in two types:
• Template 1 (to be executed before the Generate AC command), and
• Template 2 (to be executed after the Generate AC command).
Template 1 scripts always start with the byte 0x71 and Template 2 scripts always
start with 0x72. There can be any number of scripts of either type in a single host
response.

Failure to Go If it is not possible to go online to the host, it should be indicated while calling the
Online inVXEMVAPUseHostData() or inVXEMVAPSecondGenerateAC() API. In this
case, the terminal and the card can make a decision whether to authorize offline
transaction or not. This is achieved by setting the host decision argument to
FAILED_TO_CONNECT.

122 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

CHAPTER 7

Implementation

This chapter describes the procedure to implement the EMV Module into your
own payment application.

Transaction This section explains an EMV transaction flow and the EMV Module functions to
Flow call in the sequence.
1 Transaction initialization:

inVXEMVAPTransInit(terminalRecord)
2 Check for card insertion:

inVXEMVCardPresent()
3 Set transaction type:

usEMVAddTLVToCollxn(0x9C00,unsigned char *) &transType,1)

Valid values for transType are:

• 00 = sale
• 01 = cash
• 09 = sale with cashback
CAUTION
The application should update the TLV database with the required terminal tags.

4 Initialize the card:

inVXEMVAPCardInit()
5 Set account type:

usEMVAddTLVToCollxn(0x5F57, &accType, 1)

Valid values for accType are:

• 00 = default
• 10 = savings
• 20 = cheque or debit
• 30 = credit

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 123

I MPLEMENTATION
Online Processing

6 Process the card:

• application selection: inVXEMVAPSelectApplication(...)

• read application data: inVXEMVAPProcessAFL()
• data authentication: inVXEMVAPDataAuthentication()
• processing restrictions and Terminal Risk Management:
inVXEMVAPProcRisk()
• cardholder verification: inVXEMVAPVerifyCardholder()

7 Generate cryptogram and online processing:

• First Generate AC: inVXEMVAPFirstGenerateAC(...)

• evaluate the result using the cryptogram information data (9F27 tag):
usEMVGetTLVFromColxn(0x9F27, &cryptInfoDat, &tagLen)
• 0x00 = declined
• 0x40 = offline approved
• 0x80 = online requested
• perform online connection with authorization host (if needed).
• finish the transaction:
• Second Generate AC: inVXEMVAPSecondGenerateAC(…)
• Script Processing
• External Authenticate

NOTE
Verifone recommends using inVXEMVAPUseHostData(...) to perform the
above operations.

8 Finish the transaction:

• evaluate the final result (read CID; 9F27 tag)
• 0x00 = declined
• 0x40 = approved
• any other value should be interpreted as declined.
• print receipt

9 Power down the card: Terminate_CardSlot(...)

Online This section describes the requirements for application online processing. A
Processing payment application should follow the rules outlined in this section for
EMV Level 2 compliance.

124 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

I MPLEMENTATION
Online Processing

Notes on Online • Add all TLV objects received from the host to the database (excluding data
General from template 71 or 72).
Processing
• If the CID value returned by the card is unknown, assume that it is an AAC.
• The external authenticate process is automatically performed if the necessary
data is available.
• A reversal should be sent if communication with the host is unsuccessful
(even if the transaction is approved offline in Second Generate AC).
• A reversal should also be sent if the transaction is approved by the host, but
declined by the card in the Second Generate AC.
• Do not terminate the transaction even if host declined; allow the card to
perform Second Generate AC.
• Print receipt after the Second Generate AC with the correct value of the
transaction cryptogram. The receipt should contain some additional data: AID,
cryptogram value, TVR, etc.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 125

I MPLEMENTATION
Online Processing

126 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX A

File Formats for Storing CAPKs

This appendix provides the information about the CAPK file, it’s structure and
naming convention.
Certification authority public keys are normally distributed in ASCII format.
1 Each CAPK should have its own configuration file.

2 The file is named as follows:

AAAAAAAAAA.NN

where, AAAAAAAAAA is the RID associated with the CAPK represented as an

ASCII hex number (for example, VISA is A000000003), NN is the CAPK Index
associated with the CAPK.

For example, the CAPK associated with an application with a RID of

A000000003 that contained a CAPK Index (one byte data object) of 0x0C
could be found in the file:
A000000003.OC

3 The structure of the file will be:

3 digit CAPK CAPK Modulus 2 digit CAPK CAPK 40 digits

Modulus length (ASCII hex Exponent Exponent checksum
(ASCII hex representation) length (ASCII (ASCII hex value (ASCII
representation) hex representation) hex
representation) representation)

For example, the file for the first Visa test key (A000000003.01) would contain:
040C2CC423911DC4697CC223F7CBBD82C100FF4313C2D0F06941DBEE34A9D512FAC7957CB
4A03BF16A10103

This key has a 40 byte Modulus and a 1 byte Exponent of 3.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 127

F ILE F ORMATS FOR S TORING CAPK S

128 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX B

File Formats for Revoked Issuer PK CSNs

This appendix provides the structure of each record in a file.

Issuer public key certificate serial numbers that are considered invalid are stored
in the revoked issuer PK CSN files in ASCII format. There is one file for each card
scheme (RID), and each file can contain any number of ICSNs.
Each file record has the following structure:

RID of the card ASCII representation ASCII Hex Carriage Return (CR)/
scheme of 1 byte CAPK Index representation of 3 Line feed (LF)
byte ICSN

For example, if the issuer public key certificates with serial numbers 123456 and
654321 are no longer valid, and that these are associated with the CAPK indices
03 and 04 for the A000000003 card scheme respectively, then the issuer PK CSN
file contains:
A00000000303123456
A00000000304654321

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 129

F ILE F ORMATS FOR R EVOKED I SSUER PK CSN S

130 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX C

Function Pointers of the Callback Function

The function pointer of the EMV Library callback functions, which are
implemented in the application have to be set with EMV Library using
inVXEMVAPSetFunctionality() EMV Module interface function. The function code
parameter of inVXEMVAPSetFunctionality() API indicates the callback function
which is being set. The function pointer parameter provides the function pointer of
the callback API implemented in the application.
Table 6 explains the function codes for each of the callback API that is used with
the inVXEMVAPSetFunctionality() Module API.
Table 6 Function Pointers for Callback APIs
Callback API Function Code
getLastTxnAmt() GET_LAST_TXN_AMT
getTerminalParam() GET_TERMINAL_PARAMETER
getCapkExp() GET_CAPK_DATA
getUsrPin() GET_USER_PIN
getXUsrPin() GET_X_USER_PIN
usEMVDisplayErrorPrompt() DISPLAY_ERROR_PROMPT
usEMVPerformSignature() PERFORM_SIGNATURE
usEMVPerformOnlinePIN() PERFORM_ONLINE_PIN
usEMVIssAcqCVM() PERFORM_ISS_ACQ_CVM
bIsMultipleOccurencesAllowed() IS_PARTIAL_SELECT_ALLOWED
vdPromptManager()vdSelPreferredLang() PERFORM_LANGUAGE_SEL
usGetExtAuthDecision() Get_EXT_AUTH_DECISION
usGetTermAVN() GET_TERMINAL_AVN
usGetPOSDecsn() GET_POS_CVM_DECISION
usGetBypassDecsn() GET_BYPASS_DECISION
usPinInfo() GET_PIN_INFO

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 131

F UNCTION P OINTERS OF THE C ALLBACK F UNCTION

Table 7 explains the usage of the inVXEMVAPSetFunctionality() EMV Module API

to set the callback API function pointers with EMV Library:
Table 7 Usage of inVXEMVAPSetFunctionality() EMV Module API
Description
Callback API Syntax inVXEMVAPSetFunctionality() inVXEMVAPSetFunctionality()
API is called API is not called
inVxEMVAPSetFunctionality The application calls If the inVXEMVAPSetFunctionality()
(GET_LAST_TXN_AMT, (void inVXEMVAPSetFunctionality() API API is not called, then a value of 0 is
*)& getLastTxnAmt) with the syntax during transaction used for the transaction. There will be
initialization. If the no split sales validation.
getLastTxnAmt parameter value
is passed as null, then a default
implementation is used. The default
implementation in the module uses
the amount as 0 for the ulAmt field.
There will be no split sales log file
checks. The application overrides
the default implementation by
implementing the getLastTxnAmt()
API, and passes the appropriate
function to the fnPtrSet
parameter.

inVxEMVAPSetFunctionality The application calls the If the inVXEMVAPSetFunctionality()

(GET_TERMINAL_PARAMETER,(v inVXEMVAPSetFunctionality() API API is not called, then the standard
oid *) & getTerminalParam) with the syntax during transaction implementation of the EMV Module will
initialization. If the be used for the getTerminalParam()
getTerminalParam parameter API.
value is passed as null, then the
EMV Module uses the standard
implementation of the
getTerminalParam() API. If the
application requires a different
implementation for getting the
terminal parameter, then the
application should implement the
getTerminalParam() API, and then
pass the appropriate function to
fnPtrSet.

Standard Implementation: The function pointer of the standard implementation of the getTerminalParam() API is
set using inVXEMVAPSetFunctionality() API in inVXEMVAPTransInit() API during the beginning of each transaction.
Hence, if the application has to override the standard implementation, the function pointer of the application function
should be set in the module after the inVXEMVAPTransInit() function call. If no application function pointer is set or
inVXEMVAPSetFunctionality() API is not called, then the standard implementation is used.

132 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

F UNCTION P OINTERS OF THE C ALLBACK F UNCTION

Table 7 Usage of inVXEMVAPSetFunctionality() EMV Module API (continued)

Description
Callback API Syntax inVXEMVAPSetFunctionality() inVXEMVAPSetFunctionality()
API is called API is not called
inVxEMVAPSetFunctionality The application calls the If inVXEMVAPSetFunctionality() API is
(GET_CAPK_DATA, (void *) & inVXEMVAPSetFunctionality() API not called, then the standard
getCapkExp) with the syntax during transaction implementation of the EMV Module is
initialization. If the getCapkExp used for getCapkExp() API.
parameter value is passed as null,
the EMV Module uses the standard
implementation of the getCapkExp()
API. If the application requires a
different implementation for getting
the CAPK data, only then the
application should implement the
getCapkExp() API, and pass the
appropriate function to fnPtrSet.

Standard Implementation: The function pointer of the standard implementation of the getCapkExp() API is set
using inVXEMVAPSetFunctionality() API in inVXEMVAPTransInit() API during the beginning of each transaction.
Hence, if the application has to override the standard implementation, then the function pointer of the application
function is to be set in the module after the inVXEMVAPTransInit() function call. If no application function pointer is
set or inVXEMVAPSetFunctionality() API is not called, then the standard implementation is used.

inVxEMVAPSetFunctionality The application calls the If the EMV Module is used and the
(GET_USER_PIN, (void *) & inVXEMVAPSetFunctionality() API inVXEMVAPSetFunctionality() API is
getUsrPin) with the syntax during transaction not called, then no default
initialization. If the getUsrPin implementation of the EMV Module will
parameter is passed as null, then be used for getUsrPin() API. Then the
the default implementation in the cardholder verification
EMV Module will be used. The failed and the PIN entry
default function in the EMV Module required, PIN not entered bits
sends a PIN value of 1234 as are set in the TVR.
default PIN.

inVxEMVAPSetFunctionality( The application calls the If the EMV Module is used and the
GET_X_USER_PIN, (void *) inVXEMVAPSetFunctionality() API inVXEMVAPSetFunctionality() API is
&getXUsrPin) with the syntax during transaction not called, then the cardholder
initialization. If the getXUsrPin verification failed and the PIN
parameter is passed as null, then entry required, PIN not
callback will not be invoked. entered bits are set in the TVR.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 133

F UNCTION P OINTERS OF THE C ALLBACK F UNCTION

Table 7 Usage of inVXEMVAPSetFunctionality() EMV Module API (continued)

Description
Callback API Syntax inVXEMVAPSetFunctionality() inVXEMVAPSetFunctionality()
API is called API is not called
inVxEMVAPSetFunctionality The application calls the If the EMV Module is used and the
(DISPLAY_ERROR_PROMPT, inVXEMVAPSetFunctionality() API inVXEMVAPSetFunctionality() API is
(void *) & with the syntax during transaction not called, then there is no display of
usEMVDisplayErrorPrompt) initialization. If the error messages.
usEMVDisplayErrorPrompt
parameter value is passed as null,
the EMV Module uses a default
implementation. The default
implementation returns
EMV_SUCCESS and no error
messages will be displayed on the
terminal. To override the default
implementation, the application
should implement
usEMVDisplayErrorPrompt() API
and display appropriate messages
on the terminal.

inVxEMVAPSetFunctionality The application calls If the EMV Module is used and

(PERFORM_SIGNATURE, (void inVXEMVAPSetFunctionality() API inVXEMVAPSetFunctionality() API is
*) & with the above syntax during not called, then the CVM is considered
usEMVPerformSignature) transaction initialization. If the to be failed. The EMV Module sets the
usEMVPerformSignature cardholder verification
parameter is passed as null, then a failed bit in the TVR to 1 and
default implementation is used and perform the next CVM, if available.
the return value is sent as
EMV_SUCCESS. There will be no
prompting for signature and
validation performed as a part of the
default implementation. The
application should override the
default implementation by
implementing this API.

134 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

F UNCTION P OINTERS OF THE C ALLBACK F UNCTION

Table 7 Usage of inVXEMVAPSetFunctionality() EMV Module API (continued)

Description
Callback API Syntax inVXEMVAPSetFunctionality() inVXEMVAPSetFunctionality()
API is called API is not called
inVxEMVAPSetFunctionality The application calls the If the EMV Module is used and
(PERFORM_ONLINE_PIN, (void inVXEMVAPSetFunctionality() API inVXEMVAPSetFunctionality() API is
*) & with the syntax during transaction not called, then the CVM is considered
usEMVPerformOnlinePIN()) initialization. If the to be failed. The EMV Module will set
usEMVPerformOnlinePIN the cardholder verification
parameter is passed as null, then a failed bit in the TVR to 1 and
default implementation is used and perform the next CVM, if available. The
the return value is sent as EMV Library also sets the Online
EMV_SUCCESS. There will be no PIN entered bit in the TVR to 1, if
prompting for PIN as a part of the the online PIN is the CVM irrespective
default implementation. The of the availability of
application should override the usEMVPerformOnlinePIN() API.
default implementation by
implementing this API.

Note: Online PIN validation is not a part of the EMV Module.

inVxEMVAPSetFunctionality The application calls If the EMV Module is used and

(PERFORM_ISS_ACQ_CVM,(void inVXEMVAPSetFunctionality() API inVXEMVAPSetFunctionality() API is
*) & usEMVIssAcqCVM()) with the syntax during transaction not called, then this scenario is similar
initialization. If the to usEMVIssAcqCVM() API returning
usEMVIssAcqCVM parameter is E_CVM_FAILED. The cardholder
passed as null, then this scenario is verification failed bit in the
similar to usEMVIssAcqCVM() API TVR is set to 1.
returning E_CVM_FAILED and the
kernel considers the CVM process
as failure. The application should
implement usEMVIssAcqCVM() API
and pass a valid pointer.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 135

F UNCTION P OINTERS OF THE C ALLBACK F UNCTION

Table 7 Usage of inVXEMVAPSetFunctionality() EMV Module API (continued)

Description
Callback API Syntax inVXEMVAPSetFunctionality() inVXEMVAPSetFunctionality()
API is called API is not called
inVxEMVAPSetFunctionality The application calls the If the EMV Module is used, and
(IS_PARTIAL_SELECT_ALLOWED inVXEMVAPSetFunctionality() API inVXEMVAPSetFunctionality() or
,(void *) & with the syntax during transaction usEMV_Set_Functionality() API
bIsMultipleOccurencesAllow initialization. If the is not called, then the standard
ed) bIsMultipleOccurencesAll implementation of the EMV Module is
owed parameter value is passed as used for
null, the EMV Module uses the bIsMultipleOccurencesAllowed() API.
standard implementation of the
bIsMultipleOccurencesAllowed()
API in the EMV Module. If the
application requires a different
implementation for getting the
CAPK data, the application should
implement the
bIsMultipleOccurencesAllowed()
API, and pass the appropriate
function to fnPtrSet.

Standard Implementation: The function pointer of the standard implementation of the

bIsMultipleOccurencesAllowed() API is set using inVXEMVAPSetFunctionality() API in inVXEMVAPTransInit() API
during the beginning of each transaction. Hence, if the application has to override the standard implementation, then
the function pointer of the application function is to be set in the module after the inVXEMVAPTransInit() API call. If
no application function pointer is set or inVXEMVAPSetFunctionality() API is not called, then the standard
implementation is used.
inVxEMVAPSetFunctionality( The application calls If the function pointer is not set by the
PERFORM_LANGUAGE_SEL, inVXEMVAPSetFunctionality() API application, then the language
(void*)&vdSelPreferredLang during the transaction initialization. selection which was supposed to
) If the vdSelPreferredLang happen before GPO will not be
parameter value is passed as null, performed.
then the EMV Module will not
invoke the language selection
process before the GPO command
is sent to the card. Application
should implement
vdPromptManager() API and set
this function pointer with the EMV
kernel for the language selection.

136 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

F UNCTION P OINTERS OF THE C ALLBACK F UNCTION

Table 7 Usage of inVXEMVAPSetFunctionality() EMV Module API (continued)

Description
Callback API Syntax inVXEMVAPSetFunctionality() inVXEMVAPSetFunctionality()
API is called API is not called
inVxEMVAPSetFunctionality( The application calls If the function pointer is not set by the
Get_EXT_AUTH_DECISION, inVXEMVAPSetFunctionality() API application, then the EMV kernel will
(void*)& during the transaction initialization. terminate the transaction without
usGetExtAuthDecision) If the usGetExtAuthDecision setting the TVR bit for issuer
parameter value is passed as null, authentication failure.
then the EMV Module will not
consider the application’s decision
whether to terminate or continue
the transaction, if the status word of
external authenticate command
response is 0x6985. Application
should implement
usGetExtAuthDecision() API and
set this function pointer with the
EMV kernel.

inVxEMVAPSetFunctionality( The application calls If the function pointer is not set by the
GET_TERMINAL_AVN, (void*)& inVXEMVAPSetFunctionality() API application, then the terminal
usGetTermAVN) during the transaction initialization. application version numbers present in
If the usGetTermAVN parameter the EST.dat will be used for
value is passed as null, then the application version number
terminal application version comparison between the terminal and
numbers present in the EST.dat the card.
will be used for application version
number comparison between the
terminal and the card.
If the usGetTermAVN parameter
value is not passed as null, then the
application should implement
usGetTermAVN() API and set this
function pointer with the EMV
kernel. This API will be used by the
EMV kernel to consider the multiple
application version numbers
provided by the application for
application version number
comparison between the terminal
and the card.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 137

F UNCTION P OINTERS OF THE C ALLBACK F UNCTION

Table 7 Usage of inVXEMVAPSetFunctionality() EMV Module API (continued)

Description
Callback API Syntax inVXEMVAPSetFunctionality() inVXEMVAPSetFunctionality()
API is called API is not called
inVxEMVAPSetFunctionality( The application calls If the function pointer is not set by the
GET_POS_CVM_DECISION, inVXEMVAPSetFunctionality() API application, then the bypass or cancel
(void*)&usGetPOSDecsn); during the transaction initialization. of the PIN CVM from a POS/external
If the usGetPOSDecsn parameter device feature will be disabled.
value is passed as null, then the
Note: This API is not applicable for
POS/External PIN cancel and PIN Vx UPT EMV Modules.
Bypass features will be disabled.
If the usGetPOSDecsn parameter
is not passed as null, then the
application should implement
usGetPOSDecsn(), which will let
the library know whether the secure
PIN has been requested to be
bypassed or canceled by POS/
external device.

inVxEMVAPSetFunctionality( The application calls If the function pointer is not set by the
GET_BYPASS_DECISION, inVXEMVAPSetFunctionality() API application, then the double PIN
(void*)&usGetBypassDecsn); during the transaction initialization. bypass feature will be disabled.
If the usGetBypassDecsn
Note: This API is not applicable for
parameter value is passed as null, Vx UPT EMV Modules.
then the double PIN bypass feature
will be disabled.
If the usGetBypassDecsn
parameter is not passed as null,
then the application should
implement
usGetBypassDecsn(), which will
let the library know whether the PIN
session should be continued or the
cardholder bypass should be
allowed.

inVxEMVAPSetFunctionality( The application calls If the function pointer is not set by the
GET_PIN_INFO, (void *) inVXEMVAPSetFunctionality() API application, then the existing
&usPinInfo); with the syntax during transaction functionality of PIN bypass with no PIN
initialization. The EMV kernel is digits will still be supported.
enhanced to allow PIN bypass even
Note: This API is not applicable for
when PIN digits are present. This is Vx UPT EMV Modules.
performed by providing the key
press information along with the
number of PIN digits entered to the
application through this callback
function. The application can
indicate if the PIN needs to be
bypassed.

138 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX D

Second Application Version Number in EST

This appendix describes the second application version number in EST. EST
supports two different application version numbers for the finally selected AID.
During the application version number checking, the EMV kernel follows the steps
provided below:
1 For the finally selected AID, compare the card application version number
with the first terminal application version number. If this version number
matches, then second application version number need not be compared
against the card application version number.
2 If the card application version number does not match against the first
terminal application version number present in the EST, then the second
application version number is validated for the existence in the EST and
compared against this value. If there is no match found, then TVR bit is set
for "ICC and terminal have different application versions".
3 Finally in the 0x9F09 tag, terminal application version number is updated
with the first terminal application version number or with the second terminal
application version number for which the card application version number
matches.

NOTE • The EMV kernel stores the second terminal application version number in a
kernel defined tag.
• If the card application does not match with both first and second terminal
application version numbers, then the 0x9F09 tag will have the first terminal
application version number.
• If the application does not want EMV kernel to perform the second application
version number checking, then the EST should not have any value specified
for the second terminal application number field.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 139

S ECOND A PPLICATION VERSION N UMBER IN EST

140 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX E

Generic Values Returned by the Library

The specific return values for each function are mentioned in the corresponding
functions. This appendix lists the other possible return values returned by the
library depending on the specific card condition.

APPL_BLOCKED Application in the ICC is blocked.

0x6985 Conditions of use not satisfied.

0x6700 Process aborted due to a wrong length. No further action.

0x6D00 Process aborted due to an invalid or not supported instruction

code. No further action.

0x6400 State of non-volatile memory unchanged.

0x6300 State of non-volatile memory changed. No information given.

0x6A83 Wrong parameter(s) P1-P2. Record not found.

0x6A88 Wrong parameter(s) P1-P2. Referenced data not found.

0x6E00 Class not supported.

0x6283 ICC blocked.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 141

G ENERIC VALUES R ETURNED BY THE L IBRARY

142 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX F

Sample Files

This chapter lists the sample configuration files. Click on these links to view
sample code for each configuration file.

EST and MVT Sample EST.txt

Files
Sample MVT.txt

ADK Sample EMV_Applications.XML

Configuration
Sample EMV_Keys.XML
Files
Sample EMV_Terminal.XML

XML Sample EST.XML

Configuration
Sample keys.XML
Files
Sample MVT.XML

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 143

S AMPLE F ILES
XML Configuration Files

144 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX G

Relevant EMV Data Objects

This appendix provides coding for specific data elements that control the
transaction flow in the terminal or record the status of processing for the
transaction.
In the following tables,
• ‘1’ indicates that if the bit has the value ‘1’, the corresponding ‘Meaning’
applies,
• ‘x’ indicates that the bit does not apply.
Set the data (bytes or bits) marked as RFU to ‘0’.
The following data structures are described in this section:
• Application Interchange Profile (AIP)
• Application Usage Control
• Terminal Verification Results (TVR)
• Transaction Status Information (TSI)
• Terminal Capabilities
• Additional Terminal Capabilities
• Terminal Type
• Cardholder Verification Rule Format

Application Byte 1: (Leftmost)

Interchange b8 b7 b6 b5 b4 b3 b2 b1 Meaning
Profile (AIP)
0 RFU

1 SDA supported.

1 DDA supported.

1 Cardholder verification supported.

1 Perform Terminal Risk Management.

1 Issuer authentication supported.

0 RFU

1 CDDA/AC supported.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 145

R ELEVANT EMV D ATA O BJECTS
Application Usage Control

Byte 2: (Rightmost)

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

Application Byte 1: (Leftmost)

Usage Control b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 Valid for domestic cash transactions.

1 Valid for international cash transactions.

1 Valid for domestic goods.

1 Valid for international goods.

1 Valid for domestic services.

1 Valid for international services.

1 Valid at ATMs.

1 Valid at terminals other than ATMs.

Byte 2: (Rightmost)

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 Domestic cashback allowed.

1 International cashback allowed.

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

146 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

R ELEVANT EMV D ATA O BJECTS
Terminal Verification Results (TVR)

Terminal Byte 1: (Leftmost)

Verification b8 b7 b6 b5 b4 b3 b2 b1 Meaning
Results (TVR)
1 Offline data authentication was not
performed.

1 Static data authentication failed.

1 ICC data missing.

1 Card appears on terminal/ECR exception

file.

1 Dynamic data authentication failed.

1 Combined DDA/AC generation failed.

1 SDA selected.

0 RFU

Byte 2:

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

ICC and terminal have different application

1
versions.

1 Expired application.

1 Application not yet effective.

Requested service not allowed for card

1
product.

1 New card.

0 RFU

0 RFU

0 RFU

Byte 3:

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 Cardholder verification unsuccessful.

1 Unrecognized CVM.

1 PIN try limit exceeded.

PIN entry required and PINpad not present

1
or not working.

PIN entry required, PINpad present but PIN

1
not entered.

1 Online PIN entered.

0 RFU

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 147

R ELEVANT EMV D ATA O BJECTS
Transaction Status Information (TSI)

0 RFU

Byte 4:

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 Transaction exceeds floor limit.

1 Lower consecutive offline limit exceeded.

1 Upper consecutive offline limit exceeded.

Transaction selected randomly for online

1
processing.

1 Merchant forced transaction online.

0 RFU

0 RFU

0 RFU

Byte 5: (Rightmost)

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 Default TDOL used.

1 Issuer authentication unsuccessful.

Script processing failed before Final

1
Generate AC.

Script processing failed after Final Generate

1
AC.

0 RFU

0 RFU

0 RFU

0 RFU

Transaction Byte 1: (Leftmost)

Status b8 b7 b6 b5 b4 b3 b2 b1 Meaning
Information
(TSI) 1 Offline data authentication performed.

1 Cardholder verification performed.

1 Card risk management performed.

1 Issuer authentication performed.

1 Terminal risk management performed.

1 Script processing performed.

0 RFU

148 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

R ELEVANT EMV D ATA O BJECTS
Terminal Capabilities

0 RFU

Byte 2: (Rightmost)

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

Terminal Byte 1: Card Data Input Capability

Capabilities b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 Manual key entry.

1 Magnetic stripe.

1 IC with contacts.

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

Byte 2: CVM Capability

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 Plaintext PIN for ICC verification.

1 Enciphered PIN for online verification.

1 Signature (paper).

1 Enciphered PIN for ICC verification.

1 No CVM.

0 RFU

0 RFU

0 RFU

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 149

R ELEVANT EMV D ATA O BJECTS
Additional Terminal Capabilities

When the terminal supports Signature CVM, the terminal is an attended terminal
(Terminal Type = ‘x1’, ‘x2’, or ‘x3’) and should support a printer (Additional
Terminal Capabilities, byte 4, Print, attendant bit = ‘1’).
Byte 3: Security Capability

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 SDA

1 DDA

1 Card capture.

0 RFU

1 CDDA/AC supported.

0 RFU

0 RFU

0 RFU

Additional Byte 1: Transaction Type Capability

Terminal b8 b7 b6 b5 b4 b3 b2 b1 Meaning
Capabilities
1 Cash

1 Goods

1 Services

1 Cashback

1 Inquiry

1 Transfer

1 Payment

1 Administrative

• An inquiry is a request for information about one of the cardholder’s accounts.

• A transfer is movement of funds by a cardholder from one accounts to
another, both accounts are held by the same financial institution.
• A payment is a movement of funds from a cardholder account to another party,
for example, a utility bill payment.

150 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

R ELEVANT EMV D ATA O BJECTS
Additional Terminal Capabilities

Byte 2: Transaction Type Capability (continued)

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 Cash deposit.

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

0 RFU

Byte 3: Terminal Data Input Capability

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 Numeric keys

1 Alphabetic and special character keys.

1 Command keys

1 Function keys

0 RFU

0 RFU

0 RFU

0 RFU

Byte 4: Terminal Data Output Capability

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 Print, attendant

1 Print, cardholder

1 Display, attendant

1 Display, cardholder

0 RFU

0 RFU

1 Code table 10

1 Code table 9

• If the terminal is attended (terminal type = ‘x1’, ‘x2’, or ‘x3’) and there is only
one printer, the Print, attendant bit is set to ‘1’ and the Print,
cardholder bit is set to ‘0’.
VERIX/VERIX V EMV MODULE REFERENCE MANUAL 151
R ELEVANT EMV D ATA O BJECTS
Terminal Type

• If the terminal is attended and there is only one display, the Display,
attendant bit is set to ‘1’ and the Display, cardholder bit is set to ‘0’.
• If the terminal is unattended (terminal type = ‘x4’, ‘x5’, or ‘x6’), the Print,
attendant and Display, attendant bits are set to ‘0’.
• The code table number refers to the corresponding part of ISO 8859.
Byte 5: Terminal Data Output Capability (continued)

b8 b7 b6 b5 b4 b3 b2 b1 Meaning

1 Code table 8

1 Code table 7

1 Code table 6

1 Code table 5

1 Code table 4

1 Code table 3

1 Code table 2

1 Code table 1

Terminal Type Operational Control Provided By:

Financial
Environment Merchant Cardholder
Institution

Attended

Online only 11 21
Offline with online capability 12 22
Offline only 13 23

Unattended

Online only 14 24 34
Offline with online capability 15 25 35
Offline only 16 26 36

• Terminal Types ‘14’, ‘15’, and ‘16’ with cash disbursement capability
(Additional Terminal Capabilities, byte 1, cash bit = ‘1’) are considered ATMs.
• All other Terminal Types are not considered ATMs.
• An APACS Standard 40 terminal has a terminal type of ‘22.’

152 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

R ELEVANT EMV D ATA O BJECTS
Cardholder Verification Rule Format

Cardholder Byte 1 (Leftmost): Cardholder Verification Method (CVM) Codes

Verification b8 b7 b6 b5 b4 b3 b2 b1 Meaning
Rule Format
0 RFU

Fail cardholder verification if this CVM is

0
unsuccessful.

Apply succeeding CVR if this CVM is

1
unsuccessful.

0 0 0 0 0 0 Fail CVM processing.

Plaintext PIN verification performed by

0 0 0 0 0 1
ICC.

0 0 0 0 1 0 Enciphered PIN verified online.

Plaintext PIN verification performed by

0 0 0 0 1 1
ICC and signature (paper).

Enciphered PIN verification performed by

0 0 0 1 0 0
ICC.

Enciphered PIN verification performed by

0 0 0 1 0 1
ICC and signature (paper).

Values in the range 000110-011101 are

0 reserved for use by the EMV
specification.

0 1 1 1 1 0 Signature (paper).

0 1 1 1 1 1 No CVM required.

Values in the range 100000-101111

1 0 reserved for use by individual payment
systems.

Values in the range 110000-111110

1 1
reserved for use by the issuer.

1 1 1 1 1 1 This value is unavailable.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 153

R ELEVANT EMV D ATA O BJECTS
Cardholder Verification Rule Format

Byte 2 (Rightmost): Condition Codes

Value Meaning

‘00’ Always

‘01’ If unattended cash.

‘02’ If neither unattended cash nor manual cash nor purchase with cashback.

‘03’ If terminal supports the CVMa.

‘04’ If manual cash.

‘05’ If purchase with cashback.

‘06’ If transaction is in the application currencyb and is under X value.

‘07’ If transaction is in the application currency and is over X value.

‘08’ If transaction is in the application currency and is under Y value.

‘09’ If transaction is in the application currency and is over Y value.

‘0A’ - ‘7F’ RFU

‘80’ - ‘FF’ Reserved for use by individual payment systems.

a. For an offline PIN CVM, this means ‘If offline PINpad present’. For an online PIN CVM, this
means ‘If online PINpad present.’
b. That is, TCC = ACC.

154 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX H

Terminal Category Code

The following table lists the Terminal Category Code values and their descriptions:
Table 8 Terminal Category Code Values
Terminal Category Code
Description
Value
A Automobile/Vehicle Rental
C or Z Cash Disbursement
F Restaurant
H Hotel/Motel
O College/School Expense
O Hospital
P Payment Transaction
R All Other Merchants/U.S. Post Exchange
T All Other Non Face-to-Face Transaction
U Unique Transaction Quasi-Cash Disbursement
U or R Cardholder-Activated Terminal (CAT level 1, 2, 3, and
4)
X Airline
X Railroad
X Travel Agency/Transportation

The default values for Terminal Category Code are:

• Z - denotes ATM
• U - denotes CAT
• R - denotes POS
• C - denotes Manual Cash

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 155

TERMINAL C ATEGORY C ODE

156 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX I

EMV Configuration Data Update

The kernel is enhanced to support the requirement of certain regions where the
EMV configuration data is setup and maintained by application integrators who do
not have a build environment to generate the EST.dat and MVT.dat files. To
meet this requirement the EMV kernel is enhanced to accept the configuration
data. The main advantage of this feature is that these files can be downloaded
directly to the terminal in their format. They do not have to be converted to the
binary format as in the case of the EST.txt and MVT.txt before loading it to the
terminal. The kernel will read the data from these text based files and create the
EST.dat and MVT.dat. This feature is supported to only those applications
unable to provide the configuration data in the expected EST.dat and MVT.dat
format.
The Input configuration files can be in any of the following formats.
• Option 1 – EST.dat, MVT.dat
• Option 2 - ICCDATA.DAT, ICCKEYS.KEY
• Option 3 – ADK Configuration files EMV_CTLS_Applications.XML,
EMV_CTLS_Keys.XML and EMV_CTLS_Terminal.XML
• Option 4 – MVT.XML, EST.XML, KEYS.XML
Option1 - there is no specific processing required.
Option2 - the GenConfig library supports text based file formats. The kernel will
read the data from the text based files and creates the EST.dat and MVT.dat.
This feature is supported to only applications unable to provide the configuration
data in the expected EST.dat and MVT.dat formats. The text based input is
accepted from the two files namely, ICCKeys.key and ICCData.dat files. The
format of the data in these files are described in the ICCKey File Data and
ICCData File Data sections.
Option3 - the GenConfig library is enhanced to support ADK XML files. The
kernel reads the data from the XML based files, and creates the EST.dat and
MVT.dat. The format of the data in these files are described in the ADK
Configuration XML file sections.
Option4 - the GenConfig library is enhanced to support EST and MVT in XML
formats. The format of the data in these files are described in the EST/MVT XML
files sections.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 157

EMV C ONFIGURATION D ATA U PDATE

If the application is using the new configuration file formats, then it has to call the
inVXEMVAPConvertConfigData() API with the function arguments as file
format used. For this, the application has to link to genconfig library and download
the same to the terminal. The application is expected to call this API only once
after the terminal reboot before calling the first API of the EMV kernel,
inVXEMVAPSCInit().

158 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV C ONFIGURATION D ATA U PDATE
inVXEMVAPConvertConfigData()

inVXEMVAPConvertConfigData()

If the application is using the new configuration file formats, then it has to call the
inVXEMVAPConvertConfigData() API with the function arguments as
TYPE_DIONE, TYPE_ADK or TYPE_XML based on the selected combination of
file formats. The application is expected to call this API only once after the
terminal reboot before calling the first API of the EMV kernel,
inVXEMVAPSCInit(). This API is used to support EMV terminal configuration
files in three formats
• TYPE_DIONE
When inVXEMVAPConvertConfigData() is called with TYPE_DIONE, the
input ICCKEYS.key file is converted into the expected configuration files,
EST.dat and MVT.dat. It also creates the CAPK files and converts the input
ICCDATA.dat file into multiple data files, which contain the TLVs to be updated
in the global TLV collection of EMV kernel upon request from the application.
• TYPE_ADK
When inVXEMVAPConvertConfigData() is called with TYPE_ADK, the
input XML files, EMV_CTLS_Applications.XML, EMV_CTLS_Keys.XML
and EMV_CTLS_Terminal.XML are converted into the expected
configuration files, EST.dat and MVT.dat.
• TYPE_XML
When inVXEMVAPConvertConfigData() is called with TYPE_XML, the
input XML files, MVT.XML, EST.XML and KEYS.XML are processed to the
database. CAPK file format will be retained in the same format as before. Only
the CAPK file names will be mentioned in the new XML file.

Prototype int inVXEMVAPConvertConfigData (short shConfigOption);

Parameters
Input: shConfigOption Should pass as per the configura-
tion files to be used.
TYPE_DIONE, TYPE_ADK and
TYPE_XML

Return Values
Success: GEN_CONFIG_SUCCESS If the parsing has completed
successfully with the creation of
EST.dat and MVT.dat.

Failure: GEN_CONFIG_FAILURE If parsing config file fails.

GEN_CONFIG_INVALID_PARAMETER If the value of config file is invalid

or not available.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 159

EMV C ONFIGURATION D ATA U PDATE
inVXEMVAPConvertConfigData()

NOTE Once the parsing of the input files is complete and successful, the EMV Module
deletes the existing EST.dat and MVT.dat files and renames the new files
created to EST.dat and MVT.dat in case of TYPE_DIONE and TYPE_ADK.
The application needs to calculate the CRC of the input files upon boot up and
invoke inVXEMVAPConvertConfigData() API to check if the files have
changed, and conversion is required.

160 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV C ONFIGURATION D ATA U PDATE
inVxEMVAPUpdateConfigData()

inVxEMVAPUpdateConfigData()

The application calls this API to override the finally selected AID's MVT terminal
data with a different set of data present in the ICCDATA.dat input file.

Prototype int inVxEMVAPUpdateConfigData(const char* chBlockValue);

Parameters
Input: chBlockValue Name of the block from which the
values should be updated in the
global TLV collection.
Example: "00", "02", etc.

Return Values
Success: GEN_CONFIG_SUCCESS If the new set of values are
successfully updated in the global
TLV collection.

Failure: GEN_CONFIG_FAILURE If updating of the global TLV

collection with the new set of
values fails.

GEN_CONFIG_INVALID_PARAMETER If the value of chBlockValue is

not valid.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 161

EMV C ONFIGURATION D ATA U PDATE
usModifyESTXML()

usModifyESTXML()

This API is applicable for TYPE_XML configuration. The application should call
this API to:
1 EMV_UPDATE_ONE_RECORD - update an existing record from the internal
database to EST.XML file.
2 EMV_CLEAR_ONE_RECORD - clear an existing record in the EST.XML file

3 EMV_CLEAR_ALL_RECORDS - clear all the records in the EST.XML file and

delete the EST.XML file from the terminal.
4 EMV_ADD_NEW_RECORD - add a new record to the existing EST.XML file.

5 EMV_UPDATE_ALL_RECORD - update all the records from the internal

database to the EST.XML file.

Prototype unsigned short usModifyESTXML(char *szAIDstr, EMV_HANDLE_RECORD_TYPE

HandleType, srESTRecord *srNewRecord);

Parameters
Input: HandleType The handle should be one of the following values
as per the usage of this API:
EMV_UPDATE_ONE_RECORD/
EMV_CLEAR_ONE_RECORD/
EMV_CLEAR_ALL_RECORDS/
EMV_ADD_NEW_RECORD/
EMV_UPDATE_ALL_RECORD
szAIDstr Specify the AID which needs to be updated/
cleared from the internal database to/from the
EST.XML file.
This is used for EMV_UPDATE_ONE_RECORD
and EMV_CLEAR_ONE_RECORD.
This should be NULL for all other handles.
srNewRecord This is used for EMV_ADD_NEW_RECORD.
Specify the new record in srESTRecord format to
be added to the EST.XML file.
This should be NULL for all other handles.

Return Values
Success: EMV_SUCCESS Record updated/cleared/created
successfully.

Failure: INVALID_PARAMETER Failure to update/clear/create

record or parameter specified is
incorrect.

162 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV C ONFIGURATION D ATA U PDATE
usModifyMVTXML()

usModifyMVTXML()

This API is applicable for TYPE_XML configuration. The application should call
this API to:
1 EMV_UPDATE_ONE_RECORD - update an existing record from the internal
database to MVT.XML file.
2 EMV_CLEAR_ONE_RECORD - clear an existing record in the MVT.XML file

3 EMV_CLEAR_ALL_RECORDS - clear all the records in the MVT.XML file and

delete the EST.XML file from the terminal.
4 EMV_ADD_NEW_RECORD - add a new record to the existing MVT.XML file.

Prototype unsigned short usModifyMVTXML(EMV_HANDLE_RECORD_TYPE HandleType, MVT_REC

*srRec, int inRecNum);

Parameters
Input: HandleType The handle should be one of the following values
as per the usage of this API:
EMV_UPDATE_ONE_RECORD/
EMV_CLEAR_ONE_RECORD/
EMV_CLEAR_ALL_RECORDS/
EMV_ADD_NEW_RECORD/
inRecNum Specify the record number which needs to be
updated/cleared from the internal database to/from
the MVT.XML file.
This is used for EMV_UPDATE_ONE_RECORD
and EMV_CLEAR_ONE_RECORD.
This should be NULL for all other handles.
srRec This is used for EMV_ADD_NEW_RECORD.
Specify the new record in MVT_REC format to be
added to the MVT.XML file.
This should be NULL for all other handles.

Return Values
Success: EMV_SUCCESS Record updated/cleared/created
successfully.

Failure: INVALID_PARAMETER Failure to update/clear/create

record or parameter specified is
incorrect.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 163

EMV C ONFIGURATION D ATA U PDATE
usModifyKEYSXML()

usModifyKEYSXML()

This API is applicable for TYPE_XML configuration. The application should call
this API to:
1 EMV_CLEAR_ONE_RECORD - clear an existing record in the keys.XML
file
2 EMV_CLEAR_ALL_RECORDS - clear all the records in the MVT.XML file and
delete the keys.XML file from the terminal.
3 EMV_ADD_NEW_RECORD - add a new record to the existing keys.XML
file.

Prototype unsigned short usModifyKEYSXML(char *szCAPKFileName,

EMV_HANDLE_RECORD_TYPE HandleType,
srKEYSRecord *srRec);

Parameters
Input: HandleType The handle should be one of the following values
as per the usage of this API:
EMV_CLEAR_ONE_RECORD/
EMV_CLEAR_ALL_RECORDS/
EMV_ADD_NEW_RECORD/
srRec Specify the CAPK filename (in srKEYSRecord
format) which needs to be added to the keys.XML
file.
This is used for EMV_ADD_NEW_RECORD.
This should be NULL for all other handles.
szCAPKFileName This is used for EMV_CLEAR_ONE_RECORD.
Specify the CAPK filename to be removed from
keys.XML file.
This should be NULL for all other handles.

Return Values
Success: EMV_SUCCESS Record updated/cleared/created
successfully.

Failure: INVALID_PARAMETER Failure to update/clear/create

record or parameter specified is
incorrect.

164 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV C ONFIGURATION D ATA U PDATE
inVXEMVAPGetLastErrCode()

inVXEMVAPGetLastErrCode()

This API is used to get the last error code. Application should call this API to know
where exactly the error has occurred. Whenever there is an error within the library,
the library will set the error code based on the kind of error that has occurred.

Prototype unsigned short inVXEMVAPGetLastErrCode (void);

Parameters
None

Return Values
Error code value

The following are the error codes:

Error Code Value Description

GEN_CONFIG_INVALID_PARAMETER -1 When input arguments to
inVXEMVAPConvertConfigData() API and
inVxEMVAPUpdateConfigData() API are invalid or NULL.
CONFIG_KEY_FILE_NOT_FOUND -2 When ICCKEYS.KEY file is not present.
EST_FILE_CREATE_ERROR -3 Error creating EST.dat.
MVT_FILE_CREATE_ERROR -4 Error creating MVT.dat.
BUF_SIZE_ERROR -5 Returned when there is a buffer overflow.
GEN_CONFIG_FAILURE 0 Failure in creating dat files.
GEN_CONFIG_SUCCESS 1 Success.
CAPK_FILE_CREATE_ERROR -6 Error creating CAPK file.
CONFIG_DATA_FILE_NOT_FOUND -7 ICCDATA.dat is not present.
DAT_FILE_CREATE_ERROR -8 Error creating .dat files. E.g., 00.dat, 09.dat etc.
INVALID_KEYWORD -9 Returned when invalid keyword is found.
AID_FILE_ERROR -10 Failure in creating or processing of AID.dat.
EXP_DATE_ERROR -11 When date is invalid.
WRONG_CAPK_DATA -12 When CAPK Modulus or Exponent data is invalid.
CAPK_DATA_ERROR -13 When CAPK data is in not valid format.
GEN_RID_FORMAT_ERROR -14 When there is format error in key file i.e., if AID encountered
before RID section.
GEN_AID_FORMAT_ERROR -15 When there is format error in key file i.e., if CAPK data found
before any AID.
GEN_DEFAULT_SEC_ERROR -16 When there are no mandatory fields present.
BLOCK_DAT_FILE_NOT_FOUND -17 When the .dat file is missing i.e., the block dat file to be
updated in collection is missing. E.g., 00.dat is missing.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 165

EMV C ONFIGURATION D ATA U PDATE
ICCKey File Data

ICCKey File The data from the ICCKeys.key file is used to create EST.dat and MVT.dat
Data files. This file should contain the RID, AID and CAPK values to be supported by
the application.
Refer to Appendix J for more details on the format of a sample ICCKeys.key file.
The initial content of file has values for creation of the default record of the MVT
file. The file has two sections:
• RID definition section
• CAPK definition section

RID definition section

The RID definition section starts with the title '[RID]' followed by the RID value in
the following record. The RID value may be followed by any number of data object
definitions. If the object values are common to every AID, then it is placed under
the RID.
The format of each object definition record is 'KEYWORD=value'.
Refer to Appendix J for details on the valid keywords.
The AID definition section starts with the title [AID] followed by the AID value in the
following record. The first ten hexadecimal digits should be the same as the RID
value. The AID value may be followed in the same record by a hyphen (-) and a
recommended application name, which is used if the application label is not
available in the card.
For example:
[AID]
A0000000050001-MAESTRO
The next parameter for an AID is the word PARTIAL to indicate that the AID
supports partial selection. This is optional but, if present, it should be the only
word in the record.
For example:
PARTIAL
The next parameter for an AID is the active period for this AID. This takes the
following format:
[Active]
FromDate-ToDate
Each date is of the YYYYMMDD format.

166 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

EMV C ONFIGURATION D ATA U PDATE
ICCData File Data

The next (optional) parameter is usually a 'Domestic' requirement to be able to

ignore an AID (i.e., exclude from the Candidate List) if the AID currently being
defined also exists. For example, if both International Maestro and Domestic
Maestro application exist and are supported, then the Domestic Maestro should
be auto selected in preference. This takes the following format:
[IGNORE]
The AID is to be ignored.

CAPK definition section

The AID definition sections for the RID are followed by the CAPK definition
sections for that particular RID. Each CAPK definition section starts with a hash
(#) in the first byte of the record immediately followed by the hexadecimal value of
the CAPK Index.
Optionally, the CAPK Index may be followed by a space, and then the forty
hexadecimal digits, which form the SHA-1, hash of the public key. If this hash
value is present, then it will be added to the CAPK file. The EMV kernel will then
verify the authenticity of the CAPK file during the transaction flow.
The remainder of the CAPK definition section is in two parts:
• The first part defines the modulus of the public key. This starts with '[Modulus]'
as the only content of the record. Following this is the validity period of the key
and, in the following records, the key itself is in hexadecimal. A blank record
must follow the key value.
• The second part defines the exponent of the public key. This starts with
'[Exponent]' as the only content of the record followed by the exponent value
in the following record.

NOTE The following data elements are mandatory and should be present in the default
record of the ICCKeys.key file: Terminal Capabilities, Additional Terminal
Capabilities and Terminal Type.

ICCData File The data from the ICCData.dat is used to update the global TLV collection. The
Data file contains multiple blocks with a block identifier for each block.
Refer to Appendix J for details on the format of a sample ICCData.dat file.

Limitations The following fields required for the EST and MVT data files creation are not
present in the new input file formats. The default value for each of these is also
indicated.
MVT.dat -
• TRM data present field (1)
• Scheme reference (-1)
• Issuer reference (-1)

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 167

EMV C ONFIGURATION D ATA U PDATE
Backward Compatibility

• EMVCounter=0
• NextRecord=-1
• Automatic Application Selection = 0
• Black listed card support (1)
• Merchant forced online (1)
• Automatic Application selection flag (0)
• Fallback allowed flag (0)
• Modify candidate list flag (1)
• Application selection and GPO separation flag (0)
Default values within () as mentioned above will be assumed for the above fields
as they are not present in the input file.

Backward The EMV configuration update from the text based input files is an optional
Compatibility feature provided by the EMV kernel. Applications to use this feature need to link
with the new library and invoke inVXEMVAPConvertConfigData() API else
applications can continue to provide the EMV configuration data in the EST.dat
and MVT.dat files.

NOTE • Applications that choose to use this feature will see an additional processing
time taken by the kernel to convert the ICCKeys.key and ICCData.dat
files to EST and MVT files. This is a one-time operation and will not have an
impact on the transaction performance.
• The keyword ACTIVE will not be processed by the library.
• inVxEMVAPUpdateConfigData() API will update only the tags that are
defined according to the BER-TLV rules to the collection. Keywords like
TDOL and DDOL will not be updated.

168 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX J

Sample Format Files

This appendix lists sample configuration files, and describes the keywords used in
ICCKeys.key file.

Config File as This section provides the sample ICCKEYS.key and ICCData.dat file formats:
Text Format MTBRS Maximum Target Percentage for Biased Random Selection

TPRS Target Percentage for Random Selection

TVBRS Threshold Value for Biased Random Selection

TRCC Transaction Reference Currency Conversion

TACDF Terminal Action Code Default

TACDN Terminal Action Code Denial

TACOL Terminal Action Code Online

9FTAC Terminal Action Codes (TACDF, TACDN, TACOL concatenated)

Floor Floor Limit

DTDOL Default TDOL

STAVN Secondary Application version number

Following table lists and describes the keywords used in ICCKeys.key file:

ICCKeys.key The following is the sample ICCKeys.key file:

ICS=YYYYNYYYYYNNYYNYNNNNNYYYYYYNYYNNNNNNNNNYYYNYNYNYYYYYYYYYYYYNYYNNYNY
NYYNYY,22,826,248,3 2^16+1,81

9F1B = Terminal floor limit

9F1A = Terminal Country code

5F2A = Transaction currency code

5F36 = Transaction currency exponent

9F33 = Terminal capabilities

9F40 = Additional terminal capabilities

9F35 = Terminal type

9F15 = Merchant category code

SHRFU1 = The first short RFU field value to indicate the CDA mode and if
inVXEMVAPSelectApplication() API should perform application selection
and GPO

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 169

S AMPLE F ORMAT F ILES
Config File as Text Format

[RID]

A000000003

TDOL=9F02065F2A029A039C0195059F3704

DDOL=9F3704

9F1A=826

[AID]

A0000000031010-VISA

PARTIAL

[Active]

19980101-20491231

[9F09]

008C

[STAVN]

0001

[9F1D]

FFFF

[9FTAC]

D84000A8000010000000D84004F800

[Floor]

01F4

#99 4ABFFD6B1C51212D05552E431C5B17007D2F5E6D

[Modulus]

19980101-20491231

AB79FCC9520896967E776E64444E5DCD

D6E13611874F3985722520425295EEA4

BD0C2781DE7F31CD3D041F565F747306

EED62954B17EDABA3A6C5B85A1DE1BEB

9A34141AF38FCF8279C9DEA0D5A6710D

08DB4124F041945587E20359BAB47B75

75AD94262D4B25F264AF33DEDCF28E09

615E937DE32EDC03C54445FE7E382777

[Exponent]

03

170 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

S AMPLE F ORMAT F ILES
Config File as Text Format

NOTE • Tag 9F1D mentioned above will not be added to the collection. It is the
responsibility of the application developers to add it to the collection.
• ICS field mentioned above in sample ICCKEYS.key file is not a mandatory
field.

ICCData File The following is the sample ICCData file:

#01

9F01=000001

9F40=5000E0A001

9F15=1234

9F16=012345678901234

9F33=E0B8C0

9F1A=826

9F35=22

5F2A=826

5F36=2

9F3C=826

9F3D=2

TDOL=9F02065F2A029A039C0195059F3704

DDOL=9F3704

TRCC=1

#00

9F01=000066

9F40=5000E0A001

9F15=1234

9F16=012345678901234

9F33=E0B8C0

9F1A=826

9F1B=0000

9F35=22

5F2A=826

5F36=2

9F3C=826

9F3D=2

TDOL=9F0206

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 171

S AMPLE F ORMAT F ILES
Config File as Text Format

TRCC=1

$Revision:20091214115827 $

NOTE
The following keywords will be ignored if present in the ICCDATA.dat file
TACDF, TACDN, TACOL, VACDF, VACDN, VACOL, MTBRS, TPRS, TVBRS.

172 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

S AMPLE F ORMAT F ILES
Config File as XML Format

Config File as This section provides the sample EST, Keys and MVT XML files:
XML Format

NOTE
Applications using XML format should call vdSetConfigOption() API by
passing TYPE_XML parameter.

EST.XML File The following is the sample EST.XML file:

<ESTData>
<SCHEME NAME="SCHEME_1">
<MVTRecord>1</MVTRecord>
<AID VALUE= "A0000000031010">
<PartialNameAllowed>2</PartialNameAllowed>
<AVN1>008C</AVN1>
<AVN2>008C</AVN2>
<RecommendedAppName>AN08</RecommendedAppName>
</AID>

<AID VALUE= "nnn">

...
</AID>
</SCHEME>
<SCHEME NAME= "SCHEME_2">
<MVTRecord >2</MVTRecord>
<AID VALUE= "A0000000041010">
...
</AID>
</SCHEME>
...
<SCHEME NAME= “SCHEME_N”>
...
</SCHEME>
</ ESTDATA >

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 173

S AMPLE F ORMAT F ILES
Config File as XML Format

Keys.XML File The following is the sample keys.XML file:

<KeysData>
<SCHEME NAME="SCHEME_1">
<CAPK NAME="A000000003.53">
<PublicKeyIndex>83</PublicKeyIndex >
<CAPKExpDate>311220</CAPKExpDate>
</CAPK>
<CAPK NAME="nnn">
...
</CAPK>
</SCHEME>
<SCHEME NAME="SCHEME_2">
<CAPK NAME="A000000004.00">
...
</CAPK>
</SCHEME>
</KeysData>

NOTE
As shown above the CAPK file format will be retained in the same format as
before. Only the CAPK file names will be mentioned in the new XML file.

174 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

S AMPLE F ORMAT F ILES
Config File as XML Format

MVT.XML File The following is the sample MVT.XML file:

<MVTData>
<Record ID="0">
<SchemeReference>-1</SchemeReference>
<IssuerReference>-1</IssuerReference>
<TRMDataPresent>1</TRMDataPresent>
<EMVFloorLimit>1000</EMVFloorLimit>
<EMVRSThreshold>500</EMVRSThreshold>
<EMVTargetRSPercent>10</EMVTargetRSPercent>
<EMVMaxTargetRSPercent>30</EMVMaxTargetRSPercent>
<MerchantForcedOnline>1</MerchantForcedOnline>
<BlackListedCardSpprt>1</BlackListedCardSpprt>
<TACDefault>D84000A800</TACDefault>
<TACDenial>0010000000</TACDenial>
<TACOnline>D84000F800</TACOnline>
<DefaultTDOL>9F1A0295059A039C01</DefaultTDOL>
<DefaultDDOL>9f3704</DefaultDDOL>
<FallbackAllowed>0</FallbackAllowed>
<NextRecord>-1</NextRecord>
<EMVCounter>0</EMVCounter>
<AppSelectionFlag>0</AppSelectionFlag>
<EMVTermCountryCode>0840</EMVTermCountryCode>
<EMVTermCurrencyCode>0840</EMVTermCurrencyCode>
<TerminalCurrencyExponent>2</TerminalCurrencyExponent>
<EMVTermCapabilities>e0f8c8</EMVTermCapabilities>
<EMVTermAddCapabilities>F000F0A001</EMVTermAddCapabilities>
<EMVTermType>22</EMVTermType>
<EMVMerchantCategoryCode>2701</EMVMerchantCategoryCode>
<EMVTerminalCategoryCode>R</EMVTerminalCategoryCode>
<ModifyCandListFlag>0</ModifyCandListFlag>
<SHORT_RFU1>2</SHORT_RFU1>
<SHORT_RFU2>0</SHORT_RFU2>
<SHORT_RFU3>0</SHORT_RFU3>
<STRING_RFU1/>
<STRING_RFU2/>
<STRING_RFU3/>
</Record>
</MVTData>

NOTE
The fields are same and corresponds to MVT.dat file structure.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 175

S AMPLE F ORMAT F ILES
Config File as ADK File Format

Config File as This section provides the sample EMV_Applications.XML, EMV_Keys.XML and
ADK File EMV_Terminal.XML files:
Format

EMV_Applications The following is the sample EMV_Applications.XML file:

XML File
<ApplicationData>
<Application AID="A0000000031010">
<VerNum>008C</VerNum>
<AppName>Scheme1</AppName>
<ASI>01</ASI>
<BrKey>5999</BrKey>
<TermIdent>3132333435363738</TermIdent>
<FloorLimit>00001388</FloorLimit>
<Threshold>000001F4</Threshold>
<TargetPercentage>00</TargetPercentage>
<MaxTargetPercentage>00</MaxTargetPercentage>
<TAC_Denial>0010000000</TAC_Denial>
<TAC_Online>D84004F800</TAC_Online>
<TAC_Default>D84000A800</TAC_Default>
<EMV_Application>01</EMV_Application>
<DefaultTDOL/>
<DefaultDDOL>9F3704</DefaultDDOL>
<MerchIdent>202020202020202020202020202020</MerchIdent>
<CDA_Processing>02</CDA_Processing>
<AC_BeforeAfter>00</AC_BeforeAfter>
<POS_EntryMode>05</POS_EntryMode>
<AdditionalTags>00000000000000000000000000000000000000000</AdditionalTags>
<Taglist>00579F08</Taglist>
<AppTermCap>E0F8C8</AppTermCap>
<AppFlowCap>3F1F170000</AppFlowCap>
<AIP_CVM_NotSupported>00</AIP_CVM_NotSupported>
<CountryCodeTerm>0250</CountryCodeTerm>
<AppTermAddCap>F000B0A001</AppTermAddCap>
<AppTerminalType>22</AppTerminalType>
<AID_Prio/>
<AID_Prio/>
<AID_Prio/>
<AID_Prio/>
<AID_Prio/>
<FallbackMIDs>000000</FallbackMIDs>
<SpecialTRX>2120110000000000</SpecialTRX>
<FallbackHandling>00</FallbackHandling>
<ChksumParams>0100000000</ChksumParams>
<ChksumASCII_EMVCO>BE3FB52A</ChksumASCII_EMVCO>
<MasterAID/></Application>
</ApplicationData>

176 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

S AMPLE F ORMAT F ILES
Config File as ADK File Format

EMV_Keys XML The following is the sample EMV_Keys.XML file:

File
<CapKeys>
<CapKey Index="F8" RID="A000000004">
<Exponent>03</Exponent>
<KeyLen>80</KeyLen>

<Key>A1F5E1C9BD8650BD43AB6EE56B891EF7459C0A24FA84F9127D1A6C79D4930F6DB1
852E2510F18B61CD354DB83A356BD190B88AB8DF04284D02A4204A7B6CB7C5551977A9B
36379CA3DE1A08E69F301C95CC1C20506959275F41723DD5D2925290579E5A95B0DF632
3FC8E9273D6F849198C4996209166D9BFC973C361CC826E1</Key>
<Hash>F06ECC6D2AAEBF259B7E755A38D9A9B24E2FF3DD</Hash>
<ExpiryDate>000000</ExpiryDate>
<RevocationList>010203111213212223</RevocationList></CapKey>
<CapKey Index="F3" RID="A000000004">
<Exponent>03</Exponent>
<KeyLen>90</KeyLen>

<Key>98F0C770F23864C2E766DF02D1E833DFF4FFE92D696E1642F0A88C5694C6479D16
DB1537BFE29E4FDC6E6E8AFD1B0EB7EA0124723C333179BF19E93F10658B2F776E829E8
7DAEDA9C94A8B3382199A350C077977C97AFF08FD11310AC950A72C3CA5002EF513FCCC
286E646E3C5387535D509514B3B326E1234F9CB48C36DDD44B416D23654034A66F403BA
511C5EFA3</Key>
<Hash>A69AC7603DAF566E972DEDC2CB433E07E8B01A9A</Hash>
<ExpiryDate>000000</ExpiryDate></CapKey>
</CapKeys>

EMV_Terminal The following is the sample EMV_Terminal.XML file:

XML File
<TerminalData>
<TermTyp>22</TermTyp>
<CurrencyTrans>0978</CurrencyTrans>
<ExpTrans>02</ExpTrans>
<CountryCodeTerm>0250</CountryCodeTerm>
<TermCap>E0F8C8</TermCap>
<TermAddCap>F000B0A001</TermAddCap>
<SuppLang>0102000000000000</SuppLang>
<IFD_SerialNumber>12345678</IFD_SerialNumber>
<KernelVersion></KernelVersion>
<FrameworkVersion></FrameworkVersion>
</TerminalData>

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 177

S AMPLE F ORMAT F ILES
Config File as ADK File Format

178 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX K

Configurable CDA Mode for Online Transactions

The MVT.txt can be configured to set the CDA mode. The short RFU1 field of
default record of MVT is used to configure the required mode. The 2nd and 3rd bit
of the short RFU1 from LSB are used together to indicate the required mode.
Following are the values to set the appropriate mode:
• 00 - Indicates Mode 3
• 01 - Indicates the default mode that is Mode 1
• 10 - Indicates Mode 2
• 11 - Indicates Mode 4

NOTE
Only the default record from MVT.txt should be used to indicate the bit settings
for CDA mode.

All invalid mode values i.e., other than those mentioned in the above list is ignored
and the DEFAULT mode (Mode 3) will be considered for transactions.
The EMV Module will read the 2nd and 3rd bit from LSB of short RFU1 from the
default record of the MVT in inVXEMVAPSCInit() function during the
initialization of the module. It will then invoke usEMVSetCDAMode() kernel API to
set the required mode in the EMV kernel.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 179

C ONFIGURABLE CDA M ODE FOR O NLINE TRANSACTIONS

180 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX L

PIN Bypass and PIN Cancel Initiated from POS/External Device

This appendix is not applicable for Vx UPT EMV Modules. The EMV kernel
supports the POS/External Device initiated PIN Bypass and PIN Cancel during a
secure PIN Entry. To activate this feature, the application needs to register a
function pointer with the EMV kernel, which is an application callback. Once the
callback is registered, during secure PIN processing the EMV kernel creates a
thread, which invokes the callback that the application has registered to check for
PIN bypass or PIN cancel. If the application needs to cancel or bypass the PIN
CVM then they can return either EXT_PIN_CNCL or EXT_PIN_BYPASS from the
call back function to the thread.
The behavior of the EMV kernel for the POS/External Device initiated PIN
Bypass/PIN Cancel is identical to the cardholder initiated PIN Bypass and PIN
Cancel. The EMV kernel will terminate the transaction upon receiving the value
EXT_PIN_CNCL from the callback function. Upon receiving the
EXT_PIN_BYPASS value from the callback function, the EMV kernel decides
whether the current PIN CVM alone should be bypassed or subsequent PIN
CVMs should also be bypassed along with the current CVM. This decision will be
taken by the EMV kernel based on the subsequent PIN Bypass flag value
provided by the application in the srPINParams structure.
Once the PIN session is initiated, the EMV kernel invokes the callback function for
POS/External Device initiated PIN Bypass and PIN Cancel. Hence the return
value EXT_PIN_CNCL or EXT_PIN_BYPASS from the application will be
processed only after the PIN session is started.
EMV kernel invokes the callback in a thread that is created by the kernel. If the
application is blocking the callback by not returning the control back to the EMV
kernel, then the EMV kernel will not return the control back to the application from
the CVM processing method.

NOTE The secure PIN processing function considers the PIN processing decision that it
receives first and will discard the other. For example, if the cardholder bypass
decision is obtained before the POS initiated PIN cancel decision, then cardholder
bypass will be processed and the POS initiated PIN cancel decision will be
discarded by the kernel.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 181

PIN B YPASS AND PIN C ANCEL I NITIATED FROM POS/E XTERNAL D EVICE

By default, the EMV kernel assigns 1K stack memory for the thread that is getting
created. If the application requires to increase the stack allocated for the thread,
then it can set an environment variable POSDECSNSTK in the terminal. For
example, if the value of the environment variable is 3, then 3K stack will be
allocated to the thread created.

NOTE
It is the application's responsibility to allocate adequate stack space for the
application based on the value it configures for POSDECSNSTK.

Application can register the function pointer by using the existing EMV kernel API
inVxEMVAPSetFunctionality() by passing the first function argument as
GET_POS_CVM_DECISION.

182 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

APPENDIX M

Double PIN Bypass Support

This appendix is not applicable for Vx UPT EMV Modules. This feature is
supported only for secure PIN. The double PIN bypass is supported only for the
PIN bypass through internal keypad. During the PIN entry, when the user presses
the key for PIN bypass for the first time, the terminal will not allow the PIN to be
bypassed and displays a warning message like “Mandatory PIN” and continues
with the PIN entry.
If user presses the key for PIN bypass, for the second time, then the PIN bypass is
allowed and the transaction continues.
The kernel will invoke a callback function in the application when the O/S indicates
that a PIN bypass key is pressed. The application can display the required
message in the callback function and returns a specific value PIN_MANDATORY
to the kernel to indicate if the PIN session to be continued.
Application can register a function pointer using the EMV kernel API
inVXEMVAPSetFunctionality() and passing the first function argument as
GET_BYPASS_DECISION.

NOTE • EMV kernel will invoke the callback function only when the function pointer is
set and the PIN is bypassed for the first time for a specific CVM. For any
subsequent cardholder PIN bypass for the current CVM, the callback function
will not be invoked and the kernel will consider it as a cardholder PIN bypass,
and will continue with the PIN bypass transaction flow.
• The double PIN bypass is supported only for the PIN bypass done through the
internal keypad. It is not supported for PIN bypass through the external device/
POS as the external device/POS can handle the double PIN bypass by itself.
• The secure PIN processing function will process the PIN bypass/cancel
decision in the order that it receives.
For example, if the usGetBypassDecsn() callback has been set in the
application and the cardholder PIN bypass decision is obtained before the
POS/external device initiated PIN cancel decision, then the cardholder PIN
bypass will be processed, and the POS/external device initiated PIN cancel
decision will be discarded by the kernel. In such a scenario, if the application
has returned PIN_MANDATORY from usGetBypassDecsn() callback, the
application needs to resend the POS/external device PIN decision as the
previous decision has not been processed by the kernel.

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 183

D OUBLE PIN B YPASS S UPPORT

Backward Compatibility
Applications that do not want this feature do not have to make any changes.
There are no backward compatibility issues.

184 VERIX/VERIX V EMV MODULE REFERENCE MANUAL

D OUBLE PIN B YPASS S UPPORT

VERIX/VERIX V EMV MODULE REFERENCE MANUAL 185

Verifone Inc.
1-800-Verifone
www.verifone.com

Verix/Verix V EMV Module

Reference Manual

Verifone Part Number 23271, Revision T