> 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-go/documents/developers-manuals/programmers-manual-commands/messages/message-structure.md).

# Message Structure

Each message type follows a specific structure described below.

## Request Message

## Table - Request Message Format

<table><thead><tr><th width="79.33331298828125">Tag</th><th width="73.66668701171875">Len</th><th>Value / Description</th><th width="80.66668701171875">Typ</th><th width="85">Req</th><th width="110.66656494140625">Default</th></tr></thead><tbody><tr><td>-</td><td>-</td><td>One byte standard <strong>Start of Message</strong> constant, not in TLV format. 0xAA = Standard start of message byte.</td><td>-</td><td>-</td><td>-</td></tr><tr><td>-</td><td>-</td><td>One-byte standard <strong>API Framework Version</strong>, not TLV. Values: 0x00 = Pre-production, 0x01 = First production release, 0x02 = Second production release, etc.</td><td>-</td><td>-</td><td>-</td></tr><tr><td>81</td><td>var</td><td>Message Information</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>Message Type &#x26; Direction: 0x01 = Request from host to device; 0x81 = Request from device to host (Reserved)</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>Message Reference Number</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(2)</td><td>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.</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(var)</td><td>Reserved</td><td></td><td>O</td><td></td></tr><tr><td>84</td><td>var</td><td>Request Payload — as documented in the message’s Request table in section <strong>Commands</strong>.</td><td>B</td><td>R</td><td></td></tr><tr><td>9E</td><td>var</td><td>Reserved</td><td>B</td><td>O</td><td></td></tr></tbody></table>

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 %}

<table data-header-hidden><thead><tr><th width="77"></th><th width="59.3636474609375"></th><th width="57.727294921875"></th><th></th></tr></thead><tbody><tr><td>Grp</td><td>Sub</td><td>Cde</td><td>Meaning</td></tr><tr><td>00</td><td>00</td><td>00</td><td>All good / requested operation was successful.</td></tr><tr><td>00</td><td>00</td><td>02</td><td>Requested Operation Failed</td></tr><tr><td>00</td><td>00</td><td>10</td><td>Setting up RTC data and time failure</td></tr><tr><td>00</td><td>00</td><td>11</td><td>Setting up RTC alarm failure</td></tr><tr><td>00</td><td>00</td><td>12</td><td>Key generation failure</td></tr><tr><td>00</td><td>00</td><td>13</td><td>Tamper setting is locked, can’t be changed</td></tr><tr><td>00</td><td>00</td><td>14</td><td>Tamper setting requires system reset to continue</td></tr><tr><td>00</td><td>00</td><td>15</td><td>Tamper status can’t be cleared, failure</td></tr><tr><td>00</td><td>00</td><td>16</td><td>Device has been tampered, need attention</td></tr><tr><td>00</td><td>00</td><td>17</td><td>Tamper module failed for other cases</td></tr><tr><td>00</td><td>00</td><td>18</td><td>Setting WLAN SoftAP password failure</td></tr></tbody></table>

## 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 %}

<table data-header-hidden><thead><tr><th width="68.8182373046875"></th><th width="59.6363525390625"></th><th width="76.27276611328125"></th><th></th></tr></thead><tbody><tr><td>Grp</td><td>Sub</td><td>Cde</td><td>Meaning</td></tr><tr><td>01</td><td>01</td><td>01</td><td>Generic Failure.</td></tr><tr><td>01</td><td>01</td><td>02</td><td>Bad message parameter.  The host has sent a message to the device that is not constructed properly.</td></tr><tr><td>01</td><td>01</td><td>09</td><td>Device 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.</td></tr><tr><td>01</td><td>01</td><td>10</td><td>PIN Key Not Mapped.</td></tr><tr><td>01</td><td>01</td><td>13</td><td>Feature Not Available</td></tr></tbody></table>

## 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 %}

