1 of 90

OEM Readers and Components

This page provides documentation for MagTek OEM magnetic stripe and EMV insertion readers and components, including developer guides, mechanical drawings, firmware downloads, and setup instructions to help integrate secure card reading into your own kiosk, payment terminal, and unattended hardware designs.

Programmer's Manuals

This page provides comprehensive programmer's manuals, EMV flowcharts, configuration instructions, and demo guides to help you integrate the oDynamo hybrid insertion secure card reader authenticator into your software solutions using direct commands or MagTek's Common Message Structure (MTCMS) across multiple development platforms.

Documents

Reference Section

Information Available

A reference manual providing the direct command set for controlling the oDynamo's magnetic stripe and EMV contact chip reading functions in unattended terminal applications.

Introduction

About This Document

This document describes the master set of messages a host can send and receive via byte-by-byte direct communication with secure card reader authenticator devices that implement MagTek Common Message Format (MCMF), such as oDynamo (referred to in this document as “the device”).

About Terminology

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 MagTek product that receives and responds to the command set specified in this document. Devices include oDynamo.
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:

The cardholder
The operator (such as a cashier, bank teller, customer service representative, or server), and The developer or the administrator (such as an integrator configuring the device for the first time).

Because some connection types, payment brands, and other vocabulary name spaces (notably Bluetooth, 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 word terminal uses the EMV definition, which may mean a stationary interface for a cashier or teller at a point of sale or bank, an ATM or other unattended device, a handheld service interface on an air or water craft, and so on. In some situations the terminal interacts with the operator, though in self-service situations the terminal might interact with a cardholder directly.

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.

This device and related products use a common communication protocol across a variety of physical connection layers, which can include universal serial bus (USB), Ethernet, RS-232, and Bluetooth Low Energy (“Bluetooth LE”). The set of available connection layers depends on the device. Details for communicating with devices via each physical connection type are provided in section 3 Connection Types.

The information in this document applies to multiple devices. When developing solutions that use a specific device or set of devices, integrators must be aware of each device’s communication interfaces, features, and configuration options, which affect the availability and behavior of some messages. Table 1-1 provides a list of device features that may impact message availability and behavior.

MagTek provides convenient Software Development Kits (SDKs) that include libraries for some connection types and development frameworks. These SDKs wrap the details of the connection in an interface that conceptually parallels the device’s internal operation, freeing developers from dealing with the details of the connection, and allowing them to focus on software business logic. In cases where SDK libraries are available, developers also have the option to revert to direct communication with the device using libraries available in the chosen development framework. This document provides information and support for the latter method. Information about using MagTek SDKs is available in separate documentation.

Appendix A Examples

Reserved

MTCMSMessage Class Methods

This class allows building MagTek CMS messages to be used in communications with MagTek CMS devices.

MTCMSMessage

This constructor method builds an MTCMSMessage instance with the provided values.

public void MTCMSMessage(int messageType, int applicationID, int commandID, int dataTag, byte[] data)

Parameters:

Parameter

Description

messageType

Return Value: None

This constructor method builds an MTCMSMessage instance with the provided byte array value.

Parameters:

Return Value: None

This method sets the value of MessageType.

Parameters:

Return Value: None

This method sets the value of ApplciationID.

Parameters:

Return Value: None

This method sets the value of CommandID.

Parameters:

Return Value: None

This method sets the value of ResultCode.

Parameters:

Return Value: None

This method sets the value of Data Tag and the value of Data.

Parameters:

Return Value: None

This method returns the value of MessageType.

Return Value: MessageType value.

This method returns the value of ApplicationID.

Return Value: ApplicationID value.

This method returns the value of CommandID.

Return Value: CommandID value.

This method returns the value of ResultCode.

Return Value: ResultCode value.

This method returns the value of Data Tag.

Return Value: Data Tag value.

This method returns the value of Data.

Return Value: Data value.

This method returns the message bytes.

Return Value: Message bytes.

MTCMS Class Methods

After creating an instance of the MTCMS class in your software project, use the methods described in this section to communicate with MagTek CMS device.

This method initiates request to discover devices that are visible to the host using the specified connection interface. The DeviceListReceived event will provide information regarding the available devices once the discovery process is completed.

Parameters:

Rails

For all Rails documentation, including programmer’s manuals, the technical reference manual, software/SDKs, and warranty info, please visit the official Rails Support Page:

Rails Support

For more help

Need Help?

For additional support, please contact MagTek Support:

Technical Support:

📧 Email:

Introduction

About This Document

About Terminology

Device refers to the MagTek product that receives and responds to the command set specified in this document. Devices include oDynamo.
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:

The cardholder
The operator (such as a cashier, bank teller, customer service representative, or server), and The developer or the administrator (such as an integrator configuring the device for the first time).

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.

MTCMSNET Demo Guide

Manual Part Number: D998200166-10

REGISTERED TO ISO 9001:2015

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. oDynamo™ is a trademarks of MagTek, Inc.

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

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

Table 0.1 – Revisions

SOFTWARE LICENSE AGREEMENT

IMPORTANT: YOU SHOULD CAREFULLY READ ALL THE TERMS, CONDITIONS AND RESTRICTIONS OF THIS LICENSE AGREEMENT BEFORE INSTALLING THE SOFTWARE PACKAGE. YOUR INSTALLATION OF THE SOFTWARE PACKAGE PRESUMES YOUR ACCEPTANCE OF THE TERMS, CONDITIONS, AND RESTRICTIONS CONTAINED IN THIS AGREEMENT. IF YOU DO NOT AGREE WITH THESE TERMS, CONDITIONS, AND RESTRICTIONS, PROMPTLY RETURN THE SOFTWARE PACKAGE AND ASSOCIATED DOCUMENTATION TO THE ADDRESS ON THE FRONT PAGE OF THIS DOCUMENT, ATTENTION: CUSTOMER SUPPORT.

MagTek, Incorporated (the "Licensor") owns and has the right to distribute the described software and documentation, collectively referred to as the "Software."

LICENSE: Licensor grants you (the "Licensee") the right to use the Software in conjunction with MagTek products. LICENSEE MAY NOT COPY, MODIFY, OR TRANSFER THE SOFTWARE IN WHOLE OR IN PART EXCEPT AS EXPRESSLY PROVIDED IN THIS AGREEMENT. Licensee

may not decompile, disassemble, or in any other manner attempt to reverse engineer the Software. Licensee shall not tamper with, bypass, or alter any security features of the software or attempt to do so.

TRANSFER: Licensee may not transfer the Software or license to the Software to another party without the prior written authorization of the Licensor. If Licensee transfers the Software without authorization, all rights granted under this Agreement are automatically terminated.

COPYRIGHT: The Software is copyrighted. Licensee may not copy the Software except for archival purposes or to load for execution purposes. All other copies of the Software are in violation of this Agreement.

TERM: This Agreement is in effect as long as Licensee continues the use of the Software. The Licensor also reserves the right to terminate this Agreement if Licensee fails to comply with any of the terms, conditions, or restrictions contained herein. Should Licensor terminate this Agreement due to Licensee's failure to comply, Licensee agrees to return the Software to Licensor. Receipt of returned Software by the Licensor shall mark the termination.

LIMITED WARRANTY: Licensor warrants to the Licensee that the disk(s) or other media on which the Software is recorded are free from defects in material or workmanship under normal use.

THE SOFTWARE IS PROVIDED AS IS. LICENSOR MAKES NO OTHER WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Because of the diversity of conditions and PC hardware under which the Software may be used, Licensor does not warrant that the Software will meet Licensee specifications or that the operation of the Software will be uninterrupted or free of errors.

IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE, OR INABILITY TO USE, THE SOFTWARE. Licensee's sole remedy in

the event of a defect in material or workmanship is expressly limited to replacement of the Software disk(s) if applicable.

GOVERNING LAW: If any provision of this Agreement is found to be unlawful, void, or unenforceable, that provision shall be removed from consideration under this Agreement and will not affect the enforceability of any of the remaining provisions. This Agreement shall be governed by the laws of the State of California and shall inure to the benefit of MagTek, Incorporated, its successors or assigns.

ACKNOWLEDGMENT: LICENSEE ACKNOWLEDGES THAT HE HAS READ THIS AGREEMENT, UNDERSTANDS ALL OF ITS TERMS, CONDITIONS, AND RESTRICTIONS, AND AGREES TO BE BOUND BY THEM. LICENSEE ALSO AGREES THAT THIS AGREEMENT SUPERSEDES ANY AND ALL VERBAL AND WRITTEN COMMUNICATIONS BETWEEN LICENSOR AND LICENSEE OR THEIR ASSIGNS RELATING TO THE SUBJECT MATTER OF THIS AGREEMENT.

QUESTIONS REGARDING THIS AGREEMENT SHOULD BE ADDRESSED IN WRITING TO MAGTEK, INCORPORATED, ATTENTION: CUSTOMER SUPPORT, AT THE ADDRESS LISTED IN THIS DOCUMENT, OR E-MAILED TO

Common Message Structure (MTCMS) Programmer’s Reference Manual (C++)

Manual Part Number: D998200159-10 REGISTERED TO ISO 9001:2015 MagTek I 1710 Apollo Court I Seal Beach, CA 90740 I Phone: (562) 546-6400 I Technical Support: (888) 624-8350 www.magtek.com Copyright © 2006-2018 MagTek, Inc. Printed in the United States of America 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. Microsoft® and Windows® are registered trademarks of Microsoft Corporation. All other system names and product names are the property of their respective owners.

Table 0.1 Revisions

Rev Number

Date

SOFTWARE LICENSE AGREEMENT

TERMS, CONDITIONS, AND RESTRICTIONS MagTek, Incorporated (the "Licensor") owns and has the right to distribute the described software and documentation, collectively referred to as the "Software."

LICENSE: Licensor grants you (the "Licensee") the right to use the Software in conjunction with MagTek products.

LICENSEE MAY NOT COPY, MODIFY, OR TRANSFER THE SOFTWARE IN WHOLE OR IN PART EXCEPT AS EXPRESSLY PROVIDED IN THIS AGREEMENT.

Licensee may not decompile, disassemble, or in any other manner attempt to reverse engineer the Software. Licensee shall not tamper with, bypass, or alter any security features of the software or attempt to do so.

LIMITED WARRANTY: Licensor warrants to the Licensee that the disk(s) or other media on which the Software is recorded are free from defects in material or workmanship under normal use.

IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE, OR INABILITY TO USE, THE SOFTWARE.

Licensee's sole remedy in the event of a defect in material or workmanship is expressly limited to replacement of the Software disk(s) if applicable.

QUESTIONS REGARDING THIS AGREEMENT SHOULD BE ADDRESSED IN WRITING TO MAGTEK, INCORPORATED, ATTENTION: CUSTOMER SUPPORT, AT THE ADDRESS LISTED IN THIS DOCUMENT, OR E-MAILED TO SUPPORT@MAGTEK.COM.

Connection Types

Table 1-1 in section 1.4 includes a list of connection types available for each device. The following subsections provide details developers will need to communicate with the device using each connection type.

How to Use Network Connections (Ethernet or 802.11 Wireless Only)

How to Use Ethernet Connections (Ethernet Only)

When the device is connected to a network via a 10/100 Ethernet port, it will attempt to contact a DHCP server to acquire a dynamic IP address during power-up. See the network administrator to determine the IP address the DHCP server assigned to the device. After determining the IP address, use port 5000 to communicate with the device.

How to Send Commands Using the Network Connection

The messages exchanged between the host and the device on the TCP/IP connection do not require any wrappers or encoding: The binary data flowing through the connection is identical to the message format defined in section 2 Messages, Commands, Responses, and Notifications and in section 4 Command Set. A C0 at the beginning of a message’s usage table means that without any preparation other than binding to the port, the host begins sending the command by sending a single binary byte 0xC0.

For example, to send Command 0x00:0x10 - Get Product ID to the device over TCP/IP, the host should send a stream consisting of single binary byte 0xC0, followed by single binary byte 0x01, followed by single binary byte 0x01, followed by single binary byte 0xC1, and so on following the sequence in Table 4-1. The device will then send a response over the same connection according to the sequence in Table 4-2.

The messages exchanged between the host and the device on the RS-232 connection require a small wrapper and must be ASCII encoded hexadecimal (‘0’ through ‘F’ only). The message format is defined in section 2 Messages, Commands, Responses, and Notifications and in section 4 Command Set. ASCII encoding means when the device intends to send C0 at the beginning of a message’s usage table, it should send two ASCII bytes, where ‘C’ is ASCII 0x43 and ‘0’ is ASCII 0x30. When the device is using default settings, the host should send a line feed (0x0A) to signal the end of the message. The device’s responses and notifications will be wrapped and encoded the same way.

For example, to send Command 0x00:0x10 - Get Product ID to the device over the RS-232 connection, the host should send a stream consisting of ASCII ‘C’ (0x43), ASCII ‘0’ (0x30), ASCII ‘0’ (0x30), ASCII ‘1’ (0x31), ASCII ‘0’ (0x30), ASCII ‘1’ (0x31), ASCII ‘C’ (0x43), ASCII ‘1’ (0x31), and so on following the sequence in Table 4-1, then a line feed (0x0A). The device will then send a response over the same connection according to the sequence in Table 4-2, then a line feed (0x0A).

The devices only use TXD and RXD; hardware handshaking is not available. The default serial settings are 9600 bps, No parity, 8 data bits, and 1 stop bit.

The device can optionally be configured by the manufacturer to expect / transmit a Starting Byte and an ASCII CRC checksum in this order: <Starting Byte> <Message in ASCII> <CRC in ASCII> <Ending Byte>. The device’s default setting is “raw mode,” where the device only expects / transmits the Ending Byte, which is set to Line Feed (0x0A). Other popular choices when ordering a device may include Starting Byte=STX (0x02); Ending Byte=ETX (0x03) or CR (0x0D).

The device conforms to the USB specification revision 2.0, and is compatible with revision 1.1. It also conforms to the Human Interface Device (HID) class specification version 1.1, and communicates as a vendor-defined HID device. This document assumes the reader is familiar with USB HID class specifications, which are available at

Developers can easily create custom software to communicate with the device using any framework that can communicate with a USB port. For example, developers can use the standard Windows USB HID driver with Visual Basic or Visual C++. MagTek has developed demonstration software that communicates with the device via this method, and developers can use it to test the device and to provide a starting point for developing other software. Because the device’s USB implementation is operating system agnostic, the device can be used with other platforms as well, such as Linux. For more information, see the MagTek web site, or contact your reseller or MagTek Support Services.

The device is a full speed high-powered USB device that identifies itself with vendor ID 0x0801 and product ID 0x001B. The device does not draw power from the USB port, and does not support USB Suspend or remote wakeup.

USB HID devices send and receive data using reports. Each report can contain several sections, called usages, each of which has its own unique four-byte identifier. The two most significant bytes of a usage are called the usage page, and the least two significant bytes are called the usage ID. Vendor-defined usages must have a usage page in the range 0xFF00 - 0xFFFF, and it is common practice for related usage IDs to share the same usage page. For these reasons, all usages for this device uses vendor-defined usage page 0xFF20.

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

Feature Reports, which can be further divided into Get types and Set types. The host exclusively uses this type of report to send messages to the device.
Input Reports are used by the device to send asynchronous responses or notifications to the host when a related feature report completes, or automatically when the device’s state changes. This is common when an operation depends on cardholder action.
Output Reports. Output reports are part of the USB HID standard, but are not used by this device.

The list of the device’s available reports and their structure is sent to the host in a report descriptor, usually just after the device is connected to the USB port. Generally the details of the report descriptor are abstracted by the developer’s HID API; however, should it become necessary to examine a report descriptor byte-by-byte, a full inventory of the report descriptor for these devices is provided in Table 3-1.

How to Send Commands Using USB HID

The general sequence the host should use to send a message to the device is as follows:

The host sends a Set Feature Report with Report ID 0x05, containing the command message in binary format (bytes) as data.
The device asynchronously sends an Input Report with Report ID 0x02, containing the defined response to the originating command in binary format (bytes) as data. Depending on the command, the response may or may not contain a Data Field Data Object (Tag C4 or E0).

The general sequence the device uses to send a message to the host is as follows:

The device’s state changes, a cardholder or operator takes action, or new information becomes available.
The device asynchronously sends an Input Report with Report ID 0x02, containing the notification message in binary format (bytes) as data.

MagTek Response to NIST SP 800-131A re: Two-Key TDEA Encryption

April 8, 2019

Dear MagTek Customers,

In March 2019, NIST (National Institute of Standards and Technology) released a document entitled: “NIST Special Publication 800-131A Revision 2 – Transitioning the Use of Cryptographic Algorithms and Key Lengths1”. In that document, it states that the use of “Two-Key TDEA Encryption” has been listed as a “Disallowed” operational mode. This NIST document has raised concerns with our customers regarding the use of Two-Key TDEA Encryption within our products.

As a security leader, it is our intent to provide relevant information and guidance on this subject to our customers, and we can advise as follows:

At present time, “Two-Key TDEA Encryption” is currently the most widely used encryption method in the electronic payments and financial services sectors. It is used to protect both PIN and PAN payment data, and is used by most of the leading secure payment devices and payment networks deployed today.

As of this date there have been no successful attacks upon Two-Key TDEA Encryption that have resulted in the compromise of payment data encrypted under this mode. As such, Two-Key TDEA Encryption remains fully approved for use by both the ANSI X9 (American National Standards X9 - Financial Services) standards group and the PCI Security Standards Council.

MagTek customers who are currently using our products in the “Two-Key TDEA Encryption” mode can rest assured that the recent NIST announcements have no impact on security requirements within the Financial Services or Electronic Payments business sectors. As such, there is no need to make any changes to your MagTek products or encryption modes at this time.

It should be noted that the NIST recommendations only apply to Federal Agencies and their Information Systems. Commercial sector financial services are exempt from the NIST directives and are best served by following the ANSI X9 and PCI security standards organizations for recommendations on encryption requirements for payment data.

In regard to Two-Key TDEA Encryption for Transport Layer Security (TLS), PCI advised on this matter during a November 2017 blog entitled: “2”.

In that discussion, PCI acknowledges that the strength of Two-Key TDEA Encryption is under review and is no longer considered as “strong cryptography” by NIST. Further, PCI mentions that when NIST formally declares

Two-Key TDEA Encryption as “fully disallowed” it will no longer be considered “strong cryptography” by PCI SSC. Now that NIST has formally declared such (as of March 2019), the payment industry will need to await PCI’s further guidance on this subject.

In the interim, PCI has recommended that organizations begin planning their transition towards AES-128, yet acknowledges that due to legacy considerations this transition may take place over a long period of time.

Additionally, PCI recommends the use of several mitigation techniques to reduce risk. One of those measures is to “Change TDEA keys regularly…every 256 transactions or daily, whichever is more frequent”. In regard to this recommendation, MagTek can advise that our products utilize DUKPT (Derived Unique Key Per Transaction), a far more rigorous key management method. DUKPT ensures that a different key is generated for each and every transaction, taking PCI’s recommendation for frequent key changes to the maximum level.

Looking ahead, both the ANSI X9 and PCI Security Standards Council are establishing standards and transition paths towards the adoption of AES-128 as the successor to TDEA for encryption of payment data.

However, due to the proven security of TDEA, legacy concerns, and logistical considerations, it is anticipated that this transition will take place over the next 4-10 years. The earliest transition milestone will be the end of PCI support for TDEA PIN encryption using fixed-key management by Jan 1, 2023.

It is important to note that this milestone does not apply to the use of TDEA PIN encryption using DUKPT (Derived Unique Key Per Transaction) key management. As such, it is very likely that there will be a long transition period where both Two-Key TDEA DUKPT and AES128 DUKPT encryption methods will be used concurrently for the foreseeable future. (See table below for upcoming security milestones.)

As a security leader in the electronic payments industry, MagTek is moving forward with implementation of AES-128 DUKPT into our products and security services. In the meantime, we will continue to support Two-Key TDEA DUKPT encryption in our products for however long the payments industry requests it, and/or the relevant security standards support it.

As always, MagTek will continue to keep our customers informed on these matters and provide clear guidance as new security trends and requirements emerge.

If you have any further questions, please contact your MagTek Sales Representative or me and we will be happy to answer any questions you may have.

Sincerely,

Larry Meyers

Vice President, Qwantum Secure Media MagTek, Inc

1710 Apollo Court Seal Beach, CA 90740 562-546-6400

About MagTek

Founded in 1972, MagTek is a leading manufacturer of electronic systems for the reliable issuance, reading, transmission and security of cards, checks, PINs and identification documents. Leading with innovation and engineering excellence, MagTek is known for quality and dependability. Its products include secure card reader/authenticators, token generators, EMV contact, contactless and NFC reading devices, encrypting check scanners, PIN pads and distributed credential personalization systems for secure magstripe and EMV enabled cards. These products are used worldwide by financial institutions, retailers, and processors to provide secure and efficient payment and identification transactions.

Today, MagTek continues to innovate. Its MagneSafe™ Security Architecture leverages strong encryption, secure tokenization, dynamic card authentication, and device/host validation enabling users to assess the trustworthiness of credentials and terminals used for online identification, payment processing, and high- value electronic transactions.

MagTek is headquartered in Seal Beach, CA. For more information, please visit

Citations

1. Barker, Elaine and Roginsky, Allen; March 21, 2019; NIST Special Publication (SP) 800-131A Revision 2; “Transitioning the Use of Cryptographic Algorithms and Key Lengths”

2 and and “PCI SSC Cryptography Expert on Triple DEA”; link:

Device Inspection Document

Inspection of Form Factor, Front, Top, Bottom, and Back

Overview

oDynamo is a PCI PTS 5.x, SRED Certified hybrid insertion reader. oDynamo’s enclosure and its associated electronics have been designed to form a Tamper Resistant Security Module (TRSM). The covers are securely attached and incorporate sensing circuits to detect if any attempt is made to open the device. Internal spaces within the device have been minimized to reduce the possibility

of unauthorized modifications. Any attempt to penetrate or modify oDynamo electronically will cause the device to permanently erase its stored encryption keys, after which oDynamo will cease to function. Inspect the following areas of the device for tampering.

Form Factor

Visual Comparison

Carefully inspect the form factor. Make certain there are no additional electronics, wires or forms added to the device. Check the overall form factor for signs of attempted entry.

Exterior Surface/Metal Bezel

Look for any hidden and additional wires in crevasses, seams, and exterior surface. Check there are no additional wires on the device.

Mounting Gasket

The device’s installation face includes a gasket. Do not remove the gasket.

Front Face Metal Bezel

The front face metal bezel is one die-cast piece. Inspect for any modification or hidden wires protruding from the card slot or drain holes.

The device includes a label well around the General Status LED. MagTek is default label.

Apply power to the device, LED should be solid GREEN. Apply power to the device for 60 seconds. If the LED shows any red, a tamper event has occurred.

The product label is located on the back of the device. Check PN, SN and HW number. Serial Number matches serial number on boot-up.

Look for any hidden and additional wires in crevasses, seams and exterior surface of the device.

Check tampering of 6 screws. DO NOT REMOVE THE SCREWS.

PRIOR TO INSTALLATION Inspect for objects or wires in the vent holes.

The card insertion slot is a smooth, unobstructed path. Insert an embossed card into the device to check for any signs of obstruction inside. Other than the magnetic head that reads magnetic stripes and contact points that read chips there are no electronics, objects, or wires on the path.

Unauthorized removal of switches will disable the device. Exercise the two (2) dismount switches by pressing them. They should return to the original position upon release of finger pressure.

Inspect individual connection ports

RS-232 and Power Port
USB Host Port
USB Device Port
Ethernet Port

Check tampering of 4 screws. DO NOT REMOVE THE SCREWS.

PRIOR TO INSTALLATION Inspect for objects or wires in the vent holes.

Unauthorized removal of switches will disable the device. Exercise the two (2) dismount switches by pressing them. They should return to the original position upon release of finger pressure.

Inspect where the seams come together to ensure there are no extraneous wires.

Inspect crevasses to ensure there are no extraneous wires.

Inspect the 4x drain holes below the bezel nose (plus the 1x drain hole to the left side of the bezel nose). There are no electronics, objects or wires coming from the drain holes.

Inspect where the seams come together to make ensure are no extraneous wires.

Inspect crevasses to make certain there are no extraneous wires.

Carefully inspect the form factor. Ensure there are no additional electronics, wires, or forms added to the device.

Periodically inspect the following items:

Metal Bezel
Card Slot

When servicing behind cabinet/door (terminal) inspect device for external wires, or foreign objects not included in the solution design. For proper installation, refer to your solution design documentation.

Observe front face of the metal bezel and inspect for any modification or hidden wires.

Look for any hidden and additional wires. No additional wires should be coming out of the holes.

Check all views of the device and compare to photos.

It is helpful to do the following for your device inspection audit.

Have a list of the device sand details listed on the asset tag.
Take photos of the front, back, and sides of each device.

Check device Part numbers, serial numbers and IDs and check physical connections. Report any suspected signs of tampering immediately.

How to find oDynamo on PCI web site https://www.pcisecuritystandards.org/assessors_and_solutions/pin_ transaction_devices.

Search for MagTek and find the product name, oDynamo, on the web page. Compare the Hardware # and Firmware #.

Periodically inspect the following items while installed: Exterior surface/metal bezel

Card slot
Five (5) drain holes
Form factor
Crevasses

Inspect the following additional items during service:

Crevasses
Screws
Ventilation holes
Connection ports

Introduction

This document provides guidelines and technical information for designing solutions that integrate oDynamo, MagTek’s manual insertion Secure Card Reader Authenticator (SCRA) for OEM solutions.

About oDynamo

oDynamo is a secure insertion card reader that is built to be durable and flexible. oDynamo allows for fast, reliable, and secure reading of magnetic stripe and chip card data from cards that meet the ISO 7810, 7811, and 7816 specifications. The slot and chassis are designed so cardholder-facing elements are impervious to liquid and other harsh environmental elements, making it an ideal solution for gas pumps, ATMs, and vending machines. Ultimate system design flexibility makes it ideal for a variety of unattended payment terminals.

oDynamo withstands a wide range of operational conditions and supports multiple communication protocols, and offers a USB connection, an Ethernet connection, and a serial connection.

Stability and Reliability

oDynamo is made to work in harsh environmental conditions and delivers reliability of 500 thousand magnetic stripe swipes and 500 thousand chip inserts. The device is designed to be integrated into a solution that provides an enclosure. The device has been tested by an FCC lab for Class B radiated susceptibility and has no special shielding requirements.

Secure Card Reading

oDynamo is secured by the MagneSafe™ Security Architecture (MSA), providing immediate encryption of card data using Triple DEA encryption with Derived Unique Key Per Transaction (DUKPT) key management. Additionally, oDynamo provides advanced MagnePrint® Card Authentication, which enables authorizing parties to detect and stop counterfeit card fraud in real-time. The firmware and the encryption keys are securely downloaded to the reader eliminating the chance of tampering.

The card latch feature allows the card to be securely held within the reader during the entire transaction process, and reduces the possibility of unwanted human intervention during card read operations. Power-fail card latch release and manual override features are available to ensure that a cardholder’s card can be easily retrieved under any conditions.

Cardholder-facing elements impervious to Liquid
Supports Multiple Protocols
Card Seated Sensor
ESD Protection: ±4kV contact discharge / ±8kV air discharge

In this document, oDynamo is referred to as the device. It is designed to be connected to a host, which is a piece of general-purpose electronic equipment which can send commands and data to, and receive data from, the device. Host types include PC computers/laptops, tablets, and smartphones. Generally, the host must have software installed that communicates with the device and is capable of processing transactions. 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. During a transaction, the host and its software interact with the operator, such as a cashier or bank teller, while the device interacts with the cardholder.

A smooth deployment of a solution that integrates oDynamo requires some up-front planning and decision-making:

Determine the overall functional requirements and desired user experience of the solution oDynamo will be integrated into.
Determine what documentation and training will be required from solution design through testing and field deployment.
Determine what type of host oDynamo will connect to, and what connection type it will use. The host can be a computer with a USB port, serial (RS-232) port, or Ethernet port. When planning, include any additional support or devices required by the host and its connection, such as physical locations, mounting, and power connections.

From device delivery through assembly, shipping, installation, usage, and maintenance, the device must not be exposed to conditions outside the ratings in Appendix A Technical Specifications.

If the device is exposed to cold temperatures, adjust it to warmer temperatures gradually to avoid condensation, which can interfere with the operation of the device or cause permanent damage.

Upon receiving the device, inspect it according to D998200235 oDynamo Device Inspection procedure included in the box to make sure it originated from an authentic source and has not been tampered with.

Do not drop or shake the device.

The device should be transported/stored inside an anti-static bag at all times.

Before removing the device from the package, remove any static charge from your body by touching an earth-grounded metal surface.

Avoid touching the exposed pins on the connectors when handling the device.

For information about ongoing maintenance of the device, such as cleaning, see section 6 Maintenance.

Quick Installation Guide

Thank you for purchasing oDynamo Development Kit 21060861. MagTek has designed this kit to help you quickly connect oDynamo to a host and activate it so you can begin testing and development.

To set up oDynamo with your test host using the contents of the kit, follow these steps:

From the Manuals tab of the oDynamo Support page on www.magtek.com, download the latest product documentation. This includes:
- oDynamo Installation and Operation Manual, which provides an overview of the product and deep detail about integrating it into a solution design.
- oDynamo Programmer’s Manual (COMMANDS), which provides details about the internal logical workings of the device and about communicating directly (without an SDK) using operating system native communication libraries and the device’s native commands.
From the Software tab of the oDynamo Support page, download the latest SDKs that pertain to your chosen development framework, which may include:
- oDynamo MTCMS .NET SDK for Windows
- oDynamo MTCMS C++ / Java SDK for Windows
In the oDynamo Installation and Operation Manual, become familiar with the device’s major components, shown in the section About oDynamo Components . The device’s four connectors and the General Status LED are of particular importance in setting up the development kit.
In the oDynamo Installation and Operation Manual, become familiar with the device’s mount and dismount behaviors, documented in the section About Pre-Activision, Activation, and Re-Activation . After installing the clip-on dismount switch lock included in this kit, it is important to not remove it without already knowing how to re-activate the device.
Unpack oDynamo, which is sold separately from the kit.
Select the oDynamo connector you will use to communicate with the host (USB, Ethernet, or RS-232), and connect the appropriate cable(s) as follows, depending on connection type:
To use the RS-232 and Power Port [J1] to communicate with the host using RS-232:
- Connect the 9-pin DIN serial data leg of the RS-232 / power cable (1000004111) to the host.
- Connect the other signal leg of the cable to the device’s RS-232 and Power Port [J1].
To use the USB Device Port [J3] to communicate with the host using USB:
- Connect the USB cable (22350300) to the device’s USB Device Port [J3].
- Connect the other end of the cable to the host’s USB port.
To use the Ethernet Port [J4] to communicate with the host using TCP/IP:
- Connect the Ethernet cable (71900032) to the device’s Ethernet Port [J4].
- Connect the other end of the Ethernet cable to a network switch on the same network segment as the host, or appropriate network drop on the LAN.
Engage the device’s dismount switches by connecting the clip-on dismount switch lock 1000005104:

Connect the power supply (1000004941) to a properly grounded AC socket-outlet.
Make sure the power supply LED turns on and that the device’s General Status LED is blinking yellow to show the device is in the Pre-Activated state.
oDynamo is now ready for testing and development. See the product documentation and the sample code / demonstrations / documentation in the SDKs to do the following:

MTDevice Class Methods

After creating an instance of the MTDevice class in your software project, use the methods described in this section to communicate with MagTek CMS device.

requestDeviceList

This method initiates request to discover devices that are visible to the host using the specified connection interface. The OnDeviceList event will provide information regarding the available devices once the discovery process is completed.

public void requestDeviceList(MTConnectionType connectionType)

Parameters:

Parameter

Description

Return Value: None

This method sets the connection type of the device..

Parameters:

Return Value: None

This method sets the address of the device.

Parameters:

The following table shows the address formats supported by the different connection types:

Return Value: None

This method sets the device ID.

Parameters:

Return Value: None

This method opens the connection to the device.

Parameters: None

Return Value: None

This method closes the connection to the device.

Parameters: None

Return Value: None

This method returns whether the device is connected or not.

Parameters: None

Return Value:

Return true if the device is connected. Otherwise, return false.

This method sends a data string to the device.

Parameters:

Return Value:

0 = Success (MTDevice.SEND_SUCCESS)
9 = Error (MTDevice.SEND_ERROR)
15 = Busy (MTDevice.SEND_BUSY)

This method sends data bytes to the device.

Parameters:

Return Value:

0 = Success (MTDevice.SEND_SUCCESS)
9 = Error (MTDevice.SEND_ERROR)
15 = Busy (MTDevice.SEND_BUSY)

This method sends a MagTek CMS message to the device.

Parameters:

Return Value:

0 = Success (MTDevice.SEND_SUCCESS)
9 = Error (MTDevice.SEND_ERROR)
15 = Busy (MTDevice.SEND_BUSY)

EMV Transaction Flow

Flow Chart

Sample Flow Code: C#

// #1
MTSCRA m_SCRA = new MTSCRA();

// Delegate the MTSCRA Events. m_SCRA.OnDisplayMessageRequest += OnDisplayMessageRequest;
.
// Assign parameters. 
byte timeLimit = 0x3C; 
byte cardType = 0x07; 
byte option = 0x00;
byte[] amount = new 
byte[] { 0x00, 0x00, 0x00, 0x00, 0x15, 0x00 }; 
byte transactionType = 0x00; // Purchase
byte[] cashBack = new byte[] { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }; 
byte[] currencyCode = new byte[] { 0x08, 0x40 };
byte reportingOption = 0x02; // All Status Changes

// Start transaction.
long result = m_SCRA.startTransaction( 
timeLimit,
cardType, 
option, 
amount,
transactionType, 
cashBack, 
currentCode, 
reportingOption);

// #2

protected void OnDisplayMessageRequest(obj sender, byte[] data)
{
    String message;

    // Get the message. 
    if (data != NULL)
    {
        message = System.Text.Encoding.UTF8.GetString(data);
    }


    // A data size of 0 is an instruction to clear the display. 
    if (data.Length == 0)
    {
        // Clear the display.
        }
}

// #3

protected void OnUserSelectionRequest(object sender, byte[] data)
{
    /* data[0]	– selection type 
    data[1]	– timeout
    data[2..n] – remainder contains zero-terminated string items */
    
// display/retrieve user selection.
.
// set status and selection result. 
m_SCRA.setUserSelectionResult(status, selection);

}

// #4

protected void OnARQCReceived(object sender, byte[] data)
{
    /* data[0..1] – ARQC length
    data[2..n] – remainder contains the ARQC TLV object */

    // #4a Forward ARQC to Processor.

    /* An application function to forward the ARQC 
        to a Processor for approval. */
    proccesorResponse = sendARQCToProcesor(data);

    /* No need to send ARQC Response if transaction option 
        had enabled Quick Chip mode. */
    if (isQuickChipEnabled())
    {
    return;
    }


    // #4b Set Acquirer Response.

    // An application function to build Acquirer Response. 
    byte[] response = buildAcquirerResponse(processorResponse);

    // Set Acquirer Response.
    m_SCRA.setAcquirerResponse(response);

}

// #5

protected void OnDisplayMessageRequest(obj sender, byte[] data)
{
    String message;
    
    // Get the message. 
    if (data != NULL)
    {
    message = System.Text.Encoding.UTF8.GetString(data);
    }

    // A data size of 0 is an instruction to clear the display. 
    if (data.Length == 0)
    {
        // Clear the display.
    }
}

Electrical Integration

Overview

This document describes how to use oDynamo safely and securely. Using the device in any way other than the approved methods described in this document invalidates the PCI PTS approval of the device.

Not following the guidelines in this section could damage the device, render it inoperable, and/or violate the conditions of the warranty.

This section provides information and guidelines for designing the electrical aspects of a solution that incorporates oDynamo. MagTek strongly recommends vetting and testing solution designs before finalizing and deploying them, to make sure the design meets all requirements (e.g., functional, legal, security, certification, safety, and so on).

When designing the electrical portions of a solution that incorporates oDynamo, consider the following:

Review section 1.6 About oDynamo Components for an overall introduction to the device’s physical features and what they are called.
Review Appendix A Technical Specifications.
See all the subsections below for options and constraints involving cable design, signals, power, and other aspects of electrical integration. To coordinate with the solution’s mechanical design team about cables, see section 3.6 Cabling.
Consider additional factors that may affect the electrical aspects of the solution design. See section

Review safe handling practices in section 1.9 Handling to make sure the logistical aspects of the solution design meet the device’s handling requirements.
Review recommended installation practices in section 4 Installation. The steps provided in that section depend on the solution design team to customize the steps or fill in solution-specific details before distribution to installation technicians.
Review section 6 Maintenance. When installed in the solution-specific enclosure, the maintenance procedures may require modifications, or the solution may require additional maintenance not covered in the general guidelines provided here.

To guard against ground loops and to protect the device against electrostatic discharge (ESD), it is important that solution designs ground the device correctly. MagTek strongly recommends checking whether the host’s communication ports provide earth ground, and whether the cables carry that ground all the way to the corresponding ports on the device’s board. This will help make an informed decision about proper grounding. There are three paths to provide earth ground to the device; MagTek recommends all solution designs bring in earth ground to the device using one and only one of the possible paths:

Bring in earth ground through pin 10 of the RS-232 and Power Port [J1]
Bring in earth ground through pin 1 and pin 2 of the Alternative Earth Grounding Port [J9]
Bring in earth ground from the host through the USB cable’s metal connector shell to the USB Device Port [J3]

If it is not practical to connect earth ground using only one of the available paths (for example, if the solution uses multiple shielded cables that provide earth ground from the host), then the solution design must ensure that every source of external earth ground is at the same electrical potential, to prevent damaging ground loop currents from occurring. MagTek also recommends using an earth ground isolated power supply (i.e., with the power supply’s negative output not connected to earth ground) like the one shown in Figure 2-1, because a non-isolated supply would connect digital ground to earth ground, defeating the separation of digital ground from earth ground on the device’s PCBs.

Figure 2-1 - Example Earth Ground Isolated 24V Regulated Power Supply

In addition, solutions that incorporate devices with a metal bezel must ground the bezel to the same earth ground potential as the point chosen above. This provides an additional path to protect the device from electrostatic discharge during card insertion and provides additional protection for the device’s electronics. MagTek recommends this earth grounding cable comprise two 18AWG stranded wires twisted together to form a Y cable. Figure 2-2 shows a prototype example of a Y cable that could be included in a standard installation kit.

MagTek recommends using shielded cables to provide noise immunity and to prevent radiated emissions. The device itself has been tested by an FCC lab for Class B radiated susceptibility and has no special shielding requirements. For details, see the FCC information provided at the beginning of this document.

MagTek also recommends that all communication cabling (i.e., USB, Ethernet, RS-232) should be draped together where possible, and isolated from the earth grounding cable to oDynamo and any other unrelated wiring at the installation site that could potentially couple noise into the device and degrade the low-level MagnePrint head signals.

The device has no special requirements for power conditioning or signal conditioning.

oDynamo provides the following connections (see Figure 1-1 - oDynamo Major Components):

·An RS-232 and Power port, which must be connected to a power source and may be connected to an RS-232 host for bidirectional communication. For details, see section 2.5 RS-232 and Power Port.
A USB Device port, which can be connected to a USB-capable host for bidirectional communication. For details, see section 2.6 USB Device Port [J3].
An Ethernet port, which can be connected to an Ethernet-capable host for bidirectional communication. For details, see section 2.7 Ethernet Port [J4].

The RS-232 and Power port must be connected to a power source and may be connected to an RS-232 host for bidirectional communication. It is a Pancon MTSS100-10-CB header designed to mate with a Pancon MAS-CON CE100F22-10-CB connector or equivalent. Pinouts and a schematic excerpt are shown in Figure 2-3 and Table 2-1. Pin 1 is located nearest the front bezel, as shown in Figure 2-4.

Figure 2-3 - oDynamo RS-232 and Power Port J1

Figure 2-4 - oDynamo J1 Pin 1 Location

The Vin and Digital Ground (SG) pins must be connected across the terminals of a power supply. Vin is protected by an internal (non-serviceable) 3A fuse, shown in Figure 2-3.

oDynamo should be powered by a regulated isolated power supply having a fixed output between 9VDC

±5% to 24VDC ±5%, with worst-case output ripple voltage not exceeding 100mV RMS. See section 2.2 Grounding / ESD Protection for additional important information about sourcing an appropriate power supply. For optimal performance, solutions using less than 24VDC must configure the device to disable the card latch, because below 24V the latch behavior is not reliable.

The maximum current draw required from the power supply depends on the selected power supply voltage and the device features used in the solution design. To calculate the maximum required current, use the information in Table 2-2. For example, using a 24V power supply, with card latch function enabled, the maximum total current draw is 417 mA + 170 mA = 587 mA @ 24V.

MagTek recommends 22AWG wires for all signal and power lines. The connector contacts must have a minimum of 15µ" of selective gold plating over nickel. MagTek also recommends filling the pin 7 hole on the cable connector with a Pancon PK100-D polarizing key or equivalent to guarantee the cable will mate with the device in the correct position and orientation.

For oDynamo solutions that use the RS-232 interface, MagTek recommends enclosing all wires in a shielded earth-grounded jacket, and a maximum length for the combination RS-232/power cable of 6 feet. See Figure 2-5 for an example of this RS-232 / Power cable, part number 1000004111.

For oDynamo solutions that do not use RS-232 communication, oDynamo can be powered using a simple power cable using 22AWG wires. See Figure 2-6 for an example power cable, part number 1000003906.

Programmers should see section 8 Developing Host Software for cross-references to programming tools and documentation for communicating through the port and configuring the device.

The factory default communication settings for the RS-232 port are shown in Table 2-3. The host must begin communication with those settings, then can use that connection (or the USB port) to reconfigure the port and switch to the new settings. Programmers should see section 8 Developing Host Software for cross-references to programming tools and documentation for communicating through the port and configuring the device.

The USB Device port J3 can be used to provide bidirectional communication with a USB-capable host. It is a USB 2.0 Type B receptacle designed to mate with a standard USB Type B connector found on the peripheral end of commercially available USB peripheral cables. Pinouts and a schematic excerpt are shown in Figure 2-7.

Figure 2-7 - Pinouts for oDynamo USB Device Port J3

Because the device relies exclusively on RS-232 and Power Port [J1] for power, it draws negligible current from the USB Device Port.

Programmers should see section 8 Developing Host Software for cross-references to programming tools and documentation for communicating through the port.

The Ethernet Port can be used to provide bidirectional communication with an Ethernet-capable host. It is an RJ45 receptacle designed to mate with a standard RJ45 connector found on commercially available Ethernet cables. Pinouts and a schematic excerpt are shown in Figure 2-7.

Figure 2-8 - Pinouts for oDynamo Ethernet Port J4

The RJ45 connector contains integrated magnetics, and supports standard 10/100 speeds. The green LED on the port provides Ethernet Link Status, and the amber LED shows Ethernet Activity.

MagTek recommends using CAT5 cables for the Ethernet connection: Connecting the device to an Ethernet switch or router requires a “straight” Ethernet cable; connecting the device directly to a host’s Ethernet port requires a crossover Ethernet cable.

The Alternative Earth Grounding port J9 can be used in solutions that need a connection for attaching external earth ground (see section 2.2 Grounding / ESD Protection). It is a 2-pin TE Connectivity 3-641126-2 header, compatible with a Pancon MAS-CON CE100F22-2-CB connector or equivalent. If the solution uses J9 , both pins should be connected directly to earth ground.

If the solution design calls for custom cables, use 22 AWG wire or thicker. The contact must have a minimum of 15µ" of selective gold plating over nickel.

Programmer's Manual (Commands)

REGISTERED TO ISO 9001:2015

MagTek I 1710 Apollo Court I Seal Beach, CA 90740 I Phone: (562) 546-6400 I Technical Support: (888) 624-8350 www.magtek.com

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. SOME FEATURES AND FUNCTIONS MAY BE DOCUMENTED, BUT NOT AVAILABLE WITH THE CURRENT RELEASE OF THE PRODUCT. PLEASE CONTACT YOUR MAGTEK REPRESENTATIVE FOR QUESTIONS ABOUT SPECIFIC FEATURES AND FUNCTIONS AND WHEN THEY ARE SCHEDULED TO BECOME AVAILABLE.

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.

AAMVA™ is a trademark of AAMVA.

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

Apple Pay® is a registered trademark to Apple Inc.

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

MasterCard® is a registered trademark and PayPass™ and Tap & Go™ are trademarks of MasterCard International Incorporated.

Visa® and Visa payWave® are registered trademarks of Visa International Service Association.

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.

PCI Security Standards Council® is a registered trademark of the PCI Security Standards Council, LLC. EMVCo™ and EMV™ are trademarks of EMVCo and its licensors.

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

Bluetooth® is a registered trademark of Bluetooth SIG.

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™ is a trademark 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.

CRYPTERA® is a registered trademark of CRYPTERA A/S.

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

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

MagTek warrants that the products sold pursuant to this Agreement will perform in accordance with MagTek’s published specifications. This warranty shall be provided only for a period of one year from the date of the shipment of the product from MagTek (the “Warranty Period”). This warranty shall apply only to the “Buyer” (the original purchaser, unless that entity resells the product as authorized by MagTek, in which event this warranty shall apply only to the first repurchaser).

During the Warranty Period, should this product fail to conform to MagTek’s specifications, MagTek will, at its option, repair or replace this product at no additional charge except as set forth below. Repair parts and replacement products will be furnished on an exchange basis and will be either reconditioned or new. All replaced parts and products become the property of MagTek. This limited warranty does not include service to repair damage to the product resulting from accident, disaster, unreasonable use, misuse, abuse, negligence, or modification of the product not authorized by MagTek. MagTek reserves the right to examine the alleged defective goods to determine whether the warranty is applicable.

Without limiting the generality of the foregoing, MagTek specifically disclaims any liability or warranty for goods resold in other than MagTek’s original packages, and for goods modified, altered, or treated without authorization by MagTek.

Service may be obtained by delivering the product during the warranty period to MagTek (1710 Apollo Court, Seal Beach, CA 90740). If this product is delivered by mail or by an equivalent shipping carrier, the customer agrees to insure the product or assume the risk of loss or damage in transit, to prepay shipping charges to the warranty service location, and to use the original shipping container or equivalent. MagTek will return the product, prepaid, via a three (3) day shipping service. A Return Material Authorization (“RMA”) number must accompany all returns. Buyers may obtain an RMA number by contacting Technical Support at (888) 624-8350.

EACH BUYER UNDERSTANDS THAT THIS MAGTEK PRODUCT IS OFFERED AS IS. MAGTEK MAKES NO OTHER WARRANTY, EXPRESS OR IMPLIED, AND MAGTEK DISCLAIMS ANY WARRANTY OF ANY OTHER KIND, INCLUDING ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IF THIS PRODUCT DOES NOT CONFORM TO MAGTEK’S SPECIFICATIONS, THE SOLE REMEDY SHALL BE REPAIR OR REPLACEMENT AS PROVIDED ABOVE. MAGTEK’S LIABILITY, IF ANY, SHALL IN NO EVENT EXCEED THE TOTAL AMOUNT PAID TO MAGTEK UNDER THIS AGREEMENT. IN NO EVENT WILL MAGTEK BE LIABLE TO THE BUYER FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF, OR INABILITY TO USE, SUCH PRODUCT, EVEN IF MAGTEK HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.

LIMITATION ON LIABILITY

EXCEPT AS PROVIDED IN THE SECTIONS RELATING TO MAGTEK’S LIMITED WARRANTY, MAGTEK’S LIABILITY UNDER THIS AGREEMENT IS LIMITED TO THE CONTRACT PRICE OF THIS PRODUCT.

MAGTEK MAKES NO OTHER WARRANTIES WITH RESPECT TO THE PRODUCT, EXPRESSED OR IMPLIED, EXCEPT AS MAY BE STATED IN THIS AGREEMENT, AND MAGTEK DISCLAIMS ANY IMPLIED WARRANTY, INCLUDING WITHOUT LIMITATION ANY IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

MAGTEK SHALL NOT BE LIABLE FOR CONTINGENT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES TO PERSONS OR PROPERTY. MAGTEK FURTHER LIMITS ITS LIABILITY OF ANY KIND WITH RESPECT TO THE PRODUCT, INCLUDING ANY NEGLIGENCE ON ITS PART, TO THE CONTRACT PRICE FOR THE GOODS.

MAGTEK’S SOLE LIABILITY AND BUYER’S EXCLUSIVE REMEDIES ARE STATED IN THIS SECTION AND IN THE SECTION RELATING TO MAGTEK’S LIMITED WARRANTY.

This device complies with Part 15 of the FCC Rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) This device must accept any interference received, including interference that may cause undesired operation.

