![]() |
IDTech iOS/OSX SDK Guide
1.1.084
API reference for UniPay 1.5
|
#import <IDT_UniPayI_V.h>
Class Methods | |
(NSString *) | + SDK_version |
(IDT_UniPayI_V *) | + sharedController |
Properties | |
id< IDT_UniPayI_V_Delegate > | delegate |
Class to drive the IDT_UniPayI_V device
- (void) close |
Close Device
- (RETURN_CODE) config_getSerialNumber: | (NSString **) | response |
Polls device for Serial Number
response | Returns Serial Number |
- (RETURN_CODE) device_cancelConnectToAudioReader |
Cancel Connect To Audio Reader
Cancels a connection attempt to an IDTech MSR device connected via the audio port.
- (RETURN_CODE) device_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 USB port (OSX only).
- (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 UniPayI_V
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
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:()
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
Removes the Application Data as specified by the AID name passed as a parameter
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
Removes the Terminal Data
- (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
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 Application Data as specified by the AID name passed as a parameter. The AID will be in the response parameter responseAID
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: |
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
- (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 Terminal Data . The Terminal Data will be in the response parameter responseData
responseData | The 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
- (RETURN_CODE) emv_retrieveTransactionResult: | (NSData *) | tags | |
retrievedTags: | (NSDictionary **) | retrievedTags | |
Retrieve Transaction Results
Retrieves specified EMV tags from the currently executing transaction.
tags | Tags to be retrieved. Example 0x9F028A will retrieve tags 9F02 and 8A |
tlv | All 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 |
- (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
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 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
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_UniPayII::emv_authenticateTransaction() must be executed. If auto authorize is ENABLED (default), IDT_UniPayII::emv_authenticateTransaction() will automatically be executed after receiving the result EMV_RESULT_CODE_START_TRANSACTION_SUCCESS. The auto authorize can be enabled/disabled with emv_disableAutoAuthenticateTransaction:
amount | Transaction amount value (tag value 9F02) |
amtOther | Other amount value, if any (tag value 9F03) |
type | Transaction type (tag value 9C). |
timeout | Timeout value in seconds. |
tags | Any other tags to be included in the request. Passed as 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 |
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_UniPayI_V*) sharedController |
Singleton Instance
Establishes an singleton instance of IDT_UniPayI_V class.
|
readwriteatomicstrong |