1 of 1

(Preliminary Documentation) Message Structure

Each message type follows a specific structure described below.

Request Message

Request Message Format

Tag

Len

Value / Description

Typ

Req

Default

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

Grp

Sub

Cde

Meaning

Error Codes

Tag

Len

Value / Description

Typ

Req

Default

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 .

Tag

Len

Value / Description

Typ

Req

Default

Example (Hex)

(Preliminary Documentation) Message Structure

Each message type follows a specific structure described below.

Request Message

Request Message Format

Tag

Len

Value / Description

Typ

Req

Default

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

Grp

Sub

Cde

Meaning

Error Codes

Tag

Len

Value / Description

Typ

Req

Default

Tag

Len

Value / Description

Typ

Req

Default

Example (Hex)

Requested Operation Failed

000002

Setting up RTC data and time failure

000010

Setting up RTC alarm failure

000011

Key generation failure

000012

Tamper setting is locked, can’t be changed

000013

Tamper setting requires system reset to continue

000014

Tamper status can’t be cleared, failure

000015

Device has been tampered, need attention

000016

Tamper module failed for other cases

000017

Setting WLAN SoftAP password failure

000018

Bad message parameter. The host has sent a message to the device that is not constructed properly.

010102

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.

010109

PIN Key Not Mapped.

010110

Feature Not Available

010113

No Valid Subscription

01011E

Reserved

020100

Generic Failure

020101

Bad Message Parameter

020102

Response Payload too big

020103

Internal FW Failure

020107

Image Failure

02010A

Key does not exist

020119

Not Secured

02011A

Passcode validation failed

02011B

Device is locked

02011C

Device in Restricted mode

02011D

Reserved

020200

Failed, device state issue, no transaction.

020304

Failed, device state issue, cannot cancel.

020305

Failed, device state, Transaction in Progress.

020308

Failed, device state, Signature Not allowed

02030C

Failed, device state, Wrong Transaction State

02030D

Failed, device state, Invalid PIN Entry State

02030E

Failed, device state, PIN Entry in Session.

02030F

Failed, device state, Barcode Read in Progress.

020311

Failed, device state, Pass-through command Not Activated.

020314

Failed, device state, UI Settings in Progress.

020314

Failed, device state, Buzzer in Progress

020315

Failed, device state, Low Battery (5% or less)

020316

Request is invalid while card emulation is in progress

020318

Failed, device state, pass-through mode started

02031E

Failed, device state, pass-through mode is not started

02031F

Failed, device state, pass-through mode APDU is in progress

020320

Failed, BCR hardware not found.

020413

Invalid TR31parameter

020501

Invalid AES length

020502

Invalid 16-Byte Boundary

020503

Invalid Length in Message

020504

Invalid number of optional KBH

020505

Error in conversion of data type

020506

Invalid KCV algorithm

020506

Invalid KCV length

020508

Invalid Optional KBH ID

020509

Invalid KBH ID

02050A

Invalid algorithm used in KBH

02050B

Invalid KBH usage

02050C

Invalid KBH length

02050D

Invalid version ID for key derivation

02050E

Invalid KBH mode of use

02050F

TR31 engine not installed

020510

Invalid Cryptographic operation

020511

MAC Verification Failed

020512

Error in Decrypting Key data

020513

Error in computing MAC over entire message

020514

Invalid MAC length

020515

KDF Error

020516

Buffer Insufficient

020517

Invalid Storage KPM

020518

Invalid Storage Secure RAM

020519

Invalid Key ID specified in option block

02051A

Unsupported Key ID specified in option block

02051B

Invalid Key ID Relationship

02051C

Protection Key ID not loaded

02051D

Invalid Data Tag MagTek Custom option block

02051E

Invalid Kcv

02051F

Invalid Data

020520

Invalid DUKPT key derivation

020521

Invalid Exportability

020522

Invalid Key Class

020523

Invalid DSN

020524

Invalid Challenge

020525

Key Undeletable

020526

Key not present

020527

Unsupported Keyset ID

020528

KPM Error

020529

Secure RAM Error

02052A

Duplicated Key

02052B

Invalid Key Usage Rule

02052C

Selftest Key Corrupted

02052D

Selftest System Key Bitmap Corrupted

02052E

Selftest System Key Missing

02052F

Selftest System Key Not Loaded

020530

Invalid Key Storage Limit

020531

Duplicated Key set

020532

Key Restriction

020533

Key Transported by Weaker key

020534

Repeat Key Agreement

020535

Security not activated

020536

Selftest key relocated

020537

Invalid Selftest Scanned Versus Saved Bitmap

020538

One-byte standard API Framework Version, not TLV. Values as in requests/responses.

Message Information

/null

(1)

Message Type & Direction:

0x03 = Notification from host to device (Reserved).
0x83 = Notification from device to host.

/null

(1)

Reserved, set to 0x00

/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 Example values:

0x01 = Transaction.
0x09 = Firmware Update.
0x10 = Device.

/null

(1)

Notification Type — append to Notification Source to identify specific notification (e.g.,

0x01 = Information Update.
0x02 = Warning.
0x03 = Action Request.
0x04 = Callback.

/null

(var)

Reserved

(4)

Notification Detail Code — combined with Notification Source and Notification Type to form a unique six-byte Notification ID. See for notification-specific detail codes.

/null

Category — e.g., 0x00 = Power/Reset

/null

Reason — e.g., 0x02 = Battery

/null

Reason Detail (Subgroup) — e.g., 0x01 = Power Down Imminent

/null

Reserved, set to 0x00

var

Additional Detail — see notification definition in

var

Notification Payload — as documented in the notification’s table in

var

Reserved

One-byte standard API Framework Version, not TLV. Values as in requests/responses.

Message Information

/null

(1)

Message Type & Direction:

0x04 = Data file from host to device.
0x84 = Data file from device to host.

/null

(1)

Message Reference Number — host value to match responses.

/null

(2)

Command Number that prompted this message (see Command Group 0xD8nn - File Operations).

/null

(4)

File Type — the file type as defined in .

var

File Payload — as documented in .

Invalid AES length

020502

Invalid KBH mode of use

02050F

MAC Verification Failed

020512

KDF Error

020516

Invalid DUKPT key derivation

020521

Duplicated Key

02052B

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.

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

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

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

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

(Preliminary Documentation) Message Structure

Request Message

Request Message Format

(Preliminary Documentation) Message Structure

Request Message

Request Message Format

Response Message

Response Message Format

Operation Status Detail Codes

General (group 0x00)

Message Handler (group 0x01)

Request Handler (group 0x02) — representative entries

Notification Message

Notification Message Format

Data File Message

Data File Message Format

Data File Message Example

(Preliminary Documentation) Message Structure

Request Message

Request Message Format

(Preliminary Documentation) Message Structure

Request Message

Request Message Format

Response Message

Response Message Format

Operation Status Detail Codes

General (group 0x00)

Message Handler (group 0x01)

Request Handler (group 0x02) — representative entries

Notification Message

Notification Message Format

Data File Message

Data File Message Format

Data File Message Example

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