background image

 

MagTek  I  1710 Apollo Court  I  Seal Beach, CA 90740  I  Phone: (562) 546-6400  I  Technical Support: (888) 624-8350 

www.magtek.com 

Dynamag, DynaMAX, eDynamo, 

mDynamo, tDynamo, DynaWave, 

and iDynamo 6 

Secure Card Reader Authenticators 

Programmer’s Reference (Java and Java Applet) 

 

 

 

 
 
 
 

November 2019 

 

Manual Part Number:  

D99875724-101 

 

REGISTERED TO ISO 9001:2015 

 

 

Summary of Contents for DYNAMAG

Page 1: ...400 I Technical Support 888 624 8350 www magtek com Dynamag DynaMAX eDynamo mDynamo tDynamo DynaWave and iDynamo 6 Secure Card Reader Authenticators Programmer s Reference Java and Java Applet November 2019 Manual Part Number D99875724 101 REGISTERED TO ISO 9001 2015 ...

Page 2: ...ks of Microsoft Corporation Oracle and Java are registered trademarks of Oracle and or its affiliates EMV is a registered trademark in the U S and other countries and an unregistered trademark elsewhere The EMV trademark is owned by EMVCo LLC The Contactless Indicator mark consisting of four graduating arcs is a trademark owned by and used with permission of EMVCo LLC All other system names and pr...

Page 3: ...er s Reference Java and Java Applet Page 3 100 10 08 2019 Updated events for the event onTransactionStatus and result codes for the event onDeviceExtendedResponse Updated the function startTransaction cardType option and transactionType 101 11 11 2019 Added the format of card data returned from GetCardData ...

Page 4: ...If Licensee transfers the Software without authorization all rights granted under this Agreement are automatically 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 violation of this Agreement TERM This Agreement is in effect as long as Licensee continues the use...

Page 5: ...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 ACKNOWLEDGMENT LICENSEE ACKNOWLEDGES THAT HE HAS READ THIS AGREEMENT UNDERSTANDS ALL OF ITS TERMS CONDITIONS AND RESTRICTIONS AND AGREES TO BE BOUND BY THEM LICENSEE ALSO AGREES THAT THIS AGREEMENT SUPERSEDES ANY AND ALL VERBAL AND WRITT...

Page 6: ... Reader Control Panel 13 2 1 How to Download and Set Up the Swipe Reader Control Panel 13 2 2 How to Connect DynaMAX or eDynamo to a Windows Host via Bluetooth LE 13 2 3 How to Set Up the Java Library With the 32 bit JRE JVM 17 2 4 How to Manually Set Up the Java Library With the 64 bit JRE JVM 18 2 5 How to Set Up the Applet With the 32 bit JRE JVM 19 2 6 How to Modify Manifest 23 2 7 How to Sign...

Page 7: ...23 getCardExpDate 31 3 24 getExpDateMonth 31 3 25 getExpDateYear 31 3 26 getCardIIN 31 3 27 getCardLast4 31 3 28 getCapTracks 32 3 29 getTrackDecodeStatus 32 3 30 getTrack1DecodeStatus 32 3 31 getTrack2DecodeStatus 32 3 32 getTrack3DecodeStatus 32 3 33 getMaskedTracks 33 3 34 getTrack1Masked 33 3 35 getTrack2Masked 33 3 36 getTrack3Masked 33 3 37 getTrack1 33 3 38 getTrack2 33 3 39 getTrack3 33 3 ...

Page 8: ...nly 40 4 MTSCRAEvent 41 4 1 onLibLoaded 41 4 2 onDeviceConnectionStateChanged 41 4 3 onError 41 4 4 onDataReceived 41 4 5 onDeviceResponse 41 4 6 onTransactionStatus EMV Only 42 4 7 onDisplayMessageRequest EMV Only 43 4 8 onUserSelectionRequest EMV Only 44 4 9 onARQCReceived EMV Only 44 4 10 onTransactionResult EMV Only 45 4 11 OnDeviceExtendedResponse Emv Only 45 Appendix A Status Codes 47 A 1 Li...

Page 9: ...6 Secure Card Reader Authenticators Programmer s Reference Java and Java Applet Page 9 Appendix E ARQC Response from online processing 57 Appendix F Transaction Result Message Batch Data Format 58 F 1 DFDF1A Transaction Status Return Codes 58 Appendix G Supported Device Features 60 ...

