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.
ExpressCard 2000 is a trademark of MagTek, Inc.
Microsoft® and Windows® are registered trademarks of Microsoft Corporation.
All other system names and product names are the property of their respective owners.
This product has been evaluated by multiple safety certification agencies, including
Underwriters Laboratories (UL) and the United States Federal Communications
Commission (FCC Class A and Class B), and is designed to protect both the user and the
device. This document is written specifically to work in conjunction with these safety and
integrity features to protect the user and the device. It is very important to follow all steps
in the product documentation carefully, in the order in which they are described, and at
the recommended times. Failure to do so could result in personal injury, and / or cause
damage to the device, and / or void the product warranty.
SAFETY REQUIREMENTS
Caution: Never do any of the following:
DO NOT use a ground adapter plug to connect equipment to a power receptacle that lacks a ground
connection terminal.
DO NOT attempt any maintenance procedure that is not specifically described in this manual or any
other MagTek ExpressCard 2000 manual.
DO NOT remove any of the covers or guards that are fastened with screws. There are no operator-
serviceable areas within these covers.
DO NOT override or “cheat” electrical or mechanical interlock devices.
DO NOT use supplies or cleaning materials for other than their intended purposes.
DO NOT operate the device if you or anyone else has noticed unusual noises or odors.
Consider the following before operating the ExpressCard 2000:
Connect equipment to a properly grounded power source receptacle. If in doubt, have the receptacle
checked by a qualified electrician. Improper connection of the equipment’s grounding conductor
creates a risk of electric shock.
Only place the device on a solid surface that can safely support the device’s weight.
Be careful when moving or relocating the device. Use proper lifting techniques.
Use materials and supplies specifically designed for MagTek equipment. Using unsuitable materials
can cause poor performance, and in some cases may be hazardous, cause damage, and / or void the
device’s warranty.
This manual is for programmers who wish to develop custom card personalization software that can
communicate with ExpressCard 2000 (EC2000) devices. It begins with an introduction to the EC2000
device and supporting software architecture, then provides syntax for available operations.
1.1 Product Summary
ExpressCard 2000 (EC2000) is a compact instant-issuance card personalization device (CPD) that can
securely, fully personalize any CR80-sized credit, debit, ATM, gift, loyalty, or membership card in as
little as 90 seconds.
ExpressCard 2000 is supported by QwickCards.com and a wide range of third-party software solutions,
creating a complete, secure instant issuance system for distributed locations that can be maintained and
controlled centrally. With the feature-rich solution offered by EC2000, financial institutions will be able
to meet current market needs and also support new card issuance trends, including smart cards,
contactless cards, flat cards, and photo cards.
EC2000 uses the security of MagTek’s advanced MagneSafe™ Security Architecture, and MagnePrint®
card authentication technology for magstripe encoding. ExpressCard 2000’s physical and logical security
features exceed compliance requirements for instant issuance published by Visa® and MasterCard®.
EC2000’s MagnePrint Reference Capture Module captures and registers each card’s unique MagnePrint®
signature as it is issued. This registered signature can then be used to protect legitimate cardholders by
validating that the card being used at an ATM, teller window, home banking, or POS location is
authentic, not a counterfeit copy.
Product features include:
Touchscreen LCD display
Seven card stock hoppers (100 cards per hopper)
Manual feed slot (single card processing)
Magstripe encoding with MagnePrint® card authentication technology
smart card encoding (contact only)
Full-color image printing (two-sided)
Embossing
Foil tipping
Rear indent printing
Ethernet interface
Secure enclosure with key or touchscreen unlock
Physical and logical security features that exceed compliance requirements for instant issuance
published by Visa® and MasterCard®.
Card issuance supported by QwickCards.com and third-party solutions
Card issuance supported from third-party software using XML key-value pairs
For detailed information about the EC2000 device from the user perspective, see the ExpressCard 2000
User Installation and Operation Manual, available from MagTek.
This file contains a list of default ExpressCard
connections and IP addresses. This file is required
by mtecsdk.dll.
1.2 About Communicating With EC2000
EC2000 is a networked device which receives transactions from card personalization software in the form
of HTTPS requests sent to specific URLs in its internal web server, using XML formatted according to a
specification developed by MagTek. Developers of card personalization software have two options for
generating these HTTPS requests in their custom software:
They can construct XML and send HTTPS requests directly.
They can use the MagTek ExpressCard SDK provided in mtecsdk.dll.
Both options provide the same set of features, and from the device’s perspective both methods are
practically identical, apart from possible deviations in the exact XML format and content. The advantage
of using the ExpressCard SDK is that it abstracts implementation details, such as the physical connection
to the device and the creation and structure of the transaction XML. This abstraction can reduce the
overall maintenance cost of custom card personalization software.
This document serves primarily as a reference for the second method (constructing requests using the
MagTek ExpressCard Windows SDK), which requires 33090060 ExpressCard Software Development
Kit, available from MagTek. For information about sending XML requests directly, see 99875611
ExpressCard 2000 Programmer’s Reference (XML), available from MagTek.
1.3 About mtecsdk.dll
mtecsdk.dll provides a high-level API to communicate with the device. It completely encapsulates
calls to msxml4.dll to convert transactions into XML, as well as calls to wininet.dll for network
communication. mtecsdk.dll also provides functions to convert the XML responses from the device
into key-value pairs that can be easily retrieved without parsing the XML.
1.4 How to Use the ExpressCard SDK in Software Projects
To use the ExpressCard SDK in a custom software project, follow these steps:
1) Download 33090060 ExpressCard Software Development Kit (SDK), available from MagTek.
2) Run the setup program to install the SDK on your development workstation, noting the full
installation directory path. By default, the SDK installs to C:\Program Files (x86)\MagTek\ExpressCard (SDK) Demo, and supporting files install to various other Windows
library locations.
3) Ensure the files listed in Table 1-1 have successfully been copied to the specified locations.
4) Create or open your custom software project in Visual Studio.
5) If your chosen programming language links using .h files, include mtecsdk.h located in the root
installation location of the ExpressCard SDK.
6) If your chosen programming language links using .lib files, include mtecsdk.lib located in the root
installation location of the Expresscard SDK.
7) If your chosen programming language links directly to .dll files, include mtecsdk.dll located in
C:\Windows\SysWOW64 on 64-bit workstations or C:\Windows \System32 on 32-bit workstations.
Win32 API for Internet Protocols. This file is
provided by Microsoft.
msxml4.dll
C:\Windows\System32
MSXML XML parser. ActiveX Object for XML
API . This file is installed with the installation of
ExpressCard 1000 API.
1.5 How to Set Up the ExpressCard SDK for Runtime
To set up the ExpressCard SDK for runtime use with the ExpressCard Demo software or any custom
software, follow these steps on the host where the software is installed:
1) Install the ExpressCard SDK by following the steps in section 1.4 How to Use the ExpressCard
SDK.
2) Determine the IP address of the device you want to connect to. For details, see the Configuration
section of 99875600 ExpressCard 2000 User Installation and Operation Manual. Alternatively,
if the device is registered with a DNS server, you can use the device’s registered IP name.
3) Ping the device from a command prompt to make sure there is a network route from the workstation
to the device.
4) Launch Notepad from the Windows Start menu in administrator mode by right-clicking its shortcut
and selecting Run as administrator.
5) Open C:\Windows\mtecsdk.ini in Notepad.
6) Edit the ConnectionString= line to change the IP address in the sections for both [DEVICE1] and
[DEVICE2], then save and close the file. If you can not save your changes, double-check that you
have launched Notepad in administrator mode.
8) To connect to the device, select the Create Card tab, select the device you want to connect to in the
Device Name dropdown list, and press the Open Device button. The main text area should report
Device: [Device Name] Opened Successfully (see Figure 1-1).
9) Use the various features in the Demo application to operate the device.
To debug problems with sending transactions to a device, you can use the error logging function of the
ExpressCard Demo GUI software. With this option enabled, all errors returned from the device are
logged into log file named Demo.log in the ExpressCard Demo GUI installation folder.
1.7 How to Send a Transaction
The general sequence of function calls to create and send a transaction that produces a single card is:
1) Find the EC2000 device using MTECSDK_GetDevice.
2) Open the found device by calling using MTECSDK_OpenDevice.
3) Allocate memory to a string buffer that stores the XML to send to the device.
4) Use MTECSDK_SetValue to set each of the key-value pairs that define the card design, including
image files, text lines, magstripe data, embosser data, and so on. The key-value pairs are stored in the
buffer allocated previously.
5) Send the transaction to the device using MTECSDK_ProcessDoc.
6) Examine the return value from MTECSDK_ProcessDoc to determine if an error occurred. The
return values are documented in section 2.7 MTECSDK_ProcessDoc.
7) Examine the results of the transaction returned by the device by calling MTECSDK_GetValue to
retrieve key-value pairs from the transaction information returned in the pcDocInfo buffer passed by
MTECSDK_ProcessDoc, which contains the transaction information and the device’s information.
The full list of return codes can be found in the appendices of 99875611 ExpressCard 2000
Programmer’s Reference (XML).
8) After all transactions have been sent, call MTECSDK_CloseDevice to close the connection to the
After including the ExpressCard SDK in your custom card personalization software project (see section
1.4 How to Use the ExpressCard SDK), use the functions described in the following sections to
communicate with the device. For details about specific XML properties involved in transactions, see
99875611 ExpressCard 2000 Programmer’s Reference (XML).
2.1 MTECSDK_GetDevice
This function returns the name of the EC2000 device configured in mtecsdk.ini. See section 1.5
How to Set Up the ExpressCard SDK for information about that file.
Parameters:
dwDeviceContext - Specifies the device number of the device. This must be set to 1 to get the first device
found on the network. Increment it by 1 to get the name of the next device.
pcDevName - Pointer to the buffer where the device name will be stored.
This function opens a communication channel with the device specified by pcDevName.
ULONG MTECSDK_OpenDevice (
char *pcDevName
);
Parameters:
pcDevName - Pointer to null-terminated string that specifies the name of the device to open. Use
function MTECSDK_GetDevice to obtain the device name.
Return Values:
If the function succeeds, the return value is EC_ST_OK.
Remarks:
If the pcDevName is NULL, the return value is EC_ST_BAD_DEVICE_NAME.
If no device is found, the return value is EC_ST_DEVICE_NOT_FOUND.
If MSXML is not installed, return value is EC_ST_MSXML_NOT_FOUND
If device is found but cannot connect, return value is EC_ST_DEVICE_NOT_RESPONDING
Example:
#define DEVICE_NAME_LEN 128
int i=1;
DWORD dwResult;
char pcDevName[DEVICE_NAME_LEN]="";
while ((dwResult = MTECSDK_GetDevice(i,(char*) pcDevName)) !=
EC_ST_DEVICE_NOT_FOUND)
{
if (MTECSDK_OpenDevice (pcDevName) == EC_ST_OK)
{
///close the device
MTECSDK_CloseDevice (pcDevName);
}
i++;
}
2.3 MTECSDK_SetLogFileHandle
This function specifies a handle to a file where the SDK will log all messages and errors when logging is
enabled using MTECSDK_LogEnable. By default, there is no log file.
while ((dwResult = MTECSDK_GetDevice(i,(char*) cDeviceName)) !=
EC_ST_DEVICE_NOT_FOUND)
{
if (MTECSDK_OpenDevice (cDevicesNames) == EC_ST_OK)
{
//Get timeout
DWORD timeout;
HANDLE fileHandle;
// Create log file and save the handle in fileHandle
// Pass the handle of the log file
MTECSDK_SetLogFileHandle (fileHandle);
///close the device
// Close the log file
// Close the device
}
i++;
}
if (MTECSDK_OpenDevice (cDevicesNames) == EC_ST_OK)
{
// Process documents
///close the device
MTECSDK_CloseDevice (cDeviceName);
}
2.4 MTECSDK_LogEnable
This function enables or disables logging. By default, logging is disabled. To enable logging, set a valid
log file handle using MTECSDK_SetLogFileHandle, then call this function with bEnable = TRUE.
Parameters:
bEnable - Boolean value to enable or disable logging.
Return Values: None.
Remarks: None.
Example:
if (hLogFileHandle != NULL)
{
MTECSDK_LogEnable(TRUE);
MTECSDK_SetLogFileHandle (hLogFileHandle);
}
2.5 MTECSDK_SetValue
This function adds a specified key/value pair to the device settings specified in the pcOptions buffer, in
the section specified by pcSection. Each value can only be set once. After setting key/value pairs to fully
define the transaction to send to the device, call MTECSDK_ProcessDoc to send the whole buffer to the
device.
Process options are stored as key/value pairs in a buffer. The structure of the options follows XML
format. Use function MTECSDK_SetValue to add an option to this structure. Options are string-based
key/value pairs. Each option is stored only once in the buffer.
Parameters:
pcOptions - Pointer to null-terminated string containing all key/value pairs.
pcSection - Pointer to null-terminated string containing the section name.
pcKey - Pointer to null-terminated string containing the key name. To delete the entire pcSection from
the specified pcOptions buffer, set this value to NULL.
pcValue - Pointer to null-terminated string containing the key to set. To delete the specified pcKey from
the specified pcSection, set this value to NULL.
pdwLength - Pointer to a double word that contains the size of the pcOptions buffer. The minimum size
of the buffer should be equal to MTEC_OPTIONS_BUFFER_SIZE.
Remarks:
If the pcOptions buffer is not large enough to add the new key/value pair, the function returns
EC_ST_NOT_ENOUGH_MEMORY, and the required size of the buffer is returned in pdwLength.
If pdwLength is less than the size of the results pcOptions after new key/value pair is added, the functions
returns EC_ST_NOT_ENOUGH_MEMORY.
Example:
char Settings [4096];
DWORD SettingsBufferSize;
// Initialize Settings
// Initialize the Settings variable first
SettingsBufferSize =4096;
// Set a value of “4” to the key “Number” in section “ImageOptions”and
// store this new key/value pair in the buffer” Settings”
dwStatus=MTECSDK_SetValue(Settings, "ImageOptions","Number","4",
&SettingsBufferSize);
2.6 MTECSDK_SetAttribute
This function modifies the pcOptions buffer to set an attribute inside the XML tag specified by pcSection
and pcKey (for example, it can add an id tag of the form <mytag id=5>.
Parameters:
pcOptions - Pointer to null-terminated string buffer containing all key/value pairs.
pcSection - Pointer to null-terminated string containing the section name.
pcKey - Pointer to null-terminated string containing the key name. To remove the whole pcSection from
the pcOptions buffer, set pcKey to NULL.
pcValue - Pointer to null-terminated string containing the attribute value to set.
pdwLength - Pointer to a double word that contains the size of the pcOptions buffer. The minimum size
of the buffer should be equal to MTEC_OPTIONS_BUFFER_SIZE.
If the pcOptions buffer is not large enough to add the new attribute, the function returns
EC_ST_NOT_ENOUGH_MEMORY, and returns the required size of the buffer in pdwLength.
If pdwLength is less than the size of pcOptions after the new attribute is added, the function returns
EC_ST_NOT_ENOUGH_MEMORY.
Example: None
2.7 MTECSDK_ProcessDoc
This function sends a card personalization transaction with the specified options to the device with the
specified name. When the device completes the transaction, the result is returned in pcDocInfo.
For every card personalization transaction, the EC2000 requires a new set of options detailing how the
card will be personalized (image files, text lines, magnetic stripe data, embosser data, and so on). The
options are stored as key-value pairs in the buffer pointed to by pcProcessOptions.
Parameters:
pcDevName - Pointer to a null-terminated string containing device name.
pcProcessOptions - Pointer to a buffer containing the options to be used in processing the card. The
options are stored in the buffer by using function MTECSDK_SetValue.
pcDocInfo - Pointer to the buffer containing the information returned from the device. The returned
information contains Command status, MagnePrint data, Magstripe data, Smartcard data, and Device
status information.
pdwDocInfoSize - Size of the buffer pcDocInfo.
If there is no data returned from device, the return value is EC_ST_PROCESS_DOC_FAILED.
If pcProcessOptions is NULL, the return value is EC_ST_BAD_DATA.
If pcDocInfo is NULL, the return value is EC_ST_BAD_BUFFER.
If the size of returned data is larger than the value specified in pdwDocInfoSize, the return value is
EC_ST_NOT_ENOUGH_MEMORY.
If there is a bad connection with the device, the return value will be one of the following:
EC_ST_CONNECT_REQUEST_TIMEDOUT
EC_ST_REQUEST_TIMEDOUT
EC_ST_DEVICE_NOT_RESPONDING
EC_ST_ERR_INTERNET_CONNECT
EC_ST_ERR_HTTP_OPEN_REQUEST
EC_ST_ERR_HTTP_SEND_REQUEST
Parameters:
pcDocInfo - Buffer pointer containing all the key/value pairs.
pcSection - Pointer to null-terminated string containing the section name.
pcKey - Pointer to null-terminated string containing the key name.
pcValue - Pointer to the buffer that receives the retrieved string.
pdwLength - Specifies the size of the pcValue buffer.
Remarks:
MTECSDK_GetValue finds the key in the pcDocInfo buffer then returns its value in pcValue.
If MTECSDK_GetValue succeeds it returns EC_ST_OK.
If pdwLength is less than the size of the returned value, the function returns
EC_ST_NOT_ENOUGH_MEMORY and returns the required size of the pcValue buffer in pdwLength.
If the key/value pair can not be found, pcValue will be NULL and the function will return
EC_ST_KEY_NOT_FOUND.
// Use function MTECSDK_GetDevice to get
// device name for variable “device”
// Call MTECSDK_ProcessDoc function to process a document.
dwStatus = MTECSDK_ProcessDoc (device, Settings, DocInfo,
&DocInfoSize);
if (dwStatus == MTEC_ST_OK)
{
// Check the return status from the device
valueSize = 1024;
dwStatus=MTECSDK_GetValue(DocInfo, "CommandStatus", "ReturnCode",
cValue, &valueSize);
if (dwStatus != EC_ST_OK)
// error retrieving key value
else
This function reads the buffer specified by pcDocInfo to retrieve an attribute from the XML tag specified
by pcSection and pcKey (for example, it can read the id attribute from the tag <mytag id=5>.
Parameters:
pcDocInfo - Buffer pointer containing all the key/value pairs.
pcSection - Pointer to null-terminated string containing the section name.
pcKey - Pointer to null-terminated string containing the key name.
pcValue - Pointer to the buffer that receives the retrieved string.
pdwLength - Specifies the size of the pcAttribute buffer.
Remarks:
MTECSDK_GetAttribute finds the key in the pcDocInfo buffer then returns its value in pcValue. If the
function succeeds it returns EC_ST_OK.
If pdwLength is less than the size of the returned value, the function returns
EC_ST_NOT_ENOUGH_MEMORY and returns the required size for the pcValue buffer is in the
pdwLength.
If the key/value pair can not be found, pcValue is null and the function returns
EC_ST_KEY_NOT_FOUND.
// Use function MTECSDK_GetDevice to get
// device name for variable “device”
// Call MTECSDK_ProcessDoc function to process a document.
dwStatus = MTECSDK_ProcessDoc (device, Settings, DocInfo,
&DocInfoSize);
if (dwStatus == MTEC_ST_OK)
{
// Check the return status from the device
valueSize = 1024;
dwStatus=MTECSDK_GetValue(DocInfo, "CommandStatus", "ReturnCode",
cValue, &valueSize);
if (dwStatus != EC_ST_OK)
// error retrieving key value
else
{
// do further process
}
}
2.10 MTECSDK_QueryInfo
This function sends a DeviceInformation request to the device specified by pcDevName, and
returns the contents of the section specified by pcSection.
Parameters:
pcDevName - Pointer to null-terminated string containing device name.
pcSection - Pointer to null-terminated string containing the desired section to return from the
DeviceInformation request. Details about DeviceInformation requests can be found in 99875611 ExpressCard 2000 Programmer’s Reference (XML), available from MagTek.
pcSectionData - Pointer to the buffer that is used to store the contents of the requested section.
Remarks:
If the function succeeds it returns EC_ST_OK.
If the device fails to respond, the function returns EC_ST_DEVICE_NOT_RESPONDING.
If the memory allocated for pcSectionData buffer is not large enough to store the data of the inquiry
section, the function returns EC_ST_NOT_ENOUGH_MEMORY.
If there is a bad connection with the device, the return value will be one of the following:
EC_ST_CONNECT_REQUEST_TIMEDOUT
EC_ST_REQUEST_TIMEDOUT
EC_ST_DEVICE_NOT_RESPONDING
EC_ST_ERR_INTERNET_CONNECT
EC_ST_ERR_HTTP_OPEN_REQUEST
EC_ST_ERR_HTTP_SEND_REQUEST
Parameters:
pcDevName - Pointer to null-terminated string containing the name of the device to close. This is the
device that is previously opened using function MTECSDK_OpenDevice.
Remarks:
If the pcDevName is NULL, the return value is EC_ST_BAD_DEVICE_NAME.
Example:
#define DEVICE_NAME_LEN 128
int i=1;
DWORD dwResult;
char pcDevName[DEVICE_NAME_LEN]="";
// Get the device name at device number “i”
while ((dwResult = MTECSDK_GetDevice(i,(char*) pcDevName)) !=
EC_ST_DEVICE_NOT_FOUND)
{
// Success in getting the device name
// Open this device
if (MTECSDK_OpenDevice (pcDevName) == EC_ST_OK)
{
// Now close this device
MTECSDK_CloseDevice (pcDevName);
}
else
{
// Error while opening this device.
}