Magtek Universal SDK, Programmer'S Manual

Page 1: ...Seal Beach CA 90740 I Phone 562 546 6400 I Technical Support 888 624 8350 www magtek com MagTek Universal SDK For MMS Devices Programmer s Manual Java September 2021 Manual Part Number D998200385 10...

Page 2: ...DynaPro Mini are trademarks of MagTek Inc The Bluetooth word mark and logos are registered trademarks owned by Bluetooth SIG Inc and any use of such marks by MagTek is under license Microsoft and Win...

Page 3: ...utomatically terminated COPYRIGHT The Software is copyrighted Licensee may not copy the Software except for archival purposes or to load for execution purposes All other copies of the Software are in...

Page 4: ...the benefit of MagTek Incorporated its successors or assigns ACKNOWLEDGMENT LICENSEE ACKNOWLEDGES THAT HE HAS READ THIS AGREEMENT UNDERSTANDS ALL OF ITS TERMS CONDITIONS AND RESTRICTIONS AND AGREES TO...

Page 5: ...JAR 10 2 5 How to Set Up the SDK in Eclipse 11 3 CoreAPI 12 3 1 getAPIVersion 12 3 2 getDevice 12 3 3 getDeviceList 12 3 4 getConnectionTypes 13 3 5 GetConnectionTypeString 13 3 6 GetConnectionTypeFro...

Page 6: ...sendSync 26 6 11 setDateTime 27 6 12 setLatch 27 6 13 showImage 28 7 ConnectionInfo 29 7 1 getAddress 29 7 2 getConnectionType 29 7 3 getDeviceType 29 8 DeviceInfo 30 8 1 getModel 30 8 2 getName 30 8...

Page 7: ...6 StatusCode 41 12 7 TransactionStatus 41 12 8 EventType 42 12 9 UserEvent 42 Appendix A Status Codes 44 A 1 Library Status Codes 44 Appendix B API Walk Through 45 B 1 CoreAPI Walk Trough 45 B 2 IDevi...

Page 8: ...tware 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 1 2 Nomenclature D...

Page 9: ...be used follow these steps a On the master workstation navigate to the root of the MagTek Universal SDK for Java By default it will be x86 for 32 bit operating systems or x64 for 64 bit operating syst...

Page 10: ...pdate the manifest to the jar file jar umf META INF MANIFEST MF mtusdk jar 2 4 How to Sign JAR These instructions provide an overview of obtaining and using Sun Java signing and a digital certificate...

Page 11: ...s 2 5 How to Set Up the SDK in Eclipse To set up the MT Universal Java Libraries download and install package from MagTek com 1 On the master workstation navigate to the root of the MagTek Universal S...

Page 12: ...getDevice This function returns an instance of a device IDevice CoreAPI getDevice DeviceType deviceType ConnectionType connectionType String deviceAddress Parameter Description deviceType Enumerated d...

Page 13: ...list of List ConnectionType 3 5 GetConnectionTypeString This function returns a string for a connection type String CoreAPI GetConnectionTypeString ConnectionType connectionType Parameter Description...

Page 14: ...Capabilities IDevice getCapabilities Return Value Returns IDeviceCapabilities 4 3 getConnectionInfo This function retrieves the connection information of the device ConnectionInfo IDevice getConnectio...

Page 15: ...e data will be returned in the event OnEvent requestPin is reserved for future use boolean IDevice requestPIN PINRequest pinRequest Parameter Type Description Timeout byte Wait time in seconds PINMode...

Page 16: ...IData data Parameter Description data Contains ARPC blob Return Value Returns true if successful Otherwise returns false 4 12 sendSelection This function send a user selection to the device boolean ID...

Page 17: ...et to Z3 Card holder is prompted to remove the card Transaction result is later determined by the processor and not by the card Usage false Do not enable QuickChip mode true Enable QuickChip mode Defa...

Page 18: ...NCEL OR ENTER 0x06 CARD ERROR 0x07 DECLINED 0x08 ENTER AMOUNT 0x09 reserved do not use 0x0A reserved do not use 0x0B INSERT CARD 0x0C NOT ACCEPTED 0x0D reserved do not use 0x0E PLEASE WAIT 0x0F PROCES...

Page 19: ...ndary amount associated with the transaction Example 000000000123 1 23 000000009999 99 99 CurrenyCode byte 2 EMV Tag 5F2A Currency code of the transaction according to ISO 4217 The byte array is null...

Page 20: ...device boolean IDevice subscribeAll IEventSubscriber eventCallback Parameter Description eventCallback Name of a class that implements the IEventSubscriber Delegates event Return Value Returns true if...

Page 21: ...f device is equipped with a display Otherwise returns false 5 3 MSRPowerSaver This property returns true if the device has the option to disable or enable the magnetic stripe reader head MSR The MSR m...

Page 22: ...lities Signature Return Value Returns true if device is equipped with signature capture Otherwise returns false 5 7 SRED This property returns true if the device supports Secure Reading and Exchange o...

Page 23: ...ontrol close Return Value Returns true if successful Otherwise returns false 6 2 deviceReset This function resets the device This is equivalent to a power reset After the reset connection to the devic...

Page 24: ...x0E PLEASE WAIT 0x0F PROCESSING ERROR 0x10 REMOVE CARD 0x11 USE CHIP READER 0x12 USE MAGSTRIPE 0x13 TRY AGAIN 0x14 WELCOME 0x15 PRESENT CARD 0x16 PROCESSING 0x17 CARD READ OK REMOVE CARD 0x18 INSERT O...

Page 25: ...iceControl endSession Return Value Returns true if successful Otherwise returns false 6 5 getInput This function sends a request for user input at the device The response data will be returned in the...

Page 26: ...OnEvent boolean IDeviceControl sendExtendedCommand IData data Parameter Description data Byte array or string data to send to the device Return Value Returns true if successful Otherwise returns fals...

Page 27: ...ateTime This function sets the date and time for the device boolean IDeviceControl setDateTime IData data Parameter Description data Byte array or string data to send to the device Return Value Return...

Page 28: ...turns true if successful Otherwise returns false 6 13 showImage This function sends a command to immediately show an image on the device s display boolean IDeviceControl showImage byte imageID Paramet...

Page 29: ...eturns address of the device String ConnectionInfo getAddress Return Value Returns the address of the device 7 2 getConnectionType This function returns the type of connection interface for the device...

Page 30: ...1 getModel This function returns the model name of the device String DeviceInfo getModel Return Value Returns the address of the device 8 2 getName This function returns the name of the device String...

Page 31: ...ts other than the one specified will cause the token to be revoked erased byte IDeviceConfiguration getChallengeToken byte data Parameter Description data Byte array containing the request ID to be pr...

Page 32: ...tarted Otherwise returns a non 0 value 9 5 getKeyInfo This function retrieves key information byte IDeviceConfiguration getKeyInfo byte keyType byte data Parameter Description keyType Type of key For...

Page 33: ...ate operation started Otherwise returns a non 0 value 9 8 sendSecureFile This function sends a file to the device using a secure command structure int IDeviceConfiguration sendSecureFile byte fileID b...

Page 34: ...e The device requires a reset for the setting to take effect int IDeviceConfiguration setDisplayImage byte imageID Parameter Description imageID Value for the image ID For DynaFlex use 0 1 2 3 or 4 Us...

Page 35: ...IDeviceConfiguration updateKeyInfo byte keyType byte data IConfigurationCallback callback Parameter Description keyType Type of key data Key data to be sent to the device callback Name of a class or s...

Page 36: ...ubscribeAll function with the name of a class that implements the IEventSubscriber Delegates interface 10 1 OnEvent OnEvent handles most event types The eventType parameter defines which event is trig...

Page 37: ...cType byte data Parameter Description macType Type of Mac algorithm For DynaFlex use 0 data Contains the data of the payload to MAC Return Value Returns an IResult that contains the calculated MAC 11...

Page 38: ...control Enum Description SCRA Reserved for future use Secure Reader Authenticator devices eDynamo mDynamo Dynamag DynaMax tDynamo kDynamo cDynamo iDynamo 6 PPSCRA Reserved for future use PIN Pad Secur...

Page 39: ...o BLUETOOTH_LE_EMVT Reserved for future use Bluetooth Low Energy with EMV supported devices tDynamo TCP Reserved for future use Transmission Control Protocol supported devices DynaPro TCP_TLS Reserved...

Page 40: ...ce Enum Description DeviceSerialNumber Device serial number FirmwareVersion Firmware version of the device DeviceCapabilities Capabilities of the device delimited by a comma Boot1Version Boot 1 firmwa...

Page 41: ...Description NoStatus Set before the start of a transaction and before a card is presented to the device NoTransaction No transaction is progress CardSwiped A card was swiped into the device CardInser...

Page 42: ...magnetic stripe data from a card swipe TransactionStatus There was a change in transaction status DisplayMessage Device has data to be displayed to the user InputRequest Device is requesting input fr...

Page 43: ...Description ContactlessCardRemoved Contactless card has been removed CardSeated Card is seated into the chip station CardUnseated Card was removed from the chip station CardSwiped Magnetic stripe card...

Page 44: ...44 Appendix A Status Codes A 1 Library Status Codes public enum StatusCode SUCCESS 0 TIMEOUT 1 ERROR 2 UNAVAILABLE 3 Enum Description SUCCESS The operation completed successfully TIMEOUT The operatio...

Page 45: ...ice 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 Access MMS with U...

Page 46: ...vice device deviceList get 0 For a list of multiple device types List DeviceType deviceTypes null deviceTypes Add DeviceType MMS deviceTypes Add DeviceType CMS List IDevice deviceList CoreAPI getDevic...

Page 47: ...window may extent the Error Reference source not found or can be extended by a eparate class This example uses a separate class and demonstrates how to parse for the various event types Example A clas...

Page 48: ...il data StringValue break case EventType DisplayMessage String message Get the message if data NULL message TransactionStatusBuilder GetStatusDetail data StringValue break case EventType InputRequest...

Page 49: ...nsactionResult 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...

Page 50: ...viceControl IDeviceControl open IDeviceControl other functions IDeviceControl close Example Establish a device from CoreAPI List IDevice deviceList CoreAPI getDeviceList IDevice device deviceList get...

Page 51: ...tConnectionType ConnectionInfo getDeviceType Example Establish a device from CoreAPI List IDevice deviceList CoreAPI getDeviceList IDevice device deviceList get 0 Establish a ConnectionInfo from devic...

Page 52: ...s PaymentMethods to check card types supported IDeviceCapabilities other functions Establish a device from CoreAPI List IDevice deviceList CoreAPI getDeviceList IDevice device deviceList get 0 Establi...

Page 53: ...e other class ConfigCallBacks configCallBacks new ConfigCallBacks Update firmware byte data File ReadAllBytes filepath int return devConfig updateFirmware 0x01 data this Get configuration Device Drive...

Page 54: ...ConfigCallbacks MTUSDK IConfigurationCallback public void OnProgress int progress Handle progress Progress is complete when progress 100 public void OnResult StatusCode status byte data Handle result...

Page 55: ...saction Flow C 1 Flow Chart startTransaction OnDisplayMessageRequest PRESENT CARD OnUserSelection App Language setUserSelectionResult OnARQCReceive F9 TLV Object Forward ARQC to Processor OnDisplayMes...

Page 56: ...Method new ArrayList PaymentMethod paymentMethod Add PaymentMethod MSR paymentMethod Add PaymentMethod Contact paymentMethod Add PaymentMethod Contactless Transaction transaction new Transaction trans...

Page 57: ...ersal SDK For MMS Devices Programmer s Manual Java Page 57 2 Override public void OnEvent EventType eventType IData data String message switch eventType case EventType DisplayMessage Get the message i...

Page 58: ...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 selectio...

Page 59: ...C 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 IData processorARPC procARPC byteArray sen...

Page 60: ...Page 60 5 Override 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 i...

Page 61: ...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 obje...

Page 62: ...evice 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 beg...

Page 63: ...sal SDK For MMS Devices Programmer s Manual Java Page 63 Begin initial transaction startTransaction MSR Chip Contactless OnEvent PRESENT CARD NOT ACCEPTED REMOVE CARD FAILED Transaction terminated wit...

Page 64: ...Programmer s Manual Java Page 64 Continue with Fallback transaction Transaction Complete displayMessage USE MAGSTRIPE startTransaction MSR Swipe accepted No Yes Retry 3 No Yes Transaction terminated...