IDTech Windows SDK Guide  1.2.119.0
API reference for Kiosk III
IDTechSDK.IDT_KioskIII Class Reference

Public Member Functions

RETURN_CODE config_getSerialNumber (ref string response)
 
RETURN_CODE device_retrieveAIDList (ref byte[][] response)
 
RETURN_CODE device_sendDataCommand (string cmd, bool calcLRC, ref byte[] response)
 
RETURN_CODE device_sendDataCommand_ext (string cmd, bool calcLRC, ref byte[] response, int timeout, bool noResponse)
 
RETURN_CODE device_getFirmwareVersion (ref string response)
 
RETURN_CODE device_getMerchantRecord (int index, ref byte[] record)
 
RETURN_CODE device_getTransactionResults (ref IDTTransactionData results)
 
RETURN_CODE device_pingDevice ()
 
RETURN_CODE device_controlUserInterface (byte[] values)
 
RETURN_CODE device_sendVivoCommandP2 (byte command, byte subCommand, byte[] data, ref byte[] response)
 
RETURN_CODE device_sendVivoCommandP2_ext (byte command, byte subCommand, byte[] data, ref byte[] response, int timeout, bool noResponse)
 
RETURN_CODE ctls_retrieveAIDList (ref byte[][] response)
 
RETURN_CODE ctls_getAllConfigurationGroups (ref byte[][] response)
 
RETURN_CODE ctls_retrieveApplicationData (byte[] AID, ref byte[] tlv)
 
RETURN_CODE ctls_removeApplicationData (byte[] AID)
 
RETURN_CODE ctls_setApplicationData (byte[] tlv)
 
RETURN_CODE ctls_setConfigurationGroup (byte[] tlv)
 
RETURN_CODE ctls_retrieveTerminalData (ref byte[] tlv)
 
RETURN_CODE ctls_setTerminalData (byte[] tlv)
 
RETURN_CODE ctls_getConfigurationGroup (int group, ref byte[] tlv)
 
RETURN_CODE ctls_removeConfigurationGroup (int group)
 
RETURN_CODE ctls_setCAPK (byte[] key)
 
RETURN_CODE ctls_retrieveCAPK (byte[] capk, ref byte[] key)
 
RETURN_CODE ctls_removeCAPK (byte[] capk)
 
RETURN_CODE ctls_removeAllCAPK ()
 
RETURN_CODE ctls_retrieveCAPKList (ref byte[] keys)
 
RETURN_CODE device_startTransaction (double amount, double amtOther, int exponent, int type, int timeout, byte[] tags)
 
RETURN_CODE device_activateTransaction (int timeout, byte[] tags)
 
RETURN_CODE ctls_startTransaction (double amount, double amtOther, int exponent, int type, int timeout, byte[] tags)
 
RETURN_CODE ctls_updateBalance (byte statusCode, byte[] authCode, byte[] date, byte[] time)
 
RETURN_CODE ctls_activateTransaction (int timeout, byte[] tags)
 
RETURN_CODE ctls_cancelTransaction ()
 
RETURN_CODE device_setBurstMode (byte mode)
 
RETURN_CODE device_setMerchantRecord (int index, bool enabled, string merchantID, string merchantURL)
 
RETURN_CODE device_setPollMode (byte mode)
 
RETURN_CODE device_startRKI ()
 
RETURN_CODE device_SymmetricRKI ()
 
RETURN_CODE device_enablePassThrough (bool enablePassThrough)
 

Static Public Member Functions

static bool useSerialPort (int port)
 
static int getCommandTimeout ()
 
static void setCommandTimeout (int milliseconds)
 
static bool useSerialPort (int port, int baud)
 
static bool useUSB ()
 
static void setCallback (CallBack my_Callback)
 
static void setCallback (IntPtr my_Callback, SynchronizationContext context)
 
static String SDK_Version ()
 
static RETURN_CODE device_updateDeviceFirmware (byte[] firmwareData)
 

Properties

static IDT_KioskIII SharedController [get]
 

Detailed Description

Class for KioskIII and KioskIV ICC reader

Member Function Documentation

RETURN_CODE IDTechSDK.IDT_KioskIII.config_getSerialNumber ( ref string  response)

