![]() |
IDTech iOS SDK Guide
1.1.166.045
API reference for VP3300
|
#import <IDT_VP3300.h>
Class Methods | |
(void) | + disableAudioDetection |
(NSString *) | + SDK_version |
(IDT_VP3300 *) | + sharedController |
(NSString *) | + createFastEMVData: |
Properties | |
id< IDT_VP3300_Delegate > | delegate |
id< IDT_VP3300_Delegate > | bypassDelegate |
Class to drive the IDT_VP3300 device
- (RETURN_CODE) activateTransaction: | (NSMutableDictionary< NSString *, NSString * > *_Nullable) | tags | |
timeout: | (int) | timeout | |
Activate Transaction
Use this command when the ctls reader is in “Poll on Demand” mode to begin an EMV or contactless MagStripe Card transaction. When the reader is in “Poll on Demand” mode, the RF is turned on only after receiving an Activate Transaction command. When a valid Activate Transaction command is sent to the ctls reader, it starts polling for cards.
If the ctls reader does not find a supported card (an AID that matches one of the configured AIDs in the reader) for the specified time duration, it times out and ends the transaction. If the ctls reader finds a card within the specified time interval, it attempts to carry out the transaction. The transaction flow between the reader and the card depends on the type of card detected.
If the transaction is successful, the reader returns the data in CTLSResponse. If the transaction is not successful, yet it proceeded into the transaction state machine, the reader returns a Failed Transaction Record in the response data. The presence and format of the Clearing Record, Track Data and Failed Transaction record depends on the type of card that was detected.
Note: While an Activate command is in progress, only a Cancel may be sent. Do not send other commands until Activate Transaction has completed, because the reader will interpret these as a Cancel Transaction command.
tags | Activate TLV tags |
timeout | Timeout value in seconds. |
Activate TVL Tag | Description | Format | Length |
---|---|---|---|
9A | Transaction Date | n6 (YYMMDD) | 3 |
9C | Transction Type | n2 | 2 |
5F2A | Transaction Currency Code | n2 | 2 |
5F36 | Transaction Currency Exponent | n1 | 1 |
9F02 | Amount, Authorized | n12 | 6 |
9F03 | Amount Other | n12 | 6 |
9F1A | Terminal Country Code | n3 | 2 |
9F21 | Transaction Time | n6 (HHMMSS} | 3 |
9F5A | Terminal Transaction Type | b | 1 |
Transaction Types: 0x00 = Purchase Goods/Services, 0x20 = Refund Terminal Transaction Type (Interac) 0x00 = Purchase, 0x01 = Refund
EMV data is received in TLV (Tag, Length, value) format: 950500000080009B02E8009F2701018A025A339F26080C552B9364D55CE5
This data contains the following EMV tags/values:
Tag | Length | Value |
---|---|---|
9502 | 06 | 000000001995 |
9A | 03 | 140530 |
9C | 01 | 00 |
An example how to create an NSMutableDictionary with these values follows.
- (void) assignBypassDelegate: | (id< IDT_VP3300_Delegate >) | del |
- (void) close |
Close Device
- (RETURN_CODE) config_getSerialNumber: | (NSString **) | response |
Polls device for Serial Number
response | Returns Serial Number |
+ (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 (swipe or CTLS).
- (RETURN_CODE) ctls_getAllConfigGroups: | (NSData **) | 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_getAllConfigurationGroups: | (NSDictionary< NSString *, NSDictionary * > **) | response |
Get All Configuration Groups
Retrieves all Configuration Groups.
response | |
response | Groups returned as Data stream |
- (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_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_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 FFEE - > FFEE0100). The terminal data can also be retrieved by ctls_getConfiguraitonGroup(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 (FFE4). The second tag of the TLV data must be the AID (9F06) |
Example valid TLV, for Group #2, AID a0000000035010: "ffe401029f0607a0000000051010ffe10101ffe50110ffe30114ffe20106"
- (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 (FFE4). 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 |
Enable Transaction Request
Enables CLTS and MSR, waiting for swipe or tap to occur. Returns IDTEMVData to deviceDelegate::emvTransactionData:()
- (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 APPLEPAY VAS: To enable ApplePay VAS, first a merchant record must be defined in one of the six available index positions (1-6) using device_setMerchantRecord, then container tag FFEE06 must be sent as part of the additional tags parameter of ctls_startTransaction. Tag FFEE06 must contain tag 9F26 and 9F22, and can optionanally contain tags 9F2B and DFO1. Example FFEE06189F220201009F2604000000009F2B050100000000DF010101 9F22 = two bytes = ApplePay Terminal Applicaiton Version Number. Hard defined as 0100 for now. (required) 9F26 = four bytes = ApplePay Terminal Capabilities Information (required)
- (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_cancelConnectToAudioReader |
Cancel Connect To Audio Reader
Cancels a connection attempt to an IDTech MSR device connected via the audio port.
- (RETURN_CODE) device_cancelTransaction |
Cancels Transaction request (EMV, swipe or CTLS).
- (NSUUID*) device_connectedBLEDevice |
Returns the UUID of the connected BLE device
VP3300
- (RETURN_CODE) device_connectToAudioReader |
Connect To Audio Reader
Attemps to recognize and connect to an IDTech MSR device connected via the audio port.
- (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
|
- (bool) device_disableBLEDeviceSearch |
Stops searching for Bluetooth Low Energy devices in range
VP3300
NOTE: BLE only scans when there are no devices currently connected. After the SDK connects to any IDTech device, the scanning will pause automatically.
- (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
VP3300
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_VP3300::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_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_getCashTranRiskPara: | (NSData **) | tlv |
Get Cash Transaction Reader Risk Parameters
Returns the TTQ and reader risk parameters that will be used for cash transactions, if enabled
tlv | TLV data objects |
- (RETURN_CODE) device_getDateTime: | (NSData **) | dateTime |
Device Get DateTime
Gets the current system date and time of the device for VP3300 and UNIPAYI_V
dateTime | The date time returned as follows: -byte 0: Year 00-99 -byte 1: Month 01-12 -byte 2: Day 01-31 -byte 3: Hour 00-23 -byte 4: Minute 00-59 -byte 5: Second 00-59 |
- (RETURN_CODE) device_getDrlReaderRiskPara: | (Byte) | index | |
tlv: | (NSData **) | tlv | |
Get DRL Reader Risk Parameters
Gets the index, application program ID, and reader risk parameters for the DRL settings
index | DRL index (01-04) |
tlv | TLV data objects |
- (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_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
|
- (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_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_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_getUIDofMCU: | (NSString **) | response |
Get UID of MCU
Returns the UID of the device
response | The module UID information |
- (BOOL) device_isAudioReaderConnected |
Is Audio Reader Connected
Returns value on device connection status when device is an audio-type connected to headphone plug.
- (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_pingDevice |
Ping Device
Pings the reader. If it is connected, returns success, otherwise returns timeout
- (RETURN_CODE) device_rebootDevice |
Reboot Device
Executes a command to restart the device.
- (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_sendGen2Cmd: | (NSData *) | tlv | |
response: | (NSData **) | response | |
Send 2nd Gen Command
Informs SDK to format command for EMV Gen2 Device Communication
tlv | TLV Command |
response | TLV Response |
- (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 |
- (RETURN_CODE) device_setAudioVolume: | (float) | val |
Set Volume To Audio Reader
Set the iPhone’s volume for command communication with audio-based readers. The the range of iPhone’s volume is from 0.1 to 1.0.
val | Volume level from 0.1 to 1.0 |
- (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_setDateTime |
Set Date Time
Sets the date and time of the device to the current date and time of the iOS device
- (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 identifier registered with Apple. Example: ID TECH |
merchantURL | Merchant URL, when applicable Example: com.idtechproducts.applePay |
- (RETURN_CODE) device_setPassThrough: | (BOOL) | enablePassThrough |
Set Pass Through
Sets Pass-Through mode on VP3300
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_setQuickChipHIDMode: | (Byte) | mode |
Set QuickChip HID Mode
Puts the device into QuickChip KB Output Mode while in HID
mode |
|
- (RETURN_CODE) device_setTerminalData: | (NSData *) | tags |
Set Terminal Data
Sets the Terminal Data .
responseData | The data to set |
- (RETURN_CODE) device_startRKI |
Start Remote Key Injection
Attempts to perform a Remote Key Injection with IDTech's RKI servers.
- (RETURN_CODE) device_startTransaction: | (double) | amount | |
amtOther: | (double) | amtOther | |
type: | (int) | type | |
timeout: | (int) | timeout | |
tags: | (NSData *) | tags | |
forceOnline: | (BOOL) | forceOnline | |
fallback: | (BOOL) | fallback | |
Start A Transaction Request
Authorizes the EMV, CTLS, or MSR transaction
For a contact ICC EMV transaction, 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_UniPayII::emv_authenticateTransaction() must be executed. If auto authorize is ENABLED (default), IDT_UniPayII::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 |
- (RETURN_CODE) device_syncClock |
Sync Clock Syncs the VP3300 clock with the iOS device clock
- (RETURN_CODE) device_syncTime |
Sync Time Syncs the VP3300 time with the iOS device clock
+ (void) disableAudioDetection |
Disable Audio Detection. For BLE implementations. Removes monitoring headphone jack for audio devices.
- (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_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_cancelTransaction |
Cancels Transaction request (EMV).
- (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_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 |
- (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_VP3300::emv_authenticateTransaction() must be executed. If auto authorize is ENABLED (default), IDT_VP3300::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 |
- (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 |
Get Key format for ICC DUKPT
Specifies how data is being encrypted with Data Key or PIN key
format | Response return from method: -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 |
- (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 MSR swipe request.
- (RETURN_CODE) msr_startMSRSwipe |
Enable MSR Swipe
Enables CLTS and MSR, waiting for swipe or tap to occur. Returns IDTEMVData to deviceDelegate::emvTransactionData:()
- (void) processBypassResponse: | (NSData *) | data |
Process Bypass Response.
When output is being bypassed, and a command is received in the delegate redirectedOutput and sent to the device, the device rexponse must be sent to this method so the SDK can finishing processing the results;
data | The data received from the device that the SDK must process to complete the executing command |
- (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) setBLEDeviceTypeVP3300 |
Sets BLE search filter for VP3300 family
- (void) setReaderAttached: | (BOOL) | attached |
Set Reader Attached
Forces the device to reader attached state.
attached | TRUE = attached, FALSE = not attached |
- (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_VP3300*) sharedController |
Singleton Instance
Establishes an singleton instance of IDT_VP3300 class.
|
readwriteatomicstrong |
|
readwriteatomicstrong |