Payment-app developers who need to fast-track the integration of ID TECH card readers into their POS (or other) systems can make headway quickly by taking advantage of ID TECH’s Universal SDK. The SDK provides libraries (and a common API) for manipulating all of ID TECH’s current-production card readers, including chip-card (EMV), magstripe (MSR), and contactless readers, in a number of languages (such as C# for Windows, Java for Android, Swift for iOS, and C for Linux).
You don’t actually need to install the SDK, however, to run the associated demo program, a standalone app that we call the Universal Demo, or UDemo (for short). You can get the UDemo (standalone version for Windows) by going here.
We recommend that all of our developer-customers become familiar with the UDemo app, because it illustrates (in detail) what the raw requests and responses (to and from the device) look like, allows you to configure a device with particular settings, and provides a playground where developers can easily test various commands using various argument values, in real time. UDemo is also a great way to learn more about EMV, too.
After you run the UDemo installer, launch the app. You’ll see a window similar to the following:
Bear in mind, you can plug any supported ID TECH card reader into your computer’s USB port, at any time, and it will automatically be detected by UDemo. Upon device recognition, the command tree (see “COMMANDS,” above) will populate with commands specific to the device in question (showing, for example, a “CTLS” group if the device supports Contactless interactions, “EMV” if the device supports contact-EMV chip card transactions, and so on).
The basic usage idiom is:
- Plug a device in.
- Navigate the command tree until you find a command of interest.
- Double-click the command in the tree, OR single-click the green Execute Command button at the bottom of the window.
- Check the Log pane to see what the requests and responses were. (Values sent to the device are denoted by “OUT,” while values received from the device are denoted by “IN.”)
- Check the Results pane (on the right) to see the plain-English explanation of what happened.
In the screen shot above, the Start EMV Transaction command was run (against an ID TECH VP3300 card reader) using the default transaction amount of $1.00. The actual command that was run is shown at the top of the Log. Four “IN” responses were received from the device. The first response was an ACK, and the next two “IN” responses contain status info representing LCD messages (like “Processing…”) which might have to be displayed on a POS while the transaction is running. The fourth and final IN contains a block of TLV (tag-length-value) data returned by the reader. Some of the TLV parsings are shown in the Result pane.
UDemo is a highly interactive tool that’s best learned by using it. To get up the learning curve a little quicker, you might want to be aware of the following:
- Many commands take argument values, or can be configured in some way before running them. Just single-click a command in the Commands list. If the command in question can take extra values, appropriate form fields will appear automatically just above the Log pane. Supply any values that might be required, then double-click the command to run it with those values.
- The virtual keypad on the upper right becomes active when the card that’s inserted in the reader requires PIN entry as one of its Cardholder Verification Methods.
- Just above the Command listing is a button labeled Decryption. Click this button to bring up a dialog that allows you to decrypt transaction data.
- Below the Log pane, you’ll find a Start Capture to Disk button (along with a Clear Logs button and Email Logs to Support). The Start Capture button is useful when you want to capture a session’s data for later analysis. You can even e-mail us your results (with the Email Logs button), if you decide you need to open a Tech Support case.
Before Running an EMV Transaction
Of course, UDemo is just a testing tool and is not capable of actually charging a (real, live) transaction against a credit card, but it will simulate all three phases (Start, Authenticate, and Completion) of a contact EMV session. However, before you can run transaction commands, the card reader will need to undergo at least a few configurations. (Otherwise, the simulation will fail.)
You can configure a device quickly (with reasonable defaults) by running three commands:
- First, under the AID node of the command tree, find Load Default AID and run it. This is actually a batch operation that will load half a dozen common AIDs into the device. Allow ten seconds or so.
- Next, under the CAPK node of the command tree, find the Load Default CAPK command and run it. This, again, is a batch command that will take a few seconds. It loads public keys for various card brands, to be used in validating the cryptographic artifacts produced by a chip card at transaction time. (CAUTION: The keys are for testing only and are not meant to be used in production. Obtain production keys from your gateway or payment processor.)
- Finally, under the Terminal Config node of the command tree, find and run Save Terminal Data. This will load resosnable default TLVs for the reader, to support various terminal capabilities.
Once you’ve run these commands, the card reader will contain appropriate default data, and commands like Start Transaction should work without errors.
For More Information
Obviously, there’s a lot going on in the UDemo app; too much to describe here. The best way to get more information? Look at the lower left corner of the UDemo screen (refer to the graphic above) and find the pink Documentation button. If you click that button, a PDF will open in Acrobat Reader (assuming you have it on your machine), showing the Quick Start Guide for UDemo.
To understand what all the hex bytes shown in UDemo mean, you’ll probably want to obtain the low-level (firmware) API guide for your reader. You can usually get this straight from the Downloads section of our public Knowledge Base (no registration required), but some docs are available on request (only), in which case you can reach out to your ID TECH representative, and the appropriate doc(s) will be provided free of charge.