EMVL2 CT FAQ

EMVL2 does not perform any file operations. Therefore, the Application Layer (L3 layer) should maintain the AID parameter file and, before the transaction starts, build an AID list array based on the structure EMVL2_AID_LIST. The space for this array must remain valid throughout the transaction period.

EMVL2 does not perform any file operations. Therefore, the Application Layer (L3 layer) should maintain the CAPK parameter file and, before the transaction starts, configure a callback interface to retrieve CAPK parameters, allowing the L2 layer to obtain CAPK parameters during the transaction process.

EMVL2 does not perform any file operations. Therefore, after the "Final Application Selection" step is successful, the Application Layer (L3 layer) should set the required configuration parameters based on the selected AID to the L2 layer via the NAPI_EMVL2SetData interface.

EMVL2 does not perform any file operations. Therefore, the Application Layer (L3 layer) should maintain the card blacklist file and perform checks based on the card number during the transaction process.

EMVL2 does not perform any file operations. Therefore, the Application Layer (L3 layer) should maintain the revoked public key file and, before the transaction starts, configure a callback interface to check for revoked public keys, allowing the L2 layer to check for revoked public keys during the transaction process.

Possible reasons include:

• Card not powered on: The Application Layer (L3 layer) should perform the power-on operation on the card before the transaction starts;
• AID list not established or no matching AID found: The Application Layer (L3 layer) should establish the AID list before the transaction starts.

To use a partially matching AID for a transaction, the flag indicating support for partial matching functionality in the AID list entry must be set.

Possible reasons include:

• Terminal Capabilities (Tag 9F33) are set to not support SDA/DDA/CDA, resulting in no commonly supported data authentication method between the terminal and the card;
• Card Application Interchange Profile (Tag 82) indicates no support for SDA/DDA/CDA, resulting in no commonly supported data authentication method between the terminal and the card.

The commonly supported data authentication methods are determined based on Terminal Capabilities (Tag 9F33) and the card's Application Interchange Profile (Tag 82). Then, the method with the highest priority is selected based on the priority order: CDA > DDA > SDA.

Possible reasons include:

• The terminal does not possess the public key required by the card;
• Incorrect public key data stored in the terminal;
• The card is missing important data related to data authentication.

Possible reasons include:

• Terminal Capabilities (Tag 9F33) are set to not support the expected verification method;
• The Cardholder Verification Method List (Tag 8E) from the card indicates no support for the expected verification method;
• The current transaction does not meet the conditions (e.g., transaction type or amount) specified for the expected verification method in the CVM list;
• Because CVMs are executed according to the order specified in Tag 8E, it's possible that before attempting the expected verification method, cardholder verification was already successfully completed or determined to have failed using a higher priority method;
• If the expected method is Offline Plaintext/Enciphered PIN, the remaining offline PIN retry count might be 0;
• If the expected method is Offline Enciphered PIN, the required PIN public key might be missing.

There is no direct relationship. Offline PIN/Online PIN are just cardholder verification methods and do not directly determine whether the transaction is offline or online. Offline/Online Transaction refers to the overall concept of the transaction flow. Cardholder verification is just one step in the transaction.

Cardholder verification failure does not directly lead to transaction decline or termination. The outcome of the transaction is determined by comprehensively evaluating numerous factors throughout the overall transaction flow (e.g., risk management).

An Online Transaction requires the Application Layer (L3 layer) to package the transaction data and send it to the backend host. The host determines whether to accept the transaction based on the received data and returns the verification result, Issuer Authentication Data, Issuer Script Data, etc. The L2 layer then processes these parameters to perform issuer authentication, second authorization, etc. An Offline Transaction, however, is decided directly by the terminal based on its risk management rules, without sending data online or performing second authorization flows.

After the relevant functions for a normal transaction are completed (before the First GAC - Generate Application Cryptogram), the terminal will decide whether the transaction is an offline approval, offline decline, or should go online.

Judgment Process: There are 3 sets of Issuer Action Codes (IACs) from the card:

• IAC-Denial (Issuer Action Code - Denial), 5 bytes
• IAC-Online (Issuer Action Code - Online), 5 bytes
• IAC-Default (Issuer Action Code - Default), 5 bytes

There are 3 sets of Terminal Action Codes (TACs) configured in the terminal:

• TAC-Denial (Terminal Action Code - Denial), 5 bytes
• TAC-Online (Terminal Action Code - Online), 5 bytes
• TAC-Default (Terminal Action Code - Default), 5 bytes

The meaning of each bit in each IAC/TAC group corresponds one-to-one with the meaning of the bits in the TVR (Terminal Verification Results).

1. First, check for Decline: Compare IAC-Denial, TAC-Denial, and TVR. If any corresponding bits are set to 1 simultaneously in (IAC-Denial and TVR) OR (TAC-Denial and TVR), the terminal declines the transaction. Otherwise, proceed to the next step.
2. Next, check for Online: Compare IAC-Online, TAC-Online, and TVR. If any corresponding bits are set to 1 simultaneously in (IAC-Online and TVR) OR (TAC-Online and TVR), the terminal initiates an online transaction. Otherwise, the terminal decides on an offline transaction approval.
3. The offline decision made here is not final. Even if the terminal decides on an offline transaction, based on the card's risk management rules, the IC card might still return a response indicating a need for an online transaction or a decline.
4. Handling Online Failures (Second Authorization): If the terminal chose to go online but there's no online capability or the online connection fails, it then needs to determine whether to approve or decline offline during the second authorization phase: Compare IAC-Default, TAC-Default, and TVR. If any corresponding bits are set to 1 simultaneously in (IAC-Default and TVR) OR (TAC-Default and TVR), the terminal declines the transaction during the second authorization. Otherwise, the terminal requests transaction approval during the second authorization (this scenario, occurring due to inability to go online or online failure, is also considered an offline transaction).
5. Online Success: If the terminal chose to go online and the online communication is successful, the terminal proceeds with issuer authentication, second authorization, etc., based on the data received from the host.

Possible reasons include:

• The Authorization Response Code (Tag 8A) returned by the host during online processing is not '00', indicating the issuer declined the transaction. This could be due to issues with data sent in Field 55, (for domestic transactions) checking if DF69 indicates SM algorithm selection while L3 has PBOC enabled;
• Tag: 8D contains tag:91, but the authentication data Tag-0x91 returned by the issuing bank during online processing in the background is incorrect or missing, resulting in the failure of issuing bank authentication;
• Other reasons indicated in the TVR cause the card to internally decide to decline the transaction.

This error (-1202) signifies an attempt to overwrite an existing tag that has unique properties and a non-zero length. Specifically for Tag 9F08 (Application Version Number - Card), this tag is typically provided by the card, and the terminal should not attempt to set or overwrite it. The error likely stems from an incorrect attempt in the configuration or code to write to 9F08. The terminal usually needs to configure 9F09 (Application Version Number - Terminal).

External Authentication fails to execute because necessary tags are missing. The EMV process requires both Tag 82 (AIP) from the card and Tag 91 (Issuer Authentication Data) from the host (issuer) to perform External Authentication. The issue you're facing is because the host (issuer) did not return Tag 91 in its response.

This error message indicates that the terminal, while performing parameter checks, could not find the mandatory EMV Tag 9F33 (Terminal Capabilities). The terminal must be configured with this tag to process transactions correctly.

The actual return of 1F0302 (indicating No CVM Required was performed) instead of 3F0001 (expected CVM result) is due to a configuration conflict. Although you might have set Byte2 bit4 (Support No CVM) of 9F33 (Terminal Capabilities) to 0 (not supported), if DF8119 (CVM Capability – No CVM Required) is also set, the kernel logic might forcibly set Byte2 bit4 of 9F33 to 1. This leads the terminal to perform No CVM Required and return 1F0302. Please check and remove the configuration for DF8119 or adjust its value. A.1.36 CVM Capability – No CVM Required Tag: 'DF8119' Template: - Length: 1 Format: b Update: K Description: Indicates the CVM capability of the Terminal and Reader when the transaction amount is less than or equal to the Reader CVM Required Limit.

CDA failure returning -1607 (Hash check incorrect) usually indicates a problem with the card's data itself. Apart from certificate expiry (-1610) or CA public key mismatch (-1632), other CDA failures are generally due to issues with the card.

This usually occurs due to one of two situations:

