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 .

Message Format & Structure

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.

Information in this group

Each message type follows a specific structure described below.

Request Message

Request Message Format

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.

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

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, , or .

Example (Hex)

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 (bit 6 = 0), meaning it contains its values directly, or constructed (bit 6 = 1), meaning the TLV data object contains more TLV data objects.
• 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).
• 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."

Below is an example of a TLV-encoded request and response for , wrapped in the standard message format.

Host sends the device the binary byte stream:

Breakdown:

• AA00 = Standard Start of Message / API Framework Version (not TLV)

• 81, 04, 0101DF01

  • Tag 81 = Request Message Parameter 1, Message Information

Device responds with the binary byte stream:

Breakdown:

• AA00 = Standard Start of Message / API Framework Version (not TLV)

• 81, 04, 8201DF01

  • Tag 81 = Response Message Parameter 1, Message Information

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

In TLV tables, a Length of var means the length is variable and must be calculated based on nested objects.

See Table MFT-1 below for an example.