> For the complete documentation index, see [llms.txt](https://sandbox-docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sandbox-docs.verifone.com/s-adk-5.1-programmers-guide/readme/system_overview/pg_all_components/pg_sdi_users_guide.md).
# ADK-SDI Programmers Guide
## Preface
This guide provides information on the usage of the SDI-Server.
### Audience
This document is intended for users that want to understand and use the SDI-Server.
### Organization
This guide is organized as follows:
[Chapter 1, Introduction](#sec_sdi_introduction): Introduction to SDI-Server.
[Chapter 2, Getting Started](#sec_sdi_getting_started): Shows the framework concepts.
[Chapter 3, Usage](#sec_sdi_usage): Presents common uses.
[Chapter 4, System Setup and Requirements](#sec_sdi_setup_sdi_server): Environment setup, description, deployment and installation of SDI download packages.
[Chapter 5, Troubleshooting](#sec_sdi_troubleshooting): Solutions for possible issues.
## Introduction
This guide is valid for SDI-Server version: 4.36.6-291-P2PE-1.6.57
### Concepts
The SDI-Server interacts with an outside Host-Application which normally includes the SDI-Client-Library for the communication between both sides. SDI-Client and SDI-Server can be run on different devices (e.g. SDI-Client on a Smart Phone and SDI-Server on an Engage device) or on one device. In the second case (on one device) the SDI-Client can be replaced by a separate library or application which controls the security deviating from the SDI standard.
### Software Components
The SDI-Server is composed of the following components:
* The Protocol Library is the central component for the communication with an outside application. To get the possibility of exchanging the communication protocol without a rebuild of the SDI-Server the library is implemented as a shared object. Currently only the e105-Protocol is available in two variants (see [Transport Layer](#subsec_sdi_transport_layer)).
* The SDI-Server itself consists of two parts: A static library (libsdicsd.a) linked to the SDI-Server which contains all functionalities regarding sensitive data handling and a common part that includes the none security relevant code. All interfaces that handle and store cardholder sensitive data are led to the libsdicsd. There is no possibiltity to retrieve these data in clear text outside the SDI-Server.
* From the following interfaces cardholder sensitive data are yield into the system:
* EMV-CT: Data are received from the CT EMVCo kernel.
* EMV-CTLS: Data are received from the different CTLS EMVCo kernels.
* MSR: Data are received from the magstripe reader (OS).
* Manual Card Data Entry: Data are received from the touch/keypad OS driver directly or via ADK-GUI.
### User Modes
The SDI Server supports the user modes standard, headless and EPP.
* In standard mode the SDI Server has full access to display and keypad on the device.
* In headless mode all display content is managed by the outside application and PIN and card data inputs are handled internally. On devices with touch screens only the SDI server needs additional information about the touch coordinates to handle the inputs. The outside application is responsible for the corresponding display content and the touch coordinates has to match.
* The EPP mode means a two piece solution consisting of a Countertop device where the SDI server runs in headless mode connected with an external Pinpad (EPP) using the SDI server in a special EPP-standard mode. Countertop and EPP are physically connected via USB. USB device detection works automatically in background with a running USB watchdog, which is implemented in SDI server: Whenever a Verifone device is plugged to USB, SDI server creates an USB network device, which allows IP communication over USB. After the USB network device is up, on EPP SDI server starts a TLS server to accept the incoming connection from Countertop. At the same time on Countertop, SDI server initiates a secure TLS connection to EPP. After TLS handshake additional negotiation commands are executed to check prerequisites of both environments including major and minor version checks of SDI-Server, EMV-CT and EMV-CTLS Framework. Result and status of this procedure is provided by [Enable EPP (20-21)](#subsubsec_sdi_sys_enable_epp), which is mandatory to active Countertop to use an attached EPP. SDI commands sent to Countertop are either executed on both devices or on Countertop/EPP only. For a couple of SDI commands the payment application has the option to address the device (Countertop or EPP) for its execution. All security relevant actions (ADE, VCL, ...) will be performed on the Countertop device only.
VOS3 devices (e.g. P630) usually have a single USB controller and if the device shall be used as Countertop the USB mode must be set to 'USB host'. If the mode is configured to 'USB device', the USB device detection is disabled, thus, SDI will act as Standalone without Countertop support. Please also note that SDI always sets the controller mode to 'USB device', if SDI is configured to run as EPP. VOS2 devices usually have separate 2 USB controllers, thus, SDI hehaves passive and just checks, if at least one of both controllers operate with the required USB mode.
The following table provides a comparison of the properties of the Countertop and the EPP:
| | | |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| | Countertop (CTP) | External Pinpad (EPP) |
| Operator | Merchant | Cardholder |
| Connection between CTP/EPP via USB | | |
| Payment Keys | Stored on CTP only |
No additional keys have to be loaded. All necessary crypto operations are done with the warrentied keys preloaded in the factory or repair centre.
|
| Supported card technologies | MSR, CT, manual card data entry | MSR, CT, CTLS |
| User Mode | Headless | Standard with EPP support |
| Configuration packages (VOS/VOS2/VOS3) | `dl.sdi_cfg-hdl-X.X.X-X-P2PE-X.X.X.tar` |
| |
Different SDI modes (recently supported on Engage only) are activated by a [SDI config package](#vos_sdi_config_package), which is additionally installed next to [SDI base package](#vos_sdi_base_package). So far, Android platfrom only supports headless mode, therefore, no SDI config packages are provided there. Finally, if SDI-Service must support EPP mode on Android (e.g. P630), some kind of configuration packages will be introduced to activate EPP mode on this platform, too.
{% hint style="info" %}
Changing SDI user mode from standard to headless (or vice versa) with the installation of the corresponding [SDI config package](#vos_sdi_config_package) will trigger an automatic fatory reset with next SDI startup. This automatic fatory reset behaves same as [Factory Reset (20-22)](#subsubsec_sdi_sys_factory_reset) and deletes all files, which SDI has created during runtime with the previous mode.
{% endhint %}
### SDI Certifications
The SDI-Server is certified against Point to Point Encryption (P2PE) Domain 2 (Application Security) and Payment Application Data Security Standard (PA-DSS).
{% hint style="info" %}
The Implementation Guides for P2PE (P2PE\_SDI\_Implementation\_Guide.pdf) and PA-DSS (SDI\_PA\_DSS\_Implementation\_Guide.pdf) coming along with documentation and can be found in the subfolder /doc/sdi.
{% endhint %}
## Getting Started
The SDI-Server is delivered as a runnable application build for a number of VOS and VOS2 devices. Loading and start up depends on the used device and will be handled by the integration packages included in the ADK deliverables. When the SDI-Server is up and running on a device the user has the possibility to execute several commands (TLV, see next section) on it.
Network communication (LAN, WLAN etc.) needs to be configured outside the SDI-Server before it can be used. For details regarding the configuration of the communication possibilities see [Using the Communication Control Panel (CCP)](/s-adk-5.1-programmers-guide/readme/system_overview/pg_all_components/pg_ccp_users_guide.md#sec_ccp_usingadkccp).
During the 1st start of the SDI-Server (in standard mode) automatically a menu pops up to select one of the available communication methods. The variety of the provided communication methods depends on the device type and interface capabilities for the corresponding device. This communication menu is also available by pressing the menu softkey on the idle screen after each start up. The interface selection and communication settings are stored to configuration file [COM\_IF.CFG](#sec_sdi_com_if_cfg) in folder `flash` next to SDI server binary. Since SDI server version >4.1.1, this communication menu also supports to display the CCP communication wizard (provided by `libccp` of ADKCOM), which allows to do the basic interface setup, such as configuration of static IP adresses or DHCP (for details see [Using the Communication Control Panel](/s-adk-5.1-programmers-guide/readme/system_overview/pg_all_components/pg_ccp_users_guide.md#sec_ccp_usingadkccp)). In case of headless mode the selection of the communication channel is configured by configuration file [COM\_IF.CFG](#sec_sdi_com_if_cfg) including the filename of the active connection profile, has to be downloaded before the SDI-Server runs. Following profiles come along with installation of SDI-Server:
| COM Profile | Related communication method |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CONNECT\_LAN.XML | TCP/IP Local Ethernet (checks for existance of network device `eth0` and binds SDI port 12000 to all available devices for internal and external access). |
| CONNECT\_BT.XML | TCP/IP BT PAN (enables BT PAN network device and binds SDI port 12000 to all available devices for internal and external access). |
| CONNECT\_WIFI.XML | TCP/IP WiFi (checks for existance of network device `wlan0` and binds SDI port 12000 to all available devices for internal and external access). |
| CONNECT\_USB\_SER.XML | USB serial |
| CONNECT\_USB\_LAN.XML | USB TCP/IP local network (checks for existance of network device `usb0` and binds SDI port 12000 to all available devices for internal and external access). |
| CONNECT\_COM1A.XML | Virtual channel depending on the devices capabilities |
| CONNECT\_BLE.XML | BLE |
| CONNECT\_COM1.XML | Serial COM Port |
| CONNECT\_ANY.XML | TCP/IP any interface (binds SDI port 12000 to all available devices for internal and external access). |
| CONNECT\_LO.XML | Localhost (binds SDI port 12000 to network device `lo` for internal access only). |
| CONNECT\_ANDROID.XML | Internal Android network (binds SDI port 12000 to IP address 192.0.2.6 (or 192.168.50.2 on old OS) for internal Android access only). |
The content of the connection selection menu is variable depending on the devices communication capabilities. The following menu entries are possible:
| Menu entry | Description and related COM profile |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ETH (LAN) | TCP/IP communication via Ethernet/LAN, COM profile: CONNECT\_LAN.XML |
| BT PAN | TCP/IP communication via Bluetooth PAN (device selectable via submenu), COM profile: CONNECT\_BT.XML |
| WiFi | TCP/IP communication via WiFi, COM profile: CONNECT\_WIFI.XML |
| USB (serial) | Serial communication via USB, COM profile: CONNECT\_USB\_SER.XML |
| USB (LAN) | TCP/IP communication via USB, COM profile: CONNECT\_USB\_LAN.XML |
| COM1A | Serial communication via virtual channel (USB and/or Bluetooth selectable via submenu), COM profile: CONNECT\_COM1A.XML |
| BLE | Serial communication via BLE, COM profile: CONNECT\_BLE.XML |
| COM1 | Serial communication via COM Port, COM profile: CONNECT\_COM1.XML |
| ANY (LAN) | TCP/IP communication with any network device, COM profile: CONNECT\_ANY.XML |
| LOCALHOST | TCP/IP communication with local loopback device (device internal network access only), COM profile: CONNECT\_LO.XML |
| ANDROID (intern) |
TCP/IP communication via internal Android network. Use this profile on CM5/M440/M424 to disable external access and allow Android side only to connect to SDI server, COM profile: CONNECT\_ANDROID.XML
Note
This profile is provided by SDI headless config package (see chapter SDI config package), which is installed for CM5/M440/M424 only. Other devices use profile CONNECT\_LO.XML, which is the default for Engage.
|
For all TCP/IP communications port 12000 is preconfigured in the connection profiles.
Serial communication settings are as follows:
* Baudrate: 115200
* Parity: none
* Databits: 8
* Stopbits: 1
* Flowcontrol: none
{% hint style="info" %}
For devices supporting Bluetooth (e.g. e285) communication channel COM1A includes a submenu to select USB or one of the paired BT devices. BT pairing needs to be performed outside the SDI-Server and before running into this menu. On special devices or configurations COM1A stands for serial communication via USB (virtual communication channel). For details see ADK-COM Programmers Guide. If BLE is selected a pairing dialog can appear in case a mobile device is connecting
{% endhint %}
Since Version 3.x the SDI-Server supports new commands to handle sensitive data ([Data Interface (29-XX)](#subsubsec_sdi_data_interface)) and access to ADK-Sec crypto functions ([Generic Crypto Interface (70-XX)](#subsec_sdi_generic_crypto_interface)). For a successful handling of all sensitive data operations a suitable configuration of the ADK-Sec stored in file **sccfg.json** is needed as well!
{% hint style="info" %}
Numerical values are usually represented in hexadecimal in this documentation. If this is not the case or if the representation is unclear (e.g. value 11), this is indicated separately by adding an index (e.g. hex) to the value. For details see [Legend](#subsec_sdi_legend).
{% endhint %}
## Usage
### Transport Layer
#### Protocol Type A: Communication with flow control
For data transfer between an outside application (e.g. a mobile phone) SDI-Server supports serveral protocol variants (protocol types).
Protocol Type A encapsulates the message data in a frame as follows:
The message length shall be coded in two bytes and is limited to 4095 bytes (the highest nibble is used for multiple block transfer). The last two bytes includes a CRC16/XMODEM checksum. Protocol Type A is recommended for communication channels without a underlying flow control (e.g. RS232 serial communication). Each received message has to be confirmed by sending an ACK to the sender of the message.
Example:
```cpp
02 41 00 04 22 01 00 00 03 7B 25 ->
<- 06
<- 02 41 00 14 90 00 47 82 65 CA 63 73 3B 39 FF FF 98 76 54 11 14 A0 00 79 03 86 5A
06 ->
```
{% hint style="info" %}
In case of a protocol error is detected (e.g. wrong message length or protocol frame corrupted etc.) the SDI-Server discards the received data and sends for protocol Type A a NAK to inform the sender.
{% endhint %}
Protocol type A supports multiple block transfer, if the command length exceeds the maximum message size. Here up to 16 message blocks each with a maximum size of 4095 bytes are possible. SDI-Server accumulates all blocks until the message is received completely before the command will be executed. The following picture demonstrates a command transfer split in three blocks:
{% hint style="info" %}
The ETB shall indicate an intermediate block. Only the last block transfer includes the ETX. The upper nibble of the length value indicates the block number.
{% endhint %}
#### Protocol Type B: Communication w/o flow control
For communication channels supporting a underlying flow control (e.g. TCP/IP) Protocol Type B is recommended:
The message length shall be coded in four bytes and is limited to 1048575 bytes in command direction respectively 65535 bytes in response direction (the highest bytes/nibbles are reserved for future use). Because of the underlying flow control neither a CRC nor an ACK is needed.
Example:
```cpp
02 42 00 00 00 04 22 01 00 00 03 ->
<- 02 42 00 00 00 14 90 00 47 82 65 CA 63 73 3B 39 FF FF 98 76 54 11 14 A0 00 79 03
```
{% hint style="info" %}
In case of a protocol error is detected (e.g. wrong message length or protocol frame corrupted etc.) the SDI-Server closes the connection immediately.
{% endhint %}
#### Protocol Type C: Multi connection support
Since version 4.7.0, SDI server has added support to accept multiple connections from several clients at the same time (draft version). With version 4.7.1, the multi connection concept was revised and improved. With the new concept the new protocol type C was introduced, which has the same message format as protocol type B.
{% hint style="info" %}
New projects, which integrate SDI the first time and require multi connection support, should prefer implementation of new protocol type D (see chapter [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)).
{% endhint %}
SDI server accepts multiple connections as follows:
* one connection for message transfer with protocol type B (**main connection**)
* multiple connections for message transfer with protocol type C (**side connections**)
Protocol type B messages can only be sent by one SDI client, which holds the main connection. The main connection provides access to full SDI function scope, such as processing payments with EMV commands. SDI server reserves the main connection with receipt of the first message having protocol type B (first come first serve). Other connections using protocol type B messages afterwards are declined with response code `64FA` (main connection already locked). From this point the SDI client is restricted to a side connection, which allows side commands with protocol type C only. For a side connection with protocol type C the function scope of SDI server is limited to the following SDI interfaces:
* [Printer Interface (25-XX)](#subsec_sdi_printer_interface)
* [PED Interface (22-XX)](#subsubsec_sdi_ped_interface)
* [System Interface (20-XX)](#subsec_sdi_system_interface)
* [Generic Crypto Interface (70-XX)](#subsec_sdi_generic_crypto_interface)
* [Data Interface (29-XX)](#subsubsec_sdi_data_interface)
{% hint style="info" %}
Not all commands of the listed interfaces above have support for protocol type C. Users should consider subchapters and if not explicitely mentioned in description for the corresponding SDI command, it is not supported as side command with protocol type C.
{% endhint %}
SDI commands having no support for protocol type C are declined by SDI server with response code `64F9` (command not allowed). In addition, side connections don't support callbacks, requests and nested commands. Side commands are usually short-term in nature and directly replied with a final response. Further, asynchronous [Payment Notification Callbacks (9E-XX)](#subsec_sdi_payment_notification_callbacks) are only issued over main connection and never send over side connections with protocol type C.
Even basically supported as side command, SDI running as Countertop will be restricted to use it with protocol tpye C, if the command requires remote processing or partial interaction with the EPP. The reason is recent SDI implementations do not support asynchronous execution of commands on EPP and a SDI Countertop is not able to forward it as EPP side command. This implies that these commands must use protocol type B (main connection), if they require remote processing by the EPP. For instance, [PED start PIN entry (22-03)](#subsubsec_sdi_ped_start_pin) will lose side command support for the SDI Countertop, since EPP will be always responsible for PIN entry, after it was enabled with [Enable EPP (20-21)](#subsubsec_sdi_sys_enable_epp). In addition, command addressed to an EPP with TLV tag `DFA150` will also be considered as payment command, which must use the main connection. In this case the command is also declined with `64F9` (command not allowed), if sent with protocol type C on a side connection.
{% hint style="info" %}
Multi connection support is provided by protocol library `lib_mADK_PP_Prot_ipc.so`. By default, this library is always used on Android platforms such as Neo, Trinity (T650) and CM5, M440 and M424. For SDI versions <= 4.21.0, multi connection support on VOS1 and VOS2 was not available, because these platforms used old protocol library `lib_mADK_PP_Prot_com.so` only. Since version 4.21.0, VOS1/VOS2 allow to enable it with parameter `multi_connect_support` in configuration file [COM\_IF.CFG](#sec_sdi_com_if_cfg). Since version 4.23.10 SDI uses defaults for all VOS platforms depending on SDI operation mode, if parameter `multi_connect_support` is not provided. For more details please refer to chapter [COM\_IF.CFG](#sec_sdi_com_if_cfg). Later VOS3 supports parameter `multi_connect_support` in the same way. Please note that protocol library `lib_mADK_PP_Prot_ipc.so` only supports TCP/IP related communication profiles. Other communication profiles like Bluetooth (e.g. as BT PAN, COM1A, BLE) or serial communication (USB and COM) are only implemented in old protocol library `lib_mADK_PP_Prot_com.so`. Thus, these profiles are no longer usable, if multi connection support with the new library is enabled. In addition, protocol type A (designed for serial communication) is implemented in old protocol library `lib_mADK_PP_Prot_com.so` only. In addition, library `lib_mADK_PP_Prot_com.so` implements protocol type B (and D since version 4.35.0, but without multi connection capability). A protocol type A command always obtains the main connection (same as for protocol type B). Instead, protocol type D requires the payment lock to obtain the main connection (see chapter [Payment lock/unlock](#para_sdi_prod_d_callback_payment_lock_unlock)), even library `lib_mADK_PP_Prot_com.so` supports a single connection only. Thus, library `lib_mADK_PP_Prot_com.so` does not support protocol type C, since this type is required for side connections only. An additional example user config package **dl.sdi-usrconfig-ipc-prot-X.X.X-X-P2PE-X.X.X.tar** comes along in subfolder `example/load/usr_config` of SDI documentation package `sdi-doc-X.X.X-X-P2PE-X.X.X.zip`. This package enables multi connection support with communication profile `CONNECT_ANY.XML`.
{% endhint %}
**Sharing the main connection with multiple SDI clients**
With older SDI versions, multiple SDI clients could share the main connection by closing and reopening the connection only. Since version 4.29.0, command [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) was enhanced with bit value `0x02` in P2 field to release the main connection without the need that the connection is closed (for more details see chapter [Sys Abort (20-02)](#subsubsec_sdi_sys_abort)). With its termination (or with command [Sys Abort (20-02)](#subsubsec_sdi_sys_abort)) the main connection is unlocked for other connections and another secondary SDI client is allowed to send a protocol type B message to obtain the main connection (payment lock). There is no such kind of notification by SDI server for secondary SDI clients, if the main connection is closed/unlocked. Therefore, SDI clients must arrange to get the payment lock for the main connection.
**Parallel command processing**
Older versions of SDI server have implemented a sequential command processing and were able to serve one client at the same time only. Thus, SDI clients were delayed as long as a command on another connection was active. Since version 4.9.3, SDI server has added support for parallel processing so that several commands on multiple connections can be served at the same time. For this feature SDI server implements a session context per connection and settings, which were configured (e.g. for [Set Printer Property (25-00)](#subsubsec_sdi_prt_set_property)), are stored per connection and kept for duration of the connection.
{% hint style="info" %}
Please note that parallel processing is not possible, if concurrent commands needs access to an exclusive resource. For instance, it won't be possible to start 2 PIN entries in parallel on 2 connections, since SDI server needs to access the PIN entry device. If one connection has started the PIN entry, all PED commands received on other connections will be declined. In addition, SDI server will delay a print command, if the printer device is already in use by another connection. The print command is processed, after the previous print job has been finished, otherwise this would lead to broken receipt contents.
{% endhint %}
#### Protocol Type D: Concurrent command support
Protocol type D was introduced since version 4.29.0 and allows a SDI client to send concurrent commands over the same connection. In addition, the protocol type can be used with multiple connections and there is no need to use different protocol types identifier in header, as required with protocol types B and C (see chapters above). Therefore, new projects, which want to integrate SDI with communications with underlying flow control (e.g. TCP/IP), should implement protocol type D, because (sooner or later) this will replace old protocol types B and C.
{% hint style="info" %}
Protocol type D with concurrent command support is provided by protocol library `lib_mADK_PP_Prot_ipc.so`. Since SDI server version 4.35.0, protocol type D is also supported by protocol library `lib_mADK_PP_Prot_com.so`, which allows concurrent commands on the same connection using message IDs to match commands with their responses. However, `lib_mADK_PP_Prot_com.so` is limited to a single connection and does not support multiple connections (multiple clients connecting simultaneously). For multi-connection support, `lib_mADK_PP_Prot_ipc.so` must be used. Protocol library `lib_mADK_PP_Prot_com.so` implements protocol types A, B and D. For more details about multi-connection support, see previous chapter [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support).
{% endhint %}
**Message format**
The message format of protocol type D is similar to B and C, except the header was enhanced by a field containing message ID to identify the command and responses on SDI server and client side.
Similar to protocol type B and C, the header consists of STX (1 byte) and 'D' (1 byte), followed by the length field (4 bytes, big endian). New is the message ID (4 bytes, big endian) inserted between the length field and data, for both, command and response. The length field contains the length of command or response data only and does not include the preceding message ID and the appended ETX.
**Message identification by ID**
The message ID is specified in command on client side and after SDI has processed the command, the same ID returned in the response so that the client is able to associate it with the command that was sent. Usually, the message ID is a numeric value (e.g. starting from 0) and each command for the connection uses the message ID of the previous command incremented by 1. In that way concurrent commands can be processed by its message ID independently, either on the same connection or on another connection, where each client uses its own range of message IDs.
Example:
**Command cancellation**
As for old protocol types the existing command [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) is used to cancel active commands. In difference to protocol types A and B, command [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) is unidirectional and SDI never provides a command response for it. Thus, command field P2 to control behaviour for command response is always ignored for protocol type D. Command [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) uses the message ID of the active command, which shall be cancelled.
Example:
{% hint style="info" %}
There is no guarantee that the active command is always cancelled. Only a small set of commands are cancelable at all and it might depend on command progress or user interaction, if it will be considered. In addition, SDI will just ignore it beyond the point of no return. Finally, command [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) with a message ID referring an inctive command is also ignored (see example above).
{% endhint %}
**Payment lock/unlock**
Even protocol type D provides best flexibility to support concurrent command processing, most SDI commands use exclusive resources or internal APIs, which still disallow concurrent invocation (e.g. EMV, MSR or card detection commands using the card reader or UI commands using the display). Therefore, SDI clients must request SDI for permission to get access to full function scope, which corresponds blocking the main connection with old protocol type B (see chapter [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support) for more details). For this reason the new command [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment) was introduced to request a global lock for the connection: the payment lock. After obtaining the payment lock successfully, the related connection is allowed to send payment commands, whereas other connections have a limited SDI function scope and only commands especially declared as "side command" can be used then. SDI clients, which send command [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment) to an already locked SDI are declined with `64FA` (already locked) immediately. The same result is returned for a payment command on a connection not owning the lock. Payment commands always require the payment lock and cannot be sent concurrently (see section [Concurrency restrictions](#para_sdi_prod_d_concurrency_restrictions)). Side commands instead do not require this lock and can be processed concurrently. A command [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment), which has obtained the payment lock successfully, is responded by SDI with a unidirectional callback [Intermediate Result Callback (99-01)](#subsubsec_sdi_intermediate_status_cb) on this connection, which means that the command is kept open without a final response as long as the payment lock is active. Command [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) with the message ID of the previous [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment) is sent by SDI client to release the payment lock again. Finally, SDI sends the final response with error code `6500` confirming that [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment) was succesfully cancelled.
Example:
{% hint style="info" %}
The list of interfaces providing side command support are list in previous chapter [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support). Users should consider subchapters and if not explicitely mentioned in description for the corresponsing SDI command, the execution as side command with protocol type C or D is not supported and requires the payment lock. A side command will fail, if the command is addressed to EPP with TLV tag `DFA150`. In this case the command is also declined with `64F9` (command not allowed). Thus, side commands are only supported for Countertop with recent SDI implementations. Further, an attched/enabled EPP might lead to additional concurrency limitations for side commands (see section [Concurrency restrictions](#para_sdi_prod_d_concurrency_restrictions)).
{% endhint %}
It is also possible that multiple SDI client applications share the same connection (e.g. a single USB connection). In this case some kind of proxy (either implemented as a seperate process or part of a SDI client library) handles the traffic for these applications on SDI client side. Further, each application might run with an own payment context meaning they act completely independent, even they require access to payment functionality of SDI. Finally, command [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment) can be send multiple times by the proxy over the same connection to cooridinate SDI clients to access SDI payment functions.
Example:
{% hint style="info" %}
The SDI proxy mustn't just pass through the message IDs (`X,Y,Z`) of the client 1:1 to SDI server, instead it must use an own unique number range (`A,B,C,...`) for all client commands to SDI server, which is mapped to back to message ID of the related client whenever a response is received. For the proxy implementation it is also recommended to care about resources and to unblock waiting participants, whenever a connection gets lost in both directions. In case of connection lost to SDI server it should response all SDI clients with an error result for all active command or just close all SDI client connections if possible (e.g. when using TCP/IP). For interruption of a SDI client connection, it should send a [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) to abort active commmands in SDI server. In addition, special handling will be required for commands [PED start PIN entry (22-03)](#subsubsec_sdi_ped_start_pin) and [Start Card Detection (23-03)](#subsubsec_sdi_start_card_detection) : These commands cannot be aborted with [Sys Abort (20-02)](#subsubsec_sdi_sys_abort), since they were already finalized with a response. Finally, SDI proxy must send of [PED stop PIN entry (22-05)](#subsubsec_sdi_ped_stop_pin) and [Stop Card Detection (23-05)](#subsubsec_sdi_stop_card_detection) to abort an active PIN entry or card detection.
{% endhint %}
{% hint style="warning" %}
Please note that SDI server is not able to detect violations of a SDI client, if it sends a payment command, when it does not own the payment lock. The reason is another client might have requested the lock before, which SDI has associated with the (one and only) connection to the proxy. The prerequesite for a such working solution is the discipline of all SDI clients, not to send any payment command before the payment lock was obtained successfully with [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment). Basically, this is the recommendation for all solutions, even if each SDI client uses it's own connection to SDI without a proxy.
{% endhint %}
**Command requests and callbacks**
Command requests and unidirectional command callbacks use the message ID of the command, for which the request or callback was triggered. Since side commands don't have support for it, requests and callbacks are only sent for payment commands. Finally, the SDI client uses same the message ID received with the request for the its response (see [Command Requests/Callbacks](#subsec_sdi_command_requests_callbacks) for more details). Nested commands (during an active request) use another message ID than the active command, usually the message ID of each nested command is incremented by 1. It's also possible that a nested command sends an unidirectional command callback, which then get's the message ID of the nested command.
Example:
{% hint style="info" %}
As already mentioned, side commands don't support callbacks, requests and nested commands. The only exception is side command [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment), which uses [Intermediate Result Callback (99-01)](#subsubsec_sdi_intermediate_status_cb) to signal the payment lock was obtained successfully. Side commands are usually short-term in nature and directly replied with a final response. In addition, the cancellation of a side command is not supported and [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) referring a side command will be ignored.
{% endhint %}
**Payment notification callbacks**
Asynchronous [Payment Notification Callbacks (9E-XX)](#subsec_sdi_payment_notification_callbacks), which are always unidirectional without a callback response, do not belong to an active command and can be sent by SDI at any time. As for old protocol type B, with protocol type D these notifications are only issued to the main connection, which owns the payment lock. Payment notification callbacks always use the message ID of [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment). After releasing the payment lock with [Sys Abort (20-02)](#subsubsec_sdi_sys_abort), SDI no longer issues payment notification callbacks on this connection.
Example:
**Concurrency restrictions**
As already mentioned in previous section [Payment lock/unlock](#para_sdi_prod_d_callback_payment_lock_unlock), payment commands require the payment lock. Even a connection was successfully locked, payment commands do not support concurrency, therefore, a second payment command will be declined with final response `640A` (busy) as long as the previous payment command is active.
Example:
Side commands instead have concurrency support and can be sent by SDI clients at any time without requesting SDI for access. But please note that side commands might be processed delayed or even can be declined, if they use an exclusive resource, which needs its own access protection (independently from the payment lock). For instance, SDI server will delay a print command, if the printer device is already in use by another side command. The print command is processed, after the previous print job has been finished, otherwise this would lead to broken receipt contents. In addition, it won't be possible to start 2 PIN entries in parallel with 2 side commands [PED start PIN entry (22-03)](#subsubsec_sdi_ped_start_pin), since SDI server needs to access the PIN entry device. Only the first [PED start PIN entry (22-03)](#subsubsec_sdi_ped_start_pin) will start the PIN entry and block all PED commands on other connections. For more details about PIN entry with side commands and the related restrictions, please read chapter [PED start PIN entry (22-03)](#subsubsec_sdi_ped_start_pin) carefully.
Finally, an attached/enabled EPP will lead to additional concurrency restrictions for side commands, if they require remote processing or partial interaction with the EPP. The reason is recent SDI implementations do not support asynchronous execution of commands on EPP and a SDI Countertop is not able to forward it as EPP side command. This implies that some commands are always handled as synchronous payment command, if they require remote processing by the EPP. For instance, [PED start PIN entry (22-03)](#subsubsec_sdi_ped_start_pin) will lose side command support for the SDI Countertop, since EPP will be always responsible for PIN entry, after it was enabled with [Enable EPP (20-21)](#subsubsec_sdi_sys_enable_epp). In addition, command addressed to an EPP with TLV tag `DFA150` will also be considered as payment command, which requires the payment lock (see [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment)) and sequential synchronous processing.
#### Protocol Type K: Remote keyservice
Payment applications running on Android platform, e.g. on P630 (Neo), T650c (Trinity) or CM5, M440 and M424, have the requirement to establish secure TLS connections. For authentication of the terminal as a Verifone device, these applications wants to use the AuthEx key/certificate or another customer loaded RSA key/certificate. AuthEx comes along with default factory installation of warranty keys, whereas customer key/certificates must be injected with RKL (remote key loading) first. Both key/certificate variants are stored in security Vault area on Engage (e.g. CM5) or in a special security domain on Android, which is only allowed to be accessed by SDI server (e.g. K81 security processor on T650c). Android applications have no direct access to the corresponding security APIs, therefore, SDI server must provide a service to use the key/certificate remotely. For this use case a new remote keyservice with Protocol Type K (K = Keyservice) was introduced, which has the same message format as the known Protocol Type B, except the following layer differences:
* On Transport Layer the remote keyservice uses protocol identifier 'K' instead 'B' (see chapter [Transport Layer](#subsec_sdi_transport_layer))
* On Application Protocol Layer the remote keyservice uses P1\P2 for protocol compatibility reasons, but these fields are recently unused and ignored (see chapter [Application Protocol](#subsec_sdi_application_protocol)). Applications can just fill both fields with a dummy value (e.g. `00` `00`, see chapter [Remote Keyservice (72-XX)](#subsec_sdi_remote_keyservice)).
The remote keyservice runs concurrently to normal SDI server under the additional TCP port 12001 and it supports accepting side connections at any time.
{% hint style="info" %}
The remote keyservice only accepts messages of Protocol Type 'K', other messages having protocol type B or C are declined and still have to be sent to normal SDI interface available under main TCP port 12000 (see chapter [Getting Started](#sec_sdi_getting_started)).
{% endhint %}
In order to restrict access to the remote keyservice for the internal Android device, the keyservice listen port 12001 is always bound to a local network device having one of the follwing IP addresses:
* `127.0.0.1` (localhost) on Android-only devices, e.g. P630 (Neo) or T650c (Trinity)
* `192.0.2.6` (PPP network device) on hybrid OS devices like CM5, M440 or M424, where SDI Server runs on Engage side (IP address `192.168.50.2` for old OS versions is also supported).
The local network devices listed above can be considered as trusted, since device internal connections are accepted only. Remote connections outside from the device will be declined to avoid terminal key/certifcate being misused by undesired TCP clients. Hybrid OS devices use an internal PPP network `192.0.2.0`, where the Android device uses IP address `192.0.2.5` and the Engage device the IP address 192.0.2.6. Binding the keyservice port to `192.0.2.6` will restrict usage of SDI remote keyservice for Android only.
The remote keyservice with new Protocol type 'K' only supports a thin scope of SDI commands, which are descripted in chapter [Remote Keyservice (72-XX)](#subsec_sdi_remote_keyservice). New or existing TLS components in Verifone terminals most likely implemented with OpenSSL can use this minimal command set to invoke secure routines required for the TLS authentication with RSA.
{% hint style="info" %}
OpenSSL provides an engine concept, which allows to implement a SSL engine to invoke RSA private key operations in a secure way without the need to hold the private key in application context.
{% endhint %}
Such an OpenSSL engine using the SDI remote keyservice is already implemented by ADKIPC project with library `engine_keyservice_sdi.so`. The project provides an easy-to-use API for several terminal platforms. OpenSSL engine `engine_keyservice_sdi.so` comes along with the IPC distribution packages and is fully integrated in ADKIPC's TLS component ready for use. Of course, the provided SSL engine can also be integrated in already existing OpenSSL implementations. For more details please refer to documentation of the ADKIPC project.
{% hint style="info" %}
Payment applications running on Engage (not on Android) use `engine_keyservice.so`, which is a local keyservice library provided by OS. This engine provides direct access for OpenSSL to use keys/certificates in Vault, thus, these applications don't need to access to SDI remote keyservice.
{% endhint %}
### Application Protocol
The Application Layer is based on ISO 7816 or APDU. The command and response pairs have the following formats:
The structure of a SDI command is as follows:
* **CLA**: Class of command
* **INS**: Specific Instruction within command class
* **P1-P2**: See P1-P2 Coding (see [Coding of P1 and P2](#subsubsec_sdi_coding_p1_p2))
* **Data**: Command data (see [Data Coding](#subsubsec_sdi_data_coding))
A SDI response contains the following fields:
* **SW1**: Status word 1 (see [Status Word Coding](#subsubsec_sdi_status_word_coding))
* **SW2**: Status word 2 (see [Status Word Coding](#subsubsec_sdi_status_word_coding))
* **Data**: Response data (see [Data Coding](#subsubsec_sdi_data_coding))
The Application Protocol shall also have a callback flow required for EMV:
#### Coding of P1 and P2
The P1-P2 byte shall be used for either:
* **P1**: Secure channel control (appears as **SC** in this document)
* **P2**: Instruction qualifier
The coding shall be:
Example:
#### Data Coding
Three types of data encoding shall be used:
* **TLV**: Unless a DOL or COL the data shall be encoded using BER-TLV (ISO/IEC 8825). Both Primitive and Constructed TLVs shall be used. Constructed data shall be included in the **F0** Constructed Tag.
* **DOL**: The data defines a list of Tags and Lengths required. The response shall include only the data (only values, no Tag or Length). DOL requests data shall be included in the **F1** Constructed Tag and DOL responses in the **F2** Constructed Tag.
* **COL**: The data defines a list of Tags and Lengths required. The response shall be constructed using TLV. COL data shall be included in the **F3** Constructed Tag.
The Tags within a constructed tag may appear in any order and not always in the order defined in this document.
#### Status Word Coding
The following Status Words (SW1 / SW2) are defined:
| SW1 | SW2 | Comment |
| --- | --- | ---------------------------------------------------------------------------------------------------------------------- |
| 90 | 00 | All OK |
| 62 | 00 | Tag Error |
| 63 | 00 | Tag Length Error |
| 64 | 00 | Execution Error |
| 64 | 05 | Canceled by user |
| 64 | 0A | SDI-Server is busy (e.g. UI menu entered or another command blocks resource) |
| 64 | 0C | Timeout during Pin Entry |
| 64 | F4 | Result of Card Detection: ADK-EMV has detected no medium to perform a contactless payment |
| 64 | F5 | Already registered (returned for protocol type B/D, if another client already has registered for a resource) |
| 64 | F6 | MSR data not available Timeout reached (for UX devices only) |
| 64 | F7 | Card Removal Timeout reached (for UX devices only) |
| 64 | F8 | Interchar timeout during Pin Entry |
| 64 | F9 | Command not allowed |
| 64 | FA | Main connection already locked (returned for protocol type B/D, if another client owns the payment lock) |
| 64 | FB | Invalid File Content |
| 64 | FC | File Access Error |
| 64 | FD | Logic Error (e.g. wrong command order) |
| 64 | FE | Parameter Error |
| 64 | FF | Luhn check of the PAN failed |
| 65 | 00 | Execution Aborted |
| 66 | 00 | Execution Timeout |
| 67 | 00 | Message Length Error |
| 68 | 00 | No SDI Plugin available |
| 68 | 01 | Unknown plugin ID in the Instruction byte (INS) |
| 68 | 02 | Invalid or no result data returned by the plugin |
| 69 | 00 | EPP connection error |
| 6D | 00 | Unknown Instruction (INS) |
| 6E | 00 | Unknown Class (CLA) |
| 6F | B0 | CMAC Error |
| 6F | B1 | CMAC Length Error |
| 6F | B2 | CMAC Missing Error |
| 6F | B4 | Encryption Error |
| 6F | B5 | Encryption Length Error |
| 6F | B6 | Encryption Missing Error |
| 6F | B8 | Decryption Error |
| 6F | B9 | Decryption Length Error |
| 6F | BA | Decryption Missing Error |
| 6F | C0 | Excessive PIN Requests |
| 6F | D0 | Low Battery |
| 6F | E0 | No DUKPT Keys Loaded |
| 6F | F0 | Unit Tampered |
| 6F | F1 | Recovery Mode. SDI only allows [Check For Update (20-1D)](#para_sdi_sys_software_check_update) command. (Android only) |
| 90 | 70 | Input bypassed: PIN bypassed during PIN entry, or CVV bypassed during Manual Card Data Entry (21-02) |
| 90 | 71 | No match for card validation |
| 90 | XX | EMV error (for XX see ADK\_RET\_CODE) |
| 91 | 00 | Callback Request |
| 94 | 01 | Smart card removed = error caused by cardholder |
| 94 | 02 | Smart card error caused by terminal |
| 94 | 03 | Smart card error caused by ICC |
| 94 | 04 | CTLS: Two cards in the field (only in relation with smart card commands) |
| 94 | 05 | Smart card error caused for initialization |
| 94 | 06 | Smart card error caused passing invalid parameters |
| 94 | F3 | Error In TLV Data Object (only in relation with EMV commands) |
#### SDI access control
Old SDI versions were more or less permissive and all clients were allowed to send any command. But usage of security related resources or functions depended on the security-mode, which SDI was operating with:
* Trusted mode: Local applications connecting from the same device were considered as "trusted" and got full access on SDI interface without restrictions.
* Untrusted mode: Remote SDI clients connecting from the outside world were classified as potentially "untrusted", therefore, SDI operated in a restricted mode.
The following SDI commands and functionalities were affected by the untrusted/restricted mode:
* SDI configuration update required a MAC, see chapter [Software Upload Finalize (20-16)](#para_sdi_sys_software_upload_finalize). Prerequisite for using a MAC is system authentication with [Sys Auth (20-11)](#subsubsec_sdi_sys_auth). Optionally, untrusted applications could implement/install a SDI plugin with `SDITrigger_SDIConfig` to validate and update SDI configuration w/o MAC, see chapter [Internal plugin trigger functions](#subsubsec_sdi_plugin_trigger).
* EMV configuration update also required a MAC or optionally a SDI plugin with trigger `SDITrigger_EMVConfig`, see chapter [Internal plugin trigger functions](#subsubsec_sdi_plugin_trigger).
* By default, [Generic Crypto Interface (70-XX)](#subsec_sdi_generic_crypto_interface) was restricted in use.
* By default, SDI command [getMsgSignature (29-04)](#subsubsec_sdi_getmsgsignature) was blocked.
With introduction of ACL (access control list) configuration file [acl.json](#subsubsec_acl_json), the SDI access control is now configurable and can be better adjusted to projects requirements. The ACL file contains access rules, which allow to specify SDI command filters on application protocol level (see chapter [Application Protocol](#subsec_sdi_application_protocol)). These filters consists of a whitelist with class/instruction of allowed commands. Further, access rules can be defined for TCP/IP connections or for local applications (running on the same device as SDI). Finally, old security-mode "trusted"/"untrusted" is supported to align behaviour to old SDI versions. Backwards compatibility is guaranteed with a default ACL configuration file, which is installed with the SDI base package. Optionally, an user ACL configuration file can be installed with an user config package on top to extend/overload the defaults.
{% hint style="info" %}
A complete overview about SDI installation packages for the corresponding platform is provided by chapters [Software for VOS/VOS2 and VOS3](#subsec_sdi_vos_software) and [Software for Android](#subsec_sdi_android_software).
{% endhint %}
There are 2 different rule sections, which are used in an ACL file:
* Section `"system"`: List of rules for system services with highest priority. This section is always active and only supported by default ACL configuration file, thus, it will be ignored in user ACL configuration.
* Section `"clients"`: List of rules for user applications. This section is supported for both, in default and user ACL configuration file. A valid section section `"clients"` in user ACL file will disable the section in default ACL file and overlay it completely.
The matching rules for the files and its sections are implemented as follows:
1. Always the first match (from top to bottom) in a section takes precedence. Once a rules has matched, it is applied for the connection. Other rules of this section and in other ACL files are ignored.
2. Section `"system"` of default ACL files has highest priority and is looked up at first. If no system rule matches, sections `"clients"` are processed afterwards.
3. If an user ACL configuration file is installed and found, this file is preferred to the default ACL file. A valid section `"clients"` in user ACL file will disable the section in default ACL file and overlay it completelly.
4. Finally, SDI will use the section `"clients"` of the default ACL file, if no user ACL file is available.
Every command received by SDI during the session is validated against the command filters of the selected rule. If the command is not whitelisted, SDI declines it with response `64F9` (command not allowed).
TCP/IP connections are identified by its IP address. SDI detects the remote IP address of the client to match a rule with type `tcp`. For identification of local applications SDI has added support for Unix Domain Sockets, which allow to retrieve credentials of the connecting application. The SDI domain socket is available in the filesystem, its location depends on the used platfrom as follows:
* Fusion/Engage: `/tmp/share/sdi.uds`
* Android: `/dev/socket/sdi/sock.uds`
* VOS3: `/dev/socket/sdi.uds`
Applications connecting on the SDI domain socket either can be identified by user (rule type `user`) or by package name (rule type `package`). On Fusion/Engage and VOS3 the ACL file typically must implement rules of type `user`, since type `package` is not supported for this platform. On Android, the ACL file typically must implement rules of type `package`, since user name for applications are dynamically assigned by Android system and are not user-friendly.
JSON format and supported parameters as well as default ACL files for all platforms are fully described in chapter [acl.json](#subsubsec_acl_json).
{% hint style="info" %}
SDI access control is implemented for protocol type B and C with protocol library `lib_mADK_PP_Prot_ipc.so` only. This library is always used on Android, thus, SDI access control works out of the box on this platform. Engage/Fusion and VOS3 platforms use protocol library `lib_mADK_PP_Prot_com.so` by default, which provides no access control and no multi connection support (see chapter [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)). Finally, users can enable the `lib_mADK_PP_Prot_ipc.so` on Engage/Fusion/VOS3 with [COM\_IF.CFG](#sec_sdi_com_if_cfg) setting `multi_connect_support`, which also activates the SDI access control in the same way.
{% endhint %}
### SDI Command Overview
The table gives an overview about all supported SDI commands on the different platforms. The symbols in it have the following meaning: „●" = command is supported without any restrictions „○" = command is supported with restrictions, see subchapter for details „‒" = command is not supported
The column "EPP Support" indicates how the command will be processed in an EPP solution: „C" stands for card side, which means the command is processed on the device, where the card was swiped, inserted or tapped „M" stands for mirrow, which means the command is forwarded to the EPP automatically „T" stands for tag controlled, which means the command is processed on the countertop or EPP unit depending on tag DFA150
***
Cla/Ins Command VOS VOS2 VOS3 Trinity Neo VR1 EPP Remark Android SCR Support
***
20-00
\[Sync/Turn On (20-00)]\(#subsubsec\_sdi\_sync\_turn\_on)
●
●
●
●
●
●
‒
deprecated
20-01
\[Turn OFF (20-01)]\(#subsubsec\_sdi\_sync\_turn\_off)
●
●
●
●
●
●
‒
deprecated
20-02
\[Sys Abort (20-02)]\(#subsubsec\_sdi\_sys\_abort)
●
●
●
●
●
●
●
20-03
\[Sys Get Config (20-03)]\(#subsubsec\_sdi\_sys\_get\_config)
●
●
●
●
●
●
‒
deprecated, use \[Get Property (20-1A)]\(#subsubsec\_sdi\_sys\_get\_property)
20-04
\[Sys Get Status (20-04)]\(#subsubsec\_sdi\_sys\_get\_status)
●
●
●
●
●
●
‒
deprecated, use \[Get Property (20-1A)]\(#subsubsec\_sdi\_sys\_get\_property)
20-05
\[Sys Selftest (20-05)]\(#subsubsec\_sdi\_sys\_selftest)
●
●
●
●
●
●
●
deprecated
20-06
\[Sys Lock Payment (20-06)]\(#subsubsec\_sdi\_sys\_lock\_payment)
●
●
●
●
●
●
‒
20-07
\[Sys Reset Link (20-07)]\(#subsubsec\_sdi\_sys\_reset\_link)
●
●
●
●
●
●
‒
20-08
\[Sys Register Logging Callback (20-08)]\(#subsubsec\_sdi\_sys\_register\_log\_callback)
‒
‒
‒
‒
‒
●
‒
20-09
\[Sys Set Status (20-09)]\(#subsubsec\_sdi\_sys\_set\_status)
●
●
●
●
●
●
● M
deprecated, use \[Set Property (20-19)]\(#subsubsec\_sdi\_sys\_set\_property)
20-11
\[Sys Auth (20-11)]\(#subsubsec\_sdi\_sys\_auth)
●
●
‒
‒
‒
‒
‒
20-13
\[Set Idle Text (20-13)]\(#subsubsec\_sdi\_set\_idle\_text)
‒
●
●
‒
‒
‒
● T
20-14
\[Software Upload Start (20-14)]\(#para\_sdi\_sys\_software\_upload\_start)
●
●
●
●
●
●
● T
20-15
\[Software Upload Transfer (20-15)]\(#para\_sdi\_sys\_software\_upload\_transfer)
●
●
●
●
●
●
● T
20-16
\[Software Upload Finalize (20-16)]\(#para\_sdi\_sys\_software\_upload\_finalize)
●
●
●
●
●
●
● T
20-17
\[Shutdown/Reboot/Sleep (20-17)]\(#subsubsec\_sdi\_sys\_shutdown\_reboot\_sleep)
●
●
●
●
●
●
● T
20-18
\[Show MAC Desktop (20-18)]\(#subsubsec\_sdi\_sys\_show\_mac\_desktop)
●
●
●
‒
‒
‒
‒
20-19
\[Set Property (20-19)]\(#subsubsec\_sdi\_sys\_set\_property)
●
●
●
●
●
●
● T
20-1A
\[Get Property (20-1A)]\(#subsubsec\_sdi\_sys\_get\_property)
●
●
●
●
●
●
● T
20-1B
\[Install Sponsor Cert (20-1B)]\(#subsubsec\_sdi\_sys\_install\_sponsor\_cert)
‒
‒
‒
●
●
‒
‒
20-1C
\[Get SDI version info (20-1C)]\(#subsubsec\_sdi\_sys\_get\_version\_info)
●
●
●
●
●
●
● T
20-1D
\[Check For Update (20-1D)]\(#para\_sdi\_sys\_software\_check\_update)
‒
‒
‒
●
●
‒
‒
20-1E
\[Get last install error (20-1E)]\(#subsubsec\_sdi\_sys\_get\_last\_install\_error)
‒
●
‒
‒
‒
●
● T
20-20
\[External Button (20-20)]\(#subsubsec\_sdi\_sys\_external\_button)
‒
○
‒
●
●
‒
‒
20-21
\[Enable EPP (20-21)]\(#subsubsec\_sdi\_sys\_enable\_epp)
‒
●
●
●
●
‒
‒
20-22
\[Factory Reset (20-22)]\(#subsubsec\_sdi\_sys\_factory\_reset)
●
●
●
‒
‒
‒
● M
20-23
\[Read Keystore Certificate (20-23)]\(#subsubsec\_sdi\_sys\_read\_certificate)
●
●
●
●
●
●
‒
20-24
\[Force Currency Abbreviation (20-24)]\(#subsubsec\_sdi\_sys\_force\_currency\_abbreviation)
●
●
●
●
●
●
● M
relevant for standard mode only
20-25
\[Get Statistic Counters (20-25)]\(#subsubsec\_sdi\_sys\_get\_statistic\_counters)
\-
\-
●
\-
●
\-
●
21-01
\[MSR Read (21-01)]\(#subsubsec\_sdi\_msr\_read)
●
●
●
●
●
●
● M
21-02
\[MSR Card Data Entry (21-02)]\(#subsubsec\_sdi\_msr\_card\_data\_entry)
‒
●
●
●
●
‒
‒
21-03
\[MSR Set Options (21-03)]\(#subsubsec\_sdi\_msr\_set\_options)
●
●
●
●
●
●
● T
21-04
\[MSR Switch LEDs (21-04)]\(#subsubsec\_sdi\_msr\_switch\_leds)
●
●
●
●
●
●
● T
21-05
\[MSR Set Sensitivity (21-05)]\(#subsubsec\_sdi\_msr\_set\_sensitivity)
‒
‒
●
●
●
‒
● T
22-01
\[PED Get PIN (22-01)]\(#subsubsec\_sdi\_ped\_get\_pin)
‒
●
●
●
●
‒
●
22-02
\[PED Set PIN Timeout (22-02)]\(#subsubsec\_sdi\_ped\_set\_pin\_timeout)
‒
●
●
●
●
‒
● M
22-03
\[PED start PIN entry (22-03)]\(#subsubsec\_sdi\_ped\_start\_pin)
‒
●
●
●
●
‒
●
22-04
\[PED poll PIN entry (22-04)]\(#subsubsec\_sdi\_ped\_poll\_pin)
‒
●
●
●
●
‒
●
22-05
\[PED stop PIN entry (22-05)]\(#subsubsec\_sdi\_ped\_stop\_pin)
‒
●
●
●
●
‒
●
22-06
\[PED Set PIN Input Parameter (22-06)]\(#subsubsec\_sdi\_ped\_set\_pin\_input\_parameter)
‒
●
●
●
●
‒
● T
23-01
\[Card Detection (23-01)]\(#subsubsec\_sdi\_card\_detection)
●
●
●
●
●
●
● M
23-02
\[Wait Card Removal (23-02)]\(#subsubsec\_sdi\_wait\_card\_removal)
●
●
●
●
●
●
● C
23-03
\[Start Card Detection (23-03)]\(#subsubsec\_sdi\_start\_card\_detection)
●
●
●
●
●
●
● M
23-04
\[Poll Card Detection (23-04)]\(#subsubsec\_sdi\_poll\_card\_detection)
●
●
●
●
●
●
● M
23-05
\[Stop Card Detection (23-05)]\(#subsubsec\_sdi\_stop\_card\_detection)
●
●
●
●
●
●
● M
23-06
\[Add Technology (23-06)]\(#subsubsec\_sdi\_add\_technology)
●
●
●
●
●
●
● M
23-07
\[Remove Technology (23-07)]\(#subsubsec\_sdi\_remove\_technology)
●
●
●
●
●
●
● M
23-08
\[Provide Callback Response (23-08)]\(#subsubsec\_sdi\_provide\_callback\_response)
●
●
●
●
●
●
●
24-01
\[Display Text (24-01)]\(#subsubsec\_sdi\_display\_text)
‒
○
○
‒
‒
‒
‒
deprecated, use \[Handle Display (24-03)]\(#subsubsec\_sdi\_handle\_display)
24-02
\[Display Text with Confirmation (24-02)]\(#subsubsec\_sdi\_display\_text\_with\_confirmation)
‒
○
○
‒
‒
‒
‒
deprecated, use \[Handle Display (24-03)]\(#subsubsec\_sdi\_handle\_display)
24-03
\[Handle Display (24-03)]\(#subsubsec\_sdi\_handle\_display)
‒
○
○
‒
‒
‒
● T
24-04
\[Handle Secure Input (24-04)]\(#subsubsec\_sdi\_handle\_secure\_input)
‒
○
○
‒
‒
‒
● T
24-05
\[Handle Menu (24-05)]\(#subsubsec\_sdi\_handle\_menu)
‒
○
○
‒
‒
‒
● T
24-06
\[Handle Card Request Display (24-06)]\(#subsubsec\_sdi\_handle\_card\_request\_display)
‒
○
○
‒
‒
‒
● T
24-07
\[Display Idle Screen (24-07)]\(#subsubsec\_sdi\_display\_idle\_screen)
‒
○
○
‒
‒
‒
● T
24-08
\[Handle Signature Capture (24-08)]\(#subsubsec\_sdi\_handle\_signature\_capture)
‒
○
○
‒
‒
‒
●
24-09
\[Activate LEDs (24-09)]\(#subsubsec\_sdi\_activate\_leds)
‒
○
○
‒
‒
‒
●
24-0A
\[Handle HTML Dialog (24-0A)]\(#subsubsec\_sdi\_handle\_html\_dialog)
‒
○
○
‒
‒
‒
● T
24-0B
\[Get Async Display Result (24-0B)]\(#subsubsec\_sdi\_get\_async\_display\_result)
‒
○
○
‒
‒
‒
● T
25-00
\[Set Printer Property (25-00)]\(#subsubsec\_sdi\_prt\_set\_property)
‒
○
○
○
○
‒
‒
25-01
\[Get Printer Property (25-01)]\(#subsubsec\_sdi\_prt\_get\_property)
‒
○
○
○
○
‒
‒
25-02
\[Print HTML (25-02)]\(#subsubsec\_sdi\_prt\_html)
‒
○
○
○
○
‒
‒
UX302: 6400 after 10 seconds
25-04
\[Print BITMAP (25-04)]\(#subsubsec\_sdi\_prt\_bitmap)
‒
○
○
○
○
‒
‒
28-00
\[VCL Registart SRED Request (28-00)]\(#subsubsec\_sdi\_vcl\_registart\_sred\_request)
○
○
○
○
○
‒
‒
28-01
\[VCL Status Request (28-01)]\(#subsubsec\_sdi\_vcl\_status\_request)
○
○
○
○
○
‒
‒
28-02
\[VCL Advance DDK (28-02)]\(#subsubsec\_sdi\_vcl\_advance\_ddk)
○
○
○
○
○
‒
‒
28-03
\[VCL Request eParms (28-03)]\(#subsubsec\_sdi\_vcl\_eparms\_request)
○
○
○
○
○
‒
‒
28-06
\[VCL Request Diag Query (28-06)]\(#subsubsec\_sdi\_vcl\_diag\_query)
○
○
○
○
○
‒
‒
28-07
\[VCL Request Derive Query (28-07)]\(#subsubsec\_sdi\_vcl\_derive\_query)
○
○
○
○
○
‒
‒
28-08
\[VCL Override Message Query (28-08)]\(#subsubsec\_sdi\_vcl\_override\_message\_query)
○
○
○
○
○
‒
‒
28-09
\[VCL KSN Request (28-09)]\(#subsubsec\_sdi\_vcl\_ksn\_request)
○
○
○
○
○
‒
‒
28-0A
\[VCL kmailin Request (28-0A)]\(#subsubsec\_sdi\_vcl\_kmailin\_request)
○
○
○
○
○
‒
‒
29-00
\[getEncData (29-00)]\(#subsubsec\_sdi\_getencdata)
●
●
●
●
●
●
‒
29-01
\[getEncMsgData (29-01)]\(#subsubsec\_sdi\_getencmsgdata)
●
●
●
●
●
●
‒
29-02
\[fetchTrxTags (29-02)]\(#subsubsec\_sdi\_fetchtrxtags)
●
●
●
●
●
●
‒
29-03
\[clearDataStore (29-03)]\(#subsubsec\_sdi\_cleardatastore)
●
●
●
●
●
●
‒
29-04
\[getMsgSignature (29-04)]\(#subsubsec\_sdi\_getmsgsignature)
●
●
●
●
●
●
‒
29-05
\[performValidationChecks (29-05)]\(#subsubsec\_sdi\_performvalidationchecks)
●
●
●
●
●
‒
‒
29-06
\[getValidationInfo (29-06)]\(#subsubsec\_sdi\_getvalidationinfo)
●
●
●
●
●
‒
‒
29-07
\[getEncTrxData (29-07)]\(#subsubsec\_sdi\_getenctrxdata)
●
●
●
●
●
‒
‒
29-08
\[setEncTrxData (29-08)]\(#subsubsec\_sdi\_setenctrxdata)
●
●
●
●
●
‒
‒
29-09
\[endEncTrxData (29-09)]\(#subsubsec\_sdi\_endenctrxdata)
●
●
●
●
●
‒
‒
29-0A
\[getEmvInfo (29-0A)]\(#subsubsec\_sdi\_getemvinfo)
●
●
●
●
●
●
‒
31-10
\[NFC Client Init (31-10)]\(#subsubsec\_sdi\_nfc\_client\_init)
●
●
●
●
●
‒
● M
31-11
\[NFC Get Version (31-11)]\(#subsubsec\_sdi\_nfc\_get\_version)
●
●
●
●
●
‒
● T
31-00
\[NFC Ping (31-00)]\(#subsubsec\_sdi\_nfc\_ping)
●
●
●
●
●
‒
●
31-01
\[NFC Pass Through Open (31-01)]\(#subsubsec\_sdi\_nfc\_pt\_open)
●
●
●
●
●
‒
●
31-02
\[NFC Pass Through Close (31-02)]\(#subsubsec\_sdi\_nfc\_pt\_close)
●
●
●
●
●
‒
●
31-03
\[NFC Pass Through Field On (31-03)]\(#subsubsec\_sdi\_nfc\_pt\_field\_on)
●
●
●
●
●
‒
●
31-04
\[NFC Pass Through Field Off (31-04)]\(#subsubsec\_sdi\_nfc\_pt\_field\_off)
●
●
●
●
●
‒
●
31-05
\[NFC Pass Through Field Polling (31-05)]\(#subsubsec\_sdi\_nfc\_pt\_field\_polling)
●
●
●
●
●
‒
●
31-07
\[NFC Pass Through Card Activation (31-07)]\(#subsubsec\_sdi\_nfc\_pt\_card\_activation)
●
●
●
●
●
‒
●
31-09
\[NFC Pass Through Ftech Baud (31-09)]\(#subsubsec\_sdi\_nfc\_pt\_field\_ftech\_baud)
●
●
●
●
●
‒
●
31-13
\[NFC Pass Through Field Polling Full (31-13)]\(#subsubsec\_sdi\_nfc\_pt\_field\_polling\_full)
●
●
●
●
●
‒
●
31-0A
\[NFC Mifare Authenticate (31-0A)]\(#subsubsec\_sdi\_nfc\_mifare\_authenticate)
●
●
●
●
●
‒
●
31-0B
\[NFC Mifare Read (31-0B)]\(#subsubsec\_sdi\_nfc\_mifare\_read)
●
●
●
●
●
‒
●
31-0C
\[NFC Mifare Write (31-0C)]\(#subsubsec\_sdi\_nfc\_mifare\_write)
●
●
●
●
●
‒
●
31-0D
\[NFC Mifare Increment (31-0D)]\(#subsubsec\_sdi\_nfc\_mifare\_increment)
●
●
●
●
●
‒
●
31-0E
\[NFC Mifare Decrement (31-0E)]\(#subsubsec\_sdi\_nfc\_mifare\_decrement)
●
●
●
●
●
‒
●
31-15
\[NFC Mifare Increment Only (31-15)]\(#subsubsec\_sdi\_nfc\_mifare\_increment\_only)
●
●
●
●
●
‒
‒
31-16
\[NFC Mifare Decrement Only (31-16)]\(#subsubsec\_sdi\_nfc\_mifare\_decrement\_only)
●
●
●
●
●
‒
‒
31-17
\[NFC Mifare Transfer (31-17)]\(#subsubsec\_sdi\_nfc\_mifare\_transfer)
●
●
●
●
●
‒
‒
31-18
\[NFC Mifare Restore (31-18)]\(#subsubsec\_sdi\_nfc\_mifare\_restore)
●
●
●
●
●
‒
‒
31-0F
\[NFC Felica Exchange (31-0F)]\(#subsubsec\_sdi\_nfc\_felica\_exchange)
●
●
●
●
●
‒
●
31-14
\[NFC Felica Polling (31-14)]\(#subsubsec\_sdi\_nfc\_felica\_polling)
●
●
●
●
●
‒
●
31-1C
\[NFC APDU Exchange (31-1C)]\(#subsubsec\_sdi\_nfc\_apdu\_exchange)
●
●
●
●
●
‒
●
31-1D
\[NFC Pass Through Field Polling ABF (31-1D)]\(#subsubsec\_sdi\_nfc\_pt\_field\_polling\_abf)
●
●
●
●
●
‒
●
31-1E
\[NFC Pass Through Advanced TxRx (31-1E)]\(#subsubsec\_sdi\_nfc\_pt\_adv\_txrx)
●
●
●
●
●
‒
●
31-20
\[NFC Target Action (31-20)]\(#subsubsec\_sdi\_nfc\_target\_action)
●
●
●
●
●
‒
●
31-21
\[NFC Create Ndef (31-21)]\(#subsubsec\_sdi\_nfc\_create\_ndef)
●
●
●
●
●
‒
●
32-00
\[VAS Terminal Config (32-00)]\(#subsubsec\_sdi\_vas\_terminal\_config)
●
●
●
●
●
‒
● M
32-01
\[VAS Terminal Read Config (32-01)]\(#subsubsec\_sdi\_vas\_terminal\_read\_config)
●
●
●
●
●
‒
● T
32-02
\[VAS Read Config (32-02)]\(#subsubsec\_sdi\_vas\_read\_config)
●
●
●
●
●
‒
● T
32-03
\[VAS Activate (32-03)]\(#subsubsec\_sdi\_vas\_activate)
●
●
●
●
●
‒
●
32-05
\[VAS Update Config (32-05)]\(#subsubsec\_sdi\_vas\_update\_config)
●
●
●
●
●
‒
● M
32-06
\[VAS Cancel Config (32-06)]\(#subsubsec\_sdi\_vas\_cancel\_config)
●
●
●
●
●
‒
● M
32-07
\[VAS Preload (32-07)]\(#subsubsec\_sdi\_vas\_preload)
●
●
●
●
●
‒
● M
32-08
\[VAS Cancel Preload (32-08)]\(#subsubsec\_sdi\_vas\_cancel\_preload)
●
●
●
●
●
‒
● M
32-09
\[VAS Decrypt (32-09)]\(#subsubsec\_sdi\_vas\_decrypt)
●
●
●
●
●
‒
‒
39-00
[EMV\_CT\_Init\_Framework()](/s-adk-5.1-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)
●
●
●
●
●
●
● M
39-01
[EMV\_CT\_SetTermData()](/s-adk-5.1-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()](/s-adk-5.1-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)
●
●
●
●
●
●
● M
39-02
[EMV\_CT\_SetAppliData()](/s-adk-5.1-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()](/s-adk-5.1-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)
●
●
●
●
●
●
● M
39-03
[EMV\_CT\_StoreCAPKey()](/s-adk-5.1-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()](/s-adk-5.1-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)
●
●
●
●
●
●
● M
39-04
[EMV\_CT\_ApplyConfiguration()](/s-adk-5.1-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)
●
●
●
●
●
●
● M
39-06
[EMV\_CT\_MapVirtualTerminal()](/s-adk-5.1-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)
●
●
●
●
●
●
● M
39-10
[EMV\_CT\_StartTransaction()](/s-adk-5.1-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)
●
●
●
●
●
●
● C
39-11
[EMV\_CT\_ContinueOffline()](/s-adk-5.1-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)
●
●
●
●
●
●
● C
39-12
[EMV\_CT\_ContinueOnline()](/s-adk-5.1-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)
●
●
●
●
●
●
● C
39-13
[EMV\_CT\_updateTxnTags()](/s-adk-5.1-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)
●
●
●
●
●
●
● C
39-15
[EMV\_CT\_EndTransaction()](/s-adk-5.1-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#gaec319989542c7681715566de387d7f69)
●
●
●
●
●
●
● C
39-16
[EMV\_CT\_GetCandidateData()](/s-adk-5.1-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#gac8f6430c652d6dad621ca3c0cf367346)
●
●
●
●
●
●
● C
39-17
[EMV\_CT\_CheckSupportedAID()](/s-adk-5.1-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#gad55c11dd44dbba66d6fefeb48b01a9e4)
●
●
●
●
●
●
● C
41-01
\[Smart Card Detect (41-01)]\(#subsubsec\_sdi\_smart\_card\_detect)
●
●
●
●
●
●
● M
41-02
\[Smart Card Activate (41/42-02)]\(#subsubsec\_sdi\_smart\_card\_activate)
●
●
●
●
●
●
● C
41-03
\[Smart Card Exchange APDU (41/42-03)]\(#subsubsec\_sdi\_smart\_card\_exchange\_apdu)
○
○
○
○
○
○
● C
41-04
\[Smart Card Deactivate (41/42-04)]\(#subsubsec\_sdi\_smart\_card\_deactivate)
●
●
●
●
●
●
● C
41-05
[EMV\_CT\_Send\_PIN\_Offline()](/s-adk-5.1-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)
●
●
●
●
●
‒
● C
41-09
[EMV\_CT\_LED()](/s-adk-5.1-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#gaa7a875eed1a49cff8fdf70c81100be2f)
●
●
●
●
●
●
● T
40-00
[EMV\_CTLS\_Init\_Framework()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t_l_s/group___f_u_n_c___i_n_i_t___c_t_l_s.md#ga63240773908b46180eeec866ef33f93f)\
[EMV\_CTLS\_Exit\_Framework()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___i_n_i_t_i_a_l_i_z_a_t_i_o_n___c_t_l_s/group___f_u_n_c___i_n_i_t___c_t_l_s.md#gafe86c6980355b69b6a650af0bffcb7ed)
●
●
●
●
●
●
● M
40-01
[EMV\_CTLS\_SetTermData()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t_l_s/group___f_u_n_c___c_o_n_f___c_t_l_s.md#gac5ce9781bba083028538f9e77c2d58f3)\
[EMV\_CTLS\_GetTermData()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t_l_s/group___f_u_n_c___c_o_n_f___c_t_l_s.md#gad690d9dec1818d4ffc7db35c12c3b610)
●
●
●
●
●
●
● M
40-02
[EMV\_CTLS\_SetAppliDataSchemeSpecific()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t_l_s/group___f_u_n_c___c_o_n_f___c_t_l_s.md#gadc7f2eba5fd3e941d0ddb65a936a0776)\
[EMV\_CTLS\_GetAppliDataSchemeSpecific()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t_l_s/group___f_u_n_c___c_o_n_f___c_t_l_s.md#gae76efd9464ef90029a0dddb8d845d4d8)
●
●
●
●
●
●
● M
40-03
[EMV\_CTLS\_StoreCAPKey()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t_l_s/group___f_u_n_c___c_o_n_f___c_t_l_s.md#ga3e03f6dd283e873cbcd6b8e4bb78f09a)\
[EMV\_CTLS\_ReadCAPKeys()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t_l_s/group___f_u_n_c___c_o_n_f___c_t_l_s.md#gacaf6e34b74f3c446ca7f877223cf4724)
●
●
●
●
●
●
● M
40-04
[EMV\_CTLS\_ApplyConfiguration()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t_l_s/group___f_u_n_c___c_o_n_f___c_t_l_s.md#gaa5352e4331b8fd16eaa02b1bbb7027c2)
●
●
●
●
●
●
● M
40-06
[EMV\_CTLS\_MapVirtualTerminal()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___c_o_n_f_i_g_u_r_a_t_i_o_n___c_t_l_s/group___f_u_n_c___c_o_n_f___c_t_l_s.md#ga6fbd51a31dd89f11d137adab3ed4d733)
●
●
●
●
●
●
● M
40-10
[EMV\_CTLS\_SetupTransaction()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t_l_s/group___f_u_n_c___f_l_o_w___c_t_l_s.md#ga1a86c76dcf8fec6e97ead6cf8f2717ff)
●
●
●
●
●
●
●
40-11
[EMV\_CTLS\_ContinueOffline()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t_l_s/group___f_u_n_c___f_l_o_w___c_t_l_s.md#gaf23f6f87fe90619810470fad7d11f321)
●
●
●
●
●
●
●
40-12
[EMV\_CTLS\_ContinueOnline()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t_l_s/group___f_u_n_c___f_l_o_w___c_t_l_s.md#ga297b6843994afaa2e7a6f5e0e4a8af3e)
●
●
●
●
●
●
●
40-15
[EMV\_CTLS\_EndTransaction()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t_l_s/group___f_u_n_c___f_l_o_w___c_t_l_s.md#gaa7aed3c7f0c3ac0f26cc46efff422dd9)
●
●
●
●
●
●
●
40-16
[EMV\_CTLS\_GetCandidateData()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t_l_s/group___f_u_n_c___f_l_o_w___c_t_l_s.md#gab1600b67271771658ce682b9cfeb660e)
●
●
●
●
●
●
●
40-20
[EMV\_CTLS\_Break()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t_l_s/group___f_u_n_c___f_l_o_w___c_t_l_s.md#ga2b4820be53959b56fb7f672bd54f4e63)
●
●
●
●
●
●
●
42-02
\[Smart Card Activate (41/42-02)]\(#subsubsec\_sdi\_smart\_card\_activate)
●
●
●
●
●
●
●
42-03
\[Smart Card Exchange APDU (41/42-03)]\(#subsubsec\_sdi\_smart\_card\_exchange\_apdu)
○
○
○
○
○
○
●
42-04
\[Smart Card Deactivate (41/42-04)]\(#subsubsec\_sdi\_smart\_card\_deactivate)
●
●
●
●
●
●
●
43-03
[EMV\_CTLS\_LED()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___l_e_d.md#gabd80a7d1c3dbc5604604b02c20620f51)
‒
‒
‒
‒
‒
‒
●
43-04
[EMV\_CTLS\_LED\_SetMode()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___l_e_d.md#ga62eb0e6232dad59e94b75205493fa06d)
‒
‒
‒
‒
‒
‒
●
43-05
[EMV\_CTLS\_LED\_ConfigDesign()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___l_e_d.md#gaabbf98fcb94592b96bee2c680bfccee9)\
[EMV\_CTLS\_LED\_ConfigDesign\_Extended()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___l_e_d.md#ga8b647b4c8f995795b250bd2df10c2796)
‒
‒
‒
‒
‒
‒
‒
70-00
\[Crypto Open (70-00)]\(#subsubsec\_sdi\_crypto\_open)
●
●
●
●
●
●
‒
70-01
\[Crypto Close (70-01)]\(#subsubsec\_sdi\_crypto\_close)
●
●
●
●
●
●
‒
70-02
\[Crypto Encrypt (70-02)]\(#subsubsec\_sdi\_crypto\_encrypt)
●
●
●
●
●
●
‒
70-03
\[Crypto Decrypt (70-03)]\(#subsubsec\_sdi\_crypto\_decrypt)
●
●
●
●
●
●
‒
70-04
\[Crypto Sign (70-04)]\(#subsubsec\_sdi\_crypto\_sign)
●
●
●
●
●
●
‒
70-05
\[Crypto Verify (70-05)]\(#subsubsec\_sdi\_crypto\_verify)
●
●
●
●
●
●
‒
70-06
\[Crypto Updatekey (70-06)]\(#subsubsec\_sdi\_crypto\_updatekey)
●
●
●
●
●
●
‒
70-07
\[Crypto Set Key Set (70-07)]\(#subsubsec\_sdi\_crypto\_setkeyset)
●
●
●
●
●
●
‒
70-08
\[Crypto Get encrypted Pin (70-08)]\(#subsubsec\_sdi\_crypto\_getencryptedpin)
●
●
●
●
●
‒
‒
70-09
\[Crypto Get Key Inventory (70-09)]\(#subsubsec\_sdi\_crypto\_getkeyinventory)
●
●
●
●
●
●
‒
70-0A
\[Crypto Get Key Data (70-0A)]\(#subsubsec\_sdi\_crypto\_getkeydata)
●
●
●
●
●
●
‒
70-0B
\[Crypto Get Status (70-0B)]\(#subsubsec\_sdi\_crypto\_getstatus)
●
●
●
●
●
●
‒
70-0C
\[Crypto Get Versions (70-0C)]\(#subsubsec\_sdi\_crypto\_getversions)
●
●
●
●
●
●
‒
72-00
\[Read Certificate (72-00)]\(#subsubsec\_sdi\_keyservice\_read\_certificate)
‒
‒
‒
●
●
‒
‒
72-01
\[RSA Private Key Calculate (72-01)]\(#subsubsec\_sdi\_keyservice\_rsa\_pk\_calculate)
‒
‒
‒
●
●
‒
‒
\----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### System Interface (20-XX)
#### System Tags
The following tags shall be used with the System CLA (20):
***
Name Tag Min Max Get Config Get Status Set Status Len Len (20 03) (20 04) (20 09)
***
TLV Constructor
F0
00
●
●
●
DOL Constructor
F1
00
●
●
DOL Data
F2
00
●
●
COL Constructor
F3
00
●
●
CPU Unique ID
C0
14
FF
●
Serial Number
C1
0C
0C
●
Boot Software ID
C2
24
24
●
Application Software ID
C3
24
24
●
Hardware ID
C4
04
20
●
IFM ID
C5
10
10
●
EMV L2 ID
C6
08
80
●
Sys Time Date YYYYMMDDhhmmss
D0
07
07
●
●
Tamper Status
D2
09
09
●
Battery Charge + Charging Status
D4
02
02
●
Battery Voltage (Main, Coin)
D5
04
04
●
Language ID
D6
01
01
●
●
Card Entry Value Deactivation
D7
01
01
●
●
Card Entry Mode
D8
01
01
●
●
\--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
{% hint style="info" %}
\[unsupported block]
{% endhint %}
The Card Entry Value Deactivation is used to skip the entry of parameters during the input of the manual card data. In default all parameters have to be entered. They can be deactivated by setting the D7-Tag according the following table:
| b8 | b7 | b6 | b5 | b4 | b3 | b2 | b1 | Meaning |
| --- | --- | --- | --- | --- | --- | -- | -- | ---------------------------------------------------------------------------- |
| RFU | RFU | RFU | RFU | RFU | RFU | 0 | 1 | Skip Card Verification Code Entry |
| RFU | RFU | RFU | RFU | RFU | RFU | 1 | 0 | Skip Expiry Date **and** Card Verification Code Entry |
| RFU | RFU | RFU | RFU | RFU | 1 | 0 | 0 | Enter CVV without any other values (a magnetic card needs to be read before) |
The Card Entry Mode is used to choose between performing the manual card data entry in one screen or in separate screens. In default the entry is performed in one screen. To perform it in separate screens the D8-Tag has to be set to 01. Setting the D8-Tag to 00 will set the manual card data entry mode to one screen.
#### Sync/Turn On (20-00)
The Sync/Turn On command informs about the maximum message size for the data exchange between the Host device and the SDI Server.
{% hint style="info" %}
**This command is deprecated and should not be sent to the device for new implementations! All message sizes are as described in** [**Transport Layer**](#subsec_sdi_transport_layer) In case of response code '64 00' additional tag DFA000 may include detailed information about the error reason.
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ---- |
| 20 | 00 | 00 | 00 | None |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------------- | ------- |
| 90 | 00 | Max. message size | All OK |
The figure below demonstrates the Protocol Link Setup in detail:
{% hint style="info" %}
The 1st byte includes the length of the response data. Max. message size is valid for both directions (command and response messages)
{% endhint %}
Example:
```cpp
// Command to turn on PINpad
20 00 00 00
// Response
90 00 02 10 00
```
#### Turn OFF (20-01)
This command returns to the idle screen. The power management is done according to the device configuration.
{% hint style="info" %}
**This command is deprecated and should not be sent to the device for new implementations!**
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ---- |
| 20 | 01 | 00 | 00 | None |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------- |
| 90 | 00 | None | All OK |
#### Sys Abort (20-02)
This command forces the abort of the following commands in progress:
* [MSR Read (21-01)](#subsubsec_sdi_msr_read)
* [MSR Card Data Entry (21-02)](#subsubsec_sdi_msr_card_data_entry)
* [Card Detection (23-01)](#subsubsec_sdi_card_detection)
* [Display Text with Confirmation (24-02)](#subsubsec_sdi_display_text_with_confirmation)
* [Handle Display (24-03)](#subsubsec_sdi_handle_display) (synchronous with timeout)
* [Handle Secure Input (24-04)](#subsubsec_sdi_handle_secure_input)
* [Handle Menu (24-05)](#subsubsec_sdi_handle_menu)
* [Handle Signature Capture (24-08)](#subsubsec_sdi_handle_signature_capture)
* [Handle HTML Dialog (24-0A)](#subsubsec_sdi_handle_html_dialog)
* [Smart Card Detect (41-01)](#subsubsec_sdi_smart_card_detect)
* [PED Get PIN (22-01)](#subsubsec_sdi_ped_get_pin)
* [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment) (protocol type D only)
* [Sys Register Logging Callback (20-08)](#subsubsec_sdi_sys_register_log_callback) (protocol type D only)
{% hint style="info" %}
There is no guarantee that the active command is always cancelled. Only a small set of commands (see list above) are cancelable at all and it might depend on command progress or user interaction, if it will be considered. In addition, SDI will just ignore it beyond the point of no return.
{% endhint %}
Please be aware of different response behaviour when using different protocol types:
* Protocol type D: Sys Abort (20-02) is always unidirectional and SDI never provides a command response for it. Thus, command field P2 (see below) to control behaviour for command response is always ignored. Command Sys Abort (20-02) uses the message ID of the active command, which shall be cancelled. Finally, command Sys Abort (20-02) with a message ID referring an inctive command is ignored without command response, the same is with Sys Abort (20-02) referring a side command. Sys Abort (20-02) takes a special role to cancel an active command [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment) to release the payment lock (see chapter [Payment lock/unlock](#para_sdi_prod_d_callback_payment_lock_unlock) for more details). In addition, Sys Abort (20-02) is used to unregister the Logging Callback on Titus (see chapter [Sys Register Logging Callback (20-08)](#subsubsec_sdi_sys_register_log_callback) for more details).
* Protocol type B: If Sys Abort (20-02) is received during an active command, SDI does not provide a command response for it. If the command was successfully cancelled, a command response with error code `6500` (execution aborted) is for the command returned. During SDI is idle (no command active), by default a Sys Abort (20-02) will provide a command response with the same error code. For this case, SDI client might use command field P2 (bitmask) with bit 0x01 to control response behaviour. With enhancements for protocol type D, the P2 bit 0x02 was added, to allow a SDI client owning the payment lock to release it, which means that SDI client from another connection can send a type B command to reserve the main connection. Thus, a SDI client, which holds the payment lock, no longer requires to close the main connection. Finally, the P2 bit 0x04 was added to unregister the Logging Callback and to keep the payment lock in the same way.
* Protocol type C: The command is always returns with a command response with error code '64F9' (command not allowed).
* Protocol type A: Same as for protocol type B, even P2 bit 0x02 is ignored, since A does not support side connections.
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ---------------------------- |
| 20 | 02 | 00 | XX | None | for XX see description below |
Meaning of P2 command field (bitmask, for protocol type A/B only):
* `00`: Send a response, if no command is active (default)
* `01`: Suppress response, if no command is active
* `02`: Release payment lock (ignored if not main connection). This automatically includes bit `04` (see below), since Logging Callback requires the main connection.
* `04`: Unregister Logging Callback (ignored if not registered for this connection). In difference to bit `02` (see above), this bit keeps the payment lock.
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ----------------- |
| 65 | 00 | None | Execution Aborted |
{% hint style="info" %}
With a two piece solution command Sys Abort (20-02) will be forwarded from Countertop to EPP automatically.
{% endhint %}
#### Sys Get Config (20-03)
Get the requested parameters of the device configuration in DOL or COL format (see [System Tags](#subsubsec_sdi_system_tags))
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)).
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------------------- |
| 20 | 03 | SC | 00 | Tag, DOL or COL request |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ---------------- |
| 90 | 00 | Constructed | All OK |
| 62 | 00 | None | Tag Error |
| 63 | 00 | None | Tag Length Error |
| 64 | 00 | None | Execution Error |
The following system tags are returned with default values:
* CPU Unique Id (C0) is returned as 20 times 30
* HW Id (C4) returns the Hardware Id
* IFM Id (C5) is returned as 16 times 00
* EMV L2 (C6) id returns up to 128 bytes, depending on the requested number of bytes.
Example using DOL:
```cpp
// Command to get the device serial number
20 03 00 00 F1 02 C1 0C
// Response to DOL
90 00 F2 0C 31 32 33 34 35 36 37 38 39 3A 3B 3C
```
Example using COL:
```cpp
// Command to get the device serial number
20 03 00 00 F3 02 C1 0C
// Response to COL
90 00 F0 0E C1 0C 31 32 33 34 35 36 37 38 39 3A 3B 3C
```
{% hint style="info" %}
This command is not supported on EPP.
{% endhint %}
#### Sys Get Status (20-04)
Get device status information from the PINPad (see [System Tags](#subsubsec_sdi_system_tags))
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------------------- |
| 20 | 04 | SC | 00 | Tag, DOL or COL request |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ---------------- |
| 90 | 00 | Constructed | All OK |
| 62 | 00 | None | Tag Error |
| 63 | 00 | None | Tag Length Error |
| 64 | 00 | None | Execution Error |
Example using DOL:
```cpp
// Command to get the device time and date
20 04 00 00 F1 02 D0 07
// Response to DOL
90 00 F2 07 14 0D 02 16 0C 00 00
```
Example using COL:
```cpp
// Command to get the device time and date
20 04 00 00 F3 02 D0 07
// Response to COL
90 00 F0 09 D0 07 14 0D 02 16 0C 00 00
```
{% hint style="info" %}
This command is not supported on EPP.
{% endhint %}
#### Sys Selftest (20-05)
Performs a selftest on the PINPad and returns the result.
{% hint style="info" %}
**This command is deprecated and should not be sent to the device for new implementations!**
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ---- |
| 20 | 05 | 00 | 00 | None |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------- |
| 90 | 00 | None | All OK |
#### Sys Lock Payment (20-06)
Obtains the payment lock, which is applied to connection of the sending SDI client. After the lock was obtained successfully, the related SDI client has access to the full SDI function scope and can use the complete SDI interface including payment commands. SDI payment commands usually use resources or internal APIs, which disallow concurrent usage or invocation, e.g. [Card Detect Interface (23-XX)](#subsec_sdi_card_detect_interface), [Card Detect Interface (23-XX)](#subsec_sdi_card_detect_interface), [EMV System Interface](#subsec_sdi_emv_system_interface) (and other interfaces required for payments) can be used exclusive only. For this reason, SDI has introduced command Sys Lock Payment (20-06) when adding support for protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)). This new protocol type allows to do use both, side commands (which can be used without the payment lock) and payment commands (which require the lock) on the same or on different connections. For more details please read chapter [Payment lock/unlock](#para_sdi_prod_d_callback_payment_lock_unlock) carefully.
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)). With protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)) the payment lock cannot be obtained on a side connection, therefore, the command is declined with response code '64F9' (command not allowed). With protocol type A or B command Sys Lock Payment (20-06) is treated as every other command type A or B command, which tries to obtain the payment lock to use the connection as main connection.
{% endhint %}
Please be aware of different response behaviour when using different protocol types:
* Protocol type D: On success the command is kept open and not responded with a command response. The unidirectional callback [Intermediate Result Callback (99-01)](#subsubsec_sdi_intermediate_status_cb) is replied instead to signal that the payment lock was obtained successfully. Afterwards full SDI command interface is accessible for the client including mentioned payment interfaces. Even the command is not finalized, protocol type D allows to send further commands on this connection, while the open command Sys Lock Payment (20-06) holds payment lock for them. Once a SDI client has finished the payment or no longer requires the payment lock, it must use [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) with the message ID of Sys Lock Payment (20-06) to cancel and finalize it, which corresponds the release of the payment lock. Related command flows can also be found in chapter [Payment lock/unlock](#para_sdi_prod_d_callback_payment_lock_unlock). Other SDI clients, which send command Sys Lock Payment (20-06) on a connection not owning the lock (or a second time on the connection which owns the lock) are declined with 64FA (already locked) immediately. Of course, in this case the command is finalized and does not require cancellation with [Sys Abort (20-02)](#subsubsec_sdi_sys_abort).
* Protocol type B: The command is always responded with a command response. Response code '9000' means that the payment lock was successfully obtained and this connection will be used by SDI as main connection. A second Sys Lock Payment (20-06) on the main connection will also lead to a command response with error code '9000'. Sys Lock Payment (20-06) on another connection than the main connection will be declined with 64FA (already locked) immediately.
* Protocol type C: The command is always returns with a command response with error code '64F9' (command not allowed).
* Protocol type A: Same as for protocol type B, even A does not support side connections.
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ---- |
| 20 | 06 | 00 | 00 | None |
Intermediate result callback (when using protocol type D):
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------------------------------------------------------ |
| 99 | 01 | None | Payment lock obtained successfully for this connection |
Response (when using protocol type D):
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ----------------------------------------------------------------------------------- |
| 65 | 00 | None | Payment lock released successfully by [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) |
| 64 | FA | None | This or another connection has already obtained the payment lock |
Response (when using protocol B with multi connection support):
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------------------------------------------------------------------ |
| 90 | 00 | None | Payment lock obtained successfully (or already main connection) |
| 64 | FA | None | Payment lock already owned by another connection (main connection) |
Response (when using protocol C):
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------------------- |
| 64 | F9 | None | Command not allowed |
Response (when using protocol A/B without multi connection support):
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | --------------------------------------------------------------- |
| 90 | 00 | None | Payment lock obtained successfully (or already main connection) |
#### Sys Reset Link (20-07)
For communication types don't having some kind of connection set up like sockets (e.g. an USB or a serial link) command Sys Reset Link (20-07) is used to trigger an EOF (end-of-file) to reset the permanent link. With the next command on that link, SDI detects a new connection and more or less starts with a "fresh" state.
{% hint style="info" %}
The command is not supported for communication types providing a connection setup with underlying I/O layers. For instance, SDI will just decline the command with response code '64F9' (command not allowed), if command Sys Reset Link (20-07) is used on a TCP link. The command was primary introduced for Titus platform using a single USB-C link (emulated serial connection), but it works also for platforms VOS/VOS2/VOS3 using an USB or serial link. This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)).
{% endhint %}
The command will cause the following actions just like a TCP/IP client when closing a connection to SDI:
* It closes all crypto handles of [Generic Crypto Interface (70-XX)](#subsec_sdi_generic_crypto_interface), which we're opened on this connection with [Crypto Open (70-00)](#subsubsec_sdi_crypto_open)
* It aborts an active PIN entry, which was started with [PED start PIN entry (22-03)](#subsubsec_sdi_ped_start_pin) on this connection
* It aborts an active card detection, which was started with [Start Card Detection (23-03)](#subsubsec_sdi_start_card_detection) on this connection
* It aborts an active update upload, which was started with [Software Upload Start (20-14)](#para_sdi_sys_software_upload_start) on this connection
* For using it on the main connection, it will release the payment lock. In difference to [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) for an active [Sys Lock Payment (20-06)](#subsubsec_sdi_sys_lock_payment), no response is provided for protocol type D.
* For using it on the main connection with an active payment command, SDI attempts to abort the processing SDI main thread with signal about the connection lost. The aborted command won't provide a response.
* For using it on a side connection with an active side command, command Sys Reset Link (20-07) is executed after the previous commands has been finished.
* For both, on a side and on main connection, command Sys Reset Link (20-07) will reset the global busy flag and unlock other connections not to decline commands with response code '640A' (busy), if the busy lock was set by a previous command on this connection.
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ---- |
| 20 | 07 | 00 | 00 | None |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------------------- |
| 90 | 00 | None | All OK |
| 64 | F9 | None | Command not allowed |
#### Sys Register Logging Callback (20-08)
Registers the Logging Callback, which is applied to connection of the sending SDI client. After the Logging Callback was registered and confirmed successfully, the related client will receive unidirectional [Logging Notification Callbacks (98-01)](#subsec_sdi_logging_notification_callbacks) containing generated logging data of SDI provided in TLV tag `DFA161` (ADKLOG logging data).
{% hint style="info" %}
This command is recently supported for Titus platform only, since this hardware has limited resources to store logging data on the device and to download it afterwards. In addition, other external interfaces (such as VHQ) do not exists. Further, accessing console will require a special yellow cable, which is provided for development purposes only. For this reason logging data is provided via SDI interface, which can be used with a standard USB cable (e.g. VR1) Depending on number of components and detail level for logging, an huge amount ouf data might be generated. Even a bluetooth connection is not disallowed to active the logging callback, it is recommended to use an USB connection with a bigger bandwidth, which will transfer data more faster with lesser impact on SDI runtime. SDI won't generate logging data by default and logging must be enabled. This happens with the installation of an [User config package](#titus_user_config_package) containing one or more ADKLOG configuration files (one per SDI subcomponent). For more details about logging configuration, please refer to ADKLOG documentation.
{% endhint %}
Finally, [Logging Notification Callbacks (98-01)](#subsec_sdi_logging_notification_callbacks) are sent over SDI interface, whenever logging data was generated by SDI and is pending for offload. As long as the callback is not registered, SDI stores logging data to an internal ringbuffer in volatile memory (RAM). The space reserved for this ringbuffer is recently 10 KByte, which more or less covers the amount of logging data of SDI startup. After registration with command Sys Register Logging Callback (20-08), the content of the ringbuffer will be issued with [Logging Notification Callbacks (98-01)](#subsec_sdi_logging_notification_callbacks), afterwards the logging data in ringbuffer is discarded. The output of this ringbuffer is optional and can be controlled with TLV tag `DFA160` (ADKLOG register callback options). If output of the ringbuffer is disabled, SDI provides real-time logging data only, meaning generated logging data after point of callback registration. Once the Logging callback is unregistered, SDI will disable [Logging Notification Callbacks (98-01)](#subsec_sdi_logging_notification_callbacks) and create a new ringbuffer to store logging data internally again.
{% hint style="info" %}
Applications can register/unregister the Logging callback to control destination of logging data for a specific time period. It might be desired to log into ringbuffer, which has the least impact on runtime (e.g. for debugging time critical issues like race conditions). Otherwise, applications can also prefer real-time logging data with an registered callback to get logging data immediately. However, a logging entry is always prefixed with a timestamp of the device. SDI always issues buffered logging data of ringbuffer before providing real-time logging data. [Logging Notification Callbacks (98-01)](#subsec_sdi_logging_notification_callbacks) are not issued before Sys Register Logging Callback (20-08) was confirmed by SDI. Confirmation depends on used protocol type (see below).
{% endhint %}
Command Sys Register Logging Callback (20-08) is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)). This new protocol type allows to do use both, side commands (which can be used without the payment lock) and payment commands (which require the payment lock) on the same or on different connections. For more details please read chapter [Payment lock/unlock](#para_sdi_prod_d_callback_payment_lock_unlock) carefully. For protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)) command Sys Register Logging Callback (20-08) is not supported, since a side connection does not allow the use of callbacks. Therefore, the command is declined with response code '64F9' (command not allowed). For protocol type A or B command Sys Register Logging Callback (20-08) is supported, but is treated as every other command type A or B command, which tries to obtain the payment lock to use the connection as main connection.
Please be aware of different response behaviour when using different protocol types:
* Protocol type D: On success the command is kept open and not responded with a command response. The unidirectional callback [Intermediate Result Callback (99-01)](#subsubsec_sdi_intermediate_status_cb) is replied instead to signal that the Logging Callback was registered successfully. Afterwards SDI will sent [Logging Notification Callbacks (98-01)](#subsec_sdi_logging_notification_callbacks) to issue logging data. Even the command is not finalized, protocol type D allows to send further commands on this connection, while the open command Sys Register Logging Callback (20-08) holds the permission to send [Logging Notification Callbacks (98-01)](#subsec_sdi_logging_notification_callbacks) asynchronously. Once a SDI client wants to disable logging data offload with [Logging Notification Callbacks (98-01)](#subsec_sdi_logging_notification_callbacks), it must use [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) with the message ID of Sys Register Logging Callback (20-08) to cancel and finalize it, which means the Logging Callback gets unregistered. Other SDI clients, which send command Sys Register Logging Callback (20-08) on a connection while the Logging Callback was already registered (or a second time on same connection) are declined with 64F5 (already registered) immediately. Of course, in this case the command is finalized and does not require cancellation with [Sys Abort (20-02)](#subsubsec_sdi_sys_abort).
* Protocol type B: The command is always responded with a command response. Response code '9000' means that the Logging Callback was registered successfully and this connection will be used as connection to offload logging data. A second Sys Register Logging Callback (20-08) on this connection will also lead to a command response with error code '9000'. Sys Register Logging Callback (20-08) on another connection will be declined with 64F5 (already registered) immediately.
Since Sys Register Logging Callback (20-08) with protocol B behaves as every other command and tries to obtain the payment lock (see chapters Protocol Type B: Communication w/o flow control and Protocol Type C: Multi connection support), it will be declined with 64FA (already locked), if another connection is already main connection and owns the payment lock.
* Protocol type C: The command is always returns with a command response with error code '64F9' (command not allowed).
* Protocol type A: Same as for protocol type B, even A does not support side connections.
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 20 | 08 | 00 | 00 | Constructed |
Command Data:
| | | | | |
| ------ | ---- | --- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tag | Size | M/O | Format | Description |
| DFA160 | 1 | O | b |
ADKLOG register callback options (big endian), bit mask with following values:
0x00 (ADKLOG\_NoOpts): No options set (default)
0x01 (ADKLOG\_RealTimeDataOnly): Provide only real-time logging data, do not previously output buffered logging data of internal ringbuffer
|
Intermediate result callback (when using protocol type D):
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------------------------------------------------------------ |
| 99 | 01 | None | Logging Callback successfully registered for this connection |
Response (when using protocol type D):
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ----------------------------------------------------------------------------------------------- |
| 65 | 00 | None | Logging Callback was unregistered successfully by [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) |
| 64 | F5 | None | This or another connection has already registered the Logging Callback |
Response (when using protocol B with multi connection support):
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 90 | 00 | None | Logging Callback successfully registered (or already registered for this connection). If not done before, the payment lock was obtained (as main connection) |
| 64 | F5 | None | Another connection has already registered the Logging Callback |
| 64 | FA | None | Logging Callback couldn't be registered, since payment lock is already owned by another connection (main connection) |
Response (when using protocol C):
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------------------- |
| 64 | F9 | None | Command not allowed |
Response (when using protocol A/B without multi connection support):
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------------------------------------------------------------------------------------- |
| 90 | 00 | None | Logging Callback successfully registered (or already registered for this connection). |
#### Sys Set Status (20-09)
Set device status info (see [System Tags](#subsubsec_sdi_system_tags))
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 20 | 09 | SC | 00 | Constructed |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | -------------------- |
| 90 | 00 | None | All OK |
| 62 | 00 | None | Tag Error |
| 63 | 00 | None | Tag Length Error |
| 64 | 00 | None | Execution Error |
| 67 | 00 | None | Message Length Error |
| 6D | 00 | None | Unknown Instruction |
{% hint style="info" %}
Only one TLV field may be supplied with each command. For setting different status info fields, separate commands must be issued. To set date and time the year has to be "2000" at least. Otherwise an Execution Error '64 00' will be returned.
{% endhint %}
Example:
```cpp
// Command to set time and date (to 2010/12/31 - 23:59:59)
20 09 00 00 F0 09 D0 07 14 0A 0C 1F 17 3B 3B
// Response
90 00
```
{% hint style="info" %}
In the two piece solution this command will be forwarded from the Countertop to the EPP automatically.
{% endhint %}
#### Sys Get KSN (20-10)
Command checks if a key for PED, SRED or E2E encryption/decryption is loaded and returns the corresponding Key Serial Number (KSN) with one of the following default values:
* PED: 00 00 00 00 00 00 00 00 00 00
* SRED: 11 11 11 11 11 11 11 11 11 11
* E2E: 22 22 22 22 22 22 22 22 22 22
P2 indicates the DUKPT engine
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ------------ |
| 20 | 10 | SC | 00 | None | For PED KSN |
| 20 | 10 | SC | 01 | None | For SRED KSN |
| 20 | 10 | SC | 02 | None | For E2E KSN |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | -------- | ------- |
| 90 | 00 | KSN\[10] | All OK |
{% hint style="info" %}
**Since SDI-Server version greater than 4.23.2 this command is obsolete and will be always responded with 6D00 (Unknown Instruction).**
{% endhint %}
#### Sys Auth (20-11)
This command manages the synchronization of the E2E session key between the Host device and the SDI Server within two steps.
**Mutual** [**Auth**](/s-adk-5.1-programmers-guide/readme/annotated/class_auth.md) **and Session Key Setup Step 1**
* Host sends 16 bytes of random to the SDI-Server
* SDI-Server stores the Host random
* SDI-Server encrypts 16 bytes of SDI-Server token and 16 bytes of SDI-Server random (plus the used KSN) and sends this back to the Host
* The Host decrypts the data and stores the SDI-Server token and random
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | --------------- |
| 20 | 11 | 00 | 01 | HostRandom\[16] |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | --------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| 90 | 00 |
|
| 64 | 00 | None | Execution Error |
Example:
```cpp
// Mutual Auth and Session Key Setup Step 1 (clear text)
20 11 00 01 E8 68 23 38 9E 52 83 AE EC 52 04 4C A8 0F 3B 9E
// Response (encrypted)
90 00 2A FE 62 3D C7 6B F0 5B 7E D7 08 CA C0 69 12 D9 C4 69 A6 DC 2C 3E C3 CB 99 50 9B F4 0D 48 A5 1C FF FF 98 76 54 33 33 E0 00 A5
```
**Mutual** [**Auth**](/s-adk-5.1-programmers-guide/readme/annotated/class_auth.md) **and Session Key Setup Step 2**
* Host and SDI-Server prepare 16 bytes 3DES session key (SK) as XOR of Host Random and SDI-Server Random.
* Host sends 32 bytes data block, which includes 16 bytes of SDI-Server Token and 16 bytes of Host Token. The data block encrypted with 3DES session key (SK).
* SDI-Server decrypts the data block with 3DES session key (SK) and compares the received SDI-Server token with the SDI-Server Token, which sent to the Host in the step 1. If they are same, the Host is authenticated and the SDI-Server continues the step 2. Else authenticate is stopped.
* SDI-Server sends the response to the Host. The response is 32 bytes data block, which includes 16 bytes of Host Token and 16 bytes of SDI-Server Serial Number. The data block encrypted with 3DES session key (SK).
* Host receives decrypts the data block with 3DES session key (SK) and compares the received Host Token with the Host Token, which sent to the SDI-Server in the step 2 command. If they are same, the SDI-Server is authenticated. Else authenticate is stopped.
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ---------------------------------------------------------------------- |
| 20 | 11 | 00 | 02 |
Ciphered Host Data \[32]: PINPadToken\[16], ServerToken\[16]
|
| 64 | 00 | None | Execution Error |
Example:
```cpp
// Mutual Auth and Session Key Setup Step 2 (encrypted)
20 11 00 02 E6 8D 3D 0B 2B ED E6 92 9B 6F 39 34 38 A9 46 2C 36 15 9A 7E 9F C4 22 8E 93 6C 12 35 8D 40 B6 9A
// Response (encrypted)
90 00 3E 15 68 C3 C3 59 68 1D EA AF EC 7C 12 82 01 C7 F8 48 79 15 A8 17 F8 04 53 8F 97 53 02 DA 81 E7
```
{% hint style="info" %}
These commands are not supported on EPP.
{% endhint %}
#### Set Idle Text (20-13)
Command to set a text for SDI idle screen (see [Display Idle Screen (24-07)](#subsubsec_sdi_display_idle_screen)). The text is stored persistently and re-used after reboot. If no text was set, SDI takes the default text from UI catalog installed with the SDI config package for standard mode (see [Default UI resource files](#subsubsec_sdi_default_resource_files)), which can be also replaced with a custom UI catalog (see chapter [Custom UI text catalogs](#subsubsec_sdi_custom_text_catalogs)).
{% hint style="info" %}
Using a custom UI catalog to configure an own idle text is the recommended method, since this works system language depended. After deletion of the idle text (with field `P2` containing value `01`) the SDI will be display the text from the UI catalog of current system language.
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ------------------------- |
| 20 | 13 | SC | XX | Constructed | P2: 00 = set, 01 = delete |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------------------------- |
| DFA001 | var. | M | utf-8 | Idle Text |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | --------------- |
| 90 | 00 | None | All OK |
| 64 | 00 | None | Execution Error |
Examples:
```cpp
// Command to set the idle text to "\n\n Hello world"
20 13 00 00 F0 16 DF A0 01 12 0A 0A 20 20 20 20 20 48 65 6C 6C 6F 20 77 6F 72 6C 64
// Response
90 00
```
```cpp
// Command to delete the idle text
20 13 00 01
// Response
90 00
```
#### Software and Configuration Upload
The Secure Data Interface provides 2 different methods to install software updates and SDI configuration files:
* **Software/File Upload:** This method is used to upload a file (e.g. an software download package or configuration file) and to install it after the successful transfer. The following commands are used for this method:
* [Software Upload Start (20-14)](#para_sdi_sys_software_upload_start) as start command to initiate the file upload
* [Software Upload Transfer (20-15)](#para_sdi_sys_software_upload_transfer) to transfer the file content in multiple data records
* [Software Upload Finalize (20-16)](#para_sdi_sys_software_upload_finalize) as final command to validate the uploaded file records and to install the file
Software download packages or configuration files are directly uploaded to SDI server over Secure Data Interface. A software download package (TGZ or TAR ball) contains internal bundles and install packages. Each bundle and package comes along with a signature. After file upload the software package is installed with Secure Installer API, which is part of the Engage OS and not supported on Android platform (see Check For Update below). Configuration files are authenticated through a MAC, which provided with the final command Software Upload Finalize (20-16). The MAC is generated with the session key, which was negotiated with the system authentication (see chapter Sys Auth (20-11) for more details). Keep in mind that no partial update of configuration files is supported, only complete configuration files have to be uploaded. In case of upload and authentication, the existing update package or configuration file will be deleted after successful installation.
* **Check For Update:** This method is used to check for pending updates and to install one or multiple update packages. The following command is used for this method:
* [Check For Update (20-1D)](#para_sdi_sys_software_check_update)
Update packages may contain software updates or configuration files. In difference to method Software/File Upload the files are not directly uploaded over Secure Data Interface to SDI server. Update packages are uploaded and installed with the Android Secure Installer (Update Service), which is part of the Verifone Android OS. Before upload all files must be packed into an update package (TGZ file), which contains one or more internal ZIP bundles. The update package contains a manifest and a signature for each internal bundle. After the update package was authenticated and verified, the Android Secure Installer extracts the package contents to the update folder of SDI server, before it is notified by Android Secure Installer for pending update. Update packages are provided by SDI users (application or integration team). For more details about Android Secure Installer and the update package format, please refer to Android Secure Installer documentation.
{% hint style="info" %}
The Software Update of a two piece solution has to be performd as followed: 1. Update of the EPP and after this\
2\. Update of the Countertop!
{% endhint %}
**Software Upload Start (20-14)**
Command to initiate the upload of a download package for software update. In addition, the command supports upload of several configuration files or packages to install UVRK payload files.
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)). If a SDI command on another connection is active, Software Upload Start (20-14) is declined with response code '640A' (busy). In addition, during processing the upload (until completion with [Software Upload Finalize (20-16)](#para_sdi_sys_software_upload_finalize)), SDI server will decline all other SDI commands with response code '640A' (busy).
{% endhint %}
The type for file upload is specified by TLV tag `DFA01E` (upload type). If the tag is not provided, upload type `00` (Software Update) is taken as default. Some upload types additionally require TLV tag `DFA020` (filename), which is expected as filename without path prefix. For details, see list of supported upload types in table below.
Supported values for TLV tag `DFA01E` (upload type) are the following:
| | |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tag Value | Description |
| `00` |
Software Update (supported on VOS/VOS2, VOS3 and Titus only) TLV tag DFAO20 (filename) is mandatory for this upload type on VOS/VOS2 and VOS3, which must have *.tgz or *.tar as file extension. On Titus, the tag is optional, if provided, the file extension \*.tar is expected. A download package is used as upload file, for which SDI will use API of Secure Installer for installation on the target. Thus, please ensure that the package format is considered for the corresponding platform, otherwise Secure Installer will decline the installation.
|
| `01` |
White list configuration (not supported on Titus) A whitelist file (JSON format) is expected as upload file, see chapter whitelist.json for more details. TLV tag DFAO20 (filename) is not expected by SDI and ignored, if provided.
|
| `02` |
Sensitive tags configuration (not supported on Titus) A JSON file with additional sensitive EMV tags is expected as upload file, see chapter sensitivetags.json for more details. TLV tag DFAO20 (filename) is not expected by SDI and ignored, if provided.
|
| `03` |
Card ranges configuration (not supported on Titus) A card ranges configuration files (JSON format) is expected as upload file, see chapter sensitivetags.json for more details. TLV tag DFAO20 (filename) is not expected by SDI and ignored, if provided.
|
| `0B` |
Install commerce platform package (supported on VOS2 only) TLV tag DFAO20 (filename) is mandatory for upload type. TLV tag DFAO20 (filename) is mandatory for this upload type, which must have \*.zip as file extension.
Note
For details about the format of a CP package, please refer to documentation of CP installer.
|
| `0C` |
EMV configuration package (not supported on Titus) This package is uploaded as an uncompressed TAR file containing configuration files for ADKEMV, on which this component requires write access (such as EMV\_Applications.xml, EMV\_CTLS\_Terminal.xml, EMV\_Terminal.xml etc.). All files in the archive are expected flat on top level without any subfolders. SDI does not expect the filename of the package, thus, TLV tag DFAO20 (filename) is ignored, if provided.
Note
EMV configuration file emv-desired.xml (with EMV kernel/device specifications) is not allowed in EMV configuration package. Please use an user config package to install this file persistenly (see chapter User config package and User config package).
Upload of an EMV configuration package will exit EMV CT/CTLS Framework(s) and disable the EPP (if connected and enabled). Therefore, applications must consider after upload to initialize EMV CT/CLTS Framework(s) (see EMV System Interface) and enable the EPP again (see Enable EPP (20-21)).
|
| `0D` |
UVRK package (supported on Titus only) This package is uploaded as uncompressed TAR file containing *.vrk2.json payload files. All files in the archive are expected flat on top level without any subfolders. SDI does not expect the filename of the package, thus, TLV tag DFAO20 (filename) can be omitted. If provided, SDI will check the filename against pattern *.uvrk.tar, which is expected as filename for UVRK packages.
Note
For details about the format of an UVRK package, please refer to Unified VRK package specification.
|
{% hint style="info" %}
Upload type `00` (Software Update) is not supported on Android. For software update on this platform please refer to chapter [Check For Update (20-1D)](#para_sdi_sys_software_check_update). Configuration upload with upload types `01`-`03` and `0C` might require additional authentication by MAC, if the connection of SDI client is not considered as trusted, see [Software Upload Finalize (20-16)](#para_sdi_sys_software_upload_finalize) for more details. Please also note that configuration upload will install files to flash directories of SDI for direct use. No file backups were kept after upload and SDI might modify files during runtime afterwards. In addition, a [Factory Reset (20-22)](#subsubsec_sdi_sys_factory_reset) will delete the configuration files or recover them in flash to defaults (if any). Therefore, applications have to consider to upload the configuration files again in this case. If a project requires to overload default configuration files persistenly and to recover them with [Factory Reset (20-22)](#subsubsec_sdi_sys_factory_reset), the installation of an user config package is the preferred method (for more details see chapters [User config package](#vos_user_config_package) and [User config package](#android_user_config_package)).
{% endhint %}
After successful execution, the payment application must continue with sequence of command [Software Upload Transfer (20-15)](#para_sdi_sys_software_upload_transfer) to transfer the file records.
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ------- |
| 20 | 14 | SC | 00 | Constructed | |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ---------------------------------------------------------------------------------------------- |
| DFA020 | var. | O | utf-8 | Filename incl. extension (Mandatory for upload types `00` (VOS/VOS2/VOS3) and `0B` (VOS2 only) |
| DFA01E | 1 | O | b | Upload type, default: `00` (Software Update) |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
{% hint style="info" %}
On Engage the filename must have extension `tar` or `tgz`, otherwise the command is declined. The additional optional tag `DFA150` is used to specify the destination device for two piece solutions. Upload types `01`-`03` and `0C` (configuration) are not allowed for EPP.
{% endhint %}
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | -------------------- |
| 90 | 00 | None | All OK |
| 62 | 00 | None | Tag Error |
| 63 | 00 | None | Tag Length Error |
| 64 | 00 | None | Execution Error |
| 64 | 0A | None | SDI-Server is busy |
| 64 | F9 | None | Command not allowed |
| 64 | FD | None | Logic Error |
| 67 | 00 | None | Message Length Error |
Example:
```cpp
// Command to initiate the file upload (Software Update)
20 14 00 00 F0 0F DF A0 20 0B 75 70 5F 74 65 73 74 2E 74 67 7A
// Response
90 00
```
**Software Upload Transfer (20-15)**
Command to upload the file, record by record to the terminal.
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)). Only this connection, which has initiated the upload with [Software Upload Start (20-14)](#para_sdi_sys_software_upload_start), is allowed to use Software Upload Transfer (20-15). During processing the upload (until completion with [Software Upload Finalize (20-16)](#para_sdi_sys_software_upload_finalize)), SDI server will decline all other SDI commands with response code '640A' (busy).
{% endhint %}
For each record the packet number has to be increased. If the terminal detects a packet number mismatch, it deletes the already stored records and the file update has to be started from scratch. Please note that the upload time depends on communication bandwidth and file size.
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ------- |
| 20 | 15 | SC | 00 | Constructed | |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| DFA021 | var. | M | b | Record data. Size is limited by maximum message size of underlying transport layer (see [Transport Layer](#subsec_sdi_transport_layer)) |
| DFA022 | ..4 | M | b | Packet number. First packet should be number 1. |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | -------------------- |
| 90 | 00 | None | All OK |
| 62 | 00 | None | Tag Error |
| 63 | 00 | None | Tag Length Error |
| 64 | 00 | None | Execution Error |
| 64 | FE | None | Parameter Error |
| 67 | 00 | None | Message Length Error |
Example:
```cpp
// Command to upload
20 15 00 00 F0 82 03 90 DF A0 21 82 03 84 50 4B 03 04 14 00 02 00 08 00 05 57
7B 47 98 30 7C 69 D0 03 00 00 4A 04 00 00 0A 00 00 00 43 65 72 74 69 66 2E 63
72 74 33 68 62 71 33 68 62 D6 5B C0 CC C4 C8 C4 C4 66 69 6A 6A 6A 60 64 C0 CB
C6 A9 D5 E6 D1 F6 9D 97 91 91 9B 95 C1 C0 D3 50 DE 80 9B 8D 39 94 85 5B 98 25
34 D8 35 C8 40 00 C4 E1 12 E6 0C 4B 2D CA AC 50 48 0D CB 37 54 83 88 E9 32 73
32 33 31 33 32 9A 5B 27 CD 30 10 02 89 30 0B 73 3B BA 38 2B B8 A7 16 E5 26 E6
55 1A 28 88 F3 1A 9A 18 98 19 1A 19 5A 9A 98 1A 98 47 49 F0 1B 19 1A 1A 18 18
02 21 18 44 19 44 1A 1A 13 B0 0C 9B C1 86 4A 06 7C 20 51 1E 11 F6 90 D4 E2 92
78 43 53 B8 83 18 98 58 14 58 42 34 DB 14 0D 9A 18 95 90 BD C6 C8 CA C0 DC C4
C8 CF 00 14 E7 62 6A 62 64 64 78 14 70 E9 63 F7 E3 B4 79 13 8F 5E 9D B8 E2 55
F4 B2 03 27 33 2D EE F7 6F 3A 7C E2 C7 D6 CE D9 A7 1F 7E 98 EB 28 31 D5 48 95
B9 2B 39 32 CF 72 5A 69 A1 D3 8D 50 BD E0 AD 31 6F 56 94 ED 9B C6 D3 25 24 EB
9D 69 EE BF E0 7A 38 A3 A5 C2 4B AE B9 8C B1 FF 9E DE B4 9F 75 F5 61 D7 D2 4B
FD 8E 4C 99 39 31 C6 BE 97 8A E4 36 BE 10 48 32 7B 16 65 E2 E8 6C 95 9B 73 EF
1C EB FE 8D 25 12 65 DB B4 3D 7F 54 97 AD 3C F1 CC 7A 47 BC D4 F9 B2 B5 41 3C
BB CC 4C 6D 83 4E BB E9 4E 6C 7D 5B CD ED 9C E5 37 63 CA BC AF 55 77 BE 33 DB
DF 36 3B 7B 50 20 58 D5 76 61 1B B7 C5 FE 57 0B 37 97 B8 18 31 C8 DD E9 BF CB
37 C1 F9 C5 15 6D 17 1D CF 89 BB 6F BB CD BB D8 72 2E 7B FD AA D7 77 3C 1A 9D
D5 AC E5 EC 66 1A 78 AE E5 FF D4 18 6C C7 A3 F7 68 B5 BA BC 8D 5F A5 F1 86 0E
DE 1B D7 5E 7F BA C6 A1 B2 55 3A CD C2 5C A0 EE F0 67 D1 6A 60 CC 31 30 2E 6E
62 54 00 86 88 8C 81 12 30 FC 64 95 19 19 FF B3 48 18 88 35 88 68 76 15 9E 0B
F8 F2 46 3D F6 54 F0 B2 E9 6E 21 77 75 36 D9 4E 34 50 00 A9 E1 03 A9 11 63 11
49 12 AF FF FE D4 6B 7B A0 E6 C9 A7 5B FC 32 AC 18 E7 B5 89 3F 30 E0 01 A9 E0
67 61 65 66 66 6F 60 80 F0 84 59 58 0D 80 C9 8D C1 A0 94 8D 2B A1 CD 83 B1 67
96 03 30 32 58 D2 0D 52 81 06 19 24 88 31 1A 8A 31 1A 89 31 1A 8B 31 9A 88 31
9A 8A 31 9A 89 31 9A 8B 31 5A 88 31 5A 8A 31 19 1A 00 B1 21 10 1B 01 B1 31 10
9B 00 31 50 8D A3 18 A3 93 18 A3 B3 18 A3 8B 18 A3 AB 18 A3 9B 18 A3 BB 18 A3
87 18 A3 A7 18 A3 97 18 A3 B7 18 A3 8F 18 A3 AF 18 A3 9F 18 A3 BF 81 08 92 B5
4C 20 B7 03 13 2C 83 81 28 92 28 33 48 94 85 89 89 E1 3F 8A 62 16 A8 E2 FF 68
19 84 19 94 78 EE AB 59 7F 95 9C ED B9 49 F6 5E F6 79 DE F2 E8 BA D4 C8 AB 77
FE C6 ED D7 F8 B1 70 B3 EC DD 72 D9 CB 92 FB 9F 56 26 1E 4E D1 30 7E 6A 26 3D
67 E3 EA C3 FF FD 6C B2 2B 64 3D 96 31 7F BB 59 E8 B9 82 3F A8 F8 A0 D2 7E 5D
15 3B FF D9 AD 7C E2 1F 4D 37 E4 F8 46 1D DB D8 78 40 A4 51 E0 54 C3 F7 1A D7
55 C7 1F 69 5C 5E FD 79 D7 95 6D C6 FF B7 6F E8 EB 3C D6 51 DE 59 A7 BC E1 D8
CB 8A E2 35 BB 5F FD 11 9F E7 F4 2A F3 7C EC 3A E9 88 EC A3 29 EF 1F 2D 2D 35
08 AE B8 FB DF A0 22 02 00 01
// Response
90 00
```
**Software Upload Finalize (20-16)**
Final command to validate and install the file, which was previously uploaded with command [Software Upload Transfer (20-15)](#para_sdi_sys_software_upload_transfer).
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)). Only this connection, which has initiated the upload with [Software Upload Start (20-14)](#para_sdi_sys_software_upload_start) and [Software Upload Transfer (20-15)](#para_sdi_sys_software_upload_transfer), is allowed to finish the upload with Software Upload Finalize (20-16). All other SDI commands are declined with response code '640A' (busy) as long as the upload and the installation are not completed.
{% endhint %}
For Software Update with upload type `00` (see chapter [Software Upload Start (20-14)](#para_sdi_sys_software_upload_start)), an optional check of the MD5 file checksum can be requested. After successful validation the terminal installs the software package and does a reboot afterwards.
For configuration file upload with upload types `01`-`03` and `0C` the file must be authenticated through a MAC (TLV tag `DFA01F`), which is provided with tag `DFA01F`. Prerequisite for the MAC calculation is the system authentication with command [Sys Auth (20-11)](#subsubsec_sdi_sys_auth). Please note that the system authentication is recently supported on Engage platform only. Other platforms (e.g. Android) might use a SDI plugin, to authorize the configuration file via the trigger SDITrigger\_SDIConfig. After successful validation the terminal installs the configuration file without reboot of the terminal.
{% hint style="info" %}
By default, local SDI clients connecting from the same device are considered as trusted (see chapter [SDI access control](#subsubsec_sdi_access_control)). For these applications the MAC (TLV tag `DFA01F`) can be omitted and an additional SDI plugin to authenticate the configuration is not required. But please note that it is the responsibility of these applications that the provided configuration is authentic! If this default behaviour of SDI server is not desired, projects might implement a corresponsing SDI plugin with their own security.
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ---------------------------- |
| 20 | 16 | SC | 00 | None | |
| 20 | 16 | SC | 00 | Constructed | If checksum/MAC is requested |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------------------------- |
| DFA023 | 16 | O | b | MD5 check sum |
| DFA01F | 8 | O | b | MAC of the configuration file |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ------------------------------------------------ |
| 90 | 00 | None | All OK |
| 90 | 00 | Constructed | Post installation action |
| 62 | 00 | None | Tag Error |
| 63 | 00 | None | Tag Length Error |
| 64 | 00 | Constructed | Execution Error |
| 64 | FB | None | Invalid File Content |
| 64 | FC | None | File Access Error |
| 64 | FD | None | Logic Error |
| 67 | 00 | None | Message Length Error |
| 68 | 02 | None | Invalid or no result data returned by the plugin |
| 6F | B0 | None | CMAC Error |
| 6F | B1 | None | CMAC Length Error |
| 6F | B2 | None | CMAC Missing Error |
Response Data:
| | | | | |
| ------ | ---- | --- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tag | Size | M/O | Format | Description |
| DFA000 | 4 | O | b |
For upload type 00 (Software Upload) on VOS/VOS2: Post installation action (bit mask). 01: Reboot is required after installation is complete 02: Application restart is required after installation is complete
For upload type 00 (Software Upload) on VOS3: No response data returned. Terminal reboots automatically after successful installation.
For upload type 00 (Software Upload) on Titus: Additional error information/result code of Titus secure installer.
For upload type 0D (UVRK package) on Titus: Optional response data in case of error responses. Contains error code from interal SPROC-API function.
|
Examples:
```cpp
// Command to finalize software upload with MD5 checksum: 1020356F6949C4529DFFAD49A146A3419F
20 16 00 00 F0 14 DF A0 23 10 20 35 6F 69 49 C4 52 9D FF AD 49 A1 46 A3 41 9F
// Response
90 00
```
```cpp
// Command to finalize the software upload without checksum check
20 16 00 00
// Response
90 00
```
**Check For Update (20-1D)**
Command to check for available updates on various configuration types and apply those.
{% hint style="info" %}
This command is only available on Verifone Android platforms. This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)). If a SDI command on another connection is active, Check For Update (20-1D) is declined with response code '640A' (busy). In addition, during processing the command, SDI server will decline all other SDI commands with response code '640A' (busy).
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ------- |
| 20 | 1D | SC | 00 | None | |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ------------------ |
| DFA01E | 1 | M | b | Configuration type |
Configuration Types:
| Type | Value | Description |
| -------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------- |
| Whitelist | 01 | whitelist.json configuration (obsolete, use SDI user config with value 06 instead) |
| Sensitive Tags | 02 | sensitivetags.json configuration (obsolete, use SDI user config with value 06 instead) |
| Card Ranges | 03 | cardranges.json configuration (obsolete, use SDI user config with value 06 instead) |
| Firmware | 04 | secure processor firmware |
| Keys | 05 | key configurations |
| SDI user config | 06 | SDI user configuration files, see chapter [User config package](#android_user_config_package) for Android |
| Remove Sponsor | 07 | check for sponsors to remove from CRTRESET.SYS |
| Remove SDI user config | 08 | remove user configuration files, see chapter [User config removal package](#android_user_config_removal_package) for Android |
| SDI plugin package | 09 | install SDI plugin(s), see chapter [SDI plugin package](#android_sdi_plugin_package) for Android |
| SDI plugin removal package | 0A | remove SDI plugin(s), see chapter [SDI plugin removal package](#android_sdi_plugin_removal_package) for Android |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | -------------------- |
| 90 | 00 | None | All OK |
| 90 | 00 | Constructed | All OK |
| 62 | 00 | None | Tag Error |
| 63 | 00 | None | Tag Length Error |
| 64 | 00 | Constructed | Execution Error |
| 64 | 0A | None | SDI-Server is busy |
| 64 | FC | None | File Access Error |
| 64 | FD | None | Logic Error |
| 64 | FE | None | Parameter Error |
| 67 | 00 | None | Message Length Error |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ------------------------------------------------------------------------------------------------------- |
| DFA000 | 4 | O | b | Optional response data in case of error responses. Contains error code from interal SPROC-API function. |
#### Shutdown/Reboot/Sleep (20-17)
Executes a system shutdown, reboot or sets the device in sleep or hibernate state.
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ------------------------------------ |
| 20 | 17 | 00 | 00 | None | Shutdown |
| 20 | 17 | 00 | 01 | None | Reboot |
| 20 | 17 | 00 | 02 | None | Sleep (not supported on Android) |
| 20 | 17 | 00 | 03 | None | Hibernate (not supported on Android) |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------------------------- |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ------------------ |
| 90 | 00 | None | All OK |
| 64 | 00 | Constructed | Execution Error |
| 64 | 0A | None | SDI-Server is busy |
{% hint style="info" %}
In case of response code '64 00' additional tag DFA000 include the return value from the corresponding ADK function.
{% endhint %}
#### Show MAC Desktop (20-18)
Switch from SDI to MAC Desktop. SDI is still running in background.
{% hint style="info" %}
This command is not supported on Android platforms (e.g. Trinity).
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ------- |
| 20 | 18 | 00 | 00 | None | |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | --------------- |
| 90 | 00 | None | All OK |
| 64 | 00 | Constructed | Execution Error |
{% hint style="info" %}
\[unsupported block]
{% endhint %}
#### Set Property (20-19)
Access to [sysSetPropertyInt()](/s-adk-5.1-programmers-guide/readme/modules/group__led/namespacevfisysinfo.md#a377307b06ac969f30af51e7cccf94dbb) and [sysSetPropertyString()](/s-adk-5.1-programmers-guide/readme/modules/group__led/namespacevfisysinfo.md#ae7c891a4a38d050452eee0939a7f82de) functions via the serialized command interface.
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)). One property can be handled per command call only.
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | --------------- |
| 20 | 19 | 00 | 00 | Constructed | Int Property |
| 20 | 19 | 00 | 01 | Constructed | String Property |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------- | -------------------------------------------------------- |
| DFBC01 | ..4 | M | b | Property identifier |
| DFBC02 | var. | M | b / ans | Value identifier |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ---------------- |
| 90 | 00 | None | All OK |
| 62 | 00 | None | Tag Error |
| 63 | 00 | None | Tag Length Error |
| 64 | 00 | Constructed | Execution Error |
{% hint style="info" %}
In case of response code '64 00' additional tag DFA000 include the return value from the corresponding ADK function.
{% endhint %}
#### Get Property (20-1A)
Access to [sysGetPropertyInt()](/s-adk-5.1-programmers-guide/readme/modules/group__led/namespacevfisysinfo.md#ab94a5b33000760afbee10e7fefd16355) and [sysGetPropertyString()](/s-adk-5.1-programmers-guide/readme/modules/group__led/namespacevfisysinfo.md#af6c938992e005c446c81e7f1fe3e4ed3) functions via the serialized command interface.
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)). One property can be handled per command call only.
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | --------------- |
| 20 | 1A | 00 | 00 | Constructed | Int Property |
| 20 | 1A | 00 | 01 | Constructed | String Property |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------------------------- |
| DFBC01 | ..4 | M | b | Property identifier |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ---------------- |
| 90 | 00 | Constructed | All OK |
| 62 | 00 | None | Tag Error |
| 63 | 00 | None | Tag Length Error |
| 64 | 00 | Constructed | Execution Error |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------- | ------------------- |
| DFBC01 | ..4 | M | b | Property identifier |
| DFBC02 | var. | M | b / ans | Value identifier |
{% hint style="info" %}
In case of response code '64 00' additional tag DFA000 include the return value from the corresponding ADK function.
{% endhint %}
#### Install Sponsor Cert (20-1B)
Check and Install a Sponsor Certificate.
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)). If a SDI command on another connection is active, Install Sponsor Cert (20-1B) is declined with response code '640A' (busy). In addition, during processing the command, SDI server will decline all other side commands with response code '640A' (busy).
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ------- |
| 20 | 1B | 00 | 00 | Constructed | |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | --------------------------------------------------- |
| DFA12F | var. | M | b | Sponsor certificate (DER-encoded X.509 certificate) |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ----------------------------------------- |
| 90 | 00 | None | Certificate accepted or still exist |
| 62 | 00 | None | Tag Error |
| 64 | 00 | None | Execution Error, certificate not accepted |
| 64 | 0A | None | SDI-Server is busy |
| 64 | FE | None | Parameter Error |
| 67 | 00 | None | Message Length Error |
{% hint style="info" %}
A possibly required restart of the device has to be initiated separately (see [Shutdown/Reboot/Sleep (20-17)](#subsubsec_sdi_sys_shutdown_reboot_sleep))
{% endhint %}
#### Get SDI version info (20-1C)
Get version information of basic SDI components and installed SDI plugins.
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)).
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ------- |
| 20 | 1C | 00 | 00 | None | |
| 20 | 1C | 00 | 00 | Constructed | |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------------------------- |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ----------------------------------------- |
| 90 | 00 | Constructed | Version information successfully returned |
| 64 | 00 | None | Execution Error, TLV Export failed |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ---------------------------------------------------------------------------------- |
| FFA103 | var. | M | tlv | SDI component containing a pair of tag DFA00E and DFA00F. May Occur Several Times. |
| DFA00E | var. | M | ans | Name of the SDI component |
| DFA00F | var. | M | ans | Version of the SDI component |
Example:
```cpp
// Command to get SDI component version information
20 1C 00 00
// Response:
90 00 F0 75 FF A1 03 17 DF A0 0E 0A 53 44 49 20 53 65 72 76 65 72 DF A0 0F 05 34 2E 30 2E 30 FF
A1 03 16 DF A0 0E 09 6C 69 62 73 64 69 63 73 64 DF A0 0F 05 31 2E 30 2E 30 FF A1 03 1A DF A0 0E
0D 73 64 69 70 6C 75 67 69 6E 2D 63 62 61 DF A0 0F 05 31 2E 30 2E 32 FF A1 03 1E DF A0 0E 11 73
64 69 70 6C 75 67 69 6E 74 65 73 74 2D 63 62 61 DF A0 0F 05 31 2E 30 2E 30
```
Included TLV tags in contructed tag F0:
```fragment
Found tag SDI component (FFA103):
Component name (DFA00E) : SDI Server
Component version (DFA00F): 4.0.0
Found tag SDI component (FFA103):
Component name (DFA00E) : libsdicsd
Component version (DFA00F): 1.0.0
Found tag SDI component (FFA103):
Component name (DFA00E) : sdiplugin-cba
Component version (DFA00F): 1.0.2
Found tag SDI component (FFA103):
Component name (DFA00E) : sdiplugintest-cba
Component version (DFA00F): 1.0.0
```
#### Get last install error (20-1E)
Get last installation error/result from secure installer.
On platform VOS and VOS2 the last installation error can occur in two different variants, which depend on secure installer libary API version on the target:
* The new API returns the result of the last installation nevertheless if this installation was successful or not. The output will be provided with TLV tag DFA148 in JSON format.
* The old API returns the name of the failed bundle (TLV tag DFA149) and/or package (TLV tag DFA151) name only in cases of error. In addition, the old API only shows an error, if the package was installed by SDI server with commands [Software Upload Start (20-14)](#para_sdi_sys_software_upload_start), [Software Upload Transfer (20-15)](#para_sdi_sys_software_upload_transfer) and [Software Upload Finalize (20-16)](#para_sdi_sys_software_upload_finalize) using upload type `00` in TLV tag DFA01E. After a reboot, which is often due for system packages, the error is cleared and can no longer be retrieved.
On Titus platform the result of the last installed download package is also provided with TLV tag DFA148 (JSON encoded). Please note that the JSON string has another format as on VOS/VOS2, since this platform implements another secure installer (format despripted below). The result is stored persistently on device, thus, it can be retrieved after reboot (even multiple times). The result gets overwritten after a new download package was uploaded successfully and is pending for installation. Same commands (and same upload type `00`) are used as on VOS/VOS2.
{% hint style="info" %}
On other platforms (not mentioned above) the command is not supported. In this case SDI server returns an error response 64F9 (command not allowed).
{% endhint %}
The command can be executed for countertop, external pinpad and standalone devices. Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ------- |
| 20 | 1E | 00 | 00 | None | |
| 20 | 1E | 00 | 00 | Constructed | |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------------------------- |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ---------------------------------------------- |
| 90 | 00 | Constructed | Information about the last installation result |
| 64 | 00 | Constructed | Execution Error |
| 64 | F9 | None | Command not allowed |
| 67 | 00 | None | Message Length Error |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ------------------------------------------------------------------------------------------- |
| DFA148 | var. | M | ans |
VOS/VOS2: New API output in JSON format. Titus: Installation result (JSON format)
|
| DFA149 | var. | M | ans | VOS/VOS2: Old API output - name of the failed bundle |
| DFA151 | var. | M | ans | VOS/VOS2: Old API output - name of the failed package |
Example:
```cpp
// Command to get last installation status from secure installer
20 1E 00 00
// Response:
F0 82 01 6C DF A1 48 82 01 66 7B 22 74 69 74 6C 65 22 3A 22 49 6E 73 74 61 6C 6C 69 6E 67 2E 2E
2E 22 2C 22 64 6C 5F 69 74 65 6D 73 22 3A 5B 7B 22 65 72 72 6F 72 5F 6D 73 67 22 3A 22 53 75 63
63 65 73 73 22 2C 22 65 72 72 6F 72 5F 6E 75 6D 22 3A 30 2C 22 64 6C 6E 61 6D 65 22 3A 22 64 6C
2E 76 6F 73 2E 76 6F 73 32 2E 61 6C 74 5F 63 72 74 5F 70 61 74 63 68 2D 32 2E 30 2E 30 2D 44 45
56 2E 74 67 7A 22 7D 5D 2C 22 64 6C 6E 61 6D 65 22 3A 22 64 6C 2E 76 6F 73 2E 76 6F 73 32 2E 61
6C 74 5F 63 72 74 5F 70 61 74 63 68 2D 32 2E 30 2E 30 2D 44 45 56 2E 74 67 7A 22 2C 22 65 72 72
6F 72 5F 6E 75 6D 22 3A 30 2C 22 6C 65 76 65 6C 73 22 3A 7B 22 6C 65 76 65 6C 30 22 3A 7B 22 74
69 74 6C 65 22 3A 22 53 74 61 67 65 22 2C 22 63 75 72 72 65 6E 74 5F 69 74 65 6D 22 3A 22 45 78
74 72 61 63 74 69 6E 67 20 53 59 53 20 20 70 61 63 6B 61 67 65 73 22 2C 22 69 74 65 6D 73 5F 74
6F 74 61 6C 22 3A 38 2C 22 69 74 65 6D 73 5F 64 6F 6E 65 22 3A 37 2C 22 70 65 72 63 65 6E 74 22
3A 31 30 30 7D 7D 2C 22 65 72 72 6D 73 67 22 3A 22 49 6E 73 74 61 6C 6C 20 53 75 63 63 65 73 66
75 6C 6C 22 2C 22 65 72 72 6E 75 6D 22 3A 30 7D
```
Included TLV tags in contructed tag F0:
* VOS/VOS2: Example of found TLV tag DFA148 with installation result in JSON format
```fragment
{"title":"Installing...","dl_items":[{"error_msg":"Success","error_num":0,"dlname":"dl.vos.vos2.alt_crt_patch-2.0.0-DEV.tgz"}],"dlname":"dl.vos.vos2.alt_crt_patch-2.0.0-DEV.tgz","error_num":0,"levels":{"level0":{"title":"Stage","current_item":"Extracting SYS packages","items_total":8,"items_done":7,"percent":100}},"errmsg":"Install Succesfull","errnum":0}
```
For more details about this format and VOS/VOS2 secure installer, please refer to user guide of Verifone Secure Installer ERS.
* Titus: Example of found TLV tag DFA148 with installation result in JSON format
```fragment
{
"name": "dl.sdifw-VR1-1.2.0-cb300e0",
"version": "1.2.0",
"datetime": "2025-08-11T11:11:05Z",
"digest_algo": "sha256",
"error_msg": "Success, 2 of 2 installed",
"error_num": "0",
"contents": [
{
"digest": "90ixWpLbxN7b3f3+pQRnmZpQxqsR24wfMOtYbyeLM9Y=",
"name": "sdifw-1.2.0-cb300e0.bin",
"type": "spfw",
"error_msg": "Success",
"error_num": "0"
},
{
"digest": "tg39nvwfdUpCMxPX/F4yAwWTI7Au2vZG7IMp0ianbqE=",
"name": "sdifw-sysconfig.tar",
"type": "sysconfig",
"error_msg": "Success",
"error_num": "0"
}
]
}
```
Top level section contains the download package name as well as the overall result (attributes `error_msg` and `error_num` for all installed contents of the package). Since Titus secure installer is not able to support atomic installs (all or nothing), the overall result `error_msg` can be "Partial, 1 of 2 installed" (or similar), meaning not all contents were installed successfully. In this case, attribute `error_num` contains the error code of the last content, which installation has failed. In addition, each content has it's own additional error information (provided with its own attributes `error_msg` and `error_num` on content entry level). Please also note that top level attributes such as `name`, `version`, `datetime` and `digest_algo` are optional and only provided, if these attributes are provided by `manifest.json` in the package. The same is with other attributes in `manifest.json`, which are enhanced for future extensions.
In case of general package errors (wrong package format, wrong `manifest.json` or signature) no installation was performed at all. Therefore, command [Software Upload Finalize (20-16)](#para_sdi_sys_software_upload_finalize) will already provide the return code of Titus Secure Installer in TLV Tag DFA000 (additional error information/result code of secure installer).
#### External Button (20-20)
This command informs the SDI-Server in Headless Mode that the external button is pressed. It should be used for confirm the selection of a PIN digit in Navigator mode 2 only either on active [PED Get PIN (22-01)](#subsubsec_sdi_ped_get_pin) command where it returns with Navigator Callback '9D 10' (see [Navigator Callback (9D-XX)](#subsubsec_sdi_navigator_cb)) or if PIN entry was started in PIN polling mode with command [PED start PIN entry (22-03)](#subsubsec_sdi_ped_start_pin).
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)).
{% endhint %}
Please be aware of different response behaviour when using different protocol types:
* Protocol type D: External Button (20-20) always provides a command response. Thus, command field P2 (see below) to control behaviour for command response is always ignored. The message ID of External Button (20-20) can be arbitrary and must not equal the active command [PED Get PIN (22-01)](#subsubsec_sdi_ped_get_pin). The reason is the asynchronous PIN entry with [PED start PIN entry (22-03)](#subsubsec_sdi_ped_start_pin) couldn't be referred by message ID, since this command is finalized immediately with a command response, which makes the message ID invalid. In addition, the External Button (20-20) might be provided on another connection than the one started the PIN entry. For instance, this is required on Android, where PIN entry is stared by ARRS, but payment application wants to use External Button (20-20), thus, it cannot access connection from ARRS to SDI and has no knowledge about message IDs used there.
* Protocol type B: If External Button (20-20) is received during an active command, SDI does not provide a command response for it. During SDI is idle (no command active), by default a External Button (20-20) will provide a command response, either with error code '90XX' or '64FD' (meaning see below). For this case, SDI client might use command field P2 (bitmask) with bit 0x01 to control response behaviour. As already mentioned for protocol type D, the command can be send from another connection than the one started the PIN entry.
* Protocol type C: Same as for protocol type B.
* Protocol type A: Same as for protocol type B.
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ---------------------------- |
| 20 | 20 | 00 | XX | None | for XX see description below |
Meaning of P2 command field (bitmask, for protocol type A/B only):
* `00`: Send a response, if no command is active (default)
* `01`: Suppress response, if no command is active
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ---------------------------------------------------------- |
| 9D | 10 | None | Selection confirmed (Navigator Callback) |
| 90 | 00 | None | Selection confirmed (PIN polling mode) |
| 64 | FD | None | No PIN entry with navigator mode 2 is active (logic error) |
{% hint style="info" %}
This command is not supported on EPP.
{% endhint %}
#### Enable EPP (20-21)
This command enables or disables a connected EPP. If an EPP is connected it can be enabled or disabled via this command. After startup of the SDI-Server usage of the EPP is disabled per default. If EPP couldn't be enabled the response '69 00' (EPP connection error) is returned providing additional EPP connection status information with TLV tag `DFA000`. If Countertop has established a secure TLS connection and is able to communicate with EPP, but another higher-level error occured (e.g. version mismatch), EPP is operated in a restricted mode.
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ----------- |
| 20 | 21 | 00 | 00 | None | Enable EPP |
| 20 | 21 | 00 | 01 | None | Disable EPP |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ------------------------------------------ |
| 90 | 00 | None | All OK |
| 69 | 00 | Constructed | EPP connection error (only for Enable EPP) |
| 64 | FE | None | Parameter error |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | --------------------- |
| DFA000 | 4 | M | b | EPP connection status |
In case of EPP connection error the following values are returned with TLV tag `DFA000` (EPP connection status):
| Value | EPP connection status |
| ---------- | ----------------------------------------------------------------------- |
| `00000000` | EPP is disconnected |
| `00000001` | EPP Sponsor Id mismatch (EPP sponsor != Countertop sponsor) |
| `00000002` | EPP Exchange of certificates failed |
| `00000003` | EPP EMV configuration problem |
| `00000004` | EPP NFC configuration problem |
| `00000005` | EPP SDI configuration problem |
| `00000006` | TCP/TLS handshake with EPP failed |
| `00000007` | SDI version mismatch (EPP version != Countertop version) |
| `00000008` | EMV-CT framework version mismatch (EPP version != Countertop version) |
| `00000009` | EMV-CTLS framework version mismatch (EPP version != Countertop version) |
For error codes `00000000` (EPP is disconnected) and `00000006` (TCP/TLS handshake with EPP failed) there is no active TLS connection between Countertop and EPP, therefore, both devices are not able to communicate at all. For other error codes Countertop operates the EPP in a restricted mode, which allows the following commands only:
* [Software Upload Start (20-14)](#para_sdi_sys_software_upload_start), [Software Upload Transfer (20-15)](#para_sdi_sys_software_upload_transfer) and [Software Upload Finalize (20-16)](#para_sdi_sys_software_upload_finalize) (software update commands)
* [Get Property (20-1A)](#subsubsec_sdi_sys_get_property)
* [Get SDI version info (20-1C)](#subsubsec_sdi_sys_get_version_info)
* [Factory Reset (20-22)](#subsubsec_sdi_sys_factory_reset)
With activation of the EPP restricted mode the user will be noticed with an appropriate error message on the EPP display.
{% hint style="info" %}
A version mismatch error is caused when major and minor version of SDI-Server, EMV-CT and EMV-CTLS Framework version are not equal.
{% endhint %}
#### Factory Reset (20-22)
This command resets SDI server to factory defaults.
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)). If a SDI command on another connection is active, Factory Reset (20-22) is declined with response code '640A' (busy). In addition, during processing the command, SDI server will decline all SDI commands with response code '640A' (busy).
{% endhint %}
As first step SDI server deletes all files, which were created during runtime to write data persistently. This also includes files of other ADK components such as writable ADKEMV configuration files or ADKCOM related settings changeable in communication menu with SDI standard mode. As next step SDI server restores default settings and does an internal reinitialization. This reinitialization affects all active connection being closed, after SDI server has sent response '90 00' for Factory Reset command. Finally, SDI communication interface is reopened according communication default settings. In addition, the communication menu is displayed to select a communication method, if it runs in SDI standard mode without configuration default file [COM\_IF.CFG](#sec_sdi_com_if_cfg) (see chapter [Getting Started](#sec_sdi_getting_started) for more details).
{% hint style="info" %}
Default settings of SDI server can be overloaded with the installation of user config packages (see chapters [User config package](#vos_user_config_package) for Fusion/Engage and [User config package](#android_user_config_package) for Android). Please note that these external user configuration files are considered for default settings recovery. Thus, SDI server will always prefer files coming along with user config packages. Finally, if there is no external user configuration file, SDI server will recover the internal configuration file as default. If an EPP is connected, the Factory Reset is automatically forwarded to this device. After successful execution by EPP, the CT will perform the local Factory Reset. So far, no additional option is provided to perform a Factory Reset for EPP only. Factory Reset will send trigger `SDITrigger_FactoryReset` to all loaded SDI plugins, which support this trigger (see chapter [Plugin Interface (26-XX)](#subsec_sdi_plugin_interface)). Those plugins, which create persistent data (e.g. files) during runtime, should implement this trigger to support the reset to factory defaults. On Android, the factory data reset is provided by the Android OS (Android FDR), therefore, applications usually need not use command Factory Reset. Command Factory Reset is sent by the Anrdoid Secure Installer after device reboot, which is triggered by the Android FDR. The Android FDR wipes all data files in the application domain folder of the SDI service (`/data/data/com.verifone.sdi`), which do not belong the [SDI base package](#android_sdi_base_package) (APK). In order to align the same behavior as on Engage, which keeps the installed user configuration packages and SDI plugins after the Factory Reset, the SDI service will store a backup copy of the package files to the persistent partition (`/persist/appdata/sdi`), whenever a [User config package](#android_user_config_package) or [SDI plugin package](#android_sdi_plugin_package) is installed. These backup copies are recovered with command Factory Reset to reinstall the previous installed user configuration files and SDI plugins to the application domain folder of SDI service. Of cource, the installation of a [User config removal package](#android_user_config_removal_package) or a [SDI plugin removal package](#android_sdi_plugin_removal_package) will remove the back files from persistent partition again so that they are no longer considered for the recovery with command Factory Reset.
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ------- |
| 20 | 22 | 00 | 00 | None | |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | --------------------------------------------- |
| 90 | 00 | None | All OK |
| 64 | 00 | None | Execution Error, Factory Reset aborted/failed |
| 64 | 0A | None | SDI-Server is busy |
#### Read Keystore Certificate (20-23)
Read the X.509 certificate for a specified certificate reference name (user friendly label). For platforms with K81 security processor (e.g. Android, VOS3) the certificate is read from security processor's keystore. The certificate is returned in binary DER format.
{% hint style="info" %}
This command is supported as side command with protocol type D (see [Protocol Type D: Concurrent command support](#subsubsec_prot_d_concurrent_command_support)) and for a side connection with protocol type C (see [Protocol Type C: Multi connection support](#subsubsec_prot_c_multi_connection_support)).
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 20 | 23 | 00 | 00 | Constructed |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------- |
| DFA500 | var. | M | ans | Certificate reference name |
The certificate to be read is specified by a certificate reference name (in TLV tag DFA500) as follows:
| Ccertificate description | Certificate reference name | Supported platform |
| -------------------------------------- | ----------------------------------- | -------------------------------------------- |
| VFI AuthEx RSA certificate | `VFI_AUTHN_RSA` (friendly label) | VOS3, Android (Trinity, Neo), Engage, Fusion |
| VFI remote key loading RSA certificate | `VFI_VRK_RSA` (friendly label) | Android (Trinity), Engage, Fusion |
| VFI remote key loading ECC certificate | `VFI_VRK_ECC` (friendly label) | VOS3, Android (Trinity, Neo), Engage, Fusion |
| VFI device pairing RSA certificate | `VFI_PAIRING_RSA` (friendly label) | VOS3, Android (Trinity, Neo), Engage, Fusion |
| Any certificate | `` (hex string) | VOS3, Android (Trinity, Neo) |
| Any certificate | `CN` (subject common name) | VOS3, Android (Neo) |
| Any certificate (customer loaded) | `[usr[X]/]` | Engage, Fusion |
{% hint style="info" %}
Used certificate reference names depend on platform. On VOS3 and Android (Trinity, Neo) platform the certificate reference name is forwarded to K81 API function, thus, it can be used to read all certificates stored in the K81 keystore. Usually, the certificate serial number (hex string) is used to refer the corresponding certificate (e.g. use `65C95907166F14DA` to read certificate with subject `CN=VFI Dev Root CA`). Further, VOS3 and Neo platfrom also allow to use the subject `CN` to read a certificate. Other platforms (Fusion/Engage) support user friendly labels only (e.g. `VFI_AUTHN_RSA` as introduced with Android). Customer loaded certificates can be looked up by user prefix plus key label. For more details please refer to chapter [Remote Keyservice (72-XX)](#subsec_sdi_remote_keyservice).
{% endhint %}
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | -------------------- |
| 90 | 00 | Constructed | SUCCESS |
| 62 | 00 | None | Tag Error |
| 64 | 00 | None | Execution Error |
| 64 | FE | None | Parameter Error |
| 67 | 00 | None | Message Length Error |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ----------------------------- |
| DFA501 | var. | M | b | Certificate data (DER format) |
The following SW1/SW2 are returned in response:
| SW1/SW2 | Description |
| ------- | ------------------------------------------------------ |
| 90 00 | Success |
| 62 00 | Mandatory tag missing (reference name) |
| 64 FE | Parameter error (reference name not supported) |
| 64 00 | Execution error (certificate not installed or invalid) |
{% hint style="info" %}
Both primitive data tags DFA500 and DFA501 are always added to contructed container tag F0.
{% endhint %}
#### Force Currency Abbreviation (20-24)
By default, the SDI server uses the following currency symbols instead of the corresponding ISO-4217 abbreviations:
| Currency | Symbol | ISO-4217 |
| -------- | ------ | -------- |
| 376 | ₪ | ILS |
| 388 | JM$ | JMD |
| 826 | £ | GBP |
| 840 | $ | USD |
| 978 | € | EUR |
This command can be used to change the behavior when displaying a currency (e.g. to use USD instead of $). The configuration is stored persistant inside the SDI datastore and it is not necessery a resend it before each transaction.
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ----------------------------- |
| 20 | 24 | 00 | 01 | Constructed | Force Currency Abbreviation |
| 20 | 24 | 00 | 00 | Constructed | Use Currency Symbol (default) |
Command Data:
| Tag | Size | M/O | Format | Description |
| ---- | ---- | --- | ------ | -------------------------------------------------- |
| 5F2A | 2 | M | n | Currency for which the behaviour should be changed |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | -------------------- |
| 90 | 00 | None | All OK |
| 62 | 00 | None | Tag error |
| 64 | FE | None | Parameter error |
| 67 | 00 | None | Message Length Error |
{% hint style="info" %}
For TLV tag 5F2A the hexadecimal value of the currency is expected (e.g. 0x0840 for USD).
{% endhint %}
#### Get Statistic Counters (20-25)
Command to get the current values of all statistic counters stored in the device.
{% hint style="info" %}
This command is only supported on VOS3 and Android (Neo) platforms. This command is restricted to trusted connections. It is rejected with SW `64 F9` (command not allowed) on untrusted connections.
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ------- |
| 20 | 25 | 00 | 00 | None | |
| 20 | 25 | 00 | 00 | Constructed | |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------------------------- |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ---------------------------------------------------- |
| 90 | 00 | Constructed | All OK |
| 62 | 00 | None | Tag error |
| 69 | 00 | None | EPP connection error |
| 69 | 82 | None | Security Status Not Satisfied (untrusted connection) |
| 6D | 00 | None | Unknown Instruction |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ----------------------------------------- |
| DFBC06 | var. | M | ans | Current statistic counters in JSON format |
### MSR Interface (21-XX)
#### MSR Read (21-01)
Command to read MSR track data.
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ------------------------------------------------------------------------------------------------ |
| 21 | 01 | SC | NN | None |
P2 indicates the timeout as multiple of 500ms. The value FF indicates maximum timeout.
|
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DFA01B | 1 | O | b | Timer multiplier flag: 01 means that the timeout value (P2) will be multiplied with 10. Other values will be ignored |
| DFA153 | 2 | O | b | Card Removal Timeout in milliseconds (for UX devices only). It means the maximum time between starting of card removal until card is completely removed. |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ------------------------------------------------------------ |
| 90 | 00 | Constructed | All OK |
| 64 | 00 | None | Execution Error |
| 64 | F6 | None | MSR data not available Timeout reached (for UX devices only) |
| 64 | F7 | None | Card Removal Timeout reached (for UX devices only) |
| 65 | 00 | None | Execution Aborted |
| 66 | 00 | None | Execution Timeout |
| 67 | 00 | None | Message Length Error |
Response Data:
\[TABLE]
The sensitive card data will be delivered by [getEncData (29-00)](#subsubsec_sdi_getencdata) in case of VCL is disabled or by [fetchTrxTags (29-02)](#subsubsec_sdi_fetchtrxtags) when VCL is active.
{% hint style="info" %}
\[unsupported block]
{% endhint %}
#### MSR Card Data Entry (21-02)
Command to enter card data manual.
In Headless mode on touch only devices the additional Tag DFA024 including the touch coordinates is needed.
For a better user interaction in headless mode the SDI-Server performs the following additional handling with the outside application:
* During the command execution in Headless mode some Status callbacks (see [Status Callback (9F-XX)](#subsubsec_sdi_status_cb)) will be sent to inform the outside application about the number of entered digits to update the display content.
* Further there will be Status callbacks if the customer presses the confirmation button but data are not completely entered or if he tries to enter more digits if the maximum number of digits is reached.
* In case of a PAN entry the additional Tag (DFA009) containing the Headless Entry String (e.g. "123456\*\*\*\*") will be sent within the Status Callback.
* When the minimum number of PAN digits is entered and the confirm button is pressed the Status Callback 9FFE will be sent including the obfuscated PAN in Tag DFA009. Here the user has two possibilities:
* Correction of the entered PAN with Backspace (one key press per digit) and reenter of digits. The Status callback will behave as described. Also the Enter key.
* Confirmation of the enterd PAN by pressing the Enter key once again.
* In case of Expiry date entry the SDI-Server checks if a valid date was entered. If not a Status callback (9FFD) will be sent and the expiry date must be reentered.
* After the PAN or Expiry date is entered completely the SDI-Server performs a validation check based on the card range table (see [cardranges.json](#sec_sdi_cardranges_json)) and sends a Control request ([Control Request (9B-01)](#subsubsec_sdi_control_req)) to the outside application. Depending on the request response (Continue, Reenter or Abort) the SDI-Server performs the next step to enter the card data or cancels the entry.
* To handle special none payment cards without having an expiry date and activated VCL feature additional parameters "defaultExpiryDate" and "skipCvv" have been introduced to the card ranges table. Now it is possible to configure a default expiry date for a special card range which will be used for VCL encryption. To use this feature the tag DFA017 should not be set. If the SDI-Server finds a "defaultExpiryDate" after the PAN is successfully entered, the manual card entry is stopped and this date is used to encrypt the data with VCL. When VCL is not activated the SDI-Server will stop the entry as well and will return this date in clear text if requested by a following [fetchTrxTags (29-02)](#subsubsec_sdi_fetchtrxtags) command.
Depending on the security configuration (ADE, VCL, ...) the sensitive data (PAN, Expiry Date and/or CVV) will be delivered by using the [fetchTrxTags (29-02)](#subsubsec_sdi_fetchtrxtags) command in case of VCL or the [getEncData (29-00)](#subsubsec_sdi_getencdata) command.
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 21 | 02 | SC | 00 | Constructed |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DFA008 | 1 | O | b | Text Language, default is current terminal/transaction language (see [Supported System Languages](#subsec_sdi_supported_system_languages)) |
| DFA005 | 2 | O | b | Timeout in seconds (MSB, LSB): Max value 0xFFFF (65535) seconds. If no timeout is set or the value is set to 0, the default value of 300 seconds is used. |
| DFA017 | 1 | O | b | Temporary Card Entry Value Deactivation during the current command execution. For details see [System Tags](#subsubsec_sdi_system_tags) |
| DFA018 | 1 | O | b |
Card Data Entry Mode, valid values: 00: Card Data Entry performed in one screen 01: Card Data Entry performed in separate screens
|
| DFA01A | 5..6 | O | ans | Alternative Input Format String (optional) for CVV |
| DFA024 | var. | O | an |
Touch coordinates for the provided keypad layout. Needs to be added for each key. Format: xxxxyyyywwwwhhhhaa, xxxx: x-Position of a touch button, yyyy: y-Position of a touch button, wwww: width of a touch button, hhhh: heigth of a touch button, aa: associated key (ASCII), 1B = Cancel, 08 = Correction, 0D = Enter, 0E = F1, 0F = F2, 10 = F3, 11 = F4
|
| DFA162 | 1 | O | b | Minimum Pan length in range of 7 to 19 (default: 10). A value smaller than 7 or larger than the maximum Pan Length (DFA163) is invalid. |
| DFA163 | 1 | O | b | Maximum Pan length in range of 7 to 19 (default: 19). A value larger than 19 or smaller than the minimum Pan Length (DFA162) is invalid. |
| DFA123 | 1 | O | b |
Force minimum number of Pan digits to 7 instead the default of 10. Valid values: 00: Use default (10 digits) 01: Force to 7 digits. Hint: This parameter overwrites the minimum Pan length (Tag DFA162)!
|
| DFA033 | 1 | O | b |
Skip double confirmation of PAN in headless mode 00 = Double confirmation active (default) 01 = Double Confirmation skipped
|
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | -------------------- |
| 90 | 00 | Constructed | All OK |
| 90 | 70 | Constructed | CVV bypassed |
| 64 | 00 | None | Execution Error |
| 64 | 05 | None | Canceled by user |
| 64 | FD | None | Logic Error |
| 64 | FE | None | Parameter Error |
| 65 | 00 | None | Execution Aborted |
| 66 | 00 | None | Execution Timeout |
| 67 | 00 | None | Message Length Error |
Response Data:
\[TABLE]
The sensitive card data will be delivered by [getEncData (29-00)](#subsubsec_sdi_getencdata) in case of VCL is disabled or by [fetchTrxTags (29-02)](#subsubsec_sdi_fetchtrxtags) when VCL is active.
{% hint style="info" %}
\[unsupported block]
{% endhint %}
#### MSR Set Options (21-03)
Command to set the MSR options. For details see [MSR\_SetOptions()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#ac3c6f568aa57690a8b369936fc362c2a).
The MSR options are passed in TLV tag `DFA026` and applied to subsequent MSR read operations for the recent terminal runtime.
{% hint style="info" %}
Terminal reboot will recover default MSR options. This function has to be called while MSR is deactivated. If an asynchronous card detection was started with [Start Card Detection (23-03)](#subsubsec_sdi_start_card_detection) and card technology `02` (magnetic stripe), it will activate the MSR reader. During this active detection the MSR Set Options (21-03) is blocked and declined with a `6400` response.
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 21 | 03 | SC | 00 | Constructed |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ----------- |
| DFA026 | var. | M | b | MSR options |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ------------------------------------------------------------- |
| 90 | 00 | None | All OK |
| 62 | 00 | None | Tag Error |
| 64 | 00 | Constructed | Execution Error (additional MSR error code in TLV tag DFA000) |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | --------------------------------------- |
| DFA000 | 4 | O | b | MSR error code (additional result code) |
{% hint style="info" %}
\[unsupported block]
{% endhint %}
#### MSR Switch LEDs (21-04)
Command to switch the MSR LEDs. This command has an effect on devices equipped with MSR LEDs only. For details see [MSR\_SwitchLeds()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#abca7e8953c8430d80f51c867c7699fa6).
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 21 | 04 | SC | 00 | Constructed |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ------------------------------------------------------------------------ |
| DFA027 | ..4 | M | b | LED 1 state |
| DFA028 | ..4 | M | b | LED 2 state |
| DFA029 | ..4 | M | b | LED 3 state |
| DFA02A | ..4 | O | b | Lighting duration in seconds. All LEDs are switched off after this time. |
Response
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | --------------- |
| 90 | 00 | None | All OK |
| 62 | 00 | None | Tag Error |
| 64 | 00 | Constructed | Execution Error |
{% hint style="info" %}
\[unsupported block]
{% endhint %}
#### MSR Set Sensitivity (21-05)
Command to set the MSR sensitivity level for the magnetic head to amplify or damp incoming signals of the swiped MSR card. The sensitivity level is passed in TLV tag `DFA039` (MSR sensitivity level) and applied to subsequent MSR read operations for the recent terminal runtime. Basically, it is recommended to use default MSR sensitivity to get best MSR reading results. Once MSR Set Sensitivity (21-05) is used with another value than the default, it is recommended to recover default sensitivity as soon as possible.
{% hint style="info" %}
Please note that this API is supported on Android (Trinity/Neo) and VOS3 platform only. On other platforms SDI will reject the command with response `6D00` (unknown instruction). Terminal reboot will recover default MSR sensitivity. This function has to be called while MSR is deactivated. If an asynchronous card detection was started with [Start Card Detection (23-03)](#subsubsec_sdi_start_card_detection) and card technology `02` (magnetic stripe), it will activate the MSR reader. During this active detection the MSR Set Sensitivity (21-05) is blocked and declined with a `6400` response.
{% endhint %}
Command:
| | | | | |
| --- | --- | -- | -- | ----------- |
| CLA | INS | P1 | P2 | Data |
| 21 | 05 | SC | 00 | Constructed |
Command Data:
| | | | | |
| ------ | ---- | --- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tag | Size | M/O | Format | Description |
| DFA039 | 1 | M | b |
MSR sensitivity level Valid value range is : 20..200 (0 is used for default MSR sensitivity) Values >100 will increase MSR sensitivity and amplify signals. Values <100 will decrease MSR sensitivity and damp signals. Value 100 means no amplification/damping. Value 0 will reset to default MSR sensitivity.
|
| DFA150 | 1 | O | b | Command destination: `01` = Countertop (default), `02` = EPP |
Response:
| | | | |
| --- | --- | ----------- | ------------------------------------------------------------- |
| SW1 | SW2 | Data | Comment |
| 90 | 00 | None | All OK |
| 62 | 00 | None | Tag Error |
| 64 | 00 | Constructed | Execution Error (additional MSR error code in TLV tag DFA000) |
| 64 | FE | None | Parameter Error |
| 67 | 00 | None | Message Length Error |
Response Data:
| | | | | |
| ------ | ---- | --- | ------ | --------------------------------------- |
| Tag | Size | M/O | Format | Description |
| DFA000 | 4 | O | b | MSR error code (additional result code) |
{% hint style="info" %}
\[unsupported block]
{% endhint %}
### Smard Card Interface (41/42-XX)
This chapter describes the EMV Smart Card Interface. Details about the constructed data elements are described in the linked EMV documentation (see table below).
| Contact (CT) | Contactless (CTLS) |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 41 01: [EMV\_CT\_SmartDetect()](/s-adk-5.1-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 02: [EMV\_CT\_SmartReset()](/s-adk-5.1-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) | 42 02: [EMV\_CTLS\_SmartReset()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___i_c_c___i_f___c_t_l_s/group___f_u_n_c___i_c_c___c_t_l_s.md#gae2c93f30f24ceb94c930a7cae2b36116) |
| 41 03: [EMV\_CT\_SmartISO()](/s-adk-5.1-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) | 42 03: [EMV\_CTLS\_SmartISO()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___i_c_c___i_f___c_t_l_s/group___f_u_n_c___i_c_c___c_t_l_s.md#gafbcdb0278723b9629eb7c12532119e2d) |
| 41 04: [EMV\_CT\_SmartPowerOff()](/s-adk-5.1-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) | 42 04: [EMV\_CTLS\_SmartPowerOff()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___i_c_c___i_f___c_t_l_s/group___f_u_n_c___i_c_c___c_t_l_s.md#gadd0716253a50b2791ac4e2a1627d1e8d) |
| 41 09: [EMV\_CT\_LED()](/s-adk-5.1-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#gaa7a875eed1a49cff8fdf70c81100be2f) | |
| | 42 0A: [EMV\_CTLS\_CardRemoval()](/s-adk-5.1-programmers-guide/readme/modules/group___a_d_k___t_r_x___e_x_e_c___c_t_l_s/group___f_u_n_c___f_l_o_w___c_t_l_s.md#gaf9ca19bc9d77bfe1dfec28c030b18059) |
#### Smart Card Detect (41-01)
This command handles the Smart Card Detection. It can be used for both a card request and a card removal. In case of card request the SDI-Server waits for the card insertion until the timeout is elapsed. For a card removal check the command has to be used in a loop with timeout 0.
Command
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ------------------------------------------------------------------------------------------------ |
| 41 | 01 | SC | NN | None |
P2 indicates the timeout as multiple of 500ms. The value FF indicates maximum timeout.
|
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ----------------------------------------------------------------------------------------------------------- |
| DFA01B | 1 | O | b | Timer multiplier flag: 01 = The timeout value (P2) will be multiplied with 10. Other values will be ignored |
Response
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------------- |
| 90 | 00 | None | Card inserted |
| 94 | 01 | None | Card removed |
{% hint style="info" %}
\[unsupported block]
{% endhint %}
#### Smart Card Activate (41/42-02)
Command to activate a Smart Card for CT (41) or CTLS (42).
Command
| CLA | INS | P1 | P2 | Data |
| ----- | --- | -- | -- | ----------- |
| 41/42 | 02 | SC | 00 | Constructed |
Command Data:
| Tag | Size | M/O | Format | Description |
| ---- | ---- | --- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DF06 | 1 | O | b | see [EMV\_CT\_SmartReset()](/s-adk-5.1-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)/EMV\_CTLS\_SmartReset() options |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ------- |
| 90 | 00 | Constructed | All OK |
Response Data
| Tag | Size | M/O | Format | Description |
| ---- | ---- | --- | ------ | ----------- |
| DF68 | var. | O | b | ATR |
{% hint style="info" %}
\[unsupported block]
{% endhint %}
#### Smart Card Exchange APDU (41/42-03)
This command allows it to perform a Smart Card APDU for CT (41) or CTLS (42).
Command
| CLA | INS | P1 | P2 | Data |
| ----- | --- | -- | -- | ----------- |
| 41/42 | 03 | SC | 00 | Constructed |
Command Data
| Tag | Size | M/O | Format | Description |
| ---- | ---- | --- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DF06 | 1 | O | b | see [EMV\_CT\_SmartISO()](/s-adk-5.1-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)/EMV\_CTLS\_SmartISO() options |
| DF01 | var. | M | b | Command APDU |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ------- |
| 90 | 00 | Constructed | All OK |
Response Data
| Tag | Size | M/O | Format | Description |
| ---- | ---- | --- | ------ | ------------- |
| DF01 | var. | O | b | Response APDU |
{% hint style="info" %}
\[unsupported block]
{% endhint %}
#### Smart Card Deactivate (41/42-04)
Command to deactivate a Smart Card for CT (41) or CTLS (42).
Command
| CLA | INS | P1 | P2 | Data |
| ----- | --- | -- | -- | ----------- |
| 41/42 | 04 | SC | 00 | Constructed |
Command Data:
| Tag | Size | M/O | Format | Description |
| ---- | ---- | --- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DF06 | 1 | O | b | see [EMV\_CT\_SmartPowerOff()](/s-adk-5.1-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)/EMV\_CTLS\_SmartPowerOff() options |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------- |
| 90 | 00 | None | All OK |
{% hint style="info" %}
In the two piece solution the 41-04 command will be executed on the Countertop or the EPP depending on the stored reader during the [Smart Card Detect (41-01)](#subsubsec_sdi_smart_card_detect) command.
{% endhint %}
### Card Detect Interface (23-XX)
The Card Detect Interface is a single interface for all three card technologies Magnetic Stripe, Smart Card and Contactless Card (CTLS).
#### Card Detection (23-01)
Detect Mag Stripe Read, Smart Card Insertion, Contactless Card or Manual Card Data Entry depending on the value of tag DFA108.
Command
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ----------------------- |
| 23 | 01 | SC | NN | None | All technologies active |
| 23 | 01 | SC | NN | Constructed | |
{% hint style="info" %}
\[unsupported block]
{% endhint %}
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DFA108 | 1 | M | b |
|
| DFA109 | 1 | O | b | Set to 01 to allow that card detection can be stopped by an asynchronous dialog, which was started previously (see [Handle Display (24-03)](#subsubsec_sdi_handle_display)). If this dialog finishes with arbitrary UI error (except `UI_ERR_BACK`, clear key reserved for Manual Card Data Entry), command Card Detection (23-01) returns response `6405` (Canceled by user). Result of the asynchronous dialog can be read with [Get Async Display Result (24-0B)](#subsubsec_sdi_get_async_display_result) afterwards. |
| DFA12A | var. | O | b | Card Technology selection options (for details see: [cts\_StartSelection()](/s-adk-5.1-programmers-guide/readme/files/dir_c2b6fb90cbe225a4c7f5c562006e9b78/dir_797c2eec9d33c0e51d543580c2b239ca/dir_fa87c044aa590573d847d8ba2d3b48c1/tec_8h.md#ac6699fe32fc23e90713eb617e9ff25e7)) |
| DFA01B | 1 | O | b |
Timer multiplier flag (optional): 01: The timeout value (P2) will be multiplied with 10. FF: Combined with FF as value for P2 the maximal timeout for card detection is applied, which means 65535 seconds (\~18 hours). Other values for TLV tag DFA01B will be ignored and value of P2 is considered for timeout only.
|
| DFA017 | 1 | O | b | Temporary Card Entry Value Deactivation during the current command execution. For details see [System Tags](#subsubsec_sdi_system_tags) |
| DFA01A | var. | O | ans | Alternative Input Format String (optional for CVV during Manual Card Data Entry) |
| DFA133 | var. | O | b | Additional options for technology selection, used for the [cts\_SetOptions()](/s-adk-5.1-programmers-guide/readme/files/dir_c2b6fb90cbe225a4c7f5c562006e9b78/dir_797c2eec9d33c0e51d543580c2b239ca/dir_fa87c044aa590573d847d8ba2d3b48c1/tec_8h.md#aa237be1f0249503d0b959d3800f1ee34) function (eg: to set the App ID for VAS transactions) |
| DFA153 | 2 | O | b | Card Removal Timeout in milliseconds (for UX devices only). It means the maximum time between starting of card removal until card is completely removed. |
{% hint style="info" %}
\[unsupported block]
{% endhint %}
Response
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | --------------------------------------------------------------- |
| 90 | 00 | Constructed | All OK |
| 90 | D8 | None | Command not allowed (EMV CTLS) |
| 90 | E6 | None | User abort during PIN input (EMV CT) |
| 62 | 00 | None | Tag Error |
| 64 | 00 | None | Execution Error |
| 64 | 05 | None | Canceled by user |
| 64 | F4 | None | ADK-EMV has detected no medium to perform a contactless payment |
| 64 | F6 | None | MSR data not available Timeout reached (for UX devices only) |
| 64 | F7 | None | Card Removal Timeout reached (for UX devices only) |
| 64 | FD | None | Logic Error |
| 65 | 00 | None | Execution Aborted |
| 66 | 00 | None | Execution Timeout |
Response Data:
\[TABLE]
The sensitive card data will be delivered by [getEncData (29-00)](#subsubsec_sdi_getencdata) in case of VCL is disabled or by [fetchTrxTags (29-02)](#subsubsec_sdi_fetchtrxtags) when VCL is active.
Operation:
* The value of P2 indicates the timeout for selecting a card technology as multiple of 500ms. The value FF indicates maximum timeout. It is recommended to use a sufficiently large value in order to avoid unnecessary timeouts.
* The read loop will end on card read, System Abort Command or Timeout. No new command can be processed until this command is complete.
* All relevant tags of the MSR Card Data Entry command are optional and will be used in case of Manual Card data entry is selected. In that case the data entry is performed and the relevant response data tags will be returned (see [MSR Card Data Entry (21-02)](#subsubsec_sdi_msr_card_data_entry)).
{% hint style="info" %}
\[unsupported block]
{% endhint %}
#### Wait Card Removal (23-02)
Command to wait until the card is removed (Only for Contact)
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 23 | 02 | SC | 00 | Constructed |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ----------------------------------------------------------- |
| DFA005 | 2 | O | b | Card removal timeout in seconds (MSB, LSB). Default is 0000 |
Response:
| SW1 | SW2 | Data | Description |
| --- | --- | ---- | ---------------------------------------- |
| 90 | 00 | None | Card has been removed |
| 64 | 00 | None | Error |
| 64 | FD | None | Command not allowed for the moment |
| 64 | 05 | None | Canceled by user (async. dialog) |
| 66 | 00 | None | Timeout reached but card not yet removed |
{% hint style="info" %}
In the two piece solution this command will be executed on the Countertop or the EPP depending on the stored reader during the [Card Detection (23-01)](#subsubsec_sdi_card_detection) command.
{% endhint %}
#### Start Card Detection (23-03)
Asynchronous command to detect Mag Stripe Read, Smart Card Insertion or Contactless Card depending on the value of tag DFA108. Unlike (23-01) this command does not block until a card is detected, but returns immediately with the detection status. Technology result is to be fetched using the Poll Card Detection command or alternatively through a callback message. Callback message is to be enabled by setting tag DFA10B to 01. Manual Card Data Entry is currently not supported. If started in callback mode, a callback message [Card Detected Callback (9E-02)](#subsubsec_sdi_card_detected_cb) will be sent to the application to signalize the detection result as soon as a result is available. The EMV query callbacks will be sent as One Way [EMV Callback after the asychronous Card Detection (9E-03)](#subsubsec_sdi_emv_async_card_detection_cb) in callback and polling mode.
{% hint style="info" %}
During card detection several commands are not allowed in order to avoid unexpected behavior due to conflicting access to SDI resources. Following commands are blocked with return code 64-F9: MSR interface 21-xx, EMV Smart Contact and Smart Contactless interfaces (41-xx and 42-xx) and NFC and VAS interface (31-xx and 32-xx). It's recommended not to use time consuming commands such as blocking display commands or similar during asynchronous card detection, as this will disturb the polling procedure or the intime reception of the card detected callback.
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ----------------------- |
| 23 | 03 | SC | 00 | None | All technologies active |
| 23 | 03 | SC | 00 | Constructed | |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DFA108 | 1 | M | b |
|
| DFA12A | var. | O | b | Card Technology selection options (for details see: [cts\_StartSelection()](/s-adk-5.1-programmers-guide/readme/files/dir_c2b6fb90cbe225a4c7f5c562006e9b78/dir_797c2eec9d33c0e51d543580c2b239ca/dir_fa87c044aa590573d847d8ba2d3b48c1/tec_8h.md#ac6699fe32fc23e90713eb617e9ff25e7)) |
| DFA133 | var. | O | b | Additional options for technology selection, used for the [cts\_SetOptions()](/s-adk-5.1-programmers-guide/readme/files/dir_c2b6fb90cbe225a4c7f5c562006e9b78/dir_797c2eec9d33c0e51d543580c2b239ca/dir_fa87c044aa590573d847d8ba2d3b48c1/tec_8h.md#aa237be1f0249503d0b959d3800f1ee34) function (eg: to set the App ID for VAS transactions) |
| DFA005 | 2 | O | b |
Timeout in seconds (MSB, LSB): 0000 = No timeout (default to 30dec seconds) In polling mode the timeout value is fix set to maximum value of 65535 seconds (\~ 18 hours)
|
| DFA10B | 1 | O | b | Card detection response mode. 00: using Poll Card Detection command (default), 01: using callback message |
| DFA153 | 2 | O | b | Card Removal Timeout in milliseconds (for UX devices only). It means the maximum time between starting of card removal until card is completely removed. |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | --------------------------------------- |
| 90 | 00 | None | All OK, card detection in progress |
| 90 | E6 | None | Invalid technology selection parameters |
| 62 | 00 | None | TLV import failed |
| 64 | 00 | None | Execution Error |
| 64 | F9 | None | Command not allowed |
| 64 | FD | None | Logic error, detection already running |
| 64 | FE | None | Parameter error |
#### Poll Card Detection (23-04)
Polls for the result of card detection started with the 23-03 command.
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ------- |
| 23 | 04 | SC | 00 | None | |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ------------------------------------------------------------------------------------------------- |
| 90 | 00 | Constructed | All OK, check DFA108 for result. 00 means in progress |
| 90 | D8 | None | CTLS in actual state not allowed |
| 64 | 00 | None | Execution error |
| 64 | 05 | None | Canceled by user (through Stop Card Detection command) |
| 64 | F4 | None | ADK-EMV has detected no medium to perform a contactless payment |
| 64 | F6 | None | MSR data not available Timeout reached (for UX devices only) |
| 64 | F7 | None | Card Removal Timeout reached (for UX devices only) |
| 64 | F9 | None | Command not allowed |
| 64 | FD | None | Logic error, either detection has not been started or detection has been started in callback mode |
| 65 | 00 | None | Card detection aborted |
| 66 | 00 | None | Timeout reached, no card has been detected |
| 67 | 00 | None | Buffer too small |
Response Data:
\[TABLE]
{% hint style="info" %}
\[unsupported block]
{% endhint %}
#### Stop Card Detection (23-05)
Try to stop a running (23-03) Card Detection
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ---- | ------- |
| 23 | 05 | SC | 00 | None | |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ---------------------------------------------- |
| 90 | 00 | None | Stopping the card detection has been requested |
| 64 | FD | None | Logic error, detection has not been started |
{% hint style="info" %}
The Stop Card Detection command triggers the card detection to stop and returns immediately. The stopping result is communicated through the callback message or through the poll command. In case the Stop Card Detection command returned 9000, following scenarios are possible: \[unsupported block] In both cases, the callback or the poll response message can signalize either that the card detection has been stopped successfully (6405), or that it was not possible to stop because a card has already been detected. In this case (not possible to stop), 9000 will be returned together with the detected technology as described in the [Poll Card Detection (23-04)](#subsubsec_sdi_poll_card_detection) command response.
{% endhint %}
#### Add Technology (23-06)
Adds a technology to a running (23-03) Card Detection
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ------- |
| 23 | 06 | SC | 00 | Constructed | |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DFA108 | 1 | M | b |
Technology to be added (bit mask). 01: CT Smart Card 02: Magnetic stripe 04: CTLS Smart Card
|
| DFA12A | var. | O | b | Card Technology selection options (for details see: [cts\_StartSelection()](/s-adk-5.1-programmers-guide/readme/files/dir_c2b6fb90cbe225a4c7f5c562006e9b78/dir_797c2eec9d33c0e51d543580c2b239ca/dir_fa87c044aa590573d847d8ba2d3b48c1/tec_8h.md#ac6699fe32fc23e90713eb617e9ff25e7)) |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ---------------------------------------------- |
| 90 | 00 | None | All OK, technology has successfully been added |
| 62 | 00 | None | TLV import failed |
| 64 | 00 | None | Execution error |
| 64 | F9 | None | Command not allowed |
| 64 | FD | None | Logic error, detection has not been started |
#### Remove Technology (23-07)
Removes a technology from a running (23-03) Card Detection
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ------- |
| 23 | 07 | SC | 00 | Constructed | |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------------------------------------------------------------------------------- |
| DFA108 | 1 | M | b |
Technology to be removed (bit mask). 01: CT Smart Card 02: Magnetic stripe 04: CTLS Smart Card
|
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------------------------------------------------ |
| 90 | 00 | None | All OK, technology has successfully been removed |
| 62 | 00 | None | TLV import failed |
| 64 | 00 | None | Execution error |
| 64 | F9 | None | Command not allowed |
| 64 | FD | None | Logic error, detection has not been started |
{% hint style="info" %}
If the technology bitmask is empty after removing of the last technology, it is not necessary to send a Stop Card Detection command. The detection process is then stopped automatically.
{% endhint %}
#### Provide Callback Response (23-08)
Send the EMV Callback response data after a Callback Request has been received during an asynchronous Card Detection (23-03) process. If the asychronous Card Detection (23-03) has been started in callback mode, this command has to be sent after an [EMV Callback after the asychronous Card Detection (9E-03)](#subsubsec_sdi_emv_async_card_detection_cb) has been received. If the asychronous Card Detection (23-03) has been started in polling mode, this command has to be sent after the [Poll Card Detection (23-04)](#subsubsec_sdi_poll_card_detection) has received a Callback Request in the response message.
{% hint style="info" %}
Be aware that this command is expected to be received within one minute when you debug your application. In case of timeout a communication error is reported as callback response and card processing is aborted.
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data | Comment |
| --- | --- | -- | -- | ----------- | ------------------------------------------------- |
| 23 | 08 | 00 | 00 | Constructed | Callback response data as expected by the EMV ADK |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------------------------------------------------------- |
| 90 | 00 | None | All OK, callback response data communicated to EMV ADK |
| 64 | FD | None | Logic Error - Not waiting for Provide Callback Response |
### Display Interface (24-XX)
The device is equipped with a display. To use this display via the SDI protocol some display commands are defined. An additional system tag for the language id is defined to allow Multilanguage support.
{% hint style="info" %}
**In Headless mode all display commands are not supported!**
{% endhint %}
#### Display Text (24-01)
Command to display a text on the PINPad display.
{% hint style="info" %}
**This command is deprecated and should not be sent to the device! For new implementation please use command Handle Display (24-03).**
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ------------ |
| 24 | 01 | SC | 00 | Display Data |
Display Data:
| Size | Destcription |
| ---- | ------------------------------ |
| 2 | Display text length (MSB, LSB) |
| var. | Display text UTF-8 encoded |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | --------------------- |
| 90 | 00 | None | All OK |
| 64 | 00 | None | Execution Error |
| 6D | 00 | None | Command not supported |
#### Display Text with Confirmation (24-02)
Command to display a text with confirmation on the PINPad display. As confirmation keys only non-numerical keys like (Cancel, Clear or Enter) are accepted. The command can be aborted via Sys Abort (20-02) command.
{% hint style="info" %}
**This command is deprecated and should not be sent to the device! For new implementation please use command Handle Display (24-03).**
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ------------ |
| 24 | 02 | SC | 00 | Display Data |
Display Data:
| Size | Destcription |
| ---- | ------------------------------ |
| 2 | Display text length (MSB, LSB) |
| var. | Display text UTF-8 encoded |
| 2 | Timeout in seconds (MSB, LSB) |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | --------------------- |
| 90 | 00 | None | All OK |
| 64 | 00 | None | Execution Error |
| 64 | 05 | None | Canceled by user |
| 65 | 00 | None | Execution Aborted |
| 66 | 00 | None | Timeout |
| 6D | 00 | None | Command not supported |
#### Handle Display (24-03)
Command to display a dialog on screen. The dialog supports displaying pure text, with or w/o user confirmation. A flexilbe interface with dialog options (TLV tag `DFA142`) is provided to adjust behaviour and appearance of the dialog: For instance, the user has the option to add softkeys (for devices with touch) or key helpers to inform the user about which function keys to use (on devices w/o touch). Further options allow to specify the text alignment, to display an image or to enable/disable complete dialog regions (e.g. dialog header or virtual LED bar).
It's possible to display a dialog asynchronously, even if the dialog requests confirmation from the user. In this case Handle Display (24-03) returns with `9000` immediately and the result of the dialog can be stored (see option `DLG_StoreAsyncResult`). The stored result can be read with SDI command [Get Async Display Result (24-0B)](#subsubsec_sdi_get_async_display_result) afterwards.
Finally, Handle Display (24-03) also allows to use a custom HTML template, which can be installed with a [User config package](#vos_user_config_package) to external UI resource folders of SDI: VOS/VOS2:
* `/etc/config/sdi/www/x` (device specific UI resource folder, e.g. `320x480C15T` is used for P400)
* `/etc/config/sdi/www/default` (default UI resource folder, used if the resource isn't found in device specific folder)
VOS3:
* `/home/usr/sdi/www/x` (device specific UI resource folder, e.g. `320x480C15T` is used for P630)
* `/home/usr/sdi/www/default` (default UI resource folder, used if the resource isn't found in device specific folder)
The external custom HTML template file is addressed with Template Identifier (TLV tag `DFA010`) and must use the following filename notation:
```fragment
template_e_.html
```
Field `` in the template filename is the decimal value (3 digits) of Template Identifier (TLV tag `DFA010`), e.g. for Template Identifier value `02` SDI server will lookup the custom HTML template file `template_e_002.html`.
{% hint style="info" %}
Template Identifier with value `01` (default) is reserved for standard HTML dialog (see chapter [dialog.html](#pgr_dialog_html)), which is installed with the base SDI config package for standard mode. Usage of standard [dialog.html](#pgr_dialog_html) is recommended, since it implements all dialog parameters of command Handle Display (24-03), which are finally passed as variables in ADKGUI parameter map `ARGV` to the dialog (for more details see parameter description below). Thus, a custom HTML template will ignore these parameters, if related variables are not considered or implemented.
{% endhint %}
Resource files used in the custom HTML template (e.g. images) can be either referred by relativ path (if provided with the user config package) or by absolute path to SDI image folder (e.g. `/home/sys8/www/sdi/images` on VOS/VOS3) to use SDI default images. As long as no custom CSS file is provided, the SDI default CSS file is applied, which comes along with SDI config package for standard mode (see [Default UI resource files](#subsubsec_sdi_default_resource_files)). Of course, it might be useful for HTML templates to implement inline CSS to be independent from a common CSS file.
Custom HTML templates can be implemented language independed. SDI server will load the custom UI text catalog for the recent system language to invoke the dialog. Thus, HTML templates can use XML processing instruction `` in HTML to use texts from the custom catalog (for more details see chapter [Custom UI text catalogs](#subsubsec_sdi_custom_text_catalogs)).
Additional variables can be injected into custom dialogs with constructed TLV tag FFA011 (Display Data). Each tag contains a pair of primitive TLV tags `DFA012` (variable name) and `DFA013` (variable value), which are passed in ADKGUI parameter map `ARGV` to the dialog. Please ensure that a variable name in TLV tag `DFA012` doesn't conflict with variable names defined for dialog parameters in this chapter, e.g. a variable with name `key_cancel` would be overwritten by dialog option `DLG_CancelKey`.
{% hint style="info" %}
It is not possible to inject HTML with TLV tags into a HTML dialog, since SDI will substitute special HTML characters by corresponding escape references, before the TLV contents are forwarded to the dialog.
{% endhint %}
UI error codes are defined by ADKGUI header file [gui\_error.h](/s-adk-5.1-programmers-guide/readme/files/dir_9225c15707e5fd27b700c844799f6dc5/dir_7447c8e6446ba60664134d106c4ecb69/dir_8c13e55433a2f6247a8b0f337ff26c19/gui__error_8h.md), e.g. the return code `-1` stands for `UI_ERR_ABORT`. Please note that well-known UI return codes of the dialog (or template) might be mapped to SDI result code SW1/SW2, thus, `UI_ERR_ABORT` will lead to response 64 05 (see reserved UI error codes for response below). If a non-reserved UI error code is returned (e.g. `-6` for `UI_ERR_PARAMETER`), it is provided with response 6400 and TLV tag DFA000 (additional result code). It is recommended that dialogs (or templates) use well-known error codes of ADKGUI, but if there is the need to use an own range, these the return values must be positive to separate them from internal private error codes ADKGUI is using below range in [gui\_error.h](/s-adk-5.1-programmers-guide/readme/files/dir_9225c15707e5fd27b700c844799f6dc5/dir_7447c8e6446ba60664134d106c4ecb69/dir_8c13e55433a2f6247a8b0f337ff26c19/gui__error_8h.md) (for more details see ADKGUI documentation).
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 24 | 03 | SC | 00 | Constructed |
{% hint style="info" %}
Pure command `24 03 00 00` (without command data) clears the display and returns with response `9000` immediately.
{% endhint %}
Command Data:
\[TABLE]
Response:
| SW1 | SW2 | Data | Comment | Reserved UI error code |
| --- | --- | ----------- | -------------------------------------------------------------------- | ---------------------- |
| 90 | 00 | Constructed | All OK | 0 (UI\_ERR\_OK) |
| 64 | 00 | Constructed | Execution Error (UI error code in TLV tag DFA000) | |
| 64 | 05 | None | Canceled by user | -1 (UI\_ERR\_ABORT) |
| 65 | 00 | None | Execution Aborted with [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) | |
| 66 | 00 | None | Timeout | -3 (UI\_ERR\_TIMEOUT) |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------- |
| DFA000 | 4 | O | b | UI error code (additional result code) |
Examples:
```cpp
// Command to display text "Hello world"
24 03 00 00 F0 13 FF A0 11 0F DF A0 13 0B 48 65 6C 6C 6F 20 77 6F 72 6C 64
// Response
90 00
```
{% hint style="info" %}
An additional example user config package `dl.sdi-usrconfig-template_e_002-X.X.X-pre1-P2PE-X.X.X.tar` comes along in subfolder `example/load/usr_config` of SDI documentation package `sdi-doc-X.X.X-X-P2PE-X.X.X.zip`. The package contains `template_e_002.html` so that Handle Display (24-03) can be used with Template Identifier `2` to display the installed example. The dialog also demonstrates usage of 2 variables `text` and `text2`, which are provided in TLV tag FFA011 (Display Data). Appendix [UI command examples](#subsec_sdi_ui_examples) contains additional command examples demonstrating usage of Handle Display (24-03).
{% endhint %}
#### Handle Secure Input (24-04)
Command to handle a secure input on the display to request user data entry. Depending on the template, the input may be numerical (e.g. ZIP code, CVV, amounts) or alphanumeric (e.g. email address, phone number). Before displaying the addressed text the previous display content will be complete deleted.
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 24 | 04 | SC | 00 | Constructed |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| DFA007 | 1 | M | b | Input Template ID (reference to authenticated text stored inside the e-device) |
| DFA008 | 1 | O | b | Text Language, default is current terminal/transaction language (see [Supported System Languages](#subsec_sdi_supported_system_languages)) |
| DFA005 | 2 | O | b | Timeout in seconds (MSB, LSB): 0000 = Infinite timeout (default) |
| DFA00D | 1 | O | b | Beep when menu will be displayed: 00 = No beep (default), 01 = Beep |
| DFA019 | 1 | O | ans | Masking character; allowed ASCII values from 20 to 7E; if not set no masking will be done |
| DFA01A | var. | O | ans | Alternative Input Format String |
| 9F02 | 6 | O | n | Amount (6-byte BCD, non-zero): mandatory for Template ID 0E, optional for 0B and 0D (ignored otherwise) |
| 5F2A | 2 | O | n | Currency (see [Supported Currencies](#subsec_sdi_supported_currencies)): mandatory for Template ID 0B, 0D and 0E (ignored otherwise) |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
{% hint style="info" %}
The Alternative Input Format String (DFA01A) is effective only for Template IDs 01, 02, 06, and 07. For all other templates the tag is accepted syntactically but has no effect on the input behavior. For Template IDs 01 and 06 (ZIP code): the value must be a sequence of N and n characters enclosed in square brackets. N means a mandatory digit, n means an optional digit. Optional digits must follow all mandatory ones; once an n appears, no further N is allowed. Maximum total length (including brackets) is 21 characters. Example: \[NNNnn] requests between 3 and 5 digits. For Template IDs 02 and 07 (CVV): only the following format strings are accepted: `[NNN]` --- force exactly 3 digits; `[NNNN]` --- force exactly 4 digits; `[NNNn]` --- allow 3 or 4 digits (default when DFA01A is omitted). Any other value is rejected and returns 64 00. CVV bypass via `[BBBb]`, `[BBB]`, or `[BBBB]` is supported by this command too. For Template ID 0E, both 9F02 (non-zero amount, valid BCD) and 5F2A (non-zero currency) are mandatory. If either tag is absent, zero, or contains an invalid BCD value, the command returns 64 FE (Parameter Error). Supported currencies see [Supported Currencies](#subsec_sdi_supported_currencies) The number of decimal places when displaying amounts is done automatically in accordance with the ISO 4217 standard
{% endhint %}
Input templates are stored inside the PINPad and have to be loaded in a secure environment. The following input templates are supported:
| Template ID | Description | Name | Format |
| ----------- | ---------------------------------------------- | ------------ | ------ |
| 01 | ZIP code (4 -- 6 Digits) | ZIP | utf-8 |
| 02 | Card Verification Code (3 -- 4 Digits) | CVV | utf-8 |
| 03 | Date of Birth (8 Digits: MMDDYYYY) | BIRTHDAY | utf-8 |
| 04 | Social Security Number (SSN) (9 Digits) | SSN | utf-8 |
| 05 | Last 4 digits of SSN (4 Digits) | LAST4SSN | utf-8 |
| 06 | Verify ZIP code (4 -- 6 Digits) | ZIP | utf-8 |
| 07 | Verify Card Verification Code (3 -- 4 Digits) | CVV | utf-8 |
| 08 | Verify Date of Birth (8 Digits: MMDDYYYY) | BIRTHDAY | utf-8 |
| 09 | Verify Social Security Number (SSN) (9 Digits) | SSN | utf-8 |
| 0A | Verify Last 4 digits of SSN (4 Digits) | LAST4SSN | utf-8 |
| 0B | Enter Gratuity Amount | AMOUNT | utf-8 |
| 0C | Enter Gratuity Percentage | PERCENT | utf-8 |
| 0D | Enter Cashback Amount | AMOUNT | utf-8 |
| 0E | Enter Tip with showing the fare amount | AMOUNT | utf-8 |
| 0F | Entering an email address | EMAIL | utf-8 |
| 10 | Entering a telephone number | PHONE | utf-8 |
| 11 | Entering the number of installments | INSTALLMENTS | utf-8 |
{% hint style="info" %}
The special characters relevant for an email address (.!#$%25&'\*+-/=?^\_'{|}\~) are available by multiple pressing the key '1'. The character '@' is assigned to the key '0'. For Template IDs 03 and 08 (Date of Birth), the entered value is validated as a valid calendar date in MMDDYYYY format. If the entered date is not a valid date, the input dialog is repeated until a valid date is entered or the user cancels / a timeout occurs. Texts for input dialogs depend on Template ID and are looked up from UI catalogs, one for each supported system language. These texts can be customized with the installation of [Custom UI text catalogs](#subsubsec_sdi_custom_text_catalogs).
{% endhint %}
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ------------------------------- |
| 90 | 00 | Constructed | All OK, valid **Response Data** |
| 64 | 00 | None | Execution Error |
| 64 | 05 | None | Canceled by user |
| 64 | FE | None | Parameter Error |
| 65 | 00 | None | Execution Aborted |
| 66 | 00 | None | Timeout |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | -------------------------------------------------------------------------------------------------- |
| FFA014 | var. | O | tlv | **Input Data** (see table below). Depending on the used template this tag may occur more than once |
Input Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ---------------- |
| DFA015 | var. | M | ans | Input Data Name |
| DFA016 | var. | M | utf-8 | Input Data Value |
Examples:
```cpp
// Command to handle input of a zip code in Spanish with beep and a timeout of 30 seconds
24 04 00 00 F0 16 DF A0 07 01 01 DF A0 08 01 04 DF A0 0D 01 01 DF A0 05 02 00 1E
// Response
90 00 F0 16 FF A0 14 11 DF A0 15 03 5A 49 50 DF A0 16 06 31 32 33 34 35 00
```
```cpp
// Command to handle input of a zip code with alternative Input Format String to enter exactly five digits: [NNNNN]
24 04 00 00 F0 17 DF A0 07 01 01 DF A0 05 02 00 1E DF A0 1A 07 5B 4E 4E 4E 4E 4E 5D
// Response
90 00 F0 16 FF A0 14 11 DF A0 15 03 5A 49 50 DF A0 16 06 31 32 33 34 35 00
```
#### Handle Menu (24-05)
Command to display a menu dialog on screen. It expects a menu text prompt (TLV tag `DFA00A`) and menu entries (one or multiple TLV tags `DFA00B`, whereas the order in the provided TLV buffer corresponds the order for the display. The returned index (starts with `1` complies with the input sequence of the TLV tag(s) `DFA00B`. Finally, additional dialog options (TLV tag `DFA142`) are provided to adjust behaviour and appearance of the menu dialog.
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 24 | 05 | SC | 00 | Constructed |
Command Data:
\[TABLE]
{% hint style="info" %}
For devices with keypad '\*' and '#' keys are used to scroll through the menu. Enter key will confirm the pre-selected menu item. Cancel key aborts the menu dialog.
{% endhint %}
Response:
| SW1 | SW2 | Data | Comment | Reserved UI error code |
| --- | --- | ----------- | ---------------------------------------------------------------------- | ---------------------- |
| 90 | 00 | Constructed | All OK (menu confirmed, selected item is returned with TLV tag DFA00C) | 0 (UI\_ERR\_OK) |
| 64 | 00 | Constructed | Execution Error (UI error code in TLV tag DFA000) | |
| 64 | 05 | None | Canceled by user | -1 (UI\_ERR\_ABORT) |
| 65 | 00 | None | Execution Aborted with [Sys Abort (20-02)](#subsubsec_sdi_sys_abort) | |
| 66 | 00 | None | Timeout | -3 (UI\_ERR\_TIMEOUT) |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | --------------------------------------------------------- |
| DFA00C | 1 | O | b | Index of the chosen Menu Entry (`01` for the first entry) |
| DFA000 | 4 | O | b | UI error code (additional result code) |
{% hint style="info" %}
Appendix [UI command examples](#subsec_sdi_ui_examples) contains additional command examples demonstrating usage of Handle Menu (24-05).
{% endhint %}
#### Handle Card Request Display (24-06)
This command handles the card request display according the given parameter. It can be used directly before the Card Detection command (23-01) to show the corresponding display including the contactless logo on devices it is needed. Only physical card technologies are supported. If the contactless technology is contained and the virtual CLTS LED area is diabled by default it will be enabled for the card request display temporary and disabled afterwards. In addition to the amount also the Transaction Type will be displayed when requested. For manual card data entry only this command is not to be used because the user dialog is handled automatically inside the Card Detection command.
{% hint style="info" %}
Texts for card request dialog are looked up from UI catalogs, one for each supported system language. These texts can be customized with the installation of [Custom UI text catalogs](#subsubsec_sdi_custom_text_catalogs).
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 24 | 06 | SC | 00 | Constructed |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ------------------------------------------------------------------------------------------------------ |
| DFA108 | 1 | M | b | Requested Card Technology (for details see Card Detection) |
| DFA10A | 1 | O | b | Mode , 00 = Default, 01 = Fallback, 02 = Retry |
| 9F02 | 6 | O | n | Amount |
| 5F2A | 2 | O | n | Currency (see [Supported Currencies](#subsec_sdi_supported_currencies)), **must** when amount is given |
| 9C | 1 | O | n | Transaction Type according EMV-ADK definition |
| DFA150 | 1 | O | b | Command destination: 01 = Countertop (default), 02 = EPP |
{% hint style="info" %}
Supported currencies see [Supported Currencies](#subsec_sdi_supported_currencies) The number of decimal places when displaying amounts is done automatically in accordance with the ISO 4217 standard
{% endhint %}
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | --------------- |
| 90 | 00 | None | All OK |
| 64 | 00 | None | Execution Error |
| 64 | FE | None | Parameter Error |
Example:
```cpp
// Command to handle the card request display for mag stripe in default mode with an amount of 100,00 €:
24 06 00 00 F0 18 DF A1 08 01 01 DF A1 0A 01 00 9F 02 06 00 00 00 01 00 00 5F 2A 02 09 78
// Response
90 00
```
#### Display Idle Screen (24-07)
Command to display the idle screen with a text and/or an image. SDI server invokes HTML dialog `idle.html` (see chapter [idle.html](#pgr_idle_html)), which shows the idle message in region 4 and the image (if any) in region 3. The default message is provided by UI catalog installed with the SDI config package for standard mode (see [Default UI resource files](#subsubsec_sdi_default_resource_files)) and can be replaced with an user config package containing a custom UI catalog (see chapter [Custom UI text catalogs](#subsubsec_sdi_custom_text_catalogs)). Using a custom UI catalog to configure an own idle text is the recommended method, since this works system language depended. In addition, the idle text can be set with command [Set Idle Text (20-13)](#subsubsec_sdi_set_idle_text). If set with this command, this text is always used, independed from used SDI system language. Finally, another user config package can be used to install the custom logo file for the idle screen. The package must install the file `cust_logo.png` into following device location:
VOS/VOS2:
```fragment
/etc/config/sdi/www/images
```
VOS3:
```fragment
/home/usr/sdi/www/images
```
For more details and instruction how to create such a package, please refer to chapter [Install UI user config packages](#subsubsec_sdi_install_ui_user_config_packages). An example download package `dl.sdi-usrconfig-idlescreen-logo-X.X.X-X-P2PE-X.X.X.tar` containing the Verifone logo comes along with this SDI documentation package in subfolder `example/load/usr_config`.
{% hint style="info" %}
A custom text or image will replace the default idle message of SDI server used for the idle screen. Using both, the custom text and an image will display the text on bottom to the image. Deletion of the idle text (see [Set Idle Text (20-13)](#subsubsec_sdi_set_idle_text)) and removing file `cust_logo.png` will reset the SDI server idle screen to default message taken from UI catalog. Idle screen is also displayed by SDI itself, e.g. after startup to display states like waiting for connection. Once a connection is established to SDI, the idle screen is displayed at once the idle screen text.
{% endhint %}
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 24 | 07 | 00 | 00 | None |
| 24 | 07 | 00 | 00 | Constructed |
Command Data:
| | | | | |
| ------ | ---- | --- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tag | Size | M/O | Format | Description |
| DFA150 | 1 | O | b |
With enabled administration mode (see config.json) this TLV tag can be used to show Info/Menu softkeys/keyhelpers or to control admin menu access for idle screen to display. 00 = Don't show admin menu softkeys/keyhelpers and allow to enable admin menu by key combination 2-5-8 or clockwise touch presses on four display corners (default) 01 = Don't show admin menu softkeys/keyhelpers, but disallow to enable admin menu 02 = Show admin menu softkeys/keyhelpers
Note
This tag is ignored, if administartion mode is disabled (default).
Value of tag DFA155 is not stored persistently and applied for idle screen only, which was triggered by this command. If SDI shows an internal idle screen afterwards (e.g. with message "Wait for connection...." due to connection lost), the default value 00 is used again.
|
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ---- | ------- |
| 90 | 00 | None | All OK |
{% hint style="info" %}
The file name for the image must be cust\_logo.png. The maximum size of the image should be conform to the devices display resolution.
{% endhint %}
#### Handle Signature Capture (24-08)
Command to handle a signature capture dialog on the device display. Before displaying the addressed text the previous display content will be complete deleted.
Command:
| CLA | INS | P1 | P2 | Data |
| --- | --- | -- | -- | ----------- |
| 24 | 08 | SC | 00 | Constructed |
Command Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| DFA008 | 1 | O | b | Text Language, default is current terminal/transaction language (see [Supported System Languages](#subsec_sdi_supported_system_languages)) |
| DFA005 | 2 | O | b | Timeout in seconds (MSB, LSB), default is 0000 (no timeout) |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | ------------------------------- |
| 90 | 00 | Constructed | All OK, valid **Response Data** |
| 64 | 00 | None | Execution Error |
| 64 | 05 | None | Canceled by user |
| 65 | 00 | None | Execution Aborted |
| 66 | 00 | None | Timeout |
Response Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | ------------------------------------- |
| FFA015 | var. | M | tlv | **Signature Data** (see table below). |
Signature Data:
| Tag | Size | M/O | Format | Description |
| ------ | ---- | --- | ------ | --------------------------- |
| DFA01C | var. | M | a | Signature Format (e.g. png) |
| DFA01D | var. | M | b | Signature Value |
{% hint style="info" %}
\[unsupported block] Examples: \[unsupported block]
{% endhint %}
#### Activate LEDs (24-09)
Command to activate/deactivate the virtual CLTS LED area on the display. The command itself doesn't change the display at all. The display content will be updated with the next screen update. The payment application is responsible for the correct command order.
Command:
| CLA | INS | P1 | P2 | Comment |
| --- | --- | -- | -- | ---------- |
| 24 | 09 | 00 | 00 | Activate |
| 24 | 09 | 00 | 01 | Deactivate |
Response:
| SW1 | SW2 | Data | Comment |
| --- | --- | ----------- | --------------- |
| 90 | 00 | None | All OK |
| 64 | 00 | Constructed | Execution Error |
{% hint style="info" %}
\[unsupported block]
{% endhint %}
#### Handle HTML Dialog (24-0A)
Similar to [Handle Display (24-03)](#subsubsec_sdi_handle_display) this command is used to display customer specific HTML dialogs. Handle HTML Dialog (24-0A) has the following differences to [Handle Display (24-03)](#subsubsec_sdi_handle_display) :
* It always requires a HTML template and does not work without it. HTML templates are installed with an [User config package](#vos_user_config_package), which require SDI user signing privileges (e.g. with a regional user signing card for VOS/VOS2).
* It can be used to display dialogs for user inputs. A name-value map `ARGV` for ADKGUI (as already supported for [Handle Display (24-03)](#subsubsec_sdi_handle_display) for inbound direction with TLV tags `FFA011`, `DFA012` and `DFA013`) is returned in command response and contains all data, which was produced by the dialog, e.g. data of input fields. For more details see description of TLV tags `FFA014`, `DFA015` and `DFA016` below.
* It supports a reduced set of dialog options with TLV tag `DFA13D`, e.g. it is not supported to run the dialog asynchronously. Only synchronous execution is supported to provide dialog data in command response.
* It is executed with a special ADKGUI secure mode (CPApp mode), which disallows usage of `varhtml` and `print()` function to modify HTML document from JavaScript preprocessor (HTML tag ``). For more details please refer to ADKGUI documentation.
* The secure mode with restrictions allows name-value map `ARGV` in TLV tag `FFA011` to contain HTML characters, which are not filtered/substituted by SDI. For instance, this allows to provide initial data for input files containing HTML entities.
* Users must consider additional security directives to avoid misuse (e.g. fake PIN inputs). These directives are listed below and must be considered by developers providing the HTML template.
* It uses a separate CSS file `custom.css`, whereas [Handle Display (24-03)](#subsubsec_sdi_handle_display) uses `style.css`, which is also applied to internal SDI dialogs, see chapter [Default UI resource files](#subsubsec_sdi_default_resource_files).
Additional variables can be injected into custom dialogs with constructed TLV tag `FFA011` (Display Data). Each tag contains a pair of primitive TLV tags `DFA012` (variable name) and `DFA013` (variable value), which are passed in ADKGUI parameter map `ARGV` to the dialog. The ADKGUI parameter map `ARGV` is returned with constructed TLV tag `FFA014` in the same way (primitive TLV tags `DFA015` and `DFA016` used as name-value pairs).
{% hint style="info" %}
Parameter map returned with TLV tag `FFA014` never contains variables with prefix `_`. These variables are considered by the dialog as private, thus, SDI server filters them out and does not add them to the response. HTML template developers can use this prefix to keep dialog variables as private and avoid to send them to outer world in command response.
{% endhint %}
HTML templates may have an arbitrary filename and are installed with an [User config package](#vos_user_config_package) to following UI resource location: VOS/VOS2:
* `/etc/config/sdi/www/x` (device specific UI resoucre folder, e.g. `320x480C15T` is used for P400)
* `/etc/config/sdi/www/default` (default UI resource folder, used if the resource isn't found in device specific folder)
VOS3:
* `/home/usr/sdi/www/x` (device specific UI resoucre folder, e.g. `320x480C15T` is used for P630)
* `/home/usr/sdi/www/default` (default UI resource folder, used if the resource isn't found in device specific folder)
Finally, the appearance of the custom HTML template can be controlled with a CSS file `custom.css`, which comes along with the a [User config package](#vos_user_config_package) to external UI resource folders of SDI (see above). In addition, custom HTML templates can be implemented language independed and SDI server will load the custom UI text catalog for the recent system language to invoke the dialog. Thus, HTML templates can use XML processing instruction `` in HTML to use texts from the custom catalog (for more details see chapter [Custom UI text catalogs](#subsubsec_sdi_custom_text_catalogs)).
The same as decribed for command [Handle Display (24-03)](#subsubsec_sdi_handle_display), reserved UI return codes are mapped SDI result codes SW1/SW2. Other result codes are provided with response 6400 and TLV tag DFA000 (additional result code).
**Securitydirectives for developing HTML templates used for custom dialogs with user inputs**
There is a high risk for misuse of customer dialogs, if the HTML template contains elements to input user data with keyboard or touch screen. Developers must care about security related to data, which is provided in command with SDI interface, especially, if the interface is accessible from outer world (e.g. public networks). For this reason developers of custom dialogs **MUST** consider the following security directives:
* Texts used as prompt for input fields (element ``) must be part of HTML template or taken from a text catalog file with XML processing instruction ``. Texts for the custiom dialogs must be sufficient and unambiguous so that there is no risk that dialog could be misinterpreted as PIN prompt.
* Never pass prompt texts for input fields like "Please enter amount" in TLV tags `FFA011` over external SDI interface to display them in the dialog. This enables attackers to misuse the dialog for fake PIN prompts by just using another text like "Please enter PIN".
* Don't use variables in prompt texts and never place variables between the prompt text and the input field (element ``).
* Reduce number input variables injected to dialogs with TLV tags `FFA011` to a minimum. Be aware that data from outer world, which is put as text to the display could to move elements out of the screen range. Thus, input fields could become unvisible or hidden, but still active, when getting the focus. Use JavaScipt preprocessor (element ``) to check variable values and its length before displaying its content in dialogs.
* Never use multiple buttons (element `