1 of 31

Universal SDK Documentation

The Universal SDK is MagTek's cross-platform SDK for building against MMS (DynaFamily) readers. It wraps the MMS command set in native calls for each platform — handling connection, sending commands, and receiving responses and notifications — so you work in your language instead of composing raw messages. Choose your platform below; the command each call maps to is documented in the API & Command Reference.

In This Section

Reference Section

Information Available

.NET (Windows)

Build against MMS readers from .NET — libraries and APIs for connecting to a device, sending commands, and handling responses and notifications on Windows and other .NET hosts.

.NET (Windows)

Universal SDK Documentation (.NET/Windows)

The .NET edition of the MagTek Universal SDK (MTUSDK), giving developers a single managed interface for connecting to and controlling MagTek card readers and PIN pad devices — including the DynaFlex family — from Windows .NET applications. The complete API reference is available as a PDF download below.

In This Section

Reference Section

Information Available

MagTek Universal SDK for Windows .NET applications — downloadable PDF reference.

Need More Help

Need Help?

For additional support, please contact MagTek Support:

Technical Support:

📧 Email:

Java

The Java edition of the MagTek Universal SDK (MTUSDK), giving developers a single interface for connecting to and controlling MagTek card readers and PIN pad devices — including the DynaFlex family — from Java host applications. The complete API reference is available as a PDF download below.

iOS

The iOS edition of the MagTek Universal SDK (MTUSDK), giving developers a single interface for connecting to and controlling MagTek card readers and PIN pad devices — including the DynaFlex family — from native iOS apps. The complete API reference is available as a PDF download below.

Linux

Universal SDK Documentation (Linux)

The Linux edition of the MagTek Universal SDK (MTUSDK), giving developers a single interface for connecting to and controlling MagTek card readers and PIN pad devices — including the DynaFlex family — from Linux host applications. The complete API reference is available as a PDF download below.

In This Section

Reference Section

Information Available

MagTek Universal SDK for Linux applications — downloadable PDF reference.

Need More Help

Need Help?

For additional support, please contact MagTek Support:

Technical Support:

📧 Email:

Android

Universal SDK Documentation (Android)

The Android edition of the MagTek Universal SDK (MTUSDK), which brings MagTek SCRA and PIN Pad SCRA devices — including the DynaFlex family — into a single AAR library for Android apps. Use the sections below to set up the SDK, connect to and control a device through the Core API, subscribe to device events, and look up classes, enumerations, and reference appendices.

In This Section

Reference Section

Information Available

Overview of the SDK and the MagTek devices it supports, with system requirements and how to install the certificate chain for connecting to a DynaFlex II PED over WLAN.

Introduction

This document provides instructions for software developers who want to create Android software solutions that include MagTek devices connected to an Android based host. MagTek Universal SDK (MTUSDK) incorporates MagTek SCRA and MagTek PIN Pad SCRA devices into one SDK. This document is part of a larger library of documents designed to assist MagTek device implementers, which includes the following documents available from MagTek:

D998200383 DynaFlex Products Programmer's Manual ( Commands )

The sample code provides Android demonstration source code and a reusable MTUSDK API library that provides developers of custom software solutions with an easy-to-use interface for MagTek devices.

Developers can distribute the MTUSDK API Library to customers or distribute internally as part of an enterprise solution.

How to Set Up the SDK

To set up the MagTek Universal SDK library for Android, download the 1000007352 MagTek Universal SDK for MMS Devices (Android) available from MagTek.com.

To add the MT Universal libraries to a custom software project in Android Studio, follow these steps:

Launch Android Studio.
Copy the following AAR file to the libs subfolder of your software project:

IDeviceCapabilities

Create an instance of the IDeviceCapabilities using IDevice.getCapabilities(). Then use the functions described in this chapter.

BatteryBackedClock

This property returns true if the device is equipped with a battery that preserves the internal clock when not powered by a host system or charging.

Copy

boolean IDeviceCapabilities.BatteryBackedClock();

Return Value:

Returns true if device is equipped with a battery backed clock. Otherwise, returns false.

Display

This property returns true if the device is equipped with display.

Copy

Return Value:

Returns true if device is equipped with a display. Otherwise, returns false.

