Magtek DynaFlex Family Owner's manual

Type
Owner's manual

This manual is also suitable for

MagTek I 1710 Apollo Court I Seal Beach, CA 90740 I Phone: (562) 546-6400 I Technical Support: (888) 624-8350
www.magtek.com
DynaFlex Products
Three-way Secure Card Reader Authenticators
Programmers Manual (COMMANDS)
April 2021
Document Number:
D998200383-19
REGISTERED TO ISO 9001:2015
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 2 of 158 (D998200383-19)
Copyright © 2006 - 2021 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®, MagnePrint®, and MagneSafe® are registered trademarks 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.
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).
EMVCo™ and EMVare trademarks of EMVCo and its licensors.
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.
UL and the UL logo are trademarks of UL LLC.
The Bluetooth® word mark and logos are registered trademarks owned by Bluetooth SIG, Inc. and any
use of such marks by MagTek is under license.
Google Play™ store and Android™ platform are trademarks of Google Inc.
Apple Pay®, iPhone®, iPod®, Mac®, and OS X® are registered trademarks of Apple Inc., registered in
the U.S. and other countries. iPad™ is a trademark of Apple. Inc. App Store
SM
is a service mark of
Apple Inc., registered in the U.S. and other countries. IOS is a trademark or registered trademark of
Cisco in the U.S. and other countries and is used by Apple Inc. under license.
Microsoft®, Windows®, and .NET® are registered trademarks of Microsoft Corporation.
All other system names and product names are the property of their respective owners.
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 3 of 158 (D998200383-19)
Table 0-1 - Revisions
Rev Number
Date
Notes
10
Sep 3, 2020
Initial release
12
Oct 13, 2020
Prepare for general availability.
14
Dec 17, 2020
Remove Command 0x1011 - Get Transaction Data and related
content; 4.2 clarify DFDF52 value 0x03 is reserved; Add
Command 0x1802 - Report Cardholder Selection and add
related notification details to Notification 0x1803 - User
Interface Host Action Request; Add Command 0x1F02 - Set
Notification Subscriptions; Add Command 0x1803 - Display
Message; Command 0x1001 - Start Transaction, add
description of how to implement host-driven fallback, add
device-driven fallback feature, add optional parameters to
suppress “THANK YOU” message and override the final
display message; Add Property 1.2.2.2.1.1 Reduce Power
During USB Suspend; Add note in Command 0x1001 - Start
Transaction regarding transaction amount when in Quick Chip
mode; Merchant Data Container
Merchant Data is normally used by the host for receipt printing.
The contents of this container are not customizable.
Table 4-5 clarify possible values for Signature Status; Misc.
clarifications and corrections.
16
Jan 28. 2021
Command 0x1001 - Start Transaction Table 6-1 add
signature bypass control parameter and Transaction Timeout
parameter, update event sequence to change message from USE
CHIP CARD to TRY AGAIN and add information about
device-driven signature capture, clarify device-driven fallback
sequence; Notification 0x0105 - Transaction Operation
Complete Table 7-8 update possible value for Signature Status;
Add Property 1.2.3.1.2.1 Display Orientation; Add Property
1.2.1.1.2.1 Signature Capture; Add Property 1.2.1.1.2.2
Include Signature Data in EMV Batch Data; Misc.
clarifications and corrections.
18
Mar 4, 2021
Add Property 2.3.1.2.1.1 Device Operational Status; Add
Property 2.3.1.2.1.2 Offline Status Detail; Add Property
2.3.1.1.2.1 Real Time Clock Enabled; Add Property
2.3.1.1.2.2 Tamper Sensors Activated; Add Property
2.3.1.1.2.3 Tamper Sensor Tampered; Notification 0x0105 -
Transaction Operation Complete add notification codes for
Quick Chip signature capture; Misc. clarifications and
corrections.
19
Apr 1, 2021
Add Property 1.2.1.1.2.3 Signature Timing Window and
supporting information about host-driven signature capture in
Command 0x1001 - Start Transaction; Change name of
Property 1.2.1.1.2.1 Signature Capture Control (Touch
Only) and clarify behavior throughout the document.
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 4 of 158 (D998200383-19)
LIMITED WARRANTY
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 MagTek Support Services 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.
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 5 of 158 (D998200383-19)
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 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.
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 6 of 158 (D998200383-19)
FCC INFORMATION
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: Changes or modifications not expressly approved by MagTek could void the
user’s authority to operate this equipment.
CANADIAN DECLARATION OF CONFORMITY
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.
INNOVATION, SCIENCE AND ECONOMIC DEVELOPEMENT
CANADA (ISED)
This device complies with ISED Canada licence-exempt RSS standard(s). Operation is subject to the
following two conditions: (1) This device may not cause interference, and (2) This device must accept
any interference, including interference that may cause undesired operation of the device.
Le présent appareil est conforme aux CNR d'Industrie Canada applicables aux appareils radio exempts de
licence. L'exploitation est autorisée aux deux conditions suivantes: (1) L'appareil ne doit pas produire de
brouillage, et (2) L'utilisateur de l'appareil doit accepter tout brouillage radioélectrique subi, même si le
brouillage est susceptible d'en compromettre le fonctionnement.
CE STANDARDS
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.
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 7 of 158 (D998200383-19)
EU STATEMENT
Hereby, MagTek Inc. declares that the radio equipment types Wideband Transmission System (802.11
wireless and Bluetooth Low Energy), and Non-Specific Short Range Device (contactless) are in
compliance with Directive 2014/53/EU. The full text of the EU declarations of conformity is available
at the following internet addresses:
https://www.magtek.com/Content/DocumentationFiles/D998200404.pdf for DynaFlex with no
display, USB connection
https://www.magtek.com/Content/DocumentationFiles/D998200410.pdf for DynaFlex with no
display, Bluetooth LE connection
https://www.magtek.com/Content/DocumentationFiles/D998200411.pdf for DynaFlex Pro with USB
connection
https://www.magtek.com/Content/DocumentationFiles/D998200412.pdf for DynaFlex Pro with
Bluetooth LE connection
https://www.magtek.com/Content/DocumentationFiles/D998200413.pdf for DynaFlex Pro with
802.11 wireless connection
AUSTRALIA / NEW ZEALAND STATEMENT
Testing for compliance with AS/NZS standards was performed by a registered and accredited laboratory.
The unit under test was found compliant with standards established under AS/NZS CISPR 32 (2013),
AS/NZS 4268 Table 1, Row 59 DTS 2400-2483MHz SRD (802.11), and AS/NZS 4268 (2017) Table 1,
Row 43 13.553-13.567MHz (contactless reader).
UL/CSA
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).
ROHS STATEMENT
When ordered as RoHS compliant, this product meets the Electrical and Electronic Equipment (EEE)
Reduction of Hazardous Substances (RoHS) European Directive 2002/95/EC. The marking is clearly
recognizable, either as written words like “Pb-free,” “lead-free,” or as another clear symbol ( ).
PCI STATEMENT
PCI Security Standards Council, LLC (“PCI SSC”) has approved this PTS POI device (SCR class) to be
compliant with the PCI PTS POI Security Requirements v5.1.
When granted, PCI SSC approval is provided by PCI SSC to ensure certain security and operational
characteristics important to the achievement of PCI SSC’s goals, but PCI SSC approval does not under
any circumstances include any endorsement or warranty regarding the functionality, quality or
performance of any particular product or service. PCI SSC does not warrant any products or services
provided by third parties. PCI SSC approval does not under any circumstances include or imply any
product warranties from PCI SSC, including, without limitation, any implied warranties of
merchantability, fitness for purpose, or non-infringement, all of which are expressly disclaimed by PCI
SSC. All rights and remedies regarding products and services which have received PCI SSC approval
shall be provided by the party providing such products or services, and not by PCI SSC.
0 - Table of Contents
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 8 of 158 (D998200383-19)
Table of Contents
Limited Warranty .............................................................................................................................................. 4
FCC Information ................................................................................................................................................ 6
Canadian Declaration Of Conformity ............................................................................................................. 6
Innovation, Science and Economic Developement Canada (ISED).......................................................... 6
CE STANDARDS ................................................................................................................................................. 6
EU Statement ..................................................................................................................................................... 7
Australia / New Zealand Statement .............................................................................................................. 7
RoHS STATEMENT ............................................................................................................................................. 7
PCI Statement ................................................................................................................................................... 7
Table of Contents .............................................................................................................................................. 8
1 Introduction ............................................................................................................................................. 12
1.1 About This Document .................................................................................................................... 12
1.2 About Terminology ......................................................................................................................... 13
1.3 About SDKs and Sample Code ..................................................................................................... 14
1.4 About Connections and Data Formats ........................................................................................ 15
1.5 About Device Features .................................................................................................................. 16
2 Connection Types .................................................................................................................................... 17
2.1 How to Use USB Connections (USB Only) ................................................................................... 17
2.1.1 About USB Reports, Usages, Usage Pages, and Usage IDs ............................................. 17
2.1.2 How to Connect to a Device Using the USB Connection .................................................. 17
2.1.3 How to Send Command Requests Using the USB Connection ....................................... 18
2.1.4 How to Receive Data Using the USB Connection (HID Only) ........................................... 20
3 Messages (Requests, Responses, Notifications, and Files) ............................................................. 21
3.1 About Messages ............................................................................................................................. 21
3.2 Message Format ............................................................................................................................. 22
3.2.1 Tag-Length-Value (TLV) Encoding ........................................................................................ 22
3.2.1.1 About TLV Encoding ....................................................................................................... 22
3.2.1.2 TLV Example ................................................................................................................... 23
3.2.1.3 How to Read TLV Tables ............................................................................................... 25
3.2.2 Message Structure ................................................................................................................. 27
3.2.2.1 Request Message .......................................................................................................... 27
3.2.2.2 Response Message ....................................................................................................... 28
3.2.2.3 Notification Message .................................................................................................... 32
3.2.2.4 Data File Message ......................................................................................................... 34
4 Data Types and Shared TLV Data Objects .......................................................................................... 35
4.1 Primitive Data Types ...................................................................................................................... 35
4.2 EMV ARQC Type .............................................................................................................................. 36
0 - Table of Contents
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 9 of 158 (D998200383-19)
4.2.1 EMV ARQC (DynaPro Format) Type ..................................................................................... 36
4.3 EMV Batch Data Type .................................................................................................................... 39
4.3.1 EMV Batch Data (DynaPro Format) Type............................................................................ 40
4.3.2 Merchant Data Container ..................................................................................................... 44
4.4 Signature Capture File Type.......................................................................................................... 46
4.5 Security Operation Type ................................................................................................................ 47
4.6 Security Parameters Type ............................................................................................................. 50
4.7 Key Information Type ..................................................................................................................... 51
5 Security ..................................................................................................................................................... 52
5.1 About Message Authentication Codes (MAC) ............................................................................ 52
5.1.1 MACs for EMV Data ................................................................................................................ 52
5.2 About Encryption and Decryption ................................................................................................ 53
5.3 How to Determine the Key ............................................................................................................ 53
5.4 How to Decrypt Data ...................................................................................................................... 54
6 Command Definitions ............................................................................................................................ 55
6.1 Command Group 0x10nn - Transactions .................................................................................... 55
6.1.1 Command 0x1001 - Start Transaction ............................................................................... 55
6.1.2 Command 0x1008 - Cancel Transaction............................................................................ 60
6.2 Command Group 0x18nn - User Interface ................................................................................. 61
6.2.1 Command 0x1801 - Request Cardholder Signature ........................................................ 61
6.2.2 Command 0x1802 - Report Cardholder Selection ........................................................... 63
6.2.3 Command 0x1803 - Display Message ............................................................................... 65
6.2.4 Command 0x1821 - Show Image ....................................................................................... 68
6.3 Command Group 0x1Fnn - Device Control ................................................................................. 70
6.3.1 Command 0x1F01 - Reset Device....................................................................................... 70
6.3.2 Command 0x1F02 - Set Notification Subscriptions ......................................................... 71
6.4 Command Group 0xD1nn - Settings and Information .............................................................. 73
6.4.1 Command 0xD101 - Get Property ....................................................................................... 73
6.4.2 Command 0xD111 - Set Property ....................................................................................... 76
6.5 Command Group 0xD8nn - File Operations ............................................................................... 79
6.5.1 About Files .............................................................................................................................. 79
6.5.2 Command 0xD801 - Load Firmware File ........................................................................... 81
6.5.3 Command 0xD811 - Start Send File to Device (Secured) ............................................... 83
6.5.4 Command 0xD812 - Start Send File to Device (Unsecured) ........................................... 85
6.5.5 Command 0xD821 - Start Get File from Device ............................................................... 88
6.6 Command Group 0xD9nn - Process Files ................................................................................... 90
6.6.1 Command 0xD901 - Commit Firmware from File ............................................................ 90
6.7 Command Group 0xDFnn - Diagnostics and Utilities................................................................ 92
6.7.1 Command 0xDF01 - Echo ..................................................................................................... 92
0 - Table of Contents
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 10 of 158 (D998200383-19)
6.8 Command Group 0xEnnn - Security ............................................................................................ 93
6.8.1 Command 0xE001 - Get Challenge ..................................................................................... 93
6.8.2 Command 0xEEEE - Send Secured Command to Device ................................................ 95
6.8.3 Command 0xEF01 - Load Key Using TR-31 ....................................................................... 97
6.8.4 Command 0xEF11 - Get Key Info ........................................................................................ 99
7 Notification Definitions ........................................................................................................................ 101
7.1 Notification Group 0x01nn - Notifications from Transactions .............................................. 101
7.1.1 Notification 0x0101 - Transaction Information Update ................................................. 101
7.1.2 Notification 0x0103 - Transaction Host Action Request ............................................... 104
7.1.3 Notification 0x0105 - Transaction Operation Complete ................................................ 106
7.2 Notification Group 0x09nn - Notifications from Firmware Updates ..................................... 110
7.2.1 Notification 0x0905 - Firmware Update Successful ....................................................... 110
7.2.2 Notification 0x0906 - Firmware Update Failed ............................................................... 111
7.3 Notification Group 0x18nn - Notifications from User Interface ............................................ 112
7.3.1 Notification 0x1801 - User Interface Information Update ............................................. 112
7.3.2 Notification 0x1803 - User Interface Host Action Request ........................................... 112
7.3.3 Notification 0x1805 - User Interface Operation Complete ............................................ 116
8 Configuration ......................................................................................................................................... 117
8.1 About Configuration ..................................................................................................................... 117
8.2 Property Group 1.1.nnnn Financial Settings ............................................................................ 118
8.2.1 Property Subgroup 1.1.1.nnn EMV Settings .................................................................... 118
8.2.1.1 Property 1.1.1.1.1.1 EMV Terminal Identification .................................................. 118
8.2.1.2 Property 1.1.1.1.1.2 EMV ARQC Message Tag List ................................................ 119
8.2.1.3 Property 1.1.1.1.1.3 EMV Batch Data Tag List ....................................................... 121
8.2.1.4 Property 1.1.1.1.1.4 EMV Reversal Data Tag List .................................................. 123
8.2.2 Property Subgroup 1.1.2.nnn SRED Settings .................................................................. 124
8.2.2.1 Property 1.1.2.2.1.2 ISO/ABA Masking Character ................................................. 124
8.2.2.2 Property 1.1.2.2.1.3 PAN Number of Leading Unmasked Characters ................ 126
8.2.2.3 Property 1.1.2.2.1.4 PAN Number of Trailing Unmasked Characters ................. 127
8.2.2.4 Property 1.1.2.2.1.5 PAN MOD 10 Check Digit Correction ................................... 128
8.2.2.5 Property 1.1.2.5.1.1 AAMVA Allowed ....................................................................... 129
8.2.2.6 Property 1.1.2.5.1.2 Track 1 Enable ......................................................................... 130
8.2.2.7 Property 1.1.2.5.1.3 Track 2 Enable ......................................................................... 131
8.2.2.8 Property 1.1.2.5.1.4 Track 3 Enable ......................................................................... 132
8.3 Property Group 1.2.nnnn Device Settings ................................................................................ 133
8.3.1 Property Subgroup 1.2.1.nnn Transaction Settings ....................................................... 133
8.3.1.1 Property 1.2.1.1.1.1 Device-Driven Fallback Behavior .......................................... 133
8.3.1.2 Property 1.2.1.1.2.1 Signature Capture Control (Touch Only) .............................. 134
0 - Table of Contents
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 11 of 158 (D998200383-19)
8.3.1.3 Property 1.2.1.1.2.2 Include Signature Data in EMV Batch Data ........................ 135
8.3.1.4 Property 1.2.1.1.2.3 Signature Timing Window (Touch Only) .............................. 136
8.3.2 Property Subgroup 1.2.2.nnn USB Settings ..................................................................... 137
8.3.2.1 Property 1.2.2.2.1.1 Reduce Power During USB Suspend .................................... 137
8.3.2.2 Property 1.2.1.1.2.3 Signature Timing Window ..................................................... 138
8.3.3 Property Subgroup 1.2.3.nnn User Interface Settings ................................................... 139
8.3.3.1 Property 1.2.3.1.1.1 Custom Idle Page Image ....................................................... 139
8.3.3.2 Property 1.2.3.1.2.1 Display Orientation ................................................................. 141
8.4 Property Group 2.1.2.nnn Device Firmware Identification Information .............................. 142
8.4.1 Property Subgroup 2.1.2.1.nn Boot Firmware Information .......................................... 142
8.4.1.1 Property 2.1.2.1.1.2 Boot1 Firmware Version ........................................................ 142
8.4.1.2 Property 2.1.2.1.1.4 Boot1 Firmware Part Number .............................................. 143
8.4.2 Property Subgroup 2.1.2.2.nn Core Firmware Information ........................................... 144
8.4.2.1 Property 2.1.2.2.2.1 Device Model Name ............................................................... 144
8.4.2.2 Property 2.1.2.2.2.2 Main Firmware Version .......................................................... 145
8.4.2.3 Property 2.1.2.2.2.4 Main Firmware Part Number ................................................ 146
8.4.2.4 Property 2.1.2.2.2.6 Key Type ................................................................................... 147
8.5 Property Group 2.2.1.nnn Device Reader Hardware Information ........................................ 148
8.5.1 Property Subgroup 2.2.1.1.1.n Hardware Reader Common Configuration Information
148
8.5.1.1 Property 2.2.1.1.1.1 Serial Number ......................................................................... 148
8.5.1.2 Property 2.2.1.1.1.1 Device Capabilities Report .................................................... 149
8.5.1.3 Property 2.2.1.1.1.3 PCI Hardware ID ...................................................................... 150
8.6 Property Group 2.3.1.nnn System Status Information ........................................................... 151
8.6.1 Property Subgroup 2.3.1.1.2.n System Status Security Protection Information ....... 151
8.6.1.1 Property 2.3.1.1.2.1 Real Time Clock Enabled ....................................................... 151
8.6.1.2 Property 2.3.1.1.2.2 Tamper Sensors Activated .................................................... 152
8.6.1.3 Property 2.3.1.1.2.3 Tamper Sensor Tampered ..................................................... 153
8.6.2 Property Subgroup 2.3.1.2.1.n System Status Device State Information .................. 154
8.6.2.1 Property 2.3.1.2.1.1 Device Operational Status ..................................................... 154
8.6.2.2 Property 2.3.1.2.1.2 Offline Status Detail ............................................................... 155
Appendix A Object IDs (OIDs) and ITU-T X660 ...................................................................................... 156
A.1 About OIDs ..................................................................................................................................... 156
A.2 Octet Encoding of OIDs ................................................................................................................ 157
A.3 TLV Encoding of OIDs ................................................................................................................... 158
1 - Introduction
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 12 of 158 (D998200383-19)
1 Introduction
1.1 About This Document
This document describes how to communicate with Secure Card Reader Authenticator (SCRA) devices
which implement MagTek Messaging Schema (MMS) and the DynaFlex family system architecture.
The document uses bold face to:
Highlight terms / concepts being formally defined in the current sentence / paragraph
Highlight important distinguishing keywords in sentences
Indicate hyperlinks to other sections / tables
The document uses a small number of annotation standards that are important to understand:
Hexadecimal values are prefixed with 0x unless the context clearly indicates an unprefixed number is
hexadecimal (for example, TLV tags, lengths, and values are always assumed to be hex).
Binary values are prefixed with 0b unless the context clearly indicates the value is binary.
Decimal values are not prefixed unless required for clarity, in which case the prefix is 0d.
The standard documented by this document makes extensive use of Tag-Length-Value encoding. Section
3.2.1 Tag-Length-Value (TLV) Encoding describes how to encode and decode TLV, and how to read
the tables in this document that describe TLV data objects.
1 - Introduction
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 13 of 158 (D998200383-19)
1.2 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 Secure Card Reader Authenticator (SCRA) that receives and responds to the
command set specified in this document. Devices include DynaFlex, DynaProx, and so on.
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
LE, EMV, smart phones, and more recent versions of Windows) use very specific meanings for the term
“Application,” this document favors the term host software to refer to software on the host that provides
a user interface for the operator.
The combination of device(s), host(s), host software, device firmware, device configuration settings,
physical mounting and environment, user experience, and documentation is referred to as the solution.
1 - Introduction
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 14 of 158 (D998200383-19)
1.3 About SDKs and Sample Code
MagTek provides convenient SDKs and corresponding documentation for many programming languages
and operating systems. The API libraries included in the SDKs wrap the details of the connection in an
interface that conceptually parallels the device’s internal operation, freeing software developers to focus
on the business logic, without having to deal with the complexities of platform APIs for connecting to the
various available connection types, communicating using the various available protocols, and parsing the
various available data formats. Information about using MagTek wrapper APIs is available in separate
documentation, including:
D998200380 Magtek Universal SDK Programmer’s Manual (Microsoft .NET)
D998200381 Magtek Universal SDK Programmer’s Manual (Microsoft C++ )
D998200385 Magtek Universal SDK Programmer’s Manual (Java)
D998200386 Magtek Universal SDK Programmer’s Manual (iOS)
D998200387 Magtek Universal SDK Programmer’s Manual (Android)
D998200388 Magtek Universal SDK Programmer’s Manual (macOS)
The documentation is bundled with the SDKs themselves, which include:
1000007351 MagTek Universal SDK for MMS Devices (Windows)
1000007352 MagTek Universal SDK for MMS Devices (Android)
1000007353 MagTek Universal SDK for MMS Devices (iOS)
1000007354 MagTek Universal SDK for MMS Devices (macOS)
The SDKs and corresponding documentation include:
Functions for sending the direct commands described in this manual
Wrappers for commonly used commands that further simplify development
Sample source code to demonstrate how to communicate with the device using the direct commands
described in this manual
To download the SDKs and documentation, search www.magtek.com for “SDK” and select the SDK and
documentation for the programming languages and platforms you need, or contact MagTek Support
Services for assistance.
Software developers also have the option to revert to direct communication with the device using libraries
available in the chosen development framework. For example, custom software written in Visual Basic
or visual C++ may make API calls to the standard Windows USB HID driver. This document provides
information and support for developing host software using that method.
MagTek has also developed sample software that demonstrates direct communication with the device,
which software developers can use to test the device and which provides a starting point for developing
other software. For more information, see the MagTek web site, or contact your reseller or MagTek
Support Services.
1 - Introduction
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 15 of 158 (D998200383-19)
1.4 About Connections and Data Formats
MMS products transmit data using a set of common data formats across a variety of physical connection layers, which can include universal serial bus
(USB) acting as a vendor-defined HID device (“USB HID”), 802.11 wireless, Bluetooth, Bluetooth Low Energy (“Bluetooth LE”), RS-232, Apple
Lightning, and so on. The set of available physical connection types and the data formats available on each connection type is device-dependent.
Table 1-1 shows the physical connection types available on each product, and the data formats supported on each connection type for that device.
Details about connection types and formats can be found in section 2 Connection Types. Section headings in this document include tags that indicate
which connection types and/or data formats they apply to.
Table 1-1 - Device Connection Types / Data Formats
Product / Connection
Bluetooth LE GATT
RS-232 / UART
USB HID
Ethernet
DynaFlex
HID
DynaFlex Pro
HID
DynaFlex Pro w/802.11 Wireless
HID
1 - Introduction
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 16 of 158 (D998200383-19)
1.5 About Device Features
Much of the information in this document is applicable to multiple devices. When developing solutions that use a specific device or set of devices,
integrators must be aware of each device’s connection types, data formats, features, and configuration options, which affect the availability and
behavior of some commands. Table 1-2 provides a list of device features that may impact command availability and behavior. All section headings in
this document include tags that indicate which features they apply to.
Table 1-2 - Device Features
Feature / Product
DynaFlex
DynaFlex
w/Bluetooth LE
DynaFlex Pro
DynaFlex Pro
w/Bluetooth LE
DynaFlex Pro
w/802.11 Wireless
DynaFlex Pro
w/Ethernet
DynaProx
MSR Swipe
Y
Y
Y
Y
Y
Y
N
MSR Insert
N
N
N
N
N
N
N
EMV Contact
Y
Y
Y
Y
Y
Y
N
EMV Contactless
Y
Y
Y
Y
Y
Y
Y
LEDx4 RGB
Y
Y
Y
Y
Y
Y
Y
Touchscreen Display
N
N
Y
Y
Y
Y
N
Battery Power
N
Y
N
Y
Y
Y
N
Footnotes:
2 - Connection Types
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 17 of 158 (D998200383-19)
2 Connection Types
Table 1-1 on page 15 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.
2.1 How to Use USB Connections (USB Only)
These USB devices conform to the USB specification revision 1.1. They also conform to the Human
Interface Device (HID) class specification version 1.1. This document assumes the audience is familiar
with USB HID class specifications, which are available at www.usb.org. MagTek strongly recommends
becoming familiar with that standard before trying to communicate with the device directly via USB.
These devices are full-speed, high-powered USB devices that draw power from the USB bus they are
connected to. They enter and wake up from Suspend mode when directed to do so by the USB host.
They do not support remote wakeup.
When connecting via USB, MMS devices connect to the USB host as a vendor-defined Human Interface
Device. MMS devices identify themselves to the host with MagTek’s vendor ID 0x0801 and Product ID
(PID) 0x2020.
Details for exchanging messages with the device are provided in the sections that follow.
2.1.1 About USB Reports, Usages, Usage Pages, and Usage IDs
All USB HID devices send and receive data using Reports. Each report may contain several sections,
called Usages, each of which has its own unique four-byte (32-bit) identifier. The two most significant
bytes of a usage are called the usage page, and the two least significant bytes are called the usage ID.
Vendor-defined HID device usages must have a usage page in the range 0xFF00 - 0xFFFF, and it is
common practice for related usage IDs share the same usage page. For these reasons, all usages for MMS
devices use vendor-defined usage page 0xFF00, Magnetic Stripe Reader.
HID reports used by the host can be divided into two types:
Output Reports, which the host uses to send messages (such as commands) to the device.
Input Reports, which the device uses to send messages (such as responses and unsolicited
notifications) to the host.
For information about using output reports to send command messages to / receive response messages
from the device, see section 2.1.3 How to Send Command Requests Using the USB Connection. For
information about receiving unsolicited data from the device, see section 2.1.4 How to Receive Data
Using the USB Connection (HID Only).
2.1.2 How to Connect to a Device Using the USB Connection
The steps for a host to connect to the device using the USB connector are the same as connecting to any
USB HID device, and are platform specific. The general steps regardless of platform are as follows:
Enumerate the USB devices connected to the host.
Locate the desired device by PID.
Open the USB connection.
Read the report descriptor.
Begin listening for incoming reports, and sending data using outgoing reports.
2 - Connection Types
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 18 of 158 (D998200383-19)
2.1.3 How to Send Command Requests Using the USB Connection
MMS communication between the host and the device consists of Messages, which are independent of
connection type and are documented in section 3. This section focuses specifically on how to use the
device’s USB HID connection to transmit a Command to the host by composing and sending a Request
Message, then listening for and interpreting the corresponding Response Message.
When the device is connected to the host via USB, the host sends one or more Output Reports to the
device to send the requests for commands, and listens / waits for the device to send one or more Input
Reports containing a response (see section 2.1.1). All reports use Usage Page 0xFF00, Usage ID 0x20,
and no Report ID (which some platform libraries present to the calling software as Report ID 0x00).
The host may send Output Reports by using either the default Control pipe or the Interrupt OUT pipe
using a blocking call to the platform’s USB libraries. The device ACKs all Output Reports immediately.
Upon detecting the ACK for the last Output Report in the message stream, the host software can
immediately begin listening for one or more follow-up Input Reports containing the device’s response.
Some messages defined in section 3 may exceed the maximum packet length allowed by USB HID. For
this reason, MMS implements a packetizing scheme the host must use when it composes Output Reports
to send commands, and when it decomposes Input Reports to receive responses. The host should follow
this general sequence to send a request and receive a response:
1) Choose the command to invoke from section 6 Command Definitions.
2) Construct the command request message using the Request table in the command documentation.
For a deeper explanation of the contents of request tables, see section 3 Messages (Requests,
Responses, Notifications, and Files).
3) Determine the complete length of the command request message.
4) Examine the device’s Report Descriptor to determine what payload length the device expects for an
Output Report (operating system libraries may refer to this length as the “Report Length” or “Report
Count”). MMS devices using USB HID generally use a payload length of 64 bytes.
a) If the message length fits the Single Packet payload length of 62 bytes, wrap the message in the
Single Packet format shown in Table 2-1.
b) If the message length does not fit the Single Packet payload length, wrap the message in the
format of a single Multi-Packet Head, followed by zero or more Multi-Packet Middles as
necessary, followed by one Multi-Packet Tail, as shown in Table 2-2, Table 2-3, and Table 2-4.
If necessary, the host can cancel in the middle of a Multi-Packet message using the Multi-Packet
Cancel packet shown in Table 2-5.
5) For each packet, send an Output Report to the device, and wait for the device to ACK the output
report USB packet. Upon ACK, either send the next packet in the sequence (if any), or begin
listening for an Input Report containing the device’s response message [see section 2.1.4 How to
Receive Data Using the USB Connection (HID Only)]. If an ACK does not arrive, time out and
assume the command needs to be started again.
6) Strip wrappers off the device’s response in exactly the same way you constructed the command
(using either Single Packet format or Multi-Packet format), and recompose the response message. Be
sure to assemble the packets in the correct order using Packet Number, and to truncate the padding
based on Message Length or Remaining Message Length.
7) Parse the final response message using the Response table in the documentation for the command.
2 - Connection Types
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 19 of 158 (D998200383-19)
Table 2-1 - Single Packet Format
Byte Offset
Field Name
Field Value
0
Packet Type
0x00 = Single Packet
1
Message Length
Message length, denoted as N
2..N+1
Message
Message exactly from section 3
N+2..63
Padding, if needed
0x00
Table 2-2 - Multi-Packet Head Format
Byte Offset
Field Name
Field Value
0
Packet Type
0x01 = Multi-packet Head
1..4
Message Length
Total message length before decomposing into packets,
denoted as N. If less than 62, use Single Packet Format.
5..63
Message Part
First 59 bytes of message from section 3
Table 2-3 - Multi-Packet Middle Format
Byte Offset
Field Name
Field Value
0
Packet Type
0x02 = Multi-Packet Middle
1..2
Packet Number
0x0001 = First Multi-Packet Middle
0x0002 = Second Multi-Packet Middle
Etc. up to 0xFFFF
3..63
Message Part
Next 60 bytes of message from section 3
Table 2-4 - Multi-Packet Tail Format
Byte Offset
Field Name
Field Value
0
Packet Type
0x03 = Multi-Packet Tail
1
Remaining Message Length
Number of bytes of the message that are being
transmitted in this final packet, denoted as n.
2..n+1
Message Part
Final n bytes of message exactly as described in section 3
n+2..63
Padding, if needed
0x00
Table 2-5 - Multi-Packet Cancel Format
Byte Offset
Field Name
Field Value
0
Packet Type
0x04 = Multi-Packet Cancel
1..2
Reason for Cancel
0x0000 = General
3..63
Padding
0x00
2 - Connection Types
DynaFlex Products| Three-way Secure Card Reader Authenticators | Programmer’s Manual (COMMANDS)
Page 20 of 158 (D998200383-19)
2.1.4 How to Receive Data Using the USB Connection (HID Only)
MMS devices use the same mechanism to send Response messages to host commands and to send
unsolicited Notifications to the host when events occur, such as device state changes or user interactions.
When the device communicates with the host as a vendor-defined HID device, it sends messages to the
host via an Input Report, which it sends to the host using the USB Interrupt IN pipe. Per the USB HID
standard, the host polls the device on a regular Polling Interval to see if the device has input reports
available to send. If the device does not, it responds to the host’s poll with a USB NAK.
The host software should always be listening for Input Reports from the device containing notification
messages and command response messages. Assembling and parsing the incoming message is the same
in both cases, but notification messages, which are generally unpredictable, need to be routed to different
handlers than responses, which are generally anticipated after sending a command. All input reports use
Usage Page 0xFF00, Usage ID 0x20. Because MMS devices only implement one input report, the input
report they send to the host does not include an Input Report ID (which some operating system libraries
present to the calling software as Input Report ID 0x00), in accordance with the USB HID specification.
Some response and notification messages defined in section 3 may exceed the maximum packet length
allowed by USB HID. If the message can’t fit into one packet, the device sends multiple packets, each
containing partial message data using the same message packet structures described in section 2.1.3,
Table 2-1, Table 2-2, Table 2-3, Table 2-4, Table 2-5.
Upon receiving an input report, the host can determine the size of message packet Input Reports by
looking at the HID report descriptor. The host can locate a specific data element in the report by finding
the corresponding Usage and interpreting its contents as binary data. Because MMS devices use a single
usage to hold the Input Report contents, unlike devices that divide the Input Report contents into length-
delimited Usages, the host software can hard-code its method of finding the packet data; it is not
necessary for the host software to examine the Report Descriptor for information about separate data
elements’ offsets upon receiving a packet.
The host should follow this general sequence to process incoming Input Reports:
1) Register a listener with the operating system USB library to have the relevant Input Reports routed to
the host software for processing.
2) When an Input Report arrives, knowing from section 2.1.1 that the device uses Usage Page 0xFF00,
and knowing the desired data is found in the usage with Usage ID 0x0020, call the platform’s USB
SDK to retrieve the data from Usage 0xFF000020 in the input report.
3) Interpret the blob of data according to tables in section 2.1.3 to determine whether the incoming
message is in single packet format or multi-packet format. If it is using multi-packet format:
a) Continue buffering the message and processing incoming packets until the last packet of the
message arrives.
b) Assemble the full message. Be sure to assemble the packets in the correct order using the Packet
Number, and to truncate the padding based on Message Length or Remaining Message Length.
4) Determine the message type and message ID and parse it according to the corresponding Response
table or Notification table in section 3.
5) Route the fully composed message to the appropriate handler.
  • Page 1 1
  • Page 2 2
  • Page 3 3
  • Page 4 4
  • Page 5 5
  • Page 6 6
  • Page 7 7
  • Page 8 8
  • Page 9 9
  • Page 10 10
  • Page 11 11
  • Page 12 12
  • Page 13 13
  • Page 14 14
  • Page 15 15
  • Page 16 16
  • Page 17 17
  • Page 18 18
  • Page 19 19
  • Page 20 20
  • Page 21 21
  • Page 22 22
  • Page 23 23
  • Page 24 24
  • Page 25 25
  • Page 26 26
  • Page 27 27
  • Page 28 28
  • Page 29 29
  • Page 30 30
  • Page 31 31
  • Page 32 32
  • Page 33 33
  • Page 34 34
  • Page 35 35
  • Page 36 36
  • Page 37 37
  • Page 38 38
  • Page 39 39
  • Page 40 40
  • Page 41 41
  • Page 42 42
  • Page 43 43
  • Page 44 44
  • Page 45 45
  • Page 46 46
  • Page 47 47
  • Page 48 48
  • Page 49 49
  • Page 50 50
  • Page 51 51
  • Page 52 52
  • Page 53 53
  • Page 54 54
  • Page 55 55
  • Page 56 56
  • Page 57 57
  • Page 58 58
  • Page 59 59
  • Page 60 60
  • Page 61 61
  • Page 62 62
  • Page 63 63
  • Page 64 64
  • Page 65 65
  • Page 66 66
  • Page 67 67
  • Page 68 68
  • Page 69 69
  • Page 70 70
  • Page 71 71
  • Page 72 72
  • Page 73 73
  • Page 74 74
  • Page 75 75
  • Page 76 76
  • Page 77 77
  • Page 78 78
  • Page 79 79
  • Page 80 80
  • Page 81 81
  • Page 82 82
  • Page 83 83
  • Page 84 84
  • Page 85 85
  • Page 86 86
  • Page 87 87
  • Page 88 88
  • Page 89 89
  • Page 90 90
  • Page 91 91
  • Page 92 92
  • Page 93 93
  • Page 94 94
  • Page 95 95
  • Page 96 96
  • Page 97 97
  • Page 98 98
  • Page 99 99
  • Page 100 100
  • Page 101 101
  • Page 102 102
  • Page 103 103
  • Page 104 104
  • Page 105 105
  • Page 106 106
  • Page 107 107
  • Page 108 108
  • Page 109 109
  • Page 110 110
  • Page 111 111
  • Page 112 112
  • Page 113 113
  • Page 114 114
  • Page 115 115
  • Page 116 116
  • Page 117 117
  • Page 118 118
  • Page 119 119
  • Page 120 120
  • Page 121 121
  • Page 122 122
  • Page 123 123
  • Page 124 124
  • Page 125 125
  • Page 126 126
  • Page 127 127
  • Page 128 128
  • Page 129 129
  • Page 130 130
  • Page 131 131
  • Page 132 132
  • Page 133 133
  • Page 134 134
  • Page 135 135
  • Page 136 136
  • Page 137 137
  • Page 138 138
  • Page 139 139
  • Page 140 140
  • Page 141 141
  • Page 142 142
  • Page 143 143
  • Page 144 144
  • Page 145 145
  • Page 146 146
  • Page 147 147
  • Page 148 148
  • Page 149 149
  • Page 150 150
  • Page 151 151
  • Page 152 152
  • Page 153 153
  • Page 154 154
  • Page 155 155
  • Page 156 156
  • Page 157 157
  • Page 158 158

Magtek DynaFlex Family Owner's manual

Type
Owner's manual
This manual is also suitable for

Ask a question and I''ll find the answer in the document

Finding information in a document is now easier with AI