Page 10: ...t the Read Parse Card Data The Java applet available from MagTek provides demonstration source code and a reusable Java applet that provides developers of custom HTML JavaScript software solutions with a set of functions that parallels the functionality to the Java library in applet form 1 3 Nomenclature The general terms device and host are used in different often incompatible ways in a multitude...

Page 11: ...ds the Swipe Reader Control Panel Java software Test bat This bat file launches the SwipeReaderControlPanel jar software L2 html This sample web page demonstrates how to use the applet 1 5 System Requirements 1 5 1 Java Library Tested operating systems Windows 7 Windows 8 8 1 Windows 10 Java Build Platform JDK 1 8 32 bit Minimum Java Runtime requirements Java 8 Tested Java Runtime Environments Jav...

Page 12: ...B Windows 7 Windows 8 8 1 Windows 10 DynaMAX USB Windows 7 Windows 8 8 1 Windows 10 Bluetooth LE Windows 8 8 1 Windows 10 eDynamo USB Windows 7 Windows 8 8 1 Windows 10 Bluetooth LE Windows 8 8 1 Windows 10 mDynamo USB Windows 7 Windows 8 8 1 Windows 10 tDynamo USB Windows 7 Windows 8 and 8 1 Windows 10 DynaWave USB Windows 7 Windows 8 and 8 1 Windows 10 iDynamo 6 USB Windows 7 Windows 8 and 8 1 W...

Page 13: ...uetooth adapter install any required drivers and connect it to the host 2 On the host install and configure the software you intend to use with DynaMAX or eDynamo a Make sure the host software is configured to look for the device on the proper connection b Make sure the host software knows which device s it should interface with c Make sure the host software is configured to properly interpret inc...

Page 14: ...navigator select PC and devices Bluetooth 7 Make sure Bluetooth is turned on and close the PC and devices app 8 Launch the Windows Manage Bluetooth Devices app by following these steps a Enter desktop mode by swiping in from the left side of the touchscreen b Touch the Bluetooth icon in the system tray and select Add a Bluetooth Device see Figure 2 1 Figure 2 1 Launch Manage Bluetooth Devices App ...

Page 15: ...om of the device Note the final four digits 10 Read through the list of pairable devices and locate the device called DynaMAX nnnn or eDynamo nnn where nnnn is the last four digits of the device s serial number if the device does not show in the list power it off then power it back on Below the device name you should see the text Ready to pair 11 Select the device and press the Pair button If the ...

Page 16: ...let Page 16 12 Enter default passcode 000000 or the device s actual password if it has been configured differently then press the Next button Windows will return you to the Manage Bluetooth devices page After a short period of time you will see the text Connected below the device you are pairing with After a few seconds the device will disconnect which is normal power saving behavior ...

Page 17: ... Manage Bluetooth devices window 2 Press the Remove device button 2 3 How to Set Up the Java Library With the 32 bit JRE JVM MagTek highly recommends using the 32 bit version of Java when using the MTSCRA Java applet regardless of whether you are using a 32 bit or 64 bit version of Windows To set up and run the Java Demo software using the 32 bit version of Java on either a 32 bit or 64 bit versio...

Page 18: ... software and or continue to the setup steps in section 2 5 How to Set Up the Applet With the 32 bit JRE JVM 2 4 How to Manually Set Up the Java Library With the 64 bit JRE JVM MagTek highly recommends using the 32 bit version of Java if you intend to use the MTSCRA Java applet as described in section 2 3 regardless of whether you are using a 32 bit or 64 bit version of Windows 1 Uninstall any exi...

Page 19: ... the 32 bit version of Java on either a 32 bit or 64 bit version of Windows follow these steps 1 Follow the steps in section 2 3 How to Set Up the Java Library With the 32 bit JRE JVM Having a working JVM working Java library working drivers and working DLLs are prerequisites for using the applet 2 Verify Java is installed and that the Internet Explorer Java plugin is working correctly by using Or...

