Audio Reader PROGRAMMING REFERENCE MANUAL for Android Devices PART NUMBER 99875583-1 SEPTEMBER 2012 Confidential This document contains the proprietary information of MagTek. Its receipt or possession does not convey any rights to reproduce or disclose its contents or to manufacture, use or sell anything it may describe. Reproduction, disclosure or use without specific written authorization of MagTek is strictly forbidden.
Copyright© 2001-2012 MagTek®, Inc. Printed in the United States of America 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 Rev Number 1.01 1.02 1.03 Date 30 Apr 12 20 Jun 12 27 Aug 12 1.
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 RESTRICTIONS CONTAINED IN THIS AGREEMENT. IF YOU DO NOT AGREE WITH THESE TERMS, CONDITIONS, AND RESTRICTIONS, PROMPTLY RETURN THE SOFTWARE PACKAGE AND ASSOCIATED DOCUMENTATION TO THE ABOVE ADDRESS, ATTENTION: CUSTOMER SUPPORT.
Table of Contents Section 1. MagTekSCRA Class ......................................................................................... 1 Methods........................................................................................................................... 3 openDevice: ................................................................................................................ 3 closeDevice .....................................................................................................
getPANHashSHA1 ................................................................................................... 17 getPANHashSHA256 ............................................................................................... 17 getResponseData ....................................................................................................... 17 getResponseType ...................................................................................................... 18 getTagValue .....................
vi
SECTION 1. MagTekSCRA CLASS Classes MagTekSCRA Description This class allows you to perform reader functions.
getTagValue getTLVVersion getTrackDecodeStatus listenForEvents sendCommandToDevice getSDKVersion setConfiguration setConfigurationParams setConfigurationXML getConfigurationXML getConfigurationResponse getConfigurationResponse setConfigurationResponse Retrieves the value of the specified tag Retrieves TTLV version Retrieves track decode status Sets which events to listen for Sends specified command to device, with timeout Retrieves the SDK version Sets configuration parameters from server Sets configuratio
Methods openDevice: This function opens the reader. - public void openDevice() Parameters None Return Value None closeDevice This function closes the reader. - public void closeDevice(){ Parameters None Return Value None isDeviceConnected This function retrieves the connection status of the reader. - public boolean isDeviceConnected() Parameters None Return Value TRUE if the device is connected. Otherwise, return FALSE.
getMaskedTracks Get stored masked tracks data. If decodable track data exists for a given track, it is located in the Masked Track Data field that corresponds to the track number. The length of each Masked Track Data field is fixed at 112 bytes, but the length of valid data in each field is determined by the Masked Track Data Length field that corresponds to the track number.
- public String getTrack2() Parameters Return Value Return stored track2 data string. getTrack3 Get stored track3 data. This field contains the encrypted track data for track 3. - public String getTrack3 () Parameters Return Value Return stored track3 data string. getTrack1Masked Get stored masked track1 data. - public String getTrack1Masked() Parameters Return Value Return stored masked track1 data string.
Return Value Return stored masked track2 data string. For an ISO/ABA card, the PAN is masked as follows: • The specified number of initial characters are sent unmasked. The specified number of trailing characters are sent unmasked. If Mod 10 correction is specified, all but one of the intermediate characters of the PAN are set to zero; one of them will be set such that last digit of the PAN calculates an accurate Mod 10 check of the rest of the PAN as transmitted.
For an AAMVA card, the specified mask character is substituted for each of the characters read from the card. getMagnePrint Supported on uDynamo only. This 128 byte Binary field contains the MagnePrint data. Only the number of bytes specified in the MagnePrint data length field are valid. The least significant bit of the first byte of data in this field corresponds to the first bit of MagnePrint data. If the Enable/Disable MagnePrint property is set to disable MagnePrint, this field will not be sent.
This four-byte field contains the MagnePrint status. The MagnePrint status is in little endian byte order. Byte 1 is the least significant byte. Byte 1 LSB is status bit 0. Byte 4 MSB is status bit 31.
getSessionID Not suported on Audio Reader. This 8-byte Binary field contains the encrypted version of the current Session ID. Its primary purpose is to prevent replays. After a card is read, this property will be encrypted, along with the card data, and supplied as part of the transaction message. The clear text version of this will never be transmitted.
MagTekSCRA.DEVICE_TYPE_NONE MagTekSCRA.DEVICE_TYPE_AUDIO MagTekSCRA.DEVICE_TYPE_BLUETOOTH Return Value setDeviceID Set device identifier for the Bluetooth device. - public void setDeviceID(String lpstrDeviceID) Parameters lpstrDeviceID ID of the Bluetooth device to connect to.
String representing MagnePrint capabilities 0 = No MagnePrint, 1 = Short MagnePrint, 2 = Long MagnePrint getCapMagnePrintEncryption Retrieves MagnePrint Encryption Capabilities - public String getCapMagnePrintEncryption() Parameters Return Value String representing MagnePrint Encryption capabilities 0 = No Encryption, 1 = Same as MagStripe (8122), other values TBD. If absent, default value is 1. getCapMagneSafe20Encryption Retrieves MagneSafe 2.
getCapMSR Retrieves MSR Capabilities - public String getCapMSR() Parameters Return Value String representing MSR Capabilities 0 = No MSR, 1 = MSR getCapTracks Retrieves Track Capabilities - public String getCapTracks() Parameters Return Value String representing Track Capabilities Bit 0 = 1 / Track 1 supported, Bit 1 = 1 / Track 2 supported, Bit 2 = 1 / Track 3 supported, all other bits 0.
Note: The data returned is dependent on the partial information provided by the reader. If the reader supports emitting partial data for the fields below, the SDK will provide them as is. If the reader supports masking, the SDK will retrieve the information from the masked tracks supplied by the reader.
Note: The data returned is dependent on the partial information provided by the reader. If the reader supports emitting partial data for the fields below, the SDK will provide them as is. If the reader supports masking, the SDK will retrieve the information from the masked tracks supplied by the reader.
Card Encode Type This one-byte value indicates the type of encoding that was found on the card. The following table defines the possible values. Value 0 Encode Type ISO/ABA 1 AAMVA 2 3 Reserved Blank 4 Other 5 Undetermined 6 None Description ISO/ABA encode format. At least one track in ISO/ABA format, Track 3 not AAMVA format. AAMVA encode Track 3 is AAMVA format, Tracks 1 and 2 are ISO/ABA if correctly decoded. The card is blank. Only occurs if all tracks decode without error and without data.
Return Value String representing device configuration getDeviceType Retrieves device type - public int getDeviceType() Parameters Return Value Device type: MagTekSCRA.DEVICE_TYPE_NONE MagTekSCRA.DEVICE_TYPE_AUDIO MagTekSCRA.DEVICE_TYPE_BLUETOOTH getEncryptionStatus Retrieves encryption status. This two byte Binary field contains the Encryption Status. The Reader Encryption Status is sent in big endian byte order. Byte 1 is the least significant byte. Byte 1 LSB is status bit 0.
getFirmware Retrieves firmware version - public String getFirmware() Parameters Return Value String representing firmware version getMagTekDeviceSerial Retrieves MagTek device serial number - public String getMagTekDeviceSerial() Parameters Return Value String representing MagTek device serial number getPANHashSHA1 Retrieves SHA 1 hash of PAN and salt - public String getPANHashSHA1 () Parameters Return Value String representing SHA 1 hash of PAN getPANHashSHA256 Retrieves SHA 256 hash of PAN and salt - p
Parameters Return Value String representing response data getResponseType Retrieves response type - public String getResponseType() Parameters Return Value String representing response type. For Audio Reader, always “C101”.
track data length value for the track that has the error will be set to zero and no valid track data will be supplied. - public String getTrackDecodeStatus() Parameters Return Value Track Decode Status. Consists of three 2-byte hex values representing the decode status for tracks 1, 2, and 3 (respectively from left to right).
SDK Version setConfigurationParams Sets configuration parameters - public void setConfigurationParams(String lpstrParams) Parameters lpstrParams PAN_MOD10_CHECKDIGIT = TRUE/FALSE (default is TRUE) setConfiguration Sets configuration parameters from server. The method will throw an exception if there is a problem with setting configuration parameters.
-public void setConfigurationXML(String lpstrXML)throws MTSCRAException Parameters lpstrXML XML data received from the configuration server getConfigurationXML Retrieves the configuration parameters from the server as an XML data. The method will throw an exception if there is a problem with retrieving the configuration XML.
Parameters lpiReaderType Type of reader. The type of reader is assigned an integer value starting at 1. lpDeviceInfo SCRAConfigurationDeviceInfo object. This object will be used as a search criteria if provided. Currently we recommend the usage of Model number only. If this is set to null, SDK will perform the search based on the model number. lpstrAddress Address of the remote configuration server. Please refer to the sample code for details lpTimeout Timeout specified for connecting to the server.
SECTION 2. CODE EXAMPLES Open Device: if (! mMTSCRA.isDeviceConnected()) { mMTSCRA.setDeviceType(mMTSCRA.DEVICE_TYPE_BLUETOOTH); mMTSCRA.setDeviceID("00:06:66:44:C8:2C"); mMTSCRA.openDevice(); } Close Device: if (mMTSCRA != null) mMTSCRA.
Get Tracks Data From Reader: private class SCRAHandlerCallback implements Callback { public boolean handleMessage(Message msg) { switch (msg.what) { case MagTekSCRA.DEVICE_MESSAGE_STATE_CHANGE: { switch (msg.arg1) { case MagTekSCRA.DEVICE_STATE_CONNECTED: { } break; case MagTekSCRA.DEVICE_STATE_CONNECTING: { } break; case MagTekSCRA.DEVICE_STATE_DISCONNECTED: { } break; } } break; case MagTekSCRA.DEVICE_MESSAGE_DATA_CHANGE: if (msg.obj != null) { mStringCardDataBuffer = (String)msg.
