To develop an iOS app using the MTSCRA SDK, follow the setup steps in section 2 How to Set Up the MTSCRA SDK, then create an instance of the MTSCRA object in your software project, then call the functions described in this chapter to communicate with the device. For sample code that demonstrates how to use these functions, see the contents of the MTSCRA Demo folder included with the SDK.
Generally, these functions will run in one of two modes:
Asynchronous functions will return data using the event handlers (callback functions) defined in section 5 MTSCRA Delegate Methods.
Synchronous functions will return requested data immediately in the function’s return value. If the requested data is not available immediately, synchronous calls will generally block until a specified wait time has elapsed.
Most calls that wait for input from the user will run in the asynchronous mode.
MTSCRA Function - 4.1 - 4.10
This function retrieves the SDK revision number.
Parameters: None
Return Value: String containing the SDK revision number.
This function retrieves a list of available Bluetooth LE devices. After calling this function to locate the device you wish to connect to, use setAddress to tell the library which device you want to connect to. Use stopScanningForPeripherals to stop the scan.
Parameters: None
Return Value: An array of peripherals
This function stops the scanning of available Bluetooth LE devices.
Parameters: None Return Value: None
This function sets device’s address for Bluetooth LE devices.
Parameters:
Parameter
Description
address
Address of the Bluetooth LE device to communicate with
Return Value: None
This function opens a connection to the device.
To use this function to connect to a Bluetooth LE device, the app should follow these steps:
Call startScanningForPeripherals to find the device you want to connect to.
Call setAddress to tell the library which device you want to connect to.
Make sure your app’s bleReaderStateUpdated function most recent status is was OK .
Call openDevice.
After calling this function, call isDeviceOpened to make sure the device was successfully opened.
Parameters: None
Return Value:
YES = Success
NO = Error
This function closes the connection to the currently opened device. After calling this function, call isDeviceOpened to make sure the device was successfully closed.
Parameters: None
Return Value:
YES = Success
NO = Error
This function reports whether any compatible devices are connected to the host.
Parameters: None
Return Value:
YES = host is connected to a device
NO = host is not connected to a device
This function retrieves device opened status, which changes on successful completion of a call to startScanningForPeripherals or closeDevice.
Parameters: None
Return Value:
YES = Device is opened
NO = Device is not opened
This function sends a direct command to device. See MagneSafe V5 Programmer’s Reference (Commands) for details about available commands and syntax.
Parameter
Description
pData
Command to send to the device. For example, pass command string
“C10206C20503C30100” to call the Discovery command.
Return Value:
0 = Success
9 = Error
15 = Busy
This function retrieves card data from a string separated by ‘|’ after a cardholder swipes a card. The host software should call it in response to the trackDataReadyNotification callback.
Parameters: None
Return Value:
A null terminated hex string for Card Data, Field separated by ‘|’.NULL value for failed.
This function clears the SDK library’s local cache of card swipe data.
Parameters: None
Return Value: None
This function sets a callback function to notify when the device has card data to send to the host or when the device state changes. See example in Open Device code example.
Parameters: Event
MTSCRA Function - 4.41 - 4.50
This function retrieves the track decode status after a cardholder swipes a card.
Parameters: None
Return Value:
Hex string, each 2 digits represent one track’s decode status, where the left most 2 digits are for Track 1.
“00” = Success
MTSCRA Function - 4.21 - 4.30
This function retrieves the card’s encrypted MagnePrint, for readers that support MagnePrint.
Parameters: None
Return Value: String containing the card’s encrypted MagnePrint.
This function retrieves the card MagnePrint status. For more information, see D99875475. Only available on iDynamo; it will return an empty string in audio reader.
Parameters: None Return Value:
Return stored MagnePrintStatus string.
This function retrieves the device serial number.
event
Event type.
· TRANS_EVENT_OK = Transaction succeeded.
· TRANS_EVENT_START = Reader started sending data.
· TRANS_EVENT_ERROR = Reader failed sending data.
Return Value: None
This function retrieves masked card track data after a cardholder swipes a card. Only available on iDynamo/uDynamo; other devices will return an empty string.
Parameters: None
Return Value:
Return stored masked track data string. Tracks are delimited with start and end sentinels.
This function retrieves masked track 1 data after a cardholder swipes a card.
Parameters: None
Return Value: Return stored masked track1 data string.
This function retrieves masked track 2 data, if any, after a cardholder swipes a card.
Parameters: None
Return Value: Return stored masked track2 data string.
This function retrieves masked track 3 data, if any, after a cardholder swipes a card.
Parameters: None
Return Value: Return stored masked track3 data string.
This function retrieves masked PAN data, if any, after a cardholder swipes a card.
Parameters: None
Return Value: Return stored masked PAN data string.
This function retrieves the card’s track 1 data in encrypted format after a cardholder swipes a card.
This function retrieves the card’s track 3 data in encrypted format, if any, after a cardholder swipes a card.
Parameters: None
Return Value: String containing encrypted track 3 data
Parameter
4.11 clearBuffers
4.12 listenForEvents
Description
4.13 getMaskedTracks [iDynamo/uDynamo Only]
4.14 getTrack1Masked
4.15 getTrack2Masked
4.16 getTrack3Masked
4.17 getCardPAN
4.18 getTrack1
4.19 getTrack2
4.20 getTrack3
"01” = Error or not decodable
“02” = No track present
Examples:
“000000” = Track 1, 2, and 3 success.
“000100” = Track 1 and 3 success. Track 2 had error.
“000002” = Track 1 and 2 success. Track 3 not present.
This function retrieves device’s battery level percentage between 0% and 100%, if the device has a battery and supports battery level monitoring. To retrieve the most up to date percentage, call this function after a transaction.
Parameters: None
Return Value: Long value between 0 and 100
This function returns the currently opened device’s part number.
Parameters: None
Return Value: String containing the device part number.
Retrieves the Card Status
Parameters: None
Return Value: Card Status, which depends on the device.
This function retrieves individual TLV tag values. Only supported on aDynamo/UDynamo.
Parameters:
Tag = An MTSCRATransactionData type (see section D.5 MTSCRATransactionData).
Return Value: String containing the value of the specified tag.
This function gets the status of the currently connected device.
Parameters: None
Return Value: Return device status of swipe count and battery level.
This function gets the status of the current operation.
Parameters: None
Return Value: Operation Status
This function returns the version of the tag-length-value (TLV) format supported by the device.
Parameters: None
Return Value: String containing the firmware TLV version.
This function sets the protocol string the SDK will use to communicate with the device. See example in Open Device code example.
Parameters: Protocol String
Return Value: None
This function gets the response type.
Parameters: None
Return Value: Response Type
4.41 getTrackDecodeStatus
4.42 getBatteryLevel
4.43 getDevicePartNumber
4.44 getCardStatus
4.45 getTagValue [aDynamo/uDynamo Only]
4.46 getDeviceStatus
4.47 getOperationStatus
4.48 getTLVVersion
4.49 setDeviceProtocolString [iDynamo Only]
4.50 getResponseType
Parameters: None
Return Value: String containing the device serial number.
This function returns the MagTek serial number of the currently opened device.
Parameters: None
Return Value: Return stored serial number created by MagTek.
This function retrieves the Session ID from the currently opened device, which the host can use to uniquely identify a transaction to prevent replay. Only supported by iDynamo/uDynamo; on other devices this function will return an empty string. For more information, see D99875475
Parameters: None
Return Value: Stored session ID.
This function retrieves the Key Serial Number (KSN) from the device.
Parameters: None
Return Value: String containing the stored key serial number.
This function gets the device’s product name.
Parameters: None
Return Value: String containing the device product name.
This function gets the device type.
Parameters: None
Return Value: Device Type
This function sets the type of device to open. Call this function before calling openDevice.
MAGTEKIDYNAMO = iOS 30-pin and Lightning readers iDynamo.
MAGTEKDYNAMAX = Bluetooth LE reader DynaMAX.
MAGTEKEDYNAMO = Bluetooth LE reader eDynamo.
MAGTEKKDYNAMO = Lightning reader kDynamo.
MAGTEKTDYNAMO = Bluetooth LE reader tDynamo.
Return Value: None
This function gets the capabilities of the currently opened device.
Parameters: None
Return Value: Return device capabilities.
CAP_MASKING = 1,
CAP_ENCRYPTION=2,
CAP_CARD_AUTH = 4,
CAP_DEVICE_AUTH = 8,
CAP_SESSION_ID = 16,
CAP_DISCOVERY= 32,
4.21 getMagnePrint
4.22 getMagnePrintStatus [iDynamo Only]
4.23 getDeviceSerial
4.24 getMagTekDeviceSerial
4.25 getSessionID [iDynamo/uDynamo Only]
4.26 getKSN
4.27 getDeviceName
4.28 getDeviceType
4.29 setDeviceType
4.30 getDeviceCaps
(void) clearBuffers
(void) listenForEvents:(UInt32)event
(NSString *) getMaskedTracks
(NSString *) getTrack1Masked
(NSString *) getTrack2Masked
(NSString *) getTrack3Masked
(NSString *) getCardPAN
(NSString *) getTrack1
(NSString *) getTrack2
(NSString *) getTrack3
(NSString *) getTrackDecodeStatus
(long) getBatteryLevel
(NSString *) getDevicePartNumber
(NSString *) getCardStatus
(NSString *) getTagValue:(UInt32)tag
(NSString *) getDeviceStatus
(NSString *) getOperationStatus
(NSString *) getTLVVersion
(void) setDeviceProtocolString:(NSString *)pData
(NSString *) getResponseType
(NSString *) getMagnePrint
(NSString *) getMagnePrintStatus
(NSString *) getDeviceSerial
(NSString *) getMagTekDeviceSerial
(NSString *) getSessionID
(NSString *) getKSN
(NSString *) getDeviceName
(int) getDeviceType
(void) setDeviceType:(UInt32 *)deviceType
(NSString *) getDeviceCaps
MTSCRA Function - 4.31 - 4.40
4.31 getCapMSR
This function gets the MSR capability of the device. For more information, see D99875483 – Track ID Enable Property.
(NSString *) getCapMSR
Parameters: None Return Value:
Return MSR Capability bit masking.
Bit 7
Bit 6
Bit 5
0 – Decodes standard ISO/ABA cards only
1 – Decodes AAMV and 7-bit cards also
If this flag is set to 0, only tracks that conform to the ISO format allowed for that track will be decoded. If the track cannot be decoded by the ISO method it will be considered to be in error.
00 – Track Disabled
01 – Track Enabled
10 – Track Enabled/Required (Error if blank)
This function gets the device’s capability for encrypting track data.
Return Value:
“1” = Available
“0” = Unavailable.
This function gets information about the device’s tracks capability.
Parameters: None
Return Value: A hex string for the track capability. See Track ID Enable Property in D99875475.
This function retrieves the card expiration date after a cardholder swipes a card.
Parameters: None
Return Value: String containing the card expiration date
This function gets the last 4 digits of the card account number (PAN) after a cardholder swipes a card.
Parameters: None
Return Value: String containing the last 4 digits of the PAN
This function gets the issuer identification number (IIN) of the card number after a cardholder swipes a card.
Parameters: None
Return Value: String containing the IIN
This function gets the cardholder name after a cardholder swipes a card.
Parameters: None
Return Value: String containing the cardholder name, for example, “John Wayne”.
This function gets the length of the PAN after a cardholder swipes a card.
Parameters: None
Return Value: Length of card number or PAN
This function retrieves the card’s service code after a cardholder swipes a card.
Parameters: None
Return Value: String containing the card’s service code
This function retrieves the part number and revision of the device’s firmware.
Parameters: None
Return Value: String containing firmware part number and revision.
Hexadecimal string of the byte array for the extended command. The first two bytes represent the value of the extended command. The next two bytes (most significant byte first) indicate the total length of the following data in bytes.
Return Value: String containing the response data of the command.
Set the timeout in milliseconds for a sync command or sync extended command. Default value is 5000 milleseconds.
Parameters:
Return Value: None.
Set the time frame (delay) for run loop or background thread. Default value is 10 milliseconds.
Parameters:
Return Value: None.
Enable the debug print from SDK. Default value is NO.
Parameters:
Return Value: None.
Updates the device firmware
Parameters:
Return Value:
0 = UPDATE_FIRMWARE_STARTED
1 = UPDATE_FIRMWARE_SUCCESS
9 = UPDATE_FIRMWARE_ERROR
15 = UPDATE_FIRMWARE_NA
This function sends a command to an NFC tag type 2. The NFC tag must first be activated by calling startTransaction() with NFC enabled.
This function sends a command to a NFC Mifare Classic Tag type 2. The NFC tag must first be activated by calling startTransaction() with NFC enabled.
Parameters:
Return Value:
0 = Success
9 = Error
15 = Busy
This function sends a command to an NFC Mifare DESFire Light Tag Type 4. The NFC tag must first be activated by calling startTransaction() with NFC enabled.
Parameters:
Return Value:
0 = Success
9 = Error
15 = Busy
This function sends a command to an NFC tag type 2. The NFC tag must first be activated by calling startTransaction() with NFC enabled.
Parameters:
Return Value:
· Extended response of the NFC command.
This function sends a command to an NFC tag type 2. The NFC tag must first be activated by calling startTransaction() with NFC enabled.
Parameters:
Return Value:
0 = Success
9 = Error
15 = Busy
MTSCRA Function - 4.51 - 4.60
4.51 getBluetoothRSSI
This function will return the signal strength of Bluetooth LE devices.
(int)getBluetoothRSSI;
4.52 setUUIDString [DynaMAX/eDynamo Only]
This function sets the UUIDString for the Bluetooth LE connection.
This function gets an array of DynaMAX/eDynamo devices connected to the host.
Parameters: None
Return Value: Array of DynaMAX/eDynamo devices.
Start EMV Transaction.
The device’s system date and time must be set prior to sending this command. Use sendExentedCommandSync() to set the date and time.
Devices without a battery-backed real time clock require the host to set the date and time using Extended Command 0x030C - Set Date and Time every time the device is power cycled or reset.
Devices that have a battery-backed real time clock (See Supported Devices) would typically have the date and time set at the factory.
(int) startTransaction:
(Byte)timeLimit cardType:
(Byte)cardType option:
(Byte)option amount:
(Byte*)amount transactionType:
(Byte)transactionType cashBack:
(Byte*)cashBack currencyCode:
(Byte*)currencyCode reportingOption:
(Byte)reportingOption
Parameters:
Return Value:
0 = Success
9 = Error
15 = Busy
This function sets the user selection result. It should be called after receiving the onUserSelectRequest event which is triggered after the user makes a selection.
Parameters:
Return Value:
0 = Success
9 = Error
15 = Busy
This function cancels a transaction while waiting for the user to insert a card.
Return Value:
0 = Success
9 = Error
15 = Busy
The library returns the status of this function in the delegate method onEMVCommandResult (EMV Device Only).
Parameters:
This function informs EMV device to process transaction decision from acquirer.
Parameters:
Return Value:
0 = Success
9 = Error
15 = Busy
Send extended command to device. Command response is returned in the event message onDeviceExtendedResponseReceived.
Parameters:
Return Value:
0 = Success
9 = Error
15 = Busy
Send a synchronous command to device. Operation waits for the command to return.
Parameters:
Return Value: String containing the response data of the command.
response
Callback to receive the response.
Parameter
Description
timeoutMS
Timeout in milliseconds.
Parameter
Description
ms
Time frame delay in milliseconds.
Parameter
Description
enabled
When set to true, the SDK prints debugging messages in the XCode debug console. Debug messages consist of data sent to and received from the device. This may include iAP2.
Parameter
Description
firmwareType
Type of firmware to update.
· 1 - Main Firmware
firmwareData
Firmware data.
Parameter
Description
command
Command to send to the NFC tag.
· Get Version
· Read
· Fast Read
· Write
· Compatibility Write
· Read_Cnt
· PWD_Auth
· Read_Sig
lastCommand
Determines if this is the last NFC command to complete the operation.
true = This is the last command. Device will provide a single beep after receiving a successful response from the NFC tag. To send subsequent commands, the NFC tag must be activated by calling startTransaction() with NFC enabled.
false = Expect more commands (Default).
Either set to true or false, if the NFC tag command fails, device will provide a double beep.
encrypt
Determines if data returned is to be encrypted.
true = Encrypt data
false = Do not encrypt data (Default)
Parameter
Description
lastCommand
Determines if this is the last NFC command to complete the operation.
true = This is the last command. Device will provide a single beep after receiving a successful response from the NFC tag. To send subsequent commands, the NFC tag must be activated by calling startTransaction() with NFC enabled.
false = Expect more commands (Default).
Either set to true or false, if the NFC tag command fails, device will provide a double beep.
encrypt
Determines if data returned is to be encrypted.
true = Encrypt data
false = Do not encrypt data (Default)
Parameter
Description
command
Command to send to the NFC tag. See DESFire Data Sheet (MF2DLHX0). Should follow ISO 7816-4 APDU format.
lastCommand
Determines if this is the last NFC command to complete the operation.
true = This is the last command. Device will provide a single beep after receiving a successful response from the NFC tag. To send subsequent commands, the NFC tag must be activated by calling startTransaction() with NFC enabled.
false = Expect more commands (Default).
Either set to true or false, if the NFC tag command fails, device will provide a double beep.
encrypt
Determines if data returned is to be encrypted.
true = Encrypt data
false = Do not encrypt data (Default)
Parameter
Description
command
Command to send to the NFC tag.
· Get Version
· Read
· Fast Read
· Write
· Compatibility Write
· Read_Cnt
· PWD_Auth
· Read_Sig
lastCommand
Determines if this is the last NFC command to complete the operation.
true = This is the last command. Device will provide a single beep after receiving a successful response from the NFC tag. To send subsequent commands, the NFC tag must be activated by calling startTransaction() with NFC enabled.
false = Expect more commands (Default).
Either set to true or false, if the NFC tag command fails, device will provide a double beep.
encrypt
Determines if data returned is to be encrypted.
true = Encrypt data
false = Do not encrypt data (Default)
Parameter
Description
command
Command to send to the NFC tag.
· Get Version
· Read
· Fast Read
· Write
· Compatibility Write
· Read_Cnt
· PWD_Auth
· Read_Sig
lastCommand
Determines if this is the last NFC command to complete the operation.
true = This is the last command. Device will provide a single beep after receiving a successful response from the NFC tag. To send subsequent commands, the NFC tag must be activated by calling startTransaction() with NFC enabled.
false = Expect more commands (Default).
Either set to true or false, if the NFC tag command fails, device will provide a double beep.
encrypt
Determines if data returned is to be encrypted.
true = Encrypt data
false = Do not encrypt data (Default)
4.62 setTimeout
4.63 setTimeFrame
4.64 enableDebugPrint
4.65 updateFirmware
4.66 sendNFCCommand
4.67 sendClassicNFCCommand
4.68 sendDESFireNFCCommand
4.69 sendNFCCommandSync
4.70 sendNFCCommandAsync
cashBack
Cash back Amount (if non-zero, EMV Tag 9F03, format n12, 6 bytes) in hex string.
For example: “000000001000”, means 10.00 dollars.
currencyCode
Transaction Currency Code (EMV Tag 5F2A, format n4, 2 bytes) Sample Valid values:
0x0840 – US Dollar 0x0978 – Euro 0x0826 – UK Pound
reportingOption
This single byte field indicates the level of Transaction Status notifications the host desires to receive during the course of this transaction.
0x00 = Termination Status only (normal termination, card error, timeout, host cancel)
0x01 = Major Status changes (terminations plus card insertions and waiting on user)
0x02 = All Status changes (documents the entire transaction flow)
Parameter
Description
timeLimit
Specifies the maximum time, in seconds, allowed to complete the total transaction. This includes time for the user to insert the card, choose a language, choose an application, and online processing. If this time is exceeded, the transaction will be aborted and an appropriate Transaction Status will be available.
Values:
0 = no timeout, infinite. To cancel before a payment method is presented, use cancelTransaction().
(1 to 255) seconds. Use 255 for the longest time limit for devices that do not support 0.
Device Time Limit
========= =========
DynaMAX n/a
aDynamo n/a
cDynamo n/a
iDynamo 5/(GENII) n/a sDynamo n/a
uDynamo n/a
eDynamo 1 to 255
iDynamo 6 0 to 255
kDynamo 1 to 255
tDynamo 0 to 255
cardType
Card Type to Read:
0x01 = Magnetic Stripe (as alternative to EMV L2, card swipe causes abort of EMV L2)
0x02 = Contact chip card
0x03 = Magnetic Stripe and Contact chip Card. 0x04 = Contactless chip card
0x05 = Magnetic Stripe and Contactless chip card. 0x06 = Contact chip card and Contactless chip card.
0x07 = Magnetic Stripe, Contact chip card, Contactless chip card.
Refer to Appendix C for supported devices.
Parameter
Description
option
0x00 = Normal 0x01 = Bypass PIN 0x02 = Force Online
0x04 = Acquirer not available (Note: prevents long timeout on waiting for host approval) (causes “decline” to be generated internally if ARQC is generated)
To use Quick Chip mode, set the most significant bit to ‘1’.
0x80 = Quick Chip, Normal 0x81 = Quick Chip, Bypass PIN 0x82 = Quick Chip, Force Online
Refer to Appendix C for supported devices.
amount
Amount Authorized (EMV Tag 9F02, format n12, 6 bytes) in hex string For example: “000000000999”, means 9.99 dollars.
transactionType
Valid values:
0x00 = Purchase (listed as “Payment” on ICS)
0x01 = Cash Advance (not supported for this reader)
0x02 or 0x09 = Cash back (0x09 only supported when using contactless) 0x04 = Goods (Purchase)
0x08 = Services (Purchase)
0x10 = International Goods (Purchase) 0x20 = Refund
0x40 = International Cash Advance or Cash Back 0x80 = Domestic Cash Advance or Cash Back
Parameter
Description
status
Indicates the status of User Selection:
0x00 – User Selection Request completed, see Selection Result 0x01 – User Selection Request aborted, cancelled by user
0x02 – User Selection Request aborted, timeout
selection
Indicates the menu item selected by the user. This is a single byte zero based binary value.
Parameter
Description
status
Result codes:
0x0000 = Success, the transaction was cancelled 0x038D = Failure, no transaction currently in progress
0x038F = Failure, transaction in progress, card already inserted
Parameter
Description
response
Hex string for the response data following TLV response message. For details about the ARQC format, see the Programmer's Manual (COMMANDS) for the specific device with which you are communicating.
length
Two byte binary, most significant byte first. This gives the total length of the Acquirer Response message that follows.
Parameter
Description
Command
Hexadecimal string of the byte array for the extended command. The first two bytes represent the value of the extended command. The next two bytes (most significant byte first) indicate the total length of the following data in bytes.
Parameter
Description
Command
Hexadecimal string of the byte array for the command.
4.55 startTransaction (EMV Device Only)
4.56 setUserSelectionResult (EMV Only)
4.57 cancelTransaction
4.58 setAcquirerResponse (EMV Device Only)
4.59 sendExtendedCommand (EMV Device and iDynamo 5 Gen III Only)
4.60 sendCommandSync
(void) setTimeout:(NSUInteger)timeoutMS
(void) setTimeFrame:(unsigned int)ms.
(void) enableDebugPrint:(BOOL)enabled.
(int) updateFirmware: (int) firmwareType Data : (NSData*) firmwareData;