MagTek
OPOS FOR MSR DEVICES
PROGRAMMING REFERENCE M ANUAL
Part Number: 99875578 Rev 1
FEBRUARY 2012
REGISTERED TO ISO 9001:2008
1710 Apollo Court
Seal Beach, CA 90740
Phone: (562) 546-6400
FAX: (562) 546-6301
Technical Support: (651) 415-6800
www.magtek.com
ii
Rev Number
Date
Notes
1
22 Feb 12
Initial Release
Copyright© 1999-2012
MagTek®, Inc.
Printed in the United States of Americ a
Information in this document is subject to change without notice. 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.
REVISIONS
iii
SOFTWARE LICENSE AGREEMENT
IMPORTANT: YOU SHOULD CAREFULLY READ ALL THE TERMS, CONDITIONS AND RESTRICTIONS OF THIS LICENSE
AGREEMENT BEFORE INSTALLING THE SOFTWARE PACKAGE. YOUR INSTALLATION OF THE SOFTWARE PACKAGE
PRESUMES YOUR ACCEPTANCE OF THE TERMS, CONDITIONS , AND RESTRIC TIONS CONT AINED IN THIS AGREEMENT. IF
YOU DO NOT AGREE WITH THESE TERMS, CONDITIONS, AND RESTRICTIONS, PROMPTLY RETURN THE SOFTWARE
PACKAGE AND ASSOCIATED DOCUMENTATION TO ABOVE ADDRESS 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.
LICENSEE MAY NOT COPY, MODIFY OR TRANSFER THE SOFTWARE IN WHOLE OR IN P ART EXCEPT AS EXPRESSLY
PROVIDED IN THIS AGR EEMENT. Licensee may not deco mpile, disassemble or in an y other manner attempt to revers e engineer the
Software. Licensee shall not tamper with, bypass or alter any security features of the software or attempt to do so.
TRANSFER: Licensee may not transfer the Software or license to the Software to another party without prior written authorization of the
Licensor. If Licensee tran sfers the Software without authorization, all rights granted under this Agreement are automatically terminated.
COPYRIGHT:
purposes. All other copies of the Software are in violation of this Agreement.
TERM:
this Agreement if Licensee fails to comply with any of the terms, conditions or restrictions contained herein. Should Licensor terminate this
Agreement due to Licensee' s failure to comply, Licensee agrees to return the Software to Licensor. Receipt o f returned Software by the
Licensor shall mark the termination.
This Agreement is in effect as l ong as Lic ensee co ntin ues the u se of the S oftware. The Li censo r also res erves the ri ght to terminate
LIMITED WARRANTY:
from defects in material or workmanship under normal use. THE SOFTWARE IS P ROVIDED AS IS WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Because of the diversity of conditions and PC hardware under
which the Software may be used, Licensor does not warrant that the Software will meet Licensee specifications or that the operation of the
Software will be uninterrupted or free of errors.
IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS OR
OTHER INCIDENTAL OR CONSEQUENTI AL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE.
Licensee's sole remed y in the event of a defect in material or workmanship is expressl y limited to replacement of the So ftware disk(s) if
applicable.
GOVERNING LAW: If any provision of this Agreement is found to be unlawful, void or unenforceable, that provision shall be removed
from consideration under this 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 insure to the benefit of MagTek, Incorporated, its successors or assigns.
The Software is copyrighted. Licensee may not copy the Software except for archival purposes or to load for execution
Licensor warrants to the Licensee that the disk(s) or other media on which the Software is recorded to be free
ACKNOWLEDGMENT:
ITS TERMS, CONDITIONS AND RESTRICTIONS AND AGREES TO BE BOUND BY THEM. LICENSEE ALSO AGREES THAT
THIS AGREEMENT SUPERSEDES ANY AND ALL, VE RBAL AND WRITTEN, COMMUNICATIONS B ETWEEN LICENSOR AND
LICENSEE OR THEIR ASSIGNS RELATING TO THE SUBJECT MATTER OF THIS AGREEME NT.
LICENSEE ACKNOWLEDGES THAT HE HAS READ THIS AGREEMENT, UNDERS TANDS ALL OF
QUESTIONS REGARDING THIS AGREEMENT SHOULD BE ADDRESSED IN WRITING TO MAGTEK, INCORPORATED,
ATTENTION: CUSTOMER SUPPORT, AT THE ABOVE ADDRESS OR E-MAILED TO sup port@magtek. c om.
iv
TABLE OF CONTENTS
SECTION 1. INSTALLATION ...................................................................................................................... 1
SECTION 2. UTILITY ................................................................................................................................... 9
SECTION 3. SAMPLE ............................................................................................................................... 15
DEVICE POWER REPORTING ............................................................................................................. 22
SAVING DEVICE SETTINGS ACROSS CLAIM/RELEASE ................................................................... 22
ERROR PROCESSING .......................................................................................................................... 22
Reporting ............................................................................................................................................ 22
Incompatibility Issues ......................................................................................................................... 23
1
SECTION 1. INSTALLATION
The MagTek UPOS 1.13 OPOS MSR is installed via an InstallShield application. Within the
Disk1 folder, double click on the ‘setup.exe’ file to launch the installation.
The following screen shots will be a guide through the installation:
The Initial welcome screen for the installation of the MagTek OPOS MSR.
OPOS for MSR Devices
2
The license agreement display for acceptance or cancellation for the installation of the MagTek
OPOS MSR.
Section 1. Installation
3
The target folder location for the installation of the MagTek OPOS MSR.
The default target folder :
For x86 platforms: C:\Program Files\OPOS\MagTek
For x64 platforms: C:\Program Files (x86)\OPOS\MagTek
Click on the ‘Browse’ button to change the installation folder.
OPOS for MSR Devices
4
The setup type for the installation of the MagTek OPOS MSR is ‘Complete’ or ‘Custom’. The
‘Complete’ setup type will proceed to install all components for the MagTek OPOS MSR.
Section 1. Installation
5
The ‘Custom’ setup type will enable the options for the Common Control Objects and the OPOS
Sample components to be installed for the MagTek OPOS MSR.
OPOS for MSR Devices
6
The current settings displayed prior to installation of the MagTek OPOS MSR.
Section 1. Installation
7
The setup complete will be displayed for a successful installation of the MagTek OPOS MSR.
OPOS for MSR Devices
8
Maintenance for the MagTek OPOS MSR installation will include the options to Modify, Repair
or Remove (default).
* InstallShield is a registered trademark of the Flexera Software Company.
9
SECTION 2. UTILITY
The MagTek UPOS 1.13 OPOS MSR Utility application performs testing of the MagTek MSR
OPOS device object along with the management of the Logical Device Names (LDN)
registration. Within the MagTek OPOS MSR target installation folder, double click on the
‘OPOSMSRUtility.exe’ file to launch the MagTek OPOS MSR Utility application.
The MagTek OPOS MSR Utility application primary screen. The MSR Logical Device Name
(LDN) within the combo box is to first be selected for the USB connected MagTek MSR device
and tested by populating the fields below of the most recent swiped card data. The Clear button
will clear all display data fields.
Clicking the LDN button will launch the Logical Device Name Management dialog for adding
and deleting Logical Device Names for each MagTek MSR Master Key.
The MagTek MSR Master Keys available are the 1) MagTek_MSR-1 (representing the nonencrypted based reader) and 2) MagTek_MSR-2 (representing the encrypted based reader).
OPOS for MSR Devices
10
The default LDN’s installed:
MagTekMSR (MagTek non-encrypted MSR reader, using the MagTek MSR Master Key:
MagTek_MSR-1)
MagTekMSR_Encrypted (MagTek encrypted MSR reader, using the MagTek MSR Master Key:
MagTek_MSR-2).
The MagTek MSR Logical Device Names are displayed within the combo box: 1)
‘MagTekMSR’ (representing the non-encrypted based reader) and 2) ‘MagTekMSR_Encrypted’
(representing the encrypted based reader) to be tested via the populated fields:
Track 1 Data, Track 2 Data and Track 3 Data for both the MagTek Non-encrypted and encrypted
MSR reader; and the Additional Security Information, Track 1 Data Encrypted, Track 2 Data
Encrypted and Track 3 Data Encrypted for MagTek encrypted MSR reader.
Section 2. Utility
11
Example of using the ‘MagTekMSR’ Logical Device Name with the USB connected MagTek
non-encrypted based reader.
The appropriate non-encrypted data fields are populated with clear text information.
OPOS for MSR Devices
12
Example of using the ‘MagTekMSR_Encrypted’ Logical Device Name with the USB connected
MagTek encrypted based reader.
The appropriate encrypted data fields are populated with masked text data and encrypted data
along with the Additional Security Information for the encrypted data coding.
Section 2. Utility
13
When clicking the LDN button, the Logical Device Name Management dialog is launched for
adding and deleting Logical Device Names registrations for each MagTek MSR Master Key: 1)
MagTek_MSR-1 (representing the non-encrypted based reader) and 2) MagTek_MSR-2
(representing the encrypted based reader).
OPOS for MSR Devices
14
Select the MagTek Master Key via the ‘Master Key’ combo box to add or remove a Logical
Device Name (LDN).
In the example above, the Master Key ‘MagTek_MSR-1’ has an existing LDN ‘MagTekMSR’
with the LDN ‘Msr1’ to be added
via the Add LDN button.
Once the Logical Device Names are set (registered), close the Logical Device Name
Management dialog which will return control back to the primary MagTek OPOS MSR Utility
application screen.
The registered LDN’s will then be displayed within the MSR Logical Device Name combo box
to be selected for testing.
15
SECTION 3. SAMPLE
The MagTek UPOS 1.13 OPOS MSR Sample application demonstrates the UPOS 1.13 OPOS
MSR Properties, Methods and Events for the MagTek OPOS 1.13 MSR non-encrypted and
encrypted readers.
Within the MagTek OPOS MSR target installation folder, double click on the ‘Sample’ folder
and then double click on the ‘MSRSample.exe’ file to launch the MagTek OPOS MSR Sample
application.
The MagTek OPOS MSR Sample application screen. The MSR Logical Device Name (LDN)
within the combo box is to first be selected for the USB connected MagTek MSR device for
OPOS Properties, Methods and Events operations.
MSR Logical Device Name
[Combo box]
This combo box contains the OPOS registered Logical Device Names (LDN) to be selected the
for MagTek OPOS MSR device instantiation.
OPOS for MSR Devices
16
OPOS Open method
[Button]
This button will pass the selected LDN as the string parameter of the OPOS Open method, which
will instantiate the associated OPOS device object for processing of all OPOS MSR Properties,
Methods and Events.
OPOS Claim (ClaimDevice) method
[Button]
This button will claim the MagTek OPOS MSR device object for exclusive use.
(Required for the OPOS MSR device object).
OPOS DeviceEnabled property
[Check box]
This check box enables (checked) or disables (unchecked) the MSR device object.
(Required for most OPOS operations).
OPOS DataEventEnabled property
[Check box]
This check box enables (checked) or disables (unchecked) Data Events to be sent from the
MagTek OPOS MSR Service Object for any queued MSR read data. Per the UPOS 1.13 OPOS
Standards specification, this DataEventEnabled property is set to false within the MagTek OPOS
MSR Service Object after each OPOS MSR Data Event is fired to the OPOS application. The
OPOS application is required to re-enable the DataEventEnabled property to receive the MSR
read data from the most recent or queued card swipe.
OPOS CheckHealth method
[Button]
This button will invoke the CheckHealth (Internal) method and display the CheckHealthText
Property value within the output window.
OPOS ClearInput method
[Button]
This button will clear any queued MSR read data within the MagTek OPOS MSR Service
Object.
OPOS ClearInputProperties method
[Button]
This button will clear all properties populated via the most recent MSR read data.
Section 3. Sample
17
Properties
[Button]
This button will invoke and display all the OPOS common and device specific MSR properties
within the output window. All properties associated to MSR read data will contain data from the
most recently swiped card.
OPOS DecodeData property
[Check box]
This check box enables (checked) or disables (unchecked) the MSR specific DecodeData
property.
OPOS ParseDecodeData property
[Check box]
This check box enables (checked) or disables (unchecked) the MSR specific ParseDecodeData
property.
OPOS TransmitSentinels property
[Check box]
This check box enables (checked) or disables (unchecked) the MSR specific TransmitSentinels
property.
TracksToRead
[Combo box]
This combo box contains the OPOS MSR options for the Tracks To Read setting and reflected
within the populated OPOS MSR Properties.
DataEncryptionAlgorithm
[Combo box]
This combo box contains the MagTek OPOS MSR supported Data Encryption Algorithms.
Note: This Property setting only applies to the MagTek encrypted based MSR devices.
RetrieveCardProperty
[Combo box]
This combo box contains the MSR specific Properties to be retrieved corresponding to the
parsing of the recently swiped card.
Properties that do not contain data did not exist in the original track number data.
ErrorReportingType
[Combo box]
This combo box contains the MSR specific Property for reporting the error type, either Card or
Track based error reporting.
OPOS for MSR Devices
18
OPOS DirectIO method
[Button]
This button invokes the DirectIO Method example.
OPOS Statistics method
[Button]
This button invokes the supported RetrieveStatistics Method returning the OPOS Statistics XML
based string and is displayed within a launched dialog box.
OPOS AutoDisable property
[Check box]
This check box enables (checked) or disables (unchecked) the Auto Disable Property. This
Property is used for added control with receiving event driven input from the MSR device object.
OPOS FreezeEvents property
[Check box]
This check box enables (checked) or disables (unchecked) the Freeze Events Property. This
Property is used to control when events are to be received. This applies to all Events associated
with the OPOS MSR device object.
OPOS Release (Release Devi ce ) meth od
[Button]
This button will release the MagTek OPOS MSR device object from exclusive use.
OPOS Close method
[Button]
This button will close the MagTek OPOS MSR device object instantiation.
Section 3. Sample
19
Example of the Logical Device Name combo box containing the default OPOS MSR registered
Logical Device Names (LDN).
Additional Logical Device Names may be added or removed via the MagTek OPOS MSR Utility
application.
OPOS for MSR Devices
20
Example of a received and displayed OPOS MSR Data Event of a swiped card. The
’MagTekMSR’ Logical Device Name used as the OPOS MSR instantiated device object
representing the MagTek non-encrypted MSR device.
Section 3. Sample
21
Example of clicking the Properties button displaying the OPOS MSR populated Properties of the
most recently swiped card.
OPOS for MSR Devices
22
By default, the OMTD installation registers aliases for the control objects’ OLE programmatic
ID, as required by the OPOS specification. The registered aliases are:
• MSR Control Object = OPOS.MSR
• MICR Control Object = OPOS.MICR
• PINPad Control Object = OPOS.PINPad
• Line Display Control Object = OPOS.LineDisplay
When the alias registration is bypassed, the control objects are registered under the following
OLE programmatic IDs:
• MSR Control Object = MAGTEK.OPOS.MSR
• MICR Control Object = MAGTEK.OPOS.MICR
• PINPad Control Object = MAGTEK.OPOS.PPAD
• Line Display Control Object = MAGTEK.OPOS.LDSP
When the OMTD controls are uninstalled, the registered aliases are removed only if they still
refer to an OMTD control object meaning that another OPOS control has not been installed after
the OMTD controls were installed.
DEVICE POWER REPORTING
The OMTD controls do not support the optional power reporting capability described in the
OPOS Specification. This is due to the fact that MagTek devices and MTD do not report power
events.
SAVING DEVICE SETTINGS ACROSS CLAIM/RELEASE
The OPOS Specification defines that settable device characteristics are saved and restored for
each application that accesses the device. The complexity of supporting this functionality does
not justify the marginal benefit provided to applications. If MagTek foresees frequent
simultaneous access of a device from multiple applications, this feature may be added later.
ERROR PROCESSING
Reporting
The SO will display a message box if it receives a property request containing an invalid
PropIndex. These types of errors should be found during development, testing, or staging of the
containing application prior to rollout to a customer. This type of error reporting is
recommended by the OPOS Specification.
Section 3. Sample
23
Incompatibility Issues
If the control object determines that the specified service object is not supplied by MagTek or
does not implement the required device class methods, it will fail the Open method. The CO
determines if the SO is supplied by MagTek by querying a private property on the SO.
However, the SO should work with other COs by specification.
The minimally required device class methods are those methods that are common to all device
classes. Based on the service object version, one or more device class-specific methods may also
be required.
The PINPad CO will fail the Open method if the OPOS version of the SO is less than 1.3. This
is because the PINPad device class did not exist with prior versions of OPOS.
The SO will fail its OpenService method if it fails to bind to the SOxxx event handlers of the
CO.
Loading...