::iterator i;
guiCb = pinParam->callback;
uiSetPropertyInt(disp, UI_PROP_PIN_ALGORITHM, (int) pinParam->ucPinAlgo);
uiSetPropertyInt(disp, UI_PROP_PASSWORD_CHAR, (int) pinParam->ulEchoChar);
uiSetPropertyInt(disp, UI_PROP_PIN_AUTO_ENTER, (int) pinParam->ucAutoEnter);
uiSetPropertyInt(disp, UI_PROP_PIN_BYPASS_KEY, (int) pinParam->ulBypassKey);
uiSetPropertyInt(disp, UI_PROP_PIN_CLEAR_ALL, (int) pinParam->ucClearAll);
uiSetPropertyInt(disp, UI_PROP_TIMEOUT, (int) pinParam->lTimeoutMs);
std::string str = pinParam->currency;
str += " ";
str += pinParam->amount;
str += " ";
values.clear();
values["msgPIN"] = UI_STR_ENTER_PIN;
values["amount"] = str;
values["caution_icon"] = "1";
values["title"] = pinParam->appLabel;
if(isKeypadExist())
{
while ((r = uiInvokeURL(disp, UI_REGION_ID_MAIN, values, "helper_pin.html", &guiCallback, NULL)) == UI_ERR_PERMISSION)
usleep(1000);
}
else // X10, Carbon, Swordfish, e280
{
initializeUiRegions(UI_REGION_ID_MAIN|UI_REGION_ID_SOFTWARE_LEDS);
while ((r = uiInvokeURL(disp, UI_REGION_ID_MAIN, values, "kbd_pin.html", &guiCallback, NULL)) == UI_ERR_PERMISSION)
usleep(1000);
}
if(r == UI_ERR_OK)
{
for (i = values.begin(); i != values.end(); ++i) {
if (!strcmp(i->first.c_str(), "pin")) {
break;
}
}
if (i == values.end()) {
return EMV_CT_PIN_INPUT_OTHER_ERR;
}
if (sscanf(i->second.c_str(), "%d", &digits) == 1) {
Demo_SplashPleaseWait();
return EMV_CT_PIN_INPUT_OKAY;
}
if (!strcmp(i->second.c_str(), "bypass")) {
return EMV_CT_PIN_INPUT_BYPASS;
}
if (!strcmp(i->second.c_str(), "cancel")) {
return EMV_CT_PIN_INPUT_ABORT;
}
return EMV_CT_PIN_INPUT_OTHER_ERR;
}
}
switch (r) {
case UI_ERR_TIMEOUT:
return EMV_CT_PIN_INPUT_TIMEOUT;
case UI_ERR_ABORT:
case UI_ERR_CANCELLED:
return EMV_CT_PIN_INPUT_ABORT;
default:
return EMV_CT_PIN_INPUT_OTHER_ERR;
}
return EMV_CT_PIN_INPUT_OTHER_ERR;
}
unsigned char _EMVADK_cbk_duringPINinput(void)
{
if(EMV_CT_SmartDetect(0) != EMV_ADK_SMART_STATUS_OK)
{
APP_TRACE("--> WHERE IS THE CARD ???????");
return true;
}
return false;
}
unsigned char ucInputPIN( unsigned char pintype,
unsigned char bypass,
unsigned char* pucPINResultData)
{
unsigned char rsp;
int r = 0;
unsigned long BypassKey = 0;
unsigned char tucAmount[6] = {0};
unsigned char tucAmountAscii[13] = {0};
char finalAmount[13] = {0};
guiPinParam pinParam;
unsigned long TAGR;
unsigned char Buffer[32];
unsigned short TAGL = 0;
if (bypass)
{
APP_TRACE("start PIN entry: Bypass active: YES");
BypassKey = 13; // Bypass activated with Enter Key 0 digits
}
else
{
APP_TRACE("start PIN entry: Bypass active: NO");
BypassKey = 0;
}
pinParam.ucPinAlgo = EMV_PIN;
pinParam.ucAutoEnter = 0;
pinParam.ucClearAll = 0;
pinParam.ulEchoChar = '*';
pinParam.ulBypassKey = BypassKey;
pinParam.lTimeoutMs = 30000;
pinParam.callback = _EMVADK_cbk_duringPINinput;
pinParam.currency = UI_STR_CURRENCY;
TAGR = 0x9F02;
if (pintype == EMV_CTLS_PIN_INPUT_ONLINE)
{
TAGL = 0;
EMV_CTLS_fetchTxnTags(0, &TAGR, 1, Buffer, 32, &TAGL);
if (TAGL > 0)
memcpy(tucAmount, &Buffer[3], 6);
}
else
{
EMV_CT_fetchTxnTags(EMV_ADK_FETCHTAGS_NO_EMPTY, &TAGR, 1, Buffer, 32, &TAGL);
if (TAGL > 0)
memcpy(tucAmount, &Buffer[3], 6);
}
APP_TRACE("Amount extracted: %02X%02X%02X%02X%02X%02X",
Buffer[3], Buffer[4],
Buffer[5], Buffer[6],
Buffer[7], Buffer[8]);
vAmountBCD2ASCII(tucAmount, tucAmountAscii, 6);
vAmountForDisplay(finalAmount, sizeof(finalAmount), (char*)tucAmountAscii, 2);
pinParam.amount = finalAmount;
if ((pintype == EMV_CT_PIN_INPUT_ENCIPHERED) || (pintype == EMV_CT_PIN_INPUT_PLAIN))
{
// PIN Entry using GUI-ADK
rsp = UIEnterPin(&pinParam);
APP_TRACE("=== result of PIN entry: %d ===", rsp);
if (rsp == EMV_CT_PIN_INPUT_BYPASS)
APP_TRACE("PIN Bypass from customer");
if (rsp != EMV_CT_PIN_INPUT_OKAY)
{
return(rsp);
}
rsp = EMV_CT_Send_PIN_Offline(pucPINResultData);
APP_TRACE("=== result of PIN offline: %d ===", rsp);
switch (rsp)
{
case EMV_ADK_SMART_STATUS_OK:
if (pucPINResultData[0] == 0x63)
{
if (pucPINResultData[1] == 0xC1)
r = UI_ShowOkCancelMessageExt(getCardHolderDisplay(), 100000, UI_STR_PIN, UI_STR_WRONG_PIN_TRY_LAST, NULL);
else if (pucPINResultData[1] == 0xC0)
r = UI_ShowOkCancelMessageExt(getCardHolderDisplay(), 100000, UI_STR_PIN, UI_STR_WRONG_PIN_GAME_OVER, NULL);
else
r = UI_ShowOkCancelMessageExt(getCardHolderDisplay(), 100000, UI_STR_PIN, UI_STR_WRONG_PIN_TRY_AGAIN, NULL);
if (r == -1)
return EMV_CT_PIN_INPUT_ABORT;
}
return EMV_CT_PIN_INPUT_OKAY; // need to check SW1 SW2
default:
return EMV_CT_PIN_INPUT_COMM_ERR;
}
}
else if ((pintype == EMV_CT_PIN_INPUT_ONLINE) || (pintype == EMV_CTLS_PIN_INPUT_ONLINE))
{
// with Online PIN of CTLS there is no need to check card insertion
if (pintype == EMV_CTLS_PIN_INPUT_ONLINE)
pinParam.callback = NULL;
rsp = UIEnterPin(&pinParam);
APP_TRACE("=== result of PIN entry: %d ===", rsp);
if (rsp != EMV_CT_PIN_INPUT_OKAY)
{
return rsp;
}
// Online PIN needs to be fetched by the local/domestic VSS script handling the online PIN block
// transmission towards the acquirer/network provider
return EMV_CT_PIN_INPUT_OKAY;
}
else if (pintype == EMV_CT_CVM_CUSTOM)
{
// custom CVM method
APP_TRACE("=== result of custom CVM method: OK");
return EMV_CT_PIN_INPUT_OKAY;
}
return EMV_CT_PIN_INPUT_OTHER_ERR;
}
```
## Programming
Here you can find flow-specific use cases and general guidance of scenarios that you may need for implementation.
### Programming and API Principles
This section provides programming function reference for the ADK EMV Contact framework.
#### Configuration Commands
For schematic figure see [Configuration Flow](#subsec_emv_ct_intro_configflow)
The EMV Configuration comprises the following steps:
* [Initialize EMV Framework](#anchor_emv_ct_initialize_emv_framework): Turns on EMV Framework
* [Configure Terminal Data](#anchor_emv_ct_configure_terminal_data): Configures terminal data.
* [Configure Application Data](#anchor_emv_ct_configure_application_data): Configures AID data.
* [Configure CAP Keys](#anchor_emv_ct_configure_cap_keys): Configures CAP Keys
* **Exit** **Framework:** Turns off the EMV Framework ([EMV\_CT\_Exit\_Framework()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t.md#gaad2d6cdd1249528199d5dc969e48b43c))
The following sequence shows an EMV Configuration example for 2 AIDs and 3 CAP Keys:
The EMV configuration is stored permanently in flash files.
**\[Initialize EMV Framework]{.underline}**
You should initialize the ADK EMV Contact framework before usage, preferably during terminal startup. In case of memory shortage, the application can separate initialization into two steps:
* **Base** **initialization** Call with `EMV_CT_INIT_OPT_BASE_INIT` set in options To be done at terminal startup, no memory allocation.
* **Transaction** **initialization** To be done for every transaction. Must provide memory allocation. After end of transaction, application calls [EMV\_CT\_Exit\_Framework()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t.md#gaad2d6cdd1249528199d5dc969e48b43c).
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | --- | ------- | ---- |
| x39 | x00 | x00 | x00/x01 | Data |
**P2 = 0: Init Framework**
**P2 = 1: Exit Framework**
**Table: Response**
| Data | SW1 | SW2 | Comment |
| ---- | --- | --- | -------------------------------------------- |
| None | x90 | xXX | Function executed, xx = response code (P2=0) |
| None | x90 | x00 | Function executed, xx = response code (P2=1) |
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
The function interface includes four parameters:
* The number of AIDs to support
* The function pointer for the callback
* An arbitrary pointer, which will be relayed unchanged to callback function call (useful for object-oriented applications)
* Initialization options.
{% hint style="info" %}
On the serial interface the callbacks are realized by intermediate messages. Those are received by the EMV-client (use case 1 and 2 in [anchor\_emv\_ct\_Use\_Case\_Samples\_1to4](#anchor_emv_ct_use_case_samples_1to4)). If EMV-client is not used the application has to handle this data (use case 3 and 4). In any case it's mandatory to call the Init and Exit functions.
{% endhint %}
[EMV\_CT\_Init\_Framework](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t.md#ga514e39585c5a6b79632ac317593ff592), [EMV\_CT\_Init\_Framework\_Client()](/adk-5.0-programmers-guide/readme/files/dir_f2a776acea245b054b8e462971041f2d/dir_a8473f4b62cdc0a6141a040fa4015132/dir_f787d7497684cf42d067468735e00a3d/dir_18e3d3062bbf485b8b342eb241e15d99/_e_m_v___c_t___interface_8h.md#aa32731a2b868db59639385b8853170e4)
**\[Configure Terminal Data]{.underline}**
This section presents an overview of the typical tags for terminal configuration.
This function provides the ADK EMV Contact framework and subsequent kernel with the terminal data it needs. The framework checks and saves the provided data in an XML file. You can configure the XML file directly (file configuration), instead of using this function (dynamic configuration).
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | ---------- | ------- | ---- |
| x39 | x01 | don't care | x00/x01 | Data |
**P2 = 0: Set Data**
**P2 = 1: Get Data**
**Table: Response**
| Data | SW1 | SW2 | Comment |
| ------------- | --- | --- | -------------------------------------------- |
| None | x90 | xXX | Function executed, xx = response code (P2=0) |
| Terminal data | x90 | x00 | Function executed, xx = response code (P2=1) |
The following illustration shows the Set/Get Terminal Data function.
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_SetTermData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga351c2deba9865081c314d818463f20c9), [EMV\_CT\_GetTermData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga954c82bc82203115b10fcab356df0079)
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
**Defaults and Guides**
The default terminal data is an attended combined offline/online terminal, supporting all variants of CVM and card authentication:
* Currency: EUR
* Supported languages: English
* Country Code: France.
It is recommended to configure all terminal-wide parameters from the application. If any of the parameters are missing, the default will be used. The configuration will not fail because of a missing parameter.
The following table show samples of configuration values.
**Table: Configuration Values**
| Tags | Size | Default Value | Description |
| ---- | ---- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| 9F35 | 1 | 0x22 | Terminal type |
| 9F1A | 2 | 0x02, 0x50 (France) | Terminal country code according ISO 3166 |
| 9F33 | 3 | 0xE0, 0xF8, 0xC8 | Terminal capabilities |
| 9F40 | 5 | 0xF0, 0x00, 0xB0, 0xA0, 0x01 | Additional Terminal capabilities |
| 9F1C | 8 | "00000001" | Terminal Identification |
| 5F2A | 2 | 0x09, 0x78 (EUR) | Transaction currency code according ISO 4217. For a single transaction this value may be overwritten. |
| 5F36 | 1 | 0x02 | Transaction currency Exponent |
| DF67 | 20 | 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
(Only 1 supported: English)
| Supported languages by host (up to 20) |
| 9F1E | 8 | < S/N (last 8 digits) > | IFD Serial Number |
| DF65 | 128 | (response only) | Version of EMV kernel |
| DF11 | 128 | (response only) | Version of EMV framework |
| DF6B | 128 | (response only) | version of L1 Driver |
**EMV Application Terminal Configuration Examples**
*Terminal Configuration Example -- Set all but IFD serial number*
```cpp
Command
39 01 00 00 F0 42 9F 35 01 22 5F 2A 02 08 40 5F 9....B.5."_*..@_
36 01 02 9F 1A 02 08 40 9F 33 03 E0 F8 C8 9F 40 6......@.3.....@
05 F0 00 B0 A0 01 9F 1C 08 32 32 32 32 32 32 32 .........2222222
32 DF 67 14 01 02 00 00 00 00 00 00 00 00 00 00 2.g.............
00 00 00 00 00 00 00 00 ........
Response
90 00
```
*Terminal Configuration Example -- Set Country*
```cpp
Command
39 01 00 00 F0 05 9F 1A 02 02 80
Response
90 00
```
*Terminal Configuration Example -- Get Current*
```cpp
Command
39 01 00 01
Response
90 00 F0 81 B2 9F 35 01 22 5F 2A 02 08 40 5F 36 ......5."_*..@_6
01 02 9F 1A 02 08 40 9F 33 03 E0 F8 C8 9F 40 05 ......@.3.....@.
F0 00 B0 A0 01 9F 1C 08 30 30 30 30 30 30 30 31 ........00000001
DF 67 14 01 02 00 00 00 00 00 00 00 00 00 00 00 .g..............
00 00 00 00 00 00 00 9F 1E 08 30 31 31 30 30 32 ..........011002
30 39 DF 65 08 4C 32 37 2E 30 2E 33 72 DF 11 07 09.e.L27.0.3r...
34 2E 31 30 2E 32 39 DF 6B 3A 49 46 4D 31 38 63 4.10.29.k:IFM18c
2D 45 4D 56 34 2E 33 5F 41 30 30 2C 20 53 57 5F -EMV4.3_A00, SW_
41 30 30 2C 20 48 57 5F 41 30 30 3B 30 31 2E 33 A00, HW_A00;01.3
37 20 30 34 2F 32 30 32 32 3B 56 32 30 30 63 20 7 04/2022;V200c
43 54 4C 53 DF 6C 10 30 31 31 30 30 32 30 39 30 CTLS.l.011002090
30 30 30 30 30 32 62 000002b
```
**\[Configure Application Data]{.underline}**
This function provides the ADK EMV Contact framework and subsequent kernel with the application data it needs. The framework checks and saves the provided data in an XML file. You should configure one set of parameters per application (AID). You can configure the XML file directly (file configuration), instead of using this function (dynamic configuration).
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | --- | ------- | ---- |
| x39 | x02 | x00 | x00/x01 | Data |
**P2 = 0: Set Data**
**P2 = 1: Get Data**
**Table: Response**
| Data | SW1 | SW2 | Comment |
| ---------------- | --- | --- | -------------------------------------------- |
| None | x90 | xXX | Function executed, xx = response code (P2=0) |
| Application data | x90 | x00 | Function executed, xx = response code (P2=1) |
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_SetAppliData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga73ca1735defbb65a1aae2ead1de70233), [EMV\_CT\_GetAppliData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga363163e375895b7d3ad03ace5df5d0d3)
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
**Defaults and Guides**
The default application is named "Default App" and includes typical EMV parameters for TACs, CDA mode 3, floorlimit 0, partial selection supported, default DOLs == 9F37, no additional or mandatory tags and terminal-wide parameters as configured per terminal and not limited. You should configure almost all AID parameters from the application because they might be changed if applicable. If any of the parameters are missing, the default will be used. The configuration will not fail because of a missing parameter once a correct AID is available.
The following table show samples of configuration values.
**Table: AID Configuration Control**
| Tags | Size | Description |
| ---- | ---- | --------------------------------------------------------------------------------------------------------------------------- |
| DF66 | 1 | AID Set Requests:
0x01 > Write one AID config 0x10 > Write/Clear AID config
0x20 > Write/Clear all AID configs
|
| DF66 | 1 | AID Get Data Request:
0x00 > Read one AID config
0x01 > Read first AID config 0x02 > Read next AID config
|
**Table: AID Configuration Data**
| Tags | Size | Default Value | Description |
| ------ | ----- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 4F | 5..16 | **Mandatory** (**No** **Default**) | Application ID |
| 9F09 | 2 | < none > ^[1)](#fnemvcttab10_1)\ [2)](#fnemvcttab10_2)^ | Terminal application version number |
| 50 | ..16 | "Default App" ^[2)](#fnemvcttab10_2)^ | Default application name to be used in case application label (tag 50) and application preferred name (tag 9F12) are not read from chip |
| DF20 | 1 | 0x01 | Application selection indicator (ASI) |
| 9F15 | 2 | 0x59, 0x99 | Merchant category code |
| 9F1C | 8 | 0x30, 0x30, 0x30, 0x30, 0x30, 0x30, 0x30, 0x31 | Terminal Identification |
| 9F1B | 4 | 0x00, 0x00, 0x00, 0x00 | Terminal floor limit (binary coded) |
| DF24 | 4 | 0x00, 0x00, 0x00, 0x00 | Threshold Value for Biased Random Online Selection during risk management (binary coded) |
| DF26 | 1 | 0x00 | Target percentage (BCD coded) for random online selection during risk management |
| DF25 | 1 | 0x00 | Maximum target percentage (BCD coded) for random online selection during risk management |
| DF21 | 5 | 0x04, 0x00, 0x00, 0x00, 0x00 ^[2)](#fnemvcttab10_2)^ | Terminal Action Code - Denial |
| DF22 | 5 | 0xF8, 0x50, 0xAC, 0xF8, 0x00 ^[2)](#fnemvcttab10_2)^ | Terminal Action Code - Online |
| DF23 | 5 | 0xFC, 0x50, 0xAC, 0xA0, 0x00 ^[2)](#fnemvcttab10_2)^ | Terminal Action Code - Default |
| DF2D | 1 | 0x01 | 0xNN = EMV-Application (or similar)
0xFF = non-EMV-Application
|
| DF27 | ..80 | 0x9F, 0x37, 0x04 ^[2)](#fnemvcttab10_2)^ | Default TDOL |
| DF28 | ..80 | 0x9F, 0x37, 0x04 | Default DDOL |
| 9F16 | 15 | 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20 | Merchant Identifier |
| DF3E | 1 | 0x02 | CDA processing, maximum security or maximum speed:
0x00 - CDA for ARQC: yes, for TC after successful online communication: yes
0x01 - CDA for ARQC: yes, for TC after successful online communication: no
0x02 - CDA for ARQC: no, for TC after successful online communication: no
0x03 - CDA for ARQC: no, for TC after successful online communication: yes
|
| DF15 | 1 | 0x00 | TACIAC Default handling:
0x00 - process default action codes prior to 1st GENERATE AC
0x01 - process default action codes after 1st GENERATE AC
|
| DF2E | 1 | 0x00 | Behavior for AIP 'CVM not supported':
0x00 - continue transaction 0x01 - execute CVM signature
0x02 - execute CVM online PIN 0x03 - abort transaction
|
| 9F39 | 1 | 0x05 | POS entry mode according ISO 8583:1987 |
| DF5F | ..20 | < none > | Up to 10 additional terminal application version numbers (each two byte, network byte order) |
| DF2B | 5 | 0x01, 0x1A, 0x00, 0x00, 0x00 ^[2)](#fnemvcttab10_2)^ | See AID Application Flow Capabilities (see [Defines for Application flow capabilities](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t/group___a_p_p___f_l_o_w___c_a_p_s.md)) |
| DF29 | ..255 | < none > | Additional Tags, TLV encoded |
| DF2A | ..40 | 0 | Up to 20 mandatory tags (each two bytes, network byte order) |
| 9F33 | 3 | 0xE0, 0xF8, 0xC8 ^[2)](#fnemvcttab10_2)^ | Application Specific Terminal capabilities |
| 5F28 | 2 | 0x02, 0x50 | Application Specific Terminal country code |
| 9F40 | 5 | 0xF0, 0x00, 0xB0, 0xA0, 0x01 ^[2)](#fnemvcttab10_2)^ | Application Specific Additional terminal capabilities |
| 9F35 | 1 | 0x22 | Application Specific Terminal Type |
| DF1D | 5..16 | < none > | priority applications (tag might occur up to 5 times) ^[3)](#fnemvcttab10_3)^ |
| DF17 | 5 | 0, 0, 0 | 3 associated mag. stripe IDs, only non-Null values are relevant ^[3)](#fnemvcttab10_3)^ |
| DF1C | 8 | 0x21, 0x20, 0x11, 0x02, 0x00, 0x00, 0x00, 0x00 | 16 half bytes transaction use case filter ^[3)](#fnemvcttab10_3)^ |
| DF18 | 1 | 0x00 | settings for fallback from chip to mag. stripe in conjunction with DF17 ^[3)](#fnemvcttab10_3)^ |
| DF2F | 1 | 0x00 | code for custom (non-EMVCo defined) CVM method supported by this application |
| DF13 | 5 | 0x21, 0x05, 0x00, 0x00, 0x00 | flags for supplementary terminal capabilities affecting EMVCo configuration checksum |
| DF12 | 32 | (response only) | EMVCo checksum |
| DFD004 | ..3 | 0x00, 0x00, 0x00 | Transaction types for sale (omitted in response if at default) |
| DFD005 | ..3 | 0x01, 0x01, 0x01 | Transaction types for cash-out (omitted in response if at default) |
| DFD006 | ..3 | 0x09, 0x09, 0x09 | Transaction types for cash back (omitted in response if at default) |
| DFD007 | ..3 | 0x20, 0x20, 0x20 | Transaction types for refund (omitted in response if at default) |
| DFAB58 | ..88 | < none > | Data Container Read IDs for D-PAS data exchange |
| DFAB59 | ..88 | < none > | Data Container Read ranges for D-PAS data exchange |
^1)^ If none is configured card's application version is used during transaction
^2)^ Depending on AID and Terminal Type some default application data settings get adapted values, e.g. a MasterCard application gets "Mastercard" as default application label. Note that these default settings might change any time as ADK EMV evolves. Also note that especially Terminal Capabilities and Additional Terminal Capabilities are not inherited from the terminal settings. Therefore do not rely on and configure all fields as recommended above.
^3)^ Settings for special operation. Do not configure unless required.
**EMV Application (AID) Configuration Examples**
*AID Configuration Example -- Set MC Data*
```cpp
Command – Configure Multiple Parameters
39 02 00 00 F0 81 A2 DF 66 01 01 4F 07 A0 00 00
00 04 10 10 9F 09 02 00 02 50 0B 4D 61 73 74 65
72 63 61 72 64 00 DF 20 01 01 9F 15 02 59 99 9F
1C 08 31 32 33 34 35 36 37 38 9F 1B 04 00 00 13
88 DF 24 04 00 00 01 F4 DF 26 01 00 DF 25 01 00
DF 21 05 04 00 00 00 00 DF 22 05 F8 50 AC F8 00
DF 23 05 FC 50 AC A0 00 DF 2D 01 01 DF 27 0F 9F
02 06 5F 2A 02 9A 03 9C 01 95 05 9F 37 04 DF 28
03 9F 37 04 9F 16 0F 20 20 20 20 20 20 20 20 20
20 20 20 20 20 20 DF 29 04 9F 53 01 52 DF 2A 01
8E DF 2B 05 0E 00 22 00 00
Response
90 00
```
*AID Configuration Example -- Set Visa Data*
```cpp
Command – Configure Label Only
39 02 00 00 F0 1B DF 66 01 01 4F 07 A0 00 00 00 9......f..O.....
03 10 10 50 0C 56 69 73 61 20 64 65 66 61 75 6C ...P.Visa defaul
74 t
Response
90 00
```
*AID Configuration Example -- Get Visa Data*
```cpp
Command
39 02 00 01 F0 0D DF 66 01 00 4F 07 A0 00 00 00
03 10 10
Response
90 00 F0 82 01 28 4F 07 A0 00 00 00 03 10 10 9F .....(O.........
09 02 00 8C DF 5F 14 FF FF FF FF FF FF FF FF FF ....._..........
FF FF FF FF FF FF FF FF FF FF FF 50 0C 56 69 73 ...........P.Vis
61 20 64 65 66 61 75 6C 74 DF 20 01 01 9F 15 02 a default. .....
59 99 9F 1C 08 30 30 30 30 30 30 30 31 9F 1B 04 Y....00000001...
00 00 00 00 DF 49 04 00 00 00 00 DF 4A 03 E0 F8 .....I......J...
C8 DF 24 04 00 00 00 00 DF 26 01 00 DF 25 01 00 ..$......&...%..
DF 21 05 00 10 00 00 00 DF 22 05 DC 40 04 F8 00 .!......."..@...
DF 23 05 DC 40 00 80 00 DF 2D 01 01 DF 27 03 9F .#..@....-...'..
37 04 DF 28 03 9F 37 04 9F 16 0F 20 20 20 20 20 7..(..7....
20 20 20 20 20 20 20 20 20 20 DF 15 01 00 9F 39 .....9
01 05 DF 3E 01 02 DF 29 00 DF 2C 00 DF 2A 00 9F ...>...)..,..*..
33 03 E0 F8 C8 DF 2B 05 01 03 00 00 00 DF 2E 01 3.....+.........
00 9F 1A 02 02 50 5F 28 02 02 50 9F 40 05 F0 00 .....P_(..P.@...
B0 A0 01 9F 35 01 22 DF 17 03 00 00 00 DF 1C 08 ....5.".........
21 20 11 02 00 00 00 00 DF 18 01 00 DF 2F 01 00 ! .........../..
DF 13 05 21 05 00 00 00 DF 12 20 36 33 30 34 31 ...!...... 63041
38 41 45 37 30 38 42 38 38 45 38 35 36 45 34 37 8AE708B88E856E47
36 39 45 36 32 39 41 43 33 37 43 DF 04 00 69E629AC37C...
```
**\[Configure CAP Keys]{.underline}**
This function provides the ADK EMV Contact framework and subsequent kernel with the CAP keys it needs. The framework checks and saves the provided data in an XML file. You can configure the XML file directly (file configuration), instead of using this function (dynamic configuration). Additionally, you can add revoked certificates for each of the keys here, if the application supports the request. Currently, maximum number of CAP keys to be stored is 100 (for both: file and dynamic configuration).
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | --- | ------- | ---- |
| x39 | x03 | x00 | x00/x01 | Data |
**P2 = 0: Set Data**
**P2 = 1: Get Data**
**Table: Response**
| Data | SW1 | SW2 | Comment |
| -------- | --- | --- | -------------------------------------------- |
| None | x90 | xXX | Function executed, xx = response code (P2=0) |
| Key data | x90 | x00 | Function executed, xx = response code (P2=1) |
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_StoreCAPKey()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#gade5b2bbc6ab46c4b7d9efa991b696ad2), [EMV\_CT\_ReadCAPKeys()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga429a19bcd6b86ff1f165ff681ae6c79a), [EMV\_CT\_GetCAPKeyInfo()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga597af0018e1df21cfbd7e52fd4756c9a)
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
**Table: CA Key Configuration Control**
| Tags | Size | Description |
| ---- | ---- | ------------------------------------------------------------------------------------------------------------ |
| DF66 | 1 | CA Key Set Request:
0x01 > Write one CA Key
0x10 > Clear one CA Key
0x20 > Clear all CA Keys
|
**Table: CA Key Configuration Data**
| Tags | Size | Description |
| ---- | ------- | ---------------------------------------- |
| DF09 | 1 | Key Index |
| DF0B | 248 Max | Key Data (modulus) |
| DF0A | 5 | Associated RID |
| DF0D | 1 | 3 (0x03) or 65535 (0x01) |
| DF0C | 20 | SHA-1 of RID, Index, Key, Exp |
| DF0E | Var | Revocation Serial Numbers (3 bytes each) |
*Defaults and Example*
The default is an empty CAP Key list. Not configuring keys will result in card authentication failure and the corresponding TVR bits will be raised by the kernel. Once a hash is included to the CAP key injection, this will be cross checked. If not Ok, the injection will be rejected.
**EMV CA Key Configuration Example**
*CA Key Configuration Example -- Set Visa Key 99*
```cpp
Command
39 03 44 00 F0 81 AF DF 66 01 01 DF 09 01 99 DF
0A 05 A0 00 00 00 03 DF 0B 81 80 AB 79 FC C9 52
08 96 96 7E 77 6E 64 44 4E 5D CD D6 E1 36 11 87
4F 39 85 72 25 20 42 52 95 EE A4 BD 0C 27 81 DE
7F 31 CD 3D 04 1F 56 5F 74 73 06 EE D6 29 54 B1
7E DA BA 3A 6C 5B 85 A1 DE 1B EB 9A 34 14 1A F3
8F CF 82 79 C9 DE A0 D5 A6 71 0D 08 DB 41 24 F0
41 94 55 87 E2 03 59 BA B4 7B 75 75 AD 94 26 2D
4B 25 F2 64 AF 33 DE DC F2 8E 09 61 5E 93 7D E3
2E DC 03 C5 44 45 FE 7E 38 27 77 DF 0C 14 4A BF
FD 6B 1C 51 21 2D 05 55 2E 43 1C 5B 17 00 7D 2F
5E 6D DF 0D 01 03
Response
90 00
```
#### Transaction Commands
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
Use the following to implement Transaction Commands:
* [Starting a Transaction](#anchor_emv_ct_starting_a_transaction)
* [Continue a Transaction Offline Part](#anchor_emv_ct_continue_a_transaction__offline_part)
* [Continue a Transaction Online Part](#anchor_emv_ct_continue_a_transaction__online_part)
* [Fetching Additional Tags](#anchor_emv_ct_fetching_additional_tags)
* [Send EMV PIN to Smart Card](#anchor_emv_ct_send_emv_pin_to_smart_card)
#### Transaction Sequence
The following illustration shows the transaction sequence flow.
**Starting a Transaction**
You can use this function to start a transaction, which runs application selection. Terminals are usually configured with several applications, but on the ICC, the configuration may include one or several applications.
You should determine which application to use for payment transactions.
Use the following ways to find out how the ICC and the terminal (000candidate list) support AIDs:
* **PSE** Only possible with the support of terminal and ICC. ICC contains a directory including all supported applications. Find intersection with the terminal's supported AIDs.
* **Explicit** **Select** for all terminal-known applications. If there are several candidates, a callback prompts the cardholder to choose the application. The Final SELECT is done for the chosen application. The ICC works on the AID's data. *Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | --- | --- | -------- |
| x39 | x10 | x00 | x00 | Txn Data |
**Table: Response**
| Data | SW1 | SW2 | Comment |
| -------------------------------- | --- | --- | ------------------------------------- |
| txn data (application selection) | x90 | xXX | Function executed, xx = response code |
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_StartTransaction()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gac13472c2a4aea6475fe7bb52627e97eb)
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
*Defaults and Example*
Use this function to initialize a transaction. You can set the known amount, transaction type, currency, date, time and a number of transaction options. You should supply these essential transaction parameters at this point, although you can change parameters further during transaction processing. In contact mode this step performs application selection including the final select. Subsequently the application may proceed with its own apps kernel or use `Continue_Offline` to use the EMV kernel to process an EMV transaction.
*Typical tags*
This section presents an overview of typical tags for the Start transaction.
**Table: Start Transaction Command Data**
| Tag | Size | Mandatory | Description |
| ---- | ---- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 9C | 1 | Y | Transaction type, according to ISO 8583 - Annex A:
Processing Code, Position 1 + 2
|
| 9F02 | 6 | Y | Transaction amount auth |
| 5F2A | 2 | - | Currency code to be used for transaction.
Only needed in case of DCC
|
| 5F36 | 1 | - | Currency exponent to be used for transaction. Only needed in case of DCC |
| 9A | 3 | Y | Transaction date (YYMMDD).
E105 RTC does not supply transaction date.
|
| 9F21 | 3 | Y | Transaction time (HHMMSS).
E105 RTC does not supply transaction time.
|
| 9F41 | 4 | Y | Transaction Sequence Counter
Must be supplied. E105 does not keep sequence counter.
|
| 9F03 | 6 | - | Amount Other (CashBack) |
| DF40 | 1 | - | Force Online (if supported by AID config) 0x01 = True, 0x00 = False |
| DF43 | 1 | - | Force Accept (if supported by AID config) 0x01 = True, 0x00 = False |
| DF48 | 1 | - | "Request ARQC from card, but don't set "suspicious bit"
0x01 = True, 0x00 = False
|
| DF57 | 1 | - | Account Type:
> 0x00 Default
> 0x10 Savings
> 0x20 Cheque Debit
> 0x30 Credit
|
| DF47 | 1 | - | Preselected customer language.
See Different Languages .
|
| DF34 | 1 | - | Amount confirmation (if not PIN + Amount Confirm) not configured):
> 0x00 Confirm Amount immediately after language selection before CVM
> 0x01 Confirm Amount after cardholder verification
|
| DF05 | 1 | - | Build App List:
> 0x00 Reuse the existing list and remove the currently activated AID, e.g. 6985 at GPO
> 0x01 Build a new candidate list (needs to be set on start of transaction)
> 0xFn Reuse the existing list do not remove anything and select candidate n of the candidate list
|
| DF45 | 1 | - | Do not process PSE (E105 default is False): 0x01 = True, 0x00 = False |
| DF4D | 1 | - | Cardholder confirmation: 0x00 = Yes, 0x01 = No |
| DF36 | 5 | - | See [Options for transaction processing](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___d_e_f___f_l_o_w___i_n_p_u_t___c_t/group___t_x_n___o_p_t_i_o_n_s.md) . |
| DF37 | 3 | - | See [Re-entrance options](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___d_e_f___f_l_o_w___i_n_p_u_t___c_t/group___t_x_n___s_t_e_p_s.md) . |
**Table: Start Transaction Response Data**
| Tag | Size | Mandatory | Description |
| ---- | ---- | --------- | ---------------------------------------------------------------------------------------------------- |
| 84 | 17 | - | DF Name |
| 50 | 17 | - | App Label (not App Label according to EMVCo) |
| DF33 | Var | - | App Name |
| 9F11 | 1 | - | Issuer code table |
| 9F12 | Var | - | App preferred name |
| 5F2D | Var | - | Preferred language |
| DF62 | 15 | - | EMV Framework Error data |
| DF63 | 1 | - | Display Text Index |
| DF4E | - | - | 0x80 = final amount (9F02/81) is required for application initialization (GPO) |
| FF03 | var | - | Candidate list containing:
DF04 - AID
50 - App Label (not App Label according to EMVCo)
|
| DF04 | 17 | - | Selected AID Name |
**EMV Start Transaction Examples**
*Start Transaction Command for EUR 1.00 on Multi App Card*
```cpp
Start Command >>
39 10 00 00 F0 2C 9F 02 06 00 00 00 00 01 00 5F
2A 02 09 78 5F 36 01 02 9A 03 13 02 01 9F 21 03
12 00 00 9C 01 00 DF 05 01 01 DF 36 05 01 00 00
00 00
AppSel Callback Command <<
91 01 F0 34 BF 04 31 DF 74 01 01 50 0B 56 69 73
61 20 43 72 65 64 69 74 50 0A 4D 61 73 74 65 72
63 61 72 64 DF 04 07 A0 00 00 00 03 10 10 DF 04
07 A0 00 00 00 04 10 10
AppSel Callback Response >>
92 01 F0 04 DF 75 01 01
Start Response <<
90 00 F0 66 84 07 A0 00 00 00 03 10 10 50 0B 56
69 73 61 20 43 72 65 64 69 74 9F 11 01 01 5F 2D
08 65 6E 65 73 64 65 66 72 DF 4E 01 00 FF 03 17
DF 04 07 A0 00 00 00 03 10 10 50 0B 56 69 73 61
20 43 72 65 64 69 74 FF 03 16 DF 04 07 A0 00 00
00 04 10 10 50 0A 4D 61 73 74 65 72 63 61 72 64
DF 04 07 A0 00 00 00 03 10 10
Start Transaction Command for EUR 1.00 on single app card
Start Command >>
39 10 00 00 F0 24 9F 02 06 00 00 00 00 01 00 5F
2A 02 09 78 5F 36 01 02 9A 03 13 02 01 9F 21 03
12 00 00 9C 01 00 DF 05 01 01
Start Response <<
90 00 F0 48 84 07 A0 00 00 00 03 10 10 50 0F 43
52 45 44 49 54 4F 20 44 45 20 56 49 53 41 DF 33
0B 56 49 53 41 20 43 52 45 44 49 54 9F 11 01 01
9F 12 0F 43 52 45 44 49 54 4F 20 44 45 20 56 49
53 41 DF 04 07 A0 00 00 00 03 10 10
```
**Continue a Transaction (Offline Part)**
This section presents an overview on typical tags for continuing the transaction after the final selection by using the EMVCo CT kernel.
If the "EMV Start Transaction" phase results in an EMV application being found on the card, then a transaction shall be performed. The EMV Offline Transaction performs the offline part of an EMV transaction.
During the EMV Offline Transaction various Callback shall be used. Some of the Callback require UI processing and checking by the host device. The potential callbacks are:
* **Amount** **Conf:** For Amount Confirmation
* **Hotlist/Log**: For Transaction Log and Hotlist
* **Domestic/Local** Checks: For local PAN checks
* **DCC:** For DCC processing.
You can use this function to perform offline EMV transactions. Possible results for Offline Transactions:
* Decline
* Accept offline
* Go online
* Terminate
* Fallback.
The following diagram shows the flow for offline transactions.
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | --- | --- | -------- |
| x39 | x11 | x00 | x00 | Txn Data |
**Table: Response**
| Data | SW1 | SW2 | Comment |
| ----------------------------- | --- | --- | ------------------------------------- |
| txn data (txn result offline) | x90 | xXX | Function executed, xx = response code |
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_ContinueOffline()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#ga8be6df6babc587a19f63f284b2a6f006)
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
*Defaults and Example*
Use this section to determine how to continue an offline EMV transaction. You can change the amount, add a cashback amount, add the transaction counter for this AID and configure a few more transaction parameters (e.g., callbacks supported). In contact mode, this step performs the offline part of the transaction, ending with the 1st GAC. The payment is completed after this step.
**Table: EMV Transaction Offline Command Data**
| Tag | Size | Mandatory | Description |
| ---- | ---- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 9F02 | 6 | - | Transaction amount auth |
| 5F2A | 2 | - | Currency code to be used for transaction.
Only needed in case of DCC
|
| 5F36 | 1 | - | Currency exponent to be used for transaction. Only needed in case of DCC |
| 9A | 3 | - | Transaction date (YYMMDD). |
| 9F21 | 3 | - | Transaction time (HHMMSS). |
| 9F03 | 6 | - | Amount Other (CashBack) |
| DF40 | 1 | - | Force Online (if supported by AID config)
0x01 = True, 0x00 = False
|
| DF43 | 1 | - | Force Accept (if supported by AID config)
0x01 = True, 0x00 = False
|
| DF48 | 1 | - | Request ARQC from card, but don't set "suspicious bit"
0x01 = True, 0x00 = False
|
| DF57 | 1 | - | Account Type:
> 0x00 Default
> 0x10 Savings
> 0x20 Cheque Debit
> 0x30 Credit
|
| DF47 | 1 | - | Preselected customer language.
See Different Languages .
|
| DF34 | 1 | - | Amount confirmation (if not PIN + Amount Confirm) not configured):
> 0x00 Confirm Amount immediately after language selection before CVM
> 0x01 Confirm Amount after cardholder verification
|
| DF14 | Var | - | Additional Tags |
| DF36 | 5 | - | See EMV Transaction Options (Tag DF36) |
| DF37 | 3 | - | See EMV Transaction Steps (Tag DF37) |
**Table: EMV Transaction (offline and online) Response Data**
| Tag | Size | Mandatory | Description |
| ---- | ---- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| - | - | - | For Card Data See:
> Offline Transaction Card Data
> Online Transaction Card Data
> Online Transaction with Online PIN Card Data
|
| DF42 | 4 | - | Status Info |
| 9F27 | 1 | - | Cryptogram information data (CID) |
| 9F36 | 2 | - | Application transaction counter (ATC) |
| 9F26 | 8 | - | Application cryptogram |
| 9F39 | 1 | - | POS entry mode |
| 9F41 | 4 | - | Transaction Sequence Counter |
| 5F34 | 1 | - | PAN sequence number |
| 9F10 | 9 | - | Issuer Application Data |
| 9F37 | 4 | - | Unpredictable Number |
| 95 | 5 | - | Terminal Verification Results |
| 9A | 3 | - | Transaction Date |
| 9F21 | 3 | - | Transaction Time |
| 9C | 1 | - | Transaction Type |
| 5F2A | 2 | - | Transaction Currency Code |
| 82 | 2 | - | Application Interchange Profile |
| 9F1A | 2 | - | Terminal Country Code |
| 9F34 | 3 | - | CVM Results |
| 9F33 | 3 | - | Terminal Capabilities |
| 9F35 | 1 | - | Terminal Type |
| 9F1E | 8 | - | Interface Device (IFD) serial number |
| 84 | 17 | - | 1 Byte Length. Dedicated File (DF) Name |
| 9F09 | 2 | - | vApplication Version Number |
| DF08 | Var | - | Script Result Critical |
| DF07 | Var | - | Script Result Uncritical |
| 9B | 2 | - | Transaction Status Information |
| 9F06 | 17 | - | Application Identifier (AID) |
| DF29 | Var | - | Additional Tags |
| 9F53 | 1 | - | Transaction Category Code |
| 9F02 | 6 | - | Amount [Auth](/adk-5.0-programmers-guide/readme/annotated/class_auth.md) Numeric |
| 9F03 | 6 | - | Amount [Auth](/adk-5.0-programmers-guide/readme/annotated/class_auth.md) Other |
| 9F12 | 17 | - | Application name, zero terminated |
| 5F25 | 3 | - | Application Effective Date |
| 5F28 | 2 | - | Issuer Country Code |
| 9F45 | 2 | - | Data Authentication Code, present if SDA card |
| 9F4C | 9 | - | 1 Byte Length. optional: present if DDA/CDA card |
| DF21 | 5 | - | Terminal Action Code - Denial |
| DF22 | 5 | - | Terminal Action Code - Online |
| DF23 | 5 | - | Terminal Action Code - Default |
| 9F0E | 5 | - | Issuer Action Code - Denial |
| 9F0F | 5 | - | Issuer Action Code - Online |
| 9F0D | 5 | - | Issuer Action Code - Default |
| 9F40 | 5 | - | Additional Terminal Capabilities |
| 5A | 10 | - | PAN |
| 57 | 19 | - | Track 2 equivalent data |
| DF62 | 15 | - | Additional error data, filled if transaction is not successful |
| DF64 | 32 | - | Kernel Debug |
| 9F16 | 15 | - | Merchant Identifier |
| DF63 | 1 | - | Filled with index of display text id if anything should be displayed |
| 5F20 | 27 | - | 1 Byte Length. Cardholder Name |
| 5F2D | 9 | - | Language Preference (zero terminated) |
| 9F08 | 2 | - | ICC Application Version Number |
| 5F36 | 1 | - | Transaction Currency Exponent |
| DF59 | 1 | - | Number of wrong PIN entries (only in case of offline PIN) |
| 5F30 | 2 | - | Service code as defined in ISO/IEC 7813 for track 1 and track 2 format |
| DF17 | 1 | - | Fallback MID to be used. |
| 8E | 28 | - | CVM list retrieved from ICC |
EMV Offline **Transaction Example**
*Offline Transaction Command*
```cpp
Offline Command >>
39 11 00 00 F0 2D 9F 41 04 00 00 00 01 DF 46 06
00 00 00 00 00 00 DF 58 06 00 00 00 00 00 00 DF
4E 01 00 DF 47 01 00 DF 34 01 00 DF 36 05 01 2C
0C 00 00
Amount Conf Callback Command <<
91 01 F0 20 BF 02 1D DF 30 01 01 DF 31 01 02 9F
02 06 00 00 00 00 01 00 9F 03 06 00 00 00 00 00
00 9C 01 00
Amount Conf Callback Response >>
92 01 F0 04 DF 71 01 01
Hotlist/Log Callback Command <<
91 01 F0 3D BF 03 3A DF 1A 08 47 61 73 FF FF FF
FF FF DF 3D 10 2B D9 50 22 25 9D 58 31 6C 34 C2
2D 75 45 A3 10 DF 16 08 A3 EC 41 60 43 21 C9 8E
DF 3F 0A DD DD 98 76 54 22 22 E0 00 0E 5F 34 01
01
Hotlist/Log Callback Response >>
92 01 F0 00
Offline Response <<
90 E3 F0 82 01 A0 DF 3D 10 2B D9 50 22 25 9D 58
31 6C 34 C2 2D 75 45 A3 10 DF 16 08 A3 EC 41 60
43 21 C9 8E DF 3F 0A DD DD 98 76 54 22 22 E0 00
0E DF 1A 0A 47 61 73 FF FF FF FF FF FF FF DF 42
02 00 00 9F 27 01 40 9F 36 02 00 02 9F 26 08 CE
D8 D6 C7 04 15 81 69 9F 39 01 05 9F 41 04 00 00
00 01 5F 34 01 01 9F 10 07 06 01 0A 03 60 00 00
9F 37 04 B9 C2 98 98 95 05 00 00 00 00 00 9A 03
13 02 01 9F 21 03 12 00 00 9C 01 00 5F 2A 02 09
78 82 02 5C 00 9F 1A 02 02 80 9F 34 03 41 03 02
9F 33 03 E0 F8 C8 9F 35 01 22 9F 1E 08 31 32 33
34 35 36 37 38 84 07 A0 00 00 00 03 10 10 9F 09
02 00 8C 9B 02 E8 00 9F 06 07 A0 00 00 00 03 10
10 9F 12 0B 56 69 73 61 20 43 72 65 64 69 74 5F
25 03 10 01 01 5F 28 02 08 40 9F 45 02 DA C0 DF
21 05 00 10 00 00 00 DF 22 05 D8 40 04 F8 00 DF
23 05 D8 40 00 A8 00 9F 0E 05 00 50 88 00 00 9F
0F 05 F0 20 04 98 00 9F 0D 05 F0 20 04 00 00 9F
40 05 F0 00 B0 A0 01 DF 64 20 90 00 00 00 BA C1
08 00 40 40 FF FF 00 21 90 90 01 00 00 00 D1 85
6F 00 00 00 00 00 00 00 00 00 9F 16 0F 20 20 20
20 20 20 20 20 20 20 20 20 20 20 20 DF 63 01 03
5F 20 08 53 44 41 5F 4E 4F 52 4D 5F 2D 08 65 6E
65 73 64 65 66 72 9F 08 02 00 8C 5F 36 01 02 DF
59 01 00 5F 30 02 02 01 8E 1C 00 00 00 00 00 00
00 00 41 03 42 03 5E 03 43 03 1F 00 00 00 00 00
00 00 00 00 00 00
```
**Continue a Transaction (Online Part)**
This section presents an overview of the typical tags for continuing the transaction after the host call.
If the "EMV Offline Transaction" results in "Go online" then the host device must contact the Payment Host for a decision about the transaction. The Payment Host can return the following outcomes:
* Decline
* Approve
* Host not reachable
The Payment Host may send Authentication data that must be transferred to the ICC. The ICC will check Authentication data to assure authenticity of host response.
The Payment Host may also send issuer scripts, e.g. PIN (un)block, or any other proprietary commands. These must also be relayed to the ICC.
Two categories of issuer scripts:
* Critical scripts -- to be sent to ICC before GENAC2
* Uncritical scripts -- to be processed after GENAC2
You can use this function to perform online EMV transactions. Possible outcomes for Online Transactions:
* Decline
* Approve
* Host not reachable.
The host may send Authentication data to the ICC. The ICC will check the data to for authenticity of the host response.
The host may also send issuer scripts, e.g. PIN (un)block, or any other proprietary commands to the ICC.
Two categories of issuer scripts:
* Critical scripts -- to be sent to ICC before GENAC2
* Uncritical scripts -- to be processed after GENAC2.
The following diagram shows the flow for online transactions.
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | --- | --- | --------- |
| x39 | x12 | x00 | x00 | Host Data |
**Table: Response**
| Data | SW1 | SW2 | Comment |
| ---------------------------- | --- | --- | ------------------------------------- |
| txn data (txn result online) | x90 | xXX | Function executed, xx = response code |
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_ContinueOnline()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#ga42f570d2b8e66841ab9e8de7736e92d4)
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
*Defaults and Example*
Use this section to complete a transaction after host communication. The parameters do not have any default values because they are either received by the host or they are not available. This includes the response code from the host, issuer application data, as well as critical and uncritical scripts. In contact mode this step performs issuer authentication, script processing and the 2nd GAC. The transaction is completed with this step.
**Table: EMV Transaction Online Command Data (**[**EMV\_CT\_HOST\_STRUCT**](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#struct_e_m_v___c_t___h_o_s_t___s_t_r_u_c_t)**)**
| Tag | Size | Mandatory | Description |
| ---- | ---- | --------- | --------------------------------- |
| DF50 | 4 | - | OnlineResult |
| 8A | 4 | - | AuthResp |
| DF52 | 4 | - | LenAuth, AuthData |
| DF53 | 4 | - | LenScriptCrit, ScriptCritData |
| DF54 | 4 | - | LenScriptUnCrit, ScriptUnCritData |
| 89 | 4 | - | AuthorizationCode |
| DF51 | 4 | - | Result\_referral |
| DF55 | 4 | - | AuthResp\_Referral |
| DF56 | 4 | - | AuthResp\_Wrong\_PIN |
| DF57 | 4 | - | AuthResp\_Positive |
| 9F02 | 4 | - | PreAuth\_Amount |
| DF36 | 4 | - | TxnOptions |
| DF37 | 4 | - | TxnSteps |
**Table: EMV Transaction Online Response Data (**[**EMV\_CT\_TRANSRES\_STRUCT**](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#struct_e_m_v___c_t___t_r_a_n_s_r_e_s___s_t_r_u_c_t)**)**
| Tag | Size | Mandatory | Description |
| ---- | ---- | --------- | -------------------------------------------------------------------------------- |
| DF42 | 4 | - | Status Info |
| 9F27 | 1 | - | Cryptogram information data (CID) |
| 9F36 | 2 | - | Application transaction counter (ATC) |
| 9F26 | 8 | - | Application cryptogram |
| 9F39 | 1 | - | POS entry mode |
| 9F41 | 4 | - | Transaction Sequence Counter |
| 5F34 | 1 | - | PAN sequence number |
| 9F10 | 9 | - | Issuer Application Data |
| 9F37 | 4 | - | Unpredictable Number |
| 95 | 5 | - | Terminal Verification Results |
| 9A | 3 | - | Transaction Date |
| 9F21 | 3 | - | Transaction Time |
| 9C | 1 | - | Transaction Type |
| 5F2A | 2 | - | Transaction Currency Code |
| 82 | 2 | - | Application Interchange Profile |
| 9F1A | 2 | - | Terminal Country Code |
| 9F34 | 3 | - | CVM Results |
| 9F33 | 3 | - | Terminal Capabilities |
| 9F35 | 1 | - | Terminal Type |
| 9F1E | 8 | - | Interface Device (IFD) serial number |
| 84 | 17 | - | 1 Byte Length. Dedicated File (DF) Name |
| 9F09 | 2 | - | Application Version Number |
| DF08 | Var | - | Script Result Critical |
| DF07 | Var | - | Script Result Uncritical |
| 9B | 2 | - | Transaction Status Information |
| 9F06 | 17 | - | Application Identifier (AID) |
| DF29 | Var | - | Additional Tags |
| 9F53 | 1 | - | Transaction Category Code |
| 9F02 | 6 | - | Amount [Auth](/adk-5.0-programmers-guide/readme/annotated/class_auth.md) Numeric |
| 9F03 | 6 | - | Amount [Auth](/adk-5.0-programmers-guide/readme/annotated/class_auth.md) Other |
| 9F12 | 17 | - | Application name, zero terminated |
| 5F25 | 3 | - | Application Effective Date |
| 5F28 | 2 | - | Issuer Country Code |
| 9F45 | 2 | - | Data Authentication Code, present if SDA card |
| 9F4C | 9 | - | 1 Byte Length. optional: present if DDA/CDA card |
| DF21 | 5 | - | Terminal Action Code - Denial |
| DF22 | 5 | - | Terminal Action Code - Online |
| DF23 | 5 | - | Terminal Action Code - Default |
| 9F0E | 5 | - | Issuer Action Code - Denial |
| 9F0F | 5 | - | Issuer Action Code - Online |
| 9F0D | 5 | - | Issuer Action Code - Default |
| 9F40 | 5 | - | Additional Terminal Capabilities |
| 5A | 10 | - | PAN |
| 57 | 19 | - | Track 2 equivalent data |
| DF62 | 15 | - | Additional error data, filled if transaction is not successful |
| DF64 | 32 | - | Kernel Debug |
| 9F16 | 15 | - | Merchant Identifier |
| DF63 | 1 | - | Filled with index of display text ID if anything should be displayed |
| 5F20 | 27 | - | 1 Byte Length. Cardholder Name |
| 5F2D | 9 | - | Language Preference (zero terminated) |
| 9F08 | 2 | - | ICC Application Version Number |
| 5F36 | 1 | - | Transaction Currency Exponent |
| DF59 | 1 | - | Number of wrong PIN entries (only in case of offline PIN) |
| 5F30 | 2 | - | Service code as defined in ISO/IEC 7813 for track 1 and track 2 format |
| DF17 | 1 | - | Fallback MID to be used. |
| 8E | 28 | - | CVM list retrieved from ICC |
**EMV Online Transaction Example**
*Online Transaction Command*
```cpp
Online Command >>
39 12 00 00 F0 1D DF 50 01 01 8A 02 30 30 DF 52
0A 91 08 11 22 33 44 55 66 77 88 89 06 00 00 00
00 00 00
Online Response <<
90 E3 F0 82 01 9D DF 42 02 00 01 DF 3D 10 6B 81
68 B8 97 D5 75 C6 80 F1 66 BE 7B 79 4F 76 DF 16
08 7C F3 28 E0 A2 CB C8 5D DF 3F 0A DD DD 98 76
54 22 22 E0 00 0F DF 1A 0A 47 61 73 FF FF FF FF
FF FF FF 9F 27 01 40 9F 36 02 00 02 9F 26 08 72
40 46 E0 19 6D 06 7B 9F 39 01 05 9F 41 04 00 00
00 01 5F 34 01 01 9F 10 07 06 01 0A 03 60 00 00
9F 37 04 C4 21 8D F1 95 05 00 00 04 00 40 9A 03
13 02 01 9F 21 03 12 00 00 9C 01 00 5F 2A 02 09
78 82 02 5C 00 9F 1A 02 02 80 9F 34 03 42 03 00
9F 33 03 E0 F8 C8 9F 35 01 22 9F 1E 08 31 32 33
34 35 36 37 38 84 07 A0 00 00 00 03 10 10 9F 09
02 00 8C 9B 02 F8 00 9F 06 07 A0 00 00 00 03 10
10 9F 12 0A 4F 4E 4C 49 4E 45 5F 50 49 4E 5F 25
03 10 01 01 5F 28 02 08 40 9F 45 02 DA C0 DF 21
05 00 10 00 00 00 DF 22 05 D8 40 04 F8 00 DF 23
05 D8 40 00 A8 00 9F 0E 05 00 50 88 00 00 9F 0F
05 F0 20 04 98 00 9F 0D 05 F0 20 04 00 00 9F 40
05 F0 00 B0 A0 01 DF 64 20 90 00 00 00 BB C1 20
00 80 80 40 40 00 21 90 90 02 00 00 00 D1 85 6F
00 00 00 00 00 00 00 00 00 9F 16 0F 20 20 20 20
20 20 20 20 20 20 20 20 20 20 20 5F 20 0A 4F 4E
4C 49 4E 45 5F 50 49 4E 5F 2D 08 65 6E 65 73 64
65 66 72 9F 08 02 00 8C 5F 36 01 02 DF 59 01 00
5F 30 02 02 01 8E 1C 00 00 00 00 00 00 00 00 42
03 5E 03 1F 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00
```
**Fetching Additional Tags**
Use this function access all ADK EMV Contact tags used during the transaction. The standard Transaction Flow already presents all needed tags for a standard EMV transaction in a readable way (without the need of tag crawling). This function allows you to read all tags from the various tag stores used. This is useful for application-specific tags, various environments, to complete access to all tags and allow a second possibility for implementation.
The requested tag is read from the kernels tag store. If the tag is not available there, the framework tag store is searched, and if not there, the configuration parameters are searched for the tag.
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | --- | --- | ---------------- |
| x39 | x14 | x00 | x00 | Tag(s) requested |
**Table: Response**
| Data | SW1 | SW2 | Comment |
| -------- | --- | --- | ------------------------------------- |
| tag data | x90 | xXX | Function executed, xx = response code |
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_fetchTxnTags()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gab005fdec183a0c8fef18ae677cce6dc5)
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
*Defaults and Example*
Use this section to fetch transaction information once the transaction is complete. There are no defaults, but you can fetch a single tag and use it with several calls for each tag or you can you see it by providing a tag list (DOL) and fetch several tags with one call.
This is an additional function to fetch additional data or already presented data in a different way.
**Send EMV PIN to Smart Card**
Use this command to send a PIN (stored in the vault) to the ICC (see also [PIN Handling](#subsec_emv_ct_pin_handling)). This command supports both plaintext PIN and Enciphered Offline PIN. The functions need to be called after customer PIN entry. The verification result will be forwarded to the application. The encryption, forwarding and results handling are processed internally and can't be altered.
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | --- | ---- |
| x41 | x05 | 00 | x00 | --- |
**Table: Response**
| Data | SW1 | SW2 | Comment |
| ---- | --- | --- | ------------------------------------- |
| Data | x90 | xXX | Function executed, xx = response code |
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_Send\_PIN\_Offline()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#ga895cb054c344d011e9e3c6acc4aadafe)
The parameters are identical to the parameters inside tag F0 in the serial interface.
#### Evaluating Contact Transaction Results
The following status codes are returned by the EMV command interface:
**Table: EMV Command Interface Status Codes**
| Value | Definition | Comment |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0x00 | [EMV\_ADK\_OK](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga1456bb13b42906927f8a8942169b62e7) | Function successful, no error. |
| 0xE0 | [EMV\_ADK\_NOAPP](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga14713da8fe0512c8700f524279d2e573) | No common application card / terminal. |
| 0xE2 | [EMV\_ADK\_ARQC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga493578e3e0e9112d42d209b783fe1f60) | Transaction must be performed online. |
| 0xE3 | [EMV\_ADK\_TC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga555e8c267be8402d0b540253a991e1ee) | Transaction performed (offline / online). |
| 0xE4 | [EMV\_ADK\_AAC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga956701431c0cef09072c040d816e5d7b) | Transaction cancellation. |
| 0xE5 | [EMV\_ADK\_AAR](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga43a6dcc45fcf91c2ef8e73afc38ea121) | Transaction cancellation (former "card referral"). |
| 0xE6 | [EMV\_ADK\_PARAM](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga89c11346e5e636e7c9d42c6a772674bf) | Parameter error. |
| 0xE7 | [EMV\_ADK\_CARDERR](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga5db7ec54114a9799fb2f75892215ad0a) | Proprietary card error. |
| 0xE8 | [EMV\_ADK\_BADAPP](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#gab2bd25812bbdf301a668a2b1c07f63d9) | Repeat `EMV_Select` function call-up because selected application on the proprietary card is erroneous. |
| 0xE9 | [EMV\_ADK\_CVM](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga23fcc197f78dfa83f4c93f97faaa729e) | User abort during PIN input (cancel button, timeout, card removed). |
| 0xEA | [EMV\_ADK\_ABORT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga7045deba09a19eea4f7df8881a08b807) | Current transaction must be aborted. |
| 0xEB | [EMV\_ADK\_CARD\_BLOCKED](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga1dfbf84d77767d546775d51566cb9b3d) | Blocked card, regional dependent if fallback to magstripe should be done |
| 0xEC | [EMV\_ADK\_CARDERR\_FORMAT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#gacf4f664d525a588d4a4e549002e454cd) | Card error e.g. erroneous TLV coding, incorrect data. No transaction cancellation. |
| 0xED | [EMV\_ADK\_INTERNAL](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#gab0e8158b5e7019f0da44c5cbc37bae3d) | Erroneous communication to PINPad, internal error. |
| 0xEE | [EMV\_ADK\_ONLINE\_PIN\_RETRY](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga1c45091db79e3fb0564afd1c0fde9820) | Online PIN re-entered (PIN check). |
| 0xEF | [EMV\_ADK\_SAVE\_ERROR](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga19d5dde29e85ada4f706ca65644df705) | Required TLV data object is missing. (has not been entered by the application). Implementation error, no process control information (only used by the config functions). |
| 0xF0 | [EMV\_ADK\_APP\_BLOCKED](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#gab48a793910e1f71ce30d16a19f6af3e8) | Application blocked: AID evaluation at fallback, no global fallback because it is not allowed for this special blocked application. |
| 0xF1 | [EMV\_ADK\_READ\_ERROR](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#gaa385b17c04a9c6bbc0093a7ccfc3b11a) | Error while reading EMV configuration. |
| 0xF2 | [EMV\_ADK\_ERR\_HSM](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga61d626babfbbb727f0e45d7219031947) | Erroneous communication to PINPad, internal error |
| 0xF3 | [EMV\_ADK\_TLV\_BUILD\_ERR](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga4837e54c589150debdef49afb8f9b5db) | Error in TLV data object = internal error. |
| 0xF4 | [EMV\_ADK\_FALLBACK](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga5f6c47c1042b70f3753191850219e745) | Fallback to magstripe must be performed. |
| 0xF5 | [EMV\_ADK\_ONL\_PIN\_REPEAT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#gae80d82057fc9057a5555c08cbe1a013a) | Wrong Online-PIN, repeat transaction (reduced) beginning with [EMV\_CT\_StartTransaction()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gac13472c2a4aea6475fe7bb52627e97eb). |
| 0xF6 | [EMV\_ADK\_MAND\_ELEM\_MISSING](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga25a3deb540cc7a021b162caf736cedd6) | Mandatory (TLV) element missing (EMV- configuration). |
| 0xF7 | [EMV\_ADK\_INVALID\_TERM\_CAP](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga63b90cf63f7b9e1b55766589576e434e) | Invalid terminal capabilities (EMV- configuration). |
| 0xF8 | [EMV\_ADK\_REFERRAL](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga448fd17086a0da2e18f340086983c120) | A referral of the application decides if the TRX is approved or not. |
The following status codes are returned by the EMV command interface for the Re-entry feature:
**Table: Re-entry Status Codes**
| Value | Definition | Comment |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| 0xA0 | [EMV\_ADK\_APP\_REQ\_START](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#gaae0cf180db0eb31571483f68f247b395) | Application requested return start reserved codes. |
| 0xA1 | [EMV\_ADK\_APP\_REQ\_CANDIDATE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#gaed9d54e360dbfb4a72c615596c8a87fc) | Application requested return application selection. |
| 0xA2 | [EMV\_ADK\_APP\_REQ\_READREC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga7e8709216fe47553fc0c129f71846579) | Application requested return read records. |
| 0xA3 | [EMV\_ADK\_APP\_REQ\_DATAAUTH](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga3ebf5cde005e4770514ac5b6c4a93cf0) | Application requested return data authentication. |
| 0xA4 | [EMV\_ADK\_APP\_REQ\_ONL\_PIN](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga50c0c0b8fa6d7b1356c1604ad4f04e2e) | Application requested return for online PIN entry. |
| 0xA5 | [EMV\_ADK\_APP\_REQ\_OFL\_PIN](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga9f24ffaff279cf995620ec108e5f43ae) | Application requested return for offline PIN entry. |
| 0xA6 | [EMV\_ADK\_APP\_REQ\_PLAIN\_PIN](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#gae60344ca125866bbf74c921df04c6a15) | Application requested return for plaintext PIN entry. |
| 0xA7 | [EMV\_ADK\_APP\_REQ\_CVM\_END](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#gabdfc095e6577d12f82285f938328b678) | Application requested return cardholder verification. |
| 0xA8 | [EMV\_ADK\_APP\_REQ\_RISK\_MAN](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#gaeec298e8f5ee75843d4b029f06334038) | Application requested return risk management. |
| 0xAF | [EMV\_ADK\_APP\_REQ\_END](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga41a87a27c017cfc748b95d4406eecfd3) | Application requested return end of reserved codes. |
#### Transaction Callback Command
To learn about the different operation modes callback/reentrance see [Callback and Reentrance Mode](#subsubsec_emv_ct_callback_and_reentrance_mode).
Transaction callbacks can be activated to provide intermediate transaction results and update transaction parameters. All callbacks are handled in ONE function. It is called with TLV data enclosed in a constructed tag which identifies the callback type.
*Serial Interface*
* The command uses the following format:
**Table: Request**
| Data | SW1 | SW2 | Comment |
| ------------- | --- | --- | ------------------------------------------------------- |
| Callback data | x91 | xXX | Callback Request, data includes info about the callback |
* **SW2 = 0x01**: EMV Transaction Request
* **SW2 = 0x02**: External card reader request (future use)
* **SW2 = 0xFF**: Trace Data follows (see [Traces](#subsec_emv_ct_logging))
**Table: Response**
| CLA | INS | P1 | P2 | Data |
| --- | --- | -------------- | -------------- | ---- |
| x92 | xXX | not applicable | not applicable | Data |
* **INS = SW2**: From the request to indicate the response belongs to the request
The parameters inside the tag F0 are identical to the structure in the function interface (see below).
*Function Interface*
Application's callback is handed over as a function pointer to [EMV\_CT\_Init\_Framework()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t.md#ga514e39585c5a6b79632ac317593ff592). It is called with a TLV stream as input. This is enclosed in a constructed tag identifying the type of callback.
*Callback Types*
The callback types can be activated separately. The contructed tags used as identifiers can be seen in following table:
| Constructed tag | Description |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [TAG\_BF01\_CBK\_MERCHINFO](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gaf8eeceb6363ca4e9b124d67334c09f57) | Progress information for the merchant |
| [TAG\_BF02\_CBK\_AMOUNTCONF](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#ga626da7fbed5c5a9a5563cf0b9d45a4a4) | Request to let the cardholder confirm the amount |
| [TAG\_BF03\_CBK\_LOG\_HOTLIST](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#ga7db951ffee1aa377131cd752468145a4) | EMVCo features "transaction log" and "hotlist" (blacklist, exception list) |
| [TAG\_BF04\_CBK\_REDUCE\_CAND](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gababcd780ecf1c9d400ecfde024d910fe) | Application candidate list created, calling application can modify it |
| [TAG\_BF05\_CBK\_DOM\_APPS](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gafd0adcc12331559863dd65d8f7558645) | Domestic app detected during application selection |
| [TAG\_BF06\_CBK\_LOCAL\_CHECKS](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gac82fa7e4064512e71e63fd647b817d97) | Local checks after reading the PAN (and other card dat) |
| [TAG\_BF07\_CBK\_DCC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gaf335a870e9d2f299c848f76b843907f7) | DCC (Dynamic Currency Conversion, see [Dynamic Currency Change](#subsec_emv_ct_dynamic_currency_change)) |
| [TAG\_BF08\_CBK\_PIN](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gadc9d6fed84456455586fb621722ae922) | Request to let the cardholder input the PIN |
| [TAG\_BF09\_CBK\_CARDHOLDERINFO](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#ga03bf78609c19ba9c07772fcd74d8c1f1) | Information to be shown to the cardholder |
| [TAG\_BF7F\_CBK\_TRACE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#ga2bdf296e1436b64373715038c87263b2) | Traces (see [Traces](#subsec_emv_ct_logging)) |
For a detailed description refer to [Constructed tags for CT callback functions](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md).
#### Transparent ICC Commands
Use the following to implement Transparent ICC Commands:
* [Detecting a Smart Card](#anchor_emv_ct_detecting_a_smart_card)
* [Activating a Smart Card](#anchor_emv_ct_activating_a_smart_card)
* [ISO Command to a Smart Card](#anchor_emv_ct_send_an_iso_command_to_a_smart_card)
* [Deactivate a Smart Card](#anchor_emv_ct_deactivate_a_smart_card)
**Detecting a Smart Card**
Use the following information to implement the smart card detection function.
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | --- | --- | ---- |
| x41 | x01 | x00 | x00 | Data |
**Table: Response**
| Data | SW1 | SW2 | Comment |
| ---- | --- | --- | ------------------------------------- |
| None | x90 | xXX | Function executed, xx = response code |
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_SmartDetect()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_c_c___i_f___c_t/group___f_u_n_c___i_c_c___c_t.md#ga62577d8d938685a65dd2b326cb03522d)
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
**Activating a Smart Card**
Use the following information to implement the smart card activation function.
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | --- | --- | ---- |
| x41 | x02 | x00 | x00 | Data |
**Table: Response**
| Data | SW1 | SW2 | Comment |
| ---- | --- | --- | ------------------------------------- |
| Data | x90 | xXX | Function executed, xx = response code |
The following illustration shows the data flow for the function.
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_SmartReset()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_c_c___i_f___c_t/group___f_u_n_c___i_c_c___c_t.md#gaa63515431ea6f33b113fa7af5562db11)
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
**Send an ISO Command to a Smart Card**
Use the following information to implement the function.
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | --- | --- | ---- |
| x41 | x03 | x00 | x00 | Data |
**Table: Response**
| Data | SW1 | SW2 | Comment |
| ---- | --- | --- | ------------------------------------- |
| Data | x90 | xXX | Function executed, xx = response code |
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_SmartISO()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_c_c___i_f___c_t/group___f_u_n_c___i_c_c___c_t.md#ga728923e6e6be8867cf954b7c8d4414d5)
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
**Deactivate a Smart Card**
Use the following information to implement the smart card deactivation function.
*Serial Interface*
The command uses the following format:
**Table: Command**
| CLA | INS | P1 | P2 | Data |
| --- | --- | --- | --- | ---- |
| x41 | x01 | x04 | x00 | Data |
**Table: Response**
| Data | SW1 | SW2 | Comment |
| ---- | --- | --- | ------------------------------------- |
| none | x90 | xXX | Function executed, xx = response code |
The following illustration shows the Deactivate Smart Card function.
The parameters inside the tag F0 are identical to the structure in the functional interface.
*Function Interface*
[EMV\_CT\_SmartPowerOff()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_c_c___i_f___c_t/group___f_u_n_c___i_c_c___c_t.md#gab99f6946bd7815a64a54be66652c2840)
The members of the structures are identical to the parameters inside tag F0 in the serial interface.
### Dynamic Currency Change
Depending on card parameters (e.g. PAN, customer selection ,...) the calling application needs to execute the running transaction in a currency different to the one configured in [EMV\_CT\_SetTermData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga351c2deba9865081c314d818463f20c9) respectively [EMV\_CT\_SetAppliData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga73ca1735defbb65a1aae2ead1de70233).
To enable DCC feature [DCC\_CHECK](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t/group___a_p_p___f_l_o_w___c_a_p_s.md#gab46cea653620bce1d34685cb1ab851d9) must be activated in [EMV\_CT\_APPLIDATA\_STRUCT::App\_FlowCap](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t.md#a760a1211f0f7f2df285879a21e2fa9d8).
The following variants are supported:
#### Decision at callback for local checks after READ RECORD
Decision about currency change is taken in callback [EMV\_CT\_CALLBACK\_FnT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t.md#ga3ff52ae040bd291d348e505e057f02ef) with [TAG\_BF06\_CBK\_LOCAL\_CHECKS](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gac82fa7e4064512e71e63fd647b817d97).
**Schematic flow diagram (with currency change):**
**Detailed description:**
* Amount confirmation must be done after DCC decision. Configure [EMV\_CT\_CONF\_AMOUNT\_PIN](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t/group___a_p_p___f_l_o_w___c_a_p_s.md#ga646066dcb5ff2196f23e81697ece0fa0) or [CONFIRM\_AMOUNT\_AFTER\_CVM](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___d_e_f___f_l_o_w___i_n_p_u_t___c_t/group___c_o_n_f_i_r_m___a_m_o_u_n_t___w_h_e_n.md#ga3c236b770965440b570922685ba301d8).
* Transaction is going the normal way until [EMV\_CT\_CALLBACK\_FnT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t.md#ga3ff52ae040bd291d348e505e057f02ef) with [TAG\_BF06\_CBK\_LOCAL\_CHECKS](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gac82fa7e4064512e71e63fd647b817d97).
* Calling application determines, if DCC has to be done for this transaction. This check is project dependent. For example [TAG\_5A\_APP\_PAN](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga4ccedb21a71fcb6ace22bac98ba548a5) and/or [TAG\_9F42\_APP\_CURRENCY\_CODE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#gac2b5ddfa533fc2ce2612d1f126b2ed5f) may be checked. And (if DCC is allowed for the used card) the cardholder is asked for the currency to be used.
* In case **no DCC** has to be done, no special action is needed. Subsequent callback [EMV\_CT\_CALLBACK\_FnT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t.md#ga3ff52ae040bd291d348e505e057f02ef) with [TAG\_BF07\_CBK\_DCC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gaf335a870e9d2f299c848f76b843907f7) will be called and has to be answered with [MODE\_DCC\_NO\_TRX\_CONTINUE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___d_c_c___m_o_d_e.md#gab16895363cf9883dd307f4636575467d). Transaction will be completed with configured terminal currency.
* In case **DCC has to be done** calling application has to check input parameter [TAG\_DF5B\_DCC\_PROHIBIT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t.md#ga6295466514899cd71991d081038ca021).
* In case of `FALSE` (=0): no special action needed at this step. Subsequent callback [EMV\_CT\_CALLBACK\_FnT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t.md#ga3ff52ae040bd291d348e505e057f02ef) with [TAG\_BF07\_CBK\_DCC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gaf335a870e9d2f299c848f76b843907f7) will be invoked. Calling application has to fill in new currency code ([TAG\_5F2A\_TRANS\_CURRENCY](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga369ab2cc83e9b220bdfa79753f1f3962)) and exponent ([TAG\_5F36\_TRANS\_CURRENCY\_EXP](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga134c61ae2787b93c5def5bbf929f7cb4)). Amount ([TAG\_9F02\_NUM\_AMOUNT\_AUTH](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga6952b55733eff49c55768a6f7802f9e4)), floor limit ([TAG\_9F1B\_TRM\_FLOOR\_LIMIT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#gab275fa140f8e21bda8e1d0bdafe47602)) and threshold value ([TAG\_DF24\_THRESHHOLD](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t.md#gab925ead3cc4b76ac55df0d4238c9f951)) has to be converted and also given back. Return value ([TAG\_DF7D\_CBK\_DCC\_CHECK](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t/group___t_l_v___c_b_c_k___t_l_v.md#ga866150b1aa87d89f0783c4dd4eeb3d59)) must be [MODE\_DCC\_YES\_TRX\_CONTINUE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___d_c_c___m_o_d_e.md#ga3013f7c194336abee82578c1f8472bd8). Transaction will be completed in the new currency.
* In case of `TRUE:` Calling application has to set [TAG\_DF76\_CBK\_MANIPUL\_TRX](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t/group___t_l_v___c_b_c_k___t_l_v.md#ga188ecff68e5b74f42c28d8faa67778d9) to [EMV\_ADK\_AAC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___r_e_t___c_o_d_e___c_t.md#ga956701431c0cef09072c040d816e5d7b).
* Running transaction will be terminated.
* Calling application has to start a new transaction with [EMV\_CT\_StartTransaction()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gac13472c2a4aea6475fe7bb52627e97eb). As [EMV\_CT\_PAYMENT\_STRUCT::Amount](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#a30d37bb81b40a6e53cb3081ee862ddef) the converted amount has to be filled in. [EMV\_CT\_PAYMENT\_STRUCT::CurrencyTrans](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#ae1f191741d0c4b9351e7f52d69b20d73) and [EMV\_CT\_PAYMENT\_STRUCT::ExpTrans](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#aaa3e0774e163e148c88b989c3ada3b76) must be set according to the new currency to be used.
* Local check callback ([EMV\_CT\_CALLBACK\_FnT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t.md#ga3ff52ae040bd291d348e505e057f02ef) with [TAG\_BF06\_CBK\_LOCAL\_CHECKS](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gac82fa7e4064512e71e63fd647b817d97)) will be invoked as above. No special action needed for calling application. Just mirror the parameters.
* DCC callback ([EMV\_CT\_CALLBACK\_FnT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t.md#ga3ff52ae040bd291d348e505e057f02ef) with [TAG\_BF07\_CBK\_DCC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gaf335a870e9d2f299c848f76b843907f7)) will be invoked. Calling application has to give back converted values for floor limit ([TAG\_9F1B\_TRM\_FLOOR\_LIMIT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#gab275fa140f8e21bda8e1d0bdafe47602)) and threshold ([TAG\_DF24\_THRESHHOLD](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t.md#gab925ead3cc4b76ac55df0d4238c9f951)). Return value ([TAG\_DF7D\_CBK\_DCC\_CHECK](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t/group___t_l_v___c_b_c_k___t_l_v.md#ga866150b1aa87d89f0783c4dd4eeb3d59)) must be [MODE\_DCC\_YES\_TRX\_CONTINUE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___d_c_c___m_o_d_e.md#ga3013f7c194336abee82578c1f8472bd8). Amount ([TAG\_9F02\_NUM\_AMOUNT\_AUTH](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga6952b55733eff49c55768a6f7802f9e4)) and currency ([TAG\_5F2A\_TRANS\_CURRENCY](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga369ab2cc83e9b220bdfa79753f1f3962), [TAG\_5F36\_TRANS\_CURRENCY\_EXP](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga134c61ae2787b93c5def5bbf929f7cb4)) must not be mirrored unchanged at this step! Otherwise transaction will abort. Transaction will be completed in the new currency.
#### Decision at online connection
Transaction is handled online. Host decides if dynamic currency change is allowed. If yes: Transaction is terminated. The cardholder is asked to select his favourite currency. Transaction is restarted with this currency.
**Schematic flow diagram (with currency change):**
**Detailed description:**
* Including the first cryptogram the transaction is going like usual.
* In case of going online the host decides if DCC is allowed.
* If no: The transaction continues as usually.
* If yes: Host answers with protocol specific DCC information.
* Calling application has to call [EMV\_CT\_ContinueOnline()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#ga42f570d2b8e66841ab9e8de7736e92d4) with any [EMV\_CT\_HOST\_STRUCT::AuthResp](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#a50f253cd97f2612f2d5abe02959e130f) indicating "decline" (e.g. "88" for ZKA Germany).
* Running transaction will be terminated.
* If project requires: Cardholder is asked for the currency to be used.
* Calling application has to start a new transaction with [EMV\_CT\_StartTransaction()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gac13472c2a4aea6475fe7bb52627e97eb). *In case of currency change:* As [EMV\_CT\_PAYMENT\_STRUCT::Amount](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#a30d37bb81b40a6e53cb3081ee862ddef) the converted amount has to be filled in. [EMV\_CT\_PAYMENT\_STRUCT::CurrencyTrans](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#ae1f191741d0c4b9351e7f52d69b20d73) and [EMV\_CT\_PAYMENT\_STRUCT::ExpTrans](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#aaa3e0774e163e148c88b989c3ada3b76) must be set according to the new currency to be used. *In case of NO currency change:* Fill [EMV\_CT\_PAYMENT\_STRUCT::Amount](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#a30d37bb81b40a6e53cb3081ee862ddef) with the original value.
* DCC callback ([EMV\_CT\_CALLBACK\_FnT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t.md#ga3ff52ae040bd291d348e505e057f02ef) with [TAG\_BF07\_CBK\_DCC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gaf335a870e9d2f299c848f76b843907f7)): *In case of changed currency:* This function will be called unconditionally. Calling application has to give back converted values for floor limit ([TAG\_9F1B\_TRM\_FLOOR\_LIMIT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#gab275fa140f8e21bda8e1d0bdafe47602)) and threshold ([TAG\_DF24\_THRESHHOLD](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t.md#gab925ead3cc4b76ac55df0d4238c9f951)). Return value ([TAG\_DF7D\_CBK\_DCC\_CHECK](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t/group___t_l_v___c_b_c_k___t_l_v.md#ga866150b1aa87d89f0783c4dd4eeb3d59)) must be [MODE\_DCC\_YES\_TRX\_CONTINUE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___d_c_c___m_o_d_e.md#ga3013f7c194336abee82578c1f8472bd8). Amount ([TAG\_9F02\_NUM\_AMOUNT\_AUTH](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga6952b55733eff49c55768a6f7802f9e4)) and currency ([TAG\_5F2A\_TRANS\_CURRENCY](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga369ab2cc83e9b220bdfa79753f1f3962), [TAG\_5F36\_TRANS\_CURRENCY\_EXP](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga134c61ae2787b93c5def5bbf929f7cb4)) must not be changed at this step! Otherwise transaction will abort. *In case of unchanged currency:* This function may be called, depending on other transaction conditions. All values shall be mirrored unchanged and return value ([TAG\_DF7D\_CBK\_DCC\_CHECK](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t/group___t_l_v___c_b_c_k___t_l_v.md#ga866150b1aa87d89f0783c4dd4eeb3d59)) must be [MODE\_DCC\_NO\_TRX\_CONTINUE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___d_c_c___m_o_d_e.md#gab16895363cf9883dd307f4636575467d).
* Transaction will be completed in the chosen currency.
#### Decision after break at DCC callback
Transaction is aborted in case DCC is allowed. Host contact and cardholder interaction can be done outside of any callbacks. Transaction is restarted with new currency.
**Schematic flow diagram (with currency change):**
* Transaction is going the normal way until DCC callback ([EMV\_CT\_CALLBACK\_FnT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t.md#ga3ff52ae040bd291d348e505e057f02ef) with [TAG\_BF07\_CBK\_DCC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gaf335a870e9d2f299c848f76b843907f7)).
* Calling application determines, if DCC is possible for this transaction (e.g. check PAN).
* *In case NO:* return value ([TAG\_DF7D\_CBK\_DCC\_CHECK](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t/group___t_l_v___c_b_c_k___t_l_v.md#ga866150b1aa87d89f0783c4dd4eeb3d59)) must be [MODE\_DCC\_NO\_TRX\_CONTINUE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___d_c_c___m_o_d_e.md#gab16895363cf9883dd307f4636575467d). Transaction will be completed without change of the currency.
* *In case YES:* return [MODE\_DCC\_YES\_TRX\_ABORT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___d_c_c___m_o_d_e.md#ga39f2bb07ab592bed46fc75aeb756da19). TransactionFlow will abort the transaction (no display to cardholder or cashier). Calling application has the possibility to contact host for DCC decision. And (if host allows DCC) ask the cardholder for the currency to be used.
* Calling application has to start a new transaction with [EMV\_CT\_StartTransaction()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gac13472c2a4aea6475fe7bb52627e97eb). As [EMV\_CT\_SELECT\_STRUCT::TransType](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#ae9357fb5fbb42943ac347ea3b2cd4d6a) value [EMV\_ADK\_TRAN\_TYPE\_REPEAT\_AMOUNT\_CHANGE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___d_e_f___f_l_o_w___i_n_p_u_t___c_t/group___t_r_a_n_s___t_y_p_e_s___c_t.md#gac505daa3b605ab4a797b9b84296fb1a4) has to be used. *In case of currency change:* As [EMV\_CT\_PAYMENT\_STRUCT::Amount](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#a30d37bb81b40a6e53cb3081ee862ddef) the converted amount has to be filled in. [EMV\_CT\_PAYMENT\_STRUCT::CurrencyTrans](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#ae1f191741d0c4b9351e7f52d69b20d73) and [EMV\_CT\_PAYMENT\_STRUCT::ExpTrans](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#aaa3e0774e163e148c88b989c3ada3b76) must be set according to the new currency to be used. *In case of NO currency change:* Fill [EMV\_CT\_PAYMENT\_STRUCT::Amount](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t.md#a30d37bb81b40a6e53cb3081ee862ddef) with the original value.
* DCC callback ([EMV\_CT\_CALLBACK\_FnT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t.md#ga3ff52ae040bd291d348e505e057f02ef) with [TAG\_BF07\_CBK\_DCC](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gaf335a870e9d2f299c848f76b843907f7)) *In case of changed currency:* This function will be called unconditionally. Calling application has to give back converted values for floor limit ([TAG\_9F1B\_TRM\_FLOOR\_LIMIT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#gab275fa140f8e21bda8e1d0bdafe47602)) and threshold ([TAG\_DF24\_THRESHHOLD](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t.md#gab925ead3cc4b76ac55df0d4238c9f951)). Return value ([TAG\_DF7D\_CBK\_DCC\_CHECK](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t/group___t_l_v___c_b_c_k___t_l_v.md#ga866150b1aa87d89f0783c4dd4eeb3d59)) must be [MODE\_DCC\_YES\_TRX\_CONTINUE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___d_c_c___m_o_d_e.md#ga3013f7c194336abee82578c1f8472bd8). Amount ([TAG\_9F02\_NUM\_AMOUNT\_AUTH](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga6952b55733eff49c55768a6f7802f9e4)) and currency ([TAG\_5F2A\_TRANS\_CURRENCY](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga369ab2cc83e9b220bdfa79753f1f3962), [TAG\_5F36\_TRANS\_CURRENCY\_EXP](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___e_m_v_c_o___t_a_g_s___c_t.md#ga134c61ae2787b93c5def5bbf929f7cb4)) must not be changed at this step! Otherwise transaction will abort. *In case of unchanged currency:* This function may be called, depending on other transaction conditions. All values shall be mirrored unchanged and return value ([TAG\_DF7D\_CBK\_DCC\_CHECK](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t/group___t_l_v___c_b_c_k___t_l_v.md#ga866150b1aa87d89f0783c4dd4eeb3d59)) must be [MODE\_DCC\_NO\_TRX\_CONTINUE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___d_c_c___m_o_d_e.md#gab16895363cf9883dd307f4636575467d).
* Transaction will be completed in the chosen currency.
### PIN Handling
A transaction may require cardholder PIN entry. In this case EMV ADK will call the appropiate **callback function** ([EMV\_CT\_CALLBACK\_FnT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t.md#ga3ff52ae040bd291d348e505e057f02ef) with [TAG\_BF08\_CBK\_PIN](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gadc9d6fed84456455586fb621722ae922)).
Input from EMV ADK (encapsulated in `TAG_BF08_CBK_PIN`):
* PIN Type (DF79)
* Bypass Info (DF41)
* Random number (9F37)
* Public Key Modulus (DF7A)
* Public key Exponent (DF7B)
* Amount (9F02) -- only if the amount confirmation is processed together with PIN entry
* Cashback Amount (9F03) -- only if the amount confirmation is processed together with PIN entry
Output to EMV ADK:
* PIN Outcome (DF79)
* Verify Result SW12 (DF6F)
The application must implement this callback function. Three PIN methods are defined by EMV: offline plaintext, offline enciphered and online enciphered PIN. The application has to use the **Vault** to realize PIN input.
How application shall implement the callback function [EMV\_CT\_CALLBACK\_FnT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t.md#ga3ff52ae040bd291d348e505e057f02ef) with [TAG\_BF08\_CBK\_PIN](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___c_b_c_k___f_c_t___t_a_g_s___c_t.md#gadc9d6fed84456455586fb621722ae922):
* Check which *method of PIN* is required: [TAG\_DF79\_CBK\_PIN\_INFO](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t/group___t_l_v___c_b_c_k___t_l_v.md#gae1140e3c457d68c0dd795ffad8c84b29) The value is one of [Input params for PIN entry](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___a_d_k___p_i_n___p_a_r_a_m/group___a_d_k___p_i_n___i_n_p_u_t.md)
* Check if PIN bypass shall be allowed: [TAG\_DF41\_PIN\_BYPASS](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t.md#gade39b36895af55804c1fd7793695292a)
* *Version 1: Usage of GUI ADK* Realize PIN input into vault with the appropriate GUI ADK functions. *Version 2: without GUI ADK* Realize PIN input into vault with the appropriate OS functions.
* Evaluate the PIN entry result (PIN outcome can be success, timeout, bypass, cancel)
* If success and it is `EMV_PIN:` Call [EMV\_CT\_Send\_PIN\_Offline](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#ga895cb054c344d011e9e3c6acc4aadafe) to forward the entered offline PIN to the ICC for verification.
* If success and it is `POST_PROC_PIN:` Use your local host encryption routines and scripts to handle the PIN and forward it once you receive an ARQC at the end of the transaction.
* If no success, inform the EMV ADK about the outcome ([TAG\_DF79\_CBK\_PIN\_INFO](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___g_e_n_e_r_a_l___c_t/group___a_d_k___s_e_r_i_a_l_i_z_a_t_i_o_n___c_t/group___e_m_v___t_a_g_s___c_t/group___v_e_r_i___t_a_g_s___c_t/group___v_e_r_i___p_r_i_m___t_a_g_s___c_t/group___t_l_v___c_b_c_k___t_l_v.md#gae1140e3c457d68c0dd795ffad8c84b29)): [EMV\_CT\_PIN\_INPUT\_OKAY](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___a_d_k___p_i_n___p_a_r_a_m/group___a_d_k___p_i_n___r_e_t_u_r_n.md#ga6d46e6b2aa75de94de0855301068a093), [EMV\_CT\_PIN\_INPUT\_COMM\_ERR](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___a_d_k___p_i_n___p_a_r_a_m/group___a_d_k___p_i_n___r_e_t_u_r_n.md#ga6e1606e2c165d4f4af132d23f6585e37), [EMV\_CT\_PIN\_INPUT\_ABORT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___a_d_k___p_i_n___p_a_r_a_m/group___a_d_k___p_i_n___r_e_t_u_r_n.md#gaed61dc1a7482b607ebad612b3f2d7508), [EMV\_CT\_PIN\_INPUT\_BYPASS](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___a_d_k___p_i_n___p_a_r_a_m/group___a_d_k___p_i_n___r_e_t_u_r_n.md#ga5364807f6ce1265fa8f8e0228db9717c), [EMV\_CT\_PIN\_INPUT\_TIMEOUT](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___a_d_k___p_i_n___p_a_r_a_m/group___a_d_k___p_i_n___r_e_t_u_r_n.md#ga71e47e61824568f46a9c9ed547ef206b), [EMV\_CT\_PIN\_INPUT\_OTHER\_ERR](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___t_l_v___c_a_l_l_b_c_k___c_t/group___a_d_k___p_i_n___p_a_r_a_m/group___a_d_k___p_i_n___r_e_t_u_r_n.md#ga783dde28172a0a5cbe376bd56ece1a90)
#### Schematic flow diagram
### Transaction Status Information
At the end of the transaction, the status information provides the results, including Online PIN entry.
```cpp
#define EMV_ADK_SI_ONLINE_PIN_REQUIRED 0x0001u
Online PIN processing to be done.
#define EMV_ADK_SI_SIGNATURE_REQUIRED 0x0002u
Signature verification required.
#define EMV_ADK_SI_FORCED_ACCEPTANCE 0x0004u
Forced acceptance.
#define EMV_ADK_SI_USER_DEFINED_CVM 0x0008u
user defined CVM
#define EMV_ADK_SI_CUSTOMER_CARDWITHDRAWL 0x0080u
Result is EMV_ADK_ABORT because customer has pulled out the card.
#define EMV_ADK_SI_GICC_TIPPABLE 0x0100u
A tip transaction may follow this payment.
#define EMV_ADK_SI_PIN_FAILURE 0x0400u
Last entered offline PIN was wrong.
```
### Different Languages
Language selection is usually up the application, however, if not selected by the application, the EMV-ADK will run the selection during processing.
Explanation:
You can configure up to 20 languages in terminal configuration using the definitions in the header file:
```fragment
/// @defgroup TF_LANGUAGES_CT Known languages
/// @ingroup DEF_CONF_TEXT_CT
/// @brief see ::EMV_ADK_TXT_TYPE
/// @}
#define EMV_ADK_LANG_NO_LANG 0x00 ///< internal use only
#define EMV_ADK_LANG_ENGLISH 0x01 ///< English
#define EMV_ADK_LANG_GERMAN 0x02 ///< German
#define EMV_ADK_LANG_FRENCH 0x03 ///< French
#define EMV_ADK_LANG_SPANISH 0x04 ///< Spanish
….
```
However, this is to fulfill the EMVCo specs. In most cases it is expected that the application will use the config option to pre-select a language at the beginning of a transaction. This can be configured in the transaction data if the application needs to support more than one language.
There are two common ways to select the language:
* a For unattended terminals, it is usually the customer who selects the language first, before starting a transaction. Once this selection is complete, the EMVCo language selection does not take place any more (pre-selected terminal language from customer).
* b For attended machines, the customer usually selects the language after the AID is known. Therefore the results of the `StartTransaction` includes the tag 5F2D and the application can handle this on its own (GUI is part of the application not of the EMV framework) and forward the preselected language at the beginning of `ContinueOffline` function, using the same parameter as in Step [a](#a).
If either step is not performed, the framework will use the provided language list (as mentioned above) and compare it to the tag 5F2D internally to "fix" the language according to EMVCo needs.
However, there will be never a display from the framework, so it is just used for the subsequent callbacks (amount confirmation, PIN entry) to tell the application the currently selected language, which may be used by the application in customer displays.
### Display Messages
The following codes present additional information about display messages. This is optional and the application may display messages based on this information but may use return codes and debug data as well for the command.
**Table: Display Messages**
| Value | Definition | Comment |
| ----- | ---------------------------- | ---------------------------------------------------- |
| 0x00 | `EMV_TXT_NO_TXT` | No text (internal use) |
| 0x01 | `EMV_TXT_REFUND_CONF_AMOUNT` | Refund EUR XXXXXX, XX PLEASE CONFIRM. |
| 0x02 | `EMV_TXT_AMOUNT` | AMOUNT EUR XXXXXX, XX PLEASE CONFIRM |
| 0x03 | `EMV_TXT_APPROVED` | APPROVED |
| 0xA3 | `EMV_TXT_AUTH_APPROVED` | Like #EMV\_TXT\_APPROVED, but for reservation |
| 0x04 | `EMV_TXT_DECLINED` | DECLINED |
| 0xA4 | `EMV_TXT_AUTH_DECLINED` | Like #EMV\_TXT\_DECLINED, but for reservation |
| 0x05 | `EMV_TXT_NOT_ACCEPTED` | NOT ACCEPTED |
| 0x06 | `EMV_TXT_CARD_ERROR` | CARD ERROR |
| 0x07 | `EMV_TXT_PROCESSING_ERROR` | PROCESSING ERROR |
| 0x08 | `EMV_TXT_CARD_READ_OK` | Card read ok |
| 0x09 | `EMV_TXT_AUTHORIZING` | Authorizing, online txn CTLS |
| 0x10 | `EMV_TXT_REMOVE_CARD` | REMOVE CARD |
| 0x11 | `EMV_TXT_USE_CHIP_READER` | - |
| 0x12 | `EMV_TXT_USE_MAG_STRIPE` | - |
| 0x13 | `EMV_TXT_VOICEAUT` | Voice authorization in case of communication problem |
### Card Deactivation
The card is deactivated inside the ADK if:
* User aborts during Application Selection
* On internal errors
* If an AAC was requested explicitly
* If an AAC was delivered by card
* If a TC was the outcome of a transaction
* On any fallback decision or termination after GPO
* Any card read transaction after application selection process
* Always after Online processing
* On critical errors during apps selection process.
* See also chapter [Process Termination](#subsec_ct_processtermination)
The card is NOT deactivated when no common apps in the candidate list allow further processing in the application without resetting the card.
### Additional Tags
This chapter provides information how additional tags are handled using the EMV kernels and the ADK.
#### Additional tags provided by the terminal
The EMV kernel allows to define an additional tag store for each AID. This concept also reflects in the ADK interface. For additional tags there is a special configuration field in the AID configuration interface, resulting in a separate XML tag for each AID in the XML configuration file. You can configure AIDs using the EMV\_CT\_SetAppliData function (for details refer to the ADK documentation). The parameter for additional terminal tags is: unsigned char Additional\_Tags\_TRM \[EMV\_ADK\_ADD\_TAG\_SIZE] Tag + Length + Value: Additional terminal data for special applications Example: MasterCard 9F53, validity bit EMV\_CT\_INPUT\_APL\_ADD\_TAGS Tag, Struct, XML Reference: TLV tag TAG\_DF29\_ADD\_TAGS, Additional\_Tags\_TRM in [EMV\_CT\_APPLIDATA\_STRUCT::Additional\_Tags\_TRM](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t.md#ad7a6039ab1aa91113c012eab4293d664), XML Tag: XML\_TAG\_APPLIDATA\_ADDITIONAL\_TAGS\_TRM.
You need to provide probable additional terminal tags for each AID when you configure the system. If you know the value already at that time (e.g. it will not change per transaction) you can provide the final value for this tag already. Otherwise simply configure a valuable default here and update the value at the time of transaction.
For updating tags during a transaction you simply start the transaction as usual. Once the application is selected (final select performed) you can update the tags for the selected AID as needed. Once [EMV\_CT\_StartTransaction()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gac13472c2a4aea6475fe7bb52627e97eb) is completed you can use [EMV\_CT\_SetAppliData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga73ca1735defbb65a1aae2ead1de70233) with option [EMV\_ADK\_TEMP\_UPDATE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t/group___a_p_p_l_i___c_o_n_f___m_o_d_e___c_t.md#ga9014b9bb4c7b8ebf61ee98a26a7666ce) or [EMV\_CT\_updateTxnTags()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gad3dd36d27d5fa94d3f302dc4a4546b70) to update the tags according to your needs dynamically. In this way you can guarantee that in any DOL (PDOL, DDOL, CDOL, ...) the correct values are provided to the ICC.
Example: `{unsigned char additionalTagsTerminal[] = {0x9F,0x53,0x01,0x52};`
#### Additional tags provided by the ICC
Data sent by the card during SELECT, READ RECORDS and GENERATE AC operations is either stored by the L2 kernel or automatically stored by the EMV ADK automatic tag store. In both cases [EMV\_CT\_fetchTxnTags()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gab005fdec183a0c8fef18ae677cce6dc5) with option [EMV\_ADK\_FETCHTAGS\_KERNEL](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___d_e_f___f_l_o_w___o_u_t_p_u_t___c_t/group___f_e_t_c_h___t_a_g_s___o_p_t_i_o_n_s___c_t.md#gaf2ba6457aff8e9f5bc3acc1b84715061) offers access to these tags, no matter which part stored the data.
{% hint style="info" %}
Previous approaches to use [EMV\_CT\_APPLIDATA\_STRUCT::Additional\_Tags\_CRD](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t.md#acd89bdbc00f19a23befec2eed0ff7b00) are deprecated and no more supported.
{% endhint %}
#### Additional tags read with GET DATA
[EMV\_CT\_fetchTxnTags()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gab005fdec183a0c8fef18ae677cce6dc5) with option [EMV\_ADK\_FETCHTAGS\_GET\_DATA](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___d_e_f___f_l_o_w___o_u_t_p_u_t___c_t/group___f_e_t_c_h___t_a_g_s___o_p_t_i_o_n_s___c_t.md#ga4aaa4083df605146b8ca652c6ceee553) will cause a GET DATA command sent to ICC.
### Handling of special tags
#### Mandatory ICC tags
There are domestic specifications defining mandatory ICC tags. In case the ICC does not provide them the transaction must be declined. To realize this requirement one has to set these tags in [EMV\_CT\_APPLIDATA\_STRUCT::Mandatory\_Tags\_CRD](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t.md#a15601aa3b54c9da3032a3ed1d43b0b6b). EMV ADK will decline the transaction if any of these tags is not provided by the ICC.
### Priority applications
An EMV chipcard may include *several applications (AIDs)* . In case the terminal supports more than one of them, the *cardholder has to select* one for the transaction. In many countries the cards are equipped with one (or more) national application(s) and one (or more) international. Example for Germany: national = girocard, international = maestro
In these countries it's usual to have **rules** in place like this: `if card_supports_national_issuer then use_national_issuer` `else use_international_issuer`
To realize this requirement the EMV Framework supports so called "priority applications".
**Example for configuration:** *Requirement:* girocard (AID A0 00 00 00 03 59 10 10 02 80 01) shall take priority over maestro (AID A0 00 00 00 04 30 60). *Configuration:*
* Configure girocard as usual (with [EMV\_CT\_SetAppliData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga73ca1735defbb65a1aae2ead1de70233)).
* Configure maestro with desired parameters. As usually use [EMV\_CT\_SetAppliData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga73ca1735defbb65a1aae2ead1de70233). In [EMV\_CT\_APPLIDATA\_STRUCT::xAIDPrio](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t.md#aafdd60748ec764b0398657d3a87e0d19) fill in girocard AID (A0 00 00 00 03 59 10 10 02 80 01).
*Transaction behavior:* In case a card is inserted, which supports both girocard and maestro, the transaction is (automatically) done with girocard (*without cardholder selection*).
### Virtual terminal mapping table
There may be the need to use different parameter sets per transaction type or currency. Typical use case is setting the floor limit to zero for refund. And of course you have to set different floor limit for different currency. This requirement can be realized by the "Virtual terminal mapping table". Approach lets you to have several parameter sets for the same application.
It goes this way:
1. **Create a mapping table** for linkage between a. virtual terminal ID and b. transaction type respectively currency
For each desired map entry call [EMV\_CT\_MapVirtualTerminal()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#gab5d29810043af901c08736d4e9337353). Pre-condition: [EMV\_CT\_Init\_Framework()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t.md#ga514e39585c5a6b79632ac317593ff592) for any Virtual Terminal has been called before. Don't use Virtual Terminal value zero as this is used as "default": It's used in case the current transaction does not match any table entry.
2. **Set parameters for the virtual terminals** For virtual terminal 0 and every entry in above created table you have to a. Set to virtual terminal: [EMV\_CT\_Init\_Framework()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t.md#ga514e39585c5a6b79632ac317593ff592), set `options` accordingly (e.g. [EMV\_CT\_INIT\_VIRT\_1](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t/group___c_t_i_n_i_t___o_p_t_i_o_n_s.md#gaf4074eda84324e107cb5ad73458868c8), [EMV\_CT\_INIT\_VIRT\_2](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t/group___c_t_i_n_i_t___o_p_t_i_o_n_s.md#ga3fe310b168e70a4bf7e383bdd7d78494), or ...) For virtual terminal 0: set most significant byte to zero. b. Set terminal data: [EMV\_CT\_SetTermData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga351c2deba9865081c314d818463f20c9) c. Set application data: [EMV\_CT\_SetAppliData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga73ca1735defbb65a1aae2ead1de70233), if needed clear history with [EMV\_ADK\_CLEAR\_ALL\_RECORDS](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t/group___a_p_p_l_i___c_o_n_f___m_o_d_e___c_t.md#ga7bc8a670f539230cb315ba2cb7442ea8) d. Set keys: [EMV\_CT\_StoreCAPKey()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#gade5b2bbc6ab46c4b7d9efa991b696ad2), if needed clear history with [EMV\_ADK\_CLEAR\_ALL\_RECORDS](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t/group___a_p_p_l_i___c_o_n_f___m_o_d_e___c_t.md#ga7bc8a670f539230cb315ba2cb7442ea8)
3. **Reset virtual terminal to zero** To have a defined state: [EMV\_CT\_Init\_Framework()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t.md#ga514e39585c5a6b79632ac317593ff592) with most significant byte set to zero
4. **Apply the configuration** if [EMV\_CT\_INIT\_OPT\_CONFIG\_MODE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t/group___c_t_i_n_i_t___o_p_t_i_o_n_s.md#gab256e2810f51ed6cc87ea9d5536b7e1e) is set: use [EMV\_CT\_ApplyConfiguration()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga3170974cb7a73a9dec8f881295cc1cac) to write the configuration to disk
5. **Execute transactions** Use transaction commands as usual: [EMV\_CT\_StartTransaction()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gac13472c2a4aea6475fe7bb52627e97eb), [EMV\_CT\_ContinueOffline()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#ga8be6df6babc587a19f63f284b2a6f006), [EMV\_CT\_ContinueOnline()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#ga42f570d2b8e66841ab9e8de7736e92d4) EMV ADK will take care that parameter set matching current transaction's currency/transaction type is used.
Remark: The order of 1. and 2. can be changed.
### "Original" Virtual Terminal Approach
[Virtual terminal mapping table](#subsec_emv_ct_virt_term_map) provides useful feature allowing application to map different input data (like currency or transaction type) with preconfigured parameters set. However, sometimes it is useful to have different parameter sets without mapping them to transaction data fields. In case we just want to have different parameter sets and switch between them on demand, we still can use the same approach, but this time without calling method [EMV\_CT\_MapVirtualTerminal()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#gab5d29810043af901c08736d4e9337353), since there is no mapping anymore.
{% hint style="info" %}
This functionality is supported by Vertex framework only.
{% endhint %}
So, in order to work with different parameter sets, first, we need to prepare them and save them in the terminal's flash memory. All parameters will be automatically saved with ids added to their parameter file names: EMV\_CT\_Applications.xml for virtual terminal 0, EMV\_CT\_Applications\_01.xml - for virtual terminal with id == 1, etc.
Workflow should follow the algorithm described below:
1. **First, set parameters for your virtual terminals** For each virtual terminal you have to a. Set Vertex framework into configuration mode first by calling [EMV\_CT\_Init\_Framework()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t.md#ga514e39585c5a6b79632ac317593ff592) with option [EMV\_CT\_INIT\_OPT\_CONFIG\_MODE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t/group___c_t_i_n_i_t___o_p_t_i_o_n_s.md#gab256e2810f51ed6cc87ea9d5536b7e1e) enabled, set other `options` accordingly (e.g. [EMV\_CT\_INIT\_VIRT\_1](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t/group___c_t_i_n_i_t___o_p_t_i_o_n_s.md#gaf4074eda84324e107cb5ad73458868c8) for your first Virtual Terminal, [EMV\_CT\_INIT\_VIRT\_2](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t/group___c_t_i_n_i_t___o_p_t_i_o_n_s.md#ga3fe310b168e70a4bf7e383bdd7d78494) - for second and so on) b. Set terminal data: [EMV\_CT\_SetTermData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga351c2deba9865081c314d818463f20c9) c. Set application data: [EMV\_CT\_SetAppliData()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga73ca1735defbb65a1aae2ead1de70233), if needed clear history with [EMV\_ADK\_CLEAR\_ALL\_RECORDS](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t/group___a_p_p_l_i___c_o_n_f___m_o_d_e___c_t.md#ga7bc8a670f539230cb315ba2cb7442ea8) d. Set keys: [EMV\_CT\_StoreCAPKey()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#gade5b2bbc6ab46c4b7d9efa991b696ad2), if needed clear history with [EMV\_ADK\_CLEAR\_ALL\_RECORDS](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___d_e_f___c_o_n_f___a_p_p_l_i___c_t/group___a_p_p_l_i___c_o_n_f___m_o_d_e___c_t.md#ga7bc8a670f539230cb315ba2cb7442ea8) e. Switch configuration mode off by calling method [EMV\_CT\_Init\_Framework()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t.md#ga514e39585c5a6b79632ac317593ff592) again, but this time without option [EMV\_CT\_INIT\_OPT\_CONFIG\_MODE](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t/group___c_t_i_n_i_t___o_p_t_i_o_n_s.md#gab256e2810f51ed6cc87ea9d5536b7e1e) enabled. f. call [EMV\_CT\_ApplyConfiguration()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t/group___f_u_n_c___c_o_n_f___c_t.md#ga3170974cb7a73a9dec8f881295cc1cac) to write configuration to disk.
2. **Execute transactions** Use transaction commands as usual: [EMV\_CT\_StartTransaction()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gac13472c2a4aea6475fe7bb52627e97eb), [EMV\_CT\_ContinueOffline()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#ga8be6df6babc587a19f63f284b2a6f006), [EMV\_CT\_ContinueOnline()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#ga42f570d2b8e66841ab9e8de7736e92d4) EMV ADK will take care that parameter set matching current Virtual Terminal will be used.
3. **Switch Virtual Terminal** In order to switch to another set of parameters (to another Virtual Terminal), you need to call [EMV\_CT\_Init\_Framework()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t.md#ga514e39585c5a6b79632ac317593ff592) with appropriate Virtual Terminal ID ([EMV\_CT\_INIT\_VIRT\_1](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t/group___c_t_i_n_i_t___o_p_t_i_o_n_s.md#gaf4074eda84324e107cb5ad73458868c8) for ID 1, [EMV\_CT\_INIT\_VIRT\_2](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t/group___f_u_n_c___i_n_i_t___c_t/group___c_t_i_n_i_t___o_p_t_i_o_n_s.md#ga3fe310b168e70a4bf7e383bdd7d78494) for ID 2 etc.). Once done, transactions are performed using usual methods without any additional modifications ([EMV\_CT\_StartTransaction()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#gac13472c2a4aea6475fe7bb52627e97eb), [EMV\_CT\_ContinueOffline()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#ga8be6df6babc587a19f63f284b2a6f006), [EMV\_CT\_ContinueOnline()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t/group___f_u_n_c___f_l_o_w___c_t.md#ga42f570d2b8e66841ab9e8de7736e92d4)).
There is no EMV_CT_INIT_VIRT_0 defined, since 0 is reserved for your default (real) terminal. In order to return back to your default terminal set most significant option byte to zero.
EMV\_CT\_CALLBACK\_FnT, PIN handling: EMV\_CT\_Send\_PIN\_Offline()
| |
|
| | | |
| TRANSPARENT ICC COMMANDS | 41 xx | [EMV\_CT\_SmartISO()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_c_c___i_f___c_t/group___f_u_n_c___i_c_c___c_t.md#ga728923e6e6be8867cf954b7c8d4414d5) 41 03, [EMV\_CT\_SmartDetect()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_c_c___i_f___c_t/group___f_u_n_c___i_c_c___c_t.md#ga62577d8d938685a65dd2b326cb03522d) 41 01, [EMV\_CT\_SmartReset()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_c_c___i_f___c_t/group___f_u_n_c___i_c_c___c_t.md#gaa63515431ea6f33b113fa7af5562db11) 41 02, [EMV\_CT\_SmartPowerOff()](/adk-5.0-programmers-guide/readme/modules/group___a_d_k___i_c_c___i_f___c_t/group___f_u_n_c___i_c_c___c_t.md#gab99f6946bd7815a64a54be66652c2840) 41 04 | |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://sandbox-docs.verifone.com/adk-5.0-programmers-guide/readme/system_overview/pg_all_components/pg_emv_contact_users_guide.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.