IDTech iOS SDK Guide  1.1.166.045
API reference for NEO2
<IDT_NEO2_Delegate> Protocol Reference

#import <IDT_NEO2.h>

Inheritance diagram for <IDT_NEO2_Delegate>:

Instance Methods

(void) - deviceConnected
 Fires when device connects. If a connection is established before the delegate is established (no delegate to send initial connection notification to), this method will fire upon establishing the delegate.
 
(void) - deviceDisconnected
 Fires when device disconnects.
 
(void) - dataInOutMonitor:incoming:
 
(void) - swipeMSRData:
 
(void) - deviceMessage:
 
(void) - updateStatus:currentBlock:totalBlocks:error:
 
(RETURN_CODE) - sendPKUpdate:
 
(RETURN_CODE) - sendPKUpdateBLE:
 
(void) - pinRequest:key:PAN:startTO:intervalTO:language:
 
(void) - bluetoothPickerAlert:
 
(void) - bluetoothDeviceNames:
 
(RETURN_CODE) - activateTransaction:timeout:
 
(void) - pinpadData:keySN:event:
 
(void) - lcdDisplay:lines:
 
(void) - emvTransactionData:errorCode:
 

Detailed Description

Protocol methods established for IDT_NEO2 class

Method Documentation

- (RETURN_CODE) activateTransaction: (NSMutableDictionary< NSString *, NSString * > *_Nullable)  tags
timeout: (int)  timeout 
optional

Activate Transaction

  • VP3300 Initiates a CTLS 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.

Parameters
tagsActivate TLV tags
timeoutTimeout 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 n32
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

Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0xFF00: Accept the online transaction RETURN_CODE_EMV_APPROVED
  • 0xFF01: Decline the online transaction RETURN_CODE_EMV_DECLINED
  • 0xFF02: Request to go online RETURN_CODE_EMV_GO_ONLINE
  • 0xFF03: Transaction is terminated RETURN_CODE_EMV_FAILED
  • 0xFF05: ICC format error or ICC missing data error RETURN_CODE_EMV_SYSTEM_ERROR
  • 0xFF07: ICC didn't accept transaction RETURN_CODE_EMV_NOT_ACCEPTED
  • 0xFF0A: Application may fallback to magstripe technology RETURN_CODE_EMV_FALLBACK
  • 0xFF0C: Transaction was cancelled RETURN_CODE_EMV_CANCEL
  • 0xFF0D: Timeout RETURN_CODE_EMV_TIMEOUT
  • 0xFF0F: Other EMV Error RETURN_CODE_EMV_OTHER_ERROR
  • 0xFF10: Accept the offline transaction RETURN_CODE_EMV_OFFLINE_APPROVED
  • 0xFF11: Decline the offline transaction RETURN_CODE_EMV_OFFLINE_DECLINED
Converting TLV to NSMutableDictionary

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.

-(NSMutableDictionary*) createTLVDict{
NSMutableDictionary *emvTags = [[NSMutableDictionary alloc] initWithCapacity:0];
[emvTags setObject:@"000000001995" forKey:@"9502"];
[emvTags setObject:@"140530" forKey:@"9A"];
[emvTags setObject:@"00" forKey:@"9C"];
return emvTags;
}
- (void) bluetoothDeviceNames: (NSArray *)  names
optional

Bluetooth Device Names When a bluetooth name scan is requested, this delegate will return a NSArray with the names of the found devices

Parameters
namesNSArray of device names:
- (void) bluetoothPickerAlert: (UIAlertView *)  view
optional

Bluetooth Picker Alert When a bluetooth scan is requested, this delegate will return an UIAlertView for displaying to allow the selection of a found device

Parameters
viewUIAlertView:
- (void) dataInOutMonitor: (NSData *)  data
incoming: (BOOL)  isIncoming 
optional

All incoming/outgoing data going to the device can be monitored through this delegate.

Parameters
dataThe serial data represented as a NSData object
isIncomingThe direction of the data
  • TRUE specifies data being received from the device,
  • FALSE indicates data being sent to the device.
- (void) deviceMessage: (NSString *)  message
optional

Receives messages from the framework

Parameters
messageString message transmitted by framework
- (void) emvTransactionData: (IDTEMVData *)  emvData
errorCode: (int)  error 
optional

EMV Transaction Data

This protocol will receive results from IDT_Device::startEMVTransaction:otherAmount:timeout:cashback:additionalTags:()

Parameters
emvDataEMV Results Data. Result code, card type, encryption type, masked tags, encrypted tags, unencrypted tags and KSN
errorThe error code as defined in the errors.h file
- (void) lcdDisplay: (int)  mode
lines: (NSArray *)  lines 
optional

