IDTech iOS/OSX SDK Guide  1.1.084
API reference for UniPay 1.5
IDT_UniPayI_V Class Reference

#import <IDT_UniPayI_V.h>

Inheritance diagram for IDT_UniPayI_V:

Instance Methods

(void) - close
 
(void) - device_connectToUSB
 
(RETURN_CODE) - device_cancelConnectToAudioReader
 
(RETURN_CODE) - device_connectToAudioReader
 
(RETURN_CODE) - device_getFirmwareVersion:
 
(BOOL) - device_isAudioReaderConnected
 
(NSString *) - device_getResponseCodeString:
 
(bool) - device_isConnected:
 
(RETURN_CODE) - device_sendIDGCommand:subCommand:data:response:
 
(RETURN_CODE) - device_setAudioVolume:
 
(RETURN_CODE) - device_setPassThrough:
 
(RETURN_CODE) - emv_authenticateTransaction:
 
(RETURN_CODE) - device_startRKI
 
(RETURN_CODE) - emv_callbackResponseLCD:selection:
 
(RETURN_CODE) - emv_completeOnlineEMVTransaction:hostResponseTags:
 
(void) - emv_disableAutoAuthenticateTransaction:
 
(RETURN_CODE) - emv_getEMVL2Version:
 
(RETURN_CODE) - emv_removeApplicationData:
 
(RETURN_CODE) - emv_removeCAPK:index:
 
(RETURN_CODE) - emv_removeCRLList
 
(RETURN_CODE) - emv_removeTerminalData
 
(RETURN_CODE) - emv_retrieveAIDList:
 
(RETURN_CODE) - emv_retrieveApplicationData:response:
 
(RETURN_CODE) - emv_retrieveCAPK:index:response:
 
(RETURN_CODE) - emv_retrieveCAPKFile:index:response:
 
(RETURN_CODE) - emv_retrieveCAPKList:
 
(RETURN_CODE) - emv_retrieveCRLList:
 
(RETURN_CODE) - emv_retrieveTerminalData:
 
(RETURN_CODE) - emv_retrieveTransactionResult:retrievedTags:
 
(RETURN_CODE) - emv_setApplicationData:configData:
 
(RETURN_CODE) - emv_setCAPK:
 
(RETURN_CODE) - emv_setCAPKFile:
 
(RETURN_CODE) - emv_setCRLEntries:
 
(RETURN_CODE) - emv_setTerminalData:
 
(RETURN_CODE) - emv_startTransaction:amtOther:type:timeout:tags:forceOnline:fallback:
 
(RETURN_CODE) - config_getSerialNumber:
 
(RETURN_CODE) - icc_exchangeAPDU:response:
 
(RETURN_CODE) - icc_getICCReaderStatus:
 
(RETURN_CODE) - icc_powerOnICC:
 
(RETURN_CODE) - icc_powerOffICC:
 
(RETURN_CODE) - msr_cancelMSRSwipe
 
(RETURN_CODE) - msr_startMSRSwipe
 
(bool) - isConnected
 

Class Methods

(NSString *) + SDK_version
 
(IDT_UniPayI_V *) + sharedController
 

Properties

id< IDT_UniPayI_V_Delegatedelegate
 

Detailed Description

Class to drive the IDT_UniPayI_V device

Method Documentation

- (void) close

Close Device

- (RETURN_CODE) config_getSerialNumber: (NSString **)  response

Polls device for Serial Number

Parameters
responseReturns Serial Number
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_UniPay::device_getResponseCodeString:()
- (RETURN_CODE) device_cancelConnectToAudioReader

Cancel Connect To Audio Reader

Returns
RETURN_CODE

Cancels a connection attempt to an IDTech MSR device connected via the audio port.

- (RETURN_CODE) device_connectToAudioReader

Connect To Audio Reader

Returns
RETURN_CODE

Attemps to recognize and connect to an IDTech MSR device connected via the audio port.

- (void) device_connectToUSB

Connect To Audio Reader

Attemps to recognize and connect to an IDTech MSR device connected via the USB port (OSX only).

- (RETURN_CODE) device_getFirmwareVersion: (NSString **)  response

Polls device for Firmware Version

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

Get Response Code String

Interpret a response code and return string description.

Parameters
errorCodeError code, range 0x0000 - 0xFFFF, example 0x0300
Returns
Verbose error description
- (BOOL) device_isAudioReaderConnected

Is Audio Reader Connected

Returns value on device connection status when device is an audio-type connected to headphone plug.

Returns
BOOL True = Connected, False = Disconnected
- (bool) device_isConnected: (IDT_DEVICE_Types)  device

Is Device Connected

Returns the connection status of the requested device

Parameters
deviceCheck connectivity of device type
typedef enum{
IDT_DEVICE_UniPayI_V_IOS
IDT_DEVICE_UniPayI_V_OSX_USB
}IDT_DEVICE_Types;
- (RETURN_CODE) device_sendIDGCommand: (unsigned char)  command
subCommand: (unsigned char)  subCommand
data: (NSData *)  data
response: (NSData **)  response 

Send NEO IDG Command Send a NEO IDG ViVOtech 2.0 command

Parameters
commandOne byte command as per NEO IDG Reference Guide
subCommandOne byte sub-command as per NEO IDG Reference Guide
dataCommand data (if applicable)
responseReturns next Command response
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_UniMagIII::device_getResponseCodeString:()
- (RETURN_CODE) device_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.

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

Set Pass Through

Sets Pass-Through mode on UniPayI_V

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

Start Remote Key Injection

Attempts to perform a Remote Key Injection with IDTech's RKI servers.

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
  • 0x0100 through 0xFFFF refer to IDT_Device::getResponseCodeString:()
- (RETURN_CODE) emv_authenticateTransaction: (NSData *)  tags

Authenticate Transaction

Authenticated 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:()

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

Callback Response LCD Display

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

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

Complete EMV Transaction Online Request

Completes an online EMV transaction request by the card

The tags will be returned in the emvTransactionData delegate protocol.

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

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

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

Disable Auto Authenticate Transaction

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

Parameters
disableFALSE = auto authenticate ENABLED, TRUE = auto authenticate DISABLED
- (RETURN_CODE) emv_getEMVL2Version: (NSString **)  response

Polls device for EMV L2 Version

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

Remove Application Data by AID

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

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

Remove Certificate Authority Public Key

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

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

Remove Certificate Revocation List

Removes all CRLEntry entries

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

Remove Terminal Data

Removes the Terminal Data

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

Retrieve AID list

Returns all the AID names on the terminal. Populates response parameter with an Array of NSString* with AID names

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

Retrieve Application Data by AID

  • UniPay II

Retrieves the Application Data as specified by the AID name passed as a parameter. The AID will be in the response parameter responseAID

Parameters
AIDName of ApplicationID in ASCII, example "A0000000031020". Must be between 5 and 16 characters
responseAIDThe response returned from the method as a dictionary with Key/Object to match TagValues as follows:

Tag | Description ===== | ===== 5F57 | Account Type 9F01 | Acquirer Identifier 9F09 | Terminal application version number 5F36 | Transaction Currency Exponent 9F1B | Terminal Floor Limit 9F49 | Dynamic Data Authentication Data Object List(DDOL) 97 | Transaction Certificate Data Object List(TDOL) 9F39 | POS Entry Mode 9F3C | Transaction Reference Currency Code 9F3D | Transaction Reference Currency Exponent 99 | PIN Block DF10 | LANGUAGE DF11 | Use Trans Log DF13 | TAC-Default DF14 | TAC-Denial DF15 | TAC-Online DF17 | Threshold Value for Biased Random Selection DF18 | Target Percentage For Random Transaction Selection DF19 | Maximum Target Percentage For Random Transaction Selection DF20 | Trace DF22 | Merchant Forced Transaction Online DF25 | Default DDOL DF26 | Use Revocation list DF27 | Use Exception list DF28 | TDOL DF30 | Online DOL DF62 | Application Selection Flag DF63 | Transaction Reference Currency Conversion

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) emv_retrieveCAPK: (NSString *)  rid
index: (NSString *)  index
response: (CAKey **)  response 

Retrieve Certificate Authority Public Key

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

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

Retrieve Certificate Authority Public Key

  • BTPay 200

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

Parameters
ridThe RID of the key to retrieve
indexThe Index of the key to retrieve
responseResponse returned as a NSData object with the following data:
  • 5 bytes RID
  • 1 byte Index
  • 1 byte Hash Algorithm
  • 1 byte Encryption Algorithm
  • 20 bytes HashValue
  • 4 bytes Public Key Exponent
  • 2 bytes Modulus Length
  • Variable bytes Modulus>
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to IDT_Device::getResponseCodeString:()
- (RETURN_CODE) emv_retrieveCAPKList: (NSArray **)  response

Retrieve the Certificate Authority Public Key list

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

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

Retrieve the Certificate Revocation List

Returns all the RID in the CRL.

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

Retrieve Terminal Data

  • UniPay II

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

Parameters
responseDataThe response returned from the method as a dictionary with Key/Object to match TagValues as follows:

9F1A | Terminal Country Code 9F35 | Terminal Type 9F33 | Terminal Capability 9F40 | Additional Terminal Capability 9F1E | IFD Serial Number 9F15 | Merchant Category Code 9F16 | Merchant Identifier 9F1C | Terminal Identification 9F4E | Merchant Name and Location DF10 | LANGUAGE DF11 | Use Trans Log DF13 | TAC-Default DF14 | TAC-Denial DF15 | TAC-Online DF17 | Threshold Value for Biased Random Selection DF18 | Target Percentage For Random Transaction Selection DF19 | Maximum Target Percentage For Random Transaction Selection DF20 | Trace DF22 | Merchant Forced Transaction Online DF25 | Default DDOL DF26 | Use Revocation list DF27 | Use Exception list DF28 | TDOL DF30 | Online DOL DF62 | Application Selection Flag DF63 | Transaction Reference Currency

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) emv_retrieveTransactionResult: (NSData *)  tags
retrievedTags: (NSDictionary **)  retrievedTags 

Retrieve Transaction Results

Retrieves specified EMV tags from the currently executing transaction.

Parameters
tagsTags to be retrieved. Example 0x9F028A will retrieve tags 9F02 and 8A
tlvAll requested tags returned as unencrypted, encrypted and masked tags. The tlv NSDictionary will contain a NSDictionary with key "tags" that has the unencrypted tag data, a NSDictionary with the key "masked" that has the masked tag data, and a NSDictionary with the key "encrypted" that has the encrypted tag data
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
- (RETURN_CODE) emv_setApplicationData: (NSString *)  aidName
configData: (NSDictionary *)  data 

Set Application Data by AID

Sets the Application Data as specified by the dictionary containing Tags (dictionary keys) and Values (dictionary objects) according to the following table

Tag | Description ===== | ===== 5F57 | Account Type 9F01 | Acquirer Identifier 9F09 | Terminal application version number 5F36 | Transaction Currency Exponent 9F1B | Terminal Floor Limit 9F49 | Dynamic Data Authentication Data Object List(DDOL) 97 | Transaction Certificate Data Object List(TDOL) 9F39 | POS Entry Mode 9F3C | Transaction Reference Currency Code 9F3D | Transaction Reference Currency Exponent 99 | PIN Block DF10 | LANGUAGE DF11 | Use Trans Log DF13 | TAC-Default DF14 | TAC-Denial DF15 | TAC-Online DF17 | Threshold Value for Biased Random Selection DF18 | Target Percentage For Random Transaction Selection DF19 | Maximum Target Percentage For Random Transaction Selection DF20 | Trace DF22 | Merchant Forced Transaction Online DF25 | Default DDOL DF26 | Use Revocation list DF27 | Use Exception list DF28 | TDOL DF30 | Online DOL DF62 | Application Selection Flag DF34 | Authorization Response Code: 1-2 bytes=approved code, 3-4 bytes = referral code, 5-6 bytes = declined code

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

Set Certificate Authority Public Key

Sets the CAPK as specified by the CAKey structure

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

Set Certificate Authority Public Key

Sets the CAPK as specified by the CAKey raw format

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

Set Certificate Revocation List

Sets the CRL list

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

Set Terminal Data

  • UniPay II

Sets the Terminal Data as specified by the dictionary containing Tags (dictionary keys) and Values (dictionary objects) according to the following table

Tag | Description ===== | ===== 5F36 | Transaction Currency Exponent 9F1A | Terminal Country Code 9F35 | Terminal Type 9F33 | Terminal Capability 9F40 | Additional Terminal Capability 9F1E | IFD Serial Number 9F15 | Merchant Category Code 9F16 | Merchant Identifier 9F1C | Terminal Identification 9F4E | Merchant Name and Location DF10 | LANGUAGE DF11 | Use Trans Log DFEE13 | TAC-Default DFEE14 | TAC-Denial DFEE2A | Threshold Value for Biased Random Selection DF18 | Target Percentage For Random Transaction Selection DF19 | Maximum Target Percentage For Random Transaction Selection DF20 | Trace DF22 | Merchant Forced Transaction Online DF25 | Default DDOL DF26 | Use Revocation list DF27 | Use Exception list DF28 | TDOL DF30 | Online DOL DFEE15 | Application Selection Flag DF63 | Transaction Reference Currency Conversion

Parameters
dataNSDictionary with Tags/Values for the Terminal configuration file
Returns
RETURN_CODE:
  • 0x0000: Success: no error - RETURN_CODE_DO_SUCCESS
  • 0x0001: Disconnect: no response from reader - RETURN_CODE_ERR_DISCONNECT
  • 0x0002: Invalid Response: invalid response data - RETURN_CODE_ERR_CMD_RESPONSE
  • 0x0003: Timeout: time out for task or CMD - RETURN_CODE_ERR_TIMEDOUT
  • 0x0004: Invalid Parameter: wrong parameter - RETURN_CODE_ERR_INVALID_PARAMETER
  • 0x0005: MSR Busy: SDK is doing MSR or ICC task - RETURN_CODE_SDK_BUSY_MSR
  • 0x0006: PINPad Busy: SDK is doing PINPad task - RETURN_CODE_SDK_BUSY_PINPAD
  • 0x0007: Unknown: Unknown error - RETURN_CODE_ERR_OTHER
  • 0x0100 through 0xFFFF refer to IDT_Device::getResponseCodeString:()
- (RETURN_CODE) emv_startTransaction: (double)  amount
amtOther: (double)  amtOther
type: (int)  type
timeout: (int)  timeout
tags: (NSData *)  tags
forceOnline: (BOOL)  forceOnline
fallback: (BOOL)  fallback 

Start EMV Transaction Request

Authorizes the EMV transaction for an ICC card

The tags will be returned in the emvTransactionData delegate protocol.

By default, auto authorize is ENABLED. If auto authorize is DISABLED, this function will complete with a return of EMV_RESULT_CODE_START_TRANSACTION_SUCCESS to emvTransactionData delegate protocol, and then IDT_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:

Parameters
amountTransaction amount value (tag value 9F02)
amtOtherOther amount value, if any (tag value 9F03)
typeTransaction type (tag value 9C).
timeoutTimeout value in seconds.
tagsAny other tags to be included in the request. Passed as a NSData. Example, tag 9F0C with amount 0x000000000100 would be 0x9F0C06000000000100 If tags 9F02 (amount),9F03 (other amount), or 9C (transaction type) are included, they will take priority over these values supplied as individual parameters to this method. Tag DFEE1A can be used to specify tags to be returned in response, in addition to the default tags. Example DFEE1A049F029F03 will return tags 9F02 and 9F03 with the response
forceOnlineTRUE = do not allow offline approval, FALSE = allow ICC to approve offline if terminal capable
autoAuthenticateWill automatically execute Authenticate Transacation after start transaction returns successful
fallbackIndicate if it supports fallback to MSR
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
- (RETURN_CODE) icc_exchangeAPDU: (NSData *)  dataAPDU
response: (APDUResponse **)  response 

Exchange APDU (unencrypted)

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

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

Get Reader Status

Returns the reader status

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

Power Off ICC

Powers down the ICC

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

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

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

Power On ICC

Power up the currently selected microprocessor card in the ICC reader

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

Check if device is connected

- (RETURN_CODE) msr_cancelMSRSwipe

Disable MSR Swipe

Cancels MSR swipe request.

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

Enable MSR Swipe

Enables CLTS and MSR, waiting for swipe or tap to occur. If swipe captured, returns IDTMSRData instance to deviceDelegate::swipeMSRData:(). If CTLS captured, returns IDTEMVData to deviceDelegate::emvTransactionData:()

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_UniPay::device_getResponseCodeString:()
+ (NSString*) SDK_version

SDK Version

Returns the current version of IDTech.framework

Returns
Framework version
+ (IDT_UniPayI_V*) sharedController

Singleton Instance

Establishes an singleton instance of IDT_UniPayI_V class.

Returns
Instance of IDT_UniPayI_V

Property Documentation

- (id< IDT_UniPayI_V_Delegate >) delegate
readwriteatomicstrong

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