Polls device for Serial Number

Parameters
responseReturns Serial Number
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_activateTransaction ( int  timeout,
byte[]  tags 
)

Start CTLS Transaction Request

Authorizes the CTLS transaction

The tags will be returned in the callback routine.

Parameters
timeoutTimeout value in seconds.
tagsThe tags to be included in the request. Passed as TLV Data. Example, tag 9F02 with amount 0x000000000100 would be 0x9F0206000000000100
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()

NOTE ON APPLEPAY VAS: To enable ApplePay VAS, first a merchant record must be defined in one of the six available index positions (1-6) using device_setMerchantRecord, then container tag FFEE06 must be sent as part of the additional tags parameter of ctls_startTransaction. Tag FFEE06 must contain tag 9F26 and 9F22, and can optionanally contain tags 9F2B and DFO1. Example FFEE06189F220201009F2604000000009F2B050100000000DF010101 9F22 = two bytes = ApplePay Terminal Applicaiton Version Number. Hard defined as 0100 for now. (required) 9F26 = four bytes = ApplePay Terminal Capabilities Information (required)

  • Byte 1 = RFU
  • Byte 2 = Terminal Type
  • - Bit 8 = VAS Support (1=on, 0 = off)
  • - Bit 7 = Touch ID Required (1=on, 0 = off)
  • - Bit 6 = RFU
  • - Bit 5 = RFU
  • - Bit 1,2,3,4
  • - - 0 = Payment Terminal
  • - - 1 = Transit Terminal
  • - - 2 = Access Terminal
  • - - 3 = Wireless Handoff Terminal
  • - - 4 = App Handoff Terminal
  • - - 15 = Other Terminal
  • Byte 3 = RFU
  • Byte 4 = Terminal Mode
  • - 0 = ApplePay VAS OR ApplePay
  • - 1 = ApplePay VAS AND ApplePay
  • - 2 = ApplePay VAS ONLY
  • - 3 = ApplePay ONLY 9F2B = 5 bytes = ApplePay VAS Filter. Each byte filters for that specific merchant index (optional) DF01 = 1 byte = ApplePay VAS Protocol. (optional)
  • - Bit 1 : 1 = URL VAS, 0 = Full VAS
  • - Bit 2 : 1 = VAS Beeps, 0 = No VAS Beeps
  • - Bit 3 : 1 = Silent Comm Error, 2 = EMEA Comm Error
  • - Bit 4-8 : RFU
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_cancelTransaction ( )

Cancel EMV Transaction

Cancels the currently executing EMV transaction.

Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_getAllConfigurationGroups ( ref byte  response[][])

Retrieve All Configuration Groups

Returns all the Configuration Groups installed on the terminal for CTLS

Parameters
responsearray of CTLS groups as TLV bytes
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_getConfigurationGroup ( int  group,
ref byte[]  tlv 
)

Get Configuration Group

Retrieves the Configuration for the specified Group.

Parameters
groupConfiguration Group
tlvreturn data
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_removeAllCAPK ( )

Remove All Certificate Authority Public Key

Removes all the CAPK for CTLS

Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_removeApplicationData ( byte[]  AID)

Remove Application Data by AID

Removes the Application Data for CTLS as specified by the AID name passed as a parameter

Parameters
AIDName of ApplicationID Must be between 5 and 16 bytes
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_removeCAPK ( byte[]  capk)

Remove Certificate Authority Public Key

Removes the CAPK as specified by the RID/Index

Parameters
capk6 byte CAPK = 5 bytes RID + 1 byte INDEX
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_removeConfigurationGroup ( int  group)

Remove Configuration Group

Removes the Configuration as specified by the Group. Must not by group 0

Parameters
groupConfiguration Group
Return values
RETURN_CODEReturn codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_BTPay::device_getResponseCodeString:()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_retrieveAIDList ( ref byte  response[][])

Retrieve AID list

Returns all the AID names and their assigned groups installed on the terminal for CTLS.

Parameters
responsearray of 2-tag TLV data objects: FFE4 (group name) followed by 9F06 (AID)
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_retrieveApplicationData ( byte[]  AID,
ref byte[]  tlv 
)

Retrieve Application Data by AID