1. Another NFC-enabled device (like another card, a phone with NFC turned on, etc.) is within the terminal's sensing area, causing the terminal to mistakenly try interacting with it as the target card.
2. There's an issue with the underlying NFC driver or hardware, causing the polling logic to terminate abnormally or incorrectly trigger the interaction flow.

Receiving error code -1616 (Missing 9F37) is due to terminal configuration. The kernel expects to retrieve Tag 9F37 during a specific process (possibly a security check) but fails to do so. You need to set DF44 to 9F3704 in the XML configuration file.

Online PIN is performed instead of Offline PIN because the terminal's capabilities configuration (Tag 9F33) indicates it does not support Offline PIN verification. Specifically, the value of 9F33 is 60 68 C8. When decoded, Byte2 bit5 (Offline enciphered PIN verification) is 0, signifying lack of support. You need to modify Byte2 bit5 of 9F33 to 1 to enable the terminal to support and attempt Offline PIN verification.

Only the final application selection callback occurs because the terminal is configured to automatically select the application, skipping the step where the cardholder confirms or chooses the application. To implement the application selection callback, you need to modify the terminal configuration Tag DF24 (Application Selection Indicator) by setting its Byte1 bit7 (Cardholder Confirmation supported) to 1.

Tag 98 (TC Hash Value) can only be retrieved if the Card Data Object List (CDOL) explicitly requests this tag. The specific conditions depend on the relevant payment scheme specifications.

Returning -502 (User Cancelled) instead of the expected -517 (Fallback) happens because the user or the upper-level application actively cancelled the operation while the kernel was attempting fallback (which usually involves polling the card a few times). The fallback mechanism is only triggered if the kernel completes its retry logic (default: poll three times) and still doesn't find a valid application, and the process was not cancelled prematurely.

The second authorization failure is typically related to the Card Verification Results (CVR) or Issuer Authentication. The provided value for Tag 9F10 (Issuer Application Data) is 06 67 12 03 28 B8 00. Decoding the CVR part shows Byte5 bit4 is 1, which explicitly means "Issuer Authentication performed but failed". This indicates that after the first online request, the host returned Tag 91 (Issuer Authentication Data), the terminal sent it to the card for verification, but the card's verification failed, leading to the rejection of the second authorization. The issue likely lies in incorrect 91 data returned by the host.

The transaction was approved offline instead of going online because the transaction amount did not trigger the online condition. Specifically, the transaction amount 9F02 (value 2000) did not exceed the Floor Limit 9F1B (value 2701) returned by the card. Consequently, during terminal risk management, the TVR bit associated with TAC-Online (Terminal Action Code - Online), such as TVR Byte4 bit8 (Transaction exceeds floor limit), was not set. This prevented the terminal from forcing the transaction online based on the TAC-Online rule. Instead, it proceeded based on TAC-Default or TAC-Denial, potentially leading to an offline approval. To force the transaction online, the amount needs to be increased above 9F1B (2701), which would set the corresponding TVR bit, match TAC-Online, and cause GAC1 to request an online authorization.

The PIN entry prompt did not appear because, according to the card data returned in Tag 9F10, the card indicated Signature as the Cardholder Verification Method, not Online PIN.

The CVM process did not proceed to Online PIN because the terminal matched 44 03 (Offline Enciphered PIN) in the CVM List (Tag 8E) returned by the card (00 00 00 00 00 00 00 00 42 01 44 03 41 03 42 03 5E 03 1F 03). Therefore, it did not proceed to attempt Online PIN.

A key consideration for Paywave Refund transactions is that even if the card returns an AAC (Application Authentication Cryptogram - usually indicating decline), the terminal should not simply treat it as a failed transaction. According to the Paywave specification, an AAC response from the card during a refund is an expected behavior and typically requires online processing. Therefore, before initiating a Paywave Refund, the ucRefundRequestAac field in the Entrypoint structure must be set to request online authorization (0x80 - ARQC). This ensures that even if the card returns an AAC, the kernel treats it as a request requiring online authorization rather than an outright decline.

