The API & Command Reference is where you look up the exact programming details of the ) command sets that MagTek products use — every command, notification, data object, configuration property, and status code. Where the Guides walk you through accomplishing a task end to end, this is where you look up a specific detail while you build.

Information in this group

Security Parameters Type

After the NFC Type A or Type B card is activated, the host uses this command to send application-level APDUs to a PICC that supports ISO 14443-4 Protocol. The device sends the PICC response back to the host.

Request Data for Command 0x3003 – ISO 14443-4 APDU Pass-Through Commands

Example (Hex)

The host can use this command to erase all Bluetooth® LE bonds. The user should then forget the device and re-pair the device on any host that it was previously paired with if that host needs to communicate with the device again.

The sequence of events is as follows:

NFC UID Type

The host can use this command to change the device’s lock passcode. The value of the device lock passcode is stored in non-volatile memory so changes made to it will persist after the device is reset or power cycled. To change the device lock passcode using MagTek security or to see its default value see Property 1.2.5.2.1.3- Device Lock Passcode. See Device Lock Feature for more information.

Change Device Lock Passcode - Request Data for Command 0xEF07

After entering the Pass-Through Mode, the host use this command to request the device to start polling for a Type A and Type B PICC until it detects a PICC or times out. This command automatically turns on the RF Antenna.

After NFC Type A card is detected, the device will stop the polling, activate the card and

• Send a notification that identifies the ISO 14443 Type A (Supports ISO 14443-4 protocol). See Notification 0x0301 – Pass-Through Mode Information Update.

• Send another notification with the UID as a payload.

After NFC Type B card is detected, the device will stop the polling, activate the card and

• Send a notification that identifies the ISO 14443 Type B (Supports l). See .

• Send another notification with the UID as a payload.

If the card is not supported, the device will send error notification and stop the polling.

The host uses this option to display a maximum of 5 lines of host-provided text, and 1 optional green functional button, Middle – label with a String ID that associates it with a configured String message. See Default User Interface String IDs and Strings.

When the user presses this button, the device sends a notification to the host to indicate this button is pressed. See Notification 0x1803 - User Interface Host Action Request. After that, the host will decide what to do next.

Recommend maximum number of characters setting for this page:

Landscape Screen Orientation

• Each text line can fit about:

  • 18 Upper case wide size characters (example: “WM”)

  • 23 Upper case regular size characters (example: “ABC”)

  • 21 lower case wide size characters (example: “wm”)

  • 30 lower case regular size characters (example: “abc”)

• Button text can fit about:

  • 5 Upper case wide size characters (example: “WM”)

  • 8 Upper case regular size characters (example: “ABC”)

  • 6 lower case wide size characters (example: “wm”)

• Each text line can fit about:

  • 13 Upper case wide size characters (example: “WM”)

  • 17 Upper case regular size characters (example: “ABC”)

  • 14 lower case wide size characters (example: “wm”)

The host uses this command to reset the device.

A TR-31(X9.143) key block consists of three parts:

The Key Block Header(KBH) which contains attribute information about the key and the key block and is not encrypted. It is always treated as ASCII.

• The first section is 16 bytes with a fixed format defined below.

• The second section is optional within the standard, but required for current products.

The Confidential Data, which is encrypted and always binary.

• Two bytes indicating the key length (in bits, AES-128 is 128 bits, so length will be 0080).

• The secret key and/or sensitive data.

• Padding as required (random bytes 0x00 to 0xFF).

The MAC, which is of varying length as follows:

• 64 bits if the TDEA key derivation method is used (typically not used for this device).

• 128 bits if the AES key derivation method is used.

Symmetric keys are padded with Block Padding to the maximum length for the algorithm, 192 bits for TDEA or 256 bits for AES, to hide the true length of short keys.

The data to be encrypted and the MAC are always binary for calculation purposes. The encrypted data and the MAC are converted to ASCII hex as the last step.

Date and time strings specified within the TR-31 block are represented according to the rules described in ISO 8601 and TR-31. Year is 4 digits. Time uses UTC 24 hour clock. Some functions like ‘toISOString()’ will produce a string of format yyyy-mm-ddThh:mm:ss.fffZwhere fff is a decimal fraction of a second, Z is UTC time zone. The device ignores ‘Z’ and ‘.fff’ if they are present. Seconds ‘:ss’ are optional. Date, hours, and minutes are required. For example, March 23, 2020 4:19PM is encoded as 2020-03-23T16:19at minimum, but could also be 2020-03-23T16:19:00.000Z.

DUKPT – Derived Unique Key Per Transaction OID– Object Identifier

SRED- Secure Reading and Exchange of Data

There are 7 new OIDs defined for these 7 SRED Data IDs.

Each OID value contains a two-byte DUKPT slot ID and a one-byte transformation ID.

The existing TR31 Module supports 32 MagTek DUKPT Slot IDs, from 0x2000 to 0x201F. The Key Injection Software Tool shall inject DUKPT keys through these DUKPT Slot IDs.

This is the list of DUKPT transformations defined in both the Legacy and AES specifications.

During TR31 Key Injection, each DUKPT Slot ID contains a parameter indicates the purpose of a Key Set.

Example 1: The restriction value is 0x3F

This Key Set can be used for all purposes.

Example 2: The restriction value is 0x3E

This Key Set can be used for all purposes, except PIN Encryption.

Example 3: The restriction value is 0x01

This Key Set can be used for PIN Encryption only.

SRED Data ID map configuration values (Slot ID and Transformation ID) must be checked and rejected if they don’t meet the following conditions.

1. The DUKPT Slot ID must be loaded. ()

2. The loaded DUKPT Slot ID must allows this type of SRED Data ID. ()

3. The transformation must be allowed by ().

Here is the list of parameters of 4 DUKPT Slot IDs based on the existing Key Injection Tool.

Note: If SRED Data ID 2 and 4 are mapped to the same Key Set, then they must have the same Transformation ID. If the Transformation ID of the latest key mapping request is different, then the original OID setting of the other SRED Data ID will be forced to match the latest OID setting. For example, SRED Data ID 2 has been mapped to 0x2007 0x04, user wants to map SRED Data ID 4 to 0x2007 0x05, then the OID setting of SRED Data ID 2 will be forced to 0x2007 0x05.

The following OID Values indicate that:

1. 200701: Map PIN-TDES to DKPTM7-2007 PIN Encryption Variant.

2. 20020B: Map Account Data to DKPTM2-2002 Data Encryption Usage.

3. 200702: Map MAC to DKPTM7-2007 MAC Generate/Verify Variant.

4. 20030B: Map MangePrint to DKPTM3-2003 Data Encryption Usage.

Figure 1 - Configuration Usage Values

• Device refers to the Secure Card Reader Authenticator (SCRA) or PIN Entry Device (PED) that receives and responds to the command set specified in this document. Not all devices support PIN entry. Devices include DynaFlex, DynaProx, DynaFlex II, and so on.

• Host refers to the piece of general-purpose electronic equipment the device is connected or paired to, which can send data to and receive data from the device. Host types include PC and Mac computers/laptops, tablets, smartphones, teletype terminals, and even test harnesses. In many cases the host may have custom software installed on it that communicates with the device. When “host” must be used differently, it is qualified as something specific, such as “acquirer host” or “USB host.”

Similarly, the word “user” is used in different ways in different contexts. This document separates users into more descriptive categories:

• The cardholder

• The operator (such as a cashier, bank teller, customer service representative, or server)

• The developer or the administrator (such as an integrator configuring the device for the first time)

Because some connection types, payment brands, and other vocabulary name spaces (notably Bluetooth® LE, EMV, smart phones, and more recent versions of Windows) use very specific meanings for the term “Application,” this document favors the term host software to refer to software on the host that provides a user interface for the operator.

The combination of device(s), host(s), host software, device firmware, device configuration settings, physical mounting and environment, user experience, and documentation is referred to as the solution.

The host uses this command to generate a key pair to be used for a certificate signing request (CSR). The key pair generated will be 256 bit elliptic-curve (EC) keys. The key pair generated will be saved to non-volatile memory in the device and will overwrite any existing CSR key pair. The key pair will persist in non-volatile memory associated with a CSR until it is either overwritten or until a leaf certificate is loaded into the device with Command 0xD811 - Start Send File to Device (Secured) that contains a public key that matches the key pair at which point the key pair will be associated with that certificate instead of a CSR.

The sequence of events is as follows:

Example (Hex):

The host uses UI Page Option 0x01 to display a page with a title, a maximum of 6 data buttons (2 rows and 3 columns in Landscape Screen Orientation, 3 rows and 2 columns in Portrait Screen Orientation) with text, and maximum 3 functional buttons with a color option of red, green, or yellow.

The host uses UI Page Option 0x01 to display a page with a title, maximum of 4 data buttons (2 rows and 2 columns in Landscape Screen Orientation, 2 rows and 2 columns in Portrait Screen Orientation) with text, and maximum 3 functional buttons with a color option of red, green, or yellow.

The host uses UI Page Option 0x02 to display a page with a title, maximum of 6 data buttons (2 rows and 3 columns in Landscape Screen Orientation, 3 rows and 2 columns in Portrait Screen Orientation) with $Amount, and maximum 3 functional buttons with a color option of red, green, or yellow.

The host uses UI Page Option 0x02 to display a page with a title, maximum of 4 data buttons (2 rows and 2 columns in Landscape Screen Orientation, 2 rows and 2 columns in Portrait Screen Orientation) with $Amount, and maximum 3 functional buttons with a color option of red, green, or yellow.

The button with **$**Amount value is host provided. The title, data buttons text, and functional buttons are labeled with String IDs associated with configured String messages. See . When the user presses any button, the device sends a notification to the host to indicate the corresponding button is pressed. See

EMV ARPC Data

Miniature Certificate Type

The host uses this command to start a buzzer for playing a sequence of tones. Each sequence can have a minimum of 1 to maximum of 10 tones.

The host uses this command to request that the device display a message for the cardholder.

The sequence of events is as follows:

The host uses this command to provide the device with additional/modified data to resume a transaction that is currently paused.

The host uses this command to generate a certificate signing request (CSR) in PEM format. The CSR generated will be saved to volatile memory in the device and will overwrite any existing CSR. The CSR will persist in volatile memory until it is overwritten, fetched with Command 0xD821 - Start Get File from Device or the device is power cycled or reset.

The sequence of events is as follows:

The host uses this command to request challenge data from the device, which the host can then use to perform a specific sensitive operation / modify a specific type of device setting. Information about how the host should pass the required challenge data to the device is included in the documentation for all commands that use this security mechanism.

The sequence of events is as follows:

The host can load this file type to control the behavior of the device’s EMV contact and contactless kernels when the device should support Offline Data Authentication (ODA). Populate all values from information provided by each payment brand that should be supported by the device. The host can load this file using 0xD812 - Start Send File to Device (Unsecured).

MagTek provides tools that allow these settings to be loaded using a Microsoft Excel spreadsheet in xlsx format for more convenient authoring, review, and change tracking. For a reference sample spreadsheet, contact MagTek Support Services. The MagTek tools expect the spreadsheet to be formatted as shown in the table below. Each CA Key to be supported is defined in a tab of the Excel file.

EMV Configuration CA Keys File Type

The MagTek tool converts the spreadsheet data into the format shown in CA Keys Raw Format.

The host uses this command to request the deletion of a file stored on the device.

The sequence of events is as follows:

Card Emulation Overview

Card emulation enables a DynaFlex/DynaProx device to simulate a Type 4 smart card. The emulated card has the following characteristics:

• Compliance: Card emulation conforms to ISO/IEC 14443 Type-A and NFC Forum Type 4 standards.

• Passive Operation: The emulated card functions in passive mode. The phone is responsible for generating the magnetic field required to activate the simulated card.

• Read-Only: The emulated card is read-only and does not support writing.

• Supported Data Type: Supports the URI (URL) data type.

• iPhone Support: NFC card reading was introduced on Apple iPhones starting with the iPhone 7.

• Android Support: Android added NFC support in 2012; however, compatibility depends on the specific phone model and hardware capabilities. Most Android phones released since 2016 support NFC. Verify with the phone’s manufacturer to confirm compatibility.

Google Pay Indicator: If a phone supports Google Pay, it is likely capable of reading NFC tags.

The host uses this command to prompt a cardholder for customer information.

TLV data objects 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.

• N = Numeric.

• T = TLV Constructed data object (TLV Value contains additional layers of TLV-encoded data the parser should continue to process).