Page 20: ... web browser and navigate to localhost Verify the IIS default page appears as shown in Figure 2 3 Figure 2 3 IIS Default Page 5 If it does not already exist create a MTSCRA folder in C inetpub wwwroot If it does exist delete its contents 6 On the workstation where the Dynamag DynaMAX eDynamo mDynamo SCRA Windows SDK is installed navigate to the folder where it is installed By default it will be C ...

Page 21: ...orkstation Windows will install the device drivers automatically Wait for Windows to report the driver installation is complete 9 Open Internet Explorer as an administrator 10 If you are using a 64 bit version of Windows with IE8 or IE9 make sure to launch directly in 32 bit mode using the iexplore exe found in C Program Files x86 Verify you are running in 32 bit mode using the Help About menu 11 ...

Page 22: ...checkbox restart Windows 13 Open Windows Task Manager Ctrl Alt Del Start Task Manager 14 Open the Processes tab and sort by Image Name 15 Note the number and location of all iexplore exe 32 processes 16 In Internet Explorer navigate to http localhost MTSCRA mtjmsr html 17 In the Windows Task Manager Processes tab find the new process for the Internet Explorer tab you just opened and make sure it i...

Page 23: ...ndow Press the Run button to run the Java applet 20 On the Read Parse Card Data page select the device to open then press the Open Device button Command Response Status text box in the browser will display the text Reader Connected 21 Use the buttons and fields on the welcome page to test the connection to the device 2 6 How to Modify Manifest The Caller Allowable Codebase attribute is used to ide...

Page 24: ...e Manifest Attributes for Security please visit this website http docs oracle com javase 7 docs technotes guides jweb security manifest html In order to modify the Manifest file please follow these steps 1 Find installation folder by default the installation folder is Sample Code Java Applet Object Unsigned 2 Launch the command prompt and extract the META INF MANIFEST MF from the jar file jar xf m...

Page 25: ...ur applet into a Java Application Resource JAR file by entering the following command jar cvf C mtscra jar 7 Sign your applet by using jarsigner to sign the JAR file using the private key you saved in your keystore jarsigner C mtscra jar MyCert 8 Verify the output of your signed JAR file by entering the following command jarsigner verify verbose certs C mtscra jar Please visit this website https d...

Page 26: ...unctions see the mtjmsr html and mtjmsr js sample code in the SDK files Generally these functions will run in one of two modes Asynchronous functions will return data using the event handlers callback functions defined in section 4 MTSCRAEvent Synchronous functions will return requested data immediately in the function s return value If the requested data is not available immediately synchronous c...

Page 27: ... the listener object Void init MTSCRAEvent e Return Value None 3 5 getDeviceList This function enumerates all SCRA devices connected to the host String getDeviceList Return Value Returns a string which contains zero or more device paths separated by 3 6 isDeviceConnected This function retrieves the connection status of the device boolean isDeviceConnected Return Value True if the host is connected...

Page 28: ...ring containing the card data Fields are delimited by the pipe character Fields Device ID USB Vendor ID Device Serial Number Card Swipe Status CardEncode Type Track 1 Decode Status Track 2 Decode Status Track 3 Decode Status MagnePrint Status Track 1 Length Track 2 Length Track 3 Length Masked Track 1 Length Masked Track 2 Length Masked Track 3 Length MagnePrint Length Card Data Masked Card Data D...

Page 29: ...303030303233333030303F B999999555 5555550 LAST FIRST M 19042010000100233000000 9999995555555550 19042010000000233000 02 002A8069912E8BAB88EA89082AA4D701473EC3C1A0C8E1DF0075F40A167713CF6AE4DF 442DC4ED8831377E98AFA88AE422536CEF2F 100 3 11 getCardName This function retrieves the card name after a cardholder has swiped a card String getCardName Return Value String containing the card name 3 12 getFirs...

Page 30: ...r has swiped a card 3 18 getProductID This function returns the device s product identifier after a cardholder has swiped a card String getProductID Return Value Returns a null terminated string For example 2 3 19 getDeviceName This function retrieves the device name after a cardholder has swiped a card String getDeviceName Return Value String containing the device name 3 20 getCapMagneSafe20Encry...

Page 31: ...getCardExpDate Return Value String containing the card expiration date 3 24 getExpDateMonth This function retrieves the card expiration month after a cardholder swipes a card String getExpDateMonth Return Value String containing the card expiration month 3 25 getExpDateYear This function retrieves the card expiration year after a cardholder swipes a card String getExpDateYear Return Value String c...

