These file types conform to the Common File Structure format. The File Payload of these files contain a certificate in PEM format.

Certificates must be loaded into the device in the order of trust starting with the root CA, next intermediate CA(s) and ending with the leaf (server or client for example) so that the device can verify the signature of each certificate. If the certificates are not loaded in order, they will be rejected.

When loading a server cert, the associated key pair must already exist in the device as the CSR keys or as the existing server or client cert and will be used to verify that the public key contained in the certificate is correct. If the keys don’t match the certificate will be rejected. If the certificate is associated with the CSR keys, the CSR keys will be associated with the certificate and will no longer be available for other certificates until re-generated.

Initial server or client certificates can not be loaded until the respective CSR keys and CSR is generated. To generate a CSR see Generate CSR (WLAN Only) - Command 0xEF03.

These file types conform to the Common File Structure format.

The File Payload of these files contain a certificate signing request in PEM format. To generate a CSR see Generate CSR (WLAN Only) - Command 0xEF03.

The device will erase the CSR file from volatile memory after the host fetches it with Command 0xD821.

- Start Get File from Device. After fetching the CSR, the keys used to generate the CSR will still exist in non-volatile memory associated with a CSR and can be used to generate a new CSR if needed.

These pages detail how to communicate with Secure Card Reader Authenticator (SCRA) devices which implement MagTek Messaging Schema (MMS) and the DynaFlex family, DynaFlex II Go and DynaProx system architecture.

These pages also describe how to communicate with PIN Entry Devices (PED) which implement MagTek Messaging Schema (MMS) and the DynaFlex/DynaProx family system architecture. (PED ONLY)

These pages use bold face to:

• Highlight terms / concepts being formally defined in the current sentence / paragraph

• Highlight important distinguishing keywords in sentences

• Indicate hyperlinks to other sections / tables

These pages use a small number of annotation standards that are important to understand:

• Hexadecimal values are prefixed with 0x unless the context clearly indicates an un-prefixed number is hexadecimal (for example, TLV tags, lengths, and values are always assumed to be hex).

• Binary values are prefixed with 0b unless the context clearly indicates the value is binary.

• Decimal values are not prefixed unless required for clarity, in which case the prefix is 0d.

The standard documented by these pages makes extensive use of Tag-Length-Value encoding. describes how to encode and decode TLV, and how to read the tables in this document that describe TLV data objects.

The SCRA DynaFamily Programmer's Manual is the complete reference for the Multi-Interface Card Reader Platform (MMS) command set. It's written once for the whole family — DynaFlex, DynaProx, and DynaFlex II Go share the same commands, responses, and notifications — so this manual is device-agnostic. To confirm which commands a specific reader supports, use the DynaFamily Command Matrix.

New to the platform? Start with for scope and conventions, and for the vocabulary used throughout.

• Device refers to the Secure Card Reader Authenticator (SCRA) or PIN Entry Device (PED) that receives and responds to the command set specified in this document. Not all devices support PIN entry. Devices include DynaFlex, DynaProx, DynaFlex II, and so on.

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

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

TLV data objects use the following primitive data types:

• A = Alphabetic (string, no numbers).

• AN = Alphanumeric (string).

• B = Binary value, which includes bit combinations (“OR” types).

The Encryption Type provides the key type, variant, and other information the host can use to decrypt encrypted data included in various payloads. The possible values are an ORed bitmask using the following elements:

• 0xxx xxxx = Fixed Key (Not used)

• 1xxx xxxx = DUKPT Key

Card emulation enables a DynaFlex/DynaProx device to simulate a Type 4 smart card. The emulated card has the following characteristics:

• Compliance: Card emulation conforms to ISO/IEC 14443 Type-A and NFC Forum Type 4 standards.

• Passive Operation: The emulated card functions in passive mode. The phone is responsible for generating the magnetic field required to activate the simulated card.

The host and the device communicate with each other by exchanging blocks of data called Messages, which are standardized wrappers containing a payload that is either a command Request, a command Response, an unsolicited Notification, or a File. For example, the host may send a command request message to the device to change a configuration setting, and the device may send a command response message to indicate the command was successful; when a cardholder inserts a card, the device may send a notification message to the host that a cardholder has initiated a transaction; the host may send the device a file message to load firmware.

Messages can be nested. For example, a top-level secure wrapper request from the host to the device may contain an encrypted or signed command request for the device to unpack, validate, and execute.

Requests and Responses

• Requests and responses are two of the message payload types the host and device exchange inside messages. The combination of a message that contains a request payload and a message that contains the corresponding response payload is referred to generally in this document as a .

• The device can only service one command request at a time, and sends each command response within a pre-determined finite amount of time after receiving the request.

• After sending a command request, the host must wait until the device returns a response before sending another request, or until the request is unanswered after a reasonable host-defined timeout period passes.

• are a message payload type the host and device exchange inside messages. The device sends notification messages to the host if the device’s state changes or if an external event occurs, such as a cardholder inserting a card.

• The device can send a notification at any time, and does not expect a response or any specific action from the host.

• By default, the device sends all notifications to the USB interface. To configure the device to send notifications on additional connections, use .

• Data Files are a message payload type the host and device exchange inside messages. The device handles them as a stream: it begins storing the payload of the message before it has received the final packet of the message, allowing for much larger payloads than standard requests.

• This streaming behavior is possible because the message is restricted to transferring a file and thus the message payload is primitive data only; it cannot contain composed TLV data objects.

Regardless of connection type, all MMS devices use the same schema for sending and receiving messages, which is documented inMessage Format. For information about transmitting and receiving messages using specific connection types (which involves following connection-specific rules for breaking messages down into transmittable Message Streams), see .

After the host receives and decrypts EMV ARQC Type data or Merchant Data Container data from the device, it may need to parse each track into individual values embedded in the tracks. The device can read multiple card formats, which vary even between different issuers and payment brands using the same underlying standards. Describing all possible formats is beyond the scope of this document, but this section describes how to parse data from tracks 1, 2, and 3 in a generic ISO/ABA compliant format as an example.

The table below shows an example of ISO/ABA track data the device sends to the host, using unmasked placeholder numbers to make it easier to see the relative positions of the values embedded in the track data. It is important to note that some cards do not include Track 3 data. Manually entered data does not include Track 3.

Example Generic ISO/ABA Track Data Format

The example track data in the above table can be interpreted as follows:

• The %, ?, and ; are sentinels / delimiters, and are taken directly from the data on the card.

• The first character at the beginning of Track 1 data is the card format code. For swiped credit / debit cards, this comes from the card and is generally B. Manually entered data uses M.

• The string of 5s is the Account Number / License Number / PAN.

Security Parameters Type

Key Information Type

Some files types conform to the common file structure format that follows. The following is a list of file types that conform to this format.

1. EMV file types

2. Certificate File Types

3. Certificate Signing Request (CSR) File Types

Common File Structure

Transactions

This section of the DynaFamily Programmer's Manual lists available commands to initiate various ransactions in the device.

Information in this group

NFC/MIFARE Pass Through Commands (Contactless Only)

After an NTag/MIFARE Ultralight is activated, the host uses this command to send commands and receive responses to and from a NTag/MIFARE Ultralight.

Information in this group

The host and the device communicate with each other by exchanging blocks of data called messages, which are standardized wrappers containing a payload. This section will detail everything you need to know about using messages.

Pass-Through Mode is independent and separate from EMVCo Payment functions. This mode provides no access to any EMV payment kernels, and is out of scope from EMVCo certifications.

This mode is typically used by developers that require the need for non-payment low-level APDU communications with NFC cards, tokens, and devices.

The commands in this section provide the basic capability to communicate directly with the non-payment Contactless Card. They provide control of the polling process, and exchange of application protocol data units (APDU).

Typical Use Case examples of overall sequence:

• ENTER Pass-Through Mode.

The host uses this command to set device configuration / settings securely. Properties that require security should specify that they do in their documentation. This command can also be used for properties that do not require security.

The details, request data and response data of this command are identical to what is documented in Set Property (Unsecured) - Command 0xD111, however, the command must be structured and sent according to what is documented in sequence of events 1-5 of Start Send File to Device (Secured) - Command 0xD811 .

This section of the DynaFamily Programmer's Manual lists commands to process firmware file.

This section of the DynaFamily Programmer's Manual lists diagnostic and utility commands.

EMV ARPC Data

The host can load this file type to control the behavior of the device’s EMV contact and contactless kernels when the device should support Offline Data Authentication (ODA). Populate all values from information provided by each payment brand that should be supported by the device. The host can load this file using Start Send File to Device (Unsecured) - Command 0xD812.

MagTek provides tools that allow these settings to be loaded using a Microsoft Excel spreadsheet in xlsx format for more convenient authoring, review, and change tracking. For a reference sample spreadsheet,

contact MagTek Support Services. The MagTek tools expect the spreadsheet to be formatted format as shown in Table XX. Each CA Key to be supported is defined in a tab of the Excel file.

EMV Configuration CA Keys File Type

The MagTek tool converts the spreadsheet data into the format shown in CA Keys Raw Format.

Miniature Certificate Type

Banking Functions

This section of the DynaFamily Programmer's Manual lists banking functions commands.

Information in this group

The host uses this option to display a maximum of 5 lines of host-provided text, and 1 optional green functional button, Middle – label with a String ID that associates it with a configured String message. See Table – Default User Interface String IDs and Strings.

When the user presses this button, the device sends a notification to the host to indicate this button is pressed. See User Interface Host Action Request - Notification 0x1803. After that, the host will decide what to do next.

Recommend maximum number of characters setting for this page:

Landscape Screen Orientation

• Each text line can fit about:

  • 18 Upper case wide size characters (example: “WM”)

  • 23 Upper case regular size characters (example: “ABC”)

  • 21 lower case wide size characters (example: “wm”)

  • 30 lower case regular size characters (example: “abc”)

• Button text can fit about:

  • 5 Upper case wide size characters (example: “WM”)

  • 8 Upper case regular size characters (example: “ABC”)

• Each text line can fit about:

  • 13 Upper case wide size characters (example: “WM”)

  • 17 Upper case regular size characters (example: “ABC”)

The host can load this file type to control the behavior of the device’s American Express contactless kernel when the card sends tag 9F70 and one or more DRL is defined.

The host can load it using Start Send File to Device (Unsecured) - Command 0xD812. See the Expresspay 4.0.2 specification for functional details.

MagTek provides tools that allow these settings to be loaded using a Microsoft Excel spreadsheet in xlsx format for more convenient authoring, review, and change tracking. For a reference sample spreadsheet, contact MagTek Support Services. The MagTek tools expect the spreadsheet to be formatted as shown in Table 43. Each DRL to be supported is defined in a tab of the Excel file.

The host uses this command to provide the device with additional/modified data to resume a transaction that is currently paused.

The host can use this command to cancel a transaction in progress that it initiated using Start Transaction - Command 0x1001.

Sequence of events:

The host uses this command to provide a cardholder selection to the device when the device itself does not have a display or inputs to prompt the cardholder for a selection.

Sequence of events:

Card emulation is initiated by receiving a 0x1840 command from the host. The device will prepare card emulation with the parameters provided in the command and start card emulation.

The sequence of events is as follows:

This section of the DynaFamily Programmer's Manual lists available Device Control commands to initiate various functions in the device.

This command allows the host to bring up standalone pages. A page is considered standalone if it’s stateless, meaning it will be:

• Shown on the display.

• Can allow user input.

• Returns user input result to the host.

Pass-Through Mode is independent and separate from EMVCo Payment functions. This mode is typically used by developers that require the need for non-payment low-level APDU communications with NFC cards, tokens, and devices.

This section of the DynaFamily Programmer's Manual lists settings and information commands.

The host uses this command to request that the device display a message for the cardholder.

The sequence of events is as follows:

Example (Hex):

The host uses this command to trigger the device to immediately show a pre-loaded image on the display, provided the device is not in a mode that has exclusive use of the display (such as during a transaction). This is an immediate and temporary directive. For a solution that affects the device’s idle page behavior on a more permanent basis, see Property 1.2.3.1.1.1 Custom Idle Page Image. This command is different from Show Bitmap Image - Command 0x1823 in that the bitmaps are pre-loaded and persistently stored in the device and can not be composited with each other.

The sequence of events is as follows:

If the request started successfully, the Request Status in the message wrapper is All Good, Requested Operation Was Successful.

The host uses UI Page Option 0x01 to display a page with a title, a maximum of 6 data buttons (2 rows and 3 columns in Landscape Screen Orientation, 3 rows and 2 columns in Portrait Screen Orientation) with text, and maximum 3 functional buttons with a color option of red, green, or yellow.

The host uses UI Page Option 0x01 to display a page with a title, maximum of 4 data buttons (2 rows and 2 columns in Landscape Screen Orientation, 2 rows and 2 columns in Portrait Screen Orientation) with text, and maximum 3 functional buttons with a color option of red, green, or yellow.

The host uses UI Page Option 0x02 to display a page with a title, maximum of 6 data buttons (2 rows and 3 columns in Landscape Screen Orientation, 3 rows and 2 columns in Portrait Screen Orientation) with $Amount, and maximum 3 functional buttons with a color option of red, green, or yellow.

The host uses UI Page Option 0x02 to display a page with a title, maximum of 4 data buttons (2 rows and 2 columns in Landscape Screen Orientation, 2 rows and 2 columns in Portrait Screen Orientation) with $Amount, and maximum 3 functional buttons with a color option of red, green, or yellow.

The button with **$**Amount value is host provided. The title, data buttons text, and functional buttons are labeled with String IDs associated with configured String messages. See Table – Default User Interface String IDs and Strings. When the user presses any button, the device sends a notification to the host to indicate the corresponding button is pressed. See User Interface Host Action Request - Notification 0x1803. After that, the host will decide what to do next.

• Landscape Screen Orientation:

  • Title text:

    • ~18 Upper case wide size characters (example: “WM”)

File Operations

This section of the DynaFamily Programmer's Manual lists commands to move, save, and manipulate files.

Information in this group

Security

This section of the DynaFamily Programmer's Manual lists available security commands to utilize various functions in the device.

Information in this group

This non-TLV data structure consists of four or five bytes that describes a security operation, including the algorithms and methods to be used in that operation.

The host uses these commands to interact with various areas of the device's user interface.

The host can use this command to terminate a Bluetooth® LE connection. The host may also be able to terminate a Bluetooth® LE connection directly without using this command.

The sequence of events is as follows:

The host can use this command to extend a session for open protocol interfaces, such as the WLAN interface, which require session management to meet PCI requirements.

The sequence of events is as follows:

The host uses this command to prompt a cardholder for customer information.

The host uses this command to reset the device.

The host can use this command to erase all Bluetooth® LE bonds. The user should then forget the device and re-pair the device on any host that it was previously paired with if that host needs to communicate with the device again.

The sequence of events is as follows:

The host uses this command to request the deletion of a file stored on the device.

The sequence of events is as follows:

The host uses this command to enter or exit Pass-Through Mode.

The Host must “Enter Pass-Through Mode” prior to using any other commands in this section. Otherwise, subsequent commands will be “ignored” / “rejected”. When finished, the Host should “Exit Pass-Through Mode”. Once exited, the reader returns to its “normal state” and will accept traditional commands.

The host uses this command to prompt the device for a response that contains the same payload it sent.