IDTech iOS SDK Guide  1.1.166.045
API reference for NEO2
IDT_NEO2 Class Reference

#import <IDT_NEO2.h>

Inheritance diagram for IDT_NEO2:

Instance Methods

(void) - close
 
(RETURN_CODE) - ctls_cancelTransaction
 
(RETURN_CODE) - emv_cancelTransaction
 
(RETURN_CODE) - device_cancelTransaction
 
(RETURN_CODE) - device_logClear
 
(RETURN_CODE) - device_logRead:
 
(RETURN_CODE) - device_logEnable:
 
(RETURN_CODE) - device_getRT1050FirmwareVersion:
 
(RETURN_CODE) - device_getBootloaderVersion:
 
(RETURN_CODE) - device_rebootDevice
 
(RETURN_CODE) - device_buzzerOnOff
 
(RETURN_CODE) - ctls_getConfigurationGroup:response:
 
(RETURN_CODE) - device_setMerchantRecord:enabled:merchantID:merchantURL:
 
(RETURN_CODE) - device_getMerchantRecord:record:
 
(RETURN_CODE) - device_getTransactionResults:
 
(RETURN_CODE) - device_getDeviceTreeVersion:is1050:
 
(RETURN_CODE) - device_get1050FuseStatus:
 
(RETURN_CODE) - device_get1050BootloaderVersion:
 
(RETURN_CODE) - device_get1050DeviceTreeVersion:
 
(RETURN_CODE) - device_resetNVM
 
(RETURN_CODE) - config_checkDUKPTKey:value:
 
(RETURN_CODE) - config_getDEKVariantType:
 
(RETURN_CODE) - config_setDEKVariantType:
 
(RETURN_CODE) - config_getDUKPT_KSN:
 
(RETURN_CODE) - config_getSalt_KCV:
 
(RETURN_CODE) - config_setRKLKeys:tr31:nonce:hmac:kv:nonceDevice:hmacDevice:
 
(RETURN_CODE) - config_setKeyslot_PEK_DEK:keyslot:
 
(RETURN_CODE) - config_getKeyslot_PEK_DEK:keyslotDEK:
 
(RETURN_CODE) - config_getDUKPT_DEK_Attribution:mode:outputModeWorkingKey:variantKeyUsage:
 
(RETURN_CODE) - config_setDUKPT_DEK_Attribution_AES:working_Key:key_Usage:
 
(RETURN_CODE) - config_setDUKPT_DEK_Attribution_TDES:output_Mode:variant:
 
(RETURN_CODE) - ctls_removeAllCAPK
 
(RETURN_CODE) - ctls_removeApplicationData:
 
(RETURN_CODE) - ctls_removeCAPK:
 
(RETURN_CODE) - ctls_updateBalance:authCode:date:time:
 
(RETURN_CODE) - ctls_getAllConfigGroups:
 
(RETURN_CODE) - ctls_getAllConfigurationGroups:
 
(RETURN_CODE) - ctls_removeConfigurationGroup:
 
(RETURN_CODE) - ctls_retrieveAIDList:
 
(RETURN_CODE) - ctls_retrieveApplicationData:response:
 
(RETURN_CODE) - ctls_retrieveCAPK:key:
 
(RETURN_CODE) - ctls_retrieveCAPKList:
 
(RETURN_CODE) - ctls_retrieveTerminalData:
 
(RETURN_CODE) - ctls_setApplicationData:
 
(RETURN_CODE) - emv_setCAPK:
 
(RETURN_CODE) - ctls_setCAPK:
 
(RETURN_CODE) - ctls_setConfigurationGroup:
 
(RETURN_CODE) - ctls_setTerminalData:
 
(RETURN_CODE) - ctls_startTransaction:type:timeout:tags:
 
(RETURN_CODE) - ctls_resetConfigurationGroup:
 
(RETURN_CODE) - icc_getKeyFormatForICCDUKPT:
 
(RETURN_CODE) - icc_setKeyFormatForICCDUKPT:
 
(RETURN_CODE) - updateFirmwareNeo2:data:
 
(RETURN_CODE) - device_getFirmwareVersion:
 
(RETURN_CODE) - emv_getBatteryVoltage:
 
(RETURN_CODE) - emv_getBatteryPercentage:
 
(bool) - device_enableBLEDeviceSearch:
 
(NSString *) - device_getBLEFriendlyName
 
(void) - device_setBLEFriendlyName:
 
(bool) - device_disableBLEDeviceSearch
 
(NSUUID *) - device_connectedBLEDevice
 
(void) - device_disconnectBLE
 
(RETURN_CODE) - device_getAutoPollTransactionResults:
 
(RETURN_CODE) - device_extendedErrorCondition:
 
(NSString *) - device_getResponseCodeString:
 
(bool) - device_isConnected:
 
(RETURN_CODE) - device_sendIDGCommand:subCommand:data:response:
 
(RETURN_CODE) - device_sendIDGCommandV3:subCommand:data:response:
 
(void) - setServiceScanFilter:
 
(RETURN_CODE) - device_setPassThrough:
 
(RETURN_CODE) - device_pollForToken:card:serialNumber:
 
(RETURN_CODE) - device_antennaControl:
 
(RETURN_CODE) - device_exchangeContactlessData:receiveData:
 
(RETURN_CODE) - device_setSpecialFunctionOrFeature:addRequirement:
 
(RETURN_CODE) - device_getSpecialFunctionOrFeature:addRequirement:
 
(RETURN_CODE) - device_setTerminalData:
 
(RETURN_CODE) - device_retrieveTerminalData:
 
(RETURN_CODE) - device_queryFile:filename:isSD:exists:timestamp:fileSize:
 
(RETURN_CODE) - device_readFileFromSD:filename:fileData:
 
(RETURN_CODE) - device_addTLVToTerminalData:
 
(RETURN_CODE) - device_setBurstMode:
 
(RETURN_CODE) - device_setPollMode:
 
(RETURN_CODE) - emv_authenticateTransaction:
 
(RETURN_CODE) - emv_callbackResponseLCD:selection:
 
(RETURN_CODE) - emv_callbackResponsePIN:KSN:PIN:
 
(RETURN_CODE) - emv_completeOnlineEMVTransaction:hostResponseTags:
 
(void) - emv_disableAutoAuthenticateTransaction:
 
(RETURN_CODE) - emv_getEMVL2Version:
 
(RETURN_CODE) - emv_removeApplicationData:
 
(RETURN_CODE) - emv_removeCAPK:index:
 
(RETURN_CODE) - device_getPollMode:
 
(RETURN_CODE) - device_getTransArmorID:
 
(RETURN_CODE) - emv_getEMVKernelCheckValue:
 
(RETURN_CODE) - emv_getEMVKernelVersion:
 
(RETURN_CODE) - emv_callbackResponsePIN_ETC:ksn:pin:
 
(RETURN_CODE) - emv_callbackResponseKSN:
 
(RETURN_CODE) - emv_verifyDUKPTLoaded:
 
(RETURN_CODE) - emv_getEMVKernelVersionExt:
 
(RETURN_CODE) - emv_removeAllApplicationData
 
(RETURN_CODE) - device_enableL80PassThrough:
 
(RETURN_CODE) - device_getProductType:
 
(RETURN_CODE) - device_getProcessorType:
 
(RETURN_CODE) - device_getHardwareInfo:
 
(RETURN_CODE) - device_getUIDofMCU:
 
(RETURN_CODE) - device_pingDevice
 
(RETURN_CODE) - device_enableL100PassThrough:
 
(RETURN_CODE) - device_setTransArmorID:
 
(RETURN_CODE) - device_listenForNotifications:
 
(RETURN_CODE) - device_controlLED:control:
 
(RETURN_CODE) - device_certificateType:
 
(RETURN_CODE) - device_deleteFile:isSD:
 
(RETURN_CODE) - device_deleteDirectory:
 
(RETURN_CODE) - device_listDirectory:recursive:onSD:directory:
 
(RETURN_CODE) - device_createDirectory:
 
(RETURN_CODE) - device_lowPowerMode:wakeOnTrans:
 
(RETURN_CODE) - device_controlUserInterface:
 
(RETURN_CODE) - device_loadCertCA:CertData:
 
(RETURN_CODE) - device_rrcConnect
 
(RETURN_CODE) - device_rrcDisconnect
 
(RETURN_CODE) - device_rrcRunApp:
 
(RETURN_CODE) - device_rrcInstallApp:
 
(RETURN_CODE) - device_rrcUninstallApp:
 
(RETURN_CODE) - device_rrcDownloadApp:appData:
 
(RETURN_CODE) - device_getMsrSecurePara:b1:b2:b3:tlv:
 
(RETURN_CODE) - device_getModuleVer:
 
(RETURN_CODE) - device_disBlueLED
 
(RETURN_CODE) - device_enaBlueLED:
 
(RETURN_CODE) - device_onYellowLED
 
(RETURN_CODE) - device_offYellowLED
 
(RETURN_CODE) - device_enterStandbyMode
 
(RETURN_CODE) - device_getLightSensorVal:
 
(RETURN_CODE) - device_setTransArmorEncryption:
 
(RETURN_CODE) - adf_getModuleBytes:adfInfo:
 
(RETURN_CODE) - adf_getModuleInfo:adfInfo:
 
(RETURN_CODE) - adf_eraseFlash:
 
(RETURN_CODE) - adf_setJTAG:
 
(RETURN_CODE) - adf_setADFMode:
 
(RETURN_CODE) - adf_getADFMode:
 
(RETURN_CODE) - msr_getMSRTrack:
 
(RETURN_CODE) - msr_getConfiguration:
 
(RETURN_CODE) - msr_setConfiguration:
 
(RETURN_CODE) - msr_retrieveWhiteList:
 
(RETURN_CODE) - msr_setMSRTrack:
 
(RETURN_CODE) - emv_setTerminalMajorConfiguration:
 
(RETURN_CODE) - emv_getTerminalMajorConfiguration:
 
(RETURN_CODE) - emv_removeCRLList
 
(RETURN_CODE) - emv_removeTerminalData
 
(RETURN_CODE) - emv_retrieveAIDList:
 
(RETURN_CODE) - emv_retrieveApplicationData:response:
 
(RETURN_CODE) - emv_retrieveCAPKFile:index:response:
 
(RETURN_CODE) - emv_retrieveCAPKList:
 
(RETURN_CODE) - emv_retrieveCAPK:index:response:
 
(RETURN_CODE) - emv_retrieveCRLList:
 
(RETURN_CODE) - emv_retrieveTerminalData:
 
(RETURN_CODE) - emv_retrieveTransactionResult:retrievedTags:
 
(RETURN_CODE) - emv_setApplicationData:configData:
 
(RETURN_CODE) - emv_setCAPKFile:
 
(RETURN_CODE) - emv_setCRLEntries:
 
(RETURN_CODE) - emv_setTerminalData:
 