Retrieves the CTLS Application Data as specified by the AID name passed as a parameter.

Parameters
AIDName of ApplicationID. Must be between 5 and 16 bytes
tlvThe TLV elements of the requested AID
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_retrieveCAPK ( byte[]  capk,
ref byte[]  key 
)

Retrieve Certificate Authority Public Key

Retrieves the CAPK for CTLS as specified by the RID/Index passed as a parameter.

Parameters
capk6 bytes CAPK = 5 bytes RID + 1 byte Index
keyResponse returned as a CAKey format: [5 bytes RID][1 byte Index][1 byte Hash Algorithm][1 byte Encryption Algorithm][20 bytes HashValue][4 bytes Public Key Exponent][2 bytes Modulus Length][Variable bytes Modulus] Where:
  • Hash Algorithm: The only algorithm supported is SHA-1.The value is set to 0x01
  • Encryption Algorithm: The encryption algorithm in which this key is used. Currently support only one type: RSA. The value is set to 0x01.
  • HashValue: Which is calculated using SHA-1 over the following fields: RID & Index & Modulus & Exponent
  • Public Key Exponent: Actually, the real length of the exponent is either one byte or 3 bytes. It can have two values: 3 (Format is 0x00 00 00 03), or 65537 (Format is 0x00 01 00 01)
  • Modulus Length: LenL LenH Indicated the length of the next field.
  • Modulus: This is the modulus field of the public key. Its length is specified in the field above.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_retrieveCAPKList ( ref byte[]  keys)

Retrieve the Certificate Authority Public Key list

Returns all the CAPK RID and Index installed on the terminal for CTLS.

Parameters
keys[key1][key2]...[keyn], each key 6 bytes where key = 5 bytes RID + 1 byte index
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_retrieveTerminalData ( ref byte[]  tlv)

Retrieve Terminal Data

Retrieves the Terminal Data for CTLS. This is configuration group 0 (Tag FFEE - > FFEE0100). The terminal data can also be retrieved by ctls_getConfigurationGroup(0).

Parameters
tlvResponse returned as a TLV
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_setApplicationData ( byte[]  tlv)

Set Application Data by AID

Sets the Application Data for CTLS as specified by TLV data

Parameters
tlvApplication data in TLV format The first tag of the TLV data must be the group number (FFE4). The second tag of the TLV data must be the AID (9F06)

Example valid TLV, for Group #2, AID a0000000035010: "ffe401029f0607a0000000051010ffe10101ffe50110ffe30114ffe20106"

Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_setCAPK ( byte[]  key)

Set Certificate Authority Public Key

Sets the CAPK for CTLS as specified by the CAKey structure

Parameters
keyCAKey format: [5 bytes RID][1 byte Index][1 byte Hash Algorithm][1 byte Encryption Algorithm][20 bytes HashValue][4 bytes Public Key Exponent][2 bytes Modulus Length][Variable bytes Modulus] Where:
  • Hash Algorithm: The only algorithm supported is SHA-1.The value is set to 0x01
  • Encryption Algorithm: The encryption algorithm in which this key is used. Currently support only one type: RSA. The value is set to 0x01.
  • HashValue: Which is calculated using SHA-1 over the following fields: RID & Index & Modulus & Exponent
  • Public Key Exponent: Actually, the real length of the exponent is either one byte or 3 bytes. It can have two values: 3 (Format is 0x00 00 00 03), or 65537 (Format is 0x00 01 00 01)
  • Modulus Length: LenL LenH Indicated the length of the next field.
  • Modulus: This is the modulus field of the public key. Its length is specified in the field above.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_setConfigurationGroup ( byte[]  tlv)

Set Configuration Group

Sets the Configuration Group for CTLS as specified by the TLV data

Parameters
tlvConfiguration Group Data in TLV format The first tag of the TLV data must be the group number (FFE4). A second tag must exist
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_setTerminalData ( byte[]  tlv)

Set Terminal Data

Sets the Terminal Data for CTLS as specified by the TLV. The first TLV must be Configuration Group Number (Tag FFE4). The terminal global data is group 0, so the first TLV would be FFE40100. Other groups can be defined using this method (1 or greater), and those can be retrieved with emv_getConfigurationGroup(int group), and deleted with emv_removeConfigurationGroup(int group). You cannot delete group 0.