Application initialization fails with error -9 due to an improper setting of the Paypass kernel configuration DF2F (ucKernelConfig). The log shows DF2F is set to F0 (1111 0000b). According to the Paypass specification, bit8 (Only EMV Mode) and bit7 (Only Mag-Stripe Mode) of DF2F cannot both be 1 simultaneously. The current configuration F0 has both bits set to 1, representing an invalid configuration. This causes the kernel to return the error EMV_TRANS_RF_TERMINATE during initialization, which manifests as -9 at the upper layer. You need to change DF2F to a valid value, such as B0 (1011 0000b).

The Paypass kernel requests an AAC during GAC only when the TVR (Terminal Verification Results) matches the TAC-Denial (Terminal Action Code - Denial, configured in Tag DF13). Therefore, for refund transactions, the TAC-Denial (DF13) for the refund transaction type associated with that AID should be set to all 0xFF.

• Method 1 (Recommended): If using the latest L3, add <item tag="DF13" transType="20" value="FFFFFFFFFF" /> to the L3 AID XML configuration.
• Method 2: In the application code, after detecting a Mastercard refund transaction and after the final application selection, call NAPI_L3SetData(0xDF13, "\xFF\xFF\xFF\xFF\xFF", 5).

A JCB contact transaction returning -1607 (Data Authentication Hash Value Mismatch) usually indicates a problem with the card data. The expected hash value might be 47 9E 4B B7 37 C2 C7 9F 9E C1 99 BA CB 4E D3 64 E8 3A CE E2, but the actual returned value is 75 F9 DB 21 B0 CA 05 9E 6C 59 16 80 A5 55 8A 6B 36 77 74 67. This typically happens because the card data is problematic.The hash value calculation method involves: Using RSA, remove the first byte 6A, the trailing hash value, and the last byte BC (22 bytes) + remainder + exponent + AUTH_DATA + AIP.

The QPBOC specification differs from standard EMV; it doesn't directly generate or store Tag 9F34 at the kernel level. To obtain the CVM result for a QPBOC transaction and format it as 9F34, the application layer needs to, after the transaction concludes, retrieve the L3 CVM outcome code (e.g., L3_CVM_NO_CVM, L3_CVM_SIGNATURE, etc.) using NAPI_L3GetData(L3_DATA_CVM_OUTCOME, ...). Then, based on this outcome code, it must manually set the corresponding 9F34 value using NAPI_L3SetData(_EMV_TAG_9F34_TM_CVMRESULT, ...).

You can determine if a transaction failed due to application expiry by checking these two points:

1. Check Kernel Logs: Look for log entries related to EMVL2_ProcessRestrictions or date comparisons. Check if there's a clear record of the current transaction date and the card's Application Expiration Date, and confirm that the transaction date is on or after the expiration date.
2. Check TVR (Terminal Verification Results, Tag 95): Examine the transaction's TVR value. If Byte2 bit7 (Application expired) is set to 1, it indicates the kernel determined the application has expired.

The absence of 9F26 (Application Cryptogram) in the reversal message might be related to the reversal process and the timing of Field 55 data generation.

• A standard reversal process typically occurs after: 1) First GAC requests online (generating Field 55 including 9F26) -> 2) Host online response is successful -> 3) Second GAC where the card declines the transaction.
• At this point, the application layer determines a reversal is needed. The key question is which Field 55 should be used for the reversal message.
  • The first GAC (step 1) generates 9F10 and 9F26 (in Field 55).
  • When initiating the reversal (after step 3, which involves a second GAC), a new 9F10 and potentially a new 9F26 might be generated.
  • Whether the reversal should send the Field 55 generated in step 1, or if Field 55 needs to be updated based on the second GAC, depends on the host's requirements.
• If the host response is a decline, the second authorization fails, and no reversal is needed.
• If the host response is an approval, but the second authorization (second GAC) fails, a reversal is needed.

Errors or incorrect data when retrieving script result DF31 might stem from logical errors in the application layer code attempting to get and set this tag. Based on the provided code snippet:

1. The application first tries to get DF31 using NAPI_L3GetData(_EMV_TAG_DF31_IC_IISSCRIRES, ...).
2. If this fails (nRet <= 0), it attempts to get the raw script result data provided by L3 (szL3ScriptOut) using NAPI_L3GetData(L3_DATA_ISSUER_SCRIPT_RESULT, ...). Using strlen to get the length here is incorrect because it will ignore trailing null bytes, leading to an incorrect length if the script result contains them.The length should be obtained using sizeof.

