Message Structure
Each message type follows a specific structure described below.
Request Message
Table - Request Message Format
-
-
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.
-
-
-
81
var
Message Information
B
R
/null
(1)
Message Type & Direction: 0x01 = Request from host to device; 0x81 = Request from device to host (Reserved)
B
R
/null
(1)
Message Reference Number
B
R
/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.
B
R
/null
(var)
Reserved
O
9E
var
Reserved
B
O
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)
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
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
15
Tamper status can’t be cleared, failure
00
00
16
Device has been tampered, need attention
00
00
17
Tamper module failed for other cases
00
00
18
Setting WLAN SoftAP password failure
Message Handler (group 0x01)
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).
Grp
Sub
Cde
Meaning
01
01
01
Generic Failure.
01
01
02
Bad message parameter. The host has sent a message to the device that is not constructed properly.
01
01
09
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.
01
01
10
PIN Key Not Mapped.
01
01
13
Feature Not Available
Request Handler (group 0x02) — representative entries
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
Grp
Sub
Cde
Meaning
02
00
00
Reserved
02
01
00
Reserved
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
0A
Image Failure
02
01
19
Key does not exist
02
01
1A
Not Secured
02
01
1B
Passcode validation failed
02
01
1C
Device is locked
02
02
00
Reserved
02
03
04
Failed, device state issue, no transaction.
02
03
05
Failed, device state issue, cannot cancel.
02
03
08
Failed, device state, Transaction in Progress.
02
03
0C
Failed, device state, Signature Not allowed
02
03
0D
Failed, device state, Wrong Transaction State
02
03
0E
Failed, device state, Invalid PIN Entry State
02
03
0F
Failed, device state, PIN Entry in Session.
02
03
11
Failed, device state, Barcode Read in Progress.
02
03
12
Failed, device state, Pass-through command Not Activated.
02
03
14
Failed, device state, UI Settings in Progress.
02
03
15
Failed, device state, Buzzer in Progress
02
03
16
Failed, device state, Low Battery (5% or less)
02
03
18
Request is invalid while card emulation is in progress
02
03
1E
Failed, device state, pass-through mode started
02
03
1F
Failed, device state, pass-through mode is not started
02
03
20
Failed, device state, pass-through mode APDU is in progress
02
04
13
Failed, BCR hardware not found.
02
05
01
Invalid TR31parameter
02
05
02
Invalid AES length
02
05
03
Invalid 16-Byte Boundary
02
05
04
Invalid Length in Message
02
05
05
Invalid number of optional KBH
02
05
06
Error in conversion of data type
02
05
07
Invalid KCV algorithm
02
05
08
Invalid KCV length
02
05
09
Invalid Optional KBH ID
02
05
0A
Invalid KBH ID
02
05
0B
Invalid algorithm used in KBH
02
05
0C
Invalid KBH usage
02
05
0D
Invalid KBH length
02
05
0E
Invalid version ID for key derivation
02
05
0F
Invalid KBH mode of use
02
05
10
TR31 engine not installed
02
05
11
Invalid Cryptographic operation
02
05
12
MAC Verification Failed
02
05
13
Error in Decrypting Key data
02
05
14
Error in computing MAC over entire message
02
05
15
Invalid MAC length
02
05
16
KDF Error
02
05
17
Buffer Insufficient
02
05
18
Invalid Storage KPM
02
05
19
Invalid Storage Secure RAM
02
05
1A
Invalid Key ID specified in option block
02
05
1B
Unsupported Key ID specified in option block
02
05
1C
Invalid Key ID Relationship
02
05
1D
Protection Key ID not loaded
02
05
1E
Invalid Data Tag MagTek Custom option block
02
05
1F
Invalid Kcv
02
05
20
Invalid Data
02
05
21
Invalid DUKPT key derivation
02
05
22
Invalid Exportability
02
05
23
Invalid Key Class
02
05
24
Invalid DSN
02
05
25
Invalid Challenge
02
05
26
Key Undeletable
02
05
27
Key not present
02
05
28
Unsupported Keyset ID
02
05
29
KPM Error
02
05
2A
Secure RAM Error
02
05
2B
Duplicated Key
02
05
2C
Invalid Key Usage Rule
02
05
2D
Selftest Key Corrupted
02
05
2E
Selftest System Key Bitmap Corrupted
02
05
2F
Selftest System Key Missing
02
05
30
Selftest System Key Not Loaded
02
05
31
Invalid Key Storage Limit
02
05
32
Duplicated Key set
02
05
33
Key Restriction
02
05
34
Key Transported by Weaker key
02
05
35
Repeat Key Agreement
02
05
36
Security not activated
02
05
37
Selftest key relocated
02
05
38
Invalid Selftest Scanned Versus Saved Bitmap
EMV Tag Processing (group 0x03)
(MAGTEK INTERNAL ONLY FOR NOW, not used)
The EMV Tag Processing group 0x03 contains operation status detail codes related to…
Grp
Sub
Cde
Meaning
03
00
00
Reserved
Keys / Cryptographic Handler (group 0x04)
(MAGTEK INTERNAL ONLY FOR NOW, not used)
The Keys / Cryptographic Handler group 0x04 contains operation status detail codes related to…
Grp
Sub
Cde
Meaning
04
00
00
Reserved
Configuration (group 0x05)
(MAGTEK INTERNAL ONLY FOR NOW, not used)
The Configuration group 0x05 contains operation status detail codes related to…
Grp
Sub
Cde
Meaning
05
00
00
Reserved
Kernel Set ‘A’ (group 0xF0)
(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.
Please report occurrences of this type of failure to MagTek Support Services.
The Kernel Set ‘I’ group 0xF1
(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.
Please report occurrences of this type of failure to MagTek Support Services.
TR31 / Cryptographic related (Request Handler subgroup 0x05) — representative entries
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
Notification Message
Table - Notification Message Format
-
-
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.
-
-
-
81
4
Message Information
B
R
/null
(1)
Message Type & Direction: 0x03 = Notification from host to device (Reserved); 0x83 = Notification from device to host.
R
/null
(1)
Reserved, set to 0x00
R
/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)
Reserved
O
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.
B
R
/null
1
Category — e.g., 0x00 = Power/Reset
B
R
/null
1
Reason — e.g., 0x02 = Battery
B
R
/null
1
Reason Detail (Subgroup) — e.g., 0x01 = Power Down Imminent
B
R
/null
1
Reserved, set to 0x00
B
R
83
var
Additional Detail — see notification definition in section 7 Notifications.
O
84
var
Notification Payload — as documented in the notification’s table in section 7 Notifications.
B
O
9E
var
Reserved
B
O
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
-
-
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.
-
-
-
81
08
Message Information
B
R
/null
(1)
Message Type & Direction: 0x04 = Data file from host to device; 0x84 = Data file from device to host.
B
R
/null
(1)
Message Reference Number — host value to match responses.
B
R
/null
(2)
Command Number that prompted this message (see Command Group 0xD8nn - File Operations).
B
R
/null
(4)
File Type — the file type as defined in Command Group 0xD8nn - File Operations.
B
R
84
var
File Payload — as documented in section 6.7.1 About Files.
B
R
Table - Data File Message Example
Example (Hex)
Last updated