Getting Started with ID TECH’s Universal SDK

One of the nice things about choosing a credit card reader made by ID TECH is that integration of the device into a POS or payment-app environment can happen quickly and painlessly via a single Software Development Kit, which we call the Universal SDK. It’s “universal” in that it exposes a common API across all supported ID TECH products, and works the same way regardless of environment.

Having said that, it’s important to recognize that ID TECH’s Universal SDK comes in several flavors, depending on what kind of operating system you intend to deploy the device into, and the specific programming language you want to use. A C#-based (.NET Framework) Universal SDK is available to support most ID TECH products on Windows, but if you need to support, say, one of our Bluetooth VP3300 readers using a Samsung phone, there’s a Java-based Android version of the Universal SDK for that. If you need to integrate to Linux, we have a C++ Universal SDK for that (with an optional Java version as well). Some of our mobile readers work with iPads or iPhones, so of course there’s an iOS Universal SDK as well (which allows you to program in Swift or Objective-C). And yes, we support Raspberry Pi (with C and Java).

Unlike some of our competitors, ID TECH charges no money for its SDKs and doesn’t require you to join a “developer program.” In fact, you can obtain most developer tools (and documentation) without even registering for access. All you have to do is go to our Knowledge Base, select a product family, and drill into the relevant Product Page to find SDK links. (For example, check out the VP3300 Product Page. Scroll down to “SDKs.”)

What’s in the SDK? When you unpack the Zip archive,  you’ll find four folders:

  • Demo — This folder contains already-built executables corresponding to the sample-code projects provided in the SourceCode folder. There will be two executables: one (called Simple Demo) representing the very basic “tutorial” demo app described in the documentation, and a second, more elaborate app that (at least in the case of the Windows SDK) has a look and feel similar to the UDemo utility I wrote about in an earlier post.
  • Docs — SDK documentation comes in two forms: HTML, and PDF. Each has an extensive description of the APIs, usage examples, background info, a tutorial walk-through, and more.
  • SDK — Here, you’ll find the compiled libraries and other resources needed to support a running app on the platform in question. For Windows machines, expect to find DLLs. For MacOS, expect .dylib files; for Android, a JAR file.
  • SourceCode — This folder contains header files. project files, and source code for the Simple Demo (tutorial) app, plus source code for a more elaborate sample app that shows off more advanced functionality. Again, what you get depends on what operating system you’re using. Source code for Linux is in C and Java. For Windows, depending on the exact SDK you download, you can expect C# or C++ code. For Android, it’s Java. For iOS, you have your choice of Objective-C or Swift.
The Simple Demo app (provided with the Universal SDK, in source code form as well as prebuilt) shows how the SDK can be used to accomplish a number of common configuration and transaction-related tasks. Raw serial data can be seen in the log pane.

The SDK libraries take care of device connectivity on a platform-by-platform (and product-by-product) basis, so you don’t have to worry about low-level details of connecting to the card reader via RS-232, USB, Bluetooth, or audio jack (in the case of mobile devices). The libraries take care of product-specific communication protocol issues and shield you from having to deal directly with firmware-level commands. So, for example, if you were interested in querying your ViVOpay VP3300 for its firmware version, normally, without the SDK, you would need to send a raw byte stream corresponding to the hex sequence 5669564f74656368320029000000dea0, over the serial port, and wait for a response of something like:

5669564f7465636832002900000d4e454f2076312e30312e3033373d79

Then you’d have to know how to verify the CRC on the end of the response, parse out the data payload from the framing bytes, convert the payload to an ASCII string, etc. With the Universal SDK, you merely need to call the API method device_getFirmwareVersion(), then inspect the string that comes back. The SDK takes care of the gritty details of marshalling and unmarshalling data, calculating CRCs, writing and reading serial-port buffers, etc.

The Universal SDK greatly simplifies carrying out transactions (whether magstripe, contact EMV, or contactless), because convenience methods exist for parsing TLV data (and/or MSR data), interpreting status codes, and customizing device behaviors. The Universal SDK lets you code at a fairly high abstraction level so that you don’t get bogged down in data protocols, parsing routines, error-code lookup tables, and other low-level details, yourself.

Is there anything the Universal SDK doesn’t do? Well, it doesn’t contain business logic: That part’s up to you. It’s also not gateway- or processor-aware; the major payment processors all have their own SDKs for accessing the online authorization host. Which means you’ll need to use the SDK recommended by your gateway in order to go online for authorization (or settlement, etc.) at the appropriate time.

Is it possible to build a payment app (including integration with an ID TECH card reader) without using the Universal SDK? It is, actually. And some of ID TECH’s customers (who often need to integrate with hardware from a variety of providers, but don’t want to use six different SDKs to do it) do go that route. But remember, it means you need to:

  1. Create your own connectivity code (your own special driver, in essence) for talking to the device over USB, COM, Bluetooth, or whatever it happens to be.
  2. Understand the firmware commands needed for controlling the device. (ID TECH makes this information available in its documentation for various products.)
  3. Handle the packaging and unpackaging of data, and commands, according to the protocol requirements of the device (NGA, ITP, ViVOtech2, or whatever applies).
  4. Handle data parsing yourself.
  5. Interpret status codes and error codes yourself.
  6. Do all this in a way that’s tailored to the specific hardware and operating system requirements of the platform you’re targeting.

Is there any advantage to going the no-SDK route? Only this: Since you’re dealing with raw bytes, direct communication with the device is basically programming-language-independent. It no longer matters which language you use, as long as you can talk to the serial port (or USB port, etc.) natively. So if you’re accustomed to programming in Pascal, or Go, or Kotlin (or a language that’s not currently supported by the Universal SDK), you can still get the job done, albeit not as easily.

What’s the best way to get started with the Universal SDK? That’s easy: Download it and read the documentation! Go to the Knowledge Base link shown further above, and you can be coding this afternoon. In the meantime, if you’re new to EMV, you might want to start by taking a look at our white paper on EMV Transactions with the Universal SDK, which gives a recap of EMV (chip-card transactions) in addition to laying out an introduction to the USDK itself.

Device-Resident Applications

What about hosting a payment app on the device itself? Is that possible? Actually, for some of ID TECH’s newer devices (e.g., VP5300 insert readers and the VP6800, among others), it is, in fact, possible to host your app on the device itself. You’ll need to be familiar with writing embedded apps for real-time operating systems (and/or Linux), in ANSI C, but yes, it’s possible, and yes, there’s a special device-resident set of convenience libraries, known as ADF (which stands for Application Development Framework), dedicated specifically to making it possible for your app to live on the device.

Have questions about the Universal SDK (or the ADF)? Talk to one of our in-house experts. Get in touch with us at 1-800-984-1010. We’d love to hear from you!

Related Posts

Comments (2)

Great post. 🙂

Hey thanks!

Leave a comment

You must be logged in to post a comment.