The contact cashback transaction fails with -514 because the card itself does not support the cashback service. Checking the card's AUC (Application Usage Control, Tag 9F07) reveals a value of FF00, which indicates that cashback transactions are disallowed by this card. Therefore, when the terminal requests the cashback service, the card denies the request based on its AUC settings, causing the transaction to fail.

An L3CompleteTransaction returning error -506 is highly likely due to issues with the incoming Field 55 data, particularly Tag 91 (Issuer Authentication Data). The log shows the host returned Field 55 where Tag 91 has a length (0A) indicating its value should be 10 bytes. However, the data actually passed to NAPI_L3CompleteTransaction, 91 0A 50 FD 15 4E FE A1 29 4E 00, appears to have only 9 bytes of value for 91 (50 FD 15 4E FE A1 29 4E 00). You need to carefully verify if the length and content of the 91 data returned by the host are completely correct and valid.

The kernel uses transaction type 9C=00 (Purchase) for Paywave CashBack transactions, instead of the 9C=09 (Purchase with Cashback) passed by the application layer, because this is a specific requirement of the Paywave specification. The Paywave specification explicitly states that for transactions involving the purchase of goods or services, with or without cashback, the terminal must use Transaction Type '00'. The cashback amount is conveyed via Tag 9F03 (Amount, Other). Therefore, even if the application layer sets 9C=09, the Paywave kernel adheres to the specification and overrides it to 00.

L3 returns error -514 after a PIN bypass due to the combination of the card's CVM List (Tag 8E) configuration and the bypass handling logic. If the card's 8E (02 03 1F 00 in the example) prioritizes Online PIN, when the user chooses bypass, the terminal considers cardholder verification to have failed and likely does not proceed to the next CVM method listed (if any), leading to a state interpreted as an error (-514).

To enable the terminal to flexibly choose between EMV contact or mag-stripe mode based on the card or process requirements, you need to set both bit 8 (Only EMV Mode) and bit 7 (Only Mag-Stripe Mode) to 0 in the Paypass kernel configuration Tag DF2F. This indicates the terminal is not restricted to only one mode but supports both. The specific mode used will then be determined by the subsequent transaction flow and the card itself.

The Put Data command was not sent to the card because the conditions required to trigger it were not met. Put Data is typically used to update data on the card and is issued by the host as part of an Issuer Script (Tag 71 or 72). The terminal will only send this command to the card during issuer script processing if the host included an Issuer Script containing the Put Data command in the online response.

Issuer Script Format (Tag 71 or 72)

Note 12: The actions taken by the acquirer and issuer are outside the scope of this specification. However, a brief explanation of what the issuer might do may help clarify things. An ARQC is generated by the card encrypting transaction data using a key stored on the card; this key is known to the issuer's authorization system. The issuer uses this key to authenticate the ARQC, thus authenticating the card. This process is called "Online Card Authentication" or simply "Card Authentication". Note 13: After card authentication, the issuer may generate a cryptogram using data selected from the authorization response or data known to the card. This cryptogram is sent back to the terminal in the authorization response as part of the Issuer Authentication Data. The terminal provides the Issuer Authentication Data to the card in the EXTERNAL AUTHENTICATE command or the second GENERATE AC command, according to the card specification. The IC card can use the Issuer Authentication Data to confirm that the response message comes from the issuer. An example might be unlocking an offline PIN, which might be handled differently by different issuers or payment systems.

EMV2000 Payment System IC Card Specification Format (Conceptual Example of Commands within V of Tag 71/72)

This occurs because the terminal configuration has "Force Online" enabled. To correct this and ensure TVR Byte 4, bit 4 is 0 as required by the test case, the terminal parameter controlling forced online transactions (often Tag 0x1F8126) must be set to 0, effectively disabling the force online feature.

The terminal requests an AAC when the bits set in the Terminal Verification Results (TVR) match the corresponding bits set in the Terminal Action Code - Denial (TAC-Denial, Tag DF13). In this scenario, the TVR generated during the transaction is 00 00 80 80 01. For the terminal to request an AAC as required, the TAC-Denial (DF13) must be configured with a value that creates a match with this specific TVR according to the kernel's logic. The necessary configuration value for DF13 to achieve this match is `0