Parameters
tlvTerminalData configuration data
Return values
RETURN_CODEReturn codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_BTPay::device_getResponseCodeString:()
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_startTransaction ( double  amount,
double  amtOther,
int  exponent,
int  type,
int  timeout,
byte[]  tags 
)

Start CTLS Transaction Request

The tags will be returned in the callback routine.

Parameters
amountTransaction amount value (tag value 9F02)
amtOtherOther amount value, if any (tag value 9F03)
typeTransaction type (tag value 9C).
timeoutTimeout value in seconds.
tagsAny other tags to be included in the request. Passed as TLV data. Example, tag 9F02 with amount 0x000000000100 would be 0x9F0206000000000100 If tags 9F02 (amount),9F03 (other amount), or 9C (transaction type) are included, they will take priority over these values supplied as individual parameters to this method.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()

NOTE ON APPLEPAY VAS: To enable ApplePay VAS, first a merchant record must be defined in one of the six available index positions (1-6) using device_setMerchantRecord, then container tag FFEE06 must be sent as part of the additional tags parameter of ctls_startTransaction. Tag FFEE06 must contain tag 9F26 and 9F22, and can optionanally contain tags 9F2B and DFO1. Example FFEE06189F220201009F2604000000009F2B050100000000DF010101 9F22 = two bytes = ApplePay Terminal Applicaiton Version Number. Hard defined as 0100 for now. (required) 9F26 = four bytes = ApplePay Terminal Capabilities Information (required)

  • Byte 1 = RFU
  • Byte 2 = Terminal Type
  • - Bit 8 = VAS Support (1=on, 0 = off)
  • - Bit 7 = Touch ID Required (1=on, 0 = off)
  • - Bit 6 = RFU
  • - Bit 5 = RFU
  • - Bit 1,2,3,4
  • - - 0 = Payment Terminal
  • - - 1 = Transit Terminal
  • - - 2 = Access Terminal
  • - - 3 = Wireless Handoff Terminal
  • - - 4 = App Handoff Terminal
  • - - 15 = Other Terminal
  • Byte 3 = RFU
  • Byte 4 = Terminal Mode
  • - 0 = ApplePay VAS OR ApplePay
  • - 1 = ApplePay VAS AND ApplePay
  • - 2 = ApplePay VAS ONLY
  • - 3 = ApplePay ONLY 9F2B = 5 bytes = ApplePay VAS Filter. Each byte filters for that specific merchant index (optional) DF01 = 1 byte = ApplePay VAS Protocol. (optional)
  • - Bit 1 : 1 = URL VAS, 0 = Full VAS
  • - Bit 2 : 1 = VAS Beeps, 0 = No VAS Beeps
  • - Bit 3 : 1 = Silent Comm Error, 2 = EMEA Comm Error
  • - Bit 4-8 : RFU
RETURN_CODE IDTechSDK.IDT_KioskIII.ctls_updateBalance ( byte  statusCode,
byte[]  authCode,
byte[]  date,
byte[]  time 
)

Update Balance

This command is the authorization response sent by the issuer to the terminal including the Authorization Status (OK or NOT OK).

This command is also being used in some implementations (i.e. EMEA) to communicate the results of Issuer Authentication to the reader in order to display the correct LCD messages. With this command, the POS passes the authorization result (OK/NOT OK), and possibly the Authorization Code (Auth_Code)/Date/Time to the terminal.

Parameters
statusCode00: OK, 01: NOT OK, 02: (ARC response 89 for Interac)
authCodeAuthorization code from host. Six bytes. Optional
dateTransaction date. If null, uses current terminal date. 3 bytes compressed numeric YYMMDD (tag value 9A).
timeTransaction time. If null, uses current terminal time. 3 bytes compressed numeric HHMMSS (tag value 9F21).
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
RETURN_CODE IDTechSDK.IDT_KioskIII.device_activateTransaction ( int  timeout,
byte[]  tags 
)

Start CTLS Transaction Request

Authorizes the CTLS transaction

The tags will be returned in the callback routine.

Parameters
timeoutTimeout value in seconds.
tagsThe tags to be included in the request. Passed as TLV Data. Example, tag 9F02 with amount 0x000000000100 would be 0x9F0206000000000100
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()

NOTE ON APPLEPAY VAS: To enable ApplePay VAS, first a merchant record must be defined in one of the six available index positions (1-6) using device_setMerchantRecord, then container tag FFEE06 must be sent as part of the additional tags parameter of ctls_startTransaction. Tag FFEE06 must contain tag 9F26 and 9F22, and can optionanally contain tags 9F2B and DFO1. Example FFEE06189F220201009F2604000000009F2B050100000000DF010101 9F22 = two bytes = ApplePay Terminal Applicaiton Version Number. Hard defined as 0100 for now. (required) 9F26 = four bytes = ApplePay Terminal Capabilities Information (required)

  • Byte 1 = RFU
  • Byte 2 = Terminal Type
  • - Bit 8 = VAS Support (1=on, 0 = off)
  • - Bit 7 = Touch ID Required (1=on, 0 = off)
  • - Bit 6 = RFU
  • - Bit 5 = RFU
  • - Bit 1,2,3,4
  • - - 0 = Payment Terminal
  • - - 1 = Transit Terminal
  • - - 2 = Access Terminal
  • - - 3 = Wireless Handoff Terminal
  • - - 4 = App Handoff Terminal
  • - - 15 = Other Terminal
  • Byte 3 = RFU
  • Byte 4 = Terminal Mode
  • - 0 = ApplePay VAS OR ApplePay
  • - 1 = ApplePay VAS AND ApplePay
  • - 2 = ApplePay VAS ONLY
  • - 3 = ApplePay ONLY 9F2B = 5 bytes = ApplePay VAS Filter. Each byte filters for that specific merchant index (optional) DF01 = 1 byte = ApplePay VAS Protocol. (optional)
  • - Bit 1 : 1 = URL VAS, 0 = Full VAS
  • - Bit 2 : 1 = VAS Beeps, 0 = No VAS Beeps
  • - Bit 3 : 1 = Silent Comm Error, 2 = EMEA Comm Error
  • - Bit 4-8 : RFU
RETURN_CODE IDTechSDK.IDT_KioskIII.device_controlUserInterface ( byte[]  values)

Control User Interface

Controls the User Interface: Display, Beep, LED

@param values Four bytes to control the user interface
Byte[0] = LCD Message
Messages 00-07 are normally controlled by the reader. 
- 00h: Idle Message (Welcome)
- 01h: Present card (Please Present Card)
- 02h: Time Out or Transaction cancel (No Card)
- 03h: Transaction between reader and card is in the middle (Processing...) 
- 04h: Transaction Pass (Thank You)
- 05h: Transaction Fail (Fail)
- 06h: Amount (Amount $ 0.00 Tap Card)
- 07h: Balance or Offline Available funds (Balance $ 0.00) Messages 08-0B are controlled by the terminal
- 08h: Insert or Swipe card (Use Chip & PIN)
- 09h: Try Again(Tap Again)
- 0Ah: Tells the customer to present only one card (Present 1 card only) 
- 0Bh: Tells the customer to wait for authentication/authorization (Wait) 
- FFh: indicates the command is setting the LED/Buzzer only.
Byte[1] = Beep Indicator
- 00h: No beep
- 01h: Single beep
- 02h: Double beep
- 03h: Three short beeps
- 04h: Four short beeps
- 05h: One long beep of 200 ms 
- 06h: One long beep of 400 ms 
- 07h: One long beep of 600 ms 
- 08h: One long beep of 800 ms
Byte[2] = LED Number
- 00h: LED 0 (Power LED) 01h: LED 1
- 02h: LED 2
- 03h: LED 3
- FFh: All LEDs
Byte[3] = LED Status
- 00h: LED Off 
- 01h: LED On
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.device_enablePassThrough ( bool  enablePassThrough)

Enable Pass Through

Enables Pass Through Mode for direct communication with L1 interface (power on icc, send apdu, etc).

Parameters
enablePassThroughtrue = pass through ON, false = pass through OFF
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.device_getFirmwareVersion ( ref string  response)

Polls device for Firmware Version

Parameters
responseResponse returned of Firmware Version
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.device_getMerchantRecord ( int  index,
ref byte[]  record 
)

Get Merchant Record Gets the merchant record for ApplePay VAS

Parameters
indexMerchant Record index, valid values 1-6
recordData returned containing 99 bytes: Byte 0 = Merchand Index Byte 1 = Merchant Enabled (1 = enabled) Byte 2 - 33 = Merchant Protocol Hash-256 value Byte 34 = Length of Merchant URL Bytes 35 - 99 = URL
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.device_getTransactionResults ( ref IDTTransactionData  results)

Get Transaction Results Gets the transaction results when the reader is functioning in "Auto Poll" mode

Parameters
resultsThe transaction results
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString(). When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
RETURN_CODE IDTechSDK.IDT_KioskIII.device_pingDevice ( )

Ping Device

Pings the reader. If connected, returns success. Otherwise, returns timeout.

Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.device_retrieveAIDList ( ref byte  response[][])

Retrieve AID list

Returns all the AID names and their assigned groups installed on the terminal for CTLS/CONTACT.

Parameters
responsearray of TLV data objects: FFE4 (group name) followed by 9F06 (AID), and DFEE4F (Interface 01 = CTLS, 02 = CONTACT)
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.device_sendDataCommand ( string  cmd,
bool  calcLRC,
ref byte[]  response 
)

Send a data command to the device

Sends a command to the device.

Parameters
cmdString representation of command to execute
calcLRCIf TRUE, this will wrap command with start/length/lrc/sum/end: '{STX}{Len_Low}{Len_High} data {CheckLRC} {CheckSUM} {ETX}'
responseResponse data
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
RETURN_CODE IDTechSDK.IDT_KioskIII.device_sendDataCommand_ext ( string  cmd,
bool  calcLRC,
ref byte[]  response,
int  timeout,
bool  noResponse 
)

Send a data command to the device - extended

Sends a command to the device.

Parameters
cmdString representation of command to execute
calcLRCIf TRUE, this will wrap command as NGA with start/length/lrc/sum/end: '{STX}{Len_Low}{Len_High} data {CheckLRC} {CheckSUM} {ETX}'
responseResponse data
timeoutTimeout value waiting for response, in milliseconds (1000 = 1 second)
noResponseif TRUE, this will not wait for a response and immediately return SUCCESS
calcITPIf TRUE, this will wrap command as ITP with start/end/lrc: '{STX} data {ETX}{CheckLRC}'
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
RETURN_CODE IDTechSDK.IDT_KioskIII.device_sendVivoCommandP2 ( byte  command,
byte  subCommand,
byte[]  data,
ref byte[]  response 
)

Send Vivo Command Protocol 2

Sends a protocol 2 command to Vivo readers (IDG/NEO)

Parameters
commandCommand
subCommandSub-Command
dataData. May be null
responseResponse
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.device_sendVivoCommandP2_ext ( byte  command,
byte  subCommand,
byte[]  data,
ref byte[]  response,
int  timeout,
bool  noResponse 
)

Send Vivo Command Protocol 2 Extended

Sends a protocol 2 command to Vivo readers (IDG/NEO)

Parameters
commandCommand
subCommandSub-Command
dataData. May be null
responseResponse
timeoutTimeout, in milliseconds (3000 = 3 seconds)
noResponseTRUE = don't wait for response, FALSE = wait for response defined by timeout
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.device_setBurstMode ( byte  mode)

Send Burst Mode

Sets the burst mode forthe device.

Parameters
mode0 = OFF, 1 = Always On, 2 = Auto Exit
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.device_setMerchantRecord ( int  index,
bool  enabled,
string  merchantID,
string  merchantURL 
)

Set Merchant Record Sets the merchant record for ApplePay VAS

Parameters
indexMerchant Record index, valid values 1-6
enabledMerchant Enabled/Valid flag
merchantIDMerchant unique identifer registered with Apple. Example com.idtechproducts.applePay
merchantURLMerchant URL, when applicable
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.device_setPollMode ( byte  mode)

Send Poll Mode

Sets the poll mode forthe device. Auto Poll keeps reader active, Poll On Demand only polls when requested by terminal

