About This Document

This document describes how to communicate with iDynamo 5 Gen III secure card reader (SCR) equipped with the MP application specific integrated circuit (ASIC).

About SDKs

MagTek provides convenient software development kits (SDKs) and corresponding documentation for various programming languages and operating systems. The API libraries included in the SDKs wrap the details of the connection in an interface that conceptually parallels the device’s internal operation, freeing software developers to focus on the business logic, without having to deal with the complexities of platform APIs for connecting to the various available connection types, communicating using the various available protocols, and parsing the various available data formats. Information about using MagTek wrapper APIs is available in separate documentation, including D99875535 Secure Card Reader Authenticator API PROGRAMMING REFERENCE MANUAL.

The SDKs and corresponding documentation include:

• Functions for sending the direct commands described in this manual

• Wrappers for commonly used commands that further simplify development

• Sample source code to demonstrate how to communicate with the device using the direct commands described in this manual

To download the SDKs and documentation, search for “SDK” and select the SDK and documentation for the programming languages and platforms you need, or contact MagTek Support Services for assistance.

Software developers also have the option to revert to direct communication with the device using libraries available in the chosen development framework. For example, custom software written in Visual Basic or visual C++ may make API calls to the standard Windows USB HID driver. This document provides information and support for developing host software using that method.

MagTek has also developed software that demonstrates direct communication with the device, which software developers can use to test the device, and which provides a starting point for developing other software. For more information, see the MagTek web site, or contact your reseller or MagTek Support Services.

The general terms “device” and “host” are used in different, often incompatible ways in a multitude of specifications and contexts. For example, “host” may have different a meaning in the context of USB communication than in the context of networked financial transaction processing. In this document, “device” and “host” are used strictly as follows:

• Device refers to the Secure Card Reader Authenticator (SCRA) that receives and responds to the command set specified in this document; device refers to iDynamo 5 Gen III.

• Host refers to the piece of general-purpose electronic equipment the device is connected or paired to, which can send data to and receive data from the device. Host types include PC and Mac computers/laptops, tablets, smartphones, teletype terminals, and even test harnesses. In many cases the host may have custom software installed on it that communicates with the device. When “host” must be used differently, it is qualified as something specific, such as “acquirer host” or “USB host.”

• Similarly, the word “user” is used in different ways in different contexts. This document separates users into more descriptive categories:

Because some connection types, payment brands, and other vocabulary name spaces (notably Bluetooth® (LE), EMV, smart phones, and more recent versions of Windows) use very specific meanings for the term “Application,” this document favors the term software to refer to software on the host that provides a user interface for the operator.

The combination of device(s), host(s), software, firmware, configuration settings, physical mounting and environment, user experience, and documentation is referred to as the solution.

Copyright © 2006 - 2024 MagTek, Inc.

Information in this publication is subject to change without notice and may contain technical inaccuracies or graphical discrepancies. Changes or improvements made to this product will be updated in the next publication release. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of MagTek, Inc.

MagTek® is a registered trademark of MagTek, Inc.

MagnePrint® is a registered trademark of MagTek, Inc.

MagneSafe® is a registered trademark of MagTek, Inc.

Magensa™ is a trademark of MagTek, Inc.

IntelliStripe® is a registered trademark of MagTek, Inc.

AAMVA™ is a trademark of AAMVA.

American Express® and EXPRESSPAY FROM AMERICAN EXPRESS® are registered trademarks of American Express Marketing & Development Corp.

D-PAYMENT APPLICATION SPECIFICATION® is a registered trademark to Discover Financial Services CORPORATION

ANSI®, the ANSI logo, and numerous other identifiers containing "ANSI" are registered trademarks, service marks, and accreditation marks of the American National Standards Institute (ANSI).

ISO® is a registered trademark of the International Organization for Standardization.

UL™ and the UL logo are trademarks of UL LLC.

PCI Security Standards Council® is a registered trademark of the PCI Security Standards Council, LLC.

Apple Pay®, iPhone®, iPod®, and Mac® are registered trademarks of Apple Inc., registered in the U.S. and other countries. App Store^SM is a service mark of Apple Inc., registered in the U.S. and other countries. iPad™ and iPad mini™ are trademarks of Apple, Inc. Apple and MFi are registered trademarks of Apple Inc. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used by Apple Inc. under license.

Google Play™ store and Android™ platform are trademarks of Google Inc.

Microsoft® and Windows® are registered trademarks of Microsoft Corporation.

USB (Universal Serial Bus) Specification is Copyright © 1998 Compaq Computer Corporation, Intel Corporation, Microsoft Corporation, NEC Corporation.

Keyboard Usage Definitions content is taken from Universal Serial Bus HID Usage Tables, Version 1.12, Section 10, Keyboard/Keypad Page (0x07) ©1996-2005 USB Implementers’ Forum

Modifier Byte Definitions content is taken from Section 8.3 Report Format for Array Items, Device Class Definition for Human Interface Devices (HID) Version 1.11, ©1996-2001 USB Implementers’ Forum, .

Some device icons courtesy of , used under the Creative Commons Attribution-NoDerivs 3.0 license.

All other system names and product names are the property of their respective owners.

Table 0‑1 - Revisions

Command 0x0000 - Get Property

This command lets the host retrieve a property (see section on properties) from the device using the 1-byte Property ID.

Table - Get Property Command

Table - Get Property Response

Legacy (if needed) for simple & short properties.

This command sets a property in the device. For secure properties, this command should be the payload for the Send Secured Command.

This command is used to reset the device.

The host uses this command to get the date / time from the device’s internal clock. The value returned is set to Coordinated Universal Time (UTC). The host is responsible for converting the response to local time.

This command returns the information about the specified key to the host.

This command is used to activate or deactivate the button. The command is rejected if the device is not in Qwantum mode. The button always defaults to disabled after reset or when switching modes.

iDynamo 5 Gen III connects to iOS products via a USB-C or Lighting to USB-C cable.

How to Use Apple iAP2 Connections

This section provides information about developing an iOS app that interfaces with the device via the Lightning or USB connector using iPod Accessory Protocol 2 (iAP2). For sample code and other supporting materials, see DYNAMAX / EDYNAMO / UDYNAMO / ADYNAMO / IDYNAMO / KDYNAMO / SDYNAMO / TDYNAMO SDK FOR IOS (WEB), available from MagTek.

To develop host software for an iOS host that connects to the device, you must know the following device properties, which are specified by the purchaser when ordering, and loaded by the manufacturer:

• protocolString, also known as the SDK Protocol, usually in the form of a reverse DNS string unique to the host software developer or the device purchaser.

The host software project must include the protocolString in its .plist file before compiling. Spelling, including punctuation and capitalization, must exactly match the protocolString of the device.

The host software should initiate a connection to the device using the iOS SDK’s External Accessory Framework (for sample code, see Apple’s EADemo app). Upon establishing the connection, the host can begin exchanging data with the device.

This USB device conforms to the USB specification revision 2.0 and Human Interface Device (HID) class specification version 1.11. The device is set up as a full-speed, high-powered USB device that draws power from the USB bus. iDynamo5 Gen III identifies itself to the USB host with MagTek’s vendor ID 0x0801 and Product ID (PID) of 0x0020. All USB enumeration will include the device serial number.

HID reports used by the host can be divided into two types:

• Feature Reports, which the host uses to send commands to the device and receive responses using Get Feature and Set Feature.

• Input Reports are used by the device to send unsolicited notifications to the host when the device’s state changes, or to send asynchronous responses to the host when a command completes. The device commonly uses input reports when reporting card swipes, device events, or when a command takes more time for the device to process than is reasonable for the host to wait on a blocking call for the device to acknowledge completion.

A device in KB mode identifies itself to the USB host as a keyboard and transmits data to the host as ASCII as though it is being typed by a person on an actual keyboard. It does this by mapping each of the possible ASCII characters in the stream to keystrokes. To send an ASCII character to the host, the device looks up the ASCII character in the key and retrieves a combination of a single Key Usage which is a unique value assigned to every keyboard key, and a Key Modifier Byte and sends them to the host. The key modifier byte modifies the meaning of the key usage ID, by indicating whether any combination of the right or left Ctrl, Shift, Alt or GUI keys [as defined by Universal Serial Bus (USB) Device Class Definition for Human Interface Devices (HID)] are pressed at the same time as the key usage ID.

The device transmits ASCII 0 to 31 and 127 as their equivalent control code combinations. For example, for a carriage return value 13 (0x0D), the device appears to the host as a keyboard where a person very quickly presses and holds the Ctrl key, then presses the M key, then releases both keys.

When the keymap contains a Key Usage ID and Key Modifier Byte of 0xFF for the ASCII value the device wants to send, the device uses Alt ASCII code keystrokes instead of key map values, meaning it simulates holding down the Alt key on a keyboard and typing the three-digit decimal value of the ASCII character it wants to send. For example, to transmit the ASCII character ‘?’ (063 decimal in the ASCII table), the device sends keypad ‘0’ combined with the Left Alt key modifier, then keypad ‘6’ combined with the Left Alt key modifier, then keypad ‘3’ combined with the Left Alt key modifier.

Commands and Responses

Feature reports are used to send commands and receive responses, even when KB mode is active.

Notifications (RFU)

This section defines how the device communicates with the host over the USB HID interface.

The data transmitted in commands, responses, and notifications can be substantial, with a size limit of 64 kilobytes (64K bytes). However, the USB HID interface utilized by V5 restricts messages to 64 bytes. Therefore, to accommodate larger messages, we employ specific methods to segment them into multiple 64-byte packets. The segmentation approach varies depending on the message type to ensure compatibility with legacy V5. Below is the core structure of a USB HID packet.

The device makes data available to the host using one or more Input Reports over a USB Interrupt IN pipe. The host will poll the device at the configured Polling Interval to see if Input Reports are ready. The device must respond to polls with a USB NAK when no Input Reports are available.

• Data Messages sent by the device use Input Report ID 0x01.

• Notification Messages sent by the device use Input Report ID 0x02.

The host sends commands using a Set Feature Report and sends a Get Feature Report to the device to retrieve a synchronous response when appropriate. Feature reports use report ID 0x01.

The host should send both Feature Report types using the default Control pipe using a blocking call to the operating system’s native USB libraries. The device NAKs the Status page of a Set Feature Report until it finishes the requested operation, and if it does not respond, the operating system will generally time out and report failure. This method ensures that as soon as the device has fulfilled the command request embedded in the Set Feature Report, the host software can immediately call a follow-up Get Feature Report to retrieve the command.

In very rare cases, the host may simply send a Get Feature Report directly without a preceding Set Feature Report. The Commands documentation specifies these special cases if they exist.

Commands are sent to the device using USB Set Feature Reports using Report ID 1.

Sending commands to the device over a packeted interface (maximum parameter size is 64k (0xFFFF). Standard command format gets broken down into packets for interfaces that do not support unlimited length messages. This is compatible with the V5 extended command protocol.

The number ranges shown in packets assume the interface is USB with a maximum message size of 64 bytes.

The Command and Parameter Data length fields stay the same for all packets. Each packet will contain one segment of parameter data up to 52 bytes. The data offset indicates which portion of the parameter data is contained within this packet.

If the required Parameter Data is 52 bytes or shorter, the host can send the entire command using a single command packet. If the Parameter Data is longer than 52 bytes, the host should split the data into multiple packets of 52 or fewer bytes and send multiple command packets. Assuming 52-byte packets, the first packet the host sends should specify Data Offset = 0, the next packet should specify Data Offset = 52, and so on, until the host has sent all the Parameter Data. The device’s response to each packet contains either an extended command result code or a standard result code for the command that was sent:

A packet with Data Offset = 0 is considered the start of a new command. If there are still packets pending from a previous command, then that command is cleared, and all data received is erased.

The device will respond to packets with a 0x0B,0x00 when it expects additional packets (i.e., the length of parameter data received is less than the full parameter data length). When all data has been received, then the device will respond with a packet starting with 0x0A and include the response message for the command.

ACK Packet … Send next packet.

Result Code 0x0B - Protocol Request Pending indicates the device is buffering the incoming data and expects the host to send subsequent packets.

Error due to invalid or missing data or due to a timeout while the device is waiting for more packets.

Response messages are generated after executing a command and made available to the host as a feature report with the report ID set to 1. The host uses the USB Get Feature Report to receive the response or a portion. The following should be compatible with V5 extended responses.

After the host receives the initial response packet, it’s up to the host to collect the data and send 0x4A commands to get more response packets until all data has been received.

Notification messages with a data size longer than 52 bytes will need to be split into multiple packets to accommodate the USB HID interface. Notifications are made available to the host as one or more USB Input Reports with the report ID set to 2.

Data messages are another type of asynchronous communication and handled in the same manner as a notification, except the report ID is set to 1.

When connected to an iOS host, the device communicates over what appears to be a simple bidirectional serial line transferring binary data. To manage serial communications, we utilize an old method called SLIP (Serial Line Internet Protocol). This allows the addition of message control characters and a method to distinguish between control and data.

Each message is prefixed by a one-byte message type followed by a two-byte message length. The possible types are:

• 00 - Data (Data is ASCII text to be compatible with KB emulation output)

• 02 - Notification

• 04 - Response

• 05 – Command

Messages are framed before and after with a byte value of 0xC0. Because this value can also appear as part of the data message, a few 2-byte sequences are added to distinguish between control and data bytes. The sender modifies the outgoing data, and the receiver translates the incoming data back to the original message. Conversion can be done on the fly during the sending and receiving processes.

• Assemble message.

• Add message type and length to the beginning of the message.

• Replace any bytes with value 0xDB with bytes 0xDB 0xDD.

All result codes must be both universal and functional. The code 0x0396 signifies invalid date or time data, indicating that the date or time has not been set. Subsequent attempts to set the property will fail with result code 0x07, indicating a sequence error. The response may be delayed.

Table 5‑1 Response Result Codes

About Properties

Properties are used to provide information about the device and how to configure it. Secured properties are set at the factory or by an administrator using software tools supplied by MagTek. Property values take effect immediately unless specified otherwise.

Property 0x00 – Main Firmware ID

This read-only property returns the main firmware part number, a dash, the major and minor revision number, followed by a dash and the firmware type. {main firmware part number}-{3 character rev}-{type}

This one-byte value (1-255) sets the device’s polling interval in milliseconds for the Interrupt in Endpoint. The device sends the value of this property as part of USB device enumeration to the host.

This value is also found on the product label. The property contains the 7-character MagTek device serial number. This value is used for USB device enumeration, data messages, and message security.

This is a maximum 7-byte read-only property that identifies the MagneSafe Feature Level supported on this device.

This property is defined as follows:

• id = 0: Decodes standard ISO/ABA cards only

• id = 1: Decodes AAMVA and 7-bit cards also

If the id flag is set to 0, only tracks that conform to the ISO card data format allowed for that track are decoded. If the track cannot be decoded by the ISO method, the device reports a decode error.

For each pair of track bits, valid values are as follows:

• T_# = 00: Track Disabled

• T_# = 01: Track Enabled

• T_# = 10: Track Enabled and Required (Generates error if track is blank)

This property specifies how the device should mask data on ISO/ABA type cards: Each byte in the sequence has the following meaning:

This property specifies the factors for masking data on AAMVA type cards. Each byte in the property has the following meaning:

This property represents the device’s current connection type.

Valid values for this property are:

• 0x00 = USB HID (HID Only)

• 0x01 = USB Keyboard Emulation (KB) (USB KB Only)

• 0x02 = iAP2

• 0xFF = One-Time Automatic (HID Only | iAP2 Only). When the property is set to this value and the device connects to a host, the device attempts to determine which interface type the host is using. After it successfully detects the interface type, it automatically sets this property to the value that corresponds to that interface type.

Configures Magneprint options.

The device sends the value of this property to the host before all other card data. For example, if the host software requires a set of keystrokes to begin the process of receiving card data, this property could be set to transmit that keystroke sequence.

The device sends the value of this property to the host at the end of the data message. For example, if the host software requires a set of keystrokes to end the process of receiving card data, this property could be set to transmit that keystroke sequence. If the value is 0, the device does not send a termination string.

Property 0x6E - Mask Service Code (Set Mask Service Code Only)

This property controls the masking of the service code on ISO card tracks 1 and 2. If this property is set to 1, the device masks the service code. If this property is set to 0, the device does not mask the service code.

The host can use this property to enable Selectable Card Data Encryption. Any of the bits in this property enables the SCDE with the corresponding data field included in the encrypted SCDE.

The M002 message is transmitted to the host instead of the M001 message when the following four conditions are met when a financial card is swiped.

• Any of the defined property 0x78 bits are set to 1 (enabled)

• Card Encode Type of the swiped card is ISO

• Initial SCDE DUKPT Key was injected into the device

For security purposes, the reader will reset itself once a day. You can choose what time this reset will occur by changing this property. Set the value to HHMM in Coordinated Universal Time (UTC). HH is one byte with a value of 0-23. MM is one byte with a value of 0-59 The new value takes effect after the next device reset or power cycle.

This data is stored securely (encrypted by DDEK). The data gets sent out in encrypted form using DUKPT when the device is in QWANTUM Mode, the button is enabled, and the button is pressed.

For PCI certified devices, this value will match the one found on the PCI website and the product label.

This property indicates whether the firmware was built to use production device keys (005454) or test device keys (000101).

The primary functions of device states are to inform production software about completed steps and pending tasks. It serves as a checklist and can also assist with remote services and RMAs.

If a key has been loaded into the device, then it’s bit indicator should be set to 1.

A fully loaded reader would return a keymap of: 7E 00 07 00 8C 00 00 00.

The host can use this property to adjust the device’s USB packet delay. The property can be set to 0 to have no delay, or it can be set to a specific value in the range of 1 to 255 ms.

• Adjusting this value does not require security when the device is fully configured.

• Adjusting this value does not affect the USB HOST POLL TIMEOUT, PROPERTY 0x52. In fact, it is mostly independent from the polling interval.

MagTek recommends the following values for various platforms:

• Windows = 0x00 (0 ms)

• Android = 0x19 (25 ms)

• Linux = 0x32 (50 ms)

Multi-byte values like command and data lengths are always big-endian.

Message Types

Data

Data Messages are formed in response to a cardholder event such as swiping a card or pressing a button. These messages are formatted as a block of ASCII text and compatible with all interfaces.

Commands

Commands consist of a 2-byte command, a 2-byte Parameter Data Length, and Parameter Data as needed.

Table - Command Structure

Responses consist of a 2-byte return code, a 2-byte response data length, and response data as needed.

Notifications consist of a 2-byte notification code, a 2-byte notification data length, and notification data when needed. They are sent asynchronously due to device events. They can also be used as delayed responses for commands that take longer to process.

Sentinels

Data for each card track is typically bracketed by a start and end sentinel. The sentinel characters can be changed by setting properties. The start sentinel can also indicate what format was used to encode the track.

[SS] Track Data [ES]

If a property value is set to 0, then no character will be sent.

Masking

The PAN field must always be partially masked. The device can be configured to expose the 0-8 leading characters and 0-4 trailing characters. The 8-digit limit for leading characters automatically drops to 6 for cards where the PAN length is less than 16 (e.g. American Express).

Properties 0x07 and 0x08 are used to configure PAN masking.

Data messages include DUKPT KEY information fields so the host can derive the correct decryption or MAC key.

Example:

Data messages will always be made up of ASCII text characters regardless of the interface for compatibility purposes. Text is used to address limitations when using keyboard emulation.

Any Field with no value will be empty between separator characters.

The device transmits an M002 message with three new data fields: Encrypted SCDE, KSN (SCDE) and DUKPT Key Info (SCDE) to the host instead of an M001 message when the following four conditions are satisfied. Selectable Card Data Encryption is enabled through Property 0x78.

• Any of the defined property 0x78 bits are set to 1 (enabled),

• Card Encode Type is ISO (a.k.a. financial card),

• SCDE DUKPT key is injected or present in the device, and

If any one of the four conditions is not met, an M001 message will be returned to the host instead of an M002 message.

The encrypted SCDE field in the M002 message, [Encrypted SCDE], includes six data fields, field_1 ~ field_6. The six data fields are placed in a buffer prior to encryption. The selectable card data element starts with a field separator (FS) followed by a data field, and the last field separator is appended following the sixth data field (field_6) as shown below (total seven FS characters). The field separator used in the SCDE is the same FS used in the M001 or M002 message, which may be changed using Property 0x23.

Each data field in the SCDE is defined as follows.

The SCDE DUKPT key (DKPTM1F) is used to encrypt the six data fields (| field_1 | field_2 | field_3 | field_4 | field_5 | field_6 |)only. No other keys should be used for the SCDE.

The encrypted SCDE field in the M002 message is an encrypted blob holding six card data fields selected with Property 0x78 bits. If a defined bit is set to zero, the corresponding data field will be empty in the clear-text SCDE. The clear-text SCDE including enabled data fields will be encrypted with an SCDE DUKPT future key.

When all defined bits in the property 0x78 are set to zeros, the encrypted SCDE is disabled. As a result, the M001 message should be transmitted to the host instead of the M002 message.

Encrypt( | field_1 | field_2 | field_3 | field_4 | field_5 | field_6 | )

Field Separation

This device uses configurable properties to define characters that get inserted into the message for parsing purposes. The simplest option is to have characters for start of message (SOM), end of message (EOM), and field separation (FS) only.

This is the message format for Qwantum cards, or for any card when Qwantum Mode is on.

This message is used when the device sends out encrypted data from the Secure Buffer.

This message is used when the device sends out when Qwantum Secure Data is empty.