<table data-header-hidden><thead><tr><th width="56.09088134765625"></th><th width="65.45452880859375"></th><th width="64.81817626953125"></th><th></th></tr></thead><tbody><tr><td>Grp</td><td>Sub</td><td>Cde</td><td>Meaning</td></tr><tr><td>02</td><td>00</td><td>00</td><td>Reserved</td></tr><tr><td>02</td><td>01</td><td>00</td><td>Reserved</td></tr><tr><td>02</td><td>01</td><td>01</td><td>Generic Failure</td></tr><tr><td>02</td><td>01</td><td>02</td><td>Bad Message Parameter</td></tr><tr><td>02</td><td>01</td><td>03</td><td>Response Payload too big</td></tr><tr><td>02</td><td>01</td><td>07</td><td>Internal FW Failure</td></tr><tr><td>02</td><td>01</td><td>0A</td><td>Image Failure</td></tr><tr><td>02</td><td>01</td><td>19</td><td>Key does not exist</td></tr><tr><td>02</td><td>01</td><td>1A</td><td>Not Secured</td></tr><tr><td>02</td><td>01</td><td>1B</td><td>Passcode validation failed</td></tr><tr><td>02</td><td>01</td><td>1C</td><td>Device is locked</td></tr><tr><td>02</td><td>02</td><td>00</td><td>Reserved</td></tr><tr><td>02</td><td>03</td><td>04</td><td>Failed, device state issue, no transaction.</td></tr><tr><td>02</td><td>03</td><td>05</td><td>Failed, device state issue, cannot cancel.</td></tr><tr><td>02</td><td>03</td><td>08</td><td>Failed, device state, Transaction in Progress.</td></tr><tr><td>02</td><td>03</td><td>0C</td><td>Failed, device state, Signature Not allowed</td></tr><tr><td>02</td><td>03</td><td>0D</td><td>Failed, device state, Wrong Transaction State</td></tr><tr><td>02</td><td>03</td><td>0E</td><td>Failed, device state, Invalid PIN Entry State</td></tr><tr><td>02</td><td>03</td><td>0F</td><td>Failed, device state, PIN Entry in Session.</td></tr><tr><td>02</td><td>03</td><td>11</td><td>Failed, device state, Barcode Read in Progress.</td></tr><tr><td>02</td><td>03</td><td>12</td><td>Failed, device state, Pass-through command Not Activated.</td></tr><tr><td>02</td><td>03</td><td>14</td><td>Failed, device state, UI Settings in Progress.</td></tr><tr><td>02</td><td>03</td><td>15</td><td>Failed, device state, Buzzer in Progress</td></tr><tr><td>02</td><td>03</td><td>16</td><td>Failed, device state, Low Battery (5% or less)</td></tr><tr><td>02</td><td>03</td><td>18</td><td>Request is invalid while card emulation is in progress</td></tr><tr><td>02</td><td>03</td><td>1E</td><td>Failed, device state, pass-through mode started</td></tr><tr><td>02</td><td>03</td><td>1F</td><td>Failed, device state, pass-through mode is not started</td></tr><tr><td>02</td><td>03</td><td>20</td><td>Failed, device state, pass-through mode APDU is in progress</td></tr><tr><td>02</td><td>04</td><td>13</td><td>Failed, BCR hardware not found.</td></tr><tr><td>02</td><td>05</td><td>01</td><td>Invalid TR31parameter</td></tr><tr><td>02</td><td>05</td><td>02</td><td>Invalid AES length</td></tr><tr><td>02</td><td>05</td><td>03</td><td>Invalid 16-Byte Boundary</td></tr><tr><td>02</td><td>05</td><td>04</td><td>Invalid Length in Message</td></tr><tr><td>02</td><td>05</td><td>05</td><td>Invalid number of optional KBH</td></tr><tr><td>02</td><td>05</td><td>06</td><td>Error in conversion of data type</td></tr><tr><td>02</td><td>05</td><td>07</td><td>Invalid KCV algorithm</td></tr><tr><td>02</td><td>05</td><td>08</td><td>Invalid KCV length</td></tr><tr><td>02</td><td>05</td><td>09</td><td>Invalid Optional KBH ID</td></tr><tr><td>02</td><td>05</td><td>0A</td><td>Invalid KBH ID</td></tr><tr><td>02</td><td>05</td><td>0B</td><td>Invalid algorithm used in KBH</td></tr><tr><td>02</td><td>05</td><td>0C</td><td>Invalid KBH usage</td></tr><tr><td>02</td><td>05</td><td>0D</td><td>Invalid KBH length</td></tr><tr><td>02</td><td>05</td><td>0E</td><td>Invalid version ID for key derivation</td></tr><tr><td>02</td><td>05</td><td>0F</td><td>Invalid KBH mode of use</td></tr><tr><td>02</td><td>05</td><td>10</td><td>TR31 engine not installed</td></tr><tr><td>02</td><td>05</td><td>11</td><td>Invalid Cryptographic operation</td></tr><tr><td>02</td><td>05</td><td>12</td><td>MAC Verification Failed</td></tr><tr><td>02</td><td>05</td><td>13</td><td>Error in Decrypting Key data</td></tr><tr><td>02</td><td>05</td><td>14</td><td>Error in computing MAC over entire message</td></tr><tr><td>02</td><td>05</td><td>15</td><td>Invalid MAC length</td></tr><tr><td>02</td><td>05</td><td>16</td><td>KDF Error</td></tr><tr><td>02</td><td>05</td><td>17</td><td>Buffer Insufficient</td></tr><tr><td>02</td><td>05</td><td>18</td><td>Invalid Storage KPM</td></tr><tr><td>02</td><td>05</td><td>19</td><td>Invalid Storage Secure RAM</td></tr><tr><td>02</td><td>05</td><td>1A</td><td>Invalid Key ID specified in option block</td></tr><tr><td>02</td><td>05</td><td>1B</td><td>Unsupported Key ID specified in option block</td></tr><tr><td>02</td><td>05</td><td>1C</td><td>Invalid Key ID Relationship</td></tr><tr><td>02</td><td>05</td><td>1D</td><td>Protection Key ID not loaded</td></tr><tr><td>02</td><td>05</td><td>1E</td><td>Invalid Data Tag MagTek Custom option block</td></tr><tr><td>02</td><td>05</td><td>1F</td><td>Invalid Kcv</td></tr><tr><td>02</td><td>05</td><td>20</td><td>Invalid Data</td></tr><tr><td>02</td><td>05</td><td>21</td><td>Invalid DUKPT key derivation</td></tr><tr><td>02</td><td>05</td><td>22</td><td>Invalid Exportability</td></tr><tr><td>02</td><td>05</td><td>23</td><td>Invalid Key Class</td></tr><tr><td>02</td><td>05</td><td>24</td><td>Invalid DSN</td></tr><tr><td>02</td><td>05</td><td>25</td><td>Invalid Challenge</td></tr><tr><td>02</td><td>05</td><td>26</td><td>Key Undeletable</td></tr><tr><td>02</td><td>05</td><td>27</td><td>Key not present</td></tr><tr><td>02</td><td>05</td><td>28</td><td>Unsupported Keyset ID</td></tr><tr><td>02</td><td>05</td><td>29</td><td>KPM Error</td></tr><tr><td>02</td><td>05</td><td>2A</td><td>Secure RAM Error</td></tr><tr><td>02</td><td>05</td><td>2B</td><td>Duplicated Key</td></tr><tr><td>02</td><td>05</td><td>2C</td><td>Invalid Key Usage Rule</td></tr><tr><td>02</td><td>05</td><td>2D</td><td>Selftest Key Corrupted</td></tr><tr><td>02</td><td>05</td><td>2E</td><td>Selftest System Key Bitmap Corrupted</td></tr><tr><td>02</td><td>05</td><td>2F</td><td>Selftest System Key Missing</td></tr><tr><td>02</td><td>05</td><td>30</td><td>Selftest System Key Not Loaded</td></tr><tr><td>02</td><td>05</td><td>31</td><td>Invalid Key Storage Limit</td></tr><tr><td>02</td><td>05</td><td>32</td><td>Duplicated Key set</td></tr><tr><td>02</td><td>05</td><td>33</td><td>Key Restriction</td></tr><tr><td>02</td><td>05</td><td>34</td><td>Key Transported by Weaker key</td></tr><tr><td>02</td><td>05</td><td>35</td><td>Repeat Key Agreement</td></tr><tr><td>02</td><td>05</td><td>36</td><td>Security not activated</td></tr><tr><td>02</td><td>05</td><td>37</td><td>Selftest key relocated</td></tr><tr><td>02</td><td>05</td><td>38</td><td>Invalid Selftest Scanned Versus Saved Bitmap</td></tr></tbody></table>

## Kernel Set ‘A’ (group 0xF0)

{% hint style="info" %}
(MAGTEK INTERNAL ONLY FOR NOW, not used)

The Kernel Set ‘A’ group 0xF0 contains operation status detail codes from a subset of vendor-supplied libraries / modules used by the device’s firmware.  These detail codes are not specifically enumerated here, they simply provide a standard, controlled channel to report messages controlled by third parties.

&#x20;

Please report occurrences of this type of failure to MagTek Support Services.
{% endhint %}

## The Kernel Set ‘I’ group 0xF1

{% hint style="info" %}
(MAGTEK INTERNAL ONLY FOR NOW, not used)

The Kernel Set ‘I’ group 0xF1 contains operation status detail codes from a subset of vendor-supplied libraries / modules used by the device’s firmware.  These detail codes are not specifically enumerated here, they simply provide a standard, controlled channel to report messages controlled by third parties.

&#x20;

Please report occurrences of this type of failure to MagTek Support Services.
{% endhint %}

## Notification Message

## Table - Notification Message Format

<table><thead><tr><th width="76.6666259765625">Tag</th><th width="75.33331298828125">Len</th><th>Value / Description</th><th width="73">Typ</th><th width="74.66668701171875">Req</th><th width="97.66668701171875">Default</th></tr></thead><tbody><tr><td>-</td><td>-</td><td>One byte standard <strong>Start of Message</strong> constant, not TLV. 0xAA = Standard start of message byte.</td><td>-</td><td>-</td><td>-</td></tr><tr><td>-</td><td>-</td><td>One-byte standard <strong>API Framework Version</strong>, not TLV. Values as in requests/responses.</td><td>-</td><td>-</td><td>-</td></tr><tr><td>81</td><td>4</td><td>Message Information</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>Message Type &#x26; Direction: 0x03 = Notification from host to device (Reserved); 0x83 = Notification from device to host.</td><td></td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>Reserved, set to 0x00</td><td></td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>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 <strong>7 Notifications</strong>. Example values: 0x01 = Transaction; 0x09 = Firmware Update; 0x10 = Device; 0x18 = User Interface.</td><td></td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>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).</td><td></td><td>R</td><td></td></tr><tr><td>/null</td><td>(var)</td><td>Reserved</td><td></td><td>O</td><td></td></tr><tr><td>82</td><td>(4)</td><td>Notification Detail Code — combined with Notification Source and Notification Type to form a unique six-byte Notification ID. See section <strong>7 Notifications</strong> for notification-specific detail codes.</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>1</td><td>Category — e.g., 0x00 = Power/Reset</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>1</td><td>Reason — e.g., 0x02 = Battery</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>1</td><td>Reason Detail (Subgroup) — e.g., 0x01 = Power Down Imminent</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>1</td><td>Reserved, set to 0x00</td><td>B</td><td>R</td><td></td></tr><tr><td>83</td><td>var</td><td>Additional Detail — see notification definition in section <strong>7 Notifications</strong>.</td><td></td><td>O</td><td></td></tr><tr><td>84</td><td>var</td><td>Notification Payload — as documented in the notification’s table in section <strong>7 Notifications</strong>.</td><td>B</td><td>O</td><td></td></tr><tr><td>9E</td><td>var</td><td>Reserved</td><td>B</td><td>O</td><td></td></tr></tbody></table>

## 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

<table><thead><tr><th width="78.66668701171875">Tag</th><th width="78.33331298828125">Len</th><th>Value / Description</th><th width="75.6666259765625">Typ</th><th width="79">Req</th><th width="99.0001220703125">Default</th></tr></thead><tbody><tr><td>-</td><td>-</td><td>One byte standard <strong>Start of Message</strong> constant, not TLV. 0xAA = Standard start of message byte.</td><td>-</td><td>-</td><td>-</td></tr><tr><td>-</td><td>-</td><td>One-byte standard <strong>API Framework Version</strong>, not TLV. Values as in requests/responses.</td><td>-</td><td>-</td><td>-</td></tr><tr><td>81</td><td>08</td><td>Message Information</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>Message Type &#x26; Direction: 0x04 = Data file from host to device; 0x84 = Data file from device to host.</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>Message Reference Number — host value to match responses.</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(2)</td><td>Command Number that prompted this message (see Command Group 0xD8nn - File Operations).</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(4)</td><td>File Type — the file type as defined in Command Group 0xD8nn - File Operations.</td><td>B</td><td>R</td><td></td></tr><tr><td>84</td><td>var</td><td>File Payload — as documented in section <strong>6.7.1 About Files</strong>.</td><td>B</td><td>R</td><td></td></tr></tbody></table>

## 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
```

## TR31 / Cryptographic related (Request Handler subgroup 0x05) — representative entries

| Grp | Sub | Cde | Meaning                      |
| --- | --- | --- | ---------------------------- |
| 02  | 05  | 01  | Invalid TR31 parameter       |
| 02  | 05  | 02  | Invalid AES length           |
| 02  | 05  | 0F  | Invalid KBH mode of use      |
| 02  | 05  | 12  | MAC Verification Failed      |
| 02  | 05  | 16  | KDF Error                    |
| 02  | 05  | 21  | Invalid DUKPT key derivation |
| 02  | 05  | 2B  | Duplicated Key               |

## Keys / Cryptographic Handler (group 0x04)&#x20;

{% hint style="info" %}
(MAGTEK INTERNAL ONLY FOR NOW, not used)

The Keys / Cryptographic Handler group 0x04 contains operation status detail codes related to…
{% endhint %}

<table><thead><tr><th width="82.33331298828125"></th><th width="90.33331298828125"></th><th width="100.33331298828125"></th><th></th></tr></thead><tbody><tr><td>GRP</td><td>Sub</td><td>Cde</td><td>Meaning</td></tr><tr><td>04</td><td>00</td><td>00</td><td>Reserved</td></tr></tbody></table>


---

# 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-go/documents/developers-manuals/programmers-manual-commands/messages/message-structure.md?ask=<question>&goal=<endgoal>
```

`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.