Home Contents | # v4kf:chipActivate | V4kf | Core4 Lua Event System

## SYNOPSIS

#include <v4kf.lh>
rdrhandle:chipActivate(flags[[, countrycode, socket]])

## DESCRIPTION

Enable a SmartCard chip using T=0 or T=1 protocol (auto-detected). Optionally read public identification data from EMV compatible chips and EF_ID from german "EC-Karte mit Chip".

When running the command against a regular chip card, it can only be used if the reader is in the Locked state, which secures the chip card against removal during operation in insertion readers and causes the chip contact to engage in motorized readers.

Alternatively, the command can be run on a SAM card by specifying a non-zero socket number. The value selects the SAM socket to access (1..N, depending on the number of SAM sockets installed.)

While this state processes, the reader is in the Processing state and v4kf:isProcessing() returns true. The reader returns to the previous state on completion.

The optional countrycode can be used when activating an EMV card to tell the card the supposed nationality of the card terminal.

The command returns immediately. Actual execution of any reader operation is done within the event loop.

The processing result is provided with the v4kf.processingComplete() callback. The data passed to the callback contains the information that was read from the chip. It is encoded using the ISO7816/EMV Tag-Length-Value method.

The flags parameter is a bit-wise of some of the following modifier bits:

flag | Description
--- | ---
V4KF_IDENTIFY_ALL | After activating the chip, read back any public identification information that the chip offers. This can take several seconds.
V4KF_IDENTIFY_EFID | After activating the chip, request the EF_ID identification from a german "EC-Karte mit Chip". If an EF_ID could be read, the EF_ID data is tagged using the tag 0xCF, which lies in the private range as of ISO7816-4. This allows returning EMV and EF_ID in one block.
V4KF_IDENTIFY_TRACK2EQUIV | After activating the chip, request the "Track 2 Equivalent Data" from a EMV compatible credit card. This data, if available, is a copy of the data that is on the magstripe track 2.
V4KF_IDENTIFY_ATR | Return the ATR response of the chip. The data is tagged using 0xCE, which lies in the private range is of ISO7816-4. This allows piggy-backing the ATR onto the other data. Asking for the ATR takes no extra time.
V4KF_IDENTIFY_EMV_MODE V4KF_IDENTIFY_7816_MODE | Without any of these two options the command tries to activate using EMV specific quirks first, and then goes to ISO7816 mode. Specify exactly one option to enforce using just this one mode. This can reduce the activation time by 200-300ms

## NOTES

The tagged data can be decoded using v4kf.emvDecode() and v4kf.emvLookup().

## SEE ALSO

v4kf:chipDisable, v4kf:chipEnable, v4kf:chipRead, v4kf:chipWrite, v4kf:state, v4kf.emvDecode(), v4kf.emvLookup()