Page 32: ...values representing the decode status for tracks 1 2 and 3 respectively from left to right Values are 00 Track OK 01 Track read Error 02 Track is Blank 3 30 getTrack1DecodeStatus This function retrieves track 1 decode status String getTrack1DecodeStatus Return Value String containing track 1 decode status 00 Track OK 01 Track read Error 02 Track is Blank 3 31 getTrack2DecodeStatus This function re...

Page 33: ...ing masked track 1 data 3 35 getTrack2Masked This function retrieves masked track 2 data String getTrack2Masked Return Value String containing masked track 2 data 3 36 getTrack3Masked This function retrieves masked track 3 data String getTrack3Masked Return Value String containing masked track 3 data 3 37 getTrack1 This function retrieves track 1 data String getTrack1 Return Value String containin...

Page 34: ...PrintStatus Return Value String containing the MagnePrint status 3 43 getEncryptionStatus This function retrieves encryption status See D99875475 MagneSafe V5 Communication Reference Manual for detail String getEncryptionStatus Return Value String containing encryption status 3 44 getDeviceSerial This function returns the device s serial number String getDeviceSerial Return Value Returns a string ...

Page 35: ...n about direct commands see D99875475 MagneSafe V5 Communication Reference Manual long sendCommandWithLength String lpCommand Parameter Description lpCommand A hexadecimal command string to send to the device For example command 000103 where 00 is command number 01 is the length and 03 is property ID will retrieve the device serial number Return Value Null terminated hex string for the return resu...

Page 36: ...ed but all of its keys have been used 0x0383 Failure DUKPT scheme is not loaded Security Level not 3 or 4 0x0384 Invalid Total Transaction Time field 0x0385 Invalid Card Type field 0x0386 Invalid Options field 0x0387 Invalid Amount Authorized field 0x0388 Invalid Transaction Type field 0x0389 Invalid Cash Back field 0x038A Invalid Transaction Currency Code field 0x038B Invalid Selection Status 0x0...

Page 37: ...l Encrypted Track 1 DFDF39 len val Encrypted Track 2 DFDF3B len val Encrypted Track 3 DFDF3C len val Encrypted MagnePrint DFDF3D len val Encrypted MagnePrint Status DFDF50 len val KSN Tag Description FA Container for generic data DFDF25 IFD Serial Number F4 Container for MSR data DFDF37 Encrypted T1 DFDF39 Encrypted T2 DFDF3B Encrypted T3 DFDF3C Encrypted MagnePrint DFDF3D Encrypted MagnePrint Sta...

Page 38: ...ip card Contactless chip card Refer to 4 11Appendix G for supported devices option 0x00 Normal 0x01 Bypass PIN 0x02 Force Online 0x04 Acquirer not available Note prevents long timeout on waiting for host approval causes decline to be generated internally if ARQC is generated To use Quick Chip mode set the most significant bit to 1 0x80 Quick Chip Normal 0x81 Quick Chip Bypass PIN 0x82 Quick Chip F...

Page 39: ...ection result It should be called after receiving the OnUserSelectRequest event which is triggered after the user makes a selection byte setUserSelectionResult byte status byte selection Parameter Description status Indicates the status of User Selection 0x00 User Selection Request completed see Selection Result 0x01 User Selection Request aborted cancelled by user 0x02 User Selection Request abor...

Page 40: ...Only This function informs EMV device to cancel current transaction byte cancelTransaction Return Value This function will always returns an empty string To get the result code of this command use getResultCode function 3 59 sendExtendedCommand EMV Only This function sends a direct extended command to the device using a hex value long sendExtendedCommmand String data Return Value 0 for no error ...

Page 41: ...et will invoke the callback functions in this chapter to provide the requested data and or a detailed response Custom code that uses the MTSCRA Java applet should implement the following JavaScript functions to process the returning data For sample code that demonstrates how to use these functions see the mtjmsr htm and mtjmsr js sample code in the SDK files 4 1 onLibLoaded public void onLibLoad i...

Page 42: ...ication will send hex string to represent transaction status Offset Field Name Value 0 Event Indicates the event that provoked this notification 0x00 No events since start of transaction 0x01 Card inserted Contact only 0x02 Card error 0x03 Transaction Progress Change 0x04 Notification that device is waiting for user selection 0x05 Timeout on user selection 0x06 Transaction Terminated 0x07 Host Can...

Page 43: ...on Contact Only 0x0B Terminal risk management Contact Only 0x0C Terminal action analysis Contact Only 0x0D Generating first application cryptogram Contact Only 0x0E Card action analysis Contact Only 0x0F Online processing 0x10 Waiting online processing response 0x11 Transaction Complete 0x12 Transaction Error 0x13 Transaction Approved 0x14 Transaction Declined 0x15 Transaction Cancelled by MSR Swi...

Page 44: ...ult command with transaction will be aborted and an appropriate Transaction Status will be available Value 0 is not allowed 2 Menu Items This field is variable length and is a collection of C style zero terminated strings maximum 17 strings The maximum length of each string is 20 characters not including a Line Feed 0x0A character that may be in the string The last string may not have the Line Fee...

Page 45: ... this transaction Offset Field Name Value 0 Signature Required This field indicates whether a card holder signature is required to complete the transaction 0x00 No signature required 0x01 Signature required If a signature is required it is expected that the host will acquire the signature from the card holder as part of the transaction data 1 Batch Data Length Two byte binary most significant byte...

Page 46: ... started 0x0381 Failure DUKPT scheme is not loaded 0x0382 Failure DUKPT scheme is loaded but all of its keys have been used 0x0383 Failure DUKPT scheme is not loaded Security Level not 3 or 4 0x0384 Invalid Total Transaction Time field 0x0385 Invalid Card Type field 0x0386 Invalid Options field 0x0387 Invalid Amount Authorized field 0x0388 Invalid Transaction Type field 0x0389 Invalid Cash Back fi...

Page 47: ... Secure Card Reader Authenticators Programmer s Reference Java and Java Applet Page 47 Appendix A Status Codes A 1 Library Status Codes 0x00 SUCCESS 0x01 FAILED 0x02 OPENED 0x03 MTSCRA_ST_INVALID_PARAM A 2 Device Status Codes 0x00 State Disconnected 0x01 State Connected 0x02 State Error ...

Page 48: ...follow these steps to completely remove any previously installed versions 1 If you are using Windows 8 switch to Desktop mode 2 Open the Windows Control Panel 3 If the Control Panel is in View by Category mode select Programs 4 Click the Java 32 bit link Windows 8 or the Java link Windows 7 to open the Java Control Panel window 5 Select the General tab 6 Under the Temporary Internet Files heading ...

Page 49: ...les 10 Press the OK button to close the Temporary Files Settings window 11 Press the OK button to close the Java Control Panel window 12 Launch Windows Explorer If you are using a 32 bit version of Windows navigate to C Windows System32 If you are using a 64 bit version of Windows navigate to C Windows SysWOW64 13 In that folder search for the following files and delete any that exist a MTSCRA dll...

Page 50: ...ProviderImpl ede19e basic Added progress listener sun plugin util ProgressMonitorAdapter 15d4f53 security Expected Main URL http localhost SCRA mtscra jar basic Plugin2ClassLoader addURL parent called for http localhost SCRA mtscra jar network Connecting http localhost SCRA mtscra jar with proxy DIRECT network Connecting http localhost 80 with proxy DIRECT network Connecting http localhost SCRA mt...

Page 51: ...yment session certificate store security Loading certificates from Deployment session certificate store security Loaded certificates from Deployment session certificate store security Validate the certificate chain using CertPath API security Loading Root CA certificates from C Program Files x86 Java jre7 lib security cacerts security Loaded Root CA certificates from C Program Files x86 Java jre7 ...

Page 52: ... visibility hidden __applet_relaunched false name MagTekUSCRA archive mtscra jar dll_auto_update Yes codebase http localhost SCRA security Grant socket perm for http localhost SCRA mtscra jar java security Permissions 10ac287 java net SocketPermission localhost connect accept resolve security Validate the certificate chain using CertPath API basic Plugin2ClassLoader getPermissions CeilingPolicy al...

Page 53: ...proxy DIRECT network Connecting http javadl esd secure oracle com 443 with proxy DIRECT network Connecting http javadl esd secure oracle com 443 with proxy DIRECT security Loading SSL Root CA certificates from C Program Files x86 Java jre7 lib security cacerts security Loaded SSL Root CA certificates from C Program Files x86 Java jre7 lib security cacerts security Obtain certificate collection in ...

Page 54: ...cate store security Loading certificates from Deployment session certificate store security Loaded certificates from Deployment session certificate store network Updating file at C Users longv AppData LocalLow Sun Java Deployment security baseline versions from url https javadl esd secure oracle com update baseline version network Updating file at C Users longv AppData LocalLow Sun Java Deployment...

Page 55: ...d openDevice MTSCRAEventHandler mEvent new MTSCRAEventHandler MagTekUSCRA mMTSCRA new MagTekUSCRA mMTSCRA init mEvent long rv mMTSCRA openDevice if rv 0 System out print SUCESS else System out print FAIL C 2 Close Device Example public void closeDevice MTSCRAEventHandler mEvent new MTSCRAEventHandler MagTekUSCRA mMTSCRA new MagTekUSCRA mMTSCRA init mEvent long rv mMTSCRA closeDevice if rv 0 System...

Page 56: ...Tag 9F1F TLV T1 DD len val DF36 Encrypted Tag 9F20 TLV T2 DD len val DF37 Encrypted Tag 9F61 TLV T2 CVC3 len val DF38 Encrypted Tag 9F62 TLV T1 PCVC3 len val DF39 Encrypted Tag DF812A TLV T1 DD len val DF3A Encrypted Tag DF812B TLV T2 DD len val DF3B Encrypted Tag DFDF4A TLV T2 ISO Format len val DF40 Encrypted Value only of DFDF4A T2 ISO Format len val DynaPro Format F9 len container for MAC stru...

Page 57: ...e currently 2 selectable formats Original and DynaPro It is a TLV object with the following contents Original format F9 len container for ARQC Response data DFDF25 IFD Serial Number len val FA len Container for generic data 70 len Container for ARQC 8A len approval Further objects as needed DynaPro format F9 len container for MAC structure and generic data DFDF54 MAC KSN len val DFDF55 Mac Encrypt...

Page 58: ... DFDF17 F3 len container for Reversal Data if any Reversal Data tags defined in DFDF05 Note Sensitive Data cannot be defined in DFDF05 F7 len container for Merchant Data Merchant Data tags F8 len container tag for encrypted data DFDF56 Encrypted Transaction Data KSN len val DFDF57 Encrypted Transaction Data Encryption Type val FA len container for generic data DF30 Encrypted Tag 56 TLV T1 Data len...

Page 59: ...F25 IFD Serial Number len val FA len container for generic data F0 len Transaction Results F1 len container for Status Data Status Data tags F8 len container tag for encryption DFDF59 Encrypted Data Primative len Encrypted Data val Decrypt data to read tags DFDF56 Encrypted Transaction Data KSN len val DFDF57 Encrypted Transaction Data Encryption Type val DFDF58 of bytes of padding in DFDF59 len v...

Page 60: ...Y Y N N N N N N N MSR JIS Capable Y N N Y N N N Y N N SHA 1 N Y Y N N N N N N N SHA 256 N N N N N N N N N N Configurable SHA N Y Y N N N N N N N Configurable Encryption Algorithm N N N N N Y N N N N Set Mask Service Code N N N N N N N N N N Never Mask Service Code N N Y Y Y Y Y Y Y N MagneSafe 2 0 N N Y N N N N N N N EMV Contact N N Y N N Y Y N Y N EMV Contactless N N N N N Y Y N Y N EMV Offline O...

Page 61: ...sDynamo tDynamo uDynamo Display N N N N N N N N N N Multi Language N N Y N N Y Y N Y N Tamper N N Y N N N N N N N Extended Commands N N Y N N Y Y N Y N Extended Notifications N N Y N N Y Y N Y N Dual USB Ports N N N N N Y N N Y N Pairing Modes N N Y N N N N N Y N Custom Advertising N N Y N N N N N Y N Configurable Lightning FID Y N N N Y Y Y N N N Auxiliary Ports N N N N N N N N N N External LED C...

Reviews: