![]() |
IDTech iOS SDK Guide
1.1.166.045
API reference for NEO2
|
#import <IDT_NEO2.h>
Class Methods | |
(NSString *) | + SDK_version |
(IDT_NEO2 *) | + sharedController |
(NSString *) | + createFastEMVData: |
Properties | |
id< IDT_NEO2_Delegate > | delegate |
Class to drive the IDT_NEO2 device
- (RETURN_CODE) adf_eraseFlash: | (ADF_TYPE) | type |
Erase ADF Flash
Erases the ADF flash memory
type | The ADF type
|
- (RETURN_CODE) adf_getADFMode: | (BOOL *) | enable |
Get ADF Mode
Retrieves the state of the ADF environment
enable | True = ADF is enabled, False = ADF is disabled |
- (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
type | The ADF type
|
adfInfo | List of modules information |
- (RETURN_CODE) adf_getModuleInfo: | (ADF_TYPE) | type | |
adfInfo: | (NSArray **) | adfInfo | |
Get Module Info
Retrieves the module information when running in an ADF environment
type | The ADF type
|
adfInfo | List of modules information |
- (RETURN_CODE) adf_setADFMode: | (BOOL) | enable |
Set ADF Mode
Enables/Disables the ADF environment
enable | True = ADF enabled, False = ADF disabled |
- (RETURN_CODE) adf_setJTAG: | (BOOL) | enable |
Set JTAG
Enables/Disables the JTAG pin in an ADF environment
enable | True = JTAG enabled, False = JTAG disabled |
- (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.
keyIndex | Data 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 |
- (RETURN_CODE) config_getDEKVariantType: | (Byte *) | type |
Get Data Encryption Key Variant Type
Returns the data encryption key type
type | -0 = Data Variant -1 = Pin Variant |
- (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
keyslot | Key Slot |
mode | 0 = TDES, 1 = AES |
outputMode_workingKey | 0 = TDES / TDES, 1 = AES-128 / TDES3 2 = TransArmor / AES-128, Output Mode is when TDES, Working Key is when AES |
variant_keyUsage | 0 = Data Key / Encrypt/Decrypt, 1 = PIN Key / Encrypt, 2 = N/A / Decrypt, Variant is when TDES, Key Usage is when AES |
- (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.
KSN | Key Serial Number |
- (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)
keyslotPEK | PEK KeySlot (0-9). Value of 255 (0xff) = does not exist |
keyslotDEK | DEK KeySlot (0-9). Value of 255 (0xff) = does not exist |
- (RETURN_CODE) config_getSalt_KCV: | (NSData **) | KCV |
Get Salt KCV
Host can use this command to retrieve the Salt KCV
KCV | KCV |
- (RETURN_CODE) config_getSerialNumber: | (NSString **) | response |
Polls device for Serial Number
response | Returns Serial Number |
- (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
name | Device name, 1-25 characters |
oldPW | Old password, as a six character string, example "123456" |
newPW | New password, as a six character string, example "654321" |
- (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.
type | -0 = Data Variant -1 = PIN Variant |
- (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
keyslot | Key Slot |
workingKey | 0 = TDES, 1 = TDES3, 2 = AES-128 |
keyUsage | 0 = Encrypt/Decrypt, 1 = Encrypt, 2 = Decrypt |
- (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.
keyslot | Key Slot |
outputMode | 0 = TDES, 1 = AES-128, 2 = TransArmor TDES |
variant | 0 = Data Variant, 1 = PIN Variant |
- (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.
isPEK | TRUE = set PEK, FALSE = set DEK |
keySlot | The KeySlot number specifies the key this command will select |
- (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
keyNumber | Number of keys remaining to load |
tr31 | ASN.1 structure of encrypted key(s) |
nonce | Nonce generated by RKMS to generate an HMAC used for auth |
hmac | HMAC-SHA256 generated from RKMS |
kv | ASN.1 Key Verification Structure returned from device |
nonce_device | Nonce generated by the device to generate a MAC used for auth |
hmac_device | HMAC-SHA256 generated from device terminal |
+ (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
emvData | The IDTEMVData object populated with card data. |
- (RETURN_CODE) ctls_cancelTransaction |
Cancels Transaction request (all interfaces, CTLS/MSR/INSERT).
- (RETURN_CODE) ctls_getAllConfigGroups: | (NSData **) | response |
Get All Configuration Groups
Retrieves all Configuration Groups.
response |
- (RETURN_CODE) ctls_getAllConfigurationGroups: | (NSDictionary< NSString *, NSDictionary * > **) | response |
Get All Configuration Groups
Retrieves all Configuration Groups.
response | Groups returned in a dictionary Key = <String>Group Value = <Dictionary<tag,value>> |
- (RETURN_CODE) ctls_getConfigurationGroup: | (int) | group | |
response: | (NSDictionary **) | response | |
Get Configuration Group
Retrieves the Configuration for the specified Group. Group 0 = terminal settings.
group | Configuration Group |
response | Group TLV returned as a dictionary |
- (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.
nfcCmdPkt | System Code
|
response | Response as explained in FeliCA Lite-S User's Manual |
ip | IP Address of target device (optional) |
- (RETURN_CODE) ctls_removeAllCAPK |
Remove All Certificate Authority Public Key
Removes all the CAPK for CTLS
- (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
AID | Name of ApplicationID as Hex String (example "A0000000031010") Must be between 5 and 16 bytes |
- (RETURN_CODE) ctls_removeCAPK: | (NSData *) | capk |
Remove Certificate Authority Public Key
Removes the CAPK for CTLS as specified by the RID/Index
capk | 6 byte CAPK = 5 bytes RID + 1 byte INDEX |
- (RETURN_CODE) ctls_removeConfigurationGroup: | (int) | group |
Remove Configuration Group
Removes the Configuration as specified by the Group. Must not by group 0
group | Configuration Group |
- (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
group | Configuration group |
- (RETURN_CODE) ctls_retrieveAIDList: | (NSArray **) | response |
Retrieve AID list
Returns all the AID names installed on the terminal for CTLS.
response | array of AID name as NSData* |
- (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.
AID | Name of ApplicationID as Hex String (example "A0000000031010"). Must be between 5 and 16 bytes |
response | The TLV elements of the requested AID |
- (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.
capk | 6 bytes CAPK = 5 bytes RID + 1 byte Index |
key | Response 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:
|
- (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.
keys | NSArray of NSData CAPK name (RID + Index) |
- (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).
tlv | Response returned as a TLV |
- (RETURN_CODE) ctls_setApplicationData: | (NSData *) | tlv |
Set Application Data by AID
Sets the Application Data for CTLS as specified by TLV data
tlv | Application 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"
- (RETURN_CODE) ctls_setCAPK: | (NSData *) | key |
Set Certificate Authority Public Key
Sets the CAPK for CTLS as specified by the CAKey structure
key | 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:
|
- (RETURN_CODE) ctls_setConfigurationGroup: | (NSData *) | tlv |
Set Configuration Group
Sets the Configuration Group for CTLS as specified by the TLV data
tlv | Configuration Group Data in TLV format The first tag of the TLV data must be the group number (DFEE2D). A second tag must exist |
- (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.
tlv | TerminalData configuration data |
- (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.
amount | Transaction amount value (tag value 9F02) |
exponent | Number of characters after decimile point |
type | Transaction type (tag value 9C). |
timeout | Timeout value in seconds. |
tags | Any other tags to be included in the request. |
NOTE ON INTERFACE SELECTION: For the NEO2, tag DFEF37 is used to determine which interfaces to use for the transaction:
- (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.
statusCode | 00:ok, 01:not ok, 02: (ARC response 89 for Interac) |
authCode | Authorization code from host. Six bytes. Optional |
date | Transaction date. If null, uses current terminal date. 3 bytes compressed numeric YYMMDD (tag value 9A) |
time | Transaction time. If null, uses current terminal time. 3 bytes compressed numeric HHMMSS (tag value 9F21) |
- (RETURN_CODE) device_addTLVToTerminalData: | (NSData *) | tlv |
Add Terminal Data
Adds the specified TLV to the current terminal data .
tlv | The data to set, overwriting any existing value |
- (RETURN_CODE) device_antennaControl: | (bool) | turnON |
Antenna Control
The Antenna Control command turns the RF Antenna ON or OFF.
turnON | TRUE = ON, FALSE = OFF |
- (RETURN_CODE) device_buzzerOnOff |
Buzzer OnOff
Causes the buzzer to beep once
- (RETURN_CODE) device_cancelTransaction |
Cancels Transaction request (all interfaces, CTLS/MSR/INSERT).
- (RETURN_CODE) device_certificateType: | (int *) | type |
Device Certificate Type
Returns the device certificate type
type | 0 = Unknown, 1 = Demo, 2 = Production |
- (NSUUID*) device_connectedBLEDevice |
Returns the UUID of the connected BLE device
NEO2
- (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
indexLED | The LED to control starting from the left
|
control | Turns chosen LED(s) OFF (00) or ON (01) |
- (RETURN_CODE) device_controlUserInterface: | (NSData *) | values |
Control User Interface
Controls the Display, Beep, and LED
values | Four bytes to control the user interface elements Byte[0] = LCD Message
|
- (RETURN_CODE) device_createDirectory: | (NSString *) | directoryName |
Create Directory
This command adds a subdirectory to the indicated path
directoryName | The 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 (/) |
- (RETURN_CODE) device_deleteDirectory: | (NSString *) | filename |
Delete Directory
This command deletes an empty directory
filename | Complete path of the directory you want to delete. |
- (RETURN_CODE) device_deleteFile: | (NSString *) | filename | |
isSD: | (BOOL) | isSD | |
Delete File
This command deletes a file or group of files
filename | Complete 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 (/) |
isSD | True = Delete from SD card, False = Delete from Flash |
- (bool) device_disableBLEDeviceSearch |
Stops searching for Bluetooth Low Energy devices in range
NEO2
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
- (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
identifier | This 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) |
Any of the following BLE status messages may be returned to the deviceMessage delegate:
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
enablePassThrough | True = passthrough ON, False = passthrough OFF |
- (RETURN_CODE) device_enableL80PassThrough: | (BOOL) | enablePassThrough |
Enable L80 Passthrough
Enables Passthrough mode for direct communicaiton to L80 hooked up to NEO2 device
enablePassThrough | True = passthrough ON, False = passthrough OFF |
- (RETURN_CODE) device_enaBlueLED: | (NSData *) | dataCmd |
Enable the blue LED and modify the behaviour
Control the blue LED behaviour on the Vendi reader
dataCmd | LED 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.
|
- (RETURN_CODE) device_enterStandbyMode |
Enter standby mode
Puts unit into low power standby mode
- (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
sendData | APDU Out |
receiveData | APDU response |
- (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
enable | TRUE = enable log, FALSE = disable log |
- (RETURN_CODE) device_get1050BootloaderVersion: | (NSString **) | version |
Get 1050 Bootloader Version
Polls the device for the 1050 bootloader version
version | Response returned of the 1050 bootloader version |
- (RETURN_CODE) device_get1050DeviceTreeVersion: | (NSString **) | deviceTree |
Get 1050 Device Tree
Polls the NEO2/3 for the 1050 Device Tree
deviceTree | The device tree returned as a NSString |
- (RETURN_CODE) device_get1050FuseStatus: | (NSData **) | status |
RT1050 SRK Fuse Status
This command retrieves the status fo the reader's RT1050 SRK fuse
status | First 8 bytes of the SRK Fuse, if programmed. Otherwise, an empty array is returned |
- (RETURN_CODE) device_getAutoPollTransactionResults: | (IDTEMVData **) | result |
Get Transaction Results Gets the transaction results when the reader is functioning in "Auto Poll" mode
result | The transaction results |
- (NSString*) device_getBLEFriendlyName |
Get BLE Friendly Name
- (RETURN_CODE) device_getBootloaderVersion: | (NSString **) | response |
Get Bootloader Version
Polls the device for the bootloader version
response | Response return of the bootloader version from the device |
- (RETURN_CODE) device_getDeviceTreeVersion: | (NSString **) | deviceTree | |
is1050: | (BOOL) | is1050 | |
Get Device Tree
Polls the NEO2/3 for the Device Tree
deviceTree | The device's tree returned as a NSString |
- (RETURN_CODE) device_getFirmwareVersion: | (NSString **) | response |
Polls device for Firmware Version
response | Response returned of Firmware Version |
- (RETURN_CODE) device_getHardwareInfo: | (NSString **) | response |
Get Hardware Info
Returns an ASCII string for the hardware information
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
- (RETURN_CODE) device_getLightSensorVal: | (UInt16 *) | lightVal |
Get Light Sensor Value
Gets the value from the sensor
lightVal | Value of the light sensor |
- (RETURN_CODE) device_getMerchantRecord: | (int) | index | |
record: | (NSData **) | record | |
Get Merchant Record Gets the merchant record for ApplePay VAS
index | Merchant Record index, valid values 1-6 |
record | Data 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 |
- (RETURN_CODE) device_getModuleVer: | (NSString **) | moduleVer |
Get Module Version Information
Gets the 16 byte UID of the MCU
uid | The string representation of the UID |
- (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
b0 | True = T1 force encryption |
b1 | True = T2 force encryption |
b2 | True = T3 force encryption |
b3 | True = T3 force encryption when card type is 80 |
tlv | MSR secure parameters TLV objects |
- (RETURN_CODE) device_getPollMode: | (NSData **) | mode |
Get Poll Mode
Gets the current poll mode of the device
mode | Response from the device of the current poll mode |
- (RETURN_CODE) device_getProcessorType: | (NSData **) | type |
Get Processor Type
Returns a processor type TLV
45 00 | ARM7/ LPC21xx 4D 00 | ARM Cortex-M4/ K21 Family 4E 00 | ARM Cortex-M4/ K81 Family
- (RETURN_CODE) device_getProductType: | (NSData **) | type |
Get Product Type
Returns a "product type" value in a proprietary TLV
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
- (NSString *) device_getResponseCodeString: | (int) | errorCode |
Get Response Code String
Interpret a response code and return string description.
errorCode | Error code, range 0x0000 - 0xFFFF, example 0x0300 |
- (RETURN_CODE) device_getRT1050FirmwareVersion: | (NSString **) | response |
Get RT1050 Firmware Version
Gets the version for the RT1050 Firmware
response | Response returned of the RT1050 firmware |
- (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.
feature | Function/Feature ID |
addRequirement | Additional Requirement |
- (RETURN_CODE) device_getTransactionResults: | (NSData **) | results |
Get Transaction Results
Gets the transaction results when the reader is functioning in "Auto Poll" mode
results | The transaction results |
- (RETURN_CODE) device_getTransArmorID: | (NSString **) | TID |
Get TransArmor ID
Gets the TransArmor ID from the device
TID | TransArmor ID |
- (RETURN_CODE) device_getUIDofMCU: | (NSString **) | response |
Get UID of MCU
Returns the UID of the device
response | The module UID information |
- (bool) device_isConnected: | (IDT_DEVICE_Types) | device |
Is Device Connected
Returns the connection status of the requested device
device | Check connectivity of device type |
- (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
directoryName | The directory name. If null, root directory is selected |
recursive | Include sub-directories |
onSD | True = use SD card, False = use Flash |
directory | The returned directory information |
- (RETURN_CODE) device_listenForNotifications: | (BOOL) | enable |
Listen for Notifcations
Instructs SDK to listen for unsolicited data
enable | True = Listen, False = Don't listen |
- (RETURN_CODE) device_loadCertCA: | (Byte) | type | |
CertData: | (NSData *) | cert | |
Load CA Certificate
Loads the CA certificate data onto the device
type | The type of certificate -00h: Application CA -01h: TLS CA |
cert | The certificate data bytes |
- (RETURN_CODE) device_logClear |
Log Clear
Instructs the device to delete all log data
- (RETURN_CODE) device_logEnable: | (BOOL) | enable |
Enable Log
Instructs the device to enable/disable the log
enable | True = enable log, False = disable log |
- (RETURN_CODE) device_logRead: | (NSData **) | response |
Log Read
Instructs the device to output all log data
response | Full response received from NEO2 device, including log |
- (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
stopMode | True = Stop Mode (POR required), False = Sleep Mode (resume from last instruction) |
wakeOnTrans | True = Swipe/Tap will wake from low power, False = Will not wake from swipe/tap |
- (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
- (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
- (RETURN_CODE) device_pingDevice |
Ping Device
Pings the reader. If it is connected, returns success, otherwise returns timeout
- (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
timeout | Timeout, in seconds to wait for card to be detected |
card | Card Type:
|
serialNumber | Serial Number or the UID of the PICC |
ident | Device ID to send command to. If not specified, current SDK default device will be used. |
- (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
directory | The file directory to search in. If blank, will use the root directory |
filename | Name of the file to retrieve |
isSD | True = query SD card, False = query internal storage |
exists | True = file exists, False = file does not exist |
timestamp | If the file exists, reports the timestamp of the file |
fileSize | If the file exists, reports the size of the file |
- (RETURN_CODE) device_readFileFromSD: | (NSString *) | directory | |
filename: | (NSString *) | filename | |
fileData: | (NSData **) | fileData | |
Read File from SD card
Reads a file from the SD card
directory | The file directory to read from. If empty, the root directory is used |
filename | The name of the file to retrieve |
fileData | The contents of the file if it exists |
- (RETURN_CODE) device_rebootDevice |
Reboot Device
Executes a command to restart the device.
- (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.
- (RETURN_CODE) device_retrieveTerminalData: | (NSData **) | responseData |
Retrieve Terminal Data
Retrieves the Terminal Data . The Terminal Data will be in the response parameter responseData
responseData | The response returned from the method as NSData |
- (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.
- (RETURN_CODE) device_rrcDisconnect |
RRC Disonnect
The RRC Disonnect command allows a host to terminate the RRC connection to a reader.
- (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
appName | The name of the application that appears on the Application Manager list |
appData | The compressed application file to be sent in chunks |
- (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.
appName | The name of the application that will appear on the Application Manager list |
- (RETURN_CODE) device_rrcRunApp: | (NSString *) | appName |
RRC Run application
This command allows the reader to run an installed application
appName | The name of the installed application to run |
- (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.
appName | The name of the application that appears on the Application Manager list |
- (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
command | One byte command as per NEO IDG Reference Guide |
subCommand | One byte sub-command as per NEO IDG Reference Guide |
data | Command data (if applicable) |
response | Returns next Command response |
- (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
command | One byte command as per NEO IDG Reference Guide |
subCommand | One byte sub-command as per NEO IDG Reference Guide |
data | Command data (if applicable) |
response | Returns next Command response |
- (void) device_setBLEFriendlyName: | (NSString *) | friendlyName |
Set BLE Friendly Name
friendlyName | Sets 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.
mode | 0 = OFF, 1 = Always On, 2 = Auto Exit |
- (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
index | Merchant Record index, valid values 1-6 |
enabled | Merchant Enabled/Valid flag |
merchantID | Merchant unique identifer registered with Apple. Example com.idtechproducts.applePay |
merchantURL | Merchant URL, when applicable |
- (RETURN_CODE) device_setPassThrough: | (BOOL) | enablePassThrough |
Set Pass Through
Sets Pass-Through mode on NEO2
enablePassThrough | TRUE = Pass through enabled |
- (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
mode | 0 = Auto Poll, 1 = Poll On Demand |
- (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.
feature | Function/Feature ID |
addRequirement | Additional Requirement |
- (RETURN_CODE) device_setTerminalData: | (NSData *) | tags |
Set Terminal Data
Sets the Terminal Data .
responseData | The data to set |
- (RETURN_CODE) device_setTransArmorEncryption: | (NSData *) | cert |
Set TransArmor Encryption
Sets the TransArmor encryption from the given certificate
cert | Certificate in PEM format or DER format. PEM format must be string data (converted to binary) starting with "---". DER format is binary data. |
- (RETURN_CODE) device_setTransArmorID: | (NSString *) | TID |
Set TransArmor ID
Sets the TransArmor ID
TID | TransArmor ID |
- (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.
amount | Transaction amount value (tag value 9F02) |
exponent | Number of characters after decimile point |
type | Transaction type (tag value 9C). |
timeout | Timeout value in seconds. |
tags | Any other tags to be included in the request. |
NOTE ON INTERFACE SELECTION: For the NEO2, tag DFEF37 is used to determine which interfaces to use for the transaction:
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).
tags | Any 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 |
- (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
KSN | The KSN data |
- (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.
mode | The choices are as follows
|
selection | Line number in hex (0x01, 0x02), or 'C'/'E' of function key |
- (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
MSR | Swiped track data |
- (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.
mode | PIN Mode:
|
KSN | Key Serial Number. If no pairing and PIN is plaintext, value is nil |
PIN | PIN data, encrypted. If no pairing, PIN will be sent plaintext |
- (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
type | If cancel button is pressed during PIN entry, then this value is EMV_PIN_MODE_CANCEL
|
KSN | If enciphered PIN, this is either PINK DUKPT Key or PIN Session Key or PIN Pairing DUKPT |
PIN | If 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).
- (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.
isSuccess | Determines if connection to host was successful:
|
tags | Host response tag (see below) |
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
- (void) emv_disableAutoAuthenticateTransaction: | (BOOL) | disable |
Disable Auto Authenticate Transaction
If auto authenticate is DISABLED, authenticateTransaction must be called after a successful startEMV execution.
disable | FALSE = 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
cert | Send ETC certificate for signature verification, Receives NEO2 certificate for signature verification |
nonce | Send ETC random nonce, Receives NEO2 random nonce |
signature | Send ETC signature, Receives NEO2 signature. Signature of (CertETC_SV || NONCE_ETC) with PKCS1-v1_5 padding |
- (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
cert | ETC certificate for signature verification |
signature | Signature of (KEK || NONCE_ETC) with PKCS1-v1_5 padding |
key | ASN.1 structure of DUKPT IK used between NEO2 and ETC |
- (RETURN_CODE) emv_getBatteryPercentage: | (NSString **) | response |
Battery Percentage
Polls the device for the current battery percentage
response | Returns the battery percentage represented as a whole number 5 - 100% |
- (RETURN_CODE) emv_getBatteryVoltage: | (NSString **) | response |
Battery Voltage
Polls the device for the current battery voltage
response | Returns battery voltage string representing millivolts |
- (RETURN_CODE) emv_getEMVConfigurationCheckValue: | (NSString **) | response |
Get EMV Configuration Check Value
Polls device for the EMV Configuration Check Value
response | Response returned of the Check Value of the Configuration |
- (RETURN_CODE) emv_getEMVKernelCheckValue: | (NSString **) | response |
Get Kernel Check Value
Polls the device for the Kernel Check Value
response | Response returned of the Check Value of the Kernel |
- (RETURN_CODE) emv_getEMVKernelVersion: | (NSString **) | response |
Get EMV Kernel Version
Polls the device for the EMV Kernel Version
response | The kernel version response in a string |
- (RETURN_CODE) emv_getEMVKernelVersionExt: | (NSString **) | response |
Get Extended EMV Kernel Version
Polls the device for the extended EMV kernel version
response | The extended kernel verion response in a string |
- (RETURN_CODE) emv_getEMVL2Version: | (NSString **) | response |
Polls device for EMV L2 Version
response | Response returned of Level 2 Version |
- (RETURN_CODE) emv_getTerminalMajorConfiguration: | (NSUInteger **) | configuration |
Gets the terminal major configuration in ICS .
configuration | A configuration value, range 1-5
|
- (RETURN_CODE) emv_removeAllApplicationData |
Remove All Application Data
Removes all the application data for the EMV kernel
- (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.
AID | Name 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 |
- (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
rid | RID of the key to remove |
index | Index of the key to remove |
- (RETURN_CODE) emv_removeCRLList |
Remove Certificate Revocation List
Removes all CRLEntry entries
- (RETURN_CODE) emv_removeTerminalData |
Remove Terminal Data
This will remove ALL configurable TLV data associated with the terminals Kernel configuration.
- (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.
response | Returns a NSArray of NSString of AID Names |
- (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.
AID | Name of ApplicationID in ASCII, example "A0000000031020". Must be between 5 and 16 characters |
responseAID | The response returned from the method as a dictionary with Key/Object to match TagValues as follows: |
- (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
rid | The RID of the key to retrieve |
index | The Index of the key to retrieve |
response | Response returned as a CAKey |
- (RETURN_CODE) emv_retrieveCAPKFile: | (NSString *) | rid | |
index: | (NSString *) | index | |
response: | (NSData **) | 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
rid | The RID of the key to retrieve |
index | The Index of the key to retrieve |
response | Response returned as a NSData object with the following data:
|
- (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.
response | Response returned contains an NSArray of NSString items, 12 characters each, characters 1-10 RID, characters 11-12 index. Example "a00000000357" = RID a00000003, Index 57 |
- (RETURN_CODE) emv_retrieveCRLList: | (NSMutableArray **) | response |
Retrieve the Certificate Revocation List
Returns all the RID in the CRL.
response | Response returned as an NSArray of NSData objects 9-bytes each:
|
- (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.
- (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).
- (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:
Also utilities to turn a HEX/ASCII string to NSDATA and back again
aidName | aidName AID name. Example "a0000000031010" |
data | NSDictionary with Tags/Values for the AID configuration file |
- (RETURN_CODE) emv_setCAPK: | (CAKey) | key |
Set Certificate Authority Public Key
Sets the CAPK as specified by the CAKey structure
key | CAKey containing the RID, Index, and key data to set |
- (RETURN_CODE) emv_setCAPKFile: | (NSData *) | file |
Set Certificate Authority Public Key
Sets the CAPK as specified by the CAKey raw format
key | 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:
|
- (RETURN_CODE) emv_setCRLEntries: | (NSData *) | data |
Set Certificate Revocation List
Sets the CRL list
data | CRLEntries as a repeating occurance of CRL: CRL1 CRL2 … CRLn. CRL format is
|
- (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:
Also utilities to turn a HEX/ASCII string to NSDATA and back again
data | NSDictionary with Tags/Values for the Terminal configuration file |
- (RETURN_CODE) emv_setTerminalMajorConfiguration: | (int) | configuration |
Sets the terminal major configuration in ICS .
configuration | A configuration value, range 1-5
|
- (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:
amount | Transaction amount value (tag value 9F02) |
amtOther | Other amount value, if any (tag value 9F03) |
type | Transaction type (tag value 9C). |
timeout | Timeout value in seconds. |
tags | Any 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 |
forceOnline | TRUE = do not allow offline approval, FALSE = allow ICC to approve offline if terminal capable |
autoAuthenticate | Will automatically execute Authenticate Transacation after start transaction returns successful |
fallback | Indicate if it supports fallback to MSR |
NOTE ON INTERFACE SELECTION: For the NEO2, tag DFEF37 is used to determine which interfaces to use for the transaction:
- (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
KCV | ASN.1 structure of KCV |
- (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.
key | 16 byte key used for MAC generation of Read or Write with MAC |
- (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.
serviceCode | Service Code List. Each service code in Service Code List = 2 bytes of data |
numBlocks | Number of blocks |
blockList | Blocks to read. Maximum 4 block requests |
blocks | Blocks read. Each block 16 bytes. |
- (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.
numBlocks | Number of blocks |
blockList | Block to read. Each block in blockList Maximum 3 block requests |
blocks | Blocks read. Each block 16 bytes. |
- (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.
nodeCode | Node Code |
response | Response as explained in FeliCA Lite-S User's Manual |
- (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.
command | Command data from settlement center to be sent to felica card |
response | Response data from felica card |
- (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.
serviceCode | Service Code list. Each service code must be be 2 bytes |
blockCount | Block Count |
blockList | Block list. |
data | Block to write. Must be 16 bytes. |
statusFlag | Status flag response as explained in FeliCA Lite-S User's Manual, Section 4.5 |
- (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.
blockNumber | Number of block |
data | Block to write. Must be 16 bytes. |
- (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.
dataAPDU | APDU data packet |
response | Unencrypted/encrypted parsed APDU response |
- (RETURN_CODE) icc_getICCReaderStatus: | (ICCReaderStatus **) | readerStatus |
Get Reader Status
Returns the reader status
readerStatus | Pointer that will return with the ICCReaderStatus results. |
- (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.
amount | Transaction amount value (tag value 9F02) |
exponent | Number of characters after decimile point |
type | Transaction type (tag value 9C). |
timeout | Timeout value in seconds. |
transTags | Any other transaction tags to be included in the request (excluding Apple VAS and SmartTap) |
VAS | Tags 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)
|
NOTE ON INTERFACE SELECTION: For the NEO2, tag DFEF37 is used to determine which interfaces to use for the transaction:
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
format | Response 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 |
- (RETURN_CODE) icc_powerOffICC: | (NSString **) | error |
Power Off ICC
Powers down the ICC
error | Returns the error, if any |
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
response | Response returned. If Success, ATR String. If Failure, ASCII encoded data of error string |
- (RETURN_CODE) icc_setKeyFormatForICCDUKPT: | (NSData *) | encryption |
Set Key format for ICC DUKPT
Specifies how data will be encrypted with Data Key or PIN key
encryption | The 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 |
- (bool) isConnected |
Check if device is connected
- (RETURN_CODE) msr_cancelMSRSwipe |
Disable MSR Swipe
Cancels Swipe.
Cancels Transaction request (all interfaces, CTLS/MSR/INSERT).
- (RETURN_CODE) msr_getConfiguration: | (NSData **) | config |
Get MSR Configuration
Gets the MSR configuration data
config | Configuration data retrieved |
- (RETURN_CODE) msr_getMSRTrack: | (int *) | val |
Get MSR Track
Returns the track value of the MSR
val | The value of the current MSR tracks setting
|
- (RETURN_CODE) msr_retrieveWhiteList: | (NSData **) | value |
Retrieve MSR White List
Retrieves the whitelist
value | The whitelist data which is in ASN.1 block format |
- (RETURN_CODE) msr_setConfiguration: | (NSData *) | config |
Set MSR Configuration
Sets MSR configuration data
config | Configuration data to send |
- (RETURN_CODE) msr_setMSRTrack: | (int) | val |
Set MSR Track
Sets the track value of the MSR
val | The value of the current MSR tracks setting
|
- (RETURN_CODE) msr_startMSRSwipe |
Enable MSR Swipe
Enables CLTS and MSR, waiting for swipe or tap to occur. Returns IDTEMVData to deviceDelegate::emvTransactionData:()
- (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:()
- (RETURN_CODE) pin_captureAmountInput: | (int) | minPIN | |
maxPIN: | (int) | maxPIN | |
message: | (NSString *) | message | |
signature: | (NSData *) | signature | |
Capture Amount Input
minPIN | Minimum PIN Length |
maxPIN | Maximum PIN Length |
message | LCD Message |
signature | Display message signed by Numeric Private Key using RSAPSS algorithm:
|
Results returned to pinpadData delegate
- (RETURN_CODE) pin_captureFunctionKey |
Capture Function Key
Captures a function key entry on the pinpad
Results returned to pinpadData delegate
- (RETURN_CODE) pin_captureNumericInput: | (bool) | mask | |
minPIN: | (int) | minPIN | |
maxPIN: | (int) | maxPIN | |
message: | (NSString *) | message | |
signature: | (NSData *) | signature | |
Capture Numeric Input
mask | True = mask input with "*", False = no masking of input |
minPIN | Minimum PIN Length |
maxPIN | Maximum PIN Length |
message | LCD Message |
signature | Display message signed by Numeric Private Key using RSAPSS algorithm:
|
Results returned to pinpadData delegate
- (RETURN_CODE) pin_capturePin: | (int) | type | |
PAN: | (NSString *) | PAN | |
minPIN: | (int) | minPIN | |
maxPIN: | (int) | maxPIN | |
message: | (NSString *) | message | |
Capture PIN
type | PAN and Key Type
|
PAN | Personal Account Number (if internal, value is 0) |
minPIN | Minimum PIN Length |
maxPIN | Maximum PIN Length |
message | LCD Message |
Results returned to pinpadData delegate
- (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
scanTime | Amount of time to search for devices before returning alert view. |
serviceUUIDs | A null terminated array of CBUUID to filter for specific device type. Sending nil will report all ble devices in range |
options | scan 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
scanTime | Amount of time to search for devices before returning alert view. |
serviceUUIDs | A null terminated array of CBUUID to filter for specific device type. Sending nil will report all ble devices in range |
options | scan 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
- (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];
filter | The array of services to filter for |
- (void) setServiceUUID: | (nullable NSArray< CBUUID * > *) | serviceUUIDs |
Set BLE to filter for specified service UUID
setServiceUUID | Sets the UUID filter to be used when discovering BLE devices |
+ (IDT_NEO2*) sharedController |
- (RETURN_CODE) updateFirmwareNeo2: | (FIRMWARE_TYPE) | type | |
data: | (NSData *) | firmwareData | |
Update NEO 2 Firmware
Reserved for system use
|
readwriteatomicstrong |