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

Need More Help

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

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

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.

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

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

Return Value:

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

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

Copy

Return Value:

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

This function returns the model name of the device.

Return Value:

Returns the model name of the device.

This function returns the name of the device.

Return Value:

Returns the name of the device.

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

Universal SDK Documentation (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.

In This Section

Need More Help

Universal SDK Documentation (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.

In This Section

Need More Help

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: MTUSDK.aar

• Ensure your project settings are set up correctly.

• Clean, build, and run your custom software project to make sure the library imported correctly.

• In your custom software, create an instance of MTUSDK. For examples, see the source code included with the MagTek Universal Demo project and/or the Code Examples section in this document.

• Depending on the connection types supported, the project should include the uses-features and uses-permissions as specified in the table below in its AndroidManifest.xml file. For examples, see the AndroidManifest.xml included with the MagTek Universal Demo project.

To Run/Debug the sample code, follow these steps:

• In Android Studio, select File -> Open ...

• Select MTUSDKDemo project, click OK.

• Select Run -> Run app to run the sample code or select Run -> Debug app

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

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

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

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.

OnConnected

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

void OnConnected(String deviceAddress);

Return Value: None

This event is called when a device is disconnected from the MQTT broker.

Return Value: None

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.

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.

Supplementary reference material for the MagTek Universal SDK, including the full status-code list, a step-by-step API walk-through, the EMV transaction flow, and integration guidance for mobile-wallet value-added services (Apple VAS and Google Wallet Smart Tap).

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.

• Upload a Public Key to the Google Pay & Wallet Console for the issuer account associate with the Google Wallet Pass.

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

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

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

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

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.

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

getAddress

This function returns address of the device.

String ConnectionInfo.getAddress();

Return Value:

Returns the address of the device.

getConnectionType

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

ConnectionType ConnectionInfo.getConnectionType();

Return Value:

Returns the ConnectionType.

getDeviceType

This function returns the type for the device.

DeviceType ConnectionInfo.getDeviceType();

Return Value:

Returns the DeviceFeature.

This enum refers to a featured supported by the device.

NFCData

These constructors initialize an NFCData object. Use NFCDataBuilder.GetNFCData with the data byte array from the NFCData event to return an NFCData.

NFCData NFCDataBuilder.GetNFCData(deviceType, byte[] dataBytes); 
new NFCData(byte[] Data, boolean Encrypted); 
new NFCData(
    byte[] Data, 
    boolean Encrypted,
    byte EncryptionType, 
    byte[] KSN
    );

Return Value:

Returns an instance of NFCData.

These constructors initialize an NFCRAPDUData object. Use NFCDataBuilder.GetNFCRAPDUData with data byte array from the NFCRAPDUResponse event to return an NFCRAPDUData.

Return Value:

Returns an instance of NFCRAPDUData.

This class assist in parsing NFCEvent data.

These constructors initialize a PersonalInfoEntry object.

• Call startPersonalInfoEntry().

• At OnEvent():TouchscreenPersonalInfoEntry, build the object.

Return Value:

Returns an instance of PersonalInfoEntry.

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

int IDeviceConfiguration.deleteFile(byte[] fileID);

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 D998200383 DynaFlex Family Programmer's Manual (Commands).

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.

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 — Enumerated connection type.

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 — An enum list for the type of MagTek readers which the SDK will control.

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

  • 2 = Exactly 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

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

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.

• -->Host starts a transaction with PaymentMethod set to MSR.

Begin initial transaction:

Continue with Fallback transaction:

CoreAPI Walk Trough

The following walks through how to create instances of devices.

• CoreAPI.createDevice à IDevice

• CoreAPI.getDeviceList à List

• CoreAPI.createPPSCRA à MTPPSCRA

These examples demonstrate methods for creating an IDevice to be used in the MagTek Universal SDK. This also shows how to establish a device specific API, which is not used with the MagTek Universal SDK.

Here, a single IDevice is established.

Here, a list of IDevice is established. The first device is accessed at index 0.

The following walks through how to make use of IDevice.

• Implement device events within the class to receive events.

• CoreAPI à IDevice.

• IDevice à subscribeAll().

• IDevice à other functions.

Example

Application Main window may extent the

These constructors initialize a PersonalInfoEntry object.

• Call startPersonalInfoEntry().

• At OnEvent():TouchscreenPersonalInfoEntry, build the object.

Return Value:

Returns an instance of PersonalInfoEntry.

IEventSubscriber Delegates or can be extended by a separate class. This example uses a separate class and demonstrates how to parse for the various event types.

Example

Various events are separately shown below

The following walks through how to make use of IDeviceControl.

• IDevice --> IDeviceControl.· IDeviceControl à open().

• IDeviceControl --> other functions.

• IDeviceControl --> close().

Example

The following walks through how to make use of ConnectionInfo.

• IDevice --> ConnectionInfo.

• ConnectionInfo --> getAddress()

• ConnectionInfo --> getConnectionType()

• ConnectionInfo --> getDeviceType() Example

Example

The following walks through how to make use of IDeviceCapabilities.

• IDevice à IDeviceCapabilities.

• IDeviceCapabilities à BatteryBackedClock() to check if date/time should be set.

• IDeviceCapabilities à PaymentMethods() to check card types supported.

• IDeviceCapabilities à other functions.

The following walks through how to make use of IDeviceConfiguration.

• IDevice --> getDeviceConfiguration().

• IDeviceConfiguration --> updateFirmware().

• IDeviceConfiguration --> getConfiguration().

• IDeviceConfiguration --> setConfiguration().

Example

Application Main window may extent the IConfigurationCallback Delegates or can be extended by a separate class. This example uses a separate class and demonstrates how to parse for the various events.

Example

BarCodeFormat

This enum refers to the type of barcodes to display.

This enum refers to the type of barcodes to display.

This enum refers to the type of customer information to capture.

This enum refers to the readiness of the SDK to communicate with the device. This is not the physical attachment to a host system.

This enum refers to the communication interface type of MagTek reader which the SDK will control.

This enum is reserved for future use.

This enum refers to a change in the device status.

This enum refers to a featured supported by the device.

This enum refers to the type of MagTek reader which the SDK will control.

This enum refers to the type of connection error.

This enum refers to the type of event triggered by the device.

This function cancels a transaction. A transaction can only be cancelled before a card is presented.

Return Value: Returns true if cancelled. Otherwise, returns false.

This function retrieves the capabilities of the device.

Return Value: Returns IDeviceCapabilities

This function retrieves the connection information of the device.

Return Value: Returns ConnectionInfo

This function retrieves the connection state of the device.

Return Value: Returns CaptureType