This document provides instructions for software developers who want to create software solutions that include a MagTek Secure Card Reader Authenticator (SCRA) device connected to an Android device via the Audio/Headset Interface, Bluetooth, Bluetooth LE, or USB.

About the MagTek SCRA Demo

The MagTek SCRA Demo, available from MagTek, provides demonstration source code and a reusable MTSCRA library that provides developers of custom software solutions with an easy-to-use interface for Dynamag, DynaMAX, eDynamo, uDynamo, aDynamo, BulleT, mDynamo, DynaWave, tDynamo, iDynamo 6, DynaGlass, and iDynamo 5 (Gen III) readers. Developers can include the MTSCRA library in custom branded software which can be distributed to customers or distributed internally as part of an enterprise solution.

Nomenclature

The general terms “device” and “host” are used in different, often incompatible ways in a multitude of specifications and contexts. For example “host” may have different meanings in the context of USB communication than it does in the context of networked financial transaction processing. In this document, “device” and “host” are used strictly as follows:

• Device refers to the reader device that receives and responds to the command set specified in this document.

• Host refers to the piece of general-purpose electronic equipment the device is connected or paired to, which can send data to and receive data from the device. Host types include PC, laptops, tablets, smartphones, and even test harnesses. In many cases the host may have custom software installed on it that communicates with the device. When “host” must be used differently, it is qualified as something specific, such as “USB host.”

Development Environment: Eclipse 4.3 and above or Android Studio 3 and above.

Android Operating System: 4.4.2 and above

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

Copyright © 2006-2025 MagTek, Inc. Printed in the United States of America

Information in this publication is subject to change without notice and may contain technical inaccuracies or graphical discrepancies. Changes or improvements made to this product will be updated in the next publication release. 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. MagneSafe® is a registered trademark of MagTek, Inc. iDynamo™, and uDynamo are trademarks of MagTek, Inc.

eDynamo™, Dynamag, and DynaMAX are trademarks of MagTek, Inc. DynaGlass™ is a trademark 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.

Android™ is a registered trademark of Google Inc.

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 product names are the property of their respective owners.

Table 0-1 – Revisions

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 ADDRESS ON THE FRONT PAGE OF THIS DOCUMENT, 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 PART EXCEPT AS EXPRESSLY PROVIDED IN THIS AGREEMENT. Licensee

may not decompile, disassemble, or in any other manner attempt to reverse 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 the prior written authorization of the Licensor. 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 of the Software. The Licensor also reserves the right to terminate 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 of returned Software by the Licensor shall mark the termination.

LIMITED WARRANTY: Licensor warrants to the Licensee that the disk(s) or other media on which the Software is recorded are free from defects in material or workmanship under normal use.

THE SOFTWARE IS PROVIDED AS IS. LICENSOR MAKES NO OTHER 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 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE, OR INABILITY TO USE, THE SOFTWARE. Licensee’s sole remedy in

the event of a defect in material or workmanship is expressly limited to replacement of the Software 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 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 WRITTEN COMMUNICATIONS BETWEEN LICENSOR AND LICENSEE OR THEIR ASSIGNS RELATING TO THE SUBJECT MATTER OF THIS AGREEMENT.

QUESTIONS REGARDING THIS AGREEMENT SHOULD BE ADDRESSED IN WRITING TO MAGTEK, INCORPORATED, ATTENTION: CUSTOMER SUPPORT, AT THE ADDRESS LISTED IN THIS DOCUMENT, OR E-MAILED TO

To add the MTSCRA library to a custom software project in the Eclipse development environment, follow these steps:

1. Create or open your custom software project in Eclipse.

2. Copy the following JAR file to the libs subfolder of your software project: mtscra.jar

getDeviceName

Get device model name.

public String getDeviceName()

Parameters: None

Return Value:

Return device model name.

clearBuffers

Clears buffered data retrieved from the reader.

public void clearBuffers() Parameters: None

Return Value: None

getBatteryLevel

Retrieves battery level.

public long getBatteryLevel()

Parameters: None

Return Value:

Battery Level (0 to 100)

Retrieves swipe count.

Parameters: None

Return Value:

Long value representing swipe count.

Retrieves MagnePrint capabilities.

Parameters: None

Return Value:

String representing MagnePrint capabilities:

• 0 = No MagnePrint,

• 1 = Short MagnePrint,

• 2 = Long MagnePrint

Retrieves MagnePrint Encryption capabilities.

Parameters: None Return Value:

String representing MagnePrint Encryption capabilities:

• 0 = No Encryption,

• 1 = Same as MagStripe (8122), other values TBD.

• If absent, default value is 1.

Retrieves MagneSafe 2.0 Encryption capabilities.

Parameters: None

Return Value:

String representing MagneSafe 2.0 Encryption capabilities. 0 = Not supported, other values TBD.

Retrieves MagneStripe Encryption capabilities.

Parameters: None

Return Value:

String representing MagStripe Encryption capabilities. 0 = No Encryption, 1 = TDES DUKPT / PIN Variant, other values TBD

Retrieves MSR capabilities.

Return Value:

String representing MSR capabilities. 0 = No MSR, 1 = MSR.

Retrieves Track capabilities.

Parameters: None 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.

getCardDataCRC

Retrieves CRC from card data.

public long getCardDataCRC()

Parameters: None

Return Value:

Card data CRC

getCardExpDate

Retrieves card experiation date from card data.

public String getCardExpDate() Parameters: None

Return Value:

String representing card expiration date.

getCardIIN

Retrieves Issuer Identification Number (IIN) from card data.

public String getCardIIN()

Parameters: None

Return Value: String representing card IIN.

Retrieves Last 4 digits of card number from card data.

Return Value:

String representing card last 4 digits.

Retrieves card name from card data. public

Return Value:

String representing card name.

Retrieves PAN from card data.

Return Value:

String representing card PAN.

Retrieves PAN length from card data.

Return Value:

PAN length

Retrieves Service Code.

Parameters: None Return Value:

String representing service code.

Retrieves Card Status.

Parameters: None

Return Value:

String representing card status.

This one-byte value indicates the type of encoding that was found on the card. The following table defines the possible values.

Parameters: None Return Value:

Custom software can use the sendCommandToDevice method to send direct commands to the device. This section provides information about commonly used commands.

Discovery

To send a command to device, use:

public void sendCommandToDevice(String command)

Parameters: Use “C10206C20503840900” as command string for audio readers.

Return Value:

The following device information will be retrieved.

• Device SN, internal: Device serial number created by chip manufacturer. Use getDeviceSerial method to retrieve data.

• Device SN, MagTek: Device serial number created by MagTek. Use getDeviceSerialMagTek method to retrieve data.

• Device Firmware Part Number: Device firmware part number. Use getFirmware method to retrieve data.

• Device Model Name: Device model name. Use getDeviceName method to retrieve data. Device TLV Version: Device TLV version. Use getTLVVersion method to retrieve data.

• Device Part Number: Device part number. Use getDevicePartNumber method to retrieve data. Capability - MSR: 0 = No MSR, 1 = MSR. Use getCapMSR method to retrieve data.

Capability - TRACKS:

• 0 = Supported tracks: None.

• 1 = Supported tracks: Track1.

• 2 = Supported tracks: Track2.

• 3 = Supported tracks: Track1, Track2.

Use getCapTracks method to retrieve data.

Capability - MagStripe Encryption:

• 0 = No Encryption,

• 1 = TripDES DUKPT.

Use: getCapMagStripeEncryption method to retrieve data.

This class provides methods to retrieve configuration parameters from the server.

getConfigurationXML

This method 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.

public String getConfigurationXML( 
    String username, 
    String password, 
    int readerType, 
    SCRAConfigurationDeviceInfo deviceInfo, 
    String address, 
    int timeout) throws MTSCRAException

Parameters:

Return Value:

String value of the configuration parameters retrieved from the server.

This method retrieves the configuration parameters from XML data as a ProcessMessageResponse object. The method will throw an exception if there is a problem with retrieving the configuration XML.

Parameters:

Return Value:

ProcessMessageResponse containing the configuration parameters.

This method 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:

Return Value:

String value of the configuration parameters for the specified device model.

After creating an instance of the MTSCRA class in your custom software project, use the methods described in this section to communicate with SCRA device.

This method sets the connection type of the device.

Parameters:

requestCardSwipe

Request the device to display a message for swiping a card.

public int requestSwipeCard( 
        byte waitTime, 
        byte messageID, 
        byte beepCount)

Parameters:

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

This function requests the device to send MSR data after calling requestCardSwipe().

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

Request PIN entry by the cardholder.

Parameters:

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

Request the card holder to enter card data manually.

Parameters:

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

Request the card holder to sign on the screen.

Parameters:

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

Request the card holder signature from the device. To be used after calling requestSignature().

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

Request the card holder to enter text for encryption.

Parameters:

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

Request the encrypted input data from the device. To be used after calling requestEncryptedInputData().

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

Request to cancel a command or request while the device is waiting for the card holder.

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

getTrack2

Get stored track2 data. This field contains the encrypted track data for track 2.

public String getTrack2()

Parameters: None

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: None

Return Value:

Return stored track3 data string.

getTrack1Masked

Get stored masked track1 data.

Parameters: None Return Value:

Return stored masked track1 data string.

For an ISO/ABA card, the PAN is masked as follows:

• The specified number of initial characters is sent unmasked. The specified number of trailing characters is 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. If the Mod 10 correction is not specified, all of the intermediate characters of the PAN are set to the specified mask character.

• The Card Holder’s name and the Expiration Date are transmitted unmasked.

• All Field Separators are sent unmasked.

For an AAMVA card, the specified mask character is substituted for each of the characters read from the card.

Get stored masked track2 data.

Parameters: None

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. If the Mod 10 correction is not specified, all of the intermediate characters of the PAN are set to the specified mask character.

• The Expiration Date is transmitted unmasked.

• All Field Separators are sent unmasked.

For an AAMVA card, the DL/ID# 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 DL/ID#PAN are set to zero; one of them will be set such that last digit of the DL/ID# calculates an accurate Mod 10 check of the rest of the DL/ID# as transmitted. If the Mod 10 correction is not specified, all of the intermediate characters of the DL/ID# are set to the specified mask character.

• The Expiration Date and Birth Date are transmitted unmasked.

• All other characters are set to the specified mask character.

Get stored masked track3 data.

Parameters: None

Return Value:

Return stored masked track3 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. If the Mod 10 correction is not specified, all of the intermediate characters of the PAN are set to the specified mask character.

• All Field Separators are sent unmasked.

• All other characters are set to the specified mask character.

For an AAMVA card, the specified mask character is substituted for each of the characters read from the card.

Not supported on aDynamo. 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.

Parameters: None

Return Value:

String containing the MagnePrint data.

Not supported on aDynamo. Get the card MagnePrint status. For more information, see D9875475

Parameters: None

Return Value:

String containing the MagnePrint status.

This Binary field represents 32 bits of MagnePrint status information. Each character represents 4 bits (hexadecimal notation). For example, suppose the characters are: “A1050000”:

Usage Legend:

• D = Direction

• F = Too Fast

• L = Too Slow

• M = MagnePrint capable

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. MagnePrint status is defined as follows:

• Bit 0 = MagnePrint-capable product (usage M)

• Bits 1-15 = Product revision & mode (usage R)

• Bit 16 = STATUS-only state (usage S)

If the Enable/Disable MagnePrint property is set to disable MagnePrint, this field will not be sent.

Get stored device serial number. This 16-byte ASCII field contains the device serial number. The device serial number is a NUL (zero) terminated string. So the maximum length of the device serial number, not including the null terminator, is 15 bytes. This device serial number can also be retrieved and set with the device serial number property explained in the property section of this document. This field is stored in non-volatile memory, so it will persist when the unit is power cycled.

Parameters: None

Return Value:

Return stored device serial number.

Not suported on aDynamo. 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. To avoid replay, the application sets the Session ID property before a transaction and verifies that the Encrypted Session ID returned with card data decrypts to the value set.

public String getSessionID()

Parameters: None

Return Value:

Returns a string containing the session id.

Get stored key serial number. This 10-byte Binary field contains the DUKPT Key Serial Number used to encrypt the encrypted fields in this message. This 80-bit field includes the Initial Key Serial Number in the leftmost 59 bits and a value for the Encryption Counter in the rightmost 21 bits. If no keys are loaded, all bytes will have the value 0x00.

public String getKSN()

Parameters: None

Return Value:

Return stored key serial number.

OnDeviceConnectionStateChanged

This message occurs when the state of the device is changed.

OnCardDataStateChanged

This message occurs when the state of the card information is changed.

This message occurs when card information is received from the device.

This message occurs when a response is received from the device.

This message occurs when transaction status update is received from the EMV device.

This message occurs when the EMV device has display message to present to the user.

This message occurs when the EMV device has user selection message to present to the user.

This message occurs when ARQC is received from the EMV device.

This message occurs when transaction result is received from the EMV device.

This message occurs when an EMV command result is received from the EMV device.

Result Code Description

• 0x0000 = Success 0x0001 = Failure

• 0x0381 = Failure, DUKPT scheme is not loaded

• 0x0382 = Failure, DUKPT scheme is loaded but all of its keys have been used

getTrackDecodeStatus

Retrieves track decode status. This is a one-byte value, which indicates the status of decoding track 1. Bit position zero indicates if there was an error decoding track 1 if the bit is set to one. If it is zero, then no error occurred. If a track has data on it that is not noise, and it is not decodable, then a decode error is indicated. If a decode error is indicated, the corresponding 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: None 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). Values are:

• 00 = Track OK

• 01 = Track read Error

• 02 = Track is Blank

Retrieves SDK version.

Parameters: None

Return Value:

The version information of the SDK.

Send command to device.

Parameters:

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

This function starts an EMV L2 transaction.

Parameters:

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

This function sets the user selection result. It should be called after receiving the OnUserSelectRequest event which is triggered after the user makes a selection.

Parameters:

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

This function informs EMV device to process transaction decision from acquirer.

Parameters:

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

This function cancels a transaction while waiting for the user to insert a card.

Parameters: None Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

Send extended command to device.

Parameters:

Return Value:

• 0 = Success

• 9 = Error

• 15 = Busy

Retrieves features for the device.

Parameters: None

Return Value:

Retrieves power management value for the device.

Parameters: None

Return Value: Returns the PM value associated with the device.

Operation Status

Result Code Description

• 0x0000 = Success 0x0001 = Failure

• 0x0381 = Failure, DUKPT scheme is not loaded

• 0x0382 = Failure, DUKPT scheme is loaded but all of its keys have been used

public class MTBankingEvent

{

}

OnDeviceExtendedResponse (EMV Device Only)

This message occurs when an extended response is received from the device.

OnDeviceState (EMV Device Only)

This message occurs when the device changes state.

The bits of Session State mean the following:

• Pwr Chg:

  • 1 = Power Change Occurred (occurs on Power up or after a USB resume)

• Card Data:

• 0 = Certificate does not exist in the device

• 1 = Certificate exists in the device

This message occurs when the card status has changed.

This message occurs when the device sends card data.

This message occurs when the device sends the response to a PIN request.

This message occurs when the signature state has change.

This message occurs when the device sends the response to a signature request.

This message occurs when the encrypted data state has changed.

This message occurs when the device returns encrypted data.