> For the complete documentation index, see [llms.txt](https://developer.magtek.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.magtek.com/hardware/card-readers/mms-dyna-devices/dynaflex-ii-ped/documentation/developers-manuals/dynaflex-ii-ped-programmers-manual/messages.md). # Messages 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 **Command**. * 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. ### Notifications * Notifications 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 **Command 0x1F02 - Set Notification Subscriptions**. ### Data Files * 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 section **2 Connection Types**. ### Tag-Length-Value (TLV) Encoding #### About TLV Encoding All messages exchanged between the host and the device are formatted using the tag-length-value **Distinguished Encoding Rules** (DER) defined in ***ITU-T X.680 | ISO/IEC 8824-1*** and ***ITU-T X.690 | ISO/IEC 8825-1***. A subset of these standards is also used in ***EMV Integrated Circuit Card Specifications for Payment Systems 4.3, Part IV, Annex B Rules for BER-TLV Data Objects***, so the latter can serve as a useful point of reference. Summarizing those specifications, each TLV data object follows these basic rules: * The DER standard designates the least significant bit of a byte as **bit 1**, and the most significant bit of a byte as **bit 8**. This is different from the remainder of the MMS standard, which indexes bit numbers starting at 0 to be consistent with each bit position number representing that bit’s power of 2. * The **Tag** or **Identifier** portion of a TLV data object identifies the TLV data object. DER assigns the tag portion as follows: * Bits 8 and 7 specify whether the TLV data object is universal, application-defined, context-specific, or private. Most messages in this standard contain **context-specific** tags (bits 8 and 7 = **10**), meaning different messages reuse the same tags, and the tags represent sequentially numbered parameters passed in any message. * Bit 6 specifies whether the tag is **primitive** (bit 6 = **0**), meaning it contains its values directly, or **constructed** (bit 6 = **1**), meaning the TLV data object contains more TLV data objects. * Bits 5 to 1 specify a unique tag number, with 11111 reserved to mean the tag is not a single byte long. In that multi-byte case: * Bits 7 to 1 of subsequent bytes with bit 8 set to 1 are also part of the tag identifier with the most significant of the whole tag number in bit 7. * Bits 7 to 1 of the final byte with bit 8 set to 0 are also part of the tag identifier. * The **Length** portion is the total length of the Data portion that follows it. Lengths can be either short form or long form: * Short form: one byte long in the range 0x00 to 0x7F. * Long form: multiple bytes long, starting with one byte 0x80 or greater, where the lower 7 bits specify how many subsequent bytes are used to indicate the length. Example: length 8201C3 — 0x82 indicates two subsequent bytes (0x01C3) giving the total length of the data block (451 bytes). * DER stipulates all TLV objects should be encoded using the smallest length required to fit the data. * The **Value** or **Data** portion is the actual payload of the TLV data object. This document provides message definitions in hexadecimal format; when the host constructs or interprets a message, if no additional encode/decode filtering or translation is in place at the platform layer, it should expect each hexadecimal value shown in this document to be represented as binary bytes in the message stream, not as string literals. For example, FF is a single byte with all bits set to 1, not the two-byte string literal "FF." #### TLV Example Below is an example of a TLV-encoded request and response for **Command 0xDF01 - Echo**, wrapped in the standard message format. Host sends the device the binary byte stream: ``` AA0081040101DF018407DF018103010203 ``` Breakdown: * AA00 = Standard Start of Message / API Framework Version (not TLV) * 81, 04, 0101DF01 * Tag 81 = Request Message Parameter 1, **Message Information** * Length 04 * Value 01 01 DF 01 * 01 = Request from host to device * 01 = Message reference number * DF01 = **Command 0xDF01 - Echo** * 84, 07, DF018103010203 * Tag 84 = Request Message Parameter 4, **Request Payload** * Length 07 * Value DF01 81 03 01 02 03 * DF01 = Payload format is for Request **Command 0xDF01 - Echo** (not TLV) * Tag 81 = Payload Parameter 1, **Value to Echo** * Length 03 * Value 01 02 03 = Value to Echo Device responds with the binary byte stream: ``` AA0081048201DF018204000000008407DF018103010203 ``` Breakdown: * AA00 = Standard Start of Message / API Framework Version (not TLV) * 81, 04, 8201DF01 * Tag 81 = Response Message Parameter 1, **Message Information** * Length 04 * Value 82 01 DF 01 * 82 = Response from device to host * 01 = Message reference number * DF01 = **Command 0xDF01 - Echo** * 82, 04, 00000000 * Tag 82 = Response Message Parameter 2, **Response Status** (one byte Operation Status Summary, three bytes Operation Status Detail) * Length 04 * Value 00 00 00 00 = OK / Done, General / All Good / Requested operation was successful * 84, 07, DF018103010203 * Tag 84 = Response Message Parameter 4 for **Response Payload** * Length 07 * Value DF01 81 03 01 02 03 * DF01 = Payload format is for Response **Command 0xDF01 - Echo** (not TLV) * Tag 81 = Payload Parameter 1, **Value to Echo** * Length 03 * Value 01 02 03 = Value to Echo ## How to Read TLV Tables Tables that show TLV data objects use slashes in front of the **Tag** identifier to indicate that object’s relative level of nesting/containment within other TLV data objects in the same table. These levels are relative and not absolute: a given TLV object may be nested within other TLV objects at any level. Example of slash notation: * Earth contains * /North America, which contains * //United States, which contains * ///California In TLV tables, a Length of **var** means the length is variable and must be calculated based on nested objects. See Table 10 below for an example. #### Table 10 - TLV Table Example
TagLenValue / DescriptionTypReqDefault
A1varTLV data object A1 contains four directly nested TLV data objects: 81, 82, A3, and 84 (A1/81, A1/82, A1/A3, and A1/84). A1/82 is optional (Req = O), so the length of A1 will vary depending on whether or not A1/82 is included (Len = var).TR
/8101TLV data object A1/81 contains one byte and is required. It has no default value because it must be explicitly included.BR
/8203TLV data object A1/82 contains three bytes but is optional. If not included, the device assumes the default value 0x4D6F6D.BO0x4D6F6D
/A308TLV data object A1/A3 contains two TLV data objects: 81 and 82 (A1/A3/81 and A1/A3/82). Its length is the combined length of its two nested objects.TR
//8103TLV data object A1/A3/81 contains three bytes and is required.BR
//8201TLV data object A1/A3/82 contains one byte and is required.BR
/8403TLV data object A1/84 contains three bytes that represent distinct values stored directly inside A1/84 instead of separate nested TLVs.BR
//null(1)Raw byte inside 84 (no TLV). Tag shown as /null, length in parentheses.BR
//null(1)Another raw byte inside 84.BR
//null(1)Another raw byte inside 84.BR
Each message type follows a specific structure described below. ## Request Message ## Table - Request Message Format
TagLenValue / DescriptionTypReqDefault
--One byte standard Start of Message constant, not in TLV format. 0xAA = Standard start of message byte.---
--One-byte standard API Framework Version, not TLV. Values: 0x00 = Pre-production, 0x01 = First production release, 0x02 = Second production release, etc.---
81varMessage InformationBR
/null(1)Message Type & Direction: 0x01 = Request from host to device; 0x81 = Request from device to host (Reserved)BR
/null(1)Message Reference NumberBR
/null(2)Command ID — fully qualified Command number (Command Group, Command within that group). If the Request Payload contains wrappers, the host should specify the command invoked at the core after wrappers are removed.BR
/null(var)ReservedO
84varRequest Payload — as documented in the message’s Request table in section Commands.BR
9EvarReservedBO
Notes: * Message Reference Number: host can use any value to match responses; device echoes it in responses. Recommended: incrementing counter per request within a session. ## Response Message ## Table - Response Message Format ## Table - Operation Status Detail Codes The tables below list operation status detail codes grouped by source and code. (Only a representative subset is shown here; see the full document for all codes.) ## General (group 0x00) {% hint style="info" %} The General group 0x00 contains operation status detail codes related to the platform that do not originate from a specific functional module. Subgroup 0x00 = General {% endhint %}
GrpSubCdeMeaning
000000All good / requested operation was successful.
000002Requested Operation Failed
000010Setting up RTC data and time failure
000011Setting up RTC alarm failure
000012Key generation failure
000013Tamper setting is locked, can’t be changed
000014Tamper setting requires system reset to continue
000015Tamper status can’t be cleared, failure
000016Device has been tampered, need attention
000017Tamper module failed for other cases
000018Setting WLAN SoftAP password failure
## Message Handler (group 0x01) {% hint style="info" %} The Message Handler group 0x01 contains operation status detail codes related to parsing and validating messages. Subgroup 0x01 = Device issues that prevent Message Processing (e.g., Critical Battery, Pending Reset, System Failure, System Busy). {% endhint %}
GrpSubCdeMeaning
010101Generic Failure.
010102Bad message parameter. The host has sent a message to the device that is not constructed properly.
010109Device offline, can not process messages. For example, the device returns this detail code when it does not have keys injected or has registered a tamper.
010110PIN Key Not Mapped.
010113Feature Not Available
## Request Handler (group 0x02) — representative entries {% hint style="info" %} The Request Handler group 0x02 contains operation status detail codes related to starting actual command requests. * Subgroup 0x01 = Data issues (bad, missing, unknown…) * Subgroup 0x02 = Security / permission problems * Subgroup 0x03 = Device state issues (busy, not permitted, tampered, low battery) * Subgroup 0x04 = Device issues (missing hardware or features) * Subgroup 0x05 = TR31 Errors {% endhint %}
GrpSubCdeMeaning
020000Reserved
020100Reserved
020101Generic Failure
020102Bad Message Parameter
020103Response Payload too big
020107Internal FW Failure
02010AImage Failure
020119Key does not exist
02011ANot Secured
02011BPasscode validation failed
02011CDevice is locked
02011DDevice in Restricted mode
020200Reserved
020304Failed, device state issue, no transaction.
020305Failed, device state issue, cannot cancel.
020308Failed, device state, Transaction in Progress.
02030CFailed, device state, Signature Not allowed
02030DFailed, device state, Wrong Transaction State
02030EFailed, device state, Invalid PIN Entry State
02030FFailed, device state, PIN Entry in Session.
020311Failed, device state, Barcode Read in Progress.
020312Failed, device state, Pass-through command Not Activated.
020314Failed, device state, UI Settings in Progress.
020315Failed, device state, Buzzer in Progress
020316Failed, device state, Low Battery (5% or less)
020318Request is invalid while card emulation is in progress
02031EFailed, device state, pass-through mode started
02031FFailed, device state, pass-through mode is not started
020320Failed, device state, pass-through mode APDU is in progress
020413Failed, BCR hardware not found.
020501Invalid TR31parameter
020502Invalid AES length
020503Invalid 16-Byte Boundary
020504Invalid Length in Message
020505Invalid number of optional KBH
020506Error in conversion of data type
020507Invalid KCV algorithm
020508Invalid KCV length
020509Invalid Optional KBH ID
02050AInvalid KBH ID
02050BInvalid algorithm used in KBH
02050CInvalid KBH usage
02050DInvalid KBH length
02050EInvalid version ID for key derivation
02050FInvalid KBH mode of use
020510TR31 engine not installed
020511Invalid Cryptographic operation
020512MAC Verification Failed
020513Error in Decrypting Key data
020514Error in computing MAC over entire message
020515Invalid MAC length
020516KDF Error
020517Buffer Insufficient
020518Invalid Storage KPM
020519Invalid Storage Secure RAM
02051AInvalid Key ID specified in option block
02051BUnsupported Key ID specified in option block
02051CInvalid Key ID Relationship
02051DProtection Key ID not loaded
02051EInvalid Data Tag MagTek Custom option block
02051FInvalid Kcv
020520Invalid Data
020521Invalid DUKPT key derivation
020522Invalid Exportability
020523Invalid Key Class
020524Invalid DSN
020525Invalid Challenge
020526Key Undeletable
020527Key not present
020528Unsupported Keyset ID
020529KPM Error
02052ASecure RAM Error
02052BDuplicated Key
02052CInvalid Key Usage Rule
02052DSelftest Key Corrupted
02052ESelftest System Key Bitmap Corrupted
02052FSelftest System Key Missing
020530Selftest System Key Not Loaded
020531Invalid Key Storage Limit
020532Duplicated Key set
020533Key Restriction
020534Key Transported by Weaker key
020535Repeat Key Agreement
020536Security not activated
020537Selftest key relocated
020538Invalid Selftest Scanned Versus Saved Bitmap
## Notification Message ## Table - Notification Message Format
TagLenValue / DescriptionTypReqDefault
--One byte standard Start of Message constant, not TLV. 0xAA = Standard start of message byte.---
--One-byte standard API Framework Version, not TLV. Values as in requests/responses.---
814Message InformationBR
/null(1)Message Type & Direction: 0x03 = Notification from host to device (Reserved); 0x83 = Notification from device to host.R
/null(1)Reserved, set to 0x00R
/null(1)Notification Source — this byte and Notification Type form the first two bytes of a six-byte Notification ID. Use this byte to look up the Notification Group in 7 Notifications. Example values: 0x01 = Transaction; 0x09 = Firmware Update; 0x10 = Device; 0x18 = User Interface.R
/null(1)Notification Type — append to Notification Source to identify specific notification (e.g., 0x01 = Information Update; 0x02 = Warning; 0x03 = Action Request; 0x04 = Callback; 0x05 = Operation Complete).R
/null(var)ReservedO
82(4)Notification Detail Code — combined with Notification Source and Notification Type to form a unique six-byte Notification ID. See section 7 Notifications for notification-specific detail codes.BR
/null1Category — e.g., 0x00 = Power/ResetBR
/null1Reason — e.g., 0x02 = BatteryBR
/null1Reason Detail (Subgroup) — e.g., 0x01 = Power Down ImminentBR
/null1Reserved, set to 0x00BR
83varAdditional Detail — see notification definition in section 7 Notifications.O
84varNotification Payload — as documented in the notification’s table in section 7 Notifications.BO
9EvarReservedBO
## Data File Message This message type is used exclusively for transferring larger blocks of data treated as files. It is valid only after successful invocation of the appropriate file operation commands (for example, **Command 0xD811 - Start Send File to Device (Secured)**, **Command 0xD812 - Start Send File to Device (Unsecured)**, or **Command 0xD821 - Start Get File from Device**). ## Table - Data File Message Format
TagLenValue / DescriptionTypReqDefault
--One byte standard Start of Message constant, not TLV. 0xAA = Standard start of message byte.---
--One-byte standard API Framework Version, not TLV. Values as in requests/responses.---
8108Message InformationBR
/null(1)Message Type & Direction: 0x04 = Data file from host to device; 0x84 = Data file from device to host.BR
/null(1)Message Reference Number — host value to match responses.BR
/null(2)Command Number that prompted this message (see Command Group 0xD8nn - File Operations).BR
/null(4)File Type — the file type as defined in Command Group 0xD8nn - File Operations.BR
84varFile Payload — as documented in section 6.7.1 About Files.BR
## Table - Data File Message Example Example (Hex) ``` AA 00 81 08 84 08 D8 21 00 00 00 01 84 40 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.magtek.com/hardware/card-readers/mms-dyna-devices/dynaflex-ii-ped/documentation/developers-manuals/dynaflex-ii-ped-programmers-manual/messages.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.