# 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 <a href="https://magtek.gitbook.io/magtek-pilot-gitbooks/internal-documentation/index/6.0-commands"><strong>6 Commands</strong></a>.</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><thead><tr><th width="75">Tag</th><th width="71">Len</th><th width="347">Value / Description</th><th width="82">Typ</th><th width="75">Req</th><th width="97">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.</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: 0x02 = Response from host to device (Reserved); 0x82 = Response from device to host.</td><td></td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>Message Reference Number (echo of host’s reference).</td><td></td><td>R</td><td></td></tr><tr><td>/null</td><td>(2)</td><td>Response ID — matches fully qualified Command number from the corresponding Request message.</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>04</td><td>Response Status</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td><p>Operation Status Summary: e.g., 0x00 = OK Done </p><p>0x01 = OK Started/Running </p><p>0x80 = Failed to start; 0x81 = Failed during operation.</p></td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>Operation Status Detail (Group). See Table 13 for codes (examples: 0x02 = Security/Permission Problems).</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>Operation Status Detail (Subgroup). See Table 13 (examples: 0x03 = Device State Issue).</td><td>B</td><td>R</td><td></td></tr><tr><td>/null</td><td>(1)</td><td>Operation Status Detail (Status Code). See Table 13 (examples: 0x16 = Low Battery (5% or less)).</td><td>B</td><td>R</td><td></td></tr><tr><td>83</td><td>var</td><td>Additional Details — help isolate problems (e.g., specific parameter number or EMV tag). See command definition in section <strong>6 Commands</strong>.</td><td></td><td>O</td><td></td></tr><tr><td>84</td><td>var</td><td>Response Payload — as documented in the message’s Response table in section <strong>6 Commands</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>

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

| Grp | Sub | Cde | Meaning                                          |
| --- | --- | --- | ------------------------------------------------ |
| 00  | 00  | 00  | All good / requested operation was successful.   |
| 00  | 00  | 02  | Requested Operation Failed                       |
| 00  | 00  | 10  | Setting up RTC data and time failure             |
| 00  | 00  | 11  | Setting up RTC alarm failure                     |
| 00  | 00  | 12  | Key generation failure                           |
| 00  | 00  | 13  | Tamper setting is locked, can’t be changed       |
| 00  | 00  | 14  | Tamper setting requires system reset to continue |
| 00  | 00  | 16  | Device has been tampered, need attention         |
| 00  | 00  | 18  | Setting WLAN SoftAP password failure             |

## Message Handler (group 0x01)

| Grp | Sub | Cde | Meaning                                                                                 |
| --- | --- | --- | --------------------------------------------------------------------------------------- |
| 01  | 01  | 01  | Generic Failure.                                                                        |
| 01  | 01  | 02  | Bad message parameter. The host has sent a message that is not constructed properly.    |
| 01  | 01  | 09  | Device offline, cannot process messages (e.g., keys not injected or tamper registered). |
| 01  | 01  | 10  | PIN Key Not Mapped.                                                                     |
| 01  | 01  | 13  | Feature Not Available                                                                   |

## Request Handler (group 0x02) — representative entries

| Grp | Sub | Cde | Meaning                                        |
| --- | --- | --- | ---------------------------------------------- |
| 02  | 01  | 01  | Generic Failure                                |
| 02  | 01  | 02  | Bad Message Parameter                          |
| 02  | 01  | 03  | Response Payload too big                       |
| 02  | 01  | 07  | Internal FW Failure                            |
| 02  | 01  | 19  | Key does not exist                             |
| 02  | 01  | 1A  | Not Secured                                    |
| 02  | 03  | 04  | Failed, device state issue, no transaction     |
| 02  | 03  | 08  | Failed, device state, Transaction in Progress  |
| 02  | 03  | 16  | Failed, device state, Low Battery (5% or less) |
| 02  | 04  | 13  | Failed, BCR hardware not found.                |

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

(MAGTEK INTERNAL ONLY FOR NOW — other groups like EMV Tag Processing 0x03, Keys/Crypto 0x04, Configuration 0x05, Kernel sets 0xF0/0xF1 are reserved or internal)

***

## Notification Message

## Table - Notification Message Format

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


---

# Agent Instructions: 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:

```
GET https://developer.magtek.com/hardware/card-readers/mms-dyna-devices/emv-common-kernel/dynaflex-ii-go/documents/programmers-manuals/programmers-manuals-commands/messages-requests-responses-notifications-and-files/message-structure.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.