# Messages, Commands, Responses, and Notifications #### About Messages, Commands, Responses, and Notifications The host and the device communicate with each other by exchanging blocks of data called Messages, which can be either Commands, Responses to commands, or Notifications. For example, the host may send a *command* to the device to change a configuration setting, and the device may send a *response* that the command was successful; when a cardholder inserts a card, the device may send a *notification* to the host that a cardholder has initiated a transaction. The device can only service one command at a time, and sends each response within a pre-determined finite amount of time after receiving the command. After sending a command, the host must wait until the device returns a response before sending another command. The device sends notifications 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. Although the wrappers for messages may be different depending on the connection type the host and device are using to communicate, the message payload format and contents are exactly the same. For example, apart from the wrapper differences defined in section 3 Connection Types, a message sent over an RS-232 connection will be exactly the same as a message sent over a USB-HID connection. #### About Big Block Commands and Notifications There are some cases where data transmitted from the host to the device or from the device to the host requires special treatment. For example, some commands require the host or the device to transmit large blocks of data that exceed the maximum packet size of the chosen data transport layer; other commands require transmitted data to be encrypted and/or encoded, fully received, then decrypted and/or decoded as a single piece. For commands, responses, and notifications that require this special treatment, the usage information in this document indicates that the data should be sent as Big Block Data. For commands from the host to the device that require big block messages, either because the message exceeds the current connection’s maximum packet size or because the message requires special treatment such as encryption, the host should first compose the full command message in local memory according to the usage table of the desired command, then transmit the message using Command 0x01::0x10 - Send Big Block Command. See that command’s documentation for details. The host should always anticipate the device could send responses or notifications that exceed the current connection’s maximum packet size, and that the device will transmit them using multiple instances of Notification 0x01::0x10 - Big Block Device Data. The host must count all instances and concatenate them to form a complete message. See that notification’s documentation for usage details. #### About Responses **ACK Response** After receiving a command that does not require the device to return data, the device sends a simple response to the host to acknowledge (“ACK”) the command. The response includes the Message Type Data Object (Tag C0) indicating it is a response, the Application ID Data Object (Tag C1) and the Command ID Data Object (Tag C2) identical to the command the device is acknowledging, and a Result Code Data Object (Tag C3) reporting the results of the command. Table 2-1 shows an example of an ACK Response from the device after the host has sent Command 0x01::0x02 - Clear Transaction Data, where the device is reporting “OK / Done.” ## Table - Example ACK Response “OK / Done”


Tag	Len	Value(s) / Description
C0	01	02	Message Type Data Object (Tag C0) = Response
C1	01	01	Application ID Data Object (Tag C1) = Application Group 0x01 - General Messages
C2	01	02	Command ID Data Object (Tag C2) = Command 0x01::0x02 - Clear Transaction Data
C3	01	00	Result Code Data Object (Tag C3) = OK / Done

Table 2-2 shows an example of an ACK Response from the device where the host has sent a command using an invalid message format (protocol violation) and the message is “Bad Message Format.” ## Table -Example ACK Response “Bad Message Format”


Tag	Len	Value(s) / Description
C0	01	02	Message Type Data Object (Tag C0) = Response
C1	01	10	Application ID Data Object (Tag C1) = 0x01 General Messages
C2	01	10	Command ID Data Object (Tag C2) = Command 0x01::0x10 - Send Big Block Command
C3	01	FF	Result Code Data Object (Tag C3) = Bad Message Format

#### Message Format Messages exchanged between the host and the device consist of a required header, which consists of three or four specific tag-length-value (TLV) data objects, plus in many cases a fifth top-level TLV data object containing a data payload. Table 2-3 shows the header TLV data objects in the order the host should use when sending messages, and should expect when receiving messages. Details about each of the top-level data objects are provided in the following sections, and every command and notification in section 4 Command Set provides concrete usage tables that show byte-by-byte how the host software should compose or interpret the message. ## Table - Message Format


Tag	Data Value / Data Object(s)
C0	Message Type Data Object (Tag C0), sometimes abbreviated MTYP (always included)
C1	Application ID Data Object (Tag C1), sometimes abbreviated APPID (always included)
C2	Command ID Data Object (Tag C2), sometimes abbreviated CMDID (always included)
C3	Result Code Data Object (Tag C3), sometimes abbreviated RC (not always included)
C4	Data Field Data Object (Tag C4 or E0), sometimes abbreviated DATA (not always included)

The TLV data objects are constructed using the Basic Encoding Rules (BER) for the industry standard format defined in *ITU-T X.680|ISO/IEC 8824-1* and *ITU-T X.690|ISO/IEC 8825-1*. These standards are also the basis of *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, especially for programmers who are familiar with the operation of chip cards. Summarizing those specifications, each TLV data object follows these basic rules: * The Tag portion is a single byte that identifies the TLV data object \[such as 0xC0 in the case of **Message Type Data Object (Tag C0)].** · The Length portion is calculated as the total length of the Data portion that follows it. Lengths can be either one byte long from 0x00 to 0x7F, or multiple bytes starting with 0x80 or higher, in which case the lower 7 bits of the first byte specify how many subsequent bytes will indicate the length of the Data portion that follows. For example, in the case of Length 8201C3, 0x82 is greater than 0x7F, and the lower 7 bits equal 0x02, so the next 2 bytes 0x01C3 give the total length of the data block, 451 bytes. * The Data portion is the actual payload of the TLV data object. **Message Type Data Object (Tag C0)** The Message Type TLV data object specifies the message type: Either Command, Response, or Notification. Table 2-4 formally defines the TLV data object. ## Table - Message Type TLV Data Object (Tag C0)


TAG	1 Byte	C0	Message Type (MTYP) Tag
LEN	1 Byte	01	For this data object, Length is always 1 byte
DATA	Byte	Value	Definition
Data	1	01	Command message type
Data	1	02	Response message type
Data	1	03	Notification message type

For device operations that take a long time or an indefinite amount of time, the host usually sends a command that initiates the operation, and the device returns an ACK Response to indicate it has started the operation. When the operation completes, the device sends a Notification to the host. **Application ID Data Object (Tag C1)** The Application ID TLV data object specifies which Application ID the message belongs to. Each functional subsystem of the device has a unique Application ID, and contains a defined message set pertaining to that subsystem. For example, a device might contain an MSR application for its magnetic stripe reader and an EMV L2 Contact application for interacting with contact chip cards. Table 2-5 formally defines the TLV data object. ## Table - Application ID TLV Data Object (Tag C1)


TAG	1 Byte	C1	Application ID (APPID)
LEN	1 Byte	01	Length is Always 1
DATA	Byte	Value	Definition
1	00..08	Application Group 0x00 - Device Information Messages Application Group 0x01 - General Messages Application Group 0x02 - Authentication Messages Application Group 0x03 - Device Configuration Messages Application Group 0x04 - Magnetic Stripe Reader (MSR) Messages Application Group 0x05 - PAN Messages Application Group 0x07 - EMV L2 Contact Messages (Chip Card L2 Mode Only)

**Command ID Data Object (Tag C2)** The Command ID TLV data object has a different meaning for each of the possible values in the **Message Type Data Object (Tag C0):** * For Commands, the Command ID defines the operation to be carried out by the device. * For Responses, the Command ID refers to the operation that was carried out by the device, and always contains the same value as the Command ID Data Object (Tag C2) from the originating command. * For Notifications, the Command ID specifies the event that has occurred in the device. Table 2-6 formally defines the TLV data object. ## Table - Command ID TLV Data Object (Tag C2)


TAG	1 Byte	C2	CMDID
LEN	1 Byte	01	Length is Always 1
DATA	Byte	Value	Definition
Data	1		Command ID within specified Application Group

**Result Code Data Object (Tag C3)** The Result Code TLV data object has different meaning for each of the possible values in the Message Type Data Object (Tag C0): * For Commands, the host should not send this data object to the device. * For Responses, the result code reports the result of the operation that was carried out by the device. * For Notifications, the result code reports the result of the event that has occurred in the device. The Table below formally defines the TLV data object. ## Table - Result Code TLV Data Object (Tag C3)


TAG	1 Byte	C3	Result Code (RC)
LEN	1 Byte	01	Length is Always 1
DATA	Byte	Value	Definition
Data	1 (Result Code)	00..FF	0x00 = OK / Done 0x01 = Failure 0x02 = Warning 0x03 = Cardholder Cancel 0x04 = Timeout 0x05 = Host Cancel 0x06 = Verify fail 0x07 = Bad Message Header 0x08 = Bad Application ID 0x09 = Bad Message ID 0x0A = Bad Parameter 0x0B = System State Error 0x0F = Current Device Status Prohibits Command 0x10 = Command not supported 0x11 = Requested item not available 0x12 = No card inserted 0x13 = Wrong card inserted 0x14 = Smart card not accessible 0x15 = Application already running 0x16 = Requested item expired 0x17 = Configuration locked, modification prohibited 0x18 = Error state 0x19 = No encryption keys available 0xFF = Bad Message Format


		80..FF	This range is for custom result codes. A custom result code has a unique meaning for a particular application. 0x80 = Device Error. A device error or tamper has been detected, the Device Certificate is missing or has been changed, or signature is not correct. 0x81 = Device not Idle 0x82 = Data Error or Bad Parameter(s). The command contains bad parameters. For example, in a big block command transfer, the parameters in any packet 1 through n don’t match (or don’t follow) the previous data packet’s parameters; it may also indicate a bad CBC- MAC ACKSTS, wrong serial number, or a bad key. 0x83 = Length Error or OID error. The data size is 0 or is larger than the available buffer size, or a data packet is incomplete, or MagTek device OID of the certificate doesn’t match the predefined OID 0x8A = Device not Available, Device Status is not OK, Touchscreen is not connected or doesn’t exist, or Mutual Authentication challenge token has timed out (i.e. is not used within 5 minutes) 0x90 = Certificate or associated CA doesn’t exist. For unbind/rebind/key injection, the associated certificate doesn’t exist 0x91 = Expired (Certificate/Certificate Revocation List) 0x92 = Invalid (Certificate/Certificate Revocation List/Message) 0x93 = Revoked (Certificate/Certificate Revocation List) 0x94 = Associated Certificate or Certificate Revocation List doesn’t exist 0x95 = Certificate exists 0x96 = Duplicate KSN/Key. The key already exists.

80..FF

This range is for custom result codes. A custom result code has a unique meaning for a particular application.

0x80 = Device Error. A device error or tamper has been detected, the Device Certificate is missing or has been changed, or signature is not correct.

0x81 = Device not Idle

0x82 = Data Error or Bad Parameter(s). The command contains bad parameters. For example, in a big block command transfer, the parameters in any packet 1 through n don’t match (or don’t follow) the previous data packet’s parameters; it may also indicate a bad CBC- MAC ACKSTS, wrong serial number, or a bad key.

0x83 = Length Error or OID error. The data size is 0 or is larger than the available buffer size, or a data packet is incomplete, or MagTek device OID of the certificate doesn’t match the predefined OID

0x8A = Device not Available, Device Status is not OK, Touchscreen is not connected or doesn’t exist, or Mutual Authentication challenge token has timed out (i.e. is not used within 5 minutes)

0x90 = Certificate or associated CA doesn’t exist. For unbind/rebind/key injection, the associated certificate doesn’t exist

0x91 = Expired (Certificate/Certificate Revocation List) 0x92 = Invalid (Certificate/Certificate Revocation List/Message)

0x93 = Revoked (Certificate/Certificate Revocation List) 0x94 = Associated Certificate or Certificate Revocation List doesn’t exist

0x95 = Certificate exists

0x96 = Duplicate KSN/Key. The key already exists.

**Data Field Data Object (Tag C4 or E0)** If there is additional data associated with the message, it is contained in the Data Field TLV data object. The length of this field is equal to the length of the whole message minus the length of the message header \[Message Type Data Object (Tag C0), Application ID Data Object (Tag C1), Command ID Data Object (Tag C2), and Result Code Data Object (Tag C3)]. For Primitive data, the Data Field data object is identified with Tag C4. C4 is only used when the data portion of the message only contains raw data and will not include any embedded TLV data objects. Table 2-8 formally defines the C4 data object. ## Table - Primitive Data Field TLV Data Object (Tag C4)


TAG	C4	Primitive tag, for raw data with no encryption
LEN	XX	Length of Data
Data	Value (Hex)	Value of Data

For Constructed data, the Data Field data object is identified with Tag E0. E0 is used if the data portion of the message wraps additional TLV data objects. The TLV data objects that can be embedded in the Data Field are detailed in section 2.5 Data Field, or in the documentation in section 4 Command Set for messages that use them. The data inside an E0 (Constructed type) Data Field is also encoded using the BER TLV data object rules explained in section 2.4 Message Format. It becomes very important pay careful attention to the length of every data object to encode/decode correctly. Programmers way wish to recursively construct those data objects by “nesting” from the inside out. Table 2-9 formally defines the E0 data object. ## Table - Constructed Data Field TLV Data Object (Tag E0)


TAG	E0	E0 = Constructed tag, meaning Data contains other tags
LEN	XX	Length of Data
Data	Value (Hex)	Other tags are present in data section

**Linux Style Date-Time Stamps** Some commands embed Linux-style date-time stamps in their responses. To decode the time embedded in these commands, use a Linux shell to enter a command sequence similar to this: ``` # Convert the hex RTC value to a decimal number # and assign it to ‘RTC_VAL’: $ RTC_VAL=1502981285 # Run the Linux ‘date’ command with format below: $ date +"%F %T %z" -d "1970-01-01 UTC + $RTC_VAL seconds" # Tamper occurred at: 2017-08-17 07:48:05 -0700 ``` #### Data Field Content Objects This section specifies the data objects that can be embedded in the Data Field Data Object (Tag C4 or E0) when it contains Constructed data tagged with type E0. **Primitive Data Types** Throughout this document, the tables that describe tag-length-value (TLV) data structures use the following primitive data types: * A = Alphabetic (string, no numbers). * AN = Alphanumeric (string). * B = Binary value, which includes bit combinations (“OR” types). * CN = Compressed numeric, as defined by *EMV 4.3 Book 3*, section *Data Element Format Conventions*. * N = Numeric, as defined by *EMV 4.3 Book 3*, section *Data Element Format Conventions*. * T = TLV Constructed data object (TLV Value contains additional layers of TLV-encoded data the parser should continue to process). **Data Object F1 - Device Status** The device uses a data object identified by tag F1 to send the device status: ## Table - Contents of Data Object F1 Device Status


Tag	Len	Value(s) / Description
F1	Calculated	Device Status <DF51><len><val> (see Table 2-11) Device Certificate Status <DF52 ><len><val> (see Table 2-12) Reserved <DF53>..<DF5F><len><val>

Tag

Len

Value(s) / Description

Calculated

Device Status <DF51><len><val> (see Table 2-11)

Device Certificate Status <DF52 ><len><val> (see Table 2-12) Reserved <DF53>..<DF5F><len><val>

#### **Data Object DF51 Device Status** Hardware errors will cause the device to not respond to any command, except for device status inquiry. ## Table - Contents of Data Object DF51 Device Status


Value	Bit 7	6	5	4	3	2	1	0
Byte 0 Hardware				UCI Error 0 = Normal 1 = Error		TRNG Error 0 = Normal 1 = Error		Crypto Engine Error 0 = Normal 1 = Error
Byte 1 Reserved								Battery voltage: 0 = Normal 1 = Low, which indicates the device is close to end of life. Voltage can drop off drastically at any time and the device is considered tampered if that occurs.
Byte 2 Reserved
Byte 3 Reserved
Byte 4 Security Status					Real Time Clock Status Setting 0 = RTC has been set to current time. 1 = RTC has not been set to current time.	SYSTEM- CLEARED	Tamper occurred: 0 = Device not tampered 1 = Device tampered	Tamper activated: 0 = Activated 1 = Not activated
Byte 5 One-Time- Programmable (OTP) Memory Status							MAC Address Status: 0 = MAC has been written to OTP 1 = MAC has not been written to OTP	Serial Number Status: 0 = SN has been written to OTP 1 = SN has been NOT written to OTP
Byte 6 Reserved
Byte 7 Reserved
Byte 8 Reserved
Byte 9 Reserved
Byte 10 Reserved
Byte 11 Reserved

#### Data Object DF52 Device Certificate & Key Status ## Table - Contents of Data Object DF52 Device Certificate & Key Status


Value	Bit 7	6	5	4	3	2	1	0
Byte 0 Device Certificate Status	PIN CRL	MSR Keyloader Cert	PIN Keyloader Cert	Device Cert	MSR Sub CA Cert	PIN Sub CA Cert	Device CA Cert	CA Unbind Cert
Byte 1 Device Certificate Status		Device Signing Cert						MSR CRL
Byte 2 Device Key Status							MSR DUKP T KEY
Byte 3 Reserved

**Data Object F4 - Magnetic Stripe Reader Card Data** The device uses TLV Data Object F4 wrapped in Data Object F9 - MACed Message to transmit magnetic stripe data to the host. To find commands, responses, and notifications that use this data object, search this documentation for this section name. The parent data object F9 contains additional tags alongside data object F4 that indicate the conditions and events that produced the magnetic stripe data: * POS Entry Mode (9F39) is included by the device automatically every time the host calls Command 0x04::0x12 - Request MSR Card Data, and is included in Notification 0x07::0x83 - EMV L2 ARQC Message if the host has configured the device to include it by adding 9F39 to data object list DFDF02 in EMV Contact Terminal Settings and Defaults. It contains one of the following based on the card’s service code: * 0x80 = The card data came from a chip card (service code 2xx or 6xx). * 0x90 = The card data came from a magnetic stripe card. * MSR Fallback (DFDF53) which contains one of the following based on the card’s service code and the state the device was in at the time it read the card: * 0x00 = The host did not start an EMV transaction after the card was inserted. The device is returning MSR data from a magnetic stripe card. * 0x01 = The host did not start an EMV transaction after the card was inserted. The device is returning MSR data from a chip card (service code 2xx or 6xx). * 0x81 = The host started an EMV transaction using Command 0x07::0x00 - EMV L2 Start Transaction, the device detected a chip card but reported a transaction failure. * If EMV application setting DFDF67 is configured to MSR Fallback Not Supported, the device did not perform an MSR fallback operation on its own. The host performed host-driven MSR fallback using Command 0x04::0x09 - Read MSR Data, and the device read the magnetic stripe data during card removal. * If EMV application setting DFDF67 is set to MSR Fallback Supported, the device performed an MSR fallback operation automatically, used Notification 0x07::0x82 - EMV L2 User Selection Request to prompt the cardholder to remove the card, and the device read the magnetic stripe data during card removal. In this case: * The transaction failure occurred before the GENAC1 phase. If a failure occurs after the GENAC1 phase, the device does not perform automatic MSR fallback. * The device returns MSR data in the ARQC data in Notification 0x07::0x83 - EMV L2 ARQC Message in TLV data object F4. * If terminal setting DFDF17 specifies F4 should be included in batch data, the device also includes MSR data in the batch data of Notification 0x07::0x84 - EMV L2 Transaction Result. * If the card is in the Account Data Whitelist (see Command 0x03::0x80 - Read PAN Whitelist / Account Data Whitelist) the device includes F4 in TLV data object 70. * If the card is not in the Account Data Whitelist, the device includes F4 in encrypted TLV data object F8. * The device returns tags DFDF53 and 9F39 in the ARQC message in TLV data object 70. If the card’s PAN does not match any entry in the device’s configured Account Data whitelist (see Command 0x03::0x80 - Read PAN Whitelist / Account Data Whitelist), data object F4 contains the tags shown in Table 2-13. If the card is in the device’s configured Account Data whitelist, data object F4 contains the tags shown in Table 2-14. ## Table - Contents of TLV Data Object F9 - MSR Card Data (PAN Does Not Match Account Data Whitelist) ``` 9F39 DFDF53 F4 DFDF31 DFDF33 DFDF35 DFDF36 DFDF38 DFDF3A DFDF43 DFDF4F F8 /* container tag for encryption */ DFDF59 DFDF51 DFDF56 DFDF58 /* # of padding bytes added to DFDF59 value to force length to a multiple of 8 bytes */ DFDF25 ``` TLV data object F8 is an encrypted data object wrapping the encrypted track data and MagnePrint Data nested within data object DFDF59, plus supporting information as clear text in other tags. The device encrypts the value inside data object DFDF59 using the current MSR DUKPT working key used in the relevant transaction. The device uses either the PIN variant or data variant of the key, depending on the current MSR Encryption Variant setting (see Command 0x03::0x72 - Get Device Configuration). As a requirement for using the DUKPT TDES encryption algorithm, the device pads it so the length of its value is a multiple of 8 bytes. The device uses tag DFDF58 to report how many bytes of tag DFDF59 are padding. DFDF59 contains the following after the host decrypts it: ``` FA DF41 DF42 DF43 DF44 ``` ## Table - Contents of TLV Data Object F9 - MSR Card Data (PAN Matches Account Data Whitelist) ``` 9F39 DFDF53 F4 DFDF31 DFDF33 DFDF35 DFDF36 DFDF38 DFDF3A DFDF4F ``` The MAC value is calculated based on the padded \ (the MACing operation requires MACed data length to be multiple of 8). However, after MACing calculation, the padding bytes should not be included in the F9 TLV. The receiving end is responsible for padding the F9 TLV when verifying the corresponding MAC. The MAC is stored in the DFDF6C TLV. \ is the total of the \ and \. Encryption Type data object DFDF51 uses one byte to represent the key scheme, encryption algorithm and variant. Table 2-15 lists the possible values. ## Table - Contents of Encryption Type Data Object DFDF51


Tag	Description
DFDF51	MSR Encryption Type: 1xxx xxxx = DUKPT key xx00 xxxx = TDES xx01 xxxx = AES128 xx10 xxxx - AES256 xxxx xx00 = Data variant xxxx xx01 = PIN variant xxxx xx10 = MAC variant

Tag

Description

DFDF51

MSR Encryption Type: 1xxx xxxx = DUKPT key xx00 xxxx = TDES

xx01 xxxx = AES128 xx10 xxxx - AES256 xxxx xx00 = Data variant xxxx xx01 = PIN variant xxxx xx10 = MAC variant

**Data Object F8 - Encrypted Data** ``` F8 /*container tag for encryption */ DFDF59 /* Encrypted Data Primitive; decrypt data to read tags */ DFDF56 /* Encrypted Transaction Data KSN */> DFDF57 /* Encrypted Transaction Data Encryption Type */ DFDF58 /* # of padding bytes added to DFDF59 value to force length to a multiple of 8 bytes */ ``` **Data Object F9 - MACed Message** ``` F9 /* container for MAC structure and generic data */ DFDF0B(Message Data Information Primitive) DFDF54(MAC KSN) DFDF55(MAC Encryption Type) DFDF25(IFD Serial Number) FA/* container for generic data */ … or DFDF6C ``` The device only uses DFDF6C as the MAC container when it sends this data object in a response to **Command 0x04::0x12 - Request MSR Card Data.** To calculate the F9 MAC to authenticate the message, include the F9 tag, length, and contents, and pad it with zeroes to make overall length a multiple of 8. Use the DUKPT MAC variant of the transaction key (DUKPT MAC variant constant = 0000 0000 0000 FF00 0000 0000 0000 FF00) with the CBC-MAC algorithm, and use the first 4 bytes of the 8. #### Data Object DFDF0B Primitive - Message Data Information Data object DFDF0B contains three bytes that indicate the nature of the data included in the FA container within Data Object F9 - MACed Message. Byte 0 is data type: 0x00 = Reserved 0x01 = EMV Contact L2 Data Byte 1 is encryption type 0x00 = Data is Encrypted 0x01 = Data is Clear Text (account number found in device whitelist) Byte 2 is Reserved. 0x00 = Reserved 0x01 = Set to this value --- # 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/oem-readers-and-components/oem-readers/odynamo/documentation/programmers-manuals/programmers-manual-commands/messages-commands-responses-and-notifications.md?ask= ``` 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.