LCD Display Request During an EMV transaction, this delegate will receive data to clear virtual LCD display, display messages, display menu, or display language. Applies to UniPay III

Parameters
modeLCD Display Mode:
  • 0x01: Menu Display. A selection must be made to resume the transaction
  • 0x02: Normal Display get function key. A function must be selected to resume the transaction
  • 0x03: Display without input. Message is displayed without pausing the transaction
  • 0x04: List of languages are presented for selection. A selection must be made to resume the transaction
  • 0x10: Clear Screen. Command to clear the LCD screen
- (void) pinpadData: (NSData *)  value
keySN: (NSData *)  KSN
event: (EVENT_PINPAD_Types)  event 
optional

Pinpad data delegate protocol

Receives data from pinpad methods

Parameters
valueencrypted data returned from IDT_VP3300::pin_getEncryptedData:minLength:maxLength:messageID:language:(), or encrypted account number returned from IDT_VP3300::pin_getCardAccount:max:line1:line2:(). String value returned from IDT_VP3300::pin_getAmount:maxLength:messageID:language:() or IDT_VP3300::pin_getNumeric:minLength:maxLength:messageID:language:(). PINblock returned from IDT_VP3300::pin_getEncryptedPIN:keyType:line1:line2:line3:()
KSNKey Serial Number returned from IDT_VP3300::pin_getEncryptedPIN:keyType:line1:line2:line3:(), IDT_VP3300::pin_getCardAccount:max:line1:line2:() or IDT_VP3300::pin_getEncryptedData:minLength:maxLength:messageID:language:()
eventEVENT_PINPAD_Types PINpad event that solicited the data capture
typedef enum{
EVENT_PINPAD_UNKNOWN = 11,
EVENT_PINPAD_ENCRYPTED_PIN,
EVENT_PINPAD_NUMERIC,
EVENT_PINPAD_AMOUNT,
EVENT_PINPAD_ACCOUNT,
EVENT_PINPAD_ENCRYPTED_DATA,
EVENT_PINPAD_CANCEL,
EVENT_PINPAD_TIMEOUT,
EVENT_PINPAD_FUNCTION_KEY,
EVENT_PINPAD_DATA_ERROR
}EVENT_PINPAD_Types;
- (void) pinRequest: (EMV_PIN_MODE_Types)  mode
key: (NSData *)  key
PAN: (NSData *)  PAN
startTO: (int)  startTO
intervalTO: (int)  intervalTO
language: (NSString *)  language 
optional

PIN Request During an EMV transaction, this delegate will receive data that is a request to collect a PIN

Parameters
modePIN Mode:
  • EMV_PIN_MODE_CANCEL = 0X00,
  • EMV_PIN_MODE_ONLINE_PIN_DUKPT = 0X01,
  • EMV_PIN_MODE_ONLINE_PIN_MKSK = 0X02,
  • EMV_PIN_MODE_OFFLINE_PIN = 0X03
keyEither DUKPT or SESSION, depending on mode. If offline plaintext, value is nil
PANPAN for calculating PINBlock
startTOTimeout value to start PIN entry
intervalTOTimeout value between key presses
language"EN"=English, "ES"=Spanish, "ZH"=Chinese, "FR"=French
- (RETURN_CODE) sendPKUpdate: (NSData *)  pkFile
optional

Sends a PK Update

Starts a device firmware upatate using the provided path to the .pk file. Update proceeds on a background thread. Use protocol UpdateStatus to monitor progress. Keep device attached and do interrupt process until PK_STATUS_FAILED or PK_STATUS_COMPLETED has been received

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

Sends a PK Update (Faster)

Starts a device firmware upatate using the provided path to the .pk file. Update proceeds on a background thread. Use protocol UpdateStatus to monitor progress. Keep device attached and do interrupt process until PK_STATUS_FAILED or PK_STATUS_COMPLETED has been received

Data will be sent in packet size of 244 bytes. Sleep timers are modified or removed where possible to achieve faster times During transfer, no response will be sent by the device.

Parameters
pkDataThe .pk file
Returns
RETURN_CODE: Values can be parsed with IDT_Device::getResponseCodeString:()
- (void) swipeMSRData: (IDTMSRData *)  cardData
optional

Receives card data from MSR swipe.

Parameters
cardDataCaptured card data from MSR swipe
- (void) updateStatus: (PK_STATUS_Type)  type
currentBlock: (int)  currentBlock
totalBlocks: (int)  totalBlocks
error: (RETURN_CODE)  error 
optional

Reports PK Update status.

Parameters
typeThe stage of the PK update
currentBlockThe number of the block that has transferred
totalBlocksThe total number of blocks to transfer
errorThe error condition when failure is encoutered

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