Skip to main content

Getting Started with the Windows & Linux SDK

Updated

Overview

NMI's Windows & Linux SDK, powered by ChipDNA, enables secure, reliable card-present payments on Windows and Linux systems. Whether you are building attended point-of-sale software, an unattended kiosk, or anything in between, the SDK provides the tools to integrate EMV payments without managing the underlying terminal complexity.

The SDK gives developers a consistent, hardware-abstracted API for accepting card-present payments on Windows and Linux systems. It handles EMV processing, terminal management, and gateway communication, letting you focus on building your application rather than managing payment device complexity.

Common use cases include point-of-sale systems, kiosks, vending machines, parking systems, EV charging stations, ticketing, and any other environment where card-present payments need to run on Windows or Linux hardware.

ℹ️ Note: A downloadable emulator is available for Windows, enabling you to prototype and test integrations without physical hardware. macOS is not supported.

Key Benefits

Built for Card-Present Commerce
Designed to support a wide range of card-present use cases on Windows and Linux — from attended point-of-sale to unattended kiosks, vending, EV charging, and parking.

Cross-Platform Support
A single, consistent API works across both Windows and Linux, making it straightforward to scale solutions across different hardware configurations.

Wide Device Compatibility
Seamless connectivity with a broad range of payment terminals and peripherals, across both attended and unattended form factors, supported by the ChipDNA server.

Always-On Reliability
Optimized for continuous, high-traffic operation in demanding environments where downtime is not acceptable.

Secure and Compliant
Fully EMV-certified and PCI-compliant. End-to-end encryption is built into the SDK and payment gateway integration, so sensitive card data is never exposed to the host application.

How It Works

The SDK is structured around a client-server architecture running locally on the payment device host machine:

Component Description
ChipDNA Server A local service that manages the connection between your PIN pad and the NMI payment gateway. It handles EMV processing, terminal management, and transaction routing.
ChipDNA Client Your application communicates with the ChipDNA Server via a client library or CLI. NMI provides sample clients (GUI and CLI) to help you get started quickly.
Payment Gateway The NMI gateway processes and settles transactions. The ChipDNA Server handles all communication with the gateway on your behalf.
Terminal Management System (TMS) Managed by NMI. Automatically delivers EMV configuration, PIN pad firmware updates, and certificate data to the Server at regular intervals.

Prerequisites

Before starting an integration, ensure you have the following in place:

Payment Gateway Account

  • An NMI payment gateway account with an API Key (must have API source permissions). Generate it from Settings > Security Keys in the merchant portal.

SDK Package

  • Download the Windows & Linux SDK from the NMI Integration Portal. The Windows SDK is packaged as a .zip archive; the Linux SDK as a .tar.gz archive.
  • Extract to a local directory (for example, C:\Payment Device SDK on Windows, or /srv/Payment Device SDK on Linux).
  • The package includes the ChipDNA Server, sample client applications (CLI and GUI), and API documentation.

Operating Environment

Windows:

  • Windows 10 or 11 with .NET Framework 4.7.2 or later.

Linux:

  • Any Linux device with Mono 5.18.0 or higher. The SDK has been tested on Mono versions 5.18.0, 6.8.0, and 6.12.0. Pre-compiled Mono packages are available for most Linux distributions.
  • Java Runtime Environment (JRE) 8 or above is also required.

⚠️ Note: macOS is not supported.

All platforms:

  • A supported PIN pad or payment terminal (see Appendix 3 in the SDK documentation for a full device compatibility list).
  • Network access to NMI's TMS and gateway endpoints. Firewall changes may be required — see Appendix 4 (Firewall Configuration) in the SDK documentation for IP addresses and port numbers.

Integration Steps at a Glance

The full integration process is documented in detail in the developer portal. The high-level flow is:

1. Install and Configure the ChipDNA Server

Edit chipdna.config.xml to set your Application Identifier, Device ID, COM port, and API Key. Optionally configure SSL, proxy, and file store settings.

2. Run the Server

Start the ChipDNA Server in console mode for development and testing, or install it as a Windows Service (recommended for production) for automatic startup and continuous operation.

3. Configure and Run a Client

Use the provided sample CLI or GUI client to connect to the server. Set the Terminal ID from your gateway registration and confirm the server IP and port (default: 127.0.0.1:1869).

4. Run a Test Transaction

Initiate a sale transaction, follow the prompts on the PIN pad, and verify the approved or declined result in the client. Use a test card in sandbox mode.

5. Confirm or Void Transactions

⚠️ Important: Always call ConfirmTransaction() after a successful authorization. Without this step, the merchant will not receive funds. Use VoidTransaction() to cancel before settlement if needed.

6. Move to Production

Update your API Key to your production account credentials and update the ChipDNA Server configuration to point to NMI's live gateway endpoints.

Supported Environments

Platform Details
Windows Windows 10, Windows 11. Requires .NET Framework 4.7.2 or later. A payment device emulator is available for Windows to enable prototyping without hardware.
Linux Any Linux device with Mono 5.18.0 or higher (tested on Mono 5.18.0, 6.8.0, and 6.12.0). Also requires JRE 8 or above. Pre-compiled Mono packages are available for most Linux distributions.
macOS Not supported.
Payment Devices A wide range of PIN pads and terminals across attended and unattended form factors. Refer to the Appendix tables in the SDK documentation for a complete, up-to-date device compatibility list.

Common Questions

Do I need physical hardware to get started?

Not for Windows. NMI provides a downloadable payment device emulator for Windows that includes sample client code and server binaries, so you can build and test your integration before receiving physical terminals. Download it from the NMI Integration Portal.

What transaction types are supported?

The SDK supports the following transaction types:

  • Sale — authorizes and captures a payment. Must be confirmed via ConfirmTransaction() to settle.
  • Refund — processes a standalone refund to the cardholder.
  • Linked Refund — refunds all or part of a previously confirmed sale transaction.
  • Account Verification — verifies a card without charging it.

Refer to the API documentation included in the SDK package for full details on parameters and supported flows.

How does the SDK handle security and PCI compliance?

The ChipDNA SDK is EMV-certified and PCI-compliant. End-to-end encryption is built into the SDK and payment gateway integration, and sensitive card data is never exposed to the host application.

Can I run the ChipDNA Server as a background service?

Yes. For production deployments, NMI recommends installing the ChipDNA Server as a Windows Service with Automatic startup. This allows the service to start automatically without a logged-in user, and to restart automatically after reboots. See the Self/Series Integration Guide for step-by-step instructions.

What happens if a transaction is approved but not confirmed?

An approved transaction that is not confirmed via ConfirmTransaction() will not settle. Funds will not be captured. This step is mandatory after every successful authorization.

Additional Resources

Developer Documentation

For full integration guides, API references, sequence diagrams, and device appendix tables, refer to the following pages on the NMI documentation site:

SDK Download

Download the latest Windows & Linux SDK package from the NMI Integration Portal:

Support

For additional help, visit the NMI Support Center or submit a ticket: