Each input parameter supplied in the request is delimited by an ampersand character ‘&’, and the value for a parameter begins after an equal character ‘=’. Where ever a parameter contains multiple values, each are delimited by a comma character ‘,’.
Example Query
Return Value:
The EMV ARPC response output in Hex string format of device raw response for this command.
Example:
batchData
Batch data from the device to be passed to MagneFlex.
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
HTTP method to be used for the HTTP postback from MagneFlex. Use:
GET - returns the response data in the form of a query string. POST – recommended for EVM related transactions to accommodate limits on query string length.
closeDeviceAfter
Flag to close the device after the request. Use:
true – close device
false – do not close the device
readerArgument
ARPC data to send to the device. issuerAuthenticationData:, endSession:
Argument details:
issuerAuthenticationData – ARPC response to send to the device.
endSession - Flag to end the session for the device. Default value is true.
“true” = End the session after the request is processed.
“false” = Do not end the session after the request is processed.
destinationURL
MagneFlex will send the postback to this URL.
requestLocation
Flag to send GPS location of the device from which Magneflex (iOS only) is hosted.
Use:
true – send location
false – do not send location
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
Parameter
Description
errorCode
Error status. 0 is Success. Non-Zero is an error.
errorMessage
Description of the errorCode.
opType
The type of operation. For this command the value is:
This document provides instructions for using the browser-based MagTek Demo Applications to configure and test MagTek devices, including MMS devices, specifically the DynaFlex family (including DynaFlex, DynaFlex Pro, DynaFlex II, DynaFlex II PED, DynaFlex II Go and DynaProx, models).
The Demo Applications enable comprehensive testing of a wide array of capabilities, including core payment functions like EMV chip and NFC transactions, MSR reading, barcode scanning, and PIN entry. Note that feature support is dependent on your specific device model. For instance, the DynaFlex II PED model supports PIN entry, manual card entry, and signature capture functionalities.
CRITICAL REQUIREMENT: For USB connected devices, these demos require a Desktop, Chromium Browser Only!
The MagTek Demo Applications rely on Web HID functionality for USB connected devices, which is not supported by mobile browsers (iOS/Android). You must use a desktop-based Chromium browser (like Google Chrome, Microsoft Edge, or Opera) for the demos to function correctly when using a USB connected device.
Upon opening the Web HID Demo home page, the Main Page is displayed. This page serves as the central menu and is organized into the following categories:
MMS Devices – DynaFlex I/II device types and DynaProx (EMV, NFC, Barcode, PIN and MSR)
V5 MSR/Manual Entry – MSR swipe devices such as Dynamag and DynaPAD
Each section provides a corresponding demo page with user interface elements for connecting a device, issuing commands, and reviewing results see Figure 1.
Figure 1 - Demo Application Home Page
The MMS product family includes the following devices:
DynaFlex/DynaFlex Pro
DynaFlex II/DynaFlex II PED
DynaFlex II GO
DynaProx
Devices in this family generally support EMV, NFC, barcode, MSR, and PIN functionality, though specific features vary by model. The Demo Application connects through methods including USB HID, WebSocket (WSS), MQTT, or Bluetooth Low Energy (BLE), depending on the connection method enabled on your device.
This checklist provides a summary of the steps required for configuring and running a demo with your device.
Prepare Device: Power on the device (if there is a power button) and connect it via USB, Wi-Fi, MQTT, or BLE.
Open Demo Application: Launch the Web HID Demo in a desktop Chromium browser.
Configure Host App: Be sure to enter RMS, WebSocket, MQTT, and Contactless parameters prior to using the various demos.
Open Session: Select Open and confirm a successful connection.
To test your setup and connection, choose a command (e.g., Start EMV ALL), paste command data if necessary, and select Send Command.
View Results: Swipe, insert, or tap a card, and observe the transaction log for the response and confirmation.
V5 (SRED) Devices – iDynamo 5 Gen III (MSR)
Magensa Services – secure services for transaction testing
Miscellaneous – configuration and GitHub source access
Device Provisioning: If using WSS or MQTT, provision the device's network and security settings (as outlined in Section 3)
Demo Application Home Page
MMS Devices
Quick-Start Setup Guide
Note: For WSS connections, ensure the device's hostname (e.g., df-[SerialNumber]) is resolvable in your network. Also plan for periodic certificate renewal.
requestPIN (PinPad Only)
This query string instructs the device to prompt for a PIN.
Each input parameter supplied in the request is delimited by an ampersand character ‘&’, and the value for a parameter begins after an equal character ‘=’. Where ever a parameter contains multiple values, each are delimited by a comma character ‘,’.
Example query:
Return Value:
The Response output in Hex string format of device raw response for this command.
Example
operationStatus
Status of the operation.
pinEPB
Encrypted PIN block.
pinKSN
PIN KSN.
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
HTTP method to be used for the HTTP postback from MagneFlex. Use:
GET - returns the response data in the form of a query string. POST – recommended for EVM related transactions to accommodate limits on query string lengths.
closeDeviceAfter
Flag to close the device after the request. Use:
true – close device
false – do not close the device
readerArgument
Data to send for the device to be passed to MagneFlex. Arguments:
Add Lengths to each node to include all lower nodes and data.
The fully Constructed TLV command data:
Use the configType and command data for the SDK APIs.
Example Get: Device Model Name
Overview
This document is intended to describe onboarding for Selectable Card Data Encryption (SCDE) available on DynaFlex II GO devices. This feature is intended to allow the user to view card data outside of a transaction scenario. It is accessible using the MagTek Reader Management System (RMS) Application available in the Apple App Store.
The feature will work only with the RMS iOS app compatible with iPhone, iPad, and iPod touch, iPad OS.
iOS Application (PN 1000009755)
Compatible with Bluetooth Low Energy (BLE) connected readers, as well as WLAN enabled readers.
Appendix B - Related Documentation
To view or download any of the documents mentioned in this manual, visit
D998200595 - DYNAFLEX II GO SECURE CARD READER AUTHENTICATOR INSTALLATION AND OPERATION MANUAL
D998200681 - MAGTEK READER MANAGEMENT SYSTEM (RMS), IOS APPLICATION, INSTALLATION AND OPERATION MANUAL
Not sure where to start? MagTek offers different SDKs and interfaces depending on which reader you're building for and how you want to connect. This page points you to the right one; each links to its own documentation for the details.
SCDE is supported for MagTek DynaFlex II GO devices only.
Refer to D998200681 MagTek Reader Management System (RMS) iOS Application Installation and Operation Manual for detailed instructions on how to install the RMS app and how to use it.
[1] . 2 . 3 . 1 . 1 . 1 = 03000000
CT En En En En Cn = 03000000 CT EnLL->EnLL->EnLL->EnLL->CnLLValue
01 E20C->E30A->E108->E106->C10403000000
ConfigType = 01
Command data = E20CE30AE108E106C10403000000
MagneSafe V5 SCRAs and magnetic-stripe readers
MTSCRA SDK
Any supported reader, from a web browser
Native app (.NET, Java, iOS, Linux) → the Universal SDK wraps the MMS command set in native calls for your platform. (Confirm whether Android is also supported.)
In the browser (JavaScript, no install) → the MagneFlex Browser Web API connects to a reader over WebHID.
Just exploring → try a reader with no code in Demos & sample code before you pick an SDK.
The SDKs are the client-side layer — they handle connecting to a device and exchanging commands, responses, and notifications, so you work in your language instead of composing raw messages. The commands themselves — every parameter, object, and status code — are defined once in the API & Command Reference; the SDK pages link into it rather than repeating it.
Two things that are not SDKs, but live in this section because you'll reach for them while building:
Tools & Utilities — standalone tools for EMV configuration, OID conversion, and firmware updates.
Reader Management System (RMS) — the cloud service for managing deployed readers remotely (its full documentation is under Services).
Building for a DynaFamily reader? Go straight to the Universal SDK and pick your platform.
Not sure which reader is right first? See Pick Your Device.
Need runnable examples? Start with Demos & Sample Code.
For additional support, please contact MagTek Support:
Technical Support:
📧 Email: support@magtek.com
How to use the EMVConfiguration Console
How to use the EMVConfiguration Console
The following instructions are for using the MTUSDK Test console on a Linux operating system. In these examples, lines are removed and replaced with “. . .” for brevity.
BIN File
To send an individual BIN configuration file to the device follow these steps.
After the name of the console, enter:
[cfg.bin] Name of the .bin file
-t File type (excel or bin)
-i File Id number. 8 digit file id.
00000000 TERMINAL
00000100 PROCESSING
00000200 ENTRYPOINT
00000300 CA KEYS
00000500 AMEXDRL
-d Device path. Optional if using USB.
Example: Terminal configuration bin file
$ sudo ./emvconfiguration cfg00000000.bin –t bin –i 0000000000
Then press Enter key. The result is shown similar as below.
The console exits afterwards.
To send an Excel configuration file to the device follow these steps. Excel may contain one or multiple configurations.
After the name of the console, enter:
Example: Excel configuration file
Then press Enter key. The EMVConfiguration console will connect to Magensa Remote Services, send the excel content for conversion into .bin format, and then send each .bin file to the device.
The result is shown similar as below.
The console exits afterwards.
Connect to MTUSDK EMVConfig Console
Introduction
This document provides instructions to use the MTUSDK EMVConfiguration Console. The console sends either a .BIN file or contents of an Excel file to the device. BIN files are directly send to the device. Excel files are processed by Magensa Remote Services web service. The resulting BIN data is sent to the device.
This document is part of a larger library of documents designed to assist Secure Card Readers implementers, which includes the following documents available from MagTek:
D998200570 MAGTEK UNIVERSAL SDK PROGRAMMER'S MANUAL ( LINUX )
Connect the device to the USB port of the Linux computer.
The first time, allow a moment for the host to recognize the device.
The console automatically connects to the first USB DynaProx it finds. If specified used as below.
Connect the device to the Serial port of the Linux computer.
The EMVConfiguration console accepts a device path of either usb or serial. Serial may be in one of the following formats pending on the system hardware.
Set the appropriate device path when specifying –d in the command line.
DeviceInfo
Create an instance of the DeviceInfo from IDevice.getDeviceInfo(). Then use the function calls described in this chapter.
getModel
This function returns the model name of the device.
String DeviceInfo.getModel();
Return Value:
Returns the model name of the device.
getName
This function returns the name of the device.
String DeviceInfo.getName();
Return Value:
Returns the name of the device.
For the complete documentation index, see . This page is also available as .
Web-based Demos for V5 Devices for MSR/Manual Entry
This page provides access to browser-based Web HID demonstrations for MagneSafe V5 magnetic stripe (MSR) devices, showing how to communicate with Secure Card Reader Authenticators (SCRA) like Dynamag using Chromium-based desktop browsers for non-EMV transaction testing.
IEventSubscriber Delegates
MTUSDKNET API will invoke the callback function in this chapter to provide the requested data and/or a detailed response. To delegate the event, call the subscribeAll function with the name of a class that implements the IEventSubscriber Delegates interface.
OnEvent handles all event types. The eventType parameter defines which event is triggered.
Parameter
Description
Web-based Demos for V5 Devices
iDynamo 6, eDynamo, mDynamo and tDynamo
These demos provide an interactive web-based demonstration for MagneSafe V5 Secure Card Reader Authenticators (SCRA), showing how to integrate JavaScript with EMV and NFC-capable devices in Chromium-based desktop browsers.
This page provides an alternate web-based demonstration for Dynamag devices, offering a simplified interface for testing USB communication, command execution, and basic card swipe data capture workflows in a controlled browser environment.
This page provides an interactive web-based demonstration for Dynamag and similar V5 HID swipe readers, enabling developers to connect via USB, send commands, and capture magnetic stripe card data within a browser-based testing environment.
Web-based Demo
This web-based demo provides a V5 Device Client application that enables MQTT-based communication with MagTek's MagneSafe V5 devices. This application acts as a bridge between USB HID devices and an MQTT Broker.
This web-based demo shows how to communicate with Secure Card Reader Authenticator (SCRA) devices which implement MagTek's MagneSafe V5 system architecture using MQTT via the V5 Device Client (MQTT).
This web-based demo shows how to communicate with Secure Card Reader Authenticator (SCRA) devices which implement MagTek's MagneSafe V5 system architecture using WebHID.
Web-based Demos
IConfigurationCallback Delegates
MTUSDKNET API will invoke the callback function in this chapter to provide the requested data and/or a detailed response. These events will be called in a class that implements the IConfigurationCallback Delegates interface.
OnCalculateMAC
This event is called when certain asynchronous IDeviceConfiguration operations need to be have a MAC included with the request.
Returns an IResult that contains the calculated MAC.
This event is called to update the host on the progress of an asynchronous IDeviceConfiguration operation.
public void OnProgres(int progress);
Parameter
Description
Return Value: None
This event is called to update the host when an asynchronous IDeviceConfiguration operation is completed.
Copy
Parameter
Description
Return Value: None
Example:
Copy
For the complete documentation index, see . This page is also available as .
Configuration and Documentation Pages
This page provides centralized access to configuration guides, security certificate setup instructions, source code resources, and supporting documentation required to successfully deploy, secure, and integrate MagTek readers, using JavaScript and a wide array of web-based demos and related communication workflows.
Web-based Demos
Web Demos
Description
This page provides setup instructions and reference materials for configuring MagTek web-based demo environments, including device connectivity, communication parameters, and required prerequisites for running web-based demos and Chromium Desktop browsers.
requestSendExtendedCommand
This query string sends an extended command to the device and returns the raw response from the device.
Introduction
This document provides instructions for software developers who want to create Android software solutions that include MagTek devices connected to an Android based host. MagTek Universal SDK (MTUSDK) incorporates MagTek SCRA and MagTek PIN Pad SCRA devices into one SDK. This document is part of a larger library of documents designed to assist MagTek device implementers, which includes the following documents available from MagTek:
The sample code provides Android demonstration source code and a reusable MTUSDK API library that provides developers of custom software solutions with an easy-to-use interface for MagTek devices.
Developers can distribute the MTUSDK API Library to customers or distribute internally as part of an enterprise solution.
requestManualCard (PinPad Only)
This query string instructions the device to prompt for a manual card entry.
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. MagneSafe® is a registered trademark of MagTek, Inc. iDynamo™, and uDynamo are trademarks of MagTek, Inc.
eDynamo™, Dynamag, and DynaMAX are trademarks of MagTek, Inc.
This page provides guidance on configuring certificates and trust chains required for secure MQTT communication between MagTek devices, local clients, and backend services.
This page provides instructions for setting up TLS certificates and trust relationships needed to establish secure WebSocket (WSS) connections with supported MagTek devices.
This page provides access to the source code repositories for MagTek web-based demo applications, enabling developers to review implementation details, customize integrations, and build upon existing JavaScript examples.
This page provides legal and usage disclaimers outlining the terms, limitations, and responsibilities associated with using MagTek demo applications and supporting materials.
DynaProx™, DynaFlex Pro™, and DynaFlex II PED™ are trademarks of MagTek, Inc.
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.
Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries. Ubuntu® is a registered trademark of Canonical Ltd.
Microsoft®, Windows® and .NET® are registered trademarks of Microsoft Corporation.
EMV® is a registered trademark in the U.S. and other countries and an unregistered trademark elsewhere. The EMV trademark is owned by EMVCo, LLC. The Contactless Indicator mark, consisting of four graduating arcs, is a trademark owned by and used with permission of EMVCo, LLC.
All other system names and product names are the property of their respective owners.
Rev Number
Date
Notes
100
February 1, 2024
Initial release
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.
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.
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 SUPPORT@MAGTEK.COM.
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.
Table 0.1 – Revisions
SOFTWARE LICENSE AGREEMENT
macType
Type of Mac algorithm. For DynaFlex, use 0.
data
Contains the data of the payload to MAC.
progress
The progress of the configuration operation. Range: 0 - 100
public void OnResult(
StatusCode status,
byte[] data);
class OnConfigCallbackClass implements IConfigurationCallBack
{
public IResult OnCalculateMAC(byte macType, byte[] data)
{
// Event handler
}
public void OnProgress(int progress)
{
// Event handler
}
public void OnResult(StatusCode status, byte[] data)
{
// Event handler
}
}
OnConfigCallbackClass configCallBack = new OnConfigCallbackClass();
closeDeviceAfter
Flag to close the device after the request. Use:
true – close device
false – do not close the device
readerArgument
Extended command to send to reader.
destinationURL
MagneFlex will send the postback to this URL.
requestLocation
Flag to send GPS location of the device from which Magneflex (iOS only) is hosted.
Use:
true – send location
false – do not send location
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
Each input parameter supplied in the request is delimited by an ampersand character ‘&’, and the value for a parameter begins after an equal character ‘=’. Where ever a parameter contains multiple values, each are delimited by a comma character ‘,’.
Example query:
Return Value:
The Extended Command response output in Hex string format of device raw response for this command.
Parameter
Description
errorCode
Error status. 0 is Success. Non-Zero is an error.
errorMessage
Description of the errorCode.
opType
The type of operation. For this command the value is:
Operation to request from MagneFlex. Use: requestSendExtendedCommand
httpMethod
HTTP method to be used for the HTTP postback from MagneFlex. Use:
GET - returns the response data in the form of a query string. POST – recommended for EVM related transactions to accommodate limits on query string lengths.
Device refers to the MagTek devices that receives and responds to command set.
Host refers to the piece of general-purpose electronic equipment the device is connected or paired to, which sends data to and receives data from the device. Host types include but not limited to PC and Mac computers, tablets, and smartphones. When “host” must be used differently, it is qualified as something specific, such as “USB host.”
User in this document generally refers to the cardholder.
File name
Description
MTUSDKDemo.apk
Sample code APK file.
MTUSDK.aar
Universal SDK Android AAR Library file.
Tested operating systems:
Android 4.4.2 and above
Android Studio 3.5.3 and above
When connecting to the DynaFlex II PED device by WLAN, a client certificate and its certificate chain must be installed on the Android device. Root Certificate, Sub CA Certificate, and Client private key Certificate as referenced in document D998200550 DynaFlex II PED Using Wireless LAN Guide.
1
Download the certificate chain to the Android device.
2
The navigation paths for the following instructions may very on the Android device.
If not seen, do a search within Settings for the end of the navigation path.
3
Navigate to Settings --> Security --> More security settings --> Encryption & credentials --> Install a certificate
4
5
6
7
8
9
10
11
12
Custom software will need the client private key certificate (client.p12) when creating a connection to DynaFlex II PED WLAN. Place the client.p12 into a folder accessible by the custom software.
About the MagTek Sample Code
Nomenclature
SDK Contents
System Requirements
Certificate Requirements
closeDeviceAfter
Flag to close the device after the request. Use:
true – close device
false – do not close the device
readerArgument
Data to send for the device to be passed to MagneFlex. Arguments:
timeLimit:, option:, tone:, endSession:
Argument details:
timeLimit - Seconds the device will wait for the user to complete the operation in hexadecimal:
(1 - 255)
option - This is an ORed combination of flags that changes the device’s data entry request behavior. Value is decimal equivalent of the binary value.
Bits 0 and 1
destinationURL
MagneFlex will send the postback to this URL.
requestLocation
Flag to send GPS location of the device from which Magneflex (iOS only) is hosted.
Use:
true – send location
false – do not send location
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
Each input parameter supplied in the request is delimited by an ampersand character ‘&’, and the value for a parameter begins after an equal character ‘=’. Where ever a parameter contains multiple values, each are delimited by a comma character ‘,’.
Example query:
Return Value:
The CardSwipe output in TVL format.
Parameter
Description
errorCode
Error status. 0 is Success. Non-Zero is an error.
errorMessage
Description of the errorCode.
opType
The type of operation. For this command the value is:
HTTP method to be used for the HTTP postback from MagneFlex. Use:
GET - returns the response data in the form of a query string. POST – recommended for EVM related transactions to accommodate limits on query string lengths.
For devices using MQTT or WebSocket (WSS), configuring your host application and provisioning the device itself is mandatory to establish a successful secure connection. If connecting via USB HID, all steps listed in section 2 can be skipped.
Before using MQTT or WebSocket (WSS), configuration is required. From the Demo Application Home Page, select Misc. → Configuration for the Demos.
Figure 2 - Miscellaneous Configuration and Documentation Pages
Configure the Demo Application by supplying the necessary API keys and server addresses.
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. MagneSafe® is a registered trademark of MagTek, Inc. iDynamo™, and uDynamo are trademarks of MagTek, Inc.
eDynamo™, Dynamag, and DynaMAX are trademarks of MagTek, Inc. DynaFlex™, DynaFlex Pro™, and DynaProx™ are trademarks of MagTek, Inc.
Appendix D - Apple VAS
These instructions are for preparing Apple VAS (value-added service) transactions.
Set the Apple VAS Merchant ID and URL property for each slot 1 to 6 using IDeviceControl --> setConfigInfo().
Set the POS capabilities property using IDeviceControl à setConfigInfo().
iDynamo 5 Gen III Web-based Demo
This page provides access to interactive browser-based demonstrations for the iDynamo 5 Gen III, a secure card reader authenticator (SCRA) that uses MagTek's MagneSafe V5 (SRED) architecture. The demos show how to communicate with the device using WebHID for direct USB connections in Chromium-based desktop browsers, as well as MQTT for network communication via a local client application. These tools are designed to help developers quickly test device functionality and understand the integration process.
Status Codes and Responses
For SCRA V5 devices please refer to respective command reference:
D998200115 (eDyanmo)
D998200176 (Dynamag)
D998200175 (DynaMAX)
D99875483 (iDynamo)
D99875466 (MicrSafe)
For PINPAD devices please refer to the respective command reference:
Optional data to send to MagneFlex. This data will be passed back to the web app.
0 = Acct,Date,CVC
1 = Acct,Date
2 = Acct,CVC
3 = Acct
Bit 2
1=Use Qwick Codes entry
Bit 3
1=Use PAN in PIN block creation
Bit 4
0=Use PAN min 9, max 19
1=Use PAN min 14, max 21
tone – Beep behavior of prompt:
0 = None
1 = Single beep
2 = Double beep
endSession - Flag to end the session for the device. Default value is true.
“true” = End the session after the request is processed.
“false” = Do not end the session after the request is processed.
cardDataIn
Manual card entry data in TLV format.
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
ERROR
Error attempting the operation.
UNAVAILABLE
Status currently unavailable.
Microsoft®, Windows® and .NET® are registered trademarks of Microsoft Corporation.
EMV® is a registered trademark in the U.S. and other countries and an unregistered trademark elsewhere. The EMV trademark is owned by EMVCo, LLC. The Contactless Indicator mark, consisting of four graduating arcs, is a trademark owned by and used with permission of EMVCo, LLC.
All other system names and product names are the property of their respective owners.
Table 0.1 – Revisions
Rev Number
Date
Notes
10
January 9, 2023
Initial release
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 SUPPORT@MAGTEK.COM.
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.
TERMS, CONDITIONS, AND RESTRICTIONS
From the Home Page, select Misc. → Configuration for the Demos.
Enter and save the required settings.
RMS Options: Enter the Magensa API key and service URL
WebSocket Options: Provide the WebSocket server address.
MQTT Options: Specify the Org Node, broker address, client ID, and user credentials.
Contactless Options: Adjust timing parameters for NFC operations.
The separate MQTT Configuration page is used to provision your physical device with its Wi-Fi credentials and MQTT broker details.
Connect your device via USB HID.
Open the MQTT Configuration demo page.
Select Open to connect to your device.
Use the Wi-Fi Settings section to enter the device's SSID Name and SSID Password.
Use the MQTT Credentials section to enter the MQTT User, Password, and Org Node.
Select Save Config.
The device will record these settings, allowing it to connect to your broker over the network.
Connect the host PC to the same wireless network that your DynaFlex II PED device will be connected to.
Click Misc and click WSS Certificate and Trust Config
Click Open button
Select DynaFlex II PED and Click Connect.
Enter Wireless Network SSID and password, then click Set SSID
If you want to connect via non-secure TLS connection, press Load NoTLS Trust, and press Reset Device
If you want to configure via secure TLS, press Load TLS Trust, then press Get & Sign CSR, then Press Reset Device
By clicking on the MAGTEK Logo on the top of the page, go back to the Miscm Menu and press Configuration for the Demos option
Enter device host name under WebSocket Options, for Non-secure TLS, just put ws://device-hostname, for TLS secure connections, enter wss://device-hostname (example wss://df-1234567)
Click Save
Go back to home page and press MMS Devices for EMV, NFC, BCR and PIN, then press WSS Device Demo
Allow other devices on your local network
Click on Open which will all open the connection to the device:
The terminal should display a green dot indicating successful connection:
Configuring the Demo and Provisioning Your Device
Step 1: Configure Host Application Settings
Note: Configuration values must be entered and saved prior to establishing a secure session. Connection attempts without proper configuration will fail.
Step 2: Provision Device for MQTT
Note: Configuration values must be entered and saved prior to establishing a secure session. Connection attempts without proper configuration will fail.
Use the WebHID Demo to Connect Your Device via WebSocket
NOTE: The device hostname must be resolvable to an address using either DNS name resolution or creating a host file entry. See section below providing some options on resolvable DNS name.
Set the PaymentMethods to include PaymentMethod.AppleVAS.
Set AppleVASMode to: VASMode.Single, VASMode.Dual, or VASMode.VASOnly.
Set AppleVASProtocol to: VASProtocol.Full or VASProtocol.URL.
Data from an Apple VAS (9F27 and 9F2A) is returned in separate Apple VAS slot containers.
FE — var — VAS Data Container
FF01 — var — Apple VAS Container Slot 1 Container
9F27 — var — VAS Data. Up to 128 bytes.
9F2A — var — Mobile Token. Up to 36 bytes.
FF02 — var — Apple VAS Container Slot 2 Container
9F27 — var — VAS Data. Up to 128 bytes.
FF03 — var — Apple VAS Container Slot 3 Container
9F27 — var — VAS Data. Up to 128 bytes.
FF04 — var — Apple VAS Container Slot 4 Container
9F27 — var — VAS Data. Up to 128 bytes.
FF05 — var — Apple VAS Container Slot 5 Container
9F27 — var — VAS Data. Up to 128 bytes.
FF06 — var — Apple VAS Container Slot 6 Container
9F27 — var — VAS Data. Up to 128 bytes.
Merchant ID and URL Slots
POS Capabilities
Start Transaction
Transaction Response
Directs you to the companion client application required for MQTT-based communication. This local software acts as a bridge, enabling the iDynamo 5 Gen III to connect to the cloud-based demos and services that use the MQTT messaging protocol.
Launches an interactive web-based demo that enables direct communication with an iDynamo 5 Gen III device from a Chromium browser. This tool allows you to test card reading, validate device connectivity, and experiment with MagneSafe V5 commands without writing any code.
Web Demo
Select CA certificate .
Confirm any prompts such as Install anyway .
Select the rootCA.crt file.
Continue to install the subCA by selecting CA certificate .
Confirm any prompts such as Install anyway .
Select the subCA.crt file.
Verify the certificate chain by navigating to Settings --> Security --> More security settings --> Encryption & credentials --> Trusted credentials.
INFORMATION IN THIS PUBLICATION IS SUBJECT TO CHANGE WITHOUT NOTICE. MAGTEK CANNOT BE HELD LIABLE FOR ANY USE OF THE CONTENTS OF THIS DOCUMENT. ANY CHANGES OR IMPROVEMENTS MADE TO THIS PRODUCT WILL BE INCLUDED IN THE NEXT PUBLICATION RELEASE. IF YOU HAVE QUESTIONS ABOUT SPECIFIC FEATURES AND FUNCTIONS OR WHEN THEY WILL BECOME AVAILABLE, PLEASE CONTACT YOUR MAGTEK REPRESENTATIVE.
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 of 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. UL™ and the UL logo are trademarks of UL LLC.
PCI Security Standards Council® is a registered trademark of the PCI Security Standards Council, LLC. EMV® is a registered trademark in the U.S. and other countries and an unregistered trademark elsewhere. The EMV trademark is owned by EMVCo, LLC. The Contactless Indicator mark, consisting of four graduating arcs, is a trademark owned by and used with permission of EMVCo, 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, Google Wallet™ payment service, and Android™ platform are trademarks of Google LLC.
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 StoreSM 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.
The Linux edition of the MagTek Universal SDK (MTUSDK), giving developers a single interface for connecting to and controlling MagTek card readers and PIN pad devices — including the DynaFlex family — from Linux host applications. The complete API reference is available as a PDF download below.
In This Section
Reference Section
Information Available
MagTek Universal SDK for Linux applications — downloadable PDF reference.
Need More Help
Need Help?
For additional support, please contact MagTek Support:
Technical Support:
📧 Email:
User Instructions
The user must load the most current DynaFlex II GO firmware before beginning. Follow these steps to update your DynaFlex II GO Firmware:
Set Profile to SmartTab
From the Connect tab, ensure the Profile Name is set to SmartTab and Tap on the Device you want to connect to.
Update Firmware
After Connecting a DynaFlex II GO to RMS, press the Device tab. To update device firmware, check the Firmware option only, and press the Update button. Only the updates that are checked will be loaded to the device. A prompt will appear asking the user not to manually turn off the screen, press OK .
Log Data
The log will indicate:
If current configurations are up to date,
If updates have succeeded,
If updates have failed
To update or change your device’s configurations to include SCDE, begin by loading the SCDE Key:
Tap on LoadSelectableCardDataEncryptionKey first.
Press the Refresh button to refresh the list of available configurations if LoadSelectableCardDataEncryptionKey does not appear.
Press the Update button to load the key.
The log will indicate if the configuration update is successful or if it has failed.
To load SCDE Enable Name Expiration Date Service Code:
Tap on LoadSelectableCardDataEncryptionKey first.
Press the Refresh button to refresh the list of available device updates if LoadSelectableCardDataEncryptionKey does not appear.·
Press the Update button to load the key.
The log will indicate if the configuration update is successful or if it has failed
After completing the steps, the device will support Selectable Card Data Encryption, allowing the user to view card data outside of a transaction scenario.
Using the Demo Pages
These instructions detail the operational steps once all necessary configurations (Section 2) are complete. If connecting via USB HID, the steps listed in section 2 can be skipped.
The Human Interface Device (HID) protocol enables driverless plug-and-play connectivity for your device via USB.
Ensure the device is powered on and connected via USB.
If this is the first time, you may have to pair the device in the Chromium browser, which involves granting the website permission via a pop-up prompt.
requestCardSwipe
This query string instructs the device to prompt for a card swipe.
requestData (MICR Only)
This query string retrieves data from user interaction with the device.
How to use the Firmware Update Utility
This document provides the instructions to update firmware into a MagTek DynaFlex or DynaProx device on a Windows PC via USB connection.
A Windows 10 host with available USB port
Microsoft .NET 4.6.1 and above.
ISystemStatusCallback Delegates
This interface invokes callback functions to receive data and/or a detailed response. To register for the event(s), call the setSystemStatusCallback() function with the name of a class that implements the ISystemStatusCallback interface.
This event is called when an error occurs with the connection with the MQTT broker.
Load SCDE Enable Name Expiration Date Service Code
Description
error
Type of error enumeration.
details
Details of the error.
Return Value: None
void OnError(
ErrorType error,
String details);
OnError
From the Demo Application, select Open, and choose the appropriate device. A green check mark confirms the device is successfully opened.
From the command dropdown menu, select a command such as DynaFlex: START EMV ALL.
Select Send Command to execute the action.
Insert or tap a test card and monitor the transaction log for the response.
Figure 3 - HID MMS Demo
Message Queuing Telemetry Transport (MQTT) is a lightweight messaging protocol commonly used for Internet of Things (IoT) applications. It provides efficient, reliable communication between devices and applications, even in environments with limited connectivity. IMPORTANT: DynaFlex II PED is the only device that supports native MQTT. All other Dyna Devices must use the HID MQTT Device Client.
Key characteristics include:
Publish/Subscribe model – Devices publish data to a central broker; applications subscribe to receive data.
Low overhead – Messages are compact and efficient, suitable for embedded systems.
Real-time updates – Events such as card insertions are transmitted immediately to the Demo Application.
Cross operating system and cross browser connectivity: MQTT ensures seamless interaction because it is platform-agnostic, meaning devices running Windows, Linux, macOS, or embedded OS, and applications running in different browsers, can all connect and exchange messages reliably.
Within the HID MQTT Device Client and MQTT MMS Demo, this protocol enables MagTek MMS devices (e.g., Dyna Family Devices) to securely communicate via MQTT across operating systems.
Figure 4 - MQTT Geographic Map
Figure 5 - MQTT MMS Demo
Configured Device – Identifies the active device.
Status Indicator – A green check mark indicates a successful connection.
Options – Auto Start, EMV, NFC, and MSR session checkboxes.
Command Data – Field for entering or pasting hexadecimal command data.
Controls – Dropdown for pre-defined commands (e.g., START EMV) and Send Command button.
Device Instances – Displays connected devices with selectable IDs.
File Upload – Allows uploading of command scripts or batch test files.
The command above, and others can be selected from the pulldown menu. The Choose File button allows the user to upload custom commands from a file. This screen also confirms device recognition, command formatting, and connectivity prior to further testing.
The HID MQTT Device Client acts as a communication gateway that transforms your locally connected MagTek device (via USB HID) into a remote asset. This allows other applications to access the device securely via the MQTT protocol. IMPORTANT: DynaFlex II PED is the only device that supports native MQTT which means it does NOT need to use the HID MQTT Device Client.
Power on and connect the device via USB.
Open the HID MQTT Device Client page.
Select Open within the client.
Scan the QR code or select the provided link to open the separate MQTT Device Demo Application.
From the MQTT Device Demo Application’s dropdown, select the required command, or use Choose File to upload a custom command script.
Select Send Command to execute the command remotely.
Figure 6 - HID MQTT Device Client
The MQTT Geographic Map displays device location and status for connected units, see Figure .
The MQTT Configuration page provides controls and parameters necessary for device operation over MQTT.
Device Status Panel – Displays device information (model, name, IP address, SSID) and records configuration progress.
Controls – Includes Open, Save Config, Reset Device, Close, and Clear.
Wi-Fi Settings – SSID and password configuration.
MQTT Credentials – Org Node, username, and password for broker authentication.
Once configuration is complete and saved, the user may proceed to execute commands such as Start EMV. See Figure 7 - MQTT Configuration.
Figure 7 - MQTT Configuration
This interface is used to configure secure communication with WebSocket transport using TLS or mTLS. Functions include:
Network Settings – Get DHCP and Set SSID.
Wi-Fi Setup – Retrieve or assign SSID and password credentials.
Certificate and Trust Management – Load TLS/mTLS certificates, verify certificates, and generate or sign Certificate Signing Requests (CSR).
For NonTLS connection,
Click Load NoTLS Trust
Next, reset the device.
For TLS/mTLS connections,
Click Load TLS Trust or Load mTLS Trust
Next, click Get & Sign CSR
Controls – Open, Close, Clear, and Reset Device.
Device Identity – Display or update the registered device name and IP address.
Root CA Download – Provides access to the root certificate authority file for verification.
Figure 8 - WebSocket Certificate and Trust Configuration
When using WSS (WebSockets over SSL/TLS) with DynaFlex devices, the following technical considerations are critical for IT teams to ensure reliable and secure communication.
The default SSL certificate pre-installed on DynaFlex devices is uniquely generated for each device and tied to a hostname in the format df-[SerialNumber] (e.g., df-1234567). This certificate is used to establish the WSS connection.
SSL/TLS certificates are literal. The browser (or any WebSocket client) validates that the hostname used in the connection URL exactly matches the certificate's Subject Name or Subject Alternative Name (SAN). If the URL uses wss://df-1234567/ but the network appends a domain suffix (e.g., df-1234567.office.lan), the browser will reject the connection as insecure because the names do not match.
IP addresses cannot be used. Connecting via wss://192.168.1.50/ will trigger a SAN missing error because the certificate is issued to a name, not an IP address.
Therefore, the network must be configured to resolve the short hostname (e.g., df-1234567) to the device's IP address. The following options are available:
Option A: Global Search Suffix (Recommended)
Configure the DHCP server to add a Connection-Specific DNS Suffix (via DHCP Option 15/119). This allows client computers to automatically map the short name to the device without manual DNS entries.
Action: Add your local domain to the DHCP option list so that df-[SerialNumber] resolves correctly.
Option B: The "Trailing Dot" Override
If DNS search suffixes are misconfigured or polluted, you can force the browser to look for the bare hostname by appending a trailing dot to the URL.
Standard URL: wss://df-12345678/ (the OS may append the domain)
Forced URL: wss://df-12345678./ (the trailing dot forces an exact hostname lookup)
Option C: CNAME or A-Record in Local DNS
For networks with a central DNS server, create a static entry.
Action: Create a forward lookup zone with an A record (or CNAME) for df-[SerialNumber] pointing to the device's static IP address.
The WSS connection relies on a server certificate installed on the device. As of this writing, the demo application signs certificates with a validity period of 13 months. After expiration, any WSS communication will fail silently due to browser security policies—no manual override is possible for WebSocket connections.
Best Practice: Certificates must be replaced before they expire. A certificate update strategy must be employed when deploying devices in production using WSS.
Renewal Process: Use the WSS Certificate and Trust page to generate a new Certificate Signing Request (CSR) and load a renewed certificate. Refer to the steps for loading TLS trust and resetting the device.
Monitoring: Implement monitoring to alert administrators when certificate expiration is approaching (e.g., 30 days prior).
By adhering to these hostname resolution and certificate lifecycle guidelines, you ensure uninterrupted and secure WSS communication with your DynaFlex devices.
Example Command Data (Hexadecimal): (Start Transaction command (arms Contact, Contactless and MSR interfaces))
HID MQTT Device Client
2.1 MQTT Configuration Page
WSS Certificate and Trust
Error Condition: If the status window displays “OpenDevice No HID device selected or found”, ensure the reader is connected via USB HID prior to attempting certificate operations.
Technical Notes on WSS Hostname Resolution and Certificate Lifecycle
Hostname Constraint and Certificate Matching
Certificate Expiration and Renewal Strategy
closeDeviceAfter
Flag to close the device after the request. Use:
true – close device
false – do not close the device
readerArgument
Comma delimited list of arguments to be passed to MagneFlex. requestCardSwipe requires no arguments.
destinationURL
MagneFlex will send the postback to this URL.
requestLocation
Flag to send GPS location of the device from which Magneflex (iOS only) is hosted.
Use:
true – send location
false – do not send location
passInData
Optional data to send to MagneFlex. This data will be passed back to the web application.
Each input parameter supplied in the request is delimited by an ampersand character ‘&’, and the value for a parameter begins after an equal character ‘=’. Where ever a parameter contains multiple values, each are delimited by a comma character ‘,’.
Example query:
Return Value:
The CardSwipe output in TVL format.
Parameter
Description
errorCode
Error status. 0 is Success. Non-Zero is an error.
errorMessage
Description of the errorCode.
opType
The type of operation. For this command the value is:
HTTP method to be used for the HTTP postback from MagneFlex. Use:
GET - returns the response data in the form of a query string. POST – recommended for EVM related transactions to accommodate limits on query string lengths.
Message to display within the browser to instruct user interaction (iOS only).
closeDeviceAfter
Flag to close the device after the request. Use:
true – close device
false – do not close the device
readerArgument
Comma delimited list of arguments to be passed to MagneFlex. Arguments:
timeLimit:
Argument details:
timeLimit - Seconds the device will wait for the user to complete the operation in hexadecimal.
(1 - 255)
destinationURL
MagneFlex will send the postback to this URL.
requestLocation
Flag to send GPS location of the device from which Magneflex (iOS only) is hosted.
Use:
true – send location
false – do not send location
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
Each input parameter supplied in the request is delimited by an ampersand character ‘&’, and the value for a parameter begins after an equal character ‘=’. Where ever a parameter contains multiple values, each are delimited by a comma character ‘,’.
Example query:
Return Value:
The Command response output in TVL format.
Parameter
Description
errorCode
Error status. 0 is Success. Non-Zero is an error.
errorMessage
Description of the errorCode.
opType
The type of operation. For this command the value is:
HTTP method to be used for the HTTP postback from MagneFlex. Use:
GET - returns the response data in the form of a query string. POST – recommended for EVM related transactions to accommodate limits on query string lengths.
https://192.168.10.100/magneflexdemo/default.aspx?
operation=requestData
&httpMethod=GET
&customDisplayMessage=Please Swipe Card or Scan a Check
&closeDeviceAfter=true
&readerArgument=
timeLimit:3C
&destinationURL=https://192.168.10.100/magneflexdemo/cardpostback.aspx
&requestLocation=false
&passInData=testData
Connect a DynaFlex or DynaProx to the USB port of the Windows PC.
Launch the DynaFlex, DynaProx Firmware Update Utility.
Press the Scan button to update the list of devices.
Select a device from the list, then press the Connect button to connect to the device.
The status will display Connected .
Press the Browse button, select the firmware file, and then press the Open button.
The software will automatically detect the firmware type.
Press the Start Firmwre Upload button to begin the upload.
Wait until the Firmware Upload is complete. The progress of the upload will change to prepare, downloading, and updating.
After uploading, the DynaFlex, DynaProx Firmware Update Utility will display Firmware Successfully Updated . Press the OK button. The device will automatically reboot after a completed firmware update.
If you want to get current information about the device such as firmware version, firmware hash, select the desired information under the Info drop down and press the Get Info button.
Introduction
System Requirements
Connect via USB Interface
Upload Firmware
DO NOT power off or disconnect during the upload.
Classes - N - Z
NFCData
These constructors initialize an NFCData object. Use NFCDataBuilder.GetNFCData with the data byte array from the NFCData event to return an NFCData.
NFCData NFCDataBuilder.GetNFCData(deviceType, byte[] dataBytes);
new NFCData(byte[] Data, boolean Encrypted);
new NFCData(
byte[] Data,
boolean Encrypted,
byte EncryptionType,
byte[] KSN
);
Member
Description
Data()
Returns the data payload.
Encrypted()
Return Value:
Returns an instance of NFCData.
These constructors initialize an NFCRAPDUData object. Use NFCDataBuilder.GetNFCRAPDUData with data byte array from the NFCRAPDUResponse event to return an NFCRAPDUData.
Parameter
Description
Return Value:
Returns an instance of NFCRAPDUData.
This class assist in parsing NFCEvent data.
Member
Return
Description
Member
Value
Description
These constructors initialize a PersonalInfoEntry object.
Call startPersonalInfoEntry().
At OnEvent():TouchscreenPersonalInfoEntry, build the object.
INFORMATION IN THIS PUBLICATION IS SUBJECT TO CHANGE WITHOUT NOTICE. MAGTEK CANNOT BE HELD LIABLE FOR ANY USE OF THE CONTENTS OF THIS DOCUMENT. ANY CHANGES OR IMPROVEMENTS MADE TO THIS PRODUCT WILL BE INCLUDED IN THE NEXT PUBLICATION RELEASE. IF YOU HAVE QUESTIONS ABOUT SPECIFIC FEATURES AND FUNCTIONS OR WHEN THEY WILL BECOME AVAILABLE, PLEASE CONTACT YOUR MAGTEK REPRESENTATIVE.
MagTek®, MagnePrint®, and MagneSafe® are registered trademarks of MagTek, Inc. Magensa™ is a trademark of MagTek, Inc.
DynaPro™ and DynaPro Mini™, are trademarks 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).
ISO® is a registered trademark of the International Organization for Standardization. UL™ and the UL logo are trademarks of UL LLC.
PCI Security Standards Council® is a registered trademark of the PCI Security Standards Council, LLC.
EMV® is a registered trademark in the U.S. and other countries and an unregistered trademark elsewhere. The EMV trademark is owned by EMVCo, LLC. The Contactless Indicator mark, consisting of four graduating arcs, is a trademark owned by and used with permission of EMVCo, 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, Google Wallet™ payment service, 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 StoreSM 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.
IDeviceCapabilities
Create an instance of the IDeviceCapabilities using IDevice.getCapabilities(). Then use the functions described in this chapter.
BatteryBackedClock
This property returns true if the device is equipped with a battery that preserves the internal clock when not powered by a host system or charging.
Copy
boolean IDeviceCapabilities.BatteryBackedClock();
Return Value:
Returns true if device is equipped with a battery backed clock. Otherwise, returns false.
Display
This property returns true if the device is equipped with display.
Copy
Return Value:
Returns true if device is equipped with a display. Otherwise, returns false.
This property returns true if the device has the option to disable or enable the magnetic stripe reader head (MSR). The MSR may be powered down while the device is idle to minimize power consumption.
Copy
Return Value:
Returns true if device supports MSR power saver. Otherwise, returns false.
This property returns an enumerate list of payment methods supported by the device.
Copy
Return Value:
Returns a list of PaymentMethod.
This property returns true if the device is equipped with a PIN Pad.
Copy
Return Value:
Returns true if device is equipped with a PIN Pad. Otherwise, returns false.
This property returns true if the device is equipped with signature capture.
Copy
Return Value:
Returns true if device is equipped with signature capture. Otherwise, returns false.
This property returns true if the device supports Secure Reading and Exchange of Data.
Copy
Return Value:
Returns true if device supports SRED. Otherwise, returns false.
ConnectionInfo
Create an instance of the ConnectionInfo using IDevice.getConnectionInfo(). Then use the function calls described in this chapter.
getAddress
This function returns address of the device.
String ConnectionInfo.getAddress();
Return Value:
Returns the address of the device.
getConnectionType
This function returns the type of connection Interface for the device.
This enum refers to a featured supported by the device.
Enum
Description
Web-based Demos for MMS Dyna Devices
This page provides an interactive web-based demonstration for MagTek MMS Dyna devices, showing how to communicate with Secure Card Reader Authenticators (SCRA) using multiple interfaces—including WebHID, MQTT, WebSocket (WSS), WebSerial, and WebBLE—for flexible, real-time device integration and testing.
Web-based Demo
Web Demo
Description
This page provides an interactive WebHID demonstration for MMS Dyna devices, enabling direct USB communication using Chromium-based browsers to send commands and receive real-time device responses.
CoreAPI
Use the CoreAPI to create an IDevice. IDevice is the bases for the MagTek Universal SDK.
If accessing a device specific API outside of MagTek Universal SDK, use the various functions in this section to create an instance of that device’s API. Once a device specific API is referenced, the associated library will need to be added into the application’s development project.
This function creates an instance of a CMS type of device.
The API’s of MagTek Universal SDK do not apply. See D998200160 MagTek Common Message Structure (MTCMS) for the MTCMS API.
Parameter
Libraries & Downloads
Download the SDK packages, libraries, and components referenced throughout this
section — including the Universal SDK builds and related developer libraries.
cardDataIn
Magnetic swipe card data in TLV format.
FA (Container for generic data) DFDF25 (Device serial number)
This page provides a local client application that enables MQTT-based communication with MMS devices, acting as a bridge for secure publish/subscribe messaging between browser demos and connected hardware.
This page provides an interactive demonstration of MQTT messaging with MMS Dyna devices, allowing developers to send and receive device data using a lightweight publish/subscribe communication model.
This page provides a browser-based demonstration of secure WebSocket (WSS) communication with supported MMS devices, enabling persistent, full-duplex, real-time data exchange over a single TCP connection.
This page provides an interactive WebSerial demonstration for MMS devices, allowing direct serial communication from a browser to test command transmission and device response handling.
This page provides a browser-based demonstration of Bluetooth Low Energy (BLE) communication with MMS devices, enabling wireless connectivity and data exchange using Web Bluetooth APIs.
context — An instance of android.content.Context to allow SDK access to application-specific resources.
handler — An instance of android.os.Handler to allow SDK access to application-specific message queues.
Return Value:
Returns an MTDevice.
This function creates an instance of IDevice. All API’s of MagTek Universal SDK can but utilized from IDevice.
Parameter
context — An instance of android.content.Context to allow SDK access to application-specific resources.
deviceType — Enumerated device type.
connectionType — Enumerated connection type.
address — Address for the device.
For USB devices, address may be an empty string when only one device is attached. Otherwise address should be in the form:
USB://DEVICESERIALNUMBER
for example, USB://99261829170E0810
For Ethernet devices, address should be in the form:
model — Model name for the device.
name — Unique name for the device to distinguish between multiple devices of the same model.
serial — Serial number for the device.
certificateInfo — The client private key certificate (client.p12) into a folder accessible by the custom software. See Certificate Requirements.
Return Value:
Returns an IDevice.
This function creates an instance of an MMS type of device, DynaFlex Family.
Parameter
context — An instance of android.content.Context to allow SDK access to application-specific resources.
deviceAdapter — Callback interface for MMS device messages.
Return Value:
Returns an MMXDevice.
This function creates an instance of an MTPPSCRA type of device.
The API’s of MagTek Universal SDK do not apply. See D998200078 IPAD, DynaPro, DynaPro Go, and DynaPro Mini PIN Encryption Devices Programmer’s Reference for the MTPPSCRA API.
Parameter
context — An instance of android.content.Context to allow SDK access to application-specific resources.
handler — An instance of android.os.Handler to allow SDK access to application-specific message queues.
Return Value:
Returns an MTPPSCRA.
This function creates an instance of a MTSCRA type of device.
The API’s of MagTek Universal SDK do not apply. See D99875723 uDynamo, Dynamag, DynaMAX, eDynamo, mDynamo, Insert, DynaWave, iDynamo 6 for the MTSCRA API.
Parameter
context — An instance of android.content.Context to allow SDK access to application-specific resources.
handler — An instance of android.os.Handler to allow SDK access to application-specific message queues.
Return Value:
Returns an MTSCRA.
This function returns a list of IDevice. IDevice is the base for utilizing the MagTek Universal SDK interface.
Parameter
context — An instance of android.content.Context to allow SDK access to application-specific resources.
deviceType — An enum for the type of MagTek readers which the SDK will control.
deviceTypes — An enum list for the type of MagTek readers which the SDK will control.
deviceListCallback — Callback interface for SDK to provide a list of device information in the system.
Return Value:
Returns a list of IDevice
This function returns the API version.
Return Value:
Returns an integer representing the API version.
This function sets the MQTT (Message Queuing Telemetry Transport) broker information. Call prior to device discovery.
This function sets the MQTT client ID to establish a connection.
Parameter
clientID — Client ID. If not set, the default value is [HostName]-[RandomUUID]
Return Value: None
This function sets the MQTT certificate information.
Parameter
certificateInfo — If client certificate is required when initiating a connection to the MQTT broker, this shall be used to establish the connection. If not set, the default value is NULL.
Return Value: None
This function sets the MQTTDeviceDiscoveryTimeout value.
Parameter
timeout — Time out in milliseconds. Default value = 5000 if not set. A call to getDeviceList() does not return the list until this time has expired.
Return Value: None
This function sets the MQTT callback interface instance.
After connecting to the MQTT broker, the MQTT Device Status Monitoring subscribes to
"<MQTTSubscribeTopic>/#" . The wildcard "/#" is automatically appended.
Example:
When a device status updates to “connected” or “disconnected”, OnConnected() and OnDisconnected() are invoked respectively.
This method can be called whether or not there is an active connection to an MQTT device.
Devices reporting with "/Status/connected" are added to the device list as follows:
Parameter
callback — Name of a class or structure that implements the IMQTTDeviceStatusCallback interface events. Call after calling getDeviceList().
Return Value: None
This function sets the base value for MQTTPublishTopic. When connected to the MQTT broker, the composed topic is in the format:
Example:
Base topic = “MagTek/Device/DynaFlexIIPED/”
Full topic = “MagTek/Device/DynaFlexIIPED/B51E72D/MMSMessage”
Parameter
topic — Base topic for which to publish messages. Full topic is composed by the SDK.
Return Value: None
This function sets the MQTTQoS value.
Parameter
qos — The quality of service level for publishing messages. Range:
0 = At most once (default)
1 = At least once
2 = Exactly once
Return Value: None
This function sets the base value for MQTTSubscribeTopic. When connected to the device, the composed topic is in the format:
“<basetopic>/<DeviceID>/MMSMessage”.
Example:
Base topic = “MagTek/Server/DynaFlexIIPED/”
Full topic = “MagTek/Server/DynaFlexIIPED/B51E72D/MMSMessage”
Parameter
topic — Base topic for which to subscribe for messages.
Return Value: None
This function stops the MQTT device status monitoring process. If called when already running, the process shall be stopped immediately. This method can be called whether or not there is an active connection to an MQTT device.
Return Value: None
This function sets the SystemStatusCallback global value.
Parameter
callback — Name of a class or structure that implements the ISystemStatusCallback interface event. Call before starting any MQTT communication. When there is an error, the interface’s OnError() event is invoked.
Build against MMS readers from iOS — libraries for connecting over USB or Bluetooth LE and exchanging the MMS command set in your iOS app.
Build against MMS readers from Linux — libraries for connecting to a device and exchanging the MMS command set on Linux hosts.
Instructions for software developers who want to create Android software solutions that include MagTek devices connected to an Android based host.
Reference Section
Information Available
MTUSDK Omni is a sample application designed and developed to work with MagTek iOS MTUSDK and delivers the ability to communicate with MagTek's card readers.
Build against MMS readers from .NET — libraries and APIs for connecting to a device, sending commands, and handling responses and notifications on Windows and other .NET hosts.
Each input parameter supplied in the request is delimited by an ampersand character ‘&’, and the value for a parameter begins after an equal character ‘=’. Where ever a parameter contains multiple values, each are delimited by a comma character ‘,’.
Example query:
Return Value:
The Command response output in TVL format.
Example:
Each input parameter supplied in the request is delimited by an ampersand character ‘&’, and the value for a parameter begins after an equal character ‘=’. Where ever a parameter contains multiple values, each are delimited by a comma character ‘,’.
Example query:
Return Value:
The Signature capture output in TVL format.
Example:
requestSendCommand
This query string sends a command to the device and returns the raw response from the device.
Each input parameter supplied in the request is delimited by an ampersand character ‘&’, and the value for a parameter begins after an equal character ‘=’. Where ever a parameter contains multiple values, each are delimited by a comma character ‘,’.
Example query:
Return Value:
The Command response output in Hex string format of device raw response for this command.
Example:
Appendix E - Google Wallet Smart Tap VAS
These instructions are for preparing Google Wallet Smart Tap VAS (value-added service) transactions.
Mobile Device
Configure the mobile device for Google Wallet Smart Tap Pass.
Load Key
Load the LTPK protection key (Long Term Private Key) into the MagTek device.
Upload a Public Key to the Google Pay & Wallet Console for the issuer account associate with the Google Wallet Pass.
Set the Google Smart Tap Collector ID property for each slot 1 to 6 using IDeviceControl à setConfigInfo().
Set the POS capabilities property using IDeviceControl à setConfigInfo().
Set the PaymentMethods to include PaymentMethod.GoogleVAS.
Set AppleVASMode to: VASMode.Single, VASMode.Dual, or VASMode.VASOnly.
Data from a Google Wallet Smart Tap (DF7B) is returned in separate Collector ID slot containers associated with the Google Wallet Pass.
Tag
Length
Value / Description
Universal SDK Documentation
The Universal SDK is MagTek's cross-platform SDK for building against MMS (DynaFamily) readers. It wraps the MMS command set in native calls for each platform — handling connection, sending commands, and receiving responses and notifications — so you work in your language instead of composing raw messages. Choose your platform below; the command each call maps to is documented in the API & Command Reference.
In This Section
Reference Section
Information Available
.NET (Windows)
Build against MMS readers from .NET — libraries and APIs for connecting to a device, sending commands, and handling responses and notifications on Windows and other .NET hosts.
requestSendBatchCommand (Reserved for Future Use)
This query string sends a batch of commands to the device and returns the raw response from the device.
Operation to request from MagneFlex. Use: requestSendBatchCommand
httpMethod
Each input parameter supplied in the request is delimited by an ampersand character ‘&’, and the value for a parameter begins after an equal character ‘=’. Where ever a parameter contains multiple values, each are delimited by a comma character ‘,’.
Return Value:
The Batch Command response output in Hex string format of device raw response for this command.
Classes
Classes
Reference for the individual classes in the MagTek Universal SDK — the data objects used to configure commands and read structured results back from the device. Entries are listed alphabetically across two pages, Classes A–I and Classes N–Z.
In This Section
Reference Section
Information Available
Alphabetical reference for the SDK's data and result classes (Classes A–I).
Demos & Sample Code
See MagTek readers in action and start from working code. This section collects runnable demos and sample code — including a browser-based demo you can try without installing anything — to validate your setup and give you a starting point for your own integration.
In This Section
Reference Section
Information Available
A browser demo that runs the command set over WebHID.
Java
Universal SDK Documentation (Java)
The Java edition of the MagTek Universal SDK (MTUSDK), giving developers a single interface for connecting to and controlling MagTek card readers and PIN pad devices — including the DynaFlex family — from Java host applications. The complete API reference is available as a PDF download below.
In This Section
Reference Section
Information Available
MagTek Universal SDK for Java applications — downloadable PDF reference.
Need More Help
Need Help?
For additional support, please contact MagTek Support:
Technical Support:
📧 Email:
Enumerations
Enumerations
Reference for the enumerated types used throughout the MagTek Universal SDK — the named constants for values such as device and transaction states, card types, and command options that appear in SDK calls and results. The enumerations are listed alphabetically across two pages.
In This Section
Reference Section
Information Available
Reference for the SDK's enumerated types (device and transaction states, card types, option flags).
Appendix C - Warranty and Software License
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.
How to use the OID Converter Console Demo
This document provides instructions to use the OID Converter Console. It is part of a larger library of documents designed to assist Secure Card Readers implementers, which includes the following documents available from MagTek:
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. MagneSafe® is a registered trademark of MagTek, Inc. DynaFlex, DynaProx are trademarks of MagTek, Inc.
Microsoft®, Windows® and .NET® are registered trademarks of Microsoft Corporation.
EMV® is a registered trademark in the U.S. and other countries and an unregistered trademark elsewhere. The EMV trademark is owned by EMVCo, LLC. The Contactless Indicator mark, consisting of four graduating arcs, is a trademark owned by and used with permission of EMVCo, LLC.
All other system names and product names are the property of their respective owners.
.NET (Windows)
The .NET edition of the MagTek Universal SDK (MTUSDK), giving developers a single managed interface for connecting to and controlling MagTek card readers and PIN pad devices — including the DynaFlex family — from Windows .NET applications. The complete API reference is available as a PDF download below.
iOS
The iOS edition of the MagTek Universal SDK (MTUSDK), giving developers a single interface for connecting to and controlling MagTek card readers and PIN pad devices — including the DynaFlex family — from native iOS apps. The complete API reference is available as a PDF download below.
IP://IP-Address:PORT
for example, IP://10.57.10.180:26
For Wireless devices, address should be in the form:
Optional data to send to MagneFlex. This data will be passed back to the web app.
HTTP method to be used for the HTTP postback from MagneFlex. Use:
GET - returns the response data in the form of a query string. POST – recommended for EVM related transactions to accommodate limits on query string lengths.
readerArgument
Batch of commands that should be sent to reader. Commands are delimited by the bar character ‘|’.
Example:
readerArgument=0900|000100|1500
destinationURL
MagneFlex will send the postback to this URL.
requestLocation
Flag to send GPS location of the device from which Magneflex (iOS only) is hosted.
Use:
true – send location
false – do not send location
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
Parameter
Description
errorCode
Error status. 0 is Success. Non-Zero is an error.
errorMessage
Description of the errorCode.
opType
The type of operation. For this command the value is:
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 support@magtek.com
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.
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.
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 IN 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 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 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 SUPPORT@MAGTEK.COM.
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.
Limited Warranty
Limitation On Liability
SOFTWARE LICENSE AGREEMENT
TERMS, CONDITIONS, AND RESTRICTIONS
Table 0.1 – Revisions
Rev Number
Date
Notes
10
October 5, 2020
Initial release
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 SUPPORT@MAGTEK.COM.
Manual Part Number: D100005288-10
REGISTERED TO ISO 9001:2015
SOFTWARE LICENSE AGREEMENT
TERMS, CONDITIONS, AND RESTRICTIONS
commandID
Command that was sent.
commandResult
Data returned from the command sent to the device.
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
HTTP method to be used for the HTTP postback from MagneFlex. Use:
GET - returns the response data in the form of a query string. POST – recommended for EVM related transactions to accommodate limits on query string lengths.
closeDeviceAfter
Flag to close the device after the request. Use:
true – close device
false – do not close the device
readerArgument
Comma delimited list of arguments to be passed to MagneFlex. Arguments:
timeLimit:, command:, endSession:
Argument details:
timeLimit - Seconds to wait before the operation times out. Value is in hexadecimal format.
(00 - FF)
command - The command to send to the device.
endSession - Flag to end the session for the device. Default value is true.
“true” = End the session after the request is processed.
“false” = Do not end the session after the request is processed.
destinationURL
MagneFlex will send the postback to this URL.
requestLocation
Flag to send GPS location of the device from which Magneflex (iOS only) is hosted.
Use:
true – send location
false – do not send location
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
Parameter
Description
errorCode
Error status. 0 is Success. Non-Zero is an error.
errorMessage
Description of the errorCode.
opType
The type of operation. For this command the value is:
SEND_COMMAND_RESULT
The console app accepts 2 input parameters: OID & Command Data. The result is the data to pass to MTUSDK commands getConfigInfo() and setConfigInfo().
When getting a configuration, only input the OID.
Launch a command terminal where the oidconverter.exe is located.
Type oidconverter and an OID in decimal format as shown below, then ENTER. The OID may also be typed in hexadecimal as commented out below.
The console app displays the Input OID and Converted OID as shown below.
Use the Converted OID when getting a property value with the MTUSDK API getConfigInfo().
When calling the function getConfigInfo, parameter configType is the first number of the OID. 2.1.2.2.2.1
When setting a configuration, input the OID and the Command Data.
Launch a command terminal where the oidconverter.exe is located.
Type oidconverter, an OID, in decimal format, and a Value in hexadecimal as shown below, then ENTER.
The OID may also be typed in hexadecimal as commented out below.
The console app displays the Input OID and Converted OID as shown below.
Use the Converted OID when setting a property value with the MTUSDK API setConfigInfo().
When calling the function getConfigInfo, parameter configType is the first number of the OID. 1.2.3.1.1.1
byte configType = 0x01;
byte[] data = {0xE2,0x0C,0xE3,0x0A,0Xe1,0x08,0xE1,
0x06,0xC1,0x04,0x03,0x00,0x00,0x00};
int response = devConfig.setConfigInfo(configType, data, this);
commandID
Command that was sent.
commandResult
Data returned from the command sent to the device.
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
readerArgument
Comma delimited list of arguments to be passed to MagneFlex. Arguments:
timeLimit:, option:, tone:, endSession:
Argument details:
timeLimit - Seconds the device will wait for the user to complete the operation in hexadecimal.
(1 - 255)
option:
0 = Timeout clears any signature data
1 = Timeout returns timeout status plus length collected. Sig Data can be requested.
destinationURL
MagneFlex will send the postback to this URL.
requestLocation
Flag to send GPS location of the device from which Magneflex (iOS only) is hosted.
Use:
true – send location
false – do not send location
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
signatureDataIn
Signature data from the device in hexadecimal format.
signatureResult
Result of the signature capture.
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
HTTP method to be used for the HTTP postback from MagneFlex. Use:
GET - returns the response data in the form of a query string. POST – recommended for EVM related transactions to accommodate limits on query string lengths.
closeDeviceAfter
Flag to close the device after the request. Use:
true – close device
false – do not close the device
readerArgument
Comma delimited list of arguments to be passed to MagneFlex. Arguments:
HTTP method to be used for the HTTP postback from MagneFlex. Use:
GET - returns the response data in the form of a query string. POST – recommended for EVM related transactions to accommodate limits on query string lengths.
Operation to request from MagneFlex. Use: requestStartEMVTransaction
httpMethod
Each input parameter supplied in the request is delimited by an ampersand character ‘&’, and the value for a parameter begins after an equal character ‘=’. Where ever a parameter contains multiple values, each are delimited by a comma character
Example query:
Return Value:
The EMV ARQC response output in Hex string format of device raw response for this command.
Information in this publication is subject to change without notice and may contain technical inaccuracies or graphical discrepancies. Changes or improvements made to this product will be updated in the next publication release. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of MagTek, Inc.
MagTek® is a registered trademark of MagTek, Inc. MagnePrint® is a registered trademark of MagTek, Inc. Magensa™ is a trademark of MagTek, Inc.
MagneSafe® is a registered trademark of MagTek, Inc. iDynamo™, and uDynamo are trademarks of MagTek, Inc.
eDynamo™, Dynamag, and DynaMAX are trademarks of MagTek, Inc.
DynaPro Mini™, DynaPro™, and DynaPro Go™ are trademarks of MagTek, Inc.
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
Microsoft® and Windows® are registered trademarks of Microsoft Corporation.
All other system names and product names are the property of their respective owners.
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.
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.
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
Tools & Utilities
Standalone tools that help you configure, test, and maintain MagTek readers outside your application code — for tasks like preparing EMV configuration files, converting object IDs, and updating firmware.
In This Section
Reference Section
Information Available
Convert and work with object identifiers (OIDs).
Web-based Demos (Card Readers)
This page acts as a central navigation hub, consolidating all interactive browser-based demonstrations for MagTek devices. It provides essential links to demos for devices such as MMS Dyna products and V5 card readers, all within a structured documentation environment. The hub is designed to help developers quickly access the specific demo suite they need, facilitating efficient testing and integration of MagTek devices in Chromium-based desktop browsers.
Web-based Demo Documentation
These documents provide instructions for using the browser-based MagTek Demo Applications to configure and test MagTek devices
SDKs & Tools
SDKs & Tools is where you find the libraries and utilities for building against MagTek readers — the client-side code that talks to a device, plus the tools that help you develop, test, and manage one. Where the defines the command set itself, the SDKs wrap it for your platform so you aren't composing raw messages by hand. Start here to pick the right SDK for your platform and integration model.
tone – Type of prompt tone:
0 = No sound
1 = One beep
2 = Two beeps
endSession - Flag to end the session for the device. Default value is true.
“true” = End the session after the request is processed.
“false” = Do not end the session after the request is processed.
Added requestData resource and extended all resources to support requestLocation.
Fixed requestManualCard options field.
arqcData
ARQC data from the device.
passInData
Optional data to send to MagneFlex. This data will be passed back to the web app.
HTTP method to be used for the HTTP postback from MagneFlex. Use:
GET - returns the response data in the form of a query string. POST – recommended for EVM related transactions to accommodate limits on query string lengths.
closeDeviceAfter
Flag to close the device after the request. For requestStartEMVTransaction use:
false – do not close the device
readerArgument
Comma delimited list of arguments to be passed to MagneFlex. Arguments:
Bbrowser-based demonstrations for MagneSafe V5 Secure Card Reader Authenticators (SCRA), showing how to communicate with devices like iDynamo and eDynamo using Chromium-based desktop browsers.
Web-based demonstrations for V5 magnetic stripe reader devices such as Dynamag and DynaPAD, enabling developers to test card swipe data capture and command communication in non-EMV (manual entry/MSR) environments.
Browser-based demonstrations for MagTek MMS Dyna devices such as DynaFlex and DynaProx, showing how to communicate with Secure Card Reader Authenticators (SCRA) using Chromium-based desktop browsers for real-time command and response testing.
Interactive browser-based demonstrations for the iDynamo 5 Gen III, a secure card reader authenticator (SCRA) that uses MagTek's MagneSafe V5 (SRED) architecture.
Supporting configuration guides, certificates, and technical documentation required to set up secure communication, device trust, and development environments for MagTek web-based demos and related services.
In This Section
Need More Help
Need Help?
For additional support, please contact MagTek Support:
Technical Support:
📧 Email:
The cross-platform SDK for .NET, Java, iOS, and Linux.
Build against readers from the browser in JavaScript.
Remotely manage, monitor, and update fleets of devices.
Runnable examples and the web/HID demos.
SDK packages and components to download.
Standalone configuration, conversion, and firmware tools.
This document provides instructions for using the browser-based MagTek Demo Applications to configure and test MagTek devices, including MMS devices, specifically the DynaFlex family.
In This Section
Need More Help
Need Help?
For additional support, please contact MagTek Support:
The Reader Management System (RMS) lets you remotely manage, monitor, configure, and update deployed MagTek readers — keeping a fleet current from one place. RMS is a MagTek cloud service; its full documentation lives under Services.
In This Section
Reference Section
Information Available
RMS support page under .
Need More Help
Need Help?
For additional support, please contact MagTek Support:
Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.
This function retrieves a challenge token from the device. A challenge token consists of a random nonce or timestamp. A challenge token must be used within the time allowed by the device (generally 5 minutes) of being issued. Only one token can be active at a time. Attempts to use a token for requests other than the one specified will cause the token to be revoked/erased.
Copy
Parameter
data
Byte array containing the request ID to be protected.
Return Value:
Returns a byte array containing the challenge token.
This function retrieves device configuration information.
Copy
Parameter
configType
Type of configuration. For DynaFlex, this is the function ID.
data
Configuration data to be sent to the device. For DynaFlex, this is the OID.
Return Value:
Returns an array of bytes containing the configuration information.
This function retrieves device specific information.
Copy
Parameter
infoType
Enumerated information type.
Return Value:
Returns a string value device information.
This function retrieves device specific information.
Copy
Parameter
fileID
Byte array for the file ID. For DynaFlex, use a 4-byte file id.
callback
Name of a class or structure that implements the IConfigurationCallback Delegates events.
Return Value:
Returns a string value device information.
This function retrieves key information.
Copy
Parameter
keyType
Type of key. For DynaFlex, use 0.
data
Key data to be sent to the device. For DynaFlex, this is the 2-byte key slot number.
Return Value:
Returns an array of bytes containing the key information.
This function sends a file to the device.
Copy
Parameter
fileID
Byte array for the file ID. For DynaFlex, use a 4-byte file id.
data
File contents to be sent to the device.
callback
Name of a class or structure that implements the IConfigurationCallback Delegates events.
Return Value:
Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.
This function sends an image to the device.
Copy
Parameter
imageID
Value for the image ID. For DynaFlex, use:
1, 2, 3, or 4
data
File contents to be sent to the device.
Images must be BMP format, 160KB or smaller with no compression, maximum 320px by 240px, with color depth 16 color, 256 color, 16-bit color, 24-bit color. Images smaller than the maximum size are centered on the display. Note images at full screen size must be 16-bit color or lower to meet the size requirement.
For details see
Return Value:
Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.
This function sends a file to the device using a secure command structure.
Copy
Parameter
fileID
Byte array for the file ID. For DynaFlex, use a 4-byte file id.
data
File contents to be sent to the device.
callback
Name of a class or structure that implements the IConfigurationCallback Delegates events.
Return Value:
Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.
This function sets device configuration information.
Copy
Parameter
configType
Type of configuration. For DynaFlex, this is the function ID.
data
Configuration data to be sent to the device.
callback
Name of a class or structure that implements the IConfigurationCallback Delegates events.
Return Value:
Returns 0 if the asynchronous configuration operation started. Otherwise, returns a non 0 value.
This function sets which image is to be displayed when the device is idle.
Copy
Parameter
imageID
Value for the image ID. For DynaFlex, use:
0, 1, 2, 3, or 4
Where 0 substitutes the “Welcome” screen.
Return Value:
Returns 0 if the asynchronous configuration operation started. Otherwise, returns a non 0 value.
This function updates the device firmware.
Copy
Parameter
firmwareType
Type of firmware. For DynaFlex, use:
1 - Main App
data
Firmware image to be sent to the device.
callback
Name of a class or structure that implements the IConfigurationCallback Delegates events.
Return Value:
Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.
This function updates key information in the device.
Copy
Parameter
keyType
Type of key.
data
Key data to be sent to the device.
callback
Name of a class or structure that implements the IConfigurationCallback Delegates events.
Return Value:
Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.
Android
Universal SDK Documentation (Android)
The Android edition of the MagTek Universal SDK (MTUSDK), which brings MagTek SCRA and PIN Pad SCRA devices — including the DynaFlex family — into a single AAR library for Android apps. Use the sections below to set up the SDK, connect to and control a device through the Core API, subscribe to device events, and look up classes, enumerations, and reference appendices.
In This Section
Reference Section
Information Available
Overview of the SDK and the MagTek devices it supports, with system requirements and how to install the certificate chain for connecting to a DynaFlex II PED over WLAN.
Appendices
Supplementary reference material for the MagTek Universal SDK, including the full status-code list, a step-by-step API walk-through, the EMV transaction flow, and integration guidance for mobile-wallet value-added services (Apple VAS and Google Wallet Smart Tap).
Submit feedback
D998200383 DynaFlex Family Programmer's Manual (Commands)
.
callback
Name of a class or structure that implements the IConfigurationCallback Delegates events.
getChallengeToken
getConfigInfo
getDeviceInfo
getFile
getKeyInfo
sendFile
sendImage
sendSecureFile
setConfigInfo
setDisplayImage
updateFirmware
updateKeyInfo
int IDeviceConfiguration.deleteFile(byte[] fileID);
This function cancels a transaction. A transaction can only be cancelled before a card is presented.
boolean IDevice.cancelTransaction();
Return Value: Returns true if cancelled. Otherwise, returns false.
getCapabilities
This function retrieves the capabilities of the device.
IDeviceCapabilities IDevice.getCapabilities();
Return Value: Returns IDeviceCapabilities
getConnectionInfo
This function retrieves the connection information of the device.
ConnectionInfo IDevice.getConnectionInfo();
Return Value: Returns ConnectionInfo
getConnectionState
This function retrieves the connection state of the device.
Return Value: Returns CaptureType
This enum refers to the type of customer information to capture.
Enum
Description
This function allows the host to get an IDeviceConfiguration to configure the device.
Return Value: Returns IDeviceConfiguration.
This function retrieves the device control interface to the device.
Return Value: Returns IDeviceControl
This function returns an information class of the device.
Return Value: Returns DeviceInfo.
This function returns the name of the device assigned from createDevice().
String IDevice.Name();
Return Value: Returns the name of the device.
This function prompts the user to present their card and enter a PIN. A card is presented so that the device can retrieve the PAN, which is used for Format blocks requiring a PAN. The encrypted PIN block (EPB) will be returned in the event OnEvent. The data byte array may be passed to builder function PANDataBuilder.GetPANData();
For DynaFlex devices, this function starts a PIN session on the first call and shall be called again to send the PIN status to the device for completing the PIN session.
Parameter
Type
Description
Parameter
Type
Description
Return Value: Returns true if successful. Otherwise, returns false.
This function prompts the user to enter a PIN. The host must supply the PAN if the Format block selected requires a PAN. The encrypted PIN block (EPB) will be returned in the event OnEvent. The data byte array may be passed to builder function PINDataBuilder.GetPINData();
For DynaFlex devices, this function starts a PIN session on the first call and shall be called again to send the PIN status to the device for completing the PIN session.
Parameter
Type
Description
Return Value: Returns true if successful. Otherwise, returns false.
This function prompts the user to enter a signature. The response data will be returned in the event OnEvent.
Return Value: Returns true of successful. Otherwise, returns false.
This function sends the Authorization Response Code (ARPC) blob to the device. The response data will be returned in the event OnEvent. See EMV Transaction Flow for how to process an EMV transaction.
Parameter
Description
Return Value: Returns true if successful. Otherwise, returns false.
This function sends a command to a NFC Mifare Classic Tag type 2. The NFC tag must first be activated by calling startTransaction() with NFC enabled.
Parameter
Description
Return Value: Returns true if successful. Otherwise, returns false.
Command
Length
Field Value
Tag
Len
Value / Description
If unencrypted:
Tag
Len
Value / Description
If encrypted:
Tag
Len
Value / Description
Example Unencrypted Payload
Example Encrypted Payload for Fast Read
This function sends a command to an NFC Mifare DESFire Tag Type 4. The NFC tag must first be activated by calling startTransaction() with NFC enabled.
Parameter
Description
Return Value: Returns true if successful. Otherwise, returns false.
Tag
Len
Value / Description
Tag
Len
Value / Description
Tag
Len
Value / Description
This function send a user selection to the device.
Parameter
Description
Return Value: Returns true if successful. Otherwise, returns false.
This function send a user selection to the device.
Parameter
Description
Return Value: Returns true if successful. Otherwise, returns false.
This function starts a transaction. This function will automatically handle the opening and closing of a device. The transaction will be processed through multiple calls to the event OnEvent. See EMV Transaction Flow for how to process an EMV transaction.
Parameter
Description
Return Value: Returns true if the transaction started successfully. Otherwise, returns false.
This function allows the host to be notified of all events sent by the device.
Parameter
Description
Return Value: Returns true if successful.
This function allows the host to no longer receive any events sent by the device.
Parameter
Description
Return Value: Returns true if successful.
Appendix B - API Walk Through
The following walks through how to create instances of devices.
CoreAPI.createDevice à IDevice
CoreAPI.getDeviceList à List
CoreAPI.createPPSCRA à MTPPSCRA
ZipCode
Capture the zip code
EmployeeID
Capture Employee ID number
BirthDate
Capture birth date in USA format
MinLength
byte
Minimum length of accepted PIN (>= 4).
MaxLength
byte
Maximum length of accepted PIN (=< 12).
Tone
byte
Tone to play when prompting for the PIN. Usage: 0x00 - No sound 0x01 - One beep 0x02 - Two beeps
Format
byte
ISO format for the PIN block.
PAN
String
First 12 digits of the Primary Account Number. Leave blank if not required by the ISO format for the PIN block.
MinLength
byte
Minimum length of accepted PIN (> 4).
MaxLength
byte
Maximum length of accepted PIN (< 12).
Tone
byte
Tone to play when prompting for the PIN. Usage: 0x00 - No sound 0x01 - One beep 0x02 - Two beeps
Format
byte
ISO format for the PIN block.
PAN
String
First 12 digits of the Primary Account Number. Leave blank if not required by the ISO format for the PIN block.
Mifare Increment
14
Byte 0 – 0xC1 – Increment Command Byte 1 – Source Sector Number Byte 2 – Source Block number Byte 3 – Key Type 0 = A, 1 = B Byte 4 to 9 = 6 Byte Key Byte 10 to 13 = 4 Byte Operand
Mifare Decrement
14
Byte 0 – 0xC0 – Decrement Command Byte 1 – Source Sector Number Byte 2 – Source Block number Byte 3 – Key Type 0 = A, 1 = B Byte 4 to 9 = 6 Byte Key Byte 10 to 13 = 4 Byte Operand
Mifare Restore
10
Byte 0 – 0xC2 – Restore Command Byte 1 – Source Sector Number Byte 2 – Source Block number Byte 3 – Key Type 0 = A, 1 = B Byte 4 to 9 = 6 Byte Key
Mifare Transfer
10
Byte 0 – 0xB0 – Write the value from the Transfer Buffer into destination block number Byte 1 – Destination Sector Number Byte 2 – Destination Block number Byte 3 – Key Type 0 = A, 1 = B Byte 4 to 9 = 6 Byte Key
/DFDF51
01
Encrypted Data Encryption Type
If card is not able to respond: SW1 = 0x64, SW2 = 0x00
Tag
Len
Value / Description
---
---
---
821
var
Encryption Control Payload tag data.
· Data of R-APDU**(see tables below)**
/DFDF51
01
Encrypted Data Encryption Type
Unavailable
Capture unavailable
PhoneNumber
Capture the phone number
SocialSecurityNumber
Capture the social security number
Timeout
byte
Wait time in seconds.
PaymentMethods
List of PaymentMethod
List of the PaymentMethod enumeration. MSR = For magnetic stripe cards. Contact = For EMV chip cards. Contactless = For NFC contactless cards. ManualEntry = Manually entry, no card. When set, other payment methods must not be included. Barcode = For barcode. BarcodeEncrypted = For barcode with encrypted response. AppleVAS = For Apple VAS. GoogleVAS = For Google Wallet VAS. NFC = For NFC tag.
Timeout
byte
Wait time in seconds.
PINMode
byte
PIN mode. Usage: 0x00 - Enter PIN 0x01 - Enter PIN Amount 0x02 - Reenter PIN Amount 0x03 - Reenter PIN 0x04 - Verify PIN For DynaFlex devices this is the User Interface Sequence: 0x01 - Present Card / Enter PIN (start session) 0x04 - Present Card / Enter PIN / Enter PIN Again (start session) On the second call to requestPAN(), send the PIN status: 0xFD - Cancel PIN Session (end session) 0xFE - PIN Entry Failed (end session) 0xFF - PIN Entry Successful (end session)
Timeout
byte
Wait time in seconds.
PINMode
byte
PIN mode. Usage: 0x00 - Enter PIN 0x01 - Enter PIN Amount 0x02 - Reenter PIN Amount 0x03 - Reenter PIN 0x04 - Verify PIN For DynaFlex devices this is the User Interface Sequence: 0x00 - Enter PIN (start session) 0x02 - PIN Incorrect, Try Again (continue session) 0x03 - Enter PIN / Enter PIN Again (start session) 0x05 - Enter PIN Again (continue session) On the second call to requestPIN(), send the PIN status: 0xFD - Cancel PIN Session (end session) 0xFE - PIN Entry Failed (end session) 0xFF - PIN Entry Successful (end session)
data
Contains ARPC blob.
data
Command to send to the NFC tag. For details of the command see NFC Classic commands table below or D998200383 DynaFlex Family Programmer’s Manual (COMMANDS) section NFC/Mifare Pass Through Commands
lastCommand
Determines if this is the last NFC command to complete the operation. true = This is the last command. Device will provide a single beep after receiving a successful response from the NFC tag. To send subsequent commands, the NFC tag must be activated by calling startTransaction() with NFC enabled. false = Expect more commands (Default). Either set to true or false, if the NFC tag command fails, device will provide a double beep.
encrypt
Determines if data returned is to be encrypted. true = Encrypt data false = Do not encrypt data (Default)
Mifare Read
11
Byte 0 – 0x30 – Read Command Byte 1 – Sector Number to Read Byte 2 – Start Block Number Byte 3 – End Block Number Byte 4 – Key Type, 0 = A, 1 = B Byte 5 to 10 = 6 Byte Key
Mifare Write
var
Byte 0 – 0xA0 – Write Command Byte 1 – Sector Number to Write Byte 2 – Start Block Number Byte 3 – End Block Number Byte 4 – Key Type 0 = A, 1 = B Byte 5 to 10 = 6 Byte Key Byte 11 to x = Variable length Byte Data (16 bytes per block)
Command to send to the NFC tag. See DESFire Data Sheet (MF2DLHX0). Should follow ISO 7816-4 APDU format. For details of the command see D998200383 DynaFlex Family Programmer’s Manual (COMMANDS) section NFC/Mifare Pass Through Commands_
lastCommand
Determines if this is the last NFC command to complete the operation. true = This is the last command. Device will provide a single beep after receiving a successful response from the NFC tag. To send subsequent commands, the NFC tag must be activated by calling startTransaction() with NFC enabled. false = Expect more commands (Default). Either set to true or false, if the NFC tag command fails, device will provide a double beep.
encrypt
Determines if data returned is to be encrypted. true = Encrypt data false = Do not encrypt data (Default)
81
02
Tag Response (SW1 SW2). See DESFire Data Sheet (MF2DLHX0). Should follow ISO 7816-4 APDU format.
· SW1 and SW2 of R-APDU
FC
var
NFC Data Container
/DF7A
var
NFC Data
/DFDF59
var
Encrypted Data Primitive to be decrypted.
/DFDF50
var
Encrypted Data KSN
Byte 0
Status of User Selection: 0x00 = User Selection Request completed, see Selection Result 0x01 = User Selection Request aborted, cancelled by user 0x02 = User Selection Request aborted, timeout
Byte 1
The menu item selected by the user. This is a single byte zero based binary value.
Byte 0
Status of User Selection: 0x00 = User Selection Request completed, see Selection Result 0x01 = User Selection Request aborted, cancelled by user 0x02 = User Selection Request aborted, timeout
Byte 1
The menu item selected by the user. This is a single byte zero based binary value.
transaction
An interface that holds the parameters for the transaction.
eventCallback
Name of a class or structure that implements the IEventSubscriber Delegate interface event.
eventCallback
Name of a class or structure that implements the interface event.
These examples demonstrate methods for creating an IDevice to be used in the MagTek Universal SDK. This also shows how to establish a device specific API, which is not used with the MagTek Universal SDK.
Here, a single IDevice is established.
Here, a list of IDevice is established. The first device is accessed at index 0.
The following walks through how to make use of IDevice.
Implement device events within the class to receive events.
CoreAPI à IDevice.
IDevice à subscribeAll().
IDevice à other functions.
IDevice à startTransaction().
Example
Application Main window may extent the
Static
Member
Value
Description
NFC_MIFARE_ULTRALIGHT
String
"nfc_mifare_ultralight"
MIFARE_CLASSIC_1K
These constructors initialize a PersonalInfoEntry object.
Call startPersonalInfoEntry().
At OnEvent():TouchscreenPersonalInfoEntry, build the object.
Member
Description
deviceType
Type of device.
dataBytes
Data to pass in after set from OnEvent().
data()
Returns the data payload.
Return Value:
Returns an instance of PersonalInfoEntry.
IEventSubscriber Delegates or can be extended by a separate class. This example uses a separate class and demonstrates how to parse for the various event types.
Example
Various events are separately shown below
The following walks through how to make use of IDeviceControl.
IDevice --> IDeviceControl.· IDeviceControl à open().
IDeviceControl --> other functions.
IDeviceControl --> close().
Example
The following walks through how to make use of ConnectionInfo.
IDevice --> ConnectionInfo.
ConnectionInfo --> getAddress()
ConnectionInfo --> getConnectionType()
ConnectionInfo --> getDeviceType() Example
Example
The following walks through how to make use of IDeviceCapabilities.
IDevice à IDeviceCapabilities.
IDeviceCapabilities à BatteryBackedClock() to check if date/time should be set.
IDeviceCapabilities à PaymentMethods() to check card types supported.
IDeviceCapabilities à other functions.
The following walks through how to make use of IDeviceConfiguration.
IDevice --> getDeviceConfiguration().
IDeviceConfiguration --> updateFirmware().
IDeviceConfiguration --> getConfiguration().
IDeviceConfiguration --> setConfiguration().
IDeviceConfiguration --> other functions.
Example
Application Main window may extent the IConfigurationCallback Delegates or can be extended by a separate class. This example uses a separate class and demonstrates how to parse for the various events.
Example
CoreAPI Walk Trough
// Access MMS with Universal SDK using createDevice()
IDevice mtmms = CoreAPI.createDevice(
context,
DeviceType.MMS,
ConnectionType.USB, "",
"",
"DynaFlex",
"");
mtmms.requestSignature();
// Acess MMS with Universal SDK using getDeviceList()
List<IDevice> mtmms = CoreAPI.getDeviceList(
context,
DeviceType.MMS,
deviceListCallback);
mtmms[0].requestSignature();
import com.magtek.mobile.android.mtusdk.*;
// Extend the main window to receive events.
public class MainWindow implements IEventSubscriber,
IConfigurationCallback
{
// Establish a device from CoreAPI. List<IDevice> deviceList = CoreAPI.getDeviceList(
context,
deviceListCallbac);
IDevice device = deviceList[0];
/* For a list of a single device type. DeviceType deviceType = DeviceType.MMS;
List<IDevice> deviceList = CoreAPI.getDeviceList(
context,
deviceType deviceListCallback);
IDevice device = deviceList[0];
*/
/* For a list of multiple device types.
List<DeviceType> deviceTypes = null;
deviceTypes.Add(DeviceType.MMS);
deviceTypes.Add(DeviceType.CMS);
List<IDevice> deviceList = CoreAPI.getDeviceList(
context,
deviceTypes,
deviceListCallback);
IDevice device = deviceList[0];
*/
/* Suscribe to events sent from the device.
These would be but not limited to: card inserted, card removed, connection state...
Set MainWindow to receive the events. */
boolean return = device.unsubscribeAll(this);
boolean return = device.subscribeAll(this);
/* To handle events from some other class.
EventsVector eventsVector = new EventsVector()
boolean return = device.unsubscribeAll(eventsVector);
boolean return = device.subscribeAll(eventsVector);
*/
// Assign parameters for the transaction.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>();
paymentMethod.Add(PaymentMethod.MSR);
paymentMethod.Add(PaymentMethod.Contact);
paymentMethod.Add(PaymentMethod.Contactless);
Transaction transaction = new Transaction();
transaction.setAmount(“1.00”);
transaction.setCashBack(“0.00”);
transaction.setEMVOnly(true);
transaction.setPaymentMethods(paymentMethod);
transaction.setQuickChip(false);
// Start transaction.
boolean result = device.startTransaction(transaction);
// A class to handle events.
public class EventsVector implements IEventSubscriber
{
public void OnEvent(EventType eventType, IData data)
{
switch (eventType)
{
case ConnectionState:
// Parse for the ConnectionState ConnectionState value =
ConnectionStateBuilder.GetValue(data.StringValue());
break;
case DeviceResponse:
break;
case DeviceExtendedResponse:
break;
case DeviceNotification:
break;
case CardData:
break;
case TransactionStatus:
// Parse for the transaction status code and detail.
TransactionStatus status =
TransactionStatusBuilder.GetStatusCode(data.StringValue());
string statusDetail = TransactionStatusBuilder.GetStatusDetail(data.StringValue());
break;
case DisplayMessage:
String message;
// Get the message. if (data != null)
{
message = System.Text.Encoding.UTF8.GetString(data);
}
break;
case InputRequest:
break;
case AuthorizationRequest:
// Forward ARQC to processor.
/* data[0..1] – ARQC length
data[2..n] – remainder contains the ARQC TLV object
*/
IData processorARPC = new
BaseData(sendForAuthorization(data.ByteArray()));
// Send authorization to device when not in QuickChip mode.
if (transaction.QuickChip == false)
{
device.sendAuthorization(procesorARPC.ByteArray());
}
break;
case TransactionResult
/* data[0] – Signature Required
data[1..2] – Batch Data length
data[3..n] – remainder contains the Batch Data TLV object
*/
// Parse the TLV from data[].
.
// Abstract Approval status from TLV tag “DFDF1A”.
.
// Abstract Signature Required status from TLV tag data[0].
.
break;
case PINBlock:
break;
case Signature:
break;
// Establish a device from CoreAPI.
List<IDevice> deviceList = CoreAPI.getDeviceList(); IDevice device = deviceList[0];
// Establish a deviceControl from device.
IDeviceControl deviceControl = device.getDeviceControl();
// Open the device, then use the IDeviceControl functions. deviceControl.open();
. . .
// Close the device. deviceControl.close();
// Establish a device from CoreAPI.
List<IDevice> deviceList = CoreAPI.getDeviceList();
IDevice device = deviceList[0];
// Establish a ConnectionInfo from device.
ConnectionInfo connectionInfo = device.getConnectionInfo();
// Retrieve address, connectionType, and deviceType.
String address = connectionInfo.getAddress();
ConnectionType connectionType = connectionInfo.getConnectionType();
DeviceType deviceType = connectionInfo.getDeviceType();
// Establish a device from CoreAPI.
List<IDevice> deviceList = CoreAPI.getDeviceList();
IDevice device = deviceList[0];
IDeviceConfiguration deviceConfiguration =
device.getDeviceConfiguration();
/* To handle events from some other class. ConfigCallBacks
configCallBacks = new ConfigCallBacks();
*/
// Update firmware.
byte[] data = getDataFromURI(uri);
int return = deviceConfiguration.updateFirmware(1, data, this);
/* Get configuration.
Device-Driven Fallback OID = 1.2.1.1.1.1
contructed OID = E2 08 E1 06 E1 04 E1 02 C1 00
Note: first digit of OID is ommited in the construction and instead is passed in the configType.
*/
byte configType = 0x01;
data = new byte[] {0xE2,0x08,0xE1,0x06,0xE1,0x04,0xE1,0x02,0xC1,0x00
};
byte[] response = devConfig.getConfigInfo(configType, data);
/* Set configuation.
Device-Driven Fallback OID is 1.2.1.1.1.1
Disabled contructed OID = E2 09 E1 07 E1 05 E1 03 C1 01 00
Enabled contructed OID = E2 09 E1 07 E1 05 E1 03 C1 01 01
Note: first digit of OID is ommited in the construction and instead
is passed in the configType.
*/
data = new byte[]
{0xE2,0x09,0xE1,0x07,0xE1,0x05,0xE1,0x03,0xC1,0x01,0x00 };
result = devConfig.getConfigInfo(configType, data);
// A class to handle configuration callback events.
public class ConfigCallbacks implements IConfigurationCallback
{
public void OnProgress(int progress)
{
/* Handle progress.
Progress is complete when progress = 100 */
}
public void OnResult(StatusCode status, byte[] data)
{
/* Handle result.
A configuration process is complete when
status = StatusCode.Success */
}
public IResult OnCalculateMAC(byte macType, byte[] data)
{
IResult result = new Result(StatusCode.UNAVAILABLE);
byte[] macBytes = null;
DeviceType deviceType =
device.getConnection Info().getDeviceType();
switch (deviceType)
{
case DeviceType.MMS:
macBytes = getDynaFlexMAC(macType, data);
break;
}
if (macBytes != null)
{
result = new Result(StatusCode.SUCCESS);
result.Data = new BaseData(macBytes);
}
return result;
}
}
IDevice Walk Through
Handling Events
Static members
PersonalInfoEntry
IDeviceControl Walk Through
ConnectionInfo Walk Through
IDeviceCapabilities Walk Through
IDeviceConfiguration Walk Through
Handling Events
String
"mifare_classic_1k"
MIFARE_CLASSIC_4K
String
"mifare_classic_4k"
MIFARE_DESFIRE_LIGHT
String
"mifare_desfire_light"
MIFARE_MINI
String
"mifare_mini"
MIFARE_PLUS_EV1
String
"mifare_plus_ev1"
MIFARE_PLUS_EV2
String
"mifare_plus_ev2"
MIFARE_PLUS_SE
String
"mifare_plus_se"
MIFARE_PLUS_X
String
"mifare_plus_x"
MIFARE_DESFIRE_EV1
String
"mifare_desfire_ev1"
MIFARE_DESFIRE_EV2
String
"mifare_desfire_ev2"
MIFARE_DESFIRE_EV3
String
"mifare_desfire_ev3"
MDL
String
"mdl"
TAG_REMOVED
String
"tag_removed"
FAILED
String
"failed"
IO_FAILED
String
"io_failed"
AUTHENTICATION_FAILED
String
"authentication_failed"
dataType()
Returns the capture type.
encrypted()
Returns the encryption status. false = data is not encrypted true = data is encrypted
encryptionType()
Returns the encryption type.
ksn()
Returns the Key Serial Number.
Appendix C - EMV Transaction Flow
This section demonstrates transaction flow.
Flow Chart - QuickChip
Sample Code - QuickChip
The following breaks out the EMV flow chart into code. When enabling QuickChip mode, host does not send the ARPC to the device to complete the transaction. Events are shown separately and in the order received.
public void OnEvent(EventType eventType, IData data)
{
String message
switch (eventType);
{
case EventType.DisplayMessage:
// Get the message.
message = data.StringValue();
}
}
public void OnEvent(EventType eventType, IData data)
{
String message;
switch (eventType);
{
case EventType.InputRequest:
// Get the message.
message = data.StringValue();
// display/retrieve user selection.
// set status and selection result.
IData selectionData = new BaseData(new Byte[] {status, selection});
device.sendSelection(selectionData);
}
}
public void OnEvent(EventType eventType, IData data)
{
byte[] ARQC = null;
switch (eventType);
{
case EventType.AuthorizationRequest:
// Forward ARQC to processor.
/* data[0..1] – ARQC length
data[2..n] – remainder contains the ARQC TLV object */
}
}
public void OnEvent(EventType eventType, IData data)
{
String message;
switch (eventType);
{
case EventType.TransactionResult:
/* data[0] – Signature Required
data[1..2] – Batch Data length
data[3..n] – remainder contains the Batch Data TLV object
*/
// Parse the TLV from data[].
// Abstract Approval status from TLV tag “DFDF1A”.
// Abstract Signature Required status from TLV tag data[0].
}
}
Flow Chart – Signature Capture
Sample Code – Signature Capture
The following breaks out the EMV flow chart into code. Events are shown separately and in the order received.
// Assign parameters.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>();
paymentMethod.Add(PaymentMethod.MSR);
paymentMethod.Add(PaymentMethod.Contact);
paymentMethod.Add(PaymentMethod.Contactless);
Transaction transaction = new Transaction();
transaction.setAmount(“1.00”);
transaction.setCashBack(“0.00”);
transaction.setEMVOnly(true);
transaction.setPaymentMethods(paymentMethod);
transaction.setQuickChip(true);
// Start transaction.
boolean result = device.startTransaction(transaction);
public void OnEvent(EventType eventType, IData data)
{
String message;
switch (eventType);
{
case EventType.DisplayMessage:
// Get the message.
message = data.StringValue();
}
}
public void OnEvent(EventType eventType, IData data)
{
byte[] ARQC = null;
switch (eventType);
{
case EventType.AuthorizationRequest:
// #4a
// Forward ARQC to processor.
/* data[0..1] – ARQC length
data[2..n] – remainder contains the ARQC TLV object */
}
}
public void OnEvent(EventType eventType, IData data)
{
String message;
switch (eventType);
{
case EventType.DisplayMessage:
// Display approval message.
message = data.StringValue();
// A data size of 0 is an instruction to clear the display.
if (data.StringValue().Length == 0)
{
// Clear the UI display.
}
}
}
public void OnEvent(EventType eventType, IData data)
{
String message;
switch (eventType);
{
case EventType.TransactionResult:
/* data[0] – Signature Required
data[1..2] – Batch Data length
data[3..n] – remainder contains the Batch Data TLV object
*/
// Parse the TLV from data[].
// Abstract Approval status from TLV tag “DFDF1A”.
// Abstract Signature Required status from TLV tag data[0].
}
}
public void OnEvent(EventType eventType, IData data)
{
String signature;
switch (eventType);
{
case EventType.Signature:
signature = data.StringValue();
}
}
Flow Chart – With ARPC
Sample Code – With ARPC
The following breaks out the EMV flow chart into code. When disabling QuickChip mode, host must send the ARPC to the device to complete the transaction. Events are shown separately and in the order received.
public void OnEvent(EventType eventType, IData data)
{
string message;
switch (eventType);
{
case EventType.DisplayMessage:
// Get the message.
message = data.StringValue;
}
}
public void OnEvent(EventType eventType, IData data)
{
string message;
switch (eventType);
{
case EventType.InputRequest:
// Get the message.
message = data.StringValue;
// display/retrieve user selection.
// set status and selection result.
IData selectionData = new BaseData(new Byte[] {status, selection});
device.sendSelection(selectionData);
}
}
public void OnEvent(EventType eventType, IData data)
{
byte[] ARQC = null;
switch (eventType);
{
case EventType.AuthorizationRequest:
// Forward the ARQC to the processor.
/* data[0..1] – ARQC length
data[2..n] – remainder contains the ARQC TLV object */
ARQC.ByteArray = data.ByteArray;
// App function to send the request to the processor.
ARPC = sendARQCToProcessorForApproval(ARQC.ByteArray());
}
}
After the ARPC is returned from the processor, it is constructed into a TLV container and then sent to the device. The ARPC for approved (00) is set in ASCII 3030.
The optional tags 91, 71, and 72 (Issuer Authentication Data, Issuer Script Template 1, and Issuer Script Template 2) are not included in this example.
See the construction of the ARPCTLV in the table below.
ARPC TLV object for sendAuthorization().
Tag
Len
Value / Description
Typ
Req
Default
The use case for an MSR fallback is when communication with the chip results in a terminated transaction and the TransactionStatus is reported as MSRFallback.
The host application will re-attempt the transaction. To invoke this use case, here are the following pre-requisites.
Pre-requisites:
Device already configured for Device-Driven Fallback = Disabled.
A card to cause the fallback. Example but not limited to a card with no applications programmed or a card with an application not configured on the device.
Scheme:
-->Host begins an initial transaction with PaymentMethod set to MSR+Chip+Contactless.
<--Device responds with fail and with status of MSRFallback.
-->Host displays a message to use magstripe.
Begin initial transaction:
Continue with Fallback transaction:
Classes - A - I
These classes are equipped with helper classes named Builders. Builders can parse the raw data byte array of an OnEvent() into a format required by a builder’s class.
For the complete documentation index, see . This page is also available as .
These constructors initialize a BarCodeData object. Use BarCodeDataBuilder.GetBarCodeData with data from the BarCodeData event to return a BarcodeData.
As defined in EMV Integrated Circuit Card Specifications for Payment Systems 4.3
///71
var
Issuer Script Template 1
B
O
As defined in EMV Integrated Circuit Card Specifications for Payment Systems 4.3. The host may include as many instances of this parameter as needed, up to a maximum length of 128 bytes including Tags and Lengths.
///72
var
Issuer Script Template 2
B
O
As defined in EMV Integrated Circuit Card Specifications for Payment Systems 4.3. The host may include as many instances of this parameter as needed, up to a maximum length of 128 bytes including Tags and Lengths.
-->Host starts a transaction with PaymentMethod set to MSR.
<--Device may respond with transaction cancelled card read error.
-->Host displays a message each time the transaction fails until successful or until Host decides to end the transaction.
public void OnEvent(EventType eventType, IData data)
{
String message;
switch (eventType);
{
case EventType.DisplayMessage:
// Display approval message.
message = data.StringValue();
// A data size of 0 is an instruction to clear the display.
if (data.StringValue().Length == 0)
{
// Clear the UI display.
}
}
}
public void OnEvent(EventType eventType, IData data)
{
String message;
switch (eventType);
{
case EventType.TransactionResult:
/* data[0] – Signature Required
data[1..2] – Batch Data length
data[3..n] – remainder contains the Batch Data TLV object
*/
// Parse the TLV from data[].
// Abstract Approval status from TLV tag “DFDF1A”.
// Abstract Signature Required status from TLV tag data[0].
}
}
public void OnEvent(EventType eventType, IData data)
{
String signature;
switch (eventType);
{
case EventType.Signature:
signature = data.StringValue();
}
}
MSR Fallback Flow
R
Member
Description
Data()
Returns the data payload.
Encrypted()
Returns the encryption status. false = data is not encrypted true = data is encrypted
EncryptionType()
Returns the encryption type.
KSN()
Return Value: Returns an instance of BarCodeData.
CertificateInfo is used for the connection to a device requiring client credentials. See the following for details on installing a certificate chain: D998200550 DynaFlex II PED Using Wireless LAN Guide.
This constructor initialize a CertificateInfo object. Once created, it is to be passed to CoreAPI.createDevice().
Parameter / Member
Type / Format
Description
formatgetFormat()
String
Certificate data format. “PKCS12” – for .p12 file. “PFX” – for .pfx file.
datagetData()
byte[]
Certificate data.
Return Value: Returns an instance of Certificate Info. Example of using CertificateInfo.
This class returns the connection state of the device when supplied the data object of the OnEvent()ConnectionState event.
Member
Description
CONNECTED
Returns string of connected.
CONNECTING
Returns string of connecting.
DISCONNECTED
Returns string of disconnected.
Return Value: Returns an instance of ConnectionStateBuilder.
DirectoryEntry is similar to an InputRequest for Application during a transaction. Other fields of information are included besides Application Label. During a transaction, the device selects the PPSE. The directory entries are the PPSE response starting from the BF0C tag. The number of directory entries correspond to the number of applications on the card.
These constructors initialize a DirectoryEntry object.
Parameter
Type
Description
Aid
String
Application Identifier. Tag 4F
Label
String
Application Label. Tag 50
Return Value: Returns an instance of DirectoryEntry.
This supplies a directory entry list for application selection after a card has been presented to the device during a transaction. To be implemented, Application Selection Behavior property 1.2.1.1.1.2 must be set to 0x03 – Enhanced Prompt Cardholder.
The data byte array from the EnhancedInputRequest event is parsed and returned as an enhanced application selection list (directory entry). This list is the PPSE response starting from tag BF0C. EnhancedInputRequest class extends InputRequest.
Member
Return
Description
EnhancedSelectionList()
List<DirectoryEntry>
Returns a list of enhanced application selection.
setEnhancedSelectionList()
List<DirectoryEntry>
Sets a list of enhanced application selection.
IData is used for the payload of events and passing data to functions. When assigning the member StringValue, the member ByteArray is automatically assigned. Same is true vice versa. In this way either a string or an array can be accessed without need of data conversion.
Use the BaseData() function to assign an instance of IData.
Member
Type / Format
Description
StringValue()
String
Returns a string value.
ByteArray()
byte[]
Returns a byte array.
Example of using IData.
This is used for displaying messages prompted by the card during a transaction. The data byte array from the InputRequest event is parsed and returned as an application selection list.
Return Value: Returns an instance of InputRequest.
This is the interface used as the parameter for startTransaction(). For an example, see the sample code in IDevice Walk Through.
Parameter
Type / Format
Description
Timeout
byte
Transaction timeout in seconds. Default is 60 seconds.
0 to 255 - Depending on the device, 0 means no timeout.
PaymentMethods
List of Payment Method
List of the PaymentMethod enumeration.
MSR = For magnetic stripe cards.
Contact = For EMV chip cards.
Contactless = For NFC contactless cards.
ManualEntry = Manually entry, no card. When set, other payment methods must not be included.
Barcode = For barcode.
BarcodeEncrypted = For barcode with encrypted response.
AppleVAS = For Apple VAS.
GoogleVAS = For Google Wallet VAS.
NFC = For NFC tag.
new EnhancedInputRequest();
new EnhancedInputRequest(byte[] data);
// String usage
IData data1 = new BaseData(“3030”);
// Array usage
IData data2 = new BaseData(new byte[] {0x30, 0x30});
new InputRequest ();
new InputRequest (byte[] data);
CertificateInfo
ConnectionStateBuilder
DirectoryEntry
EnhancedInputRequest
IData
InputRequest
ITransaction
Markdown
Enumerations - B - E
BarCodeFormat
This enum refers to the type of barcodes to display.
Enum
Description
BLOB
Data is binary format
COMMAND
Data is a command in binary format
This enum refers to the type of barcodes to display.
Enum
Description
This enum refers to the type of customer information to capture.
Enum
Description
This enum refers to the readiness of the SDK to communicate with the device. This is not the physical attachment to a host system.
Enum
Description
This enum refers to the communication interface type of MagTek reader which the SDK will control.
Enum
Description
This enum is reserved for future use.
Enum
Description
This enum refers to a change in the device status.
Enum
Description
This enum refers to a featured supported by the device.
Enum
Description
This enum refers to the type of MagTek reader which the SDK will control.
Enum
Description
This enum refers to the type of connection error.
Enum
Description
This enum refers to the type of event triggered by the device.
Enum
Description
IMQTTDeviceStatusCallback Delegates
This interface invokes callback functions to receive data and/or a detailed response. To register for the event(s), call the setMQTTDeviceStatusMonitoring() function with the name of a class that implements the IMQTTDeviceStatusCallback interface.
OnConnected
This event is called when a device is connected to the MQTT broker.
void OnConnected(String deviceAddress);
Parameter
Description
Return Value: None
This event is called when a device is disconnected from the MQTT broker.
Parameter
Description
Return Value: None
Returns the Key Serial Number.
passwordgetPassword()
String
Password to access the certificate data.
DISCONNECTING
Returns string of disconnecting.
ERROR
Returns string of error.
GetString()
Returns string of the ConnectionState enum.
GetValue()
Returns ConnectionState enum from the event data string value.
Priority
byte
Application Priority Indicator. Tag 87
ProprietaryData
byte[]
Application Selection Registered Proprietary Data. Tag 9F0A
KernelIdentifier
byte
Kernel Identifier. Tag 9F2A
IssuerIN
byte[3]
Issuer Identification Number. Tag 42
IssuerINE
byte[4]
Issuer Identification Number Extended. Tag 9F0C
IssuerCountryCodeAlpha2
byte[2]
Issuer Country Code (alpha2 format). Tag 5F55
IssuerCountryCodeAlpha3
byte[3]
Issuer Country Code (alpha3 format). Tag 5F56
CardProductDetails
byte[2]
Card Product Details. Tag 9F7D
Title()
String
Title to display.
Type()
int
Selection type.
Timeout()
long
Timeout in seconds to make selection.
Title()setTitle()
string
Title
SelectionList()setSelectionList()
List<String>
List of selections for Application and Language depending on the Type.
INPUT_STATUS_COMPLETED
0x00
To send the status of completed for sendSelection().
INPUT_STATUS_CANCELLED
0x01
To send the status of canceled for sendSelection().
INPUT_STATUS_TIMED_OUT
0x02
To send the status of timed out for sendSelection().
QuickChip
boolean
In QuickChip mode, the device does not prompt for an amount. Device sends an ARQC request to the host. Device automatically populates the ARPC response data with EMV Tag 8A set to “Z3”. Card holder is prompted to remove the card. Transaction result is later determined by the processor and not by the card.
false - Do not enable QuickChip mode.
true - Enable QuickChip mode. Default.
EMVOnly
boolean
Flag that determines whether or not to start an EMV transaction.
false - Do not start transaction if the device does not support EMV.
true - Only start transaction if the device supports EMV. Default.
PreventMSRSignature ForCardWithICC
boolean
Flag that forces the device to skip signature capture during an MSR-only transaction if the card’s service code indicates it is a chip card.
false – Allow the prompt for a signature if requested.
true – Do not prompt for signature.
SuppressThankYouMes sage
boolean
By default, devices with a display signal the end of a transaction by briefly showing “THANK YOU,” then “WELCOME.”
false – Do not suppress the thank you message.
true – Suppress the thank you message.
DisplayAmountForQuic kChip
boolean
Display Amount for Quick Chip Transaction Flow.
false = Do not display Amount when QuickChip mode is true. Default.
true = Display Amount when QuickChip mode is true.
OverrideFinalTransacti onMessage
byte
By default, devices with a display signal the end of a transaction by returning to the idle page and showing “WELCOME.” This parameter directs the device to show a message based on the Message ID from the command displayMessage(). This option completely overrides the device’s idle page behavior until the next transaction, power cycle, or other similar state change.
Example but not limited to:
0x00 - reserved, do not use. 0x01 - “AMOUNT”
0x02 - “AMOUNT OK?”
0x03 - “APPROVED”
0x04 - “CALL YOUR BANK”
0x05 - “CANCEL OR ENTER”
0x06 - “CARD ERROR”
0x07 - “DECLINED”
0x08 - “ENTER AMOUNT”
0x09 - reserved, do not use. 0x0A - reserved, do not use. 0x0B - “INSERT CARD”
0x0C – “NOT ACCEPTED”
0x0D - reserved, do not use. 0x0E - “PLEASE WAIT”
0x0F - “PROCESSING ERROR”
0x10 - “REMOVE CARD”
0x11 - “USE CHIP READER”
0x12 - “USE MAGSTRIPE”
0x13 - “TRY AGAIN”
0x14 - “WELCOME”
0x15 - “PRESENT CARD”
0x16 - “PROCESSING”
0x17 - “CARD READ OK - REMOVE CARD”
0x18 - “INSERT OR SWIPE CARD”
0x19 - “PRESENT ONE CARD ONLY”
0x1A - “APPROVED PLEASE SIGN”
0x1B - “AUTHORIZING PLEASE WAIT”
0x1C - “INSERT, SWIPE OR TRY ANOTHER CARD”
0x1D - “PLEASE INSERT CARD”
0x1E - Null prompt (empty screen) 0x1F - reserved, do not use.
0x20 - “SEE PHONE”
0x21 - “PRESENT CARD AGAIN”
0x22 - “INSERT/SWIPE/TRY OTHER CARD”
0x23 - “TAP or SWIPE CARD”
0x24 - “TAP or INSERT CARD”
0x25 - “TAP, INSERT or SWIPE CARD”
0x26 - “TAP CARD”
0x27 - “TIMEOUT”
0x28 - “TRANSACTION TERMINATED”
EMVResponseFormat
byte
The format of the EMV response.
0x00 – Legacy. Default.
0x01 – RFU
TransactionType
byte 1
EMV Tag 9C - The type of financial transaction, represented by the first two digits of the ISO 8583:1987 Processing Code.
Examples:
0x00 – purchase. Default.
0x01 – cash advance
0x09 – purchase with cashback
0x20 – refund
Supported transaction types can found in the commands programmers manual specific to the device.
Amount
String 12
EMV Tag 9F02 - Authorized amount of the transaction.
Example:
“000000000123” – $1.23
“000000009999” – $99.99
CashBack
String 12
EMV Tag 9F03 - Secondary amount associated with the transaction.
Example:
“000000000123” – $1.23
“000000009999” – $99.99
CurrenyCode
byte[] 2
EMV Tag 5F2A - Currency code of the transaction according to ISO 4217. The byte array is null by default.
Example:
0x0840 = US Dollar0x0978 = Euro0x0826 = UK Pound
CurrencyExponent
byte[] 1
EMV Tag 5F36 - The decimal point position from the right of the transaction amount. The byte array is null by default.
Example:
0x02 – decimal point at 2 position from the right.
TransactionCategory
byte[] 1
EMV Tag 9F53 - The type of contactless transaction being performed. The byte array is null by default.
MerchantCategory
byte[] 2
EMV Tag 9F15 - The type of business being done by the merchant, represented according to ISO 18245. The byte array is null by default.
MerchantID
byte[] 15
EMV Tag 9F16 - Used to uniquely identify a given merchant. The byte array is null by default.
MerchantCustomData
byte[] 20
EMV Tag 9F7C – Proprietary merchant data that may be requested. The byte array is null by default.
ManualEntryType
byte
User interface sequence.
0x00 - Card Number, Expiration Date, Security Code
0x01 - Name on Card, Card Number, Expiration Date, Security Code (Reserved for Future Use)
0x02 – Qwick Code, Last 4 digits of Card Number, Security Code (Reserved for future use)
ManualEntryFormat
byte
Card number valid format.
0x00 - PAN min 8, max 21 digits
ManualEntrySound
byte
Beeper feedback.
0x00 - On keypress sound disabled
0x01 - On keypress sound enabled
AppleVASMode
VASMode
An enumeration for the Apple VAS Mode.
AppleVASProtocol
VASProtocol
An enumeration for the Apple VAS Protocol.
ECP2FrameData
byte[] 3-18
Apple ECP2.0 frame from Byte 2 to Byte N. See Apple ECP2.0 specification.
· For example, if ECP2.0 VASUP-A frame is 6A02C3020003FFFF
then Byte 2-N is 0xC3020003FFFF.
· By default, ECP2.0 frame (Byte 2 -N) is 0xC3020003FFFF
CustomNFCTransactionMode
List of NFC TransactionMode
List of NFC transaction modes.
CustomNFCReadDataMode
NFCDataMode
Custom NFC data mode.
TipMode
byte
Tip mode.
0x00 = Disable Tip Mode
0x01 = Show Tip GUI immediately using %
0x02 = Show Tip GUI immediately using $
0x11 = Enable Read Channel(s), with +Tip Button using %
0x12 = Enable Read Channel(s), with +Tip Button, using $
Tip1DisplayMode
byte
Display mode for Tip button 1.
0x00 = % or $
0x01 = Display Custom 0x02 = Display NO TIP 0x03 = Disabled
Tip2DisplayMode
byte
Display mode for Tip button 2.
0x00 = % or $
0x01 = Display Custom 0x02 = Display NO TIP 0x03 = Disabled
Tip3DisplayMode
byte
Display mode for Tip button 3.
0x00 = % or $
0x01 = Display Custom 0x02 = Display NO TIP 0x03 = Disabled
Tip4DisplayMode
byte
Display mode for Tip button 4.
0x00 = % or $
0x01 = Display Custom 0x02 = Display NO TIP 0x03 = Disabled
Tip5DisplayMode
byte
Display mode for Tip button 5.
0x00 = % or $
0x01 = Display Custom 0x02 = Display NO TIP 0x03 = Disabled
Tip6DisplayMode
byte
Display mode for Tip button 6.
0x00 = % or $
0x01 = Display Custom 0x02 = Display NO TIP 0x03 = Disabled
Tip1Value
String
Display value for Tip button 1.
“1.00” = $1.00 (Display Mode is $)
“10.0001” = 10.0001% (Display Mode is %)
Tip2Value
String
Display value for Tip button 2.
“1.00” = $1.00 (Display Mode is $)
“10.0001” = 10.0001% (Display Mode is %)
Tip3Value
String
Display value for Tip button 3.
“1.00” = $1.00 (Display Mode is $)
“10.0001” = 10.0001% (Display Mode is %)
Tip4Value
String
Display value for Tip button 4.
“1.00” = $1.00 (Display Mode is $)
“10.0001” = 10.0001% (Display Mode is %)
Tip5Value
String
Display value for Tip button 5.
“1.00” = $1.00 (Display Mode is $)
“10.0001” = 10.0001% (Display Mode is %)
Tip6Value
String
Display value for Tip button 6.
“1.00” = $1.00 (Display Mode is $)
“10.0001” = 10.0001% (Display Mode is %)
TaxAmount
String
Tax amount.
“1.00” = $1.00
FunctionalButtonRight Option
byte[] 2
String ID to use for the Right functional button. The byte array is null by default.
When user presses this button, device sends a notification to the host to indicate the present card functional button Right is pressed. Device then waits for the next command from the host. While waiting, the screen shows “PLEASE WAIT”.
null = Disable.
0x0000 to 0x00FF = String ID
ZipCode
Capture the zip code
EmployeeID
Capture Employee ID number
BirthDate
Capture birth date in USA format
Error
There was an error either connecting or disconnecting the device.
Connected
Device is connected and ready for transacting.
Disconnecting
Device is in the process of disconnecting. The next state will is to be Disconnected.
BLUETOOTH_LE_EMVT
Bluetooth Low Energy with EMV supported devices:
· tDynamo
TCP
Transmission Control Protocol supported devices:
· DynaPro
TCP_TLS
Transmission Control Protocol with Transport Layer Security supported devices:
· DynaPro Go
TCP_TLS_TRUST
Transmission Control Protocol with Transport Layer Security supported devices:
· DynaPro Go
WEBSOCKET
WebSocket supported devices:
· DynaFlex Pro
· DynaFlex II PED
WEBSOCKET_TRUST
WebSocket supported devices. This will establish a TLS connection to device without requirement for name match.
· DynaFlex Pro
· DynaFlex II PED
SERIAL
UART supported devices
AIDL
AIDL devices:
· DynaGlass
VIRTUAL
Virtual devices
MQTT
MQTT
· DynaFlex II PED
ZIPCODE
Request Zip code
BirthDate
Request Birth date
ActivationCode
Request Activation code
DeviceBondingFailure
Host fails to pair with device.
DeviceTemperatureLow
The device’s temperature falls below the temperature set in Low Temperature Notification Level.
DeviceTemperatureHigh
The device’s temperature rises below the temperature set in High Temperature Notification Level.
DeviceBatteryLow
The battery charge reaches 15 percent. If a device is powered on with a charge that is already 15 percent or below, this notification is sent shortly after power up.
DeviceBatteryLowPowerDown
This notification is sent one minute before it automatically powers down the device. This occurs when the battery charge has reached 0 percent. Shutdown can be prevented by connecting the device to a USB power source.
PANEntry
Supports PAN entry
ShowBarCode
Supports display of a barcode
ScanBarCode
Supports scanning a barcode
DisplayMessage
Supports display of messages
Buzzer
Has a buzzer
CardEmulation
Supports NFC card emulation
PersonalInfoEntry
Supports personal info entry
MMS
Apollo class devices.
List includes but not limited to:
* DynaFlex
* DynaFlex Pro
* DynaProx
BluetoothUnauthorized
Bluetooth not paired.
NetworkOff
Network is off.
NetworkUnreachable
Network is unreachable.
SecurityRejected
Security rejected.
SecurityFailed
Security failed.
ConnectionFailed
Connection failed.
DeviceNotification
Device has sent a notification.
CardData
Device has sent magnetic stripe data from a card swipe.
TransactionStatus
There was a change in transaction status.
DisplayMessage
Device has a message to display for the user.
ClearDisplay
Device has notified to clear the display of user messages on host app.
InputRequest
Device is requesting input from the user.
EnhancedInputRequest
Device is requesting input for enhanced application selection in response to entering the card’s payment system environment.
AuthorizationRequest
Device has sent the Authorization Request Cryptogram and associated block of EMV tags for a transaction. This block is meant to be sent to the transaction processor.
TransactionResult
Device has sent the result of the transaction.
PINBlock
Device has sent the PINBlock after the user has entered a PIN on the device.
Signature
Device has sent data which represents a signature from a user.
DeviceDataFile
Device has sent a data file.
OperationStatus
Device has sent an operation status of a command.
DeviceEvent
Device has sent change of device state.
UserEvent
Device has sent a notification related to user interaction with the device.
FeatureStatus
Device has sent status of a feature.
PINData
Device has sent data related to a PIN.
PANData
Device has sent data related to a PAN.
BarCodeData
Device has sent barcode data.
NFCEvent
Device has sent NFC event.
NFCData
Device has sent NFC data.
NFCResponse
Device has sent response to and NFC command.
NFCAPDUResponse
Device has sent response to an NFC APDU command for Mifare DESFire Tag.
NFCCardData
Device has sent NFC card data.
NFCDeviceEngagementData
Device has sent data after NFC engagement.
NFCPassThroughData
Device has sent NFC Pass-Through data.
NFCPassThroughResponse
Device has sent a response to NFC Pass- Through exchange.
GPOResponse
Device has GPO response.
TouchscreenSignatureCapture
Device has sent response to signature capture.
TouchscreenFunctionalButtonSelected
Device has sent a notification of a functional button selected.
TouchscreenTextStringButtonSelected
Device has sent a notification of a test string button selected.
TouchscreenAmountButtonSelected
Device has sent a notification of an amount button selected.
TouchscreenPresentCardFunctionalBut tonSelected
Device has sent a notification of a present card functional button selected.
TouchscreenPersonalInfoEntry
Device has sent a personal info entry.
BLOB_BASE64
Data is Base64 encoded format
COMMAND_BASE64
Data is a command in Base64 format
QRCODE
QR code
Unavailable
Capture unavailable
PhoneNumber
Capture the phone number
SocialSecurityNumber
Capture the social security number
Unknown
Device is in an unknown connection state.
Disconnected
Device is disconnected.
Connecting
Device is in the process of connecting. The next state is to be Connected.
USB
Universal Serial Bus supported devices:
· eDynamo
· DynaPro
· mDynamo
· DynaPro Go
· Dynamag
· DynaPro Mini
· DynaMax
· DynaFlex
· tDynamo
· DynaFlex Pro
· kDynamo
· DynaFlex II PED
· cDynamo
· DynaProx
· iDynamo 6
· DynaFlex II Go
BLUETOOTH_LE
Bluetooth Low Energy devices:
· DynaMax
· DynaFlex II Go
BLUETOOTH_LE_EMV
Bluetooth Low Energy with EMV supported devices:
· eDynamo
PIN
Request Personal Identification Number
Signature
Request Signature
SSN
Request Social security number
None
No event to report.
DeviceResetOccured
A device reset had occurred.
DeviceResetWillOccur
A device reset will occur soon. Host application may uses this as a warning to take appropriate actions.
None
No feature.
SignatureCapture
Supports signature capture
PINEntry
Supports PIN entry
SCRA
Secure Reader Authenticator devices. List includes but not limited to:
* eDynamo
* mDynamo
* Dynamag
* DynaMax
* tDynamo
* kDynamo
* cDynamo
* iDynamo 6
PPSCRA
PIN Pad Secure Reader Authenticator devices. List includes but not limited to:
* DynaPro
* DynaPro Go
* DynaPro Mini
CMF
Common Message Structure devices. List includes but not limited to:
* oDynamo
Unknown
Device is in an unknown connection state.
TimedOut
Device has timed out.
BluetoothOff
Bluetooth is off.
ConnectionState
There was a change in the connection state of the device.
DeviceResponse
Device has responded to a command.
DeviceExtendedResponse
Device has responded to an extended command.
BarCodeType
CaptureType
ConnectionState
ConnectionType
DataEntryType
DeviceEvent
DeviceFeature
DeviceType
ErrorType
EventType
deviceAddress
Device address.
deviceAddress
Device address.
OnDisconnected
void OnDisconnected(String deviceAddress);
Enumerations - F - V
FeatureStatus
This enum refers to the status of a specific feature reported from DeviceFeature.
Enum
Description
NoStatus
No change in status
Success
This enum refers to the type of image.
Enum
Description
This enum refers to the type of specific information to retrieve from the device.
Enum
Description
Enum
Description
Enum
Description
Enum
Description
This enum refers to the operation status of the device.
Enum
Description
This enum refers to which card type the device will perform a transaction.
Enum
Description
This enum refers to the status of the transaction.
Enum
Description
This enum refers to the type of user event reported by the device. These events relate to user interaction.
Enum
Description
This enum refers to the Apple VAS and Google Wallet VAS mode. This controls how the VAS data is returned in the transaction ARQC. For details on Apple VAS data structure returned in a transaction see D998200383 DynaFlex Family Programmer’s Manual (COMMANDS).
Enum
Description
This enum refers to the Apple VAS protocol. For details on Apple VAS data structure returned in a transaction see D998200383 DynaFlex Family Programmer’s Manual (COMMANDS).
Enum
Description
Boot1Version
Boot 1 firmware version of the device.
Boot0Version
Boot 0 firmware version of the device.
FirmwareHash
Firmware hash comprised of part numbers, versions, and timestamps.
TamperStatus
Tamper status of the device. 0x00 = Not Tampered
0x01 = Tampered
OperationStatus
Operation status of the device. 0x01 = Offline
0x02 = Online
OfflineDetail
Offline details of the device.
Bit 0 = Tamper problem present
Bit 1 = Master Key problem present
Bit 2 = Keys and Certificates problem present
Bit 3 = Real Time Clock problem present
Bit 4 = Random Number Generator problem present
Bit 5 = Cryptography Engine problem present
Bit 6 = Magnetic Stripe Reader Hardware problem present
Bit 7 = Reserved
FirmwareVersionWLAN
Firmware version for WLAN module of the device.
FirmwareVersionBLE
Firmware version for Bluetooth LE module of the device.
BatteryLevel
Battery level of the device.
MifareClassic4K
Mifare Classic 4K
MifareDESFireLight
Mifare DESFire Light
MifareMini
Mifare Mini
MifarePlusEV1
Mifare Plus EV1
MifarePlusEV2
Mifare Plus EV2
MifarePlusSE
Mifare Plus SE
MifarePlusX
Mifare Plus X
MifareDESFireEV1
Mifare DESFire EV1
MifareDESFireEV2
Mifare DESFire EV2
MifareDESFireEV3
Mifare DESFire EV3
ISO14443TypeA
ISO 14443 Type A
ISO14443TypeB
ISO 14443 Type B
NFCCardTypeNotSupported
NFC Card Type Not Supported
mDL
Mobile Driver’s License
mDLDeviceEngagementSuccess
mDL Device Engagement Success
mDLDeviceEngagementFailed
mDL Device Engagement Failed
TagRemoved
Tag removed
Failed
Command failed
IOFailed
IO failed
AuthenticationFailed
Authentication failed
Mifare2GoMobileDESFire
Mifare 2 Go Mobile DESFire
Failed
Device has failed an operation.
Done
Device has completed an operation.
ManualEntry
For user to manually enter transaction data without any card access.
Barcode
For barcode.
BarcodeEncrypted
For encrypted barcode.
AppleVAS
For Apple VAS.
NFC
For NFC tag.
GoogleVAS
For Google Wallet Smart Tap VAS.
CardInserted
A card was inserted into the device.
CardRemoved
A card was removed from the device.
CardDetected
A card was detected by the device.
CardCollision
A card collision was detected by the device.
TimedOut
The transaction was not completed before a timeout period.
HostCancelled
The host software sent a cancel.
TransactionCancelled
The transaction was cancelled.
TransactionInProgress
The transaction is in progress.
TransactionError
There is an error during the transaction.
TransactionApproved
The transactions is approved.
TransactionDeclined
The transactions is declined.
TransactionCompleted
The transaction is completed.
TransactionFailed
The transaction failed.
TransactionNotAccepted
The transaction was not accepted by the device.
SignatureCaptureRequested
A signature capture is requested by the device.
TechnicalFallback
Due to technical reasons, the chip transaction cannot be completed by the reader.
QuickChipDeferred
Device has sent a “Z3” response code to the chip card.
DataEntered
Data has been entered on the device for a manual card entry transaction.
TryAnotherInterface
Due to removal of the chip card or error with contactless card, the transaction cannot be completed by the reader.
BarcodeRead
A barcode is read.
VASError
Apple VAS error occurred.
TransactionStartedFromDevice
The transaction has started by user interaction with the device.
TransactionStartedFromDeviceQuickChip
The Quick Chip transaction has started by user interaction with the device.
TransactionCancelledFromDevice
The transaction was cancelled from device.
CardSeated
Card is seated into the chip station.
CardUnseated
Card was removed from the chip station.
CardSwiped
Magnetic stripe card was swiped.
TouchPresented
Touch screen sensor press detected.
TouchRemoved
Touch screen sensor release detected.
BarcodeRead
Barcode detected.
NFCMifareUltralightPresented
Mifare Ultralight presented.
MifareClassic1KPresented
Mifare Classic 1K presented.
MifareClassic4KPresented
Mifare Classic 4K presented.
MifareDESFireLightPresented
Mifare DESFire Light presented.
MifareMiniPresented
Mifare Mini Presented.
MifarePlusEV1Presented
Mifare Plus EV1 presented.
MifarePlusEV2Presented
Mifare Plus EV2 presented.
MifarePlusSEPresented
Mifare Plus SE presented.
MifarePlusXPresented
Mifare Plus X presented.
MifareDESFireEV1Presented
Mifare DESFire EV1 presented.
MifareDESFireEV2Presented
Mifare DESFire EV2 presented.
MifareDESFireEV3Presented
Mifare DESFire EV3 presented.
mDLPresented
Mobile Driver’s License presented.
NFCMifareUltralightRemoved
Mifare Ultralight removed.
MifareClassic1KRemoved
Mifare Classic 1K removed.
MifareClassic4KRemoved
Mifare Classic 4K removed.
MifareDESFireLightRemoved
Mifare DESFire Light removed.
MifareMiniRemoved
Mifare Mini removed.
MifarePlusEV1Removed
Mifare Plus EV1 removed.
MifarePlusEV2Removed
Mifare Plus EV2 removed.
MifarePlusSERemoved
Mifare Plus SE removed.
MifarePlusXRemoved
Mifare Plus X removed.
MifareDESFireEV1Removed
Mifare DESFire EV1 removed.
MifareDESFireEV2Removed
Mifare DESFire EV2 removed.
MifareDESFireEV3Removed
Mifare DESFire EV3 removed.
mDLRemoved
Mobile Driver’s License removed.
PaymentOnly
The device operates the same as EMV mode. It reads only EMV payment data from a tapped smartphone or a tapped card. When the device sends ARQC to conclude the transaction, it includes EMV payment data in container FC and does not include VAS data in container FE.
ECP2
The host can configure the ECP2 frame. See Apple ECP2.0 specification.
Success
Failed
Failed
TimedOut
Timed out
Cancelled
Cancelled
Error
Error
HardwareNA
Featured hardware not applicable for a status
BITMAP
BMP file
DeviceSerialNumber
FirmwareVersion
Firmware version of the device.
DeviceCapabilities
Capabilities of the device delimited by a comma.
ASCII
Ascii data mode
Binary
Binary data mode
None
No update for the operation.
NFCMifareUltralight
Mifare Ultralight
MifareClassic1K
Mifare Classic 1K
MifareClassic
Mifare Classic
MifareDESFire
Mifare DESFire
AppleWalletMobileDESFire
Apple Wallet mobile DESFire
NoStatus
No update for the operation.
Started
Device has started an operation.
Warning
Device has sent a warning about the operation.
MSR
For magnetic stripe cards.
Contact
For EMV chip cards.
Contactless
For NFC contactless cards.
NoStatus
Set before the start of a transaction and before a card is presented to the device.
NoTransaction
No transaction in progress.
CardSwiped
A card was swiped into the device.
None
No events yet to occur.
ContactlessCardPresented
Contactless card has been presented.
ContactlessCardRemoved
Contactless card has been removed.
Single
The device reads only VAS data from a tapped smartphone, or reads EMV payment data from a tapped card. When the device sends ARQC to conclude the transaction, it only includes either EMV payment data in container FC for cards, or includes VAS data in container FE for smartphones.
Dual
The device reads both VAS data and EMV payment data from a tapped smartphone, or reads EMV payment data from a tapped card. When device sends ARQC to the host to conclude the transaction, it includes EMV payment data in container FC and includes VAS data, if available, in container FE.
VASOnly
The device reads only VAS data from a tapped smartphone, and does not read data from a tapped card. If the tapped smartphone does not support VAS, the device does not detect or read from the smartphone. When the device send ARQC to conclude the transaction, it includes VAS data in container FE and does not include EMV payment data in container FC.
URL
URL VAS protocol
Full
Full VAS protocol
ImageType
InfoType
NFCDataMode
NFCEvent
NFCTransactionMode
OperationStatus
PaymentMethod
TransactionStatus
UserEvent
VASMode
VASProtocol
IDeviceControl
Create an instance of the IDeviceControl using IDevice.getDeviceControl(). Then use the function calls described in this chapter.
Generally, these functions will run in one of two modes:
Asynchronous functions return data in the event handlers in section
Synchronous functions return data in the return value. If the data is not available immediately, the call will block until a wait time has elapsed.
close
This function closes the connection to the device.
Return Value:
Returns true if successful. Otherwise, returns false.
This function resets the device. This is equivalent to a power reset. After the reset, connection to the device will need to be re-established.
Return Value:
Returns true if successful. Otherwise, returns false.
This function displays a message on the device’s screen.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function clears session data and returns the device to an idle state.
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a request for user input to the device. The response data will be returned in the event
OnEvent.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function opens a connection to the device.
Return Value:
Returns true if successful. Otherwise, returns false.
This function instructs the device to play a tone.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a command to the device. The response will be passed to the event OnEvent.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends an extended command to the device. The response will be passed to the event
OnEvent
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a raw APDU command from the host application to the NFC target while the device is operating in NFC Pass-Through mode. For NFC Type A or Type B using ISO 14443-4 Protocol.
Used for applications that require direct APDU-level communication, such as mDL, secure element transactions, or custom NFC protocols.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a synchronous command to the device. The response from the device will be returned in IResult.
Parameter
Description
Return Value:
Returns IResult.
This function sets the date and time for the device.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function send a 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.
Parameter
Description
false – unlock the latch in the device.
true – lock the latch in the device.
Return Value:
Returns true if successful. Otherwise, returns false.
This function controls the status of the device’s LED indicators (Light Emitting Diode) to provide visual feedback NFC operation states. Applicable after entering NFC Pass-Through mode. The status is reset after exiting NFC Pass-Through mode.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function commands the device to enter NFC Pass-Through Mode. This enables the host application to directly exchange APDU commands and responses with an NFC card or mobile device.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function configures the NFC reader polling behavior used to detect nearby NFC targets such as cards, mobile devices, or mDL wallets. Applicable after entering the Pass-Through mode.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a command to show a barcode on the device’s display.
Parameter
Description
Parameter
Type
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a command to immediately show an image on the device’s display.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a command to immediately show an image on the device’s display.
Parameter
Description
Member
Type/ Format
Description
Images must be BMP format, 160KB or smaller with no compression, maximum 320px by 240px, with color depth 16 color, 256 color, 16-bit color, or 24-bit color. Images smaller than the maximum size are centered on the display. Note images at full screen size must be 16-bit color or lower to meet the size requirement.
For details see D998200383 DynaFlex Family Programmer’s Manual (Commands).
Return Value:
Returns true if successful. Otherwise, returns false.
This function displays custom User Interface (UI) pages on devices that support a screen. It holds parameters for all UI page options of Text Lines, Text Buttons, Amount Buttons, and Image. Only one UI page option may be in effect at one time based on the option parameter. See the other subset functions for invoking a specific UI page.
When the UI page is active, the device waits for further action. The device notifies the host when a Button is pressed. Text Buttons and Functional Buttons report as the button number. Amount Buttons report the $ amount in BCD format. A press on a Text line does not produce a report.
Parameter
Description
0x00 = Up to 5 lines of text + 1 functional button Middle.
0x01 = Title + up to 6 text buttons + up to 3 functional buttons.
0x02 = Title + up to 6 $Amount buttons + up to 3 functional buttons.
Returns true if successful. Otherwise, returns false.
This function shows the Amount UI page.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function shows the Image UI page.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function shows the Text buttons UI page.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function shows the Text lines UI page.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a command to start the barcode reader.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a command to start card emulation.
Compliance: Conforms to ISO/IEC 14443 Type-A and NFC Forum Type 4 standards.
Passive Operation mode: The NFC reader must generate the field to activate the simulated card.
Read-Only: The emulated card is read-only and does not support writing.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a command to prompt a cardholder for customer information. Captured information is later returned in OnEvent() EventType.TouchscreenPersonalInfoEntry.
Parameter
Description
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a command to stop the barcode reader. This is applicable only when the timeout value for startBarCodeReader() was set to 0x00.
Return Value:
Returns true if successful. Otherwise, returns false.
This function sends a command to stop card emulation.
Return Value:
Returns true if successful. Otherwise, returns false.
This function stops the Personal Info Entry process. If called during info entry, the process will be canceled immediately.
Return Value:
Returns true if successful. Otherwise, returns false.
Data
byte[]
Data to encode into a barcode
BlockColor
byte[]
Block color. Use RRGGBB format. 0x000000 = Black
BackgroundColor
byte[]
Background color. Use RRGGBB format. 0xFFFFFF = White
ErrorCorrection
byte
Error Correction 0x00 = Low (default) 0x01 = Medium 0x02 = Quartile 0x03 = High
See ISO/IEC 18004:2015
MaskPattern
byte
Mask Pattern
0x00 to 0x07 = Mask Pattern
0xFF = Device Select Optimal Mask Pattern (default) See ISO/IEC 18004:2015
MinVersion
byte
Minimum Version. Must be less than or equal to Maximum Version. 0x01 to 0x28 = Version 1 to Version 40 (0x01 is default)
See ISO/IEC 18004:2015
MaxVersion
byte
Maximum Version. Must be greater than or equal to Minimum Version. 0x01 to 0x28 = Version 1 to Version 40 (0x28 is default)
See ISO/IEC 18004:2015
backgroundColor
byte[3]
Background color in RRGGBB format. 0x000000 = Black
0xFFFFFF = White
amount1[4] … amount6[4]
Value $ Amount in BCD (Binary Coded Decimal) array format for buttons 1 to 6. 4-bytes in length. To disable a button, set to null.
Byte index:
· [0-2] = dollar value
· [3] = cents value
BCD positioning:
87 65 43 . 21
0x00 0x00 0x00 0x00
· 8 – hundred thousand
· 7 – ten thousand
· 6 – thousand
· 5 – hundred
· 4 – ten
· 3 – one
· 2 – 1/tenth
· 1 – 1/hundredth
Range:
· Min value displayed is $0.00
· Max value displayed is $999,999.99
Example:
// $0.01
amount1 = new Byte[] { 0x00, 0x00, 0x00, 0x01
};
//$100,000.23
amount1 = new Byte[] { 0x10, 0x00, 0x00, 0x23
};
leftFButtonStringID[2]
String ID for the Left functional button. 2-bytes in length. To disable this button, set to null.
middleFButtonStringID[2]
String ID for the Middle functional button. 2-bytes in length. To disable this button, set to null.
rightFButtonStringID[2]
String ID for the Right functional button. 2-bytes in length. To disable this button, set to null.
leftFButtonColor
Color of Left functional button.
0 = red, 1 = green, 2 = yellow
middleFButtonColor
Color of Middle functional button.
0 = red, 1 = green, 2 = yellow
rightFButtonColor
Color of Right functional button.
0 = red, 1 = green, 2 = yellow
xPosition[2]
X Position for image. 2-bytes in length.
To display the image in the center of the loading image area, set to null.
yPosition[2]
Y Position for image. 2-bytes in length.
To display the image in the center of the loading image area, set to null.
imageData[]
Bitmap data.
Image encoded in full BMP file format as defined by Microsoft (e.g,
starting with “BM”). If no image provided, set to null.
leftFButtonStringID[2]
String ID for the Left functional button. 2-bytes in length. To disable this button, set to 0.
middleFButtonStringID[2]
String ID for the Middle functional button. 2-bytes in length. To disable this button, set to 0.
rightFButtonStringID[2]
String ID for the Right functional button. 2-bytes in length. To disable this button, set to 0.
leftFButtonColor
Color of Left functional button.
0 = red, 1 = green, 2 = yellow
middleFButtonColor
Color of Middle functional button.
0 = red, 1 = green, 2 = yellow
rightFButtonColor
Color of Right functional button.
0 = red, 1 = green, 2 = yellow
amount1 … amount6
Value $ Amount in BCD string format for buttons 1 to 6. 8-characters in length. To disable a button, set to null.
Range:
· Min value displayed is $0.00
· Max value displayed is $999,999.99
· Decimal needed to display cents
· Comma not needed
Example:
// $0.01
string sAmount1 = "0.01";
// $100,000.23
string sAmount1 = "100000.23";
amount1[4] … amount6[4]
Value $ Amount in BCD (Binary Coded Decimal) array format for buttons 1 to 6. 4-bytes in length. To disable a button, set to null.
Byte index:
· [0-2] = dollar value
· [3] = cents value
BCD positioning:
87 65 43 . 21
0x00 0x00 0x00 0x00
· 8 – hundred thousand
· 7 – ten thousand
· 6 – thousand
· 5 – hundred
· 4 – ten
· 3 – one
· 2 – 1/tenth
· 1 – 1/hundredth
Range:
· Min value displayed is $0.00
· Max value displayed is $999,999.99
Example:
// $0.01
amount1 = new Byte[] { 0x00, 0x00, 0x00, 0x01 };
//$100,000.23
amount1 = new Byte[] { 0x10, 0x00, 0x00, 0x23 };
xPosition[2]
X Position for image. 2-bytes in length.
To display the image in the center of the loading image area, set to null.
yPosition[2]
Y Position for image. 2-bytes in length.
To display the image in the center of the loading image area, set to null.
imageData[]
Bitmap data.
Image encoded in full BMP file format as defined by Microsoft (e.g,
starting with “BM”).
leftFButtonStringID[2]
String ID for the Left functional button. To disable this button, set to null.
middleFButtonStringID[2]
String ID for the Middle functional button. To disable this button, set to null.
rightFButtonStringID[2]
String ID for the Right functional button. To disable this button, set to null.
leftFButtonColor
Color of Left functional button.
0 = red, 1 = green, 2 = yellow
middleFButtonColor
Color of Middle functional button.
0 = red, 1 = green, 2 = yellow
rightFButtonColor
Color of Right functional button.
0 = red, 1 = green, 2 = yellow
middleFButtonStringID[2]
String ID for the Middle functional buttons. 2-byte in length. To disable this button, set to null.
Supported Data Type: Supports the URI (URL) data type.
LED number:
0x00 = LED 1 (Power LED)
0x01 = LED 2
0x02 = LED 3
0x03 = LED 4
0xFF = All 4 LEDs
Where the LEDs are numbered 1, 2, 3, 4 counting from the left.
status
LED Status:
0x00 = OFF
0x01 = GREEN ON
0x02 = RED ON
Duration to stay in Pass-Through mode.
0x00 = Indefinite
0x01 to 0xFF = 1 to 255 seconds
mode
Pass-Through mode.
0x00 = Stop Pass-Through Mode. Applicable only when already started. When stopped, the RF Antenna is turned off.
0x01 = Start Pass-Through Mode. This mode can only be used when the device is in Idle state.
BarCodeRequest object containing the barcode data to display.
timeout
Display Time. Usage:
0x00 = Indefinite
0x01 to 0xFF = 1 to 255 seconds
prompt
Text to display below the QR code. In Landscape orientation, the limit is approximately 30 characters. In Portrait orientation, the limit is approximately 22 characters.
Type
BarCodeType
Enum to specify the type of barcode
Format
BarCodeFormat
Enum to specify the barcode format
boolean IDeviceControl.showImage(byte imageID);
imageID
Usage:
0x01 – show the image at slot 1. 0x02 – show the image at slot 2. 0x03 – show the image at slot 3. 0x04 – show the image at slot 4.
boolean IDeviceControl.showImage(
ImageData data
byte timeout);
data
See ImageData below.
timeout
Display Time Usage:
0x00 = Indefinite
0x01 to 0xFF = 1 to 255 seconds
To set up the MagTek Universal SDK library for Android, download the 1000007352 MagTek Universal SDK for MMS Devices (Android) available from MagTek.com.
To add the MT Universal libraries to a custom software project in Android Studio, follow these steps:
Launch Android Studio.
Copy the following AAR file to the libs subfolder of your software project: MTUSDK.aar
Ensure your project settings are set up correctly.
Clean, build, and run your custom software project to make sure the library imported correctly.
In your custom software, create an instance of MTUSDK. For examples, see the source code included with the MagTek Universal Demo project and/or the Code Examples section in this document.
Depending on the connection types supported, the project should include the uses-features and uses-permissions as specified in the table below in its AndroidManifest.xml file. For examples, see the AndroidManifest.xml included with the MagTek Universal Demo project.
