IDTech iOS SDK Guide  1.1.113
API reference for NEO2
IDT_VP3600 Class Reference

#import <IDT_VP3600.h>

Inheritance diagram for IDT_VP3600:

Instance Methods

(void) - close
 
(RETURN_CODE) - ctls_cancelTransaction
 
(RETURN_CODE) - emv_cancelTransaction
 
(RETURN_CODE) - device_cancelTransaction
 
(RETURN_CODE) - ctls_getConfigurationGroup:response:
 
(RETURN_CODE) - ctls_removeAllCAPK
 
(RETURN_CODE) - ctls_removeApplicationData:
 
(RETURN_CODE) - ctls_removeCAPK:
 
(RETURN_CODE) - ctls_removeConfigurationGroup:
 
(RETURN_CODE) - ctls_retrieveAIDList:
 
(RETURN_CODE) - ctls_retrieveApplicationData:response:
 
(RETURN_CODE) - ctls_retrieveCAPK:key:
 
(RETURN_CODE) - ctls_retrieveCAPKList:
 
(RETURN_CODE) - ctls_retrieveTerminalData:
 
(RETURN_CODE) - ctls_setApplicationData:
 
(RETURN_CODE) - ctls_setCAPK:
 
(RETURN_CODE) - ctls_setConfigurationGroup:
 
(RETURN_CODE) - ctls_setTerminalData:
 
(RETURN_CODE) - ctls_startTransaction:type:timeout:tags:
 
(RETURN_CODE) - device_getFirmwareVersion:
 
(bool) - device_enableBLEDeviceSearch:
 
(NSString *) - device_getBLEFriendlyName
 
(void) - device_setBLEFriendlyName:
 
(bool) - device_disableBLEDeviceSearch
 
(NSUUID *) - device_connectedBLEDevice
 
(RETURN_CODE) - device_getAutoPollTransactionResults:
 
(NSString *) - device_getResponseCodeString:
 
(bool) - device_isConnected:
 
(RETURN_CODE) - device_sendIDGCommand:subCommand:data:response:
 
(RETURN_CODE) - device_setPassThrough:
 
(RETURN_CODE) - device_setBurstMode:
 
(RETURN_CODE) - device_setPollMode:
 
(RETURN_CODE) - emv_authenticateTransaction:
 
(RETURN_CODE) - emv_callbackResponseLCD:selection:
 
(RETURN_CODE) - emv_callbackResponsePIN:KSN:PIN:
 
(RETURN_CODE) - emv_completeOnlineEMVTransaction:hostResponseTags:
 
(void) - emv_disableAutoAuthenticateTransaction:
 
(RETURN_CODE) - emv_getEMVL2Version:
 
(RETURN_CODE) - emv_removeApplicationData:
 
(RETURN_CODE) - emv_removeCAPK:index:
 
(RETURN_CODE) - emv_setTerminalMajorConfiguration:
 
(RETURN_CODE) - emv_getTerminalMajorConfiguration:
 
(RETURN_CODE) - emv_removeCRLList
 
(RETURN_CODE) - emv_removeTerminalData
 
(RETURN_CODE) - emv_retrieveAIDList:
 
(RETURN_CODE) - emv_retrieveApplicationData:response:
 
(RETURN_CODE) - emv_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
 
(RETURN_CODE) - device_startTransaction:amtOther:type:timeout:tags:forceOnline:fallback:
 
(RETURN_CODE) - pin_captureFunctionKey
 
(RETURN_CODE) - pin_cancelPin
 
(RETURN_CODE) - pin_capturePin:PAN:minPIN:maxPIN:message:
 
(RETURN_CODE) - felica_authentication:
 
(RETURN_CODE) - felica_readWithMac:blocks:
 
(RETURN_CODE) - felica_writeWithMac:data:
 
(RETURN_CODE) - felica_read:blockList:blocks:
 
(RETURN_CODE) - felica_write:blockList:data:statusFlag:
 
(RETURN_CODE) - felica_poll:response:
 
(RETURN_CODE) - felica_requestService:response:
 
(RETURN_CODE) - pin_captureAmountInput:maxPIN:message:signature:
 
(RETURN_CODE) - pin_captureNumericInput:minPIN:maxPIN:message:signature:
 

Class Methods

(NSString *) + SDK_version
 
(IDT_VP3600 *) + sharedController
 

Properties

id< IDT_VP3600_Delegatedelegate
 

Detailed Description

Class to drive the IDT_VP3600 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 device_getResponseCodeString:
- (RETURN_CODE) ctls_cancelTransaction

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

Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_getConfigurationGroup: (int)  group
response: (NSDictionary **)  response 

Get Configuration Group

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

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

Remove All Certificate Authority Public Key

Removes all the CAPK for CTLS

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

Remove Application Data by AID

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

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

Remove Certificate Authority Public Key

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

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

Remove Configuration Group

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

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

Retrieve AID list

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

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

Retrieve Application Data by AID

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

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

Retrieve Certificate Authority Public Key

Retrieves the CAPKfor CTLS as specified by the RID/Index passed as a parameter.

Parameters
capk6 bytes CAPK = 5 bytes RID + 1 byte Index
keyResponse returned as a CAKey format: [5 bytes RID][1 byte Index][1 byte Hash Algorithm][1 byte Encryption Algorithm][20 bytes HashValue][4 bytes Public Key Exponent][2 bytes Modulus Length][Variable bytes Modulus] Where:
  • Hash Algorithm: The only algorithm supported is SHA-1.The value is set to 0x01
  • Encryption Algorithm: The encryption algorithm in which this key is used. Currently support only one type: RSA. The value is set to 0x01.
  • HashValue: Which is calculated using SHA-1 over the following fields: RID & Index & Modulus & Exponent
  • Public Key Exponent: Actually, the real length of the exponent is either one byte or 3 bytes. It can have two values: 3 (Format is 0x00 00 00 03), or 65537 (Format is 0x00 01 00 01)
  • Modulus Length: LenL LenH Indicated the length of the next field.
  • Modulus: This is the modulus field of the public key. Its length is specified in the field above.
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_retrieveCAPKList: (NSArray **)  keys

Retrieve the Certificate Authority Public Key list

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

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

Retrieve Terminal Data

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

Parameters
tlvResponse returned as a TLV
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_setApplicationData: (NSData *)  tlv

Set Application Data by AID

Sets the Application Data for CTLS as specified by TLV data

Parameters
tlvApplication data in TLV format The first tag of the TLV data must be the group number (DFEE2D). The second tag of the TLV data must be the AID (9F06)

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

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

Set Certificate Authority Public Key

Sets the CAPK for CTLS as specified by the CAKey structure

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

Set Configuration Group

Sets the Configuration Group for CTLS as specified by the TLV data

Parameters
tlvConfiguration Group Data in TLV format The first tag of the TLV data must be the group number (DFEE2D). A second tag must exist
Returns
RETURN_CODE: Return codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with device_getResponseCodeString:
- (RETURN_CODE) ctls_setTerminalData: (NSData *)  tlv

Set Terminal Data

Sets the Terminal Data for CTLS as specified by the TLV. The first TLV must be Configuration Group Number (Tag DFEE2D). The terminal global data is group 0, so the first TLV would be DFEE2D0100. Other groups can be defined using this method (1 or greater), and those can be retrieved with ctls_getConfigurationGroup(int group), and deleted with ctls_removeConfigurationGroup(int group). You cannot delete group 0.

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

Start a CTLS Transaction Request

Authorizes the CTLS transaction for an CTLS card

The tags will be returned in the callback routine.

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

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

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

    NOTE ON APPLEPAY VAS: 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)

    • Byte 1 = RFU
    • Byte 2 = Terminal Type
    • - Bit 8 = VAS Support (1=on, 0 = off)
    • - Bit 7 = Touch ID Required (1=on, 0 = off)
    • - Bit 6 = RFU
    • - Bit 5 = RFU
    • - Bit 1,2,3,4
    • - - 0 = Payment Terminal
    • - - 1 = Transit Terminal
    • - - 2 = Access Terminal
    • - - 3 = Wireless Handoff Terminal
    • - - 4 = App Handoff Terminal
    • - - 15 = Other Terminal
    • Byte 3 = RFU
    • Byte 4 = Terminal Mode
    • - 0 = ApplePay VAS OR ApplePay
    • - 1 = ApplePay VAS AND ApplePay
    • - 2 = ApplePay VAS ONLY
    • - 3 = ApplePay ONLY 9F2B = 5 bytes = ApplePay VAS Filter. Each byte filters for that specific merchant index (optional) DF01 = 1 byte = ApplePay VAS Protocol. (optional)
    • - Bit 1 : 1 = URL VAS, 0 = Full VAS
    • - Bit 2 : 1 = VAS Beeps, 0 = No VAS Beeps
    • - Bit 3 : 1 = Silent Comm Error, 2 = EMEA Comm Error
    • - Bit 4-8 : RFU
- (RETURN_CODE) device_cancelTransaction

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

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

Returns the UUID of the connected BLE device

  • VP3600

    Returns
    NSUUID UUID of the connected BLE device. Returns nil if no BLE device connected.
- (bool) device_disableBLEDeviceSearch

Stops searching for Bluetooth Low Energy devices in range

  • VP3600

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

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

- (bool) device_enableBLEDeviceSearch: (NSUUID *)  identifier

Begins searching for Bluetooth Low Energy devices in range

  • VP3600

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

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

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

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

- (RETURN_CODE) device_getAutoPollTransactionResults: (IDTEMVData **)  result

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

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

Get BLE Friendly Name

Returns
NSString Returns the default friendly name to be used when discovering any BLE devices
- (RETURN_CODE) device_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_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_VP3600_IOS = 8
IDT_DEVICE_VP3600_OSX_USB = 9
}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:()
- (void) device_setBLEFriendlyName: (NSString *)  friendlyName

Set BLE Friendly Name

Parameters
friendlyNameSets the default friendly name to be used when discovering any BLE devices
- (RETURN_CODE) device_setBurstMode: (int)  mode

Send Burst Mode

Sets the burst mode forthe device.

Parameters
mode0 = OFF, 1 = Always On, 2 = Auto Exit
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
- (RETURN_CODE) device_setPassThrough: (BOOL)  enablePassThrough

Set Pass Through

Sets Pass-Through mode on VP3600

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_setPollMode: (int)  mode

Send Poll Mode

Sets the poll mode forthe device. Auto Poll keeps reader active, Poll On Demand only polls when requested by terminal

Parameters
mode0 = Auto Poll, 1 = Poll On Demand
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
- (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:

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

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

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

Authenticate Transaction

Authenticates a transaction after startTransaction successfully executes.

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

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

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

Callback Response PIN Request

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

Parameters
modePIN Mode:
  • EMV_PIN_MODE_CANCEL = 0X00,
  • EMV_PIN_MODE_ONLINE_PIN_DUKPT = 0X01,
  • EMV_PIN_MODE_ONLINE_PIN_MKSK = 0X02,
  • EMV_PIN_MODE_OFFLINE_PIN = 0X03
KSNKey Serial Number. If no pairing and PIN is plaintext, value is nil
PINPIN data, encrypted. If no pairing, PIN will be sent plaintext
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
- (RETURN_CODE) emv_cancelTransaction

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

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

Complete EMV Transaction Online Request

Completes an online EMV transaction request by the card

The tags will be returned in the emvTransactionData delegate protocol.

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

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

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

Disable Auto Authenticate Transaction

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

Parameters
disableFALSE = auto authenticate ENABLED, TRUE = auto authenticate DISABLED
- (RETURN_CODE) emv_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_getTerminalMajorConfiguration: (NSUInteger **)  configuration

Gets the terminal major configuration in ICS .

Parameters
configurationA configuration value, range 1-5
  • 1 = 1C
  • 2 = 2C
  • 3 = 3C
  • 4 = 4C
  • 5 = 5C
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
- (RETURN_CODE) emv_removeApplicationData: (NSString *)  AID

Remove Application Data by AID

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

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

Remove Certificate Authority Public Key

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

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

Remove Certificate Revocation List

Removes all CRLEntry entries

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

Remove Terminal Data

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

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

Retrieve AID list

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

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

Retrieve Application Data by AID

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

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

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

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

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

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

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

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

Retrieve Transaction Results

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

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

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

Set Application Data by AID

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sets the terminal major configuration in ICS .

Parameters
configurationA configuration value, range 1-5
  • 1 = 1C
  • 2 = 2C
  • 3 = 3C
  • 4 = 4C
  • 5 = 5C
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
- (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_VP3600::emv_authenticateTransaction() must be executed. If auto authorize is ENABLED (default), IDT_VP3600::emv_authenticateTransaction() will automatically be executed after receiving the result EMV_RESULT_CODE_START_TRANSACTION_SUCCESS. The auto authorize can be enabled/disabled with emv_disableAutoAuthenticateTransaction:

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

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

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

FeliCa Authentication

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

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

Parameters
key16 byte key used for MAC generation of Read or Write with MAC
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
- (RETURN_CODE) felica_poll: (NSData *)  systemCode
response: (NSData **)  response 

FeliCa Poll for Card

Polls for a Felica Card

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

Parameters
systemCodeSystem Code. Must be 2 bytes
responsePoll response as explained in FeliCA Lite-S User's Manual
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
- (RETURN_CODE) felica_read: (NSData *)  serviceCode
blockList: (NSData *)  blockList
blocks: (NSData **)  blocks 

FeliCa Read

Reads up to 4 blocks.

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

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

FeliCa Read with MAC Generation

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

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

Parameters
blockListBlock to read. Each block in blockList = 2 bytes of data. Maximum 3 block requests (6 bytes of data)
blocksBlocks read. Each block 16 bytes.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
- (RETURN_CODE) felica_requestService: (NSData *)  nodeCode
response: (NSData **)  response 

FeliCa Request Service

Request Service for a Felica Card

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

Parameters
nodeCodeNode Code List. Each node 1 byte
responseResponse as explained in FeliCA Lite-S User's Manual
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
- (RETURN_CODE) felica_write: (NSData *)  serviceCode
blockList: (NSData *)  blockList
data: (NSData *)  data
statusFlag: (NSData **)  statusFlag 

FeliCa Write

Writes a block

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

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

FeliCa Write with MAC Generation

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

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

Parameters
blockNumberNumber of block
dataBlock to write. Must be 16 bytes.
Returns
RETURN_CODE: Values can be parsed with 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 Swipe.

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

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

Enable MSR Swipe

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

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

Cancel PIN Command

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

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

Capture Amount Input

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

Results returned to pinpadData delegate

Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
- (RETURN_CODE) pin_captureFunctionKey

Capture Function Key

Captures a function key entry on the pinpad

Results returned to pinpadData delegate

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

Capture Numeric Input

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

Results returned to pinpadData delegate

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

Capture PIN

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

Results returned to pinpadData delegate

Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
+ (NSString*) SDK_version

SDK Version

Returns the current version of IDTech.framework

Returns
Framework version
+ (IDT_VP3600*) sharedController

Singleton Instance

Establishes an singleton instance of IDT_VP3600 class.

Returns
Instance of IDT_VP3600

Property Documentation

- (id< IDT_VP3600_Delegate >) delegate
readwriteatomicstrong

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