This property returns true if the device has the option to disable or enable the magnetic stripe reader head (MSR). The MSR may be powered down while the device is idle to minimize power consumption.

Copy

Return Value:

Returns true if device supports MSR power saver. Otherwise, returns false.

This property returns an enumerate list of payment methods supported by the device.

Copy

Return Value:

Returns a list of PaymentMethod.

This property returns true if the device is equipped with a PIN Pad.

Copy

Return Value:

Returns true if device is equipped with a PIN Pad. Otherwise, returns false.

This property returns true if the device is equipped with signature capture.

Copy

Return Value:

Returns true if device is equipped with signature capture. Otherwise, returns false.

This property returns true if the device supports Secure Reading and Exchange of Data.

Copy

Return Value:

Returns true if device supports SRED. Otherwise, returns false.

ConnectionInfo

Create an instance of the ConnectionInfo using IDevice.getConnectionInfo(). Then use the function calls described in this chapter.

This function returns address of the device.

Return Value:

Returns the address of the device.

This function returns the type of connection Interface for the device.

Return Value:

DeviceInfo

Create an instance of the DeviceInfo from IDevice.getDeviceInfo(). Then use the function calls described in this chapter.

getModel

This function returns the model name of the device.

String DeviceInfo.getModel();

Return Value:

Returns the model name of the device.

getName

This function returns the name of the device.

String DeviceInfo.getName();

Return Value:

Returns the name of the device.

For the complete documentation index, see . This page is also available as .

Classes

Reference for the individual classes in the MagTek Universal SDK — the data objects used to configure commands and read structured results back from the device. Entries are listed alphabetically across two pages, Classes A–I and Classes N–Z.

In This Section

Reference Section

Information Available

Alphabetical reference for the SDK's data and result classes (Classes A–I).

IEventSubscriber Delegates

MTUSDKNET API will invoke the callback function in this chapter to provide the requested data and/or a detailed response. To delegate the event, call the subscribeAll function with the name of a class that implements the IEventSubscriber Delegates interface.

OnEvent

OnEvent handles all event types. The eventType parameter defines which event is triggered.

public void OnEvent( 
    EventType eventType, 
    IData data);

Parameter

Description

eventType

Return Value: None

Example

In this example, the main window implements IEventSubscriber. The keyword this is used to pass in the name of the current class MainWindow.

Classes can be initialized by passing in the data byte array.

Example

IConfigurationCallback Delegates

MTUSDKNET API will invoke the callback function in this chapter to provide the requested data and/or a detailed response. These events will be called in a class that implements the IConfigurationCallback Delegates interface.

This event is called when certain asynchronous IDeviceConfiguration operations need to be have a MAC included with the request.

Copy

Parameter

Description

IMQTTDeviceStatusCallback Delegates

This interface invokes callback functions to receive data and/or a detailed response. To register for the event(s), call the setMQTTDeviceStatusMonitoring() function with the name of a class that implements the IMQTTDeviceStatusCallback interface.

This event is called when a device is connected to the MQTT broker.

Parameter

Description

ISystemStatusCallback Delegates

This interface invokes callback functions to receive data and/or a detailed response. To register for the event(s), call the setSystemStatusCallback() function with the name of a class that implements the ISystemStatusCallback interface.

This event is called when an error occurs with the connection with the MQTT broker.

Prototype

Parameters

Parameter

Enumerations

Reference for the enumerated types used throughout the MagTek Universal SDK — the named constants for values such as device and transaction states, card types, and command options that appear in SDK calls and results. The enumerations are listed alphabetically across two pages.

In This Section

Reference Section

Information Available

Reference for the SDK's enumerated types (device and transaction states, card types, option flags).

Appendix D - Apple VAS

These instructions are for preparing Apple VAS (value-added service) transactions.

Merchant ID and URL Slots

Set the Apple VAS Merchant ID and URL property for each slot 1 to 6 using IDeviceControl --> setConfigInfo().

POS Capabilities

Set the POS capabilities property using IDeviceControl à setConfigInfo().

Start Transaction

Set the PaymentMethods to include PaymentMethod.AppleVAS.
Set AppleVASMode to: VASMode.Single, VASMode.Dual, or VASMode.VASOnly.
Set AppleVASProtocol to: VASProtocol.Full or VASProtocol.URL.

Data from an Apple VAS (9F27 and 9F2A) is returned in separate Apple VAS slot containers.
FE — var — VAS Data Container

Appendix E - Google Wallet Smart Tap VAS

These instructions are for preparing Google Wallet Smart Tap VAS (value-added service) transactions.

Configure the mobile device for Google Wallet Smart Tap Pass.

Load the LTPK protection key (Long Term Private Key) into the MagTek device.

IDeviceConfiguration

Create an instance of the IDeviceConfiguration using getDeviceConfiguration(). Then use the function calls described in this chapter.

Generally, these functions will run in one of two modes:

Asynchronous functions return data in the event handlers in section.
Synchronous functions return data in the return value. If the data is not available immediately, the call will block until a wait time has elapsed.

deleteFile

This function deletes a file from the device.

Copy

Parameter

fileID Byte array for the file ID. For DynaFlex, use a 4-byte file id. 0x02000000 = Custom idle page image 1
0x02000001 = Custom idle page image 2 0x02000002 = Custom idle page image 3 0x02000003 = Custom idle page image 4

Return Value:

Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.

This function retrieves a challenge token from the device. A challenge token consists of a random nonce or timestamp. A challenge token must be used within the time allowed by the device (generally 5 minutes) of being issued. Only one token can be active at a time. Attempts to use a token for requests other than the one specified will cause the token to be revoked/erased.

Copy

Parameter

data Byte array containing the request ID to be protected.

Return Value:

Returns a byte array containing the challenge token.

This function retrieves device configuration information.

Copy

Parameter

configType Type of configuration. For DynaFlex, this is the function ID.
data Configuration data to be sent to the device. For DynaFlex, this is the OID.

Return Value:

Returns an array of bytes containing the configuration information.

This function retrieves device specific information.

Copy

Parameter

infoType Enumerated information type.

Return Value:

Returns a string value device information.

This function retrieves device specific information.

Copy

Parameter

fileID Byte array for the file ID. For DynaFlex, use a 4-byte file id.
callback Name of a class or structure that implements the IConfigurationCallback Delegates events.

Return Value:

Returns a string value device information.

This function retrieves key information.

Copy

Parameter

keyType Type of key. For DynaFlex, use 0.
data Key data to be sent to the device. For DynaFlex, this is the 2-byte key slot number.

Return Value:

Returns an array of bytes containing the key information.

This function sends a file to the device.

Copy

Parameter

fileID Byte array for the file ID. For DynaFlex, use a 4-byte file id.
data File contents to be sent to the device.
callback Name of a class or structure that implements the IConfigurationCallback Delegates events.

Return Value:

Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.

This function sends an image to the device.

Copy

Parameter

imageID Value for the image ID. For DynaFlex, use:
1, 2, 3, or 4
data File contents to be sent to the device.
Images must be BMP format, 160KB or smaller with no compression, maximum 320px by 240px, with color depth 16 color, 256 color, 16-bit color, 24-bit color. Images smaller than the maximum size are centered on the display. Note images at full screen size must be 16-bit color or lower to meet the size requirement.
For details see

Return Value:

Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.

This function sends a file to the device using a secure command structure.

Copy

Parameter

fileID Byte array for the file ID. For DynaFlex, use a 4-byte file id.
data File contents to be sent to the device.
callback Name of a class or structure that implements the IConfigurationCallback Delegates events.

Return Value:

Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.

This function sets device configuration information.

Copy

Parameter

configType Type of configuration. For DynaFlex, this is the function ID.
data Configuration data to be sent to the device.
callback Name of a class or structure that implements the IConfigurationCallback Delegates events.

Return Value:

Returns 0 if the asynchronous configuration operation started. Otherwise, returns a non 0 value.

This function sets which image is to be displayed when the device is idle.

Copy

Parameter

imageID Value for the image ID. For DynaFlex, use:
0, 1, 2, 3, or 4
Where 0 substitutes the “Welcome” screen.

Return Value:

Returns 0 if the asynchronous configuration operation started. Otherwise, returns a non 0 value.

This function updates the device firmware.

Copy

Parameter

firmwareType Type of firmware. For DynaFlex, use:
1 - Main App
data Firmware image to be sent to the device.
callback Name of a class or structure that implements the IConfigurationCallback Delegates events.

Return Value:

Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.

This function updates key information in the device.

Copy

Parameter

keyType Type of key.
data Key data to be sent to the device.
callback Name of a class or structure that implements the IConfigurationCallback Delegates events.

Return Value:

Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value.

CoreAPI

Use the CoreAPI to create an IDevice. IDevice is the bases for the MagTek Universal SDK.

If accessing a device specific API outside of MagTek Universal SDK, use the various functions in this section to create an instance of that device’s API. Once a device specific API is referenced, the associated library will need to be added into the application’s development project.

createCMSDevice

This function creates an instance of a CMS type of device.

The API’s of MagTek Universal SDK do not apply. See D998200160 MagTek Common Message Structure (MTCMS) for the MTCMS API.

MTDevice CoreAPI.createCMSDevice(Context context, Handler handler);

Parameter

context — An instance of android.content.Context to allow SDK access to application-specific resources.
handler — An instance of android.os.Handler to allow SDK access to application-specific message queues.

Return Value:

Returns an MTDevice.

This function creates an instance of IDevice. All API’s of MagTek Universal SDK can but utilized from IDevice.

Parameter

context — An instance of android.content.Context to allow SDK access to application-specific resources.
deviceType — Enumerated device type.
connectionType

Return Value:

Returns an IDevice.

This function creates an instance of an MMS type of device, DynaFlex Family.

Parameter

context — An instance of android.content.Context to allow SDK access to application-specific resources.
deviceAdapter — Callback interface for MMS device messages.

Return Value:

Returns an MMXDevice.

This function creates an instance of an MTPPSCRA type of device.

The API’s of MagTek Universal SDK do not apply. See D998200078 IPAD, DynaPro, DynaPro Go, and DynaPro Mini PIN Encryption Devices Programmer’s Reference for the MTPPSCRA API.

Parameter

context — An instance of android.content.Context to allow SDK access to application-specific resources.
handler — An instance of android.os.Handler to allow SDK access to application-specific message queues.

Return Value:

Returns an MTPPSCRA.

This function creates an instance of a MTSCRA type of device.

The API’s of MagTek Universal SDK do not apply. See D99875723 uDynamo, Dynamag, DynaMAX, eDynamo, mDynamo, Insert, DynaWave, iDynamo 6 for the MTSCRA API.

Parameter

context — An instance of android.content.Context to allow SDK access to application-specific resources.
handler — An instance of android.os.Handler to allow SDK access to application-specific message queues.

Return Value:

Returns an MTSCRA.

This function returns a list of IDevice. IDevice is the base for utilizing the MagTek Universal SDK interface.

Parameter

context — An instance of android.content.Context to allow SDK access to application-specific resources.
deviceType — An enum for the type of MagTek readers which the SDK will control.
deviceTypes

Return Value:

Returns a list of IDevice

This function returns the API version.

Return Value:

Returns an integer representing the API version.

This function sets the MQTT (Message Queuing Telemetry Transport) broker information. Call prior to device discovery.

Parameter

uri — URI included the port. Support URIs:
1. TCP: test.mosquitto.org, test.mosquitto.org:1883, mqtt://test.mosquitto.org:1883, mqtt://broker.emqx.io:1883

Return Value: None

This function sets the MQTT client ID to establish a connection.

Parameter

clientID — Client ID. If not set, the default value is [HostName]-[RandomUUID]

Return Value: None

This function sets the MQTT certificate information.

Parameter

certificateInfo — If client certificate is required when initiating a connection to the MQTT broker, this shall be used to establish the connection. If not set, the default value is NULL.

Return Value: None

This function sets the MQTTDeviceDiscoveryTimeout value.

Parameter

timeout — Time out in milliseconds. Default value = 5000 if not set. A call to getDeviceList() does not return the list until this time has expired.

Return Value: None

This function sets the MQTT callback interface instance.

After connecting to the MQTT broker, the MQTT Device Status Monitoring subscribes to

"<MQTTSubscribeTopic>/#" . The wildcard "/#" is automatically appended.

Example:

When a device status updates to “connected” or “disconnected”, OnConnected() and OnDisconnected() are invoked respectively.

This method can be called whether or not there is an active connection to an MQTT device.

Devices reporting with "/Status/connected" are added to the device list as follows:

Parameter

callback — Name of a class or structure that implements the IMQTTDeviceStatusCallback interface events. Call after calling getDeviceList().

Return Value: None

This function sets the base value for MQTTPublishTopic. When connected to the MQTT broker, the composed topic is in the format:

Example:

Base topic = “MagTek/Device/DynaFlexIIPED/”
Full topic = “MagTek/Device/DynaFlexIIPED/B51E72D/MMSMessage”

Parameter

topic — Base topic for which to publish messages. Full topic is composed by the SDK.

Return Value: None

This function sets the MQTTQoS value.

Parameter

qos — The quality of service level for publishing messages. Range:
- 0 = At most once (default)
- 1 = At least once

Return Value: None

This function sets the base value for MQTTSubscribeTopic. When connected to the device, the composed topic is in the format:

“<basetopic>/<DeviceID>/MMSMessage”.

Example:

Base topic = “MagTek/Server/DynaFlexIIPED/”
Full topic = “MagTek/Server/DynaFlexIIPED/B51E72D/MMSMessage”

Parameter

topic — Base topic for which to subscribe for messages.

Return Value: None

This function stops the MQTT device status monitoring process. If called when already running, the process shall be stopped immediately. This method can be called whether or not there is an active connection to an MQTT device.

Return Value: None

This function sets the SystemStatusCallback global value.

Parameter

callback — Name of a class or structure that implements the ISystemStatusCallback interface event. Call before starting any MQTT communication. When there is an error, the interface’s OnError() event is invoked.

Return Value: None

Appendix C - EMV Transaction Flow

This section demonstrates transaction flow.

Flow Chart - QuickChip

Sample Code - QuickChip

The following breaks out the EMV flow chart into code. When enabling QuickChip mode, host does not send the ARPC to the device to complete the transaction. Events are shown separately and in the order received.

// Assign parameters.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>(); 
paymentMethod.Add(PaymentMethod.MSR); 
paymentMethod.Add(PaymentMethod.Contact); 
paymentMethod.Add(PaymentMethod.Contactless);

Transaction transaction = new Transaction(); 
transaction.setAmount(“1.00”); 
transaction.setCashBack(“0.00”); 
transaction.setEMVOnly(true); 
transaction.setPaymentMethods(paymentMethod); 
transaction.setQuickChip(true); // QuickChip mode enabled.

// Start transaction.
boolean result = device.startTransaction(transaction);

public void OnEvent(EventType eventType, IData data)
{
    String message 
    switch (eventType);
        {
            case EventType.DisplayMessage:
                // Get the message.
                message = data.StringValue();
    }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            case EventType.InputRequest:
            // Get the message.
            message = data.StringValue();

            // display/retrieve user selection.

            // set status and selection result.
            IData selectionData = new BaseData(new Byte[] {status, selection});
            device.sendSelection(selectionData);
    }
}

public void OnEvent(EventType eventType, IData data)
{
byte[] ARQC = null; 
switch (eventType);
    {
        case EventType.AuthorizationRequest:
            // Forward ARQC to processor.
            /* data[0..1] – ARQC length
                data[2..n] – remainder contains the ARQC TLV object */
    }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
        
            case EventType.TransactionResult:
                /* data[0]	– Signature Required 
                    data[1..2] – Batch Data length
                    data[3..n] – remainder contains the Batch Data TLV object
                */

                // Parse the TLV from data[].
                // Abstract Approval status from TLV tag “DFDF1A”.
                // Abstract Signature Required status from TLV tag data[0].
        }
}

Flow Chart – Signature Capture

Sample Code – Signature Capture

The following breaks out the EMV flow chart into code. Events are shown separately and in the order received.

// Assign parameters.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>(); 
paymentMethod.Add(PaymentMethod.MSR); 
paymentMethod.Add(PaymentMethod.Contact); 
paymentMethod.Add(PaymentMethod.Contactless);

Transaction transaction = new Transaction(); 
transaction.setAmount(“1.00”); 
transaction.setCashBack(“0.00”); 
transaction.setEMVOnly(true); 
transaction.setPaymentMethods(paymentMethod); 
transaction.setQuickChip(true);

// Start transaction.
boolean result = device.startTransaction(transaction);

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            case EventType.DisplayMessage:

                // Get the message.
                message = data.StringValue();
    }
}

public void OnEvent(EventType eventType, IData data)
{
    byte[] ARQC = null; 
    switch (eventType);
        {
            case EventType.AuthorizationRequest:
                // #4a
                // Forward ARQC to processor.
                /* data[0..1] – ARQC length
                    data[2..n] – remainder contains the ARQC TLV object */
        }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            case EventType.DisplayMessage:
                // Display approval message. 
                message = data.StringValue();

                // A data size of 0 is an instruction to clear the display. 
                if (data.StringValue().Length == 0)
                {
                    // Clear the UI display.
                }
        }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            case EventType.TransactionResult:
                /* data[0]	– Signature Required 
                data[1..2] – Batch Data length
                data[3..n] – remainder contains the Batch Data TLV object
                */

                // Parse the TLV from data[].
                // Abstract Approval status from TLV tag “DFDF1A”.
                // Abstract Signature Required status from TLV tag data[0].
        }
}

public void OnEvent(EventType eventType, IData data)
{
    String signature; 
    switch (eventType);
        {
            case EventType.Signature: 
                signature = data.StringValue();
        }
}

Flow Chart – With ARPC

Sample Code – With ARPC

The following breaks out the EMV flow chart into code. When disabling QuickChip mode, host must send the ARPC to the device to complete the transaction. Events are shown separately and in the order received.

// Assign parameters.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>(); 
paymentMethod.Add(PaymentMethod.MSR); 
paymentMethod.Add(PaymentMethod.Contact); 
paymentMethod.Add(PaymentMethod.Contactless);

Transaction transaction = new Transaction(); 
transaction.setAmount(“1.00”); 
transaction.setCashBack(“0.00”); 
transaction.setEMVOnly(true); 
transaction.setPaymentMethods(paymentMethod); 
transaction.setQuickChip(false); //QuickChip mode disabled.

// Start transaction.
boolean result = device.startTransaction(transaction);

public void OnEvent(EventType eventType, IData data)
{
    string message; 
    switch (eventType);
        {
            case EventType.DisplayMessage:

                // Get the message.
                message = data.StringValue;
    }
}

public void OnEvent(EventType eventType, IData data)
{
    string message; 
    switch (eventType);
        {
            case EventType.InputRequest:
                // Get the message.
                message = data.StringValue;

                // display/retrieve user selection.

                // set status and selection result.
                IData selectionData = new BaseData(new Byte[] {status, selection});
device.sendSelection(selectionData);
    }
}

public void OnEvent(EventType eventType, IData data)
{
    byte[] ARQC = null; 
    switch (eventType);
        {
            case EventType.AuthorizationRequest:
                // Forward the ARQC to the processor.
                /* data[0..1] – ARQC length
                data[2..n] – remainder contains the ARQC TLV object */

                ARQC.ByteArray = data.ByteArray;
                // App function to send the request to the processor. 
                ARPC = sendARQCToProcessorForApproval(ARQC.ByteArray());

        }
}

After the ARPC is returned from the processor, it is constructed into a TLV container and then sent to the device. The ARPC for approved (00) is set in ASCII 3030.

The optional tags 91, 71, and 72 (Issuer Authentication Data, Issuer Script Template 1, and Issuer Script Template 2) are not included in this example.

See the construction of the ARPCTLV in the table below.

ARPC TLV object for sendAuthorization().

Tag

Len

Value / Description

Typ

Req

Default

The use case for an MSR fallback is when communication with the chip results in a terminated transaction and the TransactionStatus is reported as MSRFallback.

The host application will re-attempt the transaction. To invoke this use case, here are the following pre-requisites.

Pre-requisites:

Device already configured for Device-Driven Fallback = Disabled.
A card to cause the fallback. Example but not limited to a card with no applications programmed or a card with an application not configured on the device.

Scheme:

-->Host begins an initial transaction with PaymentMethod set to MSR+Chip+Contactless.
<--Device responds with fail and with status of MSRFallback.
-->Host displays a message to use magstripe.

Begin initial transaction:

Continue with Fallback transaction:

By default, devices with a display signal the end of a transaction by returning to the idle page and showing “WELCOME.” This parameter directs the device to show a message based on the Message ID from the command displayMessage(). This option completely overrides the device’s idle page behavior until the next transaction, power cycle, or other similar state change. Example but not limited to: 0x00 - reserved, do not use. 0x01 - “AMOUNT” 0x02 - “AMOUNT OK?” 0x03 - “APPROVED” 0x04 - “CALL YOUR BANK” 0x05 - “CANCEL OR ENTER” 0x06 - “CARD ERROR” 0x07 - “DECLINED” 0x08 - “ENTER AMOUNT” 0x09 - reserved, do not use. 0x0A - reserved, do not use. 0x0B - “INSERT CARD” 0x0C – “NOT ACCEPTED” 0x0D - reserved, do not use. 0x0E - “PLEASE WAIT” 0x0F - “PROCESSING ERROR” 0x10 - “REMOVE CARD” 0x11 - “USE CHIP READER” 0x12 - “USE MAGSTRIPE” 0x13 - “TRY AGAIN” 0x14 - “WELCOME” 0x15 - “PRESENT CARD” 0x16 - “PROCESSING” 0x17 - “CARD READ OK - REMOVE CARD” 0x18 - “INSERT OR SWIPE CARD” 0x19 - “PRESENT ONE CARD ONLY” 0x1A - “APPROVED PLEASE SIGN” 0x1B - “AUTHORIZING PLEASE WAIT” 0x1C - “INSERT, SWIPE OR TRY ANOTHER CARD” 0x1D - “PLEASE INSERT CARD” 0x1E - Null prompt (empty screen) 0x1F - reserved, do not use. 0x20 - “SEE PHONE” 0x21 - “PRESENT CARD AGAIN” 0x22 - “INSERT/SWIPE/TRY OTHER CARD” 0x23 - “TAP or SWIPE CARD” 0x24 - “TAP or INSERT CARD” 0x25 - “TAP, INSERT or SWIPE CARD” 0x26 - “TAP CARD” 0x27 - “TIMEOUT” 0x28 - “TRANSACTION TERMINATED”

IDeviceControl

Create an instance of the IDeviceControl using IDevice.getDeviceControl(). Then use the function calls described in this chapter.

Generally, these functions will run in one of two modes:

Asynchronous functions return data in the event handlers in section
Synchronous functions return data in the return value. If the data is not available immediately, the call will block until a wait time has elapsed.

close

This function closes the connection to the device.

Return Value:

Returns true if successful. Otherwise, returns false.

This function resets the device. This is equivalent to a power reset. After the reset, connection to the device will need to be re-established.

Return Value:

Returns true if successful. Otherwise, returns false.

This function displays a message on the device’s screen.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function clears session data and returns the device to an idle state.

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a request for user input to the device. The response data will be returned in the event

OnEvent.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function opens a connection to the device.

Return Value:

Returns true if successful. Otherwise, returns false.

This function instructs the device to play a tone.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a command to the device. The response will be passed to the event OnEvent.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends an extended command to the device. The response will be passed to the event

OnEvent

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a raw APDU command from the host application to the NFC target while the device is operating in NFC Pass-Through mode. For NFC Type A or Type B using ISO 14443-4 Protocol.

Used for applications that require direct APDU-level communication, such as mDL, secure element transactions, or custom NFC protocols.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a synchronous command to the device. The response from the device will be returned in IResult.

Parameter

Description

Return Value:

Returns IResult.

This function sets the date and time for the device.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function send a 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.

Parameter

Description

false – unlock the latch in the device.
true – lock the latch in the device.

Return Value:

Returns true if successful. Otherwise, returns false.

This function controls the status of the device’s LED indicators (Light Emitting Diode) to provide visual feedback NFC operation states. Applicable after entering NFC Pass-Through mode. The status is reset after exiting NFC Pass-Through mode.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function commands the device to enter NFC Pass-Through Mode. This enables the host application to directly exchange APDU commands and responses with an NFC card or mobile device.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function configures the NFC reader polling behavior used to detect nearby NFC targets such as cards, mobile devices, or mDL wallets. Applicable after entering the Pass-Through mode.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a command to show a barcode on the device’s display.

Parameter

Description

Parameter

Type

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a command to immediately show an image on the device’s display.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a command to immediately show an image on the device’s display.

Parameter

Description

Member

Type/ Format

Description

Images must be BMP format, 160KB or smaller with no compression, maximum 320px by 240px, with color depth 16 color, 256 color, 16-bit color, or 24-bit color. Images smaller than the maximum size are centered on the display. Note images at full screen size must be 16-bit color or lower to meet the size requirement.

For details see D998200383 DynaFlex Family Programmer’s Manual (Commands).

Return Value:

Returns true if successful. Otherwise, returns false.

This function displays custom User Interface (UI) pages on devices that support a screen. It holds parameters for all UI page options of Text Lines, Text Buttons, Amount Buttons, and Image. Only one UI page option may be in effect at one time based on the option parameter. See the other subset functions for invoking a specific UI page.

When the UI page is active, the device waits for further action. The device notifies the host when a Button is pressed. Text Buttons and Functional Buttons report as the button number. Amount Buttons report the $ amount in BCD format. A press on a Text line does not produce a report.

Parameter

Description

0x00 = Up to 5 lines of text + 1 functional button Middle.

0x01 = Title + up to 6 text buttons + up to 3 functional buttons.

0x02 = Title + up to 6 $Amount buttons + up to 3 functional buttons.

0x03 = Title + custom image + 1 functional button Right.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function shows the Amount UI page.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function shows the Image UI page.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function shows the Text buttons UI page.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function shows the Text lines UI page.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a command to start the barcode reader.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a command to start card emulation.

Compliance: Conforms to ISO/IEC 14443 Type-A and NFC Forum Type 4 standards.
Passive Operation mode: The NFC reader must generate the field to activate the simulated card.
Read-Only: The emulated card is read-only and does not support writing.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a command to prompt a cardholder for customer information. Captured information is later returned in OnEvent() EventType.TouchscreenPersonalInfoEntry.

Parameter

Description

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a command to stop the barcode reader. This is applicable only when the timeout value for startBarCodeReader() was set to 0x00.

Return Value:

Returns true if successful. Otherwise, returns false.

This function sends a command to stop card emulation.

Return Value:

Returns true if successful. Otherwise, returns false.

This function stops the Personal Info Entry process. If called during info entry, the process will be canceled immediately.

Return Value:

Returns true if successful. Otherwise, returns false.

Universal SDK Documentation

In This Section

.NET (Windows)

Universal SDK Documentation (.NET/Windows)

In This Section

Need More Help

Java

iOS

Linux

Universal SDK Documentation (Linux)

In This Section

Need More Help

Android

Universal SDK Documentation (Android)

In This Section

Introduction

How to Set Up the SDK

IDeviceCapabilities

BatteryBackedClock

Display

ConnectionInfo

DeviceInfo

getModel

getName

Classes

Classes

In This Section

IEventSubscriber Delegates

OnEvent

IConfigurationCallback Delegates

IMQTTDeviceStatusCallback Delegates

ISystemStatusCallback Delegates

Enumerations

Enumerations

In This Section

Appendix D - Apple VAS

Merchant ID and URL Slots

POS Capabilities

Start Transaction

Appendix E - Google Wallet Smart Tap VAS

.NET (Windows)

Universal SDK Documentation (.NET/Windows)

In This Section

Need More Help

DeviceInfo

getModel

getName

Java

IMQTTDeviceStatusCallback Delegates

How to Set Up the SDK

ConnectionInfo

iOS

ISystemStatusCallback Delegates

OnError

OnConnected

OnDisconnected

getAddress

getConnectionType

getDeviceType

Universal SDK Documentation (Java)

In This Section

Need More Help

Universal SDK Documentation (iOS)

In This Section

Need More Help

Linux

Universal SDK Documentation (Linux)

In This Section

Need More Help

Enumerations

Enumerations

In This Section

Android

Universal SDK Documentation (Android)

In This Section

IEventSubscriber Delegates

OnEvent

IDeviceCapabilities

BatteryBackedClock

Display