To set up the MagTek Universal SDK library, download and install the MTUSDK available from MagTek.com.

To build out demo code, follow these steps:

1. Locate and copy the framework files to your project folder. iOS files is under folder ios-arm64 of the SDK package.

1. Click your project and select “General”. In the section “Frameworks, Libraries, and Embedded Content”, click “+”.

1. Pick the framework files - “MTUSDK.xcframework” and “MTSCRA.xcframework” (MTSCRA is referenced in MTUSDK).

1. Validate that the framework is embedded in your project.

1. Add code and build.

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.

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 .

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

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

MTUniversal API will invoke the callback function in this chapter to provide the requested data and/or a detailed response. To delegate the event, implements the MTUSDKDelegate interface.

onDeviceList

Handles BLE Service and EA Service events. Use this to find a BLE device or EA accessory.

(void) onDeviceList: (id) instance
withConnectionType: (MTU_ConnectionType) connectionType 
        deviceList: (NSArray<IDevice *> *) deviceList;

Return Value: None

Handles update of host system state.

Return Value: None

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

Create an instance of the DeviceInformation from Idevice.getDeviceInfo. Then use the function calls described in this chapter.

deviceModel

This property returns the model name of the device.

NSString* deviceModel;

Return Value:

Returns the model name of the device.

deviceName

This property returns the name of the device.

NSString* deviceName;

Return Value:

Returns the name of the device.

deviceSerial

This property returns the serial number of the device.

NSString* deviceSerial;

Return Value:

Returns the serial number of the device.

initWithName

This function initializes an instance of DeviceInfo.

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

  • FF01

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

configType

This property is for the configuration type.

Byte configType;

Return Value:

• 0x01 = Device Settings

• 0x02 = Device Information

OidAndValue

This property is for the Object ID and value.

NSData* OidAndValue;

Return Value:

The OID and value.

This function is for reading and setting the device OID properties.

Return Value:

OID property value.

Create an instance of the DeviceCapability, then use the properties described in this chapter.

AutoSignatureCapture

This property returns true if the device is capable of automatically capturing a signature during a transaction.

BOOL AutoSignatureCapture;

Return Value:

Returns true if device is capable of automatically capturing a signature. Otherwise, returns false.

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.

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.

BOOL Display;

Return Value:

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

MSRPowerSaver

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.

Return Value:

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

This property returns a bit masked option of payment methods supported by the device.

Return Value:

Returns a bit masked option of MTU_PaymentMethod.

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

Return Value:

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

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

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.

Return Value:

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

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:

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.

• Device refers to the MagTek devices that receives and responds to command set.

This interface invokes a callback function to receive data and/or a detailed response. To use, a class must implements the IConfigurationCallback Delegates interface.

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

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.

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.

This document provides instructions for software developers who want to create iOS software solutions that include MagTek devices connected to an iOS 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.

The following are absolute prerequisites:

· DynaFlex Family Programmer’s Manual

About the MagTek Sample Code

The sample code provides Swift demonstration source code and a reusable MTUSDK library that provides developers of custom software solutions with an easy-to-use interface for MagTek devices. Developers can distribute the MTUSDK library to customers or distribute internally as part of an enterprise solution.

Nomenclature

• Device refers to the MagTek devices that receives and responds to command set.

• Host refers to the piece of general-purpose electronic equipment the device is connected or paired to, which sends data to and receives data from the device. Host types include but not limited to PC and Mac computers, tablets, and smartphones. When “host” must be used differently, it is qualified as something specific, such as “USB host.”

• User in this document generally refers to the cardholder.

Tested operating systems:

• iOS 13 and above.

• Xcode 14 and above.

When connecting to the DynaFlex II PED device by WebSocket, a client certificate and its certificate chain must be installed on the iOS device.

The Root Certificate, Sub CA Certificate, and Client private key Certificate as referenced in document DynaFlex TLS Certificate Installation Manual. The client private key certificate (e.g. filename client.p12) must be accessible to the custom software that makes a secure WebSocket connection to the DynaFlex II PED.

After creating the certificates and transferring them in the iOS device, load the certificate chain into the iOS device by follow these steps. The certificate names shown here are for reference only.

1. Delete the previously installed certificates prior to beginning this procedure. If the certificate chain is current, skip this installation section. View the certificates by going to Settings à General à VPN & Device Management.

1. Copy the certificate chain to the iOS device. Touch the Root certificate DF-2-1_RootCA.pem to download to iOS device.

1. Go to Settings > General >VPN & Device Management > Select Root DF2-1

1. Select Install.

1. Enter Passcode.

1. Press Install twice.

1. Repeat the same steps above for the SubCA certificate Amce_SubCA.pem and for the Client certificate Client.p12. For Client, iOS will ask for an additional certificate password, enter the password used during the creation of the Client certificate when prompted, and then press Next.

1. Enable Certificates by going to Settings à About à Certificate Trust Settings

1. When building the custom app, the Client certificate must be loaded into the data member of CertificateInfo during the call to createDevice(). See below as an example to access the client certificate.

The following instructions are for Bluetooth pairing the DynaFlex II Go.

1. Place the device into Pairing Mode by pressing and holding the power button on device until 4 beeps and release the button. The 4th LED will blink green.

1. When in pairing mode and the first time connecting to device, the host will prompt for a pairing request. Enter the pairing code. The default code is "000000".

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.

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

boolean IDeviceCapabilities.Display();

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.

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.

OnCalculateMAC

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

Copy

IResult OnCalculateMAC( 
    byte macType, 
    byte[] data);

Return Value:

Returns an IResult that contains the calculated MAC.

This event is called to update the host on the progress of an asynchronous IDeviceConfiguration operation.

public void OnProgres(int progress);

Return Value: None

This event is called to update the host when an asynchronous IDeviceConfiguration operation is completed.

Copy

Return Value: None

Example:

Copy

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

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

In This Section

Appendices

Blurb goes here.

In This Section

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.

Create an instance of the ConnectionInfo, then use the function calls described in this chapter.

getAddress

This function returns the address of the device.

(NSString*) getAddress;

Return Value:

Returns the address of the device.

getConnectionType

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

(MTU_ConnectionType) getConnectionType;

Return Value:

Returns the MTU_ConnectionType

getDeviceType

This function returns the type for the device.

(MTU_DeviceType) getDeviceType;

Return Value:

Returns the MTU_DeviceType.

getCertificateInfo

This function returns the type for the device.

(CertificateInfo*) getCertificateInfo;

Return Value:

Returns the CertificateInfo*. CertificateInfo:

This function initializes an instance of ConnectionInfo.

Return Value:

Returns an IDevice*.

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

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

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

The MagTek Universal SDK for iOS gives iPhone and iPad apps one Objective-C/Swift interface to MagTek card readers and PIN pads, across SCRA, PIN pad (PPSCRA), and MMS-class devices such as the DynaFlex family. You find or create a device through CoreAPI, drive transactions and PIN, PAN, and signature requests through IDevice, control the display, barcode reader, and NFC through IDeviceControl, and receive card data, transaction status, and ARQC authorization requests through delegate callbacks. Supported transports include External Accessory (iAP2) for DynaFlex II Go, and WebSocket, secure WebSocket, and MQTT for DynaFlex II PED. This section is the API reference for those classes, delegates, data types, and enumerations, with appendices that walk through API usage and the EMV transaction flow.

CoreAPI

Use the CoreAPI to create an IDevice. IDevice, which 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);

Return Value:

Returns an MTDevice

createDevice

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

IDevice CoreAPI.createDevice( 
    DeviceType deviceType, 
    ConnectionType connectionType, 
    string address,
    string model, 
    string name, 
    string serial,
    CertificateInfo certificateInfo = null);

Parameter

Return Value:

Returns an IDevice.

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

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.

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 uDynamo, Dynamag, DynaMAX, eDynamo, mDynamo, Insert, DynaWave, iDynamo 6 for the MTSCRA API.

Return Value:

Returns an MTSCRA.

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

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.

Return Value: None

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

Return Value: None

This function sets the MQTT certificate information.

Parameter

Return Value: None

This function sets the MQTTDeviceDiscoveryTimeout value.

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.

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”

Return Value: None

This function sets the MQTTQoS value.

Parameter

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

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

Return Value: None

MTUniversal 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 interface.

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

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

Need More Help

These classes are equipped with helper classes named Builders. Builders can parse the raw data byte array of an OnEvent() into a format required by a builder’s class.

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

BarCodeData

These constructors initialize a BarCodeData object. Use BarCodeDataBuilder.GetBarCodeData with data from the BarCodeData event to return a BarcodeData.

BarCodeData BarCodeDataBuilder.GetBarCodeData( 
    DeviceType deviceType, 
    byte[] dataBytes 
    );
    
new BarCodeData(byte[] Data, boolean Encrypted); 
new BarCodeData(
    byte[] Data, 
    boolean Encrypted,
    byte EncryptionType, 
    byte[] KSN
    );

Return Value: Returns an instance of BarCodeData.

CertificateInfo is used for the connection to a device requiring client credentials. See the following for details on installing a certificate chain: D998200550 DynaFlex II PED Using Wireless LAN Guide.

This constructor initialize a CertificateInfo object. Once created, it is to be passed to CoreAPI.createDevice().

Return Value: Returns an instance of Certificate Info. Example of using CertificateInfo.

This class returns the connection state of the device when supplied the data object of the OnEvent() ConnectionState event.

Return Value: Returns an instance of ConnectionStateBuilder.

DirectoryEntry is similar to an InputRequest for Application during a transaction. Other fields of information are included besides Application Label. During a transaction, the device selects the PPSE. The directory entries are the PPSE response starting from the BF0C tag. The number of directory entries correspond to the number of applications on the card.

These constructors initialize a DirectoryEntry object.

Return Value: Returns an instance of DirectoryEntry.

This supplies a directory entry list for application selection after a card has been presented to the device during a transaction. To be implemented, Application Selection Behavior property 1.2.1.1.1.2 must be set to 0x03 – Enhanced Prompt Cardholder.

The data byte array from the EnhancedInputRequest event is parsed and returned as an enhanced application selection list (directory entry). This list is the PPSE response starting from tag BF0C. EnhancedInputRequest class extends InputRequest.

IData is used for the payload of events and passing data to functions. When assigning the member StringValue, the member ByteArray is automatically assigned. Same is true vice versa. In this way either a string or an array can be accessed without need of data conversion.

Use the BaseData() function to assign an instance of IData.

Example of using IData.

This is used for displaying messages prompted by the card during a transaction. The data byte array from the InputRequest event is parsed and returned as an application selection list.

Return Value: Returns an instance of InputRequest.

This is the interface used as the parameter for startTransaction(). For an example, see the sample code in IDevice Walk Through.

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.
var transaction: ITransaction = ITransaction( 
Amount:“1.00”,
CashBack:“0.00”, 
TransactionType:0, 
Timeout:30,
For:MTU_PaymentMethod_MSR | MTU_PaymentMethod_Contact | 
MTU_PaymentMethod_Contactless,
QuickChip:true)

// Start transaction.
var result: BOOL = device.startTransaction(transaction)

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
        var message: NSString = “” 
        switch eventType
                {
                        case MTU_EventType_DisplayMessage:
                        // Get the message. 
                        message = data.StringValue
                }
}

 func onEvent(_ eventType: MTU_EventType, data: IData!)
{
    var message: NSString = “” 
    switch eventType
        {
            case MTU_EventType_InputRequest:
                // Get the message. 
                message = data.StringValue
                
                // display/retrieve user selection.

                // set status and selection result.
                var statusSelection: NSString* = "0001"
                var selectionData: IData = IData.dataWithHex(statusSelection); 
                device.sendSelection(selectionData)
        }
}

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
    var ARQC[]: Byte = nil; switch eventType
        {
            case MTU_EventType_AuthorizationRequest:
                // Forward ARQC to processor.
                /* data[0..1] – ARQC length
                data[2..n] – remainder contains the ARQC TLV object */
        }
}

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
        var message: NSString = “” 
        switch eventType
                {
                        case MTU_EventType_DisplayMessage:
                                // Display approval message. 
                                message = data.StringValue
                        // A data size of 0 is an instruction to clear the display. 
                        if (data.StringValue.count == 0)
                        {
                                // Clear the UI display.
                        }
                }
}

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
    switch eventType
        (
            case MTU_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.
var transaction: ITransaction = ITransaction( 
Amount: "1.00",
CashBack: "0.00", 
TransactionType:0, 
Timeout:30,
For:MTU_PaymentMethod_MSR | MTU_PaymentMethod_Contact | 
MTU_PaymentMethod_Contactless,
QuickChip:true
)

// Start transaction.
var result: BOOL = device.startTransaction(transaction)

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
    var message: NSString = "" 
    switch eventType
        {
            case MTU_EventType_DisplayMessage:
            // Get the message. 
            message = data.StringValue
    }
}

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
    var message: NSString = "" 
    switch eventType
        {
            case MTU_EventType_InputRequest:
        // Get the message. 
        message = data.StringValue

        // display/retrieve user selection.

        // set status and selection result.
        var statusSelection: NSString* = "0001"
        IData* selectionData = IData dataWithHex(statusSelection);             
        device.sendSelection(selectionData);
    }
}

 func onEvent(_ eventType: MTU_EventType, data: IData!)
{
var ARQC[]: Byte = nil; switch eventType
  {
      case MTU_EventType_AuthorizationRequest:
          // Forward ARQC to processor.
          /* data[0..1] – ARQC length
          data[2..n] – remainder contains the ARQC TLV object */
    }
}

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
    var message: NSString = "" 
    switch eventType
        {
            case MTU_EventType_DisplayMessage:
            // Display approval message. 
            message = data.StringValue;
            
            // A data size of 0 is an instruction to clear the display. 
            if (data.StringValue.count == 0)
        {
            // Clear the UI display.
        }
    }
}

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
        switch eventType
        {
                case MTU_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].
        }
}

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
    var signature: NSString = “”;
    switch eventType
        {
            case MTU_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.
var transaction: ITransaction = ITransaction( 
Amount:“1.00”,
CashBack:“0.00”, 
TransactionType:0, 
Timeout:30,
For:MTU_PaymentMethod_MSR | MTU_PaymentMethod_Contact | 
MTU_PaymentMethod_Contactless,
QuickChip:false
);

// Start transaction.
var result: BOOL = device.startTransaction(transaction)

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
    var message: NSString = "" 
    switch eventType
        {
            case MTU_EventType_DisplayMessage:
                // Get the message. 
                message = data.StringValue
    }
}

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
        var message: NSString = ""; 
        switch eventType
                {
                        case MTU_EventType_InputRequest:
                                // Get the message. 
                                message = data.StringValue
                                
                                // display/retrieve user selection.

                                // set status and selection result. 
                                var statusSelection: NSString = "0001" 
                                var selectionData: IData* = IData
dataWithHex(statusSelection); 
                                device.sendSelection(selectionData)
        }
}

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
    var ARQC: IData = data; 
    switch eventType        
        {
            case MTU_EventType_AuthorizationRequest:
                // Forward ARQC to processor.
                /* data[0..1] – ARQC length
                data[2..n] – remainder contains the ARQC TLV object */ 
                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.

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 magnetic stripe.

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

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.