(RETURN_CODE) - emv_startTransaction:amtOther:type:timeout:tags:forceOnline:fallback:
 
(RETURN_CODE) - emv_exchangeCerts:nonce:signature:
 
(RETURN_CODE) - emv_getEMVConfigurationCheckValue:
 
(RETURN_CODE) - emv_callbackResponseMSR:
 
(RETURN_CODE) - emv_generateDUKPT:signature:key:
 
(RETURN_CODE) - config_getSerialNumber:
 
(RETURN_CODE) - icc_exchangeAPDU:response:
 
(RETURN_CODE) - icc_getICCReaderStatus:
 
(RETURN_CODE) - icc_powerOnICC:
 
(RETURN_CODE) - icc_powerOffICC:
 
(RETURN_CODE) - msr_cancelMSRSwipe
 
(RETURN_CODE) - msr_startMSRSwipe
 
(bool) - isConnected
 
(RETURN_CODE) - device_startTransaction:type:timeout:tags:
 
(RETURN_CODE) - pin_captureFunctionKey
 
(RETURN_CODE) - pin_cancelPin
 
(RETURN_CODE) - pin_capturePin:PAN:minPIN:maxPIN:message:
 
(RETURN_CODE) - config_setBluetoothParameters:oldPW:newPW:
 
(RETURN_CODE) - felica_authentication:
 
(RETURN_CODE) - felica_readWithMac:blockList:blocks:
 
(RETURN_CODE) - felica_SendCommand:response:
 
(RETURN_CODE) - felica_writeWithMac:data:
 
(RETURN_CODE) - felica_read:numBlocks:blockList:blocks:
 
(RETURN_CODE) - felica_write:blockCount:blockList:data:statusFlag:
 
(RETURN_CODE) - ctls_nfcCommand:response:
 
(void) - scanForBLEDevices:serviceUUIDs:options:
 
(void) - scanForBLEDeviceNames:serviceUUIDs:options:
 
(RETURN_CODE) - felica_requestService:response:
 
(void) - setServiceUUID:
 
(RETURN_CODE) - pin_captureAmountInput:maxPIN:message:signature:
 
(RETURN_CODE) - pin_captureNumericInput:minPIN:maxPIN:message:signature:
 

Class Methods

(NSString *) + SDK_version
 
(IDT_NEO2 *) + sharedController
 
(NSString *) + createFastEMVData:
 

Properties

id< IDT_NEO2_Delegatedelegate
 

Detailed Description

Class to drive the IDT_NEO2 device

Method Documentation

- (RETURN_CODE) adf_eraseFlash: (ADF_TYPE)  type

Erase ADF Flash

Erases the ADF flash memory

Parameters
typeThe ADF type
  • ADF_TYPE_SDK = SDK
  • ADF_TYPE_APP = Application
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) adf_getADFMode: (BOOL *)  enable

Get ADF Mode

Retrieves the state of the ADF environment

Parameters
enableTrue = ADF is enabled, False = ADF is disabled
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) adf_getModuleBytes: (ADF_TYPE)  type
adfInfo: (NSArray< NSData * > **)  adfInfo 

Get Module Bytes

Retrieves the first 64 bytes of the module information running in an ADF environment

Parameters
typeThe ADF type
  • ADF_TYPE_SDK = SDK
  • ADF_TYPE_APP = Application
adfInfoList of modules information
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) adf_getModuleInfo: (ADF_TYPE)  type
adfInfo: (NSArray **)  adfInfo 

Get Module Info

Retrieves the module information when running in an ADF environment

Parameters
typeThe ADF type
  • ADF_TYPE_SDK = SDK
  • ADF_TYPE_APP = Application
adfInfoList of modules information
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) adf_setADFMode: (BOOL)  enable

Set ADF Mode

Enables/Disables the ADF environment

Parameters
enableTrue = ADF enabled, False = ADF disabled
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) adf_setJTAG: (BOOL)  enable

Set JTAG

Enables/Disables the JTAG pin in an ADF environment

Parameters
enableTrue = JTAG enabled, False = JTAG disabled
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (void) close

Close Device

- (RETURN_CODE) config_checkDUKPTKey: (Byte)  keyIndex
value: (NSData **)  val 

Check DUKPT Key

This command checks whether a valid DUKPT key is stored at the specified slot and if a valid key is found then some basic information related to the type of key is returned. The actual key data is never returned. This command can be used to check whether a key is already present before injecting a key in a KeyIndex to prevent overwriting an existing DUKPT key.

Parameters
keyIndexData Encryption key (usually 5)
val-Byte 0 = Key State: 00h = Unused, 01h = Valid, 02h = End of Life, FFh = Not Available -Byte 1-2 = Key Usage (ASCII). "D0" = Used to encrypt data -Byte 3 = Algorithm (ASCII). "T" = Triple DES -Byte 4 = Mode of Use (ASCII). "E" = Encryption Only -Byte 5-6 = Key Version (ASCII). "00" = Key version not used
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) config_getDEKVariantType: (Byte *)  type

Get Data Encryption Key Variant Type

Returns the data encryption key type

Parameters
type-0 = Data Variant -1 = Pin Variant
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) config_getDUKPT_DEK_Attribution: (Byte)  keyslot
mode: (Byte *)  mode
outputModeWorkingKey: (Byte *)  outputMode_workingKey
variantKeyUsage: (Byte *)  variant_keyUsage 

Get DUKPT DEK Attribution based on KeySlot

Command settings can only be changed for each key one time

Parameters
keyslotKey Slot
mode0 = TDES, 1 = AES
outputMode_workingKey0 = TDES / TDES, 1 = AES-128 / TDES3 2 = TransArmor / AES-128, Output Mode is when TDES, Working Key is when AES
variant_keyUsage0 = Data Key / Encrypt/Decrypt, 1 = PIN Key / Encrypt, 2 = N/A / Decrypt, Variant is when TDES, Key Usage is when AES
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) config_getDUKPT_KSN: (NSData **)  KSN

Get DUKPT Key Serial Number (KSN)

Host can use this command to retrieve the KSN of the DUKPT key.

Parameters
KSNKey Serial Number
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) config_getKeyslot_PEK_DEK: (NSData **)  keyslotPEK
keyslotDEK: (NSData **)  keyslotDEK 

Get KeySlot for DUKPT PEK and DUKPT DEK

Returns the KeySlot for PEK and DEK (if they exist)

Parameters
keyslotPEKPEK KeySlot (0-9). Value of 255 (0xff) = does not exist
keyslotDEKDEK KeySlot (0-9). Value of 255 (0xff) = does not exist
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) config_getSalt_KCV: (NSData **)  KCV

Get Salt KCV

Host can use this command to retrieve the Salt KCV

Parameters
KCVKCV
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) config_getSerialNumber: (NSString **)  response

Polls device for Serial Number

Parameters
responseReturns Serial Number
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) config_setBluetoothParameters: (NSString *)  name
oldPW: (NSString *)  oldPW
newPW: (NSString *)  newPW 

Set BluetoothParameters

Sets the name and password for the BLE module.

Sending nil to all three parameters resets the default password to 123456

Parameters
nameDevice name, 1-25 characters
oldPWOld password, as a six character string, example "123456"
newPWNew password, as a six character string, example "654321"
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) config_setDEKVariantType: (Byte)  type

Set Data Encryption Key Variant Type

This command exists to specify the key variant type of Data encryption key (Slot = 0), and MUST be used before the initial loading of the Data encryption key into the device. The key variant type CANNOT be changed once the Data encryption key is present. It must remain either Data variant or PIN variant.

Parameters
type-0 = Data Variant -1 = PIN Variant
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) config_setDUKPT_DEK_Attribution_AES: (Byte)  keyslot
working_Key: (Byte)  workingKey
key_Usage: (Byte)  keyUsage 

Set DUKPT DEK Atribution based on KeySlot AES

Command settings can only be changed for each key one time

Parameters
keyslotKey Slot
workingKey0 = TDES, 1 = TDES3, 2 = AES-128
keyUsage0 = Encrypt/Decrypt, 1 = Encrypt, 2 = Decrypt
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) config_setDUKPT_DEK_Attribution_TDES: (Byte)  keyslot
output_Mode: (Byte)  outputMode
variant: (Byte)  variant 

Set DUKPT DEK Attribution based on KeySlot TDES

Command settings can only be changed for each key one time. However, switching the Output mode (TDES and TransArmor TDES) is always valid.

Parameters
keyslotKey Slot
outputMode0 = TDES, 1 = AES-128, 2 = TransArmor TDES
variant0 = Data Variant, 1 = PIN Variant
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) config_setKeyslot_PEK_DEK: (BOOL)  isPEK
keyslot: (Byte)  keySlot 

Set KeySlot for DUKPT PEK and DUKPT DEK

Selects one of the available PEKs for use in subsequent PIN encryption operations. Selects one of the available DEKs for use in subsequent Data encryption operations.

Parameters
isPEKTRUE = set PEK, FALSE = set DEK
keySlotThe KeySlot number specifies the key this command will select
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) config_setRKLKeys: (short)  keyNumber
tr31: (NSData *)  tr31
nonce: (NSData *)  nonce
hmac: (NSData *)  hmac
kv: (NSData **)  kv
nonceDevice: (NSData **)  nonce_device
hmacDevice: (NSData **)  hmac_device 

Set RKL Keys

Sets the RKL Keys

Parameters
keyNumberNumber of keys remaining to load
tr31ASN.1 structure of encrypted key(s)
nonceNonce generated by RKMS to generate an HMAC used for auth
hmacHMAC-SHA256 generated from RKMS
kvASN.1 Key Verification Structure returned from device
nonce_deviceNonce generated by the device to generate a MAC used for auth
hmac_deviceHMAC-SHA256 generated from device terminal
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
+ (NSString*) createFastEMVData: (IDTEMVData *)  emvData

Create Fast EMV Data

At the completion of a Fast EMV Transaction, after the final card decision is returned and the IDTEMVData object is provided, sending that emvData object to this method will populate return string data that represents the Fast EMV data that would be returned from and IDTech FastEMV over KB protocol

Parameters
emvDataThe IDTEMVData object populated with card data.
Returns
Fast EMV String data
- (RETURN_CODE) ctls_cancelTransaction

Cancels Transaction request (all interfaces, CTLS/MSR/INSERT).

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_getAllConfigGroups: (NSData **)  response

Get All Configuration Groups

Retrieves all Configuration Groups.

Parameters
response
- (RETURN_CODE) ctls_getAllConfigurationGroups: (NSDictionary< NSString *, NSDictionary * > **)  response

Get All Configuration Groups

Retrieves all Configuration Groups.

Parameters
responseGroups returned in a dictionary Key = <String>Group Value = <Dictionary<tag,value>>
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) ctls_getConfigurationGroup: (int)  group
response: (NSDictionary **)  response 

Get Configuration Group

Retrieves the Configuration for the specified Group. Group 0 = terminal settings.

