Command 0x05::0x01 - Read PAN

The host uses this command to retrieve the Primary Account Number (PAN) of the last card it successfully read, regardless of the interface used to read the card. Generally the host would use this command in solutions that use an external Encrypting PIN Pad (EPP), to retrieve the PAN and provide it to the EPP so it can create a PIN block.

For the host to successfully retrieve the plaintext PAN using this command, the device must have determined the card matched one or more entries in the device’s PAN Whitelist (see Command 0x03::0x80 - Read PAN Whitelist / Account Data Whitelist). If the card does not match an entry in the whitelist, the PAN will be available in encrypted form, but only if oDynamo is currently paired with a Cryptera EPP. The EPP decrypts the PAN and uses it to form the encrypted PIN block. Otherwise the device returns 0x0000 in parameter C4 to indicate the PAN is not available.

After successful return of the PAN to the host or a timeout, the device erases the PAN from memory. For MSR transactions, the timeout for the host to follow up with the device to retrieve the PAN is 3 seconds. Because EMV transactions may require more time for the cardholder and operator to complete, the timeout for EMV transactions is 255 seconds. If a timeout occurred, the device returns 0x0000 in parameter C4 to indicate the requested item is not available.

Table - Message Structure for Command 0x05::0x01 - Read PAN

Command 0x04::0x09 - Read MSR Data

The host uses this command to arm the device’s MSR to read magnetic stripe data after the device reports an EMV transaction using a chip card has failed. The command is intended to be used to implement fallback when Command 0x07::0x80 - EMV L2 Transaction Status or Notification 0x07::0x8A - EMV L2 Transaction Status report statuses EMV Error - Card Blocked or Empty Candidate List. If the host wishes to fall back to reading MSR data upon receiving those status reports, it must invoke this command while the card is still inserted, and the device will read the magnetic stripe when the cardholder removes the card from the slot, then send its response to the host to return the requested data.

Although this command is intended to be used after EMV transaction failure, if the host calls it outside the context of an EMV transaction, the command will function the same: The MSR reader will continue to be armed, and the device will return MSR card data in the response upon card removal.

Table - Message Structure for Command 0x04::0x09 - Read MSR Data

Notification 0x04::0x11 - MSR Card Data Available

When a cardholder swipes a magnetic stripe card, the device sends this notification to inform the host that card data is available. After receiving this notification, the host should call Command 0x04::0x12 - Request MSR Card Data to get the data.

Command 0x04::0x12 - Request MSR Card Data

The host uses this command to request MSR data after receiving Notification 0x04::0x11 - MSR Card Data Available.

Command 0x02::0x0A - EPP Pairing Certificate Exchange

This command starts the EPP pairing process on oDynamo using the results from the START_EXCHANGE command on the Encrypting PIN Pad (EPP). The host should use the oDynamo response as the parameters for the next EPP command GENERATE_KEK. For details about the pairing flow, see Appendix G How to Pair With a Cryptera Encrypting PIN Pad.

Table - Message Structure for Command 0x02::0x0A - EPP Pairing Certificate Exchange

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x02::0x0B - Get Challenge

This command directs the device to send challenge data to the host, 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.

Upon providing the challenge to the host, the device sets an internal 5-minute countdown timer. When the time limit expires, the device will no longer accept the challenge. This binding of the command to a specific time period allows the device to detect and reject commands that have been captured/intercepted at one point in time and replayed later.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x02::0x0C - EPP Pairing Load KEK

This command is the second step in the EPP pairing process after Command 0x02::0x0A - EPP Pairing Certificate Exchange has completed successfully. This step loads a temporary key from the EPP that will be used during the third step of pairing (Command 0x02::0x0D - EPP Pairing Load Derivation Key). For details about the pairing flow, see Appendix G How to Pair With a Cryptera Encrypting PIN Pad.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x02::0x0D - EPP Pairing Load Derivation Key

This command is used for the third and final step of the EPP pairing process. It securely loads a key shared with the paired EPP. This key is used to derive keys that protect the PIN and PAN sent to/from the EPP.. For details about the pairing flow, see Appendix G How to Pair With a Cryptera Encrypting PIN Pad.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x02::0x0E - Get Key / Certificate Information

The host uses this command to get key or certificate information from the device.

If an error occurs, the device terminates the command and reports the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3).

If no error occurs, the device responds by immediately sending two or more instances of Notification 0x01::0x10 - Big Block Device Data, which the host should concatenate, then interpret as follows:

Command 0x02::0x58 - Request Device Certificates

The host uses this command to request the Device Certificate, which the host would generally pass to Magensa web services that generate signed byte sequences for remote configuration commands.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

The host should then wait (up to 90 seconds in some cases) for the device to respond synchronously with the requested data.

This section documents the full set of messages that can be exchanged between the device and the host.

Command 0x00:0x10 - Get Product ID

The host uses this command to get the device’s product ID.

Table 4-1 - Message Structure for Command 0x00:0x10 - Get Product ID

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x00::0x12 - Get Capability String

The host uses this command to get the device’s Capability String.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x00::0x13 - Get Manufacturer

The host uses this command to get the device manufacturer.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x00::0x14 - Get Product Name

The host uses this command to get the device’s product name.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x00::0x15 - Get Secure Tracking Number

The host uses this command to get the device’s secure tracking number.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x00::0x16 - Get Firmware Version

The host uses this command to get the device’s firmware version.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x00::0x18 - Get Network Information (Ethernet Only)

The host uses this command to get information about the device’s network connection.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x00::0x23 - Get Boot Loader Version

The host uses this command to get the device’s boot loader version.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x00::0x27 - Get CT-L2 Version

The host uses this command to get the device’s EMV L2 version, if any.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x00::0x28 - Get Serial Number

The host uses this command to get the device’s serial number.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x01::0x02 - Clear Transaction Data

The host uses this command to direct the device to clear all transaction data, including account data, encrypted PIN block, PAN, and amount, and return to the idle state.

The host uses commands in this application to get and set the configuration of the device. Every configuration setting has a command to get the setting and a command to change the setting. When using get commands, the host should not include Data Field Data Object (Tag C4 or E0). The device responds with the current configuration values in Data Field Data Object (Tag C4 or E0).

Command 0x03::0x00 - Card Latch Control

The host uses this command to lock or unlock the card latch. The host can choose to lock the card during EMV transactions to limit the possibility of the cardholder prematurely removing the card. The lock can also be enabled while the card is out of the system to block cardholders from inserting a card.

Table - Message Structure for Command 0x03::0x00 - Card Latch Control

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x03::0x60 - Set/Get Ethernet Configuration (Ethernet Only)

The host uses this command and its subcommands to set and get configuration settings for the device’s Ethernet connection.

To change the device’s Ethernet configuration, the host should follow these steps:

• Call the command with the Set Ethernet IP Address Mode subcommand to select DHCP or Static.

• If using Static, call the command with each Set subcommand for all remaining settings. If the host selected DHCP, the device ignores the remaining settings and further Set calls are unnecessary.

• Call the command again with the Apply Changes subcommand. The device will begin using the new configuration immediately, and the settings will persist through subsequent power cycles and restarts.

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x03::0x70 - Set Chip Card Support

The host uses this command to enable or disable support for chip cards. When disabled, the device will ignore chip cards and will only read magnetic stripe cards. When enabled, the device checks whether an inserted card has an EMV chip, and will try to communicate with the chip and notify the host first, before falling back to reading the magnetic stripe. This changes the value of tag DFDFDF12 in the device configuration (see Command 0x03::0x72 - Get Device Configuration).

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Command 0x03::0x72 - Get Device Configuration

The host uses this command to get the device’s configuration. If the host uses the Data Field Data Object (Tag C4 or E0) to specify a single configuration setting to retrieve, the device returns that setting in the format shown in Table 4-59. If the host omits the Data Field Data Object (Tag C4 or E0), the device returns a list of all configuration values as shown in Table 4-60.

Command 0x03::0x80 - Read PAN Whitelist / Account Data Whitelist

The host uses this command to read the device’s PAN Whitelist or Account Data Whitelist, which are loaded securely by the manufacturer and allow the device to relax security for cards that match the criteria specified in the lists.

The first 6 digits of a card’s Primary Account Number (PAN) are called the Issuer Identification Number (IIN), previously known as bank identification number (BIN). The IIN identifies the institution that issued the card to the cardholder. Before the device transmits certain types of card data to the host, it compares the card’s IIN to the rules stored in the two whitelist tables, and changes the data it sends accordingly:

• The device’s PAN Whitelist affects the behavior of Command 0x05::0x01 - Read PAN. This whitelist is specifically designed to support solutions that use an external Encrypting PIN Pad (EPP), where the host would typically need an unencrypted PAN to create an encrypted PIN block.

• The device’s Account Data Whitelist affects the behavior of MSR transactions in Notification 0x04::0x11 - MSR Card Data Available, Command 0x04::0x12 - Request MSR Card Data, and the corresponding Data Object F4 - Magnetic Stripe Reader Card Data.

• The device’s Account Data Whitelist affects the behavior of EMV transactions in Notification 0x07::0x83 - EMV L2 ARQC Message, Notification 0x07::0x84 - EMV L2 Transaction Result, and the corresponding Transaction Result Message - Batch Data Format (EMV Only).

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

About EMV L2 Transaction Flows

The general flow of an EMV L2 transaction is as follows (bear in mind the device does not have a display, so in these steps the host drives the user interface for both the terminal operator / cashier and for the cardholder / customer):

• The terminal operator / cashier performs steps external to the transaction, generally resulting in a total balance owed, and directs the host software to initiate a transaction. If the device supports Quick Chip and the system is designed to use that feature, the host may skip this step and instead start the transaction with a default amount as a placeholder, which is generally a pre-determined non-zero value that is consistent with the system’s payment processing environment. Further differences pertaining to Quick Chip transactions are included in the steps below.

• The device must have already used Command 0x01::0x50 - Subscribe to Notifications to subscribe to at least notifications from Application Group 0x01 - General Messages, Application Group 0x04 - Magnetic Stripe Reader (MSR) Messages, and Application Group 0x07 - EMV L2 Contact Messages (Chip Card L2 Mode Only).

• The cardholder inserts their card into the device. In response, the device sends Notification 0x01::0x40 - Card Detected / Identified / Removed to report Card was not present and is now present / Card is a chip card (ICC card) indicating there is a chip card ready to begin a transaction.

• The host software may optionally call Command 0x03::0x00 - Card Latch Control to hold the card in the slot.

• The host software sends the device Command 0x07::0x00 - EMV L2 Start Transaction.

• From this point until the host sends the transaction results to the transaction processor, the host may cancel the EMV transaction by sending Command 0x07::0x04 - EMV L2 Cancel Transaction and the device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Host Canceled Transaction / Transaction error.

• The device attempts to communicate with a chip on the inserted card.

  • If the device is unable to power up the card:

    • The device responds with error code 0013 and terminates the transaction.
• At this point the device was able to power-up the card and found mutually supported applications. The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Selecting the application.

• The device sends Notification 0x07::0x81 - EMV L2 Display Message Request with the message Please Wait.

• The device negotiates with the card to determine which payment applications are available. If the card holds only one mutually supported payment application and the host did not enable Enhanced App Selection in the Transaction Options parameter, the device uses that application. Otherwise:

  • The device sends Notification 0x07::0x82 - EMV L2 User Selection Request to prompt the cardholder to Select Application with a list of available applications, followed by Notification 0x07::0x8A - EMV L2 Transaction Status to report Waiting for User Response / Waiting for User Application Selection.

  • After the cardholder selects an application, the host passes the selection to the device by sending Command 0x07::0x02 - EMV L2 User Selection Result.

• The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Initiating Application.

• If the card’s selected application reports to the device that the cardholder should select a language, the device sends Notification 0x07::0x82 - EMV L2 User Selection Request to prompt the cardholder to Select Language with a list of available languages, followed by Notification 0x07::0x8A - EMV L2 Transaction Status to report event Waiting for User Response / Waiting for user language selection. After the cardholder selects a language, the host passes the selection to the device by sending Command 0x07::0x02 - EMV L2 User Selection Result.

• The device continues communicating with the card and sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Reading Application Data. If an error or other type of failure occurs during this step, the device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Terminated / Transaction Error, followed by Notification 0x07::0x81 - EMV L2 Display Message Request with the message Transaction Terminated, followed by Notification 0x07::0x84 - EMV L2 Transaction Result.

• If the host used the Transaction Options parameter to specify either Continue Mode Enabled, Wait or Continue Mode Enabled, Continue when it called Command 0x07::0x00 - EMV L2 Start Transaction, the device sends Notification 0x07::0x8C - EMV L2 Continue Notification with data from the card application read in the previous step. If the host specified Continue Mode Enabled, Wait, the device pauses the transaction and sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Waiting for User Response / Waiting for Continue. The host must send Command 0x07::0x13 - EMV L2 Continue Action to direct the device to proceed or cancel before the 60 seconds timeout occurs, otherwise the device terminates the transaction.

• Depending on the capabilities of the card and the device, the device authenticates the card data using SDA, DDA, or CDA. The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Offline data authentication.

• The steps from here through Card Action Analysis below are collectively referred to as the Risk Management process:

  • The device checks to make sure the selected application is valid for the transaction, and is compatible with the device (such as application version number, application usage control, and application effective / expiration date), and sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Process Restrictions.

  • The device uses the cardholder verification related data in the card to determine which cardholder verification method (CVMs) to use. The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Cardholder Verification.
• The device performs terminal risk management procedures, which involves floor limit checking, velocity checking, and periodically forcing online authorization to protect against fraud, and sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Terminal Risk Management.

• The device analyzes the results of the previous steps and sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Terminal Action Analysis.

• The device rolls up the results of the previous Risk Management process:

  • If the Risk Management process encounters an error or determines the transaction or payment method fails to meet required criteria, the device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Terminated / Transaction Error, followed by Notification 0x07::0x81 - EMV L2 Display Message Request with the message TRANSACTION TERMINATED , followed by Notification 0x07::0x84 - EMV L2 Transaction Result, and terminates the transaction.

  • If the Risk Management process determines the transaction is too risky to approve, the device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Terminated / Transaction Error, followed by Notification 0x07::0x84 - EMV L2 Transaction Result, followed by Notification 0x07::0x81 - EMV L2 Display Message Request with message Declined to notify the cardholder, and terminates the transaction.

• The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Generating First Application Cryptogram, followed by Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Card Action Analysis.

• If the device is NOT configured as Online-Only Terminal Type [see Tag 9F35 in EMV Contact Terminal Settings and Defaults] and the Risk Management processes determined the transaction is OK to perform offline, the device reports the transaction result to the host as follows:

  • The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Transaction Complete.

  • The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Terminated and either Transaction Approved or Transaction Declined, then sends Notification 0x07::0x81 - EMV L2 Display Message Request with message Approved or Declined to notify the cardholder.
• If the device is configured as an Online Only Terminal Type [see Tag 9F35 in EMV Contact Terminal Settings and Defaults] or the Risk Management processes determined the transaction must be performed online, the device reports the transaction result to the host as follows:

  • The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Online Processing, followed by Notification 0x07::0x83 - EMV L2 ARQC Message.

  • The next event depends on whether the device supports the Contact Quick Chip feature and whether the host specified Quick Chip as an Option when it started the transaction:
• If Quick Chip operation is NOT supported or is not in effect:

  • The device sends Notification 0x07::0x8A - EMV L2 Transaction Status to report Transaction Progress Change / Waiting for Online Processing Response.

  • The host processes the ARQC Message data and uses it to coordinate with the transaction processor to receive an ARPC Response, which it processes and sends to the device using Command 0x07::0x03 - EMV L2 Online Processing Result / Acquirer Response. Alternatively, the host may implement host-driven Quick Chip by instead constructing its own preliminary ARPC Response with tag 8A set to ‘Z3’ and sending it to the device immediately, without waiting for a transaction processor response. The device responds by sending Notification 0x07::0x81 - EMV L2 Display Message Request to the host with message Declined and ending the transaction. The host should suppress this message and take over the remainder of the transaction, including notifying the cardholder to remove the card, determining the final transaction amount, coordinating with the transaction processor to retrieve a final transaction result, and interacting with the cardholder.