Parameters
mode0 = Auto Poll, 1 = Poll On Demand
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_KioskIII.device_startRKI ( )

Start Legacy Remote Key Injection

Starts a remote key injection request with IDTech RKI Legacy servers.

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
RETURN_CODE IDTechSDK.IDT_KioskIII.device_startTransaction ( double  amount,
double  amtOther,
int  exponent,
int  type,
int  timeout,
byte[]  tags 
)

Start CTLS Transaction Request

The tags will be returned in the callback routine.

Parameters
amountTransaction amount value (tag value 9F02)
amtOtherOther amount value, if any (tag value 9F03)
typeTransaction type (tag value 9C).
timeoutTimeout value in seconds.
tagsAny other tags to be included in the request. Passed as TLV data. Example, tag 9F02 with amount 0x000000000100 would be 0x9F0206000000000100 If tags 9F02 (amount),9F03 (other amount), or 9C (transaction type) are included, they will take priority over these values supplied as individual parameters to this method.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()

NOTE ON APPLEPAY VAS: To enable ApplePay VAS, first a merchant record must be defined in one of the six available index positions (1-6) using device_setMerchantRecord, then container tag FFEE06 must be sent as part of the additional tags parameter of ctls_startTransaction. Tag FFEE06 must contain tag 9F26 and 9F22, and can optionanally contain tags 9F2B and DFO1. Example FFEE06189F220201009F2604000000009F2B050100000000DF010101 9F22 = two bytes = ApplePay Terminal Applicaiton Version Number. Hard defined as 0100 for now. (required) 9F26 = four bytes = ApplePay Terminal Capabilities Information (required)

  • Byte 1 = RFU
  • Byte 2 = Terminal Type
  • - Bit 8 = VAS Support (1=on, 0 = off)
  • - Bit 7 = Touch ID Required (1=on, 0 = off)
  • - Bit 6 = RFU
  • - Bit 5 = RFU
  • - Bit 1,2,3,4
  • - - 0 = Payment Terminal
  • - - 1 = Transit Terminal
  • - - 2 = Access Terminal
  • - - 3 = Wireless Handoff Terminal
  • - - 4 = App Handoff Terminal
  • - - 15 = Other Terminal
  • Byte 3 = RFU
  • Byte 4 = Terminal Mode
  • - 0 = ApplePay VAS OR ApplePay
  • - 1 = ApplePay VAS AND ApplePay
  • - 2 = ApplePay VAS ONLY
  • - 3 = ApplePay ONLY 9F2B = 5 bytes = ApplePay VAS Filter. Each byte filters for that specific merchant index (optional) DF01 = 1 byte = ApplePay VAS Protocol. (optional)
  • - Bit 1 : 1 = URL VAS, 0 = Full VAS
  • - Bit 2 : 1 = VAS Beeps, 0 = No VAS Beeps
  • - Bit 3 : 1 = Silent Comm Error, 2 = EMEA Comm Error
  • - Bit 4-8 : RFU
RETURN_CODE IDTechSDK.IDT_KioskIII.device_SymmetricRKI ( )

Start Remote Key Injection

Starts a remote key injection request with IDTech Symmetric RKI servers. Set/Get RKI url with IDT_Device.RKI_URL.

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
static RETURN_CODE IDTechSDK.IDT_KioskIII.device_updateDeviceFirmware ( byte[]  firmwareData)
static

Update Firmware

Updates the firmware .

Parameters
firmwareDataSigned binary data of a firmware file provided by IDTech
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()

After you pass the firmwareData file, a new thread will start to execute the firmware download. You will receive status of the progress through callbacks to the IDTechSDK.Callback() delegate. The following parameters will be passed back:

  • sender = IDT_DEVICE_Types.IDT_DEVICE_AUGUSTA
  • state = DeviceState.FirmwareUpdate
  • transactionResultCode = status of the firmware update (starting, entering bootloader, applying update, block success, firmware success)
  • data = File Progress. Four bytes, with bytes [0][1] = current block, and bytes [2][3] = total blocks. 0x00030010 = block 3 of 16

Example code starting a firmware update

OpenFileDialog diag = new OpenFileDialog();
diag.Filter = "NGA FW Files|*.fm";
if (diag.ShowDialog() == DialogResult.OK)
{
byte[] file = File.ReadAllBytes(diag.FileName);
RETURN_CODE rt = IDT_Device.SharedController.device_updateDeviceFirmware(file);
if (rt == RETURN_CODE.RETURN_CODE_DO_SUCCESS)
{
//Was a success
}
else
{
//Error starting firmware download
}
}

Example monitoring firmware update status / success

private void MessageCallBack(IDTechSDK.IDT_DEVICE_Types type, DeviceState state, byte[] data, IDTTransactionData cardData, EMV_Callback emvCallback, RETURN_CODE transactionResultCode)
{
switch (state)
{
case DeviceState.FirmwareUpdate:
switch (transactionResultCode)
{
case RETURN_CODE.RETURN_CODE_FW_STARTING_UPDATE:
SetOutputText("Starting Firmware Update\n");
break;
case RETURN_CODE.RETURN_CODE_DO_SUCCESS:
SetOutputText("Firmware Update Successful\n");
break;
case RETURN_CODE.RETURN_CODE_APPLYING_FIRMWARE_UPDATE:
SetOutputText("Applying Firmware Update....\n");
break;
case RETURN_CODE.RETURN_CODE_ENTERING_BOOTLOADER_MODE:
SetOutputText("Entering Bootloader Mode....\n");
break;
case RETURN_CODE.RETURN_CODE_BLOCK_TRANSFER_SUCCESS:
int start = data[0] * 0x100 + data[1];
int end = data[2] * 0x100 + data[3];
SetOutputText("Sent block " + start.ToString() + " of " + end.ToString() + "\n");
break;
default:
SetOutputText("Firmware Update Error Code: " + "0x" + String.Format("{0:X}", (ushort)transactionResultCode) + ": " + IDTechSDK.errorCode.getErrorString(transactionResultCode) + "\r\n");
break;
}
break;
}
}
static int IDTechSDK.IDT_KioskIII.getCommandTimeout ( )
static

Get Command Timeout

Gets the default timeout (in milliseconds) waiting for a blocking command response

Return values
timeTime
static String IDTechSDK.IDT_KioskIII.SDK_Version ( )
static

SDK Version

  • All Devices

Returns the current version of SDK

Returns
Framework version
static void IDTechSDK.IDT_KioskIII.setCallback ( CallBack  my_Callback)
static

Set Callback

Sets the class callback
static void IDTechSDK.IDT_KioskIII.setCallback ( IntPtr  my_Callback,
SynchronizationContext  context 
)
static

Set Callback

Sets the class callback

Parameters
my_CallbackThe callback function to receive the response message from device. defined as follows. public unsafe delegate void MFCCallBack(Parameters parameters);
contextThe context of the UI thread
static void IDTechSDK.IDT_KioskIII.setCommandTimeout ( int  milliseconds)
static

Set Command Timeout

Sets the default timeout (in milliseconds) waiting for a blocking command response

Parameters
millisecondsTime
static bool IDTechSDK.IDT_KioskIII.useSerialPort ( int  port)
static

Use Serial Port Interface

Instructs SDK to attempt to use the Serial Port for communication with Kiosk III/IV using default baud rate

Parameters
portSerial Port to use. Example COM1 = 1.
Returns
bool TRUE=successful, FALSE=failure
static bool IDTechSDK.IDT_KioskIII.useSerialPort ( int  port,
int  baud 
)
static

Use Serial Port Interface with baud rate

Instructs SDK to attempt to use the Serial Port for communication with Kiosk III/IV

Parameters
portSerial Port to use. Example COM1 = 1.
baudBaud rate to override default. Example 115200;
Returns
bool TRUE=successful, FALSE=failure
static bool IDTechSDK.IDT_KioskIII.useUSB ( )
static

Use USB Interface

Instructs SDK to attempt to use USB for communication with Kiosk III/IV

Property Documentation

IDT_KioskIII IDTechSDK.IDT_KioskIII.SharedController
staticget

Singleton Instance

Establishes an singleton instance of IDT_KioskIII class.

Returns
Instance of IDT_KioskIII

The documentation for this class was generated from the following file: