1. Manuals
  2. Brands
  3. Magtek Manuals
  4. Card Reader
  5. Universal SDK
  6. Programmer's manual

Magtek Universal SDK Programmer's Manual

Hide thumbs
Table of Contents

Advertisement

Quick Links

Download this manual
MagTek Universal SDK
For MMS Devices
Programmer's Manual ( Java )
September 2021
Manual Part Number:
D998200385-10
REGISTERED TO ISO 9001:2015
MagTek I 1710 Apollo Court I Seal Beach, CA 90740 I Phone: (562) 546-6400 I Technical Support: (888) 624-8350
www.magtek.com

Advertisement

Table of Contents
loading

Related Manuals for Magtek Universal SDK

Summary of Contents for Magtek Universal SDK

  • Page 1 MagTek Universal SDK For MMS Devices Programmer’s Manual ( Java ) September 2021 Manual Part Number: D998200385-10 REGISTERED TO ISO 9001:2015 MagTek I 1710 Apollo Court I Seal Beach, CA 90740 I Phone: (562) 546-6400 I Technical Support: (888) 624-8350 www.magtek.com...
  • Page 2 No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of MagTek, Inc. MagTek® is a registered trademark of MagTek, Inc.
  • Page 3 ATTENTION: CUSTOMER SUPPORT. TERMS, CONDITIONS, AND RESTRICTIONS MagTek, Incorporated (the "Licensor") owns and has the right to distribute the described software and documentation, collectively referred to as the "Software." LICENSE: Licensor grants you (the "Licensee") the right to use the Software in conjunction with MagTek products.
  • Page 4 Agreement and will not affect the enforceability of any of the remaining provisions. This Agreement shall be governed by the laws of the State of California and shall inure to the benefit of MagTek, Incorporated, its successors or assigns.

  • Page 5: Table Of Contents

    System Requirements ........................8 How to Set Up the MagTek Universal Project ..................9 How to Download and Set Up the MagTek Universal Java Project ........... 9 How to Set Up the Java Library With the JRE/JVM ..............9 How to Modify Manifest ........................9 How to Sign JAR ..........................
  • Page 6 ..........................33 setConfigInfo ........................... 33 9.10 setDisplayImage ......................... 34 9.11 updateFirmware ......................... 34 9.12 updateKeyInfo ..........................35 IEventSubscriber Delegates ......................36 10.1 OnEvent ............................36 MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 6...
  • Page 7 B.6.1 Handling Events ........................54 Appendix C EMV Transaction Flow ......................55 Flow Chart ............................55 Sample Flow Code ......................... 56 MSR Fallback Flow ......................... 62 MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 7...

  • Page 8: Introduction

    This document provides instructions for software developers who want to create Java software solutions that include MagTek devices connected to a Windows based host. This document is part of a larger library of documents designed to assist MagTek device implementers, which includes the following documents available from MagTek: ...

  • Page 9: How To Set Up The Magtek Universal Project

    2) Download and install the latest version of the Java Runtime Environment (JRE) and Java Development Kit (JDK). 3) Follow the steps in section 2.1 How to Download and Set Up the MagTek Universal Java Project to download and install the latest MagTek Universal Windows SDK. You may download and install it directly on the target workstation where it will be used, or you may opt to install it on a master development workstation and copy the dependencies to the target workstation manually.

  • Page 10: How To Sign Jar

    7) Sign your applet by using jarsigner to sign the JAR file, using the private key you saved in your keystore: jarsigner C:\mtusdk.jar MyCert 8) Verify the output of your signed JAR file by entering the following command: jarsigner -verify -verbose -certs C:\mtusdk.jar MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 10...

  • Page 11: How To Set Up The Sdk In Eclipse

    2) In Eclipse, click File  New  Java Project 3) Type the project name 4) In the library tab, click Add external jar, then point to the Lib folder of the root folder of MagTek Universal SDK for Java to add the MTUSDK.jar.

  • Page 12: 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.

  • Page 13: Getconnectiontypes

    Returns a string for a connection type. GetConnectionTypeFromString This function returns an enumerated connection type from a string. ConnectionType CoreAPI.GetConnectionTypeFromString(String connectionType); Parameter Description connectionType Enumerated connections type. Return Value: Returns a ConnectionType. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 13...

  • Page 14: Idevice

    This function retrieves the device control interface to the device. IDeviceControl IDevice.getDeviceControl(); Return Value: Returns IDeviceControl getDeviceConfiguration This function retrieves a device configuration interface to the device. IDeviceConfiguration IDevice.getDeviceConfiguration(); MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 14...

  • Page 15: Getdeviceinfo

    ISO format for the PIN block. String The left most 12 digits of the Primary Account Number. Leave blank if not required by the ISO format for the PIN block. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 15...

  • Page 16: Requestsignature

    Returns true if successful. Otherwise, returns false. 4.13 startTransaction This function starts a transaction. The transaction will be processed through multiple calls to the event OnEvent. boolean IDevice.startTransaction(ITransaction transaction); MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 16...
  • Page 17 By default, devices with a display signal the end of a transaction by briefly showing “THANK YOU,” then “WELCOME.” sage Usage: false – Do not suppress the thank you message. true – Suppress the thank you message. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 17...
  • Page 18 0x23 - “TAP or SWIPE CARD” 0x24 - “TAP or INSERT CARD” 0x25 - “TAP, INSERT or SWIPE CARD” 0x26 - “TAP CARD” 0x27 - “TIMEOUT” 0x28 - “TRANSACTION TERMINATED” MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 18...
  • Page 19 ISO 18245. The byte array is null by default. MerchantID byte[] EMV Tag 9F16 - Used to uniquely identify a given merchant. The byte array is null by default. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 19...

  • Page 20: Subscribeall

    This function allows the host to no longer receive any events sent by the device. boolean IDevice.unsubscribeAll(IEventSubscriber eventCallback); Parameter Description eventCallback Name of a class that implements the IEventSubscriber Delegates event. Return Value: Returns true if successful. Otherwise, returns false. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 20...

  • Page 21: Idevicecapabilities

    Return Value: Returns true if device is equipped with a PIN Pad. Otherwise, returns false. Signature This property returns true if the device is equipped signature capture. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 21...

  • Page 22: Sred

    This property returns true if the device supports Secure Reading and Exchange of Data. boolean IDeviceCapabilities.SRED(); Return Value: Returns true if device supports SRED. Otherwise, returns false. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 22...

  • Page 23: Idevicecontrol

    IDeviceControl.deviceReset(); Return Value: Returns true if successful. Otherwise, returns false. displayMessage This function sets a show message on the device’s display. boolean IDeviceControl.displayMessage(byte messageID, byte timeout); MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 23...
  • Page 24 0x23 - “TAP or SWIPE CARD” 0x24 - “TAP or INSERT CARD” 0x25 - “TAP, INSERT or SWIPE CARD” 0x26 - “TAP CARD” 0x27 - “TIMEOUT” 0x28 - “TRANSACTION TERMINATED” MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 24...

  • Page 25: Endsession

    This function instructs the device to play a tone. boolean IDeviceControl.playSound(IData data); Parameter Description data Byte array or string data to send to the device. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 25...

  • Page 26: Send

    Return Value: Returns IResult. public interface IResult StatusCode Status; IData Data; public class Result implements IResult private StatusCode mStatus; private IData mData = null; public Result(StatusCode status) MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 26...

  • Page 27: Setdatetime

    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. boolean IDeviceControl.setLatch(boolean enableLock); MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 27...

  • Page 28: Showimage

    0x03 – show the image at slot 3. 0x04 – show the image at slot 4. Return Value: Returns true if successful. Otherwise, returns false. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 28...

  • Page 29: Connectioninfo

    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 DeviceType MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 29...

  • Page 30: Deviceinfo

    Returns the address of the device. getSerial This function returns the serial number of the device. String DeviceInfo.getSerial(); Return Value: Returns the address of the device. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 30...

  • Page 31: Ideviceconfiguration

    Return Value: Returns an array of bytes containing the configuration information. getDeviceInfo This function retrieves device specific information. String IDeviceConfiguration.getDeviceInfo(InfoType infoType); Parameter Description infoType Enumerated information type. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 31...

  • Page 32: Getfile

    Byte array for the file ID. For DynaFlex, use a 4-byte file id. data File contents to be sent to the device. Name of a class or structure that implements the IConfigurationCallback callback Delegates events. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 32...

  • Page 33: Sendimage

    Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value. setConfigInfo This function sets device configuration information. For an example, see appendix 12.9B.6 IDeviceConfiguration Walk Through. int IDeviceConfiguration.setConfigInfo( byte configType, byte[] data, IConfigurationCallback callback); MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 33...

  • Page 34: Setdisplayimage

    Name of a class or structure that implements the IConfigurationCallback callback Delegates events. Return Value: Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 34...

  • Page 35: Updatekeyinfo

    Name of a class or structure that implements the IConfigurationCallback callback Delegates events. Return Value: Returns 0 if the asynchronous update operation started. Otherwise, returns a non 0 value. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 35...

  • Page 36: Ieventsubscriber Delegates

    10 - IEventSubscriber Delegates IEventSubscriber Delegates MagTeK Universal SDK 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.

  • Page 37: Iconfigurationcallback Delegates

    11 - IConfigurationCallback Delegates IConfigurationCallback Delegates MagTek Universal SDK 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.

  • Page 38: Mtusdk Enumerations

    12 - MTUSDK Enumerations MTUSDK Enumerations 12.1 DeviceType This enum refers to the type of MagTek reader which the SDK will control. Enum Description Reserved for future use. Secure Reader Authenticator devices.  eDynamo  mDynamo  Dynamag SCRA ...

  • Page 39: Connectiontype

    12 - MTUSDK Enumerations 12.2 ConnectionType This enum refers to the communication interface type of MagTek reader which the SDK will control. Enum Description Universal Serial Bus supported devices:  DynaFlex  DynaFlex Pro Reserved for future use. BLUETOOTH_LE Bluetooth Low Energy devices: ...

  • Page 40: Connectionstate

    Bit 6 = Magnetic Stripe Reader Hardware problem present  Bit 7 = Reserved 12.5 PaymentMethod This enum refers to card type for which the device will perform a transaction. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 40...

  • Page 41: Statuscode

    The transactions is in progress. TransactionError There is an error during the transaction. TransactionApproved The transactions is approved. TransactionDeclined The transactions is declined. TransactionCompleted The transaction is completed. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 41...

  • Page 42: Eventtype

    This enum refers to the type of user event reported by the device. These events are related to user interaction. Enum Description None No events yet to occur. ContactlessCardPresented Contactless card has been presented. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 42...
  • Page 43 Card is seated into the chip station. CardUnseated Card was removed from the chip station. CardSwiped Magnetic stripe card was swiped. TouchPresented Touch screen press detected. TouchRemoved Touch screen release detected. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 43...

  • Page 44: Appendix A Status Codes

    ERROR = 2, UNAVAILABLE = 3 Enum Description SUCCESS The operation completed successfully. TIMEOUT The operation timed out. ERROR Error attempting the operation. UNAVAILABLE Status currently unavailable. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 44...

  • Page 45: Appendix Bapi Walk Through

    CoreAPI.getDeviceList  List<IDevice> 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.

  • Page 46: Idevice Walk Through

    EventsVector eventsVector = new EventsVector() boolean return = device.unsubscribeAll(eventsVector); boolean return = device.subscribeAll(eventsVector); // Assign parameters for the transaction. List<PaymentMethod> paymentMethod = new List<PaymentMethod>(); paymentMethod.Add(PaymentMethod.MSR); paymentMethod.Add(PaymentMethod.Contact); MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 46...

  • Page 47: Handling Events

    Various events are separately shown below. case EventType.ConnectionState: // Parse for the ConnectionState ConnectionState value = ConnectionStateBuilder.GetValue(data.StringValue); break; case EventType.DeviceResponse: break; case EventType.DeviceExtendedResponse: break; case EventType.DeviceNotification: break; MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 47...
  • Page 48 – remainder contains the ARQC TLV object IData processorARPC; procARPC.byteArray = sendForAuthorization(data.ByteArray); // Send authorization to device when not in QuickChip mode. if (transaction.QuickChip == false) device.sendAuthorization(procARPC.ByteArray); break; MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 48...
  • Page 49 // Parse the TLV from data[]. // Abstract Approval status from TLV tag “DFDF1A”. // Abstract Signature Required status from TLV tag at data[0]. break; case EventType.PINBlock: break; case EventType.Signature: break; MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 49...

  • Page 50: Idevicecontrol Walk Through

    // Establish a deviceControl from device. IDeviceControl deviceControl = device.getDeviceControl(); // Open the device, then use the IDeviceControl functions. deviceControl.open(); . . . // Close the device. deviceControl.close(); MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 50...

  • Page 51: Connectioninfo Walk Through

    // Establish a ConnectionInfo from device. ConnectionInfo connectionInfo = device.getConnectionInfo(); // Retrieve address, connectionType, and deviceType. String address = connectionInfo.getAddress(); ConnectionType connectionType = connectionInfo.getConnectionType(); DeviceType deviceType = connectionInfo.getDeviceType(); MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 51...

  • Page 52: Idevicecapabilities Walk Through

    // Retrieve device capabilities. boolean batteryBackedClock = capabilities.BatteryBackedClock(); if (batteryBackedClock) // Call IDeviceControl.setDateTime(). // Retrieve supported card payment methods. List<PaymentMethod> paymentMethods = capabilities.PaymentMethods(); . . . MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 52...

  • Page 53: Ideviceconfiguration Walk Through

    Note: first digit of OID is ommited in the custruction and instead is passed as the configType. data = new byte[] {0xE2,0x09,0xE1,0x07,0xE1,0x05,0xE1,0x03,0xC1,0x01,0x00 }; result = devConfig.getConfigInfo(0x01, data); MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 53...

  • Page 54: Handling Events

    = null; DeviceType deviceType = device.getConnectionInfo().getDeviceType(); switch (deviceType) case DeviceType.MMS: macBytes = getDynaFlexMAC(macType, data); break; if (macBytes != null) result = new Result(StatusCode.SUCCESS, new BaseData(macBytes)); return result; MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 54...

  • Page 55: Appendix Cemv Transaction Flow

    OnDisplayMessageRequest() ”PRESENT CARD” OnUserSelection() setUserSelectionResult() -App / Language OnARQCReceive() Forward ARQC to Processor -F9 TLV Object sendAuthorization() -F9 TLV Object OnDisplayMessageRequest() “APPROVED” OnTransactionResult() -F9 TLV Object MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 55...

  • Page 56: Sample Flow Code

    // Assign parameters. List<PaymentMethod> paymentMethod = new ArrayList<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); // Start transaction. boolean result = device.startTransaction(transaction); MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 56...
  • Page 57 // #2 @Override public void OnEvent(EventType eventType, IData data) String message; switch (eventType); case EventType.DisplayMessage: // Get the message. if (data != NULL) message = data.StringValue(); break; MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 57...
  • Page 58 // display/retrieve user selection..// set status and selection result. IData selectionData = new IData; selectionData[0] = status; selectionData[1] = selection; device.sendSelection(data); break; MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 58...
  • Page 59 – remainder contains the ARQC TLV object */ IData processorARPC; procARPC.byteArray = sendForAuthorization(data.ByteArray()); // #4b // Send authorization to device when not in QuickChip mode. if (transaction.QuickChip == false) device.sendAuthorization(procARPC.ByteArray()); break; MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 59...
  • Page 60 = data.StringValue(); // A data size of 0 is an instruction to clear the display. if (data.StringValue().Length == 0) // Clear the UI display. break; MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 60...
  • Page 61 – 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]. break; MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 61...

  • Page 62: Msr Fallback Flow

     Host displays a message each time the transaction fails until successful or until Host decides to end the transaction.  Device sends the transaction result. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 62...
  • Page 63 Appendix C - EMV Transaction Flow Begin initial transaction: startTransaction() MSR+Chip+Contactless OnEvent() ”PRESENT CARD” Card holder presents card. “NOT ACCEPTED” “REMOVE CARD” “FAILED" Transaction terminated with fallback type MSR. MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 63...
  • Page 64 Appendix C - EMV Transaction Flow Continue with Fallback transaction: displayMessage() “USE MAGSTRIPE” startTransaction() displayMessage() “TRY AGAIN” Retry > 3 Swipe accepted? Transaction terminated. Receive ARQC Process ARQC sendAuthorization() Transaction Complete MagTek Universal SDK| For MMS Devices | Programmer’s Manual ( Java ) Page 64...

Table of Contents