Parameters
groupConfiguration Group
responseGroup TLV returned as a dictionary
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_nfcCommand: (NSData *)  systemCode
response: (NSData **)  response 

NFC Command

This command uses nfcCmdPkt[0] in command data field to implement different functions. This command should be used in Pass-Through mode and command with “Poll for a NFC Tag” data should be used first. Command with other data can only be used once the “Poll for a NFC Tag” command has indicated that a NFC tag is present.

Parameters
nfcCmdPktSystem Code
  • Poll for NFC Tag: nfcCmdPkt[0] = 0xff, nfcCmdPkt[1] = timeout value (in seconds)
  • Tag1 Static Get All Data: nfcCmdPkt[0] = 0x11
  • Tag1 Static Read a Byte: nfcCmdPkt[0] = 0x12, nfcCmdPkt[1] = Address of Data
  • Tag1 Static Write a Byte: nfcCmdPkt[0] = 0x13 nfcCmdPkt[1] = Address of Data, nfcCmdPkt[2] = Data to be written
  • Tag1 Static Write a Byte NE: nfcCmdPkt[0] = 0x14, nfcCmdPkt[1] = Address of Data, nfcCmdPkt[2] = Data to be written
  • Tag1 Dynamic Read a Segment: nfcCmdPkt[0] = 0x15, nfcCmdPkt[1] = Address of Segment
  • Tag1 Dynamic Read 8 Bytes: nfcCmdPkt[0] = 0x16, nfcCmdPkt[1] = Address of Data
  • Tag1 Dynamic Write 8 Bytes: nfcCmdPkt[0] = 0x17, nfcCmdPkt[1] = Address of Data, nfcCmdPkt[2]~nfcCmdPkt[9] = Data to be written
  • Tag1 Dynamic Write 8 Bytes NE: nfcCmdPkt[0] = 0x18, nfcCmdPkt[1] = Address of Data, nfcCmdPkt[2]~nfcCmdPkt[9] = Data to be written
  • Tag2 Read Data (16 bytes): nfcCmdPkt[0] = 0x21, nfcCmdPkt[1] = Address of Data
  • Tag2 Write Data (4 bytes): nfcCmdPkt[0] = 0x22, nfcCmdPkt[1] = Address of Data, nfcCmdPkt[2]~nfcCmdPkt[5] = Data to be written
  • Tag2 Select Sect: nfcCmdPkt[0] = 0x23, nfcCmdPkt[1] = Sect number
  • Tag3 Read Data: – nfcCmdPkt[0] = 0x41, – nfcCmdPkt[1] = Number of services, value n – nfcCmdPkt[2]~nfcCmdPkt[2n+1]: Service code list – nfcCmdPkt[2n+2]: Number of blocks, value m. – nfcCmdPkt[2n+3....]: Block list, length is 2m~3m
  • Tag3 Write Data: – nfcCmdPkt[0] = 0x41, – nfcCmdPkt[1] = Number of services, value n – nfcCmdPkt[2]~nfcCmdPkt[2n+1]: Service code list – nfcCmdPkt[2n+2]: Number of blocks, value m. – nfcCmdPkt[2n+3....]: Block list, length is 2m~3m – nfcCmdPkt[...]: Block data, length is 16m
  • Tag4 Command: nfcCmdPkt[0] = 0x81, nfcCmdPkt[1]~nfcCmdPkt[n]:data
responseResponse as explained in FeliCA Lite-S User's Manual
ipIP Address of target device (optional)
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_removeAllCAPK

Remove All Certificate Authority Public Key

Removes all the CAPK for CTLS

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_removeApplicationData: (NSString *)  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 as Hex String (example "A0000000031010") Must be between 5 and 16 bytes
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_removeCAPK: (NSData *)  capk

Remove Certificate Authority Public Key

Removes the CAPK for CTLS as specified by the RID/Index

Parameters
capk6 byte CAPK = 5 bytes RID + 1 byte INDEX
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_removeConfigurationGroup: (int)  group

Remove Configuration Group

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

Parameters
groupConfiguration Group
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_resetConfigurationGroup: (int)  group

Reset Configuration Group

This command allows resetting a dataset to its default configuration If the file exists, it will be overwritten. If not, it will be created

Parameters
groupConfiguration group
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_VP3300::device_getResponseCodeString:()
- (RETURN_CODE) ctls_retrieveAIDList: (NSArray **)  response

Retrieve AID list

Returns all the AID names installed on the terminal for CTLS.

Parameters
responsearray of AID name as NSData*
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_retrieveApplicationData: (NSString *)  AID
response: (NSDictionary **)  response 

Retrieve Application Data by AID

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

Parameters
AIDName of ApplicationID as Hex String (example "A0000000031010"). Must be between 5 and 16 bytes
responseThe TLV elements of the requested AID
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_retrieveCAPK: (NSData *)  capk
key: (NSData **)  key 

Retrieve Certificate Authority Public Key

Retrieves the CAPKfor 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: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_retrieveCAPKList: (NSArray **)  keys

Retrieve the Certificate Authority Public Key list

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

Parameters
keysNSArray of NSData CAPK name (RID + Index)
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_retrieveTerminalData: (NSData **)  tlv

Retrieve Terminal Data

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

Parameters
tlvResponse returned as a TLV
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_setApplicationData: (NSData *)  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 (DFEE2D). The second tag of the TLV data must be the AID (9F06)

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

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_setCAPK: (NSData *)  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 device_getResponseCodeString:
- (RETURN_CODE) ctls_setConfigurationGroup: (NSData *)  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 (DFEE2D). A second tag must exist
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_setTerminalData: (NSData *)  tlv

Set Terminal Data

Sets the Terminal Data for CTLS transaction and general terminal settings as specified by the TLV. If the value already exists in terminal data, it will be updated. If the value does not exist, it will be added.

Parameters
tlvTerminalData configuration data
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_VP8800::device_getResponseCodeString:()
- (RETURN_CODE) ctls_startTransaction: (double)  amount
type: (int)  type
timeout: (int)  timeout
tags: (NSMutableDictionary *)  tags 

Start a CTLS Transaction Request

Authorizes the CTLS transaction for an CTLS card

The tags will be returned in the callback routine.

Parameters
amountTransaction amount value (tag value 9F02)
exponentNumber of characters after decimile point
typeTransaction type (tag value 9C).
timeoutTimeout value in seconds.
tagsAny other tags to be included in the request.
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:

NOTE ON INTERFACE SELECTION: For the NEO2, tag DFEF37 is used to determine which interfaces to use for the transaction:

  • 01 = MSR Only
  • 02 = CTLS Only
  • 03 = MSR + CTLS
  • 04 = EMV Only
  • 05 = EMV + MSR
  • 06 = EMV + CTLS
  • 07 = EMV + MSR + CLTS. This API method will automatically send DFEF37 with a value of 02 if this tag is not provided.
- (RETURN_CODE) ctls_updateBalance: (NSData *)  statusCode
authCode: (NSData *)  authCode
date: (NSData *)  date
time: (NSData *)  time 

Update Balance

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

This command is also being ussed in some implementations (i.e. EMEA) to communicate the results of Issuer Authorization 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 (authCode)/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: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_addTLVToTerminalData: (NSData *)  tlv

Add Terminal Data

Adds the specified TLV to the current terminal data .

Parameters
tlvThe data to set, overwriting any existing value
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) device_antennaControl: (bool)  turnON

Antenna Control

The Antenna Control command turns the RF Antenna ON or OFF.

Parameters
turnONTRUE = ON, FALSE = OFF
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_buzzerOnOff

Buzzer OnOff

Causes the buzzer to beep once

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_cancelTransaction

Cancels Transaction request (all interfaces, CTLS/MSR/INSERT).

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_certificateType: (int *)  type

Device Certificate Type

Returns the device certificate type

Parameters
type0 = Unknown, 1 = Demo, 2 = Production
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (NSUUID*) device_connectedBLEDevice

Returns the UUID of the connected BLE device

  • NEO2

    Returns
    NSUUID UUID of the connected BLE device. Returns nil if no BLE device connected.
- (RETURN_CODE) device_controlLED: (Byte)  indexLED
control: (Byte)  control 

Control LED

Controls the LED for the reader. This command will only operate in pass-through mode

Parameters
indexLEDThe LED to control starting from the left
  • 00: LED 0
  • 01: LED 1
  • 02: LED 2
  • 03: LED 3
  • FF: All LEDs
controlTurns chosen LED(s) OFF (00) or ON (01)
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_controlUserInterface: (NSData *)  values

Control User Interface

Controls the Display, Beep, and LED

Parameters
valuesFour bytes to control the user interface elements Byte[0] = LCD Message
  • 00h: Idle Message (Welcome)
  • 01h: Present Card (Please Present Card)
  • 02h: Timeout or Transaction Canceled (No Card)
  • 03h: Transaction between reader and card is in progress (Processing...)
  • 04h: Transaction success (Thank You)
  • 05h: Transaction failed (Failed)
  • 06h: Amount (Amount $ 0.00 Tap Card)
  • 07h: Balance or Offline available funds (Balance $ 0.00)
  • 08h: Insert 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: Triple beep
  • 04h: Quadruple beep
  • 05h: Single long beep (200 ms)
  • 06h: Single long beep (400 ms)
  • 07h: Single long beep (600 ms)
  • 08h: Single long beep (800 ms) Byte[2] = LED
  • 00h: LED 0 (Power LED)
  • 01h: LED 1
  • 02h: LED 2
  • 03h: LED 3
  • FFh: All LEDs Byte[3] = LED Power
  • 00h: LED OFF
  • 01h: LED ON
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_createDirectory: (NSString *)  directoryName

Create Directory

This command adds a subdirectory to the indicated path

Parameters
directoryNameThe directory name. The data for this command is an ASCII string with the complete path and directory name you want to create. You do not need to specify the root directory. Indicate subdirectories with a forward slash (/)
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_deleteDirectory: (NSString *)  filename

Delete Directory

This command deletes an empty directory

Parameters
filenameComplete path of the directory you want to delete.
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_deleteFile: (NSString *)  filename
isSD: (BOOL)  isSD 

Delete File

This command deletes a file or group of files

Parameters
filenameComplete path and file name of the file you want to delete. You do not need to specify the root directory. Indicate subdirectories with a foward slash (/)
isSDTrue = Delete from SD card, False = Delete from Flash
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (bool) device_disableBLEDeviceSearch

Stops searching for Bluetooth Low Energy devices in range

  • NEO2

    Returns
    bool If successful, polling was in progress and has stopped. If unsuccessful, BLE Device Search was not in progress.

    NOTE: BLE only scans when there are no devices currently connected. After the SDK connects to any IDTech device, the scanning will pause automatically.

- (RETURN_CODE) device_disBlueLED

Disable Blue LED Sequence

Stop the blue LEDs on the ViVOpay Vendi reader from flashing in the left to right sequence and the LEDs off. Contactless function is also disabled at the same time

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (void) device_disconnectBLE