Note: This equipment has been tested and found to comply with the limits for a Class B digital device, pursuant to part 15 of the FCC Rules. These limits are designed to provide reasonable protection against harmful interference in a residential installation. This equipment generates, uses and can radiate radio frequency energy and, if not installed and used in accordance with the instructions, may cause harmful interference to radio communications. However, there is no guarantee that interference will not occur in a particular installation. If this equipment does cause harmful interference to radio or television reception, which can be determined by turning the equipment off and on, the user is encouraged to try to correct the interference by one or more of the following measures:

· Reorient or relocate the receiving antenna.

· Increase the separation between the equipment and receiver.

· Connect the equipment into an outlet on a circuit different from that to which the receiver is connected.

· Consult the dealer or an experienced radio/TV technician for help.

Caution: Any changes or modifications not expressly approved by the party responsible for compliance could void the user’s authority to operate this equipment. RF Exposure: A distance of 20 cm shall be maintained between the antenna and users, and the transmitter may not be co-located with any other transmitter or antenna.

This product is recognized per Underwriter Laboratories and Canadian Underwriter Laboratories 1950.

This digital apparatus does not exceed the Class B limits for radio noise from digital apparatus set out in the Radio Interference Regulations of the Canadian Department of Communications.

Le présent appareil numérique n’émet pas de bruits radioélectriques dépassant les limites applicables aux appareils numériques de la classe B prescrites dans le Réglement sur le brouillage radioélectrique édicté par le ministère des Communications du Canada.

This Class B digital apparatus complies with Canadian ICES-003.

Cet appareil numérique de la classe B est conformé à la norme NMB-003 du Canada.

Testing for compliance with CE requirements was performed by an independent laboratory. The unit under test was found compliant with standards established for Class B devices.

This product is recognized per UL 60950-1, 2nd Edition, 2011-12-19 (Information Technology Equipment - Safety - Part 1: General Requirements), CSA C22.2 No. 60950-1-07, 2nd Edition, 2011-12 (Information Technology Equipment - Safety - Part 1: General Requirements).

When ordered as RoHS compliant, this product meets the Electrical and Electronic Equipment (EEE) Reduction of Hazardous Substances (RoHS) Directive (EU) 2015/863 amending Annex II to Directive 2011/65/EU. The marking is clearly recognizable, either as written words like “Pb-free,” “lead-free,” or as another clear symbol ( ).

TERMS, CONDITIONS, AND RESTRICTIONS

MagTek, Incorporated (the "Licensor") owns and has the right to distribute the described software and documentation, collectively referred to as the "Software."

LIMITED WARRANTY: Licensor warrants to the Licensee that the disk(s) or other media on which the Software is recorded are free from defects in material or workmanship under normal use.

Because of the diversity of conditions and hardware under which the Software may be used, Licensor does not warrant that the Software will meet Licensee specifications or that the operation of the Software will be uninterrupted or free of errors.

the event of a defect in material or workmanship is expressly limited to replacement of the Software disk(s) if applicable.

ACKNOWLEDGMENT: LICENSEE ACKNOWLEDGES THAT LICENSEE HAS READ THIS AGREEMENT, UNDERSTANDS ALL OF ITS TERMS, CONDITIONS, AND RESTRICTIONS, AND AGREES TO BE BOUND BY THEM. LICENSEE ALSO AGREES THAT THIS AGREEMENT SUPERSEDES ANY AND ALL VERBAL AND WRITTEN COMMUNICATIONS BETWEEN LICENSOR AND LICENSEE OR THEIR ASSIGNS RELATING TO THE SUBJECT MATTER OF THIS AGREEMENT.

QUESTIONS REGARDING THIS AGREEMENT SHOULD BE ADDRESSED IN WRITING TO MAGTEK, INCORPORATED, ATTENTION: CUSTOMER SUPPORT, AT THE ADDRESS LISTED IN THIS DOCUMENT, OR E-MAILED TO

DEMO SOFTWARE / SAMPLE CODE: Unless otherwise stated, all demo software and sample code are to be used by Licensee for demonstration purposes only and MAY NOT BE incorporated into any production or live environment. The PIN Pad sample implementation is for software PIN Pad test purposes only and is not PCI compliant. To meet PCI compliance in production or live environments, a third-party PCI compliant component (hardware or software-based) must be used.

Application Group 0x02 - Authentication Messages

Command 0x02::0x0A - EPP Pairing Certificate Exchange

This command starts the EPP pairing process on oDynamo using the results from the START_EXCHANGE command on the Encrypting PIN Pad (EPP). The host should use the oDynamo response as the parameters for the next EPP command GENERATE_KEK. For details about the pairing flow, see Appendix G How to Pair With a Cryptera Encrypting PIN Pad.

Table - Message Structure for Command 0x02::0x0A - EPP Pairing Certificate Exchange

Tag

Len

Value(s) / Description

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x02::0x0B - Get Challenge

This command directs the device to send challenge data to the host, which the host can then use to perform a specific sensitive operation / modify a specific type of device setting. Information about how the host should pass the required challenge data to the device is included in the documentation for all commands that use this security mechanism.

Upon providing the challenge to the host, the device sets an internal 5-minute countdown timer. When the time limit expires, the device will no longer accept the challenge. This binding of the command to a specific time period allows the device to detect and reject commands that have been captured/intercepted at one point in time and replayed later.

Command 0x02::0x0C - EPP Pairing Load KEK

This command is the second step in the EPP pairing process after Command 0x02::0x0A - EPP Pairing Certificate Exchange has completed successfully. This step loads a temporary key from the EPP that will be used during the third step of pairing (Command 0x02::0x0D - EPP Pairing Load Derivation Key). For details about the pairing flow, see Appendix G How to Pair With a Cryptera Encrypting PIN Pad.

Command 0x02::0x0D - EPP Pairing Load Derivation Key

This command is used for the third and final step of the EPP pairing process. It securely loads a key shared with the paired EPP. This key is used to derive keys that protect the PIN and PAN sent to/from the EPP.. For details about the pairing flow, see Appendix G How to Pair With a Cryptera Encrypting PIN Pad.

Command 0x02::0x0E - Get Key / Certificate Information

The host uses this command to get key or certificate information from the device.

If an error occurs, the device terminates the command and reports the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3).

If no error occurs, the device responds by immediately sending two or more instances of Notification 0x01::0x10 - Big Block Device Data, which the host should concatenate, then interpret as follows:

Command 0x02::0x58 - Request Device Certificates

The host uses this command to request the Device Certificate, which the host would generally pass to Magensa web services that generate signed byte sequences for remote configuration commands.

The host should then wait (up to 90 seconds in some cases) for the device to respond synchronously with the requested data.

Application Group 0x01 - General Messages

Command 0x01::0x02 - Clear Transaction Data

The host uses this command to direct the device to clear all transaction data, including account data, encrypted PIN block, PAN, and amount, and return to the idle state.

Table - Message Structure for Command 0x01::0x02 - Clear Transaction Data

Tag

Len

Value(s) / Description

Command 0x01::0xFF - Device Reset

The host uses this command to direct the device to reset.

Notification 0x01::0xFF - Device Reset

The device sends this notification to the host to notify the host that it is about to perform a periodic automatic device reset, which it initiates after 23 hours of continuous operation to fulfill PCI requirements. MagTek recommends the host software pre-empt these automatic resets by initiating resets in advance of the 23 hour schedule, at times that are least disruptive to the solution design.

Command 0x01::0x04 - Get Device Status

The host uses this command to request the device status, such as Session State, Device State, and Status.

Notification 0x01::0x04 - Send Device Status

In addition to sending device status in response to Command 0x01::0x04 - Get Device Status, the device will automatically send the same data when the device powers up, restarts, or changes state.

Command 0x01::0x10 - Send Big Block Command

The host uses this command to send command messages to the device as a sequence of packets. The host should follow this sequence:

In local memory, compose the entire command message as documented by the desired command’s usage table (for example, Command 0x01::0x17 - Update Firmware).
Calculate the length of the fully-composed command message. Divide the fully-composed command message into packets that are shorter than the connection type’s maximum packet size.
- When using the USB connection, the maximum packet size is 0x3F bytes.

For every packet the host sends, if an error occurs (such as an out of order packet), the device will terminate the command, report the error using an ACK Response containing the result code, and will stop expecting to receive subsequent big block packets. The host should stop sending them. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3).

If no error occurs, the device responds to every packet as follows:

Notification 0x01::0x10 - Big Block Device Data

The device uses this notification to send data to the host as a sequence of packets. The host should process this notification as follows:

The host may receive this notification completely unsolicited or in response to a command (all commands that operate in this way say so in the command documentation). If the host has sent such a command to the device, it should start a timeout counter and begin listening for incoming notifications.
Parse the first incoming notification, which should be identified as Packet 0000, according to Table 4-32 below. Use the value of Total Message Length to allocate buffer space to begin concatenating all subsequent packets, which together form the complete message.
Continue receiving packets 0001 through nnnn, parsing them according to Table 4-33 below, concatenating the Packet Data from all notifications in order and adding the length of Packet Data in each packet, until the length of concatenated message data equals the Total Message Length.

Command 0x01::0x17 - Update Firmware

The host uses this command to update the device’s firmware. The host should first compose the entire message for this command, then transmit the entire message to the device in packets using Command 0x01::0x10 - Send Big Block Command.

After the device receives the final packet of this command, the device will validate the firmware image, and if the validation passes, it will commit the image to the selected firmware storage location. In all cases, the device will also send an additional response:

Although this command works on all connection types, for speed reasons, MagTek recommends using an

Ethernet or USB connection to upgrade the device’s firmware.

Notification 0x01::0x40 - Card Detected / Identified / Removed

The device uses this notification to signal to the host that a cardholder has inserted or removed a card, and to identify the type of card. Upon insertion or removal of a card, the device sends this notification to provide a Card Present Indication (CPI). After the device finishes identifying the type of card, it sends this notification again to provide an ICC Present Indication (IPI). When the CPI indicates a card is present and the IPI reports it is a chip card, the host is free to begin an EMV transaction, or in the case of magnetic stripe cards, to prompt the cardholder to remove the card to swipe on exit.

Command 0x01::0x50 - Subscribe to Notifications

The host uses this command to specify which notifications the device should send to it (for example, Notification 0x01::0xFF - Device Reset). By default, the device does not send any notifications to the host.

Application Group 0x00 - Device Information Messages

This section documents the full set of messages that can be exchanged between the device and the host.

Command 0x00:0x10 - Get Product ID

The host uses this command to get the device’s product ID.

Table 4-1 - Message Structure for Command 0x00:0x10 - Get Product ID

Tag

Len

Command 0x00::0x12 - Get Capability String

The host uses this command to get the device’s Capability String.

Command 0x00::0x13 - Get Manufacturer

The host uses this command to get the device manufacturer.

Command 0x00::0x14 - Get Product Name

The host uses this command to get the device’s product name.

Command 0x00::0x15 - Get Secure Tracking Number

The host uses this command to get the device’s secure tracking number.

Command 0x00::0x16 - Get Firmware Version

The host uses this command to get the device’s firmware version.

Command 0x00::0x18 - Get Network Information (Ethernet Only)

The host uses this command to get information about the device’s network connection.

Command 0x00::0x23 - Get Boot Loader Version

The host uses this command to get the device’s boot loader version.

Command 0x00::0x27 - Get CT-L2 Version

The host uses this command to get the device’s EMV L2 version, if any.

Command 0x00::0x28 - Get Serial Number

The host uses this command to get the device’s serial number.

Messages, Commands, Responses, and Notifications

About Messages, Commands, Responses, and Notifications

The host and the device communicate with each other by exchanging blocks of data called Messages, which can be either Commands, Responses to commands, or Notifications. For example, the host may send a command to the device to change a configuration setting, and the device may send a response that the command was successful; when a cardholder inserts a card, the device may send a notification to the host that a cardholder has initiated a transaction.

The device can only service one command at a time, and sends each response within a pre-determined finite amount of time after receiving the command. After sending a command, the host must wait until the device returns a response before sending another command.

The device sends notifications to the host if the device’s state changes or if an external event occurs, such as a cardholder inserting a card. The device can send a notification at any time, and does not expect a response or any specific action from the host.

Although the wrappers for messages may be different depending on the connection type the host and device are using to communicate, the message payload format and contents are exactly the same. For example, apart from the wrapper differences defined in section 3 Connection Types, a message sent over an RS-232 connection will be exactly the same as a message sent over a USB-HID connection.

About Big Block Commands and Notifications

There are some cases where data transmitted from the host to the device or from the device to the host requires special treatment. For example, some commands require the host or the device to transmit large blocks of data that exceed the maximum packet size of the chosen data transport layer; other commands require transmitted data to be encrypted and/or encoded, fully received, then decrypted and/or decoded as a single piece. For commands, responses, and notifications that require this special treatment, the usage information in this document indicates that the data should be sent as Big Block Data.

For commands from the host to the device that require big block messages, either because the message exceeds the current connection’s maximum packet size or because the message requires special treatment such as encryption, the host should first compose the full command message in local memory according to the usage table of the desired command, then transmit the message using Command 0x01::0x10 - Send Big Block Command. See that command’s documentation for details.

The host should always anticipate the device could send responses or notifications that exceed the current connection’s maximum packet size, and that the device will transmit them using multiple instances of Notification 0x01::0x10 - Big Block Device Data. The host must count all instances and concatenate them to form a complete message. See that notification’s documentation for usage details.

ACK Response

After receiving a command that does not require the device to return data, the device sends a simple response to the host to acknowledge (“ACK”) the command. The response includes the Message Type Data Object (Tag C0) indicating it is a response, the Application ID Data Object (Tag C1) and the Command ID Data Object (Tag C2) identical to the command the device is acknowledging, and a Result Code Data Object (Tag C3) reporting the results of the command.

Table 2-1 shows an example of an ACK Response from the device after the host has sent Command 0x01::0x02 - Clear Transaction Data, where the device is reporting “OK / Done.”

Table 2-2 shows an example of an ACK Response from the device where the host has sent a command using an invalid message format (protocol violation) and the message is “Bad Message Format.”

Messages exchanged between the host and the device consist of a required header, which consists of three or four specific tag-length-value (TLV) data objects, plus in many cases a fifth top-level TLV data object containing a data payload. Table 2-3 shows the header TLV data objects in the order the host should use when sending messages, and should expect when receiving messages. Details about each of the top-level data objects are provided in the following sections, and every command and notification in section 4 Command Set provides concrete usage tables that show byte-by-byte how the host software should compose or interpret the message.

The TLV data objects are constructed using the Basic Encoding Rules (BER) for the industry standard format defined in ITU-T X.680|ISO/IEC 8824-1 and ITU-T X.690|ISO/IEC 8825-1. These standards are also the basis of EMV Integrated Circuit Card Specifications for Payment Systems 4.3, Part IV, Annex B Rules for BER-TLV Data Objects, so the latter can serve as a useful point of reference, especially for programmers who are familiar with the operation of chip cards. Summarizing those specifications, each TLV data object follows these basic rules:

The Tag portion is a single byte that identifies the TLV data object [such as 0xC0 in the case of

Message Type Data Object (Tag C0)].

· The Length portion is calculated as the total length of the Data portion that follows it. Lengths can be either one byte long from 0x00 to 0x7F, or multiple bytes starting with 0x80 or higher, in which case the lower 7 bits of the first byte specify how many subsequent bytes will indicate the length of the Data portion that follows. For example, in the case of Length 8201C3, 0x82 is greater than 0x7F, and the lower 7 bits equal 0x02, so the next 2 bytes 0x01C3 give the total length of the data block, 451 bytes.

The Data portion is the actual payload of the TLV data object.

Message Type Data Object (Tag C0)

The Message Type TLV data object specifies the message type: Either Command, Response, or Notification. Table 2-4 formally defines the TLV data object.

For device operations that take a long time or an indefinite amount of time, the host usually sends a command that initiates the operation, and the device returns an ACK Response to indicate it has started the operation. When the operation completes, the device sends a Notification to the host.

Application ID Data Object (Tag C1)

The Application ID TLV data object specifies which Application ID the message belongs to. Each functional subsystem of the device has a unique Application ID, and contains a defined message set pertaining to that subsystem. For example, a device might contain an MSR application for its magnetic stripe reader and an EMV L2 Contact application for interacting with contact chip cards. Table 2-5 formally defines the TLV data object.

Command ID Data Object (Tag C2)

The Command ID TLV data object has a different meaning for each of the possible values in the

Message Type Data Object (Tag C0):

For Commands, the Command ID defines the operation to be carried out by the device.
For Responses, the Command ID refers to the operation that was carried out by the device, and always contains the same value as the Command ID Data Object (Tag C2) from the originating command.
For Notifications, the Command ID specifies the event that has occurred in the device.

Table 2-6 formally defines the TLV data object.

Result Code Data Object (Tag C3)

The Result Code TLV data object has different meaning for each of the possible values in the Message Type Data Object (Tag C0):

For Commands, the host should not send this data object to the device.
For Responses, the result code reports the result of the operation that was carried out by the device.
For Notifications, the result code reports the result of the event that has occurred in the device.

The Table below formally defines the TLV data object.

Data Field Data Object (Tag C4 or E0)

If there is additional data associated with the message, it is contained in the Data Field TLV data object. The length of this field is equal to the length of the whole message minus the length of the message header [Message Type Data Object (Tag C0), Application ID Data Object (Tag C1), Command ID Data Object (Tag C2), and Result Code Data Object (Tag C3)].

For Primitive data, the Data Field data object is identified with Tag C4. C4 is only used when the data portion of the message only contains raw data and will not include any embedded TLV data objects.

Table 2-8 formally defines the C4 data object.

For Constructed data, the Data Field data object is identified with Tag E0. E0 is used if the data portion of the message wraps additional TLV data objects. The TLV data objects that can be embedded in the Data Field are detailed in section 2.5 Data Field, or in the documentation in section 4 Command Set for messages that use them.

The data inside an E0 (Constructed type) Data Field is also encoded using the BER TLV data object rules explained in section 2.4 Message Format. It becomes very important pay careful attention to the length of every data object to encode/decode correctly. Programmers way wish to recursively construct those data objects by “nesting” from the inside out.

Table 2-9 formally defines the E0 data object.

Linux Style Date-Time Stamps

Some commands embed Linux-style date-time stamps in their responses. To decode the time embedded in these commands, use a Linux shell to enter a command sequence similar to this:

This section specifies the data objects that can be embedded in the Data Field Data Object (Tag C4 or E0) when it contains Constructed data tagged with type E0.

Primitive Data Types

Throughout this document, the tables that describe tag-length-value (TLV) data structures use the following primitive data types:

A = Alphabetic (string, no numbers).
AN = Alphanumeric (string).
B = Binary value, which includes bit combinations (“OR” types).

Data Object F1 - Device Status

The device uses a data object identified by tag F1 to send the device status:

Hardware errors will cause the device to not respond to any command, except for device status inquiry.

Data Object F4 - Magnetic Stripe Reader Card Data

The device uses TLV Data Object F4 wrapped in Data Object F9 - MACed Message to transmit magnetic stripe data to the host. To find commands, responses, and notifications that use this data object, search this documentation for this section name.

The parent data object F9 contains additional tags alongside data object F4 that indicate the conditions and events that produced the magnetic stripe data:

POS Entry Mode (9F39) is included by the device automatically every time the host calls Command 0x04::0x12 - Request MSR Card Data, and is included in Notification 0x07::0x83 - EMV L2 ARQC Message if the host has configured the device to include it by adding 9F39 to data object list DFDF02 in EMV Contact Terminal Settings and Defaults. It contains one of the following based on the card’s service code:
- 0x80 = The card data came from a chip card (service code 2xx or 6xx).
- 0x90 = The card data came from a magnetic stripe card.

If the card’s PAN does not match any entry in the device’s configured Account Data whitelist (see Command 0x03::0x80 - Read PAN Whitelist / Account Data Whitelist), data object F4 contains the tags shown in Table 2-13. If the card is in the device’s configured Account Data whitelist, data object F4 contains the tags shown in Table 2-14.

TLV data object F8 is an encrypted data object wrapping the encrypted track data and MagnePrint Data nested within data object DFDF59, plus supporting information as clear text in other tags.

The device encrypts the value inside data object DFDF59 using the current MSR DUKPT working key used in the relevant transaction. The device uses either the PIN variant or data variant of the key, depending on the current MSR Encryption Variant setting (see Command 0x03::0x72 - Get Device Configuration).

As a requirement for using the DUKPT TDES encryption algorithm, the device pads it so the length of its value is a multiple of 8 bytes. The device uses tag DFDF58 to report how many bytes of tag DFDF59 are padding. DFDF59 contains the following after the host decrypts it:

The MAC value is calculated based on the padded <F9 TLV for MACed MSR data> (the MACing operation requires MACed data length to be multiple of 8). However, after MACing calculation, the padding bytes should not be included in the F9 TLV. The receiving end is responsible for padding the F9 TLV when verifying the corresponding MAC. The MAC is stored in the DFDF6C TLV. <E0 TLV len> is the total of the <F9 TLV for MACed MSR data> and <DFDF6C TLV for MAC value>.

Encryption Type data object DFDF51 uses one byte to represent the key scheme, encryption algorithm and variant. Table 2-15 lists the possible values.

Data Object F8 - Encrypted Data

Data Object F9 - MACed Message

The device only uses DFDF6C as the MAC container when it sends this data object in a response to

Command 0x04::0x12 - Request MSR Card Data.

To calculate the F9 MAC to authenticate the message, include the F9 tag, length, and contents, and pad it with zeroes to make overall length a multiple of 8. Use the DUKPT MAC variant of the transaction key (DUKPT MAC variant constant = 0000 0000 0000 FF00 0000 0000 0000 FF00) with the CBC-MAC algorithm, and use the first 4 bytes of the 8.

Data object DFDF0B contains three bytes that indicate the nature of the data included in the FA container within Data Object F9 - MACed Message.

Byte 0 is data type:

0x00 = Reserved

0x01 = EMV Contact L2 Data

Byte 1 is encryption type 0x00 = Data is Encrypted

0x01 = Data is Clear Text (account number found in device whitelist)

Byte 2 is Reserved.

0x00 = Reserved

0x01 = Set to this value

Application Group 0x03 - Device Configuration Messages

The host uses commands in this application to get and set the configuration of the device. Every configuration setting has a command to get the setting and a command to change the setting. When using get commands, the host should not include Data Field Data Object (Tag C4 or E0). The device responds with the current configuration values in Data Field Data Object (Tag C4 or E0).

Command 0x03::0x00 - Card Latch Control

The host uses this command to lock or unlock the card latch. The host can choose to lock the card during EMV transactions to limit the possibility of the cardholder prematurely removing the card. The lock can also be enabled while the card is out of the system to block cardholders from inserting a card.

Table - Message Structure for Command 0x03::0x00 - Card Latch Control

Tag

Command 0x03::0x60 - Set/Get Ethernet Configuration (Ethernet Only)

The host uses this command and its subcommands to set and get configuration settings for the device’s Ethernet connection.

To change the device’s Ethernet configuration, the host should follow these steps:

Call the command with the Set Ethernet IP Address Mode subcommand to select DHCP or Static.
If using Static, call the command with each Set subcommand for all remaining settings. If the host selected DHCP, the device ignores the remaining settings and further Set calls are unnecessary.
Call the command again with the Apply Changes subcommand. The device will begin using the new configuration immediately, and the settings will persist through subsequent power cycles and restarts.

Command 0x03::0x70 - Set Chip Card Support

The host uses this command to enable or disable support for chip cards. When disabled, the device will ignore chip cards and will only read magnetic stripe cards. When enabled, the device checks whether an inserted card has an EMV chip, and will try to communicate with the chip and notify the host first, before falling back to reading the magnetic stripe. This changes the value of tag DFDFDF12 in the device configuration (see Command 0x03::0x72 - Get Device Configuration).

Command 0x03::0x72 - Get Device Configuration

The host uses this command to get the device’s configuration. If the host uses the Data Field Data Object (Tag C4 or E0) to specify a single configuration setting to retrieve, the device returns that setting in the format shown in Table 4-59. If the host omits the Data Field Data Object (Tag C4 or E0), the device returns a list of all configuration values as shown in Table 4-60.

Command 0x03::0x80 - Read PAN Whitelist / Account Data Whitelist

The host uses this command to read the device’s PAN Whitelist or Account Data Whitelist, which are loaded securely by the manufacturer and allow the device to relax security for cards that match the criteria specified in the lists.

The first 6 digits of a card’s Primary Account Number (PAN) are called the Issuer Identification Number (IIN), previously known as bank identification number (BIN). The IIN identifies the institution that issued the card to the cardholder. Before the device transmits certain types of card data to the host, it compares the card’s IIN to the rules stored in the two whitelist tables, and changes the data it sends accordingly:

The device’s PAN Whitelist affects the behavior of Command 0x05::0x01 - Read PAN. This whitelist is specifically designed to support solutions that use an external Encrypting PIN Pad (EPP), where the host would typically need an unencrypted PAN to create an encrypted PIN block.
The device’s Account Data Whitelist affects the behavior of MSR transactions in Notification 0x04::0x11 - MSR Card Data Available, Command 0x04::0x12 - Request MSR Card Data, and the corresponding Data Object F4 - Magnetic Stripe Reader Card Data.
The device’s Account Data Whitelist affects the behavior of EMV transactions in Notification 0x07::0x83 - EMV L2 ARQC Message, Notification 0x07::0x84 - EMV L2 Transaction Result, and the corresponding Transaction Result Message - Batch Data Format (EMV Only).

Appendix H Licenses and Copyright Disclosures

The information in this section requires no action on the part of the consumer, and is included to comply with various disclosure requirements governing the use of components used in the development of this device’s firmware.

GNU GENERAL PUBLIC LICENSE

From https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary.

To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. The precise terms and conditions for copying, distribution and modification follow.

GNU GENERAL PUBLIC LICENSE

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

<one line to give the program's name and a brief idea of what it does.> Copyright (C) <year> <name of author>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) year name of author

Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.

This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker.

<signature of Ty Coon>, 1 April 1989 Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License.

Application Group 0x07 - EMV L2 Contact Messages (Chip Card L2 Mode Only) - 1 - 15

About EMV L2 Transaction Flows

The general flow of an EMV L2 transaction is as follows (bear in mind the device does not have a display, so in these steps the host drives the user interface for both the terminal operator / cashier and for the cardholder / customer):

The terminal operator / cashier performs steps external to the transaction, generally resulting in a total balance owed, and directs the host software to initiate a transaction. If the device supports Quick Chip and the system is designed to use that feature, the host may skip this step and instead start the transaction with a default amount as a placeholder, which is generally a pre-determined non-zero value that is consistent with the system’s payment processing environment. Further differences pertaining to Quick Chip transactions are included in the steps below.
The device must have already used Command 0x01::0x50 - Subscribe to Notifications to subscribe to at least notifications from Application Group 0x01 - General Messages, Application Group 0x04 - Magnetic Stripe Reader (MSR) Messages, and Application Group 0x07 - EMV L2 Contact Messages (Chip Card L2 Mode Only).
The cardholder inserts their card into the device. In response, the device sends Notification 0x01::0x40 - Card Detected / Identified / Removed to report Card was not present and is now present / Card is a chip card (ICC card) indicating there is a chip card ready to begin a transaction.
The host software may optionally call Command 0x03::0x00 - Card Latch Control to hold the card in the slot.
The host software sends the device Command 0x07::0x00 - EMV L2 Start Transaction.
From this point until the host sends the transaction results to the transaction processor, the host may cancel the EMV transaction by sending Command 0x07::0x04 - EMV L2 Cancel Transaction and the device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Host Canceled Transaction / Transaction error.
The device attempts to communicate with a chip on the inserted card.
- If the device is unable to power up the card:
  - The device responds with error code 0013 and terminates the transaction.
At this point the device was able to power-up the card and found mutually supported applications. The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Selecting the application.
The device sends Notification 0x07::0x81 - EMV L2 Display Message Request with the message Please Wait.
The device negotiates with the card to determine which payment applications are available. If the card holds only one mutually supported payment application and the host did not enable Enhanced App Selection in the Transaction Options parameter, the device uses that application. Otherwise:
- The device sends Notification 0x07::0x82 - EMV L2 User Selection Request to prompt the cardholder to Select Application with a list of available applications, followed by Notification 0x07::0x8A - EMV L2 Transaction Status to report Waiting for User Response / Waiting for User Application Selection.
- After the cardholder selects an application, the host passes the selection to the device by sending Command 0x07::0x02 - EMV L2 User Selection Result.
The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Initiating Application.
If the card’s selected application reports to the device that the cardholder should select a language, the device sends Notification 0x07::0x82 - EMV L2 User Selection Request to prompt the cardholder to Select Language with a list of available languages, followed by Notification 0x07::0x8A - EMV L2 Transaction Status to report event Waiting for User Response / Waiting for user language selection. After the cardholder selects a language, the host passes the selection to the device by sending Command 0x07::0x02 - EMV L2 User Selection Result.
The device continues communicating with the card and sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Reading Application Data. If an error or other type of failure occurs during this step, the device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Terminated / Transaction Error, followed by Notification 0x07::0x81 - EMV L2 Display Message Request with the message Transaction Terminated, followed by Notification 0x07::0x84 - EMV L2 Transaction Result.
If the host used the Transaction Options parameter to specify either Continue Mode Enabled, Wait or Continue Mode Enabled, Continue when it called Command 0x07::0x00 - EMV L2 Start Transaction, the device sends Notification 0x07::0x8C - EMV L2 Continue Notification with data from the card application read in the previous step. If the host specified Continue Mode Enabled, Wait, the device pauses the transaction and sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Waiting for User Response / Waiting for Continue. The host must send Command 0x07::0x13 - EMV L2 Continue Action to direct the device to proceed or cancel before the 60 seconds timeout occurs, otherwise the device terminates the transaction.
Depending on the capabilities of the card and the device, the device authenticates the card data using SDA, DDA, or CDA. The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Offline data authentication.
The steps from here through Card Action Analysis below are collectively referred to as the Risk Management process:
- The device checks to make sure the selected application is valid for the transaction, and is compatible with the device (such as application version number, application usage control, and application effective / expiration date), and sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Process Restrictions.
- The device uses the cardholder verification related data in the card to determine which cardholder verification method (CVMs) to use. The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Cardholder Verification.
The device performs terminal risk management procedures, which involves floor limit checking, velocity checking, and periodically forcing online authorization to protect against fraud, and sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Terminal Risk Management.
The device analyzes the results of the previous steps and sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Terminal Action Analysis.
The device rolls up the results of the previous Risk Management process:
- If the Risk Management process encounters an error or determines the transaction or payment method fails to meet required criteria, the device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Terminated / Transaction Error, followed by Notification 0x07::0x81 - EMV L2 Display Message Request with the message TRANSACTION TERMINATED , followed by Notification 0x07::0x84 - EMV L2 Transaction Result, and terminates the transaction.
- If the Risk Management process determines the transaction is too risky to approve, the device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Terminated / Transaction Error, followed by Notification 0x07::0x84 - EMV L2 Transaction Result, followed by Notification 0x07::0x81 - EMV L2 Display Message Request with message Declined to notify the cardholder, and terminates the transaction.
The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Generating First Application Cryptogram, followed by Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Card Action Analysis.
If the device is NOT configured as Online-Only Terminal Type [see Tag 9F35 in EMV Contact Terminal Settings and Defaults] and the Risk Management processes determined the transaction is OK to perform offline, the device reports the transaction result to the host as follows:
- The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Transaction Complete.
- The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Terminated and either Transaction Approved or Transaction Declined, then sends Notification 0x07::0x81 - EMV L2 Display Message Request with message Approved or Declined to notify the cardholder.
If the device is configured as an Online Only Terminal Type [see Tag 9F35 in EMV Contact Terminal Settings and Defaults] or the Risk Management processes determined the transaction must be performed online, the device reports the transaction result to the host as follows:
- The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Online Processing, followed by Notification 0x07::0x83 - EMV L2 ARQC Message.
- The next event depends on whether the device supports the Contact Quick Chip feature and whether the host specified Quick Chip as an Option when it started the transaction:
If Quick Chip operation is NOT supported or is not in effect:
- The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Waiting for Online Processing Response.
- The host processes the ARQC Message data and uses it to coordinate with the transaction processor to receive an ARPC Response, which it processes and sends to the device using Command 0x07::0x03 - EMV L2 Online Processing Result / Acquirer Response. Alternatively, the host may implement host-driven Quick Chip by instead constructing its own preliminary ARPC Response with tag 8A set to ‘Z3’ and sending it to the device immediately, without waiting for a transaction processor response. The device responds by sending Notification 0x07::0x81 - EMV L2 Display Message Request to the host with message Declined and ending the transaction. The host should suppress this message and take over the remainder of the transaction, including notifying the cardholder to remove the card, determining the final transaction amount, coordinating with the transaction processor to retrieve a final transaction result, and interacting with the cardholder.

Command 0x07::0x00 - EMV L2 Start Transaction

The host uses this command to start an EMV L2 transaction.

The host can only select the Quick Chip Mode transaction option for online transactions. This option significantly reduces the time the chip card needs to stay in the device. In this mode, the cardholder can remove the chip card before the transaction processor returns the Authorization Response Cryptogram (ARPC) to the host.

When Quick Chip Mode is enabled, the device requests data for an online authorization from the card. After the card responds with an online authorization request (ARQC), oDynamo sends the Authorization Response Code (tag 8A) with a declined status (Z3) to the card. The host software should complete the EMV processing as a deferred authorization, and prompt the card holder to remove the card. The host software should then proceed with requesting authorization from the transaction processor, and wait for the online response to approve or deny the transaction. For more details, see Visa’s Quick Chip for EMV and qVSDC - Specification Version 2.0.

Command 0x07::0x02 - EMV L2 User Selection Result

The host uses this command to report the cardholder’s or operator’s selection in response to the device’s Notification 0x07::0x82 - EMV L2 User Selection Request. In response to each possible selection, the device will behave according to EMV rules.

Command 0x07::0x03 - EMV L2 Online Processing Result / Acquirer Response

The host uses this command to inform the device of the result of online processing. It will contain ARPC, Script 1, and Script 2 data.

Command 0x07::0x04 - EMV L2 Cancel Transaction

The host uses this command to cancel an EMV transaction while the device is waiting for the cardholder to insert a card.

Command 0x07::0x05 - EMV L2 Modify Contact Terminal Configuration

The host uses this command to modify EMV Contact Terminal configuration data. Descriptions of the tags can be found in EMV Integrated Circuit Card Specifications for Payment Systems v4.3 .

Command 0x07::0x06 - EMV L2 Get Contact Terminal Configuration

The host uses this command to read EMV Contact Terminal configuration data.

Command 0x07::0x07 - EMV L2 Modify Contact Application Configuration

The host uses this command to modify EMV contact application configuration data. Descriptions of the tags can be found in EMV Integrated Circuit Card Specifications for Payment Systems v4.3 .

Command 0x07::0x08 - EMV L2 Get Contact Application Configuration

The host uses this command to read back EMV contact application configuration data.

Command 0x07::0x09 - EMV L2 Modify CA Public Key

The host uses this command to modify EMV CA Public Key data.

Command 0x07::0x0A - EMV L2 Get CA Public Key

The host uses this command to read EMV Certificate Authority Public Key data.

Command 0x07::0x0B - EMV L2 Get Kernel Base Checksum

The host uses this command to read EMV L2 Kernel Checksum.

Command 0x07:0x0D - Get Date Time

The host uses this command to read the device’s Real Time Clock (RTC).

Command 0x07::0x0E - EMV L2 Commit Configuration

The host uses this command to commit changes after using Command 0x07::0x10 - Modify EMV L2 Terminal Capabilities Configuration.

Command 0x07::0x10 - Modify EMV L2 Terminal Capabilities Configuration

The host uses this command to select EMV Terminal Capabilities Configuration. The EMV terminal settings affected by this command can not be set directly; they must be set to one of a specified set of certified values. Descriptions of the tags and their values can be found in EMV Integrated Circuit Card Specifications for Payment Systems v4.3. For full descriptions of each configuration, see the device’s EMVCo Letter of Approval for Contact Terminal Level 2 [see Appendix D EMV Configurations (EMV Only)].

After calling this command, the host should call Command 0x07::0x0E - EMV L2 Commit Configuration to save the changes.

Running this command changes the value of tag DFDFDF33 in the device configuration. See Command 0x03::0x72 - Get Device Configuration. It also changes the device and terminal configuration check values reported by Command 0x07::0x12 - Read EMV L2 Configuration Check Values.

Application Group 0x07 - EMV L2 Contact Messages (Chip Card L2 Mode Only) - 16 - 30

Command 0x07::0x11 - Read EMV L2 Terminal Capabilities Configuration

The host uses this command to read the device’s EMV L2 Terminal Capabilities Configuration set by Command 0x07::0x10 - Modify EMV L2 Terminal Capabilities Configuration. Descriptions of the tags can be found in EMV Integrated Circuit Card Specifications for Payment Systems v4.3 .

Table - Message Structure for Command 0x07::0x11 - Read EMV L2 Terminal Capabilities Configuration

Tag

Len

Value(s) / Description

Command 0x07::0x12 - Read EMV L2 Configuration Check Values

The host can use this command to retrieve check values (CVs) for a number of device configuration settings. Use this command after finishing configuring a device to obtain baseline values, then use it again at any time and compare the check values to the baseline values to quickly determine whether any changes have occurred. A changed Master CV indicates a configuration change has occurred. The individual check values can help determine which configuration section has changed. Merchant data in tags 9F16, 9F1C, and 9F4E are not included in any check value calculations.

Command 0x07::0x13 - EMV L2 Continue Action

If the host has called Command 0x07::0x00 - EMV L2 Start Transaction with the Transaction Options specifying Continue Mode Enabled, Wait, the host uses this command to tell the device how to proceed with the transaction after receiving Notification 0x07::0x8C - EMV L2 Continue Notification. The host can cancel the transaction or modify the transaction amount here.

Command 0x07::0x14 - EMV L2 Offline PIN CVM Result

The host uses this command to send offline PIN data to the device in response to Notification 0x07::0x8B - EMV L2 Offline PIN CVM Request. The response from the EPP when reading the PIN includes the PIN block and sequence number needed for this command (DF53 and DFDF41).

Command 0x07::0x80 - EMV L2 Transaction Status

The host uses this command to get the ongoing status of a transaction it has initiated using Command 0x07::0x00 - EMV L2 Start Transaction. The host may opt to call this command during an EMV transaction to monitor progress, or it may subscribe to notifications using Command 0x01::0x50 - Subscribe to Notifications and the device will send status reports proactively using Notification 0x07::0x8A - EMV L2 Transaction Status.

Notification 0x07::0x81 - EMV L2 Display Message Request

The device sends this notification to request that the host display a message to the operator or cardholder. The host should display the message exactly as received. If the message is too long to fit on a single line it may be split to multiple lines if the host wishes. Messages are limited to 1024 bytes. If the message is zero length, this is a request for the host to clear the display.

Notification 0x07::0x82 - EMV L2 User Selection Request

The device uses this notification to inform the host that a cardholder must enter a selection before the device can continue with the transaction. This can include:

The host needs the cardholder to select a language.
The host and card have more than one mutually supported application in common.
The host and card have only one mutually supported application in common, but the host called Command 0x07::0x00 - EMV L2 Start Transaction with the Transaction Options parameter specifying Enhanced App Select Mode Enabled.

In response, the host should prompt the cardholder to select an item from the menu, then send Command 0x07::0x02 - EMV L2 User Selection Result to provide the selection result and inform the device to continue the transaction.

Notification 0x07::0x83 - EMV L2 ARQC Message

The device uses this notification to send ARQC data for the host to process. After the host processes the ARQC data, it should send Command 0x07::0x03 - EMV L2 Online Processing Result / Acquirer Response to inform the device it can proceed with the transaction.

If the card matches one or more rules in the device’s Account Data Whitelist (see Command 0x03::0x80 - Read PAN Whitelist / Account Data Whitelist), the ARQC Message is a TLV data object with the following contents:

Notification 0x07::0x84 - EMV L2 Transaction Result

The device sends this notification to provide the host with final information from the transaction. It will usually include batch data and an indication of whether a signature is required.

Notification 0x07::0x87 - EMV L2 PIN Entry Show Prompt Request

The device uses this notification to request that the host display a PIN entry related prompt on the host’s display.

Notification 0x07::0x88 - EMV L2 Online PIN CVM Request

The device uses this notification to request a online PIN block from the host.

Notification 0x07::0x89 - EMV L2 Language Selection Result

The device uses this notification to notify host the language selection result.

Notification 0x07::0x8A - EMV L2 Transaction Status

The host can use Command 0x01::0x50 - Subscribe to Notifications to subscribe to this notification to receive notifications of ongoing progress of an EMV transaction it has initiated using Command 0x07::0x00 - EMV L2 Start Transaction. It may also request some of this status information on demand using Command 0x07::0x80 - EMV L2 Transaction Status.

Notification 0x07::0x8B - EMV L2 Offline PIN CVM Request

The device uses this notification to request am offline PIN block from the host. The host must request PIN entry from a paired Cryptera EPP, get the sequence number and encrypted PIN block, and send the data to the oDynamo using Command 0x07::0x14 - EMV L2 Offline PIN CVM Result.

Notification 0x07::0x8C - EMV L2 Continue Notification

If the host has called Command 0x07::0x00 - EMV L2 Start Transaction with the Transaction Options parameter specifying Continue Mode Enabled, Wait or Continue Mode Enabled, Continue, the device uses this notification to provide data to the host after state EMV Read Application Data (status progress code = 8) is complete. If the value of the Notification Flag TLV data object indicates Transaction Paused, the host should call Command 0x07::0x13 - EMV L2 Continue Action to proceed with the transaction.

OEM Readers and Components

Programmer's Manuals

Documents

Introduction

About This Document

About Terminology

Appendix A Examples

MTCMSMessage Class Methods

MTCMSMessage

MTCMS Class Methods

Rails

Rails Support

For more help

Appendix A Examples

Programmer's Manuals

Documents

Need More Help

OEM Readers and Components