![]() |
IDTech iOS/OSX SDK Guide
1.1.090
API reference for UniPay III
|
#import <IDT_UniPayIII.h>
Class Methods | |
(NSString *) | + SDK_version |
(IDT_UniPayIII *) | + sharedController |
Properties | |
id< IDT_UniPayIII_Delegate > | delegate |
Class to drive the IDT_UniPayIII device
- (void) close |
Close Device
- (RETURN_CODE) config_getSerialNumber: | (NSString **) | response |
Polls device for Serial Number
response | Returns Serial Number |
- (RETURN_CODE) ctls_cancelTransaction |
Cancels Transaction request (swipe or CTLS).
- (RETURN_CODE) ctls_startTransaction |
Enable Transaction Request
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:()
- (RETURN_CODE) device_cancelConnectToAudioReader |
Cancel Connect To Audio Reader
Cancels a connection attempt to an IDTech MSR device connected via the audio port.
- (NSUUID*) device_connectedBLEDevice |
Returns the UUID of the connected BLE device
UniPayIII
- (RETURN_CODE) device_connectToAudioReader |
Connect To Audio Reader
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 audio port.
- (bool) device_disableBLEDeviceSearch |
Stops searching for Bluetooth Low Energy devices in range
UniPayIII
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: | (IDT_DEVICE_Types) | type | |
identifier: | (NSUUID *) | identifier | |
Begins searching for Bluetooth Low Energy devices in range
UniPayIII
type | When a NSUUID identifer is not provided, this will attempt to connect to the first device of this type it finds. If a NSUUID identifer is provided, this filter will be ignored. |
identifier | This will only connect to a device with this calculated UUID identifier |
Any of the following BLE status messages may be returned to the deviceMessage delegate:
The state of the BLE Manager is unknown.
Note: a Devices UUID is calculated by the iOS device using a combiniation of the iOS device UUID and the BLE device MAC address. This value is not known until after it connects for the first time, and then every time after that, it will be the same value. This value can be retrieved by IDT_Device::connectedBLEDevice() after the device connects.
- (RETURN_CODE) device_getFirmwareVersion: | (NSString **) | response |
Polls device for Firmware Version
response | Response returned of Firmware Version |
- (NSString *) device_getResponseCodeString: | (int) | errorCode |
Get Response Code String
Interpret a response code and return string description.
errorCode | Error code, range 0x0000 - 0xFFFF, example 0x0300 |
- (BOOL) device_isAudioReaderConnected |
Is Audio Reader Connected
Returns value on device connection status when device is an audio-type connected to headphone plug.
- (bool) device_isConnected: | (IDT_DEVICE_Types) | device |
Is Device Connected
Returns the connection status of the requested device
device | Check connectivity of device type |
- (RETURN_CODE) device_sendIDGCommand: | (unsigned char) | command | |
subCommand: | (unsigned char) | subCommand | |
data: | (NSData *) | data | |
response: | (NSData **) | response | |
Send NEO IDG Command Send a NEO IDG ViVOtech 2.0 command
command | One byte command as per NEO IDG Reference Guide |
subCommand | One byte sub-command as per NEO IDG Reference Guide |
data | Command data (if applicable) |
response | Returns next Command response |
- (RETURN_CODE) device_setAudioVolume: | (float) | val |
Set Volume To Audio Reader
Set the iPhone’s volume for command communication with audio-based readers. The the range of iPhone’s volume is from 0.1 to 1.0.
val | Volume level from 0.1 to 1.0 |
- (RETURN_CODE) device_setPassThrough: | (BOOL) | enablePassThrough |
Set Pass Through
Sets Pass-Through mode on UniPayIII
enablePassThrough | TRUE = Pass through enabled |
- (RETURN_CODE) device_startRKI |
Start Remote Key Injection
Attempts to perform a Remote Key Injection with IDTech's RKI servers.
- (RETURN_CODE) emv_authenticateTransaction: | (NSData *) | tags |
Authenticate Transaction
Authenticates a transaction after startTransaction successfully executes.
By default, auto authorize is ENABLED. If auto authorize is DISABLED, this function must be called after a result EMV_RESULT_CODE_START_TRANSACTION_SUCCESS returned to emvTransactionData delegate protocol is received after a startTransaction call. If auto authorize is ENABLED (default), this method will automatically be executed after receiving the result EMV_RESULT_CODE_START_TRANSACTION_SUCCESS after startTransaction. The auto authorize can be enabled/disabled with IDT_DEVICE::disableAutoAuthenticateTransaction:()
The purpose of this step is to allow the merchant the chance to evaluate the data captured from the matching Application (if found) before the kernel authenticates the transaction data. This would allow, for instance, the merchant to be told what card is being used, and if it is a specific type (like a store card), perform an action like reducing the amount before proceeding (as a promotion in using that card).
tags | Any tags to modify original tags submitted with startTransaction. Passed as NSData. Example, tag 9F0C with amount 0x000000000100 would be 0x9F0C06000000000100 Tag DFEE1A can be used to specify tags to be returned in response, in addition to the default tags. Example DFEE1A049F029F03 will return tags 9F02 and 9F03 with the response |
- (RETURN_CODE) emv_callbackResponseLCD: | (int) | mode | |
selection: | (unsigned char) | selection | |
Callback Response LCD Display
Provides menu selection responses to the kernel after a callback was received lcdDisplay delegate.
mode | The choices are as follows
|
selection | Line number in hex (0x01, 0x02), or 'C'/'E' of function key |
- (RETURN_CODE) emv_completeOnlineEMVTransaction: | (BOOL) | isSuccess | |
hostResponseTags: | (NSData *) | tags | |
Complete EMV Transaction Online Request
Completes an online EMV transaction request by the card
The tags will be returned in the emvTransactionData delegate protocol.
isSuccess | Determines if connection to host was successful:
|
tags | Host response tag (see below) |
Tag | Length | Description |
---|---|---|
8A | 2 | Data element Authorization Response Code. Mandatory |
91 | 8-16 | Issuer Authentication Data. Optional |
71 | 0-256 | Issuer Scripts. Optional |
72 | 0-256 | Issuer Scripts. Optional |
DFEE1A | 0-256 | Tag list of additional tags to return |
Tag DFEE1A will force additional tags to be returned. Example DFEE1A049F029F03 will return tags 9F02 and 9F03 with the response
- (void) emv_disableAutoAuthenticateTransaction: | (BOOL) | disable |
Disable Auto Authenticate Transaction
If auto authenticate is DISABLED, authenticateTransaction must be called after a successful startEMV execution.
disable | FALSE = auto authenticate ENABLED, TRUE = auto authenticate DISABLED |
- (RETURN_CODE) emv_getEMVL2Version: | (NSString **) | response |
Polls device for EMV L2 Version
response | Response returned of Level 2 Version |
- (RETURN_CODE) emv_removeApplicationData: | (NSString *) | AID |
Remove Application Data by AID
This will REMOVE the an AID configuration file and all the tlv data associated with that AID.
AID | Name of ApplicationID in ASCII, example "A0000000031020". Must be between 5 and 16 characters |
- (RETURN_CODE) emv_removeCAPK: | (NSString *) | rid | |
index: | (NSString *) | index | |
Remove Certificate Authority Public Key
Removes the CAPK as specified by the RID/Index passed as a parameter in the CAKey structure
rid | RID of the key to remove |
index | Index of the key to remove |
- (RETURN_CODE) emv_removeCRLList |
Remove Certificate Revocation List
Removes all CRLEntry entries
- (RETURN_CODE) emv_removeTerminalData |
Remove Terminal Data
This will remove ALL configurable TLV data associated with the terminals Kernel configuration.
- (RETURN_CODE) emv_retrieveAIDList: | (NSArray **) | response |
Retrieve AID list
Returns all the AID names on the terminal. Populates response parameter with an Array of NSString* with AID names. Each AID name represent a unique configuration file to be loaded/used when a matching application is found on a card during a transaction.
response | Returns a NSArray of NSString of AID Names |
- (RETURN_CODE) emv_retrieveApplicationData: | (NSString *) | AID | |
response: | (NSDictionary **) | responseAID | |
Retrieve Application Data by AID
Retrieves the configuration information for a provided AID name, if that AID file exists on the terminal.
The TLV data in that AID is returned as a NSDictionary, with the Key being the tag name as a NSString representation of the tag hex value (example "9F06"), and the Object being the Value as NSData (example 0xa0000000031010).
The data returned will be from the range of allowable kernel EMV tags. Please see "EMV Tag Reference" at the end of this document for the listing.
AID | Name of ApplicationID in ASCII, example "A0000000031020". Must be between 5 and 16 characters |
responseAID | The response returned from the method as a dictionary with Key/Object to match TagValues as follows: |
- (RETURN_CODE) emv_retrieveCAPK: | (NSString *) | rid | |
index: | (NSString *) | index | |
response: | (CAKey **) | response | |
Retrieve Certificate Authority Public Key
Retrieves the CAPK as specified by the RID/Index passed as a parameter in the CAKey structure. The CAPK will be in the response parameter
rid | The RID of the key to retrieve |
index | The Index of the key to retrieve |
response | Response returned as a CAKey |
- (RETURN_CODE) emv_retrieveCAPKFile: | (NSString *) | rid | |
index: | (NSString *) | index | |
response: | (NSData **) | response | |
Retrieve Certificate Authority Public Key
Retrieves the CAPK as specified by the RID/Index passed as a parameter in the CAKey structure. The CAPK will be in the response parameter
rid | The RID of the key to retrieve |
index | The Index of the key to retrieve |
response | Response returned as a NSData object with the following data:
|
- (RETURN_CODE) emv_retrieveCAPKList: | (NSArray **) | response |
Retrieve the Certificate Authority Public Key list
Returns all the CAPK RID and Index. Populates response parameter with an array of NSString items, 12 characters each, characters 1-10 RID, characters 11-12 index.
response | Response returned contains an NSArray of NSString items, 12 characters each, characters 1-10 RID, characters 11-12 index. Example "a00000000357" = RID a00000003, Index 57 |
- (RETURN_CODE) emv_retrieveCRLList: | (NSMutableArray **) | response |
Retrieve the Certificate Revocation List
Returns all the RID in the CRL.
response | Response returned as an NSArray of NSData objects 9-bytes each:
|
- (RETURN_CODE) emv_retrieveTerminalData: | (NSDictionary **) | responseData |
Retrieve Terminal Data
Retrieves the tag values associated with the terminal configuration file. This will be a combination of uneditable major configuration tags for the kernel configuration (example 9F33, Terminal Capabilities), and editable tags set with IDT_Device::emv_setTerminalData:() (example DF13, Terminal Action Code - Default)
The TLV data returned as a NSDictionary, with the Key being the tag name as a NSString representation of the tag hex value (example "DF13"), and the Object being the Value as NSData (example 0x00058003FF).
The data returned will be from the range of allowable kernel EMV tags. Please see "EMV Tag Reference" at the end of this document for the listing.
- (RETURN_CODE) emv_retrieveTransactionResult: | (NSData *) | tags | |
retrievedTags: | (NSDictionary **) | retrievedTags | |
Retrieve Transaction Results
Retrieves the requested tag values (if they exist) from the last transaction.
The TLV data returned as a NSDictionary, with the Key being the tag name as a NSString representation of the tag hex value (example "5A"), and the Object being the Value as NSData (example 0x41359276429372938).
- (RETURN_CODE) emv_setApplicationData: | (NSString *) | aidName | |
configData: | (NSDictionary *) | data | |
Set Application Data by AID
Sets the configuration information for a provided AID name, with TLV data that populates a NSDictionary.
The TLV data for the AID is sent as a NSDictionary, with the Key being the tag name as a NSString representation of the tag hex value (example "9F06"), and the Object being the Value as NSData (example 0xa0000000031010).
The data for the AID configuration will will be from the range of allowable kernel EMV tags. Please see "EMV Tag Reference" at the end of this document for the listing.
NOTES: There is no minimum defined set of AID TLV data that must be provided, other than 9F06 for the AID name.
If this AID is selected and matched during an EMV transaction, any data in this AID will either OVERRIDE the same data in the terminal configuration file, or PROVIDE the data if it is non-existant in the terminal configuration file.
AID configuration information is provided during L3 certification. Dummy/stub AID data can be used pre-certification to test EMV transaction as long as at least tag 9F06 is defined that makes up the AID configuration locator.
There are convenience utilities to turn a TLV NSData object into a NSDictionary, and a NSDictionary into a NSData object in IDTUtility:
Also utilities to turn a HEX/ASCII string to NSDATA and back again
aidName | aidName AID name. Example "a0000000031010" |
data | NSDictionary with Tags/Values for the AID configuration file |
- (RETURN_CODE) emv_setCAPK: | (CAKey) | key |
Set Certificate Authority Public Key
Sets the CAPK as specified by the CAKey structure
key | CAKey containing the RID, Index, and key data to set |
- (RETURN_CODE) emv_setCAPKFile: | (NSData *) | file |
Set Certificate Authority Public Key
Sets the CAPK as specified by the CAKey raw format
key | CAKey format: [5 bytes RID][1 byte Index][1 byte Hash Algorithm][1 byte Encryption Algorithm][20 bytes HashValue][4 bytes Public Key Exponent][2 bytes Modulus Length][Variable bytes Modulus] Where:
|
- (RETURN_CODE) emv_setCRLEntries: | (NSData *) | data |
Set Certificate Revocation List
Sets the CRL list
data | CRLEntries as a repeating occurance of CRL: CRL1 CRL2 … CRLn. CRL format is
|
- (RETURN_CODE) emv_setTerminalData: | (NSDictionary *) | data |
Set Terminal Data
Sets the terminal configuration information, with TLV data that populates a NSDictionary.
The TLV data for the terminal configuration is sent as a NSDictionary, with the Key being the tag name as a NSString representation of the tag hex value (example "DF13"), and the Object being the Value as NSData (example 0x00080039FF).
The data for the terminal configuration will will be from the range of allowable kernel EMV tags. Please see "EMV Tag Reference" at the end of this document for the listing.
NOTES: There is an uneditable set of tags that make up the current kernel configuration major parameters. Any attempt to set those will return an error.
If an AID is selected and matched during an EMV transaction, any data in that AID will either OVERRIDE the same data in the terminal configuration file, or PROVIDE the data if it is non-existant in the terminal configuration file.
There are convenience utilities to turn a TLV NSData object into a NSDictionary, and a NSDictionary into a NSData object in IDTUtility:
Also utilities to turn a HEX/ASCII string to NSDATA and back again
data | NSDictionary with Tags/Values for the Terminal configuration file |
- (RETURN_CODE) emv_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_UniPayIII::emv_authenticateTransaction() must be executed. If auto authorize is ENABLED (default), IDT_UniPayIII::emv_authenticateTransaction() will automatically be executed after receiving the result EMV_RESULT_CODE_START_TRANSACTION_SUCCESS. The auto authorize can be enabled/disabled with emv_disableAutoAuthenticateTransaction:
amount | Transaction amount value (tag value 9F02) |
amtOther | Other amount value, if any (tag value 9F03) |
type | Transaction type (tag value 9C). |
timeout | Timeout value in seconds. |
tags | Any other tags to be included in the request. Passed as NSData. Example, tag 9F0C with amount 0x000000000100 would be 0x9F0C06000000000100 If tags 9F02 (amount),9F03 (other amount), or 9C (transaction type) are included, they will take priority over these values supplied as individual parameters to this method. Tag DFEE1A can be used to specify tags to be returned in response, in addition to the default tags. Example DFEE1A049F029F03 will return tags 9F02 and 9F03 with the response |
forceOnline | TRUE = do not allow offline approval, FALSE = allow ICC to approve offline if terminal capable |
autoAuthenticate | Will automatically execute Authenticate Transacation after start transaction returns successful |
fallback | Indicate if it supports fallback to MSR |
- (RETURN_CODE) icc_exchangeAPDU: | (NSData *) | dataAPDU | |
response: | (APDUResponse **) | response | |
Exchange APDU (unencrypted)
Sends an APDU packet to the ICC. If successful, response is returned in APDUResult class instance in response parameter.
dataAPDU | APDU data packet |
response | Unencrypted/encrypted parsed APDU response |
- (RETURN_CODE) icc_getICCReaderStatus: | (ICCReaderStatus **) | readerStatus |
Get Reader Status
Returns the reader status
readerStatus | Pointer that will return with the ICCReaderStatus results. |
- (RETURN_CODE) icc_powerOffICC: | (NSString **) | error |
Power Off ICC
Powers down the ICC
error | Returns the error, if any |
If Success, empty If Failure, ASCII encoded data of error string
- (RETURN_CODE) icc_powerOnICC: | (NSData **) | response |
Power On ICC
Power up the currently selected microprocessor card in the ICC reader
response | Response returned. If Success, ATR String. If Failure, ASCII encoded data of error string |
- (bool) isConnected |
Check if device is connected
- (RETURN_CODE) msr_cancelMSRSwipe |
Disable MSR Swipe
Cancels MSR swipe request.
- (RETURN_CODE) msr_startMSRSwipe |
Enable MSR Swipe
Enables CLTS and MSR, waiting for swipe or tap to occur. If swipe captured, returns IDTMSRData instance to deviceDelegate::swipeMSRData:(). If CTLS captured, returns IDTEMVData to deviceDelegate::emvTransactionData:()
+ (NSString*) SDK_version |
SDK Version
Returns the current version of IDTech.framework
+ (IDT_UniPayIII*) sharedController |
Singleton Instance
Establishes an singleton instance of IDT_UniPayIII class.
|
readwriteatomicstrong |