Disconnect from BLE -

Will disconnect from existing BLE connection. You can now set another BLE Friendly Name to attach to another device.

- (bool) device_enableBLEDeviceSearch: (NSUUID *)  identifier

Begins searching for Bluetooth Low Energy devices in range

  • NEO2

    This method will UNPAIR and DISCONNECT from any current PAIRED and CONNECTED devices before starting a new BLE Device Search. This function is for PAIRING a new Device and connecting to it. Once a device is PAIRED/CONNECTED, the search will terminate. If a paired devices becomes disconnected (out of range, power cycle), the BLE search will automatically start again to reconnect to the devices once available

    Parameters
    identifierThis will only connect to a device with this calculated UUID identifier. If nil is passed, it will connect to the first devices with the default friendly name (device_getBLEFriendlyName / IDT_NEO2::device_setBLEFriendlyName)
    Returns
    bool If successful, polling has started

    Any of the following BLE status messages may be returned to the deviceMessage delegate:

  • This device does not support Bluetooth Low Energy.
  • This app is not authorized to use Bluetooth Low Energy.
  • Bluetooth on this device is currently powered off.
  • The BLE Manager is resetting; a state update is pending.
  • Bluetooth LE is turned on and ready for communication.
  • The state of the BLE Manager is unknown.

    Note: a Devices UUID is calculated by the iOS device using a combiniation of the iOS device UUID and the BLE device MAC address. This value is not known until after it connects for the first time, and then every time after that, it will be the same value. This value can be retrieved by IDT_Device::connectedBLEDevice() after the device connects.

- (RETURN_CODE) device_enableL100PassThrough: (BOOL)  enablePassThrough

Enable L100 Passthrough

Enable passthrough mode for direct communication to L100 hooked up to NEO2 device

Parameters
enablePassThroughTrue = passthrough ON, False = passthrough OFF
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_enableL80PassThrough: (BOOL)  enablePassThrough

Enable L80 Passthrough

Enables Passthrough mode for direct communicaiton to L80 hooked up to NEO2 device

Parameters
enablePassThroughTrue = passthrough ON, False = passthrough OFF
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_enaBlueLED: (NSData *)  dataCmd

Enable the blue LED and modify the behaviour

Control the blue LED behaviour on the Vendi reader

Parameters
dataCmdLED control. Minimum 4 bytes, maximum 25 bytes. First byte is cycle, next three bytes are the sequence. Then sequence can repeat up to 8 times.
  • Byte 0 = Cycle (0 = Cycle once, 1 = Repeat)
  • Byte 1 = LED state map
    • bit 7 = Left blue LED
    • bit 6 = Center blue LED
    • bit 5 = Right blue LED
    • bit 4 = Yellow LED
    • bit 3 = Reserved
    • bit 2 = Reserved
    • bit 1 = Reserved
    • bit 0 = Reserved
  • Bytes 2 & 3 = Duration (Given in multiples of 10 ms, i.e. 10/20/30 etc.) If Cycle = 1, more pairs be after 3
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_enterStandbyMode

Enter standby mode

Puts unit into low power standby mode

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_exchangeContactlessData: (NSData *)  sendData
receiveData: (NSData **)  receiveData 

Exchange Contactless Data

The Echange Contactless Data command allows the host device to send, via the ViVOpay reader, application-level APDUs to a PICC that supports ISO 14443-4 Protocol. The reader sends the PICC response back to the host

Parameters
sendDataAPDU Out
receiveDataAPDU response
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_extendedErrorCondition: (BOOL)  enable

Extended Error Condition

Enables/disables extended error condition for commands 02-40, 61-xx, 62-xx, 83-41 when error is 0xd0a or 0xd0b

Parameters
enableTRUE = enable log, FALSE = disable log
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_get1050BootloaderVersion: (NSString **)  version

Get 1050 Bootloader Version

Polls the device for the 1050 bootloader version

Parameters
versionResponse returned of the 1050 bootloader version
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_get1050DeviceTreeVersion: (NSString **)  deviceTree

Get 1050 Device Tree

Polls the NEO2/3 for the 1050 Device Tree

Parameters
deviceTreeThe device tree returned as a NSString
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_get1050FuseStatus: (NSData **)  status

RT1050 SRK Fuse Status

This command retrieves the status fo the reader's RT1050 SRK fuse

Parameters
statusFirst 8 bytes of the SRK Fuse, if programmed. Otherwise, an empty array is returned
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_getAutoPollTransactionResults: (IDTEMVData **)  result

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

Parameters
resultThe transaction results
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:. When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
- (NSString*) device_getBLEFriendlyName

Get BLE Friendly Name

Returns
NSString Returns the default friendly name to be used when discovering any BLE devices
- (RETURN_CODE) device_getBootloaderVersion: (NSString **)  response

Get Bootloader Version

Polls the device for the bootloader version

Parameters
responseResponse return of the bootloader version from the device
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_getDeviceTreeVersion: (NSString **)  deviceTree
is1050: (BOOL)  is1050 

Get Device Tree

Polls the NEO2/3 for the Device Tree

Parameters
deviceTreeThe device's tree returned as a NSString
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_getFirmwareVersion: (NSString **)  response

Polls device for Firmware Version

Parameters
responseResponse returned of Firmware Version
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to IDT_UniPay::device_getResponseCodeString:()
- (RETURN_CODE) device_getHardwareInfo: (NSString **)  response

Get Hardware Info

Returns an ASCII string for the hardware information

response The ASCII character string

ASCII | Description

HW,VPVendi<CR><LF>K21F Rev9 | Vendi HW,VP3300 Audio Jack<CR><LF>K21F Rev9 | Unipay III HW,VPUnipay1.5<CR><LF>K21F Rev9 | Unipay 1.5 HW,VPUniPay1.5TTK<CR><LF>K21F Rev9 | UniPay 1.5 TTK HW,VP3300 USB<CR><LF>K21F Rev9 | VP3300 USB, VP3300 USB OEM (iBase/Cake same code, string ident = "") HW,VP3300 USB-E<CR><LF>K21F Rev9 | VP3300 USB-E HW,VP3300 USB-C<CR><LF>K21F Rev9 | VP3300 USB-C HW,VPVP3300 Bluetooth<CR><LF>K21F Rev9 | VP3300 Bluetooth HW,.VP6300<CR><LF>K81F.Rev4 | VP6300

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_getLightSensorVal: (UInt16 *)  lightVal

Get Light Sensor Value

Gets the value from the sensor

Parameters
lightValValue of the light sensor
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_getMerchantRecord: (int)  index
record: (NSData **)  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 device_getResponseCodeString:
- (RETURN_CODE) device_getModuleVer: (NSString **)  moduleVer

Get Module Version Information

Gets the 16 byte UID of the MCU

Parameters
uidThe string representation of the UID
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_getMsrSecurePara: (BOOL)  b0
b1: (BOOL)  b1
b2: (BOOL)  b2
b3: (BOOL)  b3
tlv: (NSData **)  tlv 

Get MSR Secure Parameters

Gets the parameters from the flash setting

Parameters
b0True = T1 force encryption
b1True = T2 force encryption
b2True = T3 force encryption
b3True = T3 force encryption when card type is 80
tlvMSR secure parameters TLV objects
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_getPollMode: (NSData **)  mode

Get Poll Mode

Gets the current poll mode of the device

Parameters
modeResponse from the device of the current poll mode
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_getProcessorType: (NSData **)  type

Get Processor Type

Returns a processor type TLV

type Processor type

Processor Type | Description

45 00 | ARM7/ LPC21xx 4D 00 | ARM Cortex-M4/ K21 Family 4E 00 | ARM Cortex-M4/ K81 Family

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_getProductType: (NSData **)  type

Get Product Type

Returns a "product type" value in a proprietary TLV

type Product type

Product Type | Description

42 37 00 | ViVOpay 5000 43 33 00 | ViVOpay 4500 43 35 00 | ViVOpay Vend 43 36 00 | Vendi (NEO, string ident = "") 43 37 00 | ViVOpay Kiosk1 (ATM1, string ident = "") 43 38 00 | Kiosk2 43 39 00 | Kiosk3 (NEO, string ident = "") 55 31 00 | UniPay 1.5 (NEO, string ident = "") 55 33 00 | UniPay III (NEO) 55 33 31 | VP3300, VP3300 OEM (NEO) (iBase/Cake same code, string ident = "") 55 33 32 | VP3300E(NEO, string ident = "") 55 33 33 | VP3300C(NEO, string ident = "") 55 33 34 | BTPay Mini (NEO) (UniPayIII + BLE, string ident = "") 56 31 00 | VP3600 56 32 00 | VP5200 56 33 00 | VP5300 56 34 00 | VP6300 56 35 00 | VP6800 56 36 00 | VP8300 56 37 00 | VP8310 56 38 00 | VP8800 56 39 00 | VP8810 56 40 00 | VP9000 44 30 00 | QX120 44 31 00 | Mx8Series 44 32 00 | NETs 44 33 00 | Magtek 44 35 00 | ICP

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (NSString *) device_getResponseCodeString: (int)  errorCode

Get Response Code String

Interpret a response code and return string description.

Parameters
errorCodeError code, range 0x0000 - 0xFFFF, example 0x0300
Returns
Verbose error description
- (RETURN_CODE) device_getRT1050FirmwareVersion: (NSString **)  response

Get RT1050 Firmware Version

Gets the version for the RT1050 Firmware

Parameters
responseResponse returned of the RT1050 firmware
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_getSpecialFunctionOrFeature: (NSData **)  feature
addRequirement: (NSData **)  addRequirement 

Get Special Function or Feature Configuration Command

The Get Special Function or Feature Configuration command returns the specific special configuration.

Parameters
featureFunction/Feature ID
addRequirementAdditional Requirement
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_getTransactionResults: (NSData **)  results

Get Transaction Results

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

Parameters
resultsThe transaction results
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_getTransArmorID: (NSString **)  TID

Get TransArmor ID

Gets the TransArmor ID from the device

Parameters
TIDTransArmor ID
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_getUIDofMCU: (NSString **)  response

Get UID of MCU

Returns the UID of the device

Parameters
responseThe module UID information
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (bool) device_isConnected: (IDT_DEVICE_Types)  device

Is Device Connected

Returns the connection status of the requested device

Parameters
deviceCheck connectivity of device type
typedef enum{
IDT_DEVICE_NEO2_IOS = 16
}IDT_DEVICE_Types;
- (RETURN_CODE) device_listDirectory: (NSString *)  directoryName
recursive: (BOOL)  recursive
onSD: (BOOL)  onSD
directory: (NSString **)  directory 

List Directory

This command retrieves a directory listing of user accessible files from the reader

Parameters
directoryNameThe directory name. If null, root directory is selected
recursiveInclude sub-directories
onSDTrue = use SD card, False = use Flash
directoryThe returned directory information
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_listenForNotifications: (BOOL)  enable

Listen for Notifcations

Instructs SDK to listen for unsolicited data

Parameters
enableTrue = Listen, False = Don't listen
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_loadCertCA: (Byte)  type
CertData: (NSData *)  cert 

Load CA Certificate

Loads the CA certificate data onto the device

Parameters
typeThe type of certificate -00h: Application CA -01h: TLS CA
certThe certificate data bytes
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_logClear

Log Clear

Instructs the device to delete all log data

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_logEnable: (BOOL)  enable

Enable Log

Instructs the device to enable/disable the log

Parameters
enableTrue = enable log, False = disable log
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_logRead: (NSData **)  response

Log Read

Instructs the device to output all log data

Parameters
responseFull response received from NEO2 device, including log
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_lowPowerMode: (BOOL)  stopMode
wakeOnTrans: (BOOL)  wakeOnTrans 

Enter Low Power Mode

Puts the terminal in sleep or stop mode, with the option to wake on swipe/tap

Parameters
stopModeTrue = Stop Mode (POR required), False = Sleep Mode (resume from last instruction)
wakeOnTransTrue = Swipe/Tap will wake from low power, False = Will not wake from swipe/tap
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_offYellowLED

Turn Off Yellow LED

Turn off the ViVOpay Vendi reader yellow LED. This LED is located below the three blue LEDs

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_onYellowLED

Turn On Yellow LED

Turn on the ViVOpay Vendi reader yellow LED. This LED is located below the three blue LEDs

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_pingDevice

Ping Device

Pings the reader. If it is connected, returns success, otherwise returns timeout

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_pollForToken: (Byte)  seconds
card: (Byte **)  card
serialNumber: (NSData **)  serialNumber 

Poll for Token

Once Pass-Through Mode is started, ViVOpay will not poll for any cards until the “Poll for Token” command is received. This command tells ViVOpay to start polling for a Type A or Type B PICC until a PICC is detected or a timeout occurs.

This command automatically turns the RF Antenna on.

If a PICC is detected within the specified time limit, ViVOpay activates it and responds back to the terminal with card related data such as the Serial Number. If no PICC is detected within the specified time limit, ViVOpay stops polling and responds back indicating that no card was found. No card related data is returned in this case

Parameters
timeoutTimeout, in seconds to wait for card to be detected
cardCard Type:
  • 00h None (Card Not Detected or Could not Activate)
  • 01h ISO 14443 Type A (Supports ISO 14443-4 Protocol)
  • 02h ISO 14443 Type B (Supports ISO 14443-4 Protocol)
  • 03h Mifare Type A (Standard)
  • 04h Mifare Type A (Ultralight)
  • 05h ISO 14443 Type A (Does not support ISO 14443-4 Protocol)
  • 06h ISO 14443 Type B (Does not support ISO 14443-4 Protocol)
  • 07h ISO 14443 Type A and Mifare (NFC phone)
serialNumberSerial Number or the UID of the PICC
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_queryFile: (NSString *)  directory
filename: (NSString *)  filename
isSD: (BOOL)  isSD
exists: (BOOL *)  exists
timestamp: (NSDate **)  timestamp
fileSize: (int *)  fileSize 

Query File

Report if tthe file exists, and if so will report the file timestamp and the file size

Parameters
directoryThe file directory to search in. If blank, will use the root directory
filenameName of the file to retrieve
isSDTrue = query SD card, False = query internal storage
existsTrue = file exists, False = file does not exist
timestampIf the file exists, reports the timestamp of the file
fileSizeIf the file exists, reports the size of the file
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_readFileFromSD: (NSString *)  directory
filename: (NSString *)  filename
fileData: (NSData **)  fileData 

Read File from SD card

Reads a file from the SD card

Parameters
directoryThe file directory to read from. If empty, the root directory is used
filenameThe name of the file to retrieve
fileDataThe contents of the file if it exists
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_rebootDevice

Reboot Device

  • NEO2
  • VP3300 -VP8800 -UniPayI_V

Executes a command to restart the device.

Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) device_resetNVM

Reset non-volatile memory

The Set Configuration Defaults and Keep Encryption Key command provides an external method for resetting parameters in non-volatile memory (NVM) to their default values. When the reader receives this command, it erases EEPROM (but retains encryption keys). After completing initialization, the reader reboots.

Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_retrieveTerminalData: (NSData **)  responseData

Retrieve Terminal Data

Retrieves the Terminal Data . The Terminal Data will be in the response parameter responseData

Parameters
responseDataThe response returned from the method as NSData
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) device_rrcConnect

RRC Connect

The RRC Connect command allows a host to establish an RRC connection to a reader. A host must first establish an RRC connection to the reader before issuing other RRC IDG commands.

Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_rrcDisconnect

RRC Disonnect

The RRC Disonnect command allows a host to terminate the RRC connection to a reader.

Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_rrcDownloadApp: (NSString *)  appName
appData: (NSData *)  appData 

RRC Download Application

The RRC Download Application command allows the transfer of a compressed application file from a host to a reader, extracts it, and performs signature verification on its contents

The reader receives all the chunked data from the host and, once completed, the reader combines it into one file

Parameters
appNameThe name of the application that appears on the Application Manager list
appDataThe compressed application file to be sent in chunks
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_rrcInstallApp: (NSString *)  appName

RRC Install Application

The RRC Install Application command installs a downloaded application to a reader. Only installed applications can run on the reader.

Parameters
appNameThe name of the application that will appear on the Application Manager list
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_rrcRunApp: (NSString *)  appName

RRC Run application

This command allows the reader to run an installed application

Parameters
appNameThe name of the installed application to run
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_rrcUninstallApp: (NSString *)  appName

RRC Uninstall Application

The RRC Uninstall Application command uninstalls an application on a reader device. The application will remain in the file system of the reader but cannot be executed.

Parameters
appNameThe name of the application that appears on the Application Manager list
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) device_sendIDGCommand: (unsigned char)  command
subCommand: (unsigned char)  subCommand
data: (NSData *)  data
response: (NSData **)  response 

Send NEO IDG Command Send a NEO IDG ViVOtech 2.0 command

Parameters
commandOne byte command as per NEO IDG Reference Guide
subCommandOne byte sub-command as per NEO IDG Reference Guide
dataCommand data (if applicable)
responseReturns next Command response
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_UniMagIII::device_getResponseCodeString:()
- (RETURN_CODE) device_sendIDGCommandV3: (unsigned char)  command
subCommand: (unsigned char)  subCommand
data: (NSData *)  data
response: (NSData **)  response 

Send NEO IDG Command Send a NEO IDG ViVOtech 3.0 command

Parameters
commandOne byte command as per NEO IDG Reference Guide
subCommandOne byte sub-command as per NEO IDG Reference Guide
dataCommand data (if applicable)
responseReturns next Command response
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_UniMagIII::device_getResponseCodeString:()
- (void) device_setBLEFriendlyName: (NSString *)  friendlyName

Set BLE Friendly Name

Parameters
friendlyNameSets the default friendly name to be used when discovering any BLE devices
- (RETURN_CODE) device_setBurstMode: (int)  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 device_getResponseCodeString:
- (RETURN_CODE) device_setMerchantRecord: (int)  index
enabled: (bool)  enabled
merchantID: (NSString *)  merchantID
merchantURL: (NSString *)  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 device_getResponseCodeString:
- (RETURN_CODE) device_setPassThrough: (BOOL)  enablePassThrough

Set Pass Through

Sets Pass-Through mode on NEO2

Parameters
enablePassThroughTRUE = Pass through enabled
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) device_setPollMode: (int)  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 device_getResponseCodeString:
- (RETURN_CODE) device_setSpecialFunctionOrFeature: (NSData *)  feature
addRequirement: (NSData *)  addRequirement 

Set Special Function or Feature Configuration Command

The Set Special Function or Feature Configuration command sets a specific special configuration.

Parameters
featureFunction/Feature ID
addRequirementAdditional Requirement
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_setTerminalData: (NSData *)  tags

Set Terminal Data

Sets the Terminal Data .

Parameters
responseDataThe data to set
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) device_setTransArmorEncryption: (NSData *)  cert

Set TransArmor Encryption

Sets the TransArmor encryption from the given certificate

Parameters
certCertificate in PEM format or DER format. PEM format must be string data (converted to binary) starting with "---". DER format is binary data.
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) device_setTransArmorID: (NSString *)  TID

Set TransArmor ID

Sets the TransArmor ID

Parameters
TIDTransArmor ID
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) device_startTransaction: (double)  amount
type: (int)  type
timeout: (int)  timeout
tags: (NSData *)  tags 

Start a Transaction Request

Authorizes the CTLS transaction for an CTLS card

The tags will be returned in the callback routine.

Parameters
amountTransaction amount value (tag value 9F02)
exponentNumber of characters after decimile point
typeTransaction type (tag value 9C).
timeoutTimeout value in seconds.
tagsAny other tags to be included in the request.
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:

NOTE ON INTERFACE SELECTION: For the NEO2, tag DFEF37 is used to determine which interfaces to use for the transaction:

  • 01 = MSR Only
  • 02 = CTLS Only
  • 03 = MSR + CTLS
  • 04 = EMV Only
  • 05 = EMV + MSR
  • 06 = EMV + CTLS
  • 07 = EMV + MSR + CLTS. This API method will automatically send DFEF37 with a value of 07 if this tag is not provided.

    USE tag DFEF3C for fallback support and timeout waiting for insertion byte 1: = fallback support 01 = YES, 00 = NO byte 2-3 = timeout in BCD. Example 60 seconds is 0060

- (RETURN_CODE) emv_authenticateTransaction: (NSData *)  tags

Authenticate Transaction

Authenticates a transaction after startTransaction successfully executes.

By default, auto authorize is ENABLED. If auto authorize is DISABLED, this function must be called after a result EMV_RESULT_CODE_START_TRANSACTION_SUCCESS returned to emvTransactionData delegate protocol is received after a startTransaction call. If auto authorize is ENABLED (default), this method will automatically be executed after receiving the result EMV_RESULT_CODE_START_TRANSACTION_SUCCESS after startTransaction. The auto authorize can be enabled/disabled with IDT_DEVICE::disableAutoAuthenticateTransaction:()

The purpose of this step is to allow the merchant the chance to evaluate the data captured from the matching Application (if found) before the kernel authenticates the transaction data. This would allow, for instance, the merchant to be told what card is being used, and if it is a specific type (like a store card), perform an action like reducing the amount before proceeding (as a promotion in using that card).

Parameters
tagsAny tags to modify original tags submitted with startTransaction. Passed as NSData. Example, tag 9F0C with amount 0x000000000100 would be 0x9F0C06000000000100 Tag DFEE1A can be used to specify tags to be returned in response, in addition to the default tags. Example DFEE1A049F029F03 will return tags 9F02 and 9F03 with the response
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) emv_callbackResponseKSN: (NSData *)  KSN

Callback Response Get ETC DUKPT key KSN

Provides a status code to device request of DUKPT IK loaded status, from callback type GET KSN

Parameters
KSNThe KSN data
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) emv_callbackResponseLCD: (int)  mode
selection: (unsigned char)  selection 

Callback Response LCD Display

Provides menu selection responses to the kernel after a callback was received lcdDisplay delegate.

Parameters
modeThe choices are as follows
  • 0x00 Cancel
  • 0x01 Menu Display
  • 0x02 Normal Display get Function Key supply either 0x43 ('C') for Cancel, or 0x45 ('E') for Enter/accept
  • 0x08 Language Menu Display
selectionLine number in hex (0x01, 0x02), or 'C'/'E' of function key
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) emv_callbackResponseMSR: (NSData *)  MSR

Callback Response MSR Entry

Provides MSR information to kernel after a callback was received with type EMV_CALLBACK_MSR

Parameters
MSRSwiped track data
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) emv_callbackResponsePIN: (EMV_PIN_MODE_Types)  mode
KSN: (NSData *)  KSN
PIN: (NSData *)  PIN 

Callback Response PIN Request

Provides PIN data to the kernel after a callback was received pinRequest delegate.

Parameters
modePIN Mode:
  • EMV_PIN_MODE_CANCEL = 0X00,
  • EMV_PIN_MODE_ONLINE_PIN_DUKPT = 0X01,
  • EMV_PIN_MODE_ONLINE_PIN_MKSK = 0X02,
  • EMV_PIN_MODE_OFFLINE_PIN = 0X03
KSNKey Serial Number. If no pairing and PIN is plaintext, value is nil
PINPIN data, encrypted. If no pairing, PIN will be sent plaintext
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) emv_callbackResponsePIN_ETC: (EMV_PIN_MODE_Types)  type
ksn: (NSData *)  KSN
pin: (NSData *)  PIN 

Callback Response PIN Entry for ETC

Provides (or cancels) PIN entry information to kernel after a callback was received with callback type PINPAD ETC

Parameters
typeIf cancel button is pressed during PIN entry, then this value is EMV_PIN_MODE_CANCEL
  • If PIN bypass is pressed during PIN entry, then this value is EMV_PIN_MODE_BYPASS. Otherwise the value can be EMV_PIN_MODE_ONLINE_DUKPT, EMV_PIN_MODE_ONLINE_MKSK, or EMV_PIN_MODE_OFFLINE
KSNIf enciphered PIN, this is either PINK DUKPT Key or PIN Session Key or PIN Pairing DUKPT
PINIf enciphered PIN, this is an ecrypted PIN block. If device does not implement pairing fuctions, this plaintext PIN
- (RETURN_CODE) emv_cancelTransaction

Cancels Transaction request (all interfaces, CTLS/MSR/INSERT).

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) emv_completeOnlineEMVTransaction: (BOOL)  isSuccess
hostResponseTags: (NSData *)  tags 

Complete EMV Transaction Online Request

Completes an online EMV transaction request by the card

The tags will be returned in the emvTransactionData delegate protocol.

Parameters
isSuccessDetermines if connection to host was successful:
  • TRUE: Online processing with the host (issuer) was completed
  • FALSE: Online processing could not be completed due to connection error with the host (issuer). No further data (tags) required.
tagsHost response tag (see below)
Host response tag:
Tag Length Description
8A 2 Data element Authorization Response Code. Mandatory
91 8-16 Issuer Authentication Data. Optional
71 0-256 Issuer Scripts. Optional
72 0-256 Issuer Scripts. Optional
DFEE1A 0-256 Tag list of additional tags to return

Tag DFEE1A will force additional tags to be returned. Example DFEE1A049F029F03 will return tags 9F02 and 9F03 with the response

Returns
RETURN_CODE:
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0xFE00: Authorization Accepted - RETURN_CODE_EMV_AUTHORIZATION_ACCEPTED
  • 0xFE01: Online Failure - RETURN_CODE_EMV_AUTHORIZATION_UNABLE_TO_GO_ONLINE
  • 0xFE02: Technical Issue - RETURN_CODE_EMV_AUTHORIZATION_TECHNICAL_ISSUE
  • 0xFE03: Declined - RETURN_CODE_EMV_AUTHORIZATION_DECLINED
  • 0xFE04: Issuer Referral - RETURN_CODE_EMV_AUTHORIZATION_ISSUER_REFERRAL
- (void) emv_disableAutoAuthenticateTransaction: (BOOL)  disable

Disable Auto Authenticate Transaction

If auto authenticate is DISABLED, authenticateTransaction must be called after a successful startEMV execution.

Parameters
disableFALSE = auto authenticate ENABLED, TRUE = auto authenticate DISABLED
- (RETURN_CODE) emv_exchangeCerts: (NSData **)  cert
nonce: (NSData **)  nonce
signature: (NSData **)  signature 

Exchange Certificates, Nonces, and Keys

Use this command to send the ETC certificate, nonce, and signature The returned data is the NEO2 certificate, nonce, and signature

Parameters
certSend ETC certificate for signature verification, Receives NEO2 certificate for signature verification
nonceSend ETC random nonce, Receives NEO2 random nonce
signatureSend ETC signature, Receives NEO2 signature. Signature of (CertETC_SV || NONCE_ETC) with PKCS1-v1_5 padding
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) emv_generateDUKPT: (NSData *)  cert
signature: (NSData *)  signature
key: (NSData **)  key 

Generate DUKPT IK using KEK

Use this command to send the encrypted KEK and signature generated by the ETC. NEO2 returns the DUKPT IK in TR-31 format encrypted with the KEK and signature

Parameters
certETC certificate for signature verification
signatureSignature of (KEK || NONCE_ETC) with PKCS1-v1_5 padding
keyASN.1 structure of DUKPT IK used between NEO2 and ETC
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) emv_getBatteryPercentage: (NSString **)  response

Battery Percentage

Polls the device for the current battery percentage

Parameters
responseReturns the battery percentage represented as a whole number 5 - 100%
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (RETURN_CODE) emv_getBatteryVoltage: (NSString **)  response

Battery Voltage

Polls the device for the current battery voltage

Parameters
responseReturns battery voltage string representing millivolts
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) emv_getEMVConfigurationCheckValue: (NSString **)  response

Get EMV Configuration Check Value

Polls device for the EMV Configuration Check Value

Parameters
responseResponse returned of the Check Value of the Configuration
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) emv_getEMVKernelCheckValue: (NSString **)  response

Get Kernel Check Value

Polls the device for the Kernel Check Value

Parameters
responseResponse returned of the Check Value of the Kernel
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) emv_getEMVKernelVersion: (NSString **)  response

Get EMV Kernel Version

Polls the device for the EMV Kernel Version

Parameters
responseThe kernel version response in a string
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) emv_getEMVKernelVersionExt: (NSString **)  response

Get Extended EMV Kernel Version

Polls the device for the extended EMV kernel version

Parameters
responseThe extended kernel verion response in a string
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) emv_getEMVL2Version: (NSString **)  response

Polls device for EMV L2 Version

Parameters
responseResponse returned of Level 2 Version
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) emv_getTerminalMajorConfiguration: (NSUInteger **)  configuration

Gets the terminal major configuration in ICS .

Parameters
configurationA configuration value, range 1-5
  • 1 = 1C
  • 2 = 2C
  • 3 = 3C
  • 4 = 4C
  • 5 = 5C
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) emv_removeAllApplicationData

Remove All Application Data

Removes all the application data for the EMV kernel

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) emv_removeApplicationData: (NSString *)  AID

Remove Application Data by AID

This will REMOVE the an AID configuration file and all the tlv data associated with that AID.

Parameters
AIDName of ApplicationID in ASCII, example "A0000000031020". Must be between 5 and 16 characters If null or empty string is passed, it will remove ALL application data
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to BTPay::device_getResponseCodeString:()
- (RETURN_CODE) emv_removeCAPK: (NSString *)  rid
index: (NSString *)  index 

Remove Certificate Authority Public Key

Removes the CAPK as specified by the RID/Index passed as a parameter in the CAKey structure

Parameters
ridRID of the key to remove
indexIndex of the key to remove
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to IDT_UniPayII::device_getResponseCodeString:()
- (RETURN_CODE) emv_removeCRLList

Remove Certificate Revocation List

Removes all CRLEntry entries

Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to IDT_UniPayII::device_getResponseCodeString:()
- (RETURN_CODE) emv_removeTerminalData

Remove Terminal Data

This will remove ALL configurable TLV data associated with the terminals Kernel configuration.

Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to IDT_UniPayII::device_getResponseCodeString:()
- (RETURN_CODE) emv_retrieveAIDList: (NSArray **)  response

Retrieve AID list

Returns all the AID names on the terminal. Populates response parameter with an Array of NSString* with AID names. Each AID name represent a unique configuration file to be loaded/used when a matching application is found on a card during a transaction.

Parameters
responseReturns a NSArray of NSString of AID Names
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to BTPay::device_getResponseCodeString:()
- (RETURN_CODE) emv_retrieveApplicationData: (NSString *)  AID
response: (NSDictionary **)  responseAID 

Retrieve Application Data by AID

Retrieves the configuration information for a provided AID name, if that AID file exists on the terminal.

The TLV data in that AID is returned as a NSDictionary, with the Key being the tag name as a NSString representation of the tag hex value (example "9F06"), and the Object being the Value as NSData (example 0xa0000000031010).

The data returned will be from the range of allowable kernel EMV tags. Please see "EMV Tag Reference" at the end of this document for the listing.

Parameters
AIDName of ApplicationID in ASCII, example "A0000000031020". Must be between 5 and 16 characters
responseAIDThe response returned from the method as a dictionary with Key/Object to match TagValues as follows:
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) emv_retrieveCAPK: (NSString *)  rid
index: (NSString *)  index
response: (CAKey **)  response 

Retrieve Certificate Authority Public Key

Retrieves the CAPK as specified by the RID/Index passed as a parameter in the CAKey structure. The CAPK will be in the response parameter

Parameters
ridThe RID of the key to retrieve
indexThe Index of the key to retrieve
responseResponse returned as a CAKey
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to IDT_UniPayII::device_getResponseCodeString:()
- (RETURN_CODE) emv_retrieveCAPKFile: (NSString *)  rid
index: (NSString *)  index
response: (NSData **)  response 

Retrieve Certificate Authority Public Key

  • BTPay 200

Retrieves the CAPK as specified by the RID/Index passed as a parameter in the CAKey structure. The CAPK will be in the response parameter

Parameters
ridThe RID of the key to retrieve
indexThe Index of the key to retrieve
responseResponse returned as a NSData object with the following data:
  • 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>
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) emv_retrieveCAPKList: (NSArray **)  response

Retrieve the Certificate Authority Public Key list

Returns all the CAPK RID and Index. Populates response parameter with an array of NSString items, 12 characters each, characters 1-10 RID, characters 11-12 index.

Parameters
responseResponse returned contains an NSArray of NSString items, 12 characters each, characters 1-10 RID, characters 11-12 index. Example "a00000000357" = RID a00000003, Index 57
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to IDT_UniPayII::device_getResponseCodeString:()
- (RETURN_CODE) emv_retrieveCRLList: (NSMutableArray **)  response

Retrieve the Certificate Revocation List

Returns all the RID in the CRL.

Parameters
responseResponse returned as an NSArray of NSData objects 9-bytes each:
  • 5-bytes RID, 1-byte Index, 3-byte Serial Number
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) emv_retrieveTerminalData: (NSDictionary **)  responseData

Retrieve Terminal Data

Retrieves the tag values associated with the terminal configuration file. This will be a combination of uneditable major configuration tags for the kernel configuration (example 9F33, Terminal Capabilities), and editable tags set with IDT_Device::emv_setTerminalData:() (example DF13, Terminal Action Code - Default)

The TLV data returned as a NSDictionary, with the Key being the tag name as a NSString representation of the tag hex value (example "DF13"), and the Object being the Value as NSData (example 0x00058003FF).

The data returned will be from the range of allowable kernel EMV tags. Please see "EMV Tag Reference" at the end of this document for the listing.

Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) emv_retrieveTransactionResult: (NSData *)  tags
retrievedTags: (NSDictionary **)  retrievedTags 

Retrieve Transaction Results

Retrieves the requested tag values (if they exist) from the last transaction.

The TLV data returned as a NSDictionary, with the Key being the tag name as a NSString representation of the tag hex value (example "5A"), and the Object being the Value as NSData (example 0x41359276429372938).

Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) emv_setApplicationData: (NSString *)  aidName
configData: (NSDictionary *)  data 

Set Application Data by AID

Sets the configuration information for a provided AID name, with TLV data that populates a NSDictionary.

The TLV data for the AID is sent as a NSDictionary, with the Key being the tag name as a NSString representation of the tag hex value (example "9F06"), and the Object being the Value as NSData (example 0xa0000000031010).

The data for the AID configuration will will be from the range of allowable kernel EMV tags. Please see "EMV Tag Reference" at the end of this document for the listing.

NOTES: There is no minimum defined set of AID TLV data that must be provided, other than 9F06 for the AID name.

If this AID is selected and matched during an EMV transaction, any data in this AID will either OVERRIDE the same data in the terminal configuration file, or PROVIDE the data if it is non-existant in the terminal configuration file.

AID configuration information is provided during L3 certification. Dummy/stub AID data can be used pre-certification to test EMV transaction as long as at least tag 9F06 is defined that makes up the AID configuration locator.

There are convenience utilities to turn a TLV NSData object into a NSDictionary, and a NSDictionary into a NSData object in IDTUtility:

+(NSDictionary*) TLVtoDICT:(NSData*)param;
+(NSData*) DICTotTLV:(NSDictionary*)tags;

Also utilities to turn a HEX/ASCII string to NSDATA and back again

+ (NSData *)hexToData:(NSString*)str ;
+(NSString*) dataToHexString:(NSData*)data;
Parameters
aidNameaidName AID name. Example "a0000000031010"
dataNSDictionary with Tags/Values for the AID configuration file
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) emv_setCAPK: (CAKey key

Set Certificate Authority Public Key

Sets the CAPK as specified by the CAKey structure

Parameters
keyCAKey containing the RID, Index, and key data to set
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to IDT_UniPayII::device_getResponseCodeString:()
- (RETURN_CODE) emv_setCAPKFile: (NSData *)  file

Set Certificate Authority Public Key

Sets the CAPK as specified by the CAKey raw format

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 device_getResponseCodeString:
- (RETURN_CODE) emv_setCRLEntries: (NSData *)  data

Set Certificate Revocation List

Sets the CRL list

Parameters
dataCRLEntries as a repeating occurance of CRL: CRL1 CRL2 … CRLn. CRL format is
  • 5Bytes RID
  • 1Byte CA public key Index
  • 3Bytes Certificate Serial Number
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to IDT_UniPayII::device_getResponseCodeString:()
- (RETURN_CODE) emv_setTerminalData: (NSDictionary *)  data

Set Terminal Data

Sets the terminal configuration information, with TLV data that populates a NSDictionary.

The TLV data for the terminal configuration is sent as a NSDictionary, with the Key being the tag name as a NSString representation of the tag hex value (example "DF13"), and the Object being the Value as NSData (example 0x00080039FF).

The data for the terminal configuration will will be from the range of allowable kernel EMV tags. Please see "EMV Tag Reference" at the end of this document for the listing.

NOTES: There is an uneditable set of tags that make up the current kernel configuration major parameters. Any attempt to set those will return an error.

If an AID is selected and matched during an EMV transaction, any data in that AID will either OVERRIDE the same data in the terminal configuration file, or PROVIDE the data if it is non-existant in the terminal configuration file.

There are convenience utilities to turn a TLV NSData object into a NSDictionary, and a NSDictionary into a NSData object in IDTUtility:

+(NSDictionary*) TLVtoDICT:(NSData*)param;
+(NSData*) DICTotTLV:(NSDictionary*)tags;

Also utilities to turn a HEX/ASCII string to NSDATA and back again

+ (NSData *)hexToData:(NSString*)str ;
+(NSString*) dataToHexString:(NSData*)data;
Parameters
dataNSDictionary with Tags/Values for the Terminal configuration file
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to device_getResponseCodeString:
- (RETURN_CODE) emv_setTerminalMajorConfiguration: (int)  configuration

Sets the terminal major configuration in ICS .

Parameters
configurationA configuration value, range 1-5
  • 1 = 1C
  • 2 = 2C
  • 3 = 3C
  • 4 = 4C
  • 5 = 5C
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) emv_startTransaction: (double)  amount
amtOther: (double)  amtOther
type: (int)  type
timeout: (int)  timeout
tags: (NSData *)  tags
forceOnline: (BOOL)  forceOnline
fallback: (BOOL)  fallback 

Start EMV Transaction Request

Authorizes the EMV transaction for an ICC card

The tags will be returned in the emvTransactionData delegate protocol.

By default, auto authorize is ENABLED. If auto authorize is DISABLED, this function will complete with a return of EMV_RESULT_CODE_START_TRANSACTION_SUCCESS to emvTransactionData delegate protocol, and then IDT_NEO2::emv_authenticateTransaction() must be executed. If auto authorize is ENABLED (default), IDT_NEO2::emv_authenticateTransaction() will automatically be executed after receiving the result EMV_RESULT_CODE_START_TRANSACTION_SUCCESS. The auto authorize can be enabled/disabled with emv_disableAutoAuthenticateTransaction:

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 NSData. Example, tag 9F0C with amount 0x000000000100 would be 0x9F0C06000000000100 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. Tag DFEE1A can be used to specify tags to be returned in response, in addition to the default tags. Example DFEE1A049F029F03 will return tags 9F02 and 9F03 with the response
forceOnlineTRUE = do not allow offline approval, FALSE = allow ICC to approve offline if terminal capable
autoAuthenticateWill automatically execute Authenticate Transacation after start transaction returns successful
fallbackIndicate if it supports fallback to MSR
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:

NOTE ON INTERFACE SELECTION: For the NEO2, tag DFEF37 is used to determine which interfaces to use for the transaction:

  • 01 = MSR Only
  • 02 = CTLS Only
  • 03 = MSR + CTLS
  • 04 = EMV Only
  • 05 = EMV + MSR
  • 06 = EMV + CTLS
  • 07 = EMV + MSR + CLTS. This API method will automatically send DFEF37 with a value of 04 if this tag is not provided.
- (RETURN_CODE) emv_verifyDUKPTLoaded: (NSData *)  KCV

Verify DUKPT IK Loaded on ETC

Use this command to verify the DUKPT IK isloaded into the ETC. NEO2 is activated and it can request PIN from ETC after this command

Parameters
KCVASN.1 structure of KCV
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_Device::device_getResponseCodeString:()
- (RETURN_CODE) felica_authentication: (NSData *)  key

FeliCa Authentication

Provides a key to be used in a follow up FeliCa Read with MAC (3 blocks max) or Write with MAC (1 block max). This command must be executed before each Read w/MAC or Write w/MAC command

NOTE: The reader must be in Pass Through Mode for FeliCa commands to work.

Parameters
key16 byte key used for MAC generation of Read or Write with MAC
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) felica_read: (NSData *)  serviceCode
numBlocks: (int)  numBlocks
blockList: (NSData *)  blockList
blocks: (NSData **)  blocks 

FeliCa Read

Reads up to 4 blocks.

NOTE: The reader must be in Pass Through Mode for FeliCa commands to work.

Parameters
serviceCodeService Code List. Each service code in Service Code List = 2 bytes of data
numBlocksNumber of blocks
blockListBlocks to read. Maximum 4 block requests
blocksBlocks read. Each block 16 bytes.
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) felica_readWithMac: (int)  numBlocks
blockList: (NSData *)  blockList
blocks: (NSData **)  blocks 

FeliCa Read with MAC Generation

Reads up to 3 blocks with MAC Generation. FeliCa Authentication must be performed first

NOTE: The reader must be in Pass Through Mode for FeliCa commands to work.

Parameters
numBlocksNumber of blocks
blockListBlock to read. Each block in blockList Maximum 3 block requests
blocksBlocks read. Each block 16 bytes.
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) felica_requestService: (NSData *)  nodeCode
response: (NSData **)  response 

FeliCa Request Service

Perform functions a Felica Request Service

NOTE: The reader must be in Pass Through Mode for FeliCa commands to work.

Parameters
nodeCodeNode Code
responseResponse as explained in FeliCA Lite-S User's Manual
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) felica_SendCommand: (NSData *)  command
response: (NSData **)  response 

FeliCa Send Command

Send a Felica Command

NOTE: The reader must be in Pass Through Mode for FeliCa commands to work.

Parameters
commandCommand data from settlement center to be sent to felica card
responseResponse data from felica card
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) felica_write: (NSData *)  serviceCode
blockCount: (int)  blockCount
blockList: (NSData *)  blockList
data: (NSData *)  data
statusFlag: (NSData **)  statusFlag 

FeliCa Write

Writes a block

NOTE: The reader must be in Pass Through Mode for FeliCa commands to work.

Parameters
serviceCodeService Code list. Each service code must be be 2 bytes
blockCountBlock Count
blockListBlock list.
dataBlock to write. Must be 16 bytes.
statusFlagStatus flag response as explained in FeliCA Lite-S User's Manual, Section 4.5
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) felica_writeWithMac: (int)  blockNumber
data: (NSData *)  data 

FeliCa Write with MAC Generation

Writes a block with MAC Generation. FeliCa Authentication must be performed first

NOTE: The reader must be in Pass Through Mode for FeliCa commands to work.

Parameters
blockNumberNumber of block
dataBlock to write. Must be 16 bytes.
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) icc_exchangeAPDU: (NSData *)  dataAPDU
response: (APDUResponse **)  response 

Exchange APDU (unencrypted)

Sends an APDU packet to the ICC. If successful, response is returned in APDUResult class instance in response parameter.

Parameters
dataAPDUAPDU data packet
responseUnencrypted/encrypted parsed APDU response
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) icc_getICCReaderStatus: (ICCReaderStatus **)  readerStatus

Get Reader Status

Returns the reader status

Parameters
readerStatusPointer that will return with the ICCReaderStatus results.
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
ICCReaderStatus* readerStatus;
RETURN_CODE rt = [[IDT_Device sharedController] getICCReaderStatus:&readerStatus];
if(RETURN_CODE_DO_SUCCESS != rt){
NSLog(@"Fail");
}
else{
NSString *sta;
if(readerStatus->iccPower)
sta =@"[ICC Powered]";
else
sta = @"[ICC Power not Ready]";
if(readerStatus->cardSeated)
sta =[NSString stringWithFormat:@"%@,[Card Seated]", sta];
else
sta =[NSString stringWithFormat:@"%@,[Card not Seated]", sta];
- (RETURN_CODE) icc_getKeyFormatForICCDUKPT: (NSData **)  format

Start a CTLS Transaction Request

Authorizes the CTLS transaction for an CTLS card, including AppleVAS and SmartTAP

The tags will be returned in the callback routine.

Parameters
amountTransaction amount value (tag value 9F02)
exponentNumber of characters after decimile point
typeTransaction type (tag value 9C).
timeoutTimeout value in seconds.
transTagsAny other transaction tags to be included in the request (excluding Apple VAS and SmartTap)
VASTags to enable the capture of Apple 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 the VAS data must contain tags 9F26 and 9F22, and can optionanally contain tags 9F2B and DFO1. Example 9F220201009F2604000000009F2B050100000000DF010101 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
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:

NOTE ON INTERFACE SELECTION: For the NEO2, tag DFEF37 is used to determine which interfaces to use for the transaction:

  • 01 = MSR Only
  • 02 = CTLS Only
  • 03 = MSR + CTLS
  • 04 = EMV Only
  • 05 = EMV + MSR
  • 06 = EMV + CTLS
  • 07 = EMV + MSR + CLTS. This API method will automatically send DFEF37 with a value of 02 if this tag is not provided.

    NOTE ON APPLEPAY VAS: Get Key format for ICC DUKPT

Specifies how data is being encrypted with Data Key or PIN key

Parameters
formatResponse return from method: -'TDES' : Encrypted card data with TDES if DUKPT Key had been loaded -'AES' : Encrypted card data with AES if DUKPT Key had been loaded -NONE' : No Encryption
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) icc_powerOffICC: (NSString **)  error

Power Off ICC

Powers down the ICC

Parameters
errorReturns the error, if any
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE.

If Success, empty If Failure, ASCII encoded data of error string

- (RETURN_CODE) icc_powerOnICC: (NSData **)  response

Power On ICC

Power up the currently selected microprocessor card in the ICC reader

Parameters
responseResponse returned. If Success, ATR String. If Failure, ASCII encoded data of error string
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE.
- (RETURN_CODE) icc_setKeyFormatForICCDUKPT: (NSData *)  encryption

Set Key format for ICC DUKPT

Specifies how data will be encrypted with Data Key or PIN key

Parameters
encryptionThe type of encryption to be used -0x00 : Encrypted card data with TDES if DUKPT Key had been loaded -0x01 : Encrypted card data with AES if DUKPT Key had been loaded -Other Data : No Encryption
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (bool) isConnected

Check if device is connected

- (RETURN_CODE) msr_cancelMSRSwipe

Disable MSR Swipe

Cancels Swipe.

Cancels Transaction request (all interfaces, CTLS/MSR/INSERT).

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) msr_getConfiguration: (NSData **)  config

Get MSR Configuration

Gets the MSR configuration data

Parameters
configConfiguration data retrieved
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) msr_getMSRTrack: (int *)  val

Get MSR Track

Returns the track value of the MSR

Parameters
valThe value of the current MSR tracks setting
  • 0 : Any track
  • 1 : Track 1
  • 2 : Track 2
  • 3 : Track 1, Track 2
  • 4 : Track 3
  • 5 : Track 1, Track 3
  • 6 : Track 2, Track 3
  • 7 : Track 1, Track 2 , Track 3
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) msr_retrieveWhiteList: (NSData **)  value

Retrieve MSR White List

Retrieves the whitelist

Parameters
valueThe whitelist data which is in ASN.1 block format
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) msr_setConfiguration: (NSData *)  config

Set MSR Configuration

Sets MSR configuration data

Parameters
configConfiguration data to send
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) msr_setMSRTrack: (int)  val

Set MSR Track

Sets the track value of the MSR

Parameters
valThe value of the current MSR tracks setting
  • 0 : Any track
  • 1 : Track 1
  • 2 : Track 2
  • 3 : Track 1, Track 2
  • 4 : Track 3
  • 5 : Track 1, Track 3
  • 6 : Track 2, Track 3
  • 7 : Track 1, Track 2 , Track 3
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) msr_startMSRSwipe

Enable MSR Swipe

Enables CLTS and MSR, waiting for swipe or tap to occur. Returns IDTEMVData to deviceDelegate::emvTransactionData:()

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) pin_cancelPin

Cancel PIN Command

This command can cancel IDT_Device:getEncryptedPIN:keyType:line1:line2:line3:() and IDT_Device::getNumeric:minLength:maxLength:messageID:language:() and IDT_Device::getAmount:maxLength:messageID:language:() and IDT_Device::getCardAccount:max:line1:line2:() and IDT_Device::pin_getFunctionKey() and IDT_Device::getEncryptedData:minLength:maxLength:messageID:language:()

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) pin_captureAmountInput: (int)  minPIN
maxPIN: (int)  maxPIN
message: (NSString *)  message
signature: (NSData *)  signature 

Capture Amount Input

Parameters
minPINMinimum PIN Length
maxPINMaximum PIN Length
messageLCD Message
signatureDisplay message signed by Numeric Private Key using RSAPSS algorithm:
  1. Calculate 32 bytes Hash for “<Display Flag><Key max="" length>="">< Key Min Length><Plaintext display="" message>="">”
  2. Using RSAPSS algorithm calculate the Hash to be 256 bytes Raw Data
  3. Using Numeric Private Key to sign the Raw Data to be 256 bytes signature

Results returned to pinpadData delegate

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) pin_captureFunctionKey

Capture Function Key

Captures a function key entry on the pinpad

Results returned to pinpadData delegate

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) pin_captureNumericInput: (bool)  mask
minPIN: (int)  minPIN
maxPIN: (int)  maxPIN
message: (NSString *)  message
signature: (NSData *)  signature 

Capture Numeric Input

Parameters
maskTrue = mask input with "*", False = no masking of input
minPINMinimum PIN Length
maxPINMaximum PIN Length
messageLCD Message
signatureDisplay message signed by Numeric Private Key using RSAPSS algorithm:
  1. Calculate 32 bytes Hash for “<Display Flag><Key max="" length>="">< Key Min Length><Plaintext display="" message>="">”
  2. Using RSAPSS algorithm calculate the Hash to be 256 bytes Raw Data
  3. Using Numeric Private Key to sign the Raw Data to be 256 bytes signature

Results returned to pinpadData delegate

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) pin_capturePin: (int)  type
PAN: (NSString *)  PAN
minPIN: (int)  minPIN
maxPIN: (int)  maxPIN
message: (NSString *)  message 

Capture PIN

Parameters
typePAN and Key Type
  • 00h = MKSK to encrypt PIN, Internal PAN (from MSR)
  • 01h = DUKPT to encrypt PIN, Internal PAN (from MSR)
  • 10h = MKSK to encrypt PIN, External Plaintext PAN
  • 11h = DUKPT to encrypt PIN, External Plaintext PAN
  • 20h = MKSK to encrypt PIN, External Ciphertext PAN
  • 21h = DUKPT to encrypt PIN, External Ciphertext PAN
PANPersonal Account Number (if internal, value is 0)
minPINMinimum PIN Length
maxPINMaximum PIN Length
messageLCD Message

Results returned to pinpadData delegate

Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString:
- (void) scanForBLEDeviceNames: (NSTimeInterval)  scanTime
serviceUUIDs: (nullable NSArray< CBUUID * > *)  serviceUUIDs
options: (nullable NSDictionary< NSString *, id > *)  options 

Begins searching for Bluetooth Low Energy devices in range and return NSArray with found device names

  • VP3300, NEO2

    This will initiate a bluetooth searech, and return an UIAlertView to the delegate bluetoothPickerAlert

    Parameters
    scanTimeAmount of time to search for devices before returning alert view.
    serviceUUIDsA null terminated array of CBUUID to filter for specific device type. Sending nil will report all ble devices in range
    optionsscan options

    Note: Please refer to CBCentralManager scanForPeripheralsWithServices for information about serviceUUIDs and options parameters

- (void) scanForBLEDevices: (NSTimeInterval)  scanTime
serviceUUIDs: (nullable NSArray< CBUUID * > *)  serviceUUIDs
options: (nullable NSDictionary< NSString *, id > *)  options 

Begins searching for Bluetooth Low Energy devices in range and return UIAlertView with choices

  • VP3300, NEO2

    This will initiate a bluetooth searech, and return an UIAlertView to the delegate bluetoothPickerAlert

    Parameters
    scanTimeAmount of time to search for devices before returning alert view.
    serviceUUIDsA null terminated array of CBUUID to filter for specific device type. Sending nil will report all ble devices in range
    optionsscan options

    Note: Please refer to CBCentralManager scanForPeripheralsWithServices for information about serviceUUIDs and options parameters

+ (NSString*) SDK_version

SDK Version

Returns the current version of IDTech.framework

Returns
Framework version
- (void) setServiceScanFilter: (NSArray< CBUUID * > *)  filter

Set BLE Service Scan Filter.

When searching for BLE devices, this will limit the service search to the provided service ID's

Example data format: NSArray<CBUUID *> *filter = [[NSArray alloc] initWithObjects:[CBUUID UUIDWithString:"1820"], nil];

Parameters
filterThe array of services to filter for
- (void) setServiceUUID: (nullable NSArray< CBUUID * > *)  serviceUUIDs

Set BLE to filter for specified service UUID

Parameters
setServiceUUIDSets the UUID filter to be used when discovering BLE devices
+ (IDT_NEO2*) sharedController

Singleton Instance

Establishes an singleton instance of IDT_NEO2 class.

Returns
Instance of IDT_NEO2
- (RETURN_CODE) updateFirmwareNeo2: (FIRMWARE_TYPE)  type
data: (NSData *)  firmwareData 

Update NEO 2 Firmware

Reserved for system use

Property Documentation

- (id< IDT_NEO2_Delegate >) delegate
readwriteatomicstrong

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