Uniterm Integration and Deployment Guide - TranSafe Gateway: Electronic Payments Made Easy

v10.0.0
April 29 2026

UniTerm System

Overview

UniTerm securely handles sensitive cardholder data independent of the merchants application software. In addition, UniTerm provides a simple consistent interface to multiple payment acceptance devices such as card readers, pinpads and terminals. This guide is focused on local merchant deployment and management of the software. See our cloud hosted Uniterm service for a zero installation and management alternative.

Uniterm Architecture

The UniTerm module is accessed via its ‘Transaction Request’ mode, as described below

Step	Description
A	Point of sale application calls UniTerm for txnrequest (such as a sale transaction request) and includes basic information such as the amount of the sale and an order-number. This communication channel or request will NEVER contain sensitive cardholder data meaning it has reduced PCI scope.
B	UniTerm communicates with devices (such as pinpads and card readers) to retrieve sensitive data, depending on request type (step A).
C	UniTerm sends the full transaction data-set to Transafe for further processing.
D	Transafe processes the transaction request (such as a sale) against the appropriate end point (for example TSYS) and then sends back the response it receives to the UniTerm module.
E	The UniTerm module then returns the transaction response back to the calling application. This communication channel or request will NEVER contain sensitive cardholder data meaning it is out of PCI scope.

PAN Data Flows

Device     |  
  ↓        | 
Uniterm    |  Uniterm GUI
  ↓        |       ↓     
Transafe   |    Transafe

PAN data sent from the device to Uniterm uses the device configured connectivity. If using the Uniterm Cloud hosted instance this is always a TLS encrypted network connection. Local installations of Uniterm use the merchant configured connectivity as dictated by the device. E.g. USB-HID, Bluetooth, IP-TLS. Devices can optionally encrypt PAN data before leaving the device.

PAN data is sent from Uniterm to Transafe over a TLS encrypted connection.

PAN Protection

PAN data is stored encrypted in memory and only decrypted when necessary for processing. An example is decrypting PAN data to then put into a Transafe API message which is then TLS encrypted and sent to Transafe.

At rest PAN encryption is detailed in the “Storage, Key Management, and Logging” section.

Design Decisions

UniTerm is designed to run as an independent application running in a separate address space from any integrated applications. The design decisions behind this are due to the PCI Secure Software Standards and EMV certification requirements, where a clear line can be drawn between the certified application (UniTerm) and the POS without any ambiguity as to if the POS would fall into scope. If this clear line was not drawn, the POS may be required to undergo the extremely intensive and costly EMV Brand Certifications, not to mention fall into scope for PCI Secure Software Standards.

Store and Forward / Stand-In processing

Store and Forward or Stand-In processing is a mechanism to locally approve a transaction under a configurable dollar amount if an unrecoverable connectivity failure to your processing institution has occurred. When connectivity is restored, the authorization will be automatically forwarded to the host for approval. This functionality is only applicable to Credit Card transactions, and only those that do not require Online PIN as the cardholder verification method.

Stand-In is primarily designed for short-term outages where real-time approvals are necessary to the operation of a business. It is disabled by default due to the liability/risk of use.

A stand-in approval puts liability for the transaction on the merchant. A stand-in approval does not provide any guarantee the merchant will receive the funds. The issuer may decline for a number of reasons such as, Insufficient Funds, or a closed card account being presented. Use stand-in processing at your own risk!

There are a number of configuration options that allow a merchant to specify criteria for which transaction can be stored. Options such as, number of transactions currently offline, transaction amount, aggregate approved amount. Please see the uniterm.ini Configuration File section for additional configuration parameters.

If stand-in approves a transaction when the host is offline, the returned TTID will be prefixed with a ‘U’. This indicates it is a UniTerm TTID and is associated with the UniTerm instance that returned the approval. This TTID cannot be used with any other system. The TTID can be used with UniTerm reports to determine the transaction response once forwarded. At which point the real TTID will be returned. A response key of u_standin=yes will also be returned if a transaction was a stand-in.

Stored transactions will automatically attempt to be sent online for authorization every 15 minutes. If successfully sent the response will be recorded and can be accessed later by referencing the UniTerm TTID. Responses will be stored for a configurable number of days before being purged.

Stand-In eligibility rules

Not all transactions qualify for stand-in processing. Below you will find a quick reference to assist in determining why a transaction may not be eligible.

Applicable to all methods of entry:

Only cards able to be processed using credit card networks are eligible by default. E.g. not private label gift, EBT, or Pin-Debit. However, as of UniTerm v9.1, it is possible to allow Pin-Debit transactions to be stored by setting the corresponding flag in the merchant configuration in Transfe.
Missing or malformed authorization data (does not pass local edit checks).

EMV-specific failure reasons:

Online PIN was attempted (unless corresponding flag set in the merchant configuration on Transafe to allow this).
ODA (Offline Data Authentication) was not performed (ignored for US Debit) (unless overwritten by merch_flags with EMVODA_FAIL_STANDIN_ALLOWED).
ODA (Offline Data Authentication) static or dynamic failed (unless overwritten by merch_flags with EMVODA_FAIL_STANDIN_ALLOWED).
Card on terminal exception file.
CDA (Offline combined dynamic data authentication with application cryptogram) failed.
SDA (Static data authentication) was selected.
Card application expired.
Card application not yet effective.
Cardholder verification was not successful.
Unrecognized Cardholder Verification Method (ignored for US Debit).
PIN failures such as: limit try exceeded, pin entry device not present or inoperable, pin not entered (ignored for US Debit).
Consecutive offline limit exceeded.

ChipTab – EMV Bar Tab support

Tabs are used to capture card data for later processing. This is for a single transaction and is not equivalent to tokenizing a card.

Typical use is at a bar where the customer opens a tab and as they order drinks or food the amount they’re spending is added to the tab. Once they’re finished and ready to leave the tab is closed and their card is charged.

This is commonly used in situations where payment is not taken at the same time as the product is given to the customer. And when there is the potential for the customer to leave without paying. Unlike a restaurant a bar can have a patron become intoxicated and forget to pay. In this situation the store has already captured the customer’s card data and can close the tab against the card.

Tabs are intended to be opened and closed on the same day. Usually within a few hours. They are not intended for taking payment and shipping goods at a later time. Open tabs are auto purged if older than 14 days.

When closed the transaction data is sent to Transafe for authorization. If there is a communication error between UniTerm and Transafe or between Transafe and the processor tabs may be eligible for stand-in authorization. Stand-in authorization must be enabled and the transaction must be eligible for offline storage to take place. Tabs that are converted to offline authorizations will skip stand-in amount and count limits in order to prevent losing tabs.

ChipTab eligibility rules

Not all transactions qualify for ChipTab processing. Below you will find a quick reference to assist in determining why a transaction may not be eligible.

Allowed card types that can be used for tabs:

Credit
Debit
EBT Cash Benefits

These card types are specifically not allowed for tabs:

Gift
EBT Food Stamps

EMV-specific failure reasons:

ODA (Offline Data Authentication) static or dynamic failed.
Card on terminal exception file.
CDA (Offline combined dynamic data authentication with application cryptogram) failed.
SDA (Static data authentication) was selected.
Card application expired.
Card application not yet effective.
Cardholder verification was not successful.
Unrecognized Cardholder Verification Method.
PIN failures such as: limit try exceeded, pin entry device not present or inoperable, pin not entered.
Consecutive offline limit exceeded.

UniTerm Integration and Deployment Overview

Uniterm can be installed locally by merchants or used as a cloud service provided as part of Transafe. We recommend using the cloud service because it does not require installation or maintenance by the merchant.

Local Deployments

Merchants may choose to install locally for some of the following reasons:

The chosen payment device does not support cloud connections
b. Only Ingencio devices are supported by the cloud service
a. USB-HID, or Bluetooth connectivity
Local installation allows for Standin-In authorizations when internet connectivity is not available
Security restrictions and monitoring needs within the merchant systems

Uniterm installation packages can be found at Uniterm Developers. Windows and Linux are supported operating system on the x64 architecture.

Installation involves running the installer and following the instructions.

Version Scheme

The versioning scheme employed by UniTerm is formatted as X.Y.Z, where each X, Y, and Z components are numeric-only version indicators separated by a period. Each numeric component may be from one to three digits in length. All software distribution updates will result in at least one of the components being updated.

The X component of the version indicates the product major version number. The major version component only changes when there are significant feature changes, or the changes impact any part of a security standard, such as PCI.

The Y component of the version indicates a product minor version change. The minor version will change when there are minor feature enhancements that do not impact the part of any security standard such as PCI.

The Z component of the version indicates a bug-fix release. Bug-fix releases do not change the overall feature-set or functionality of UniTerm, but may include security related fixes such as updates to 3rd party libraries (e.g. cryptographic libraries) distributed with UniTerm.

Starting UniTerm

For Desktop based deployments, the UniTerm module should be launched by the POS application software and should not be started at startup. If the POS system does not start UniTerm, then it is possible UniTerm will not be able to obtain screen focus for on-screen prompts.

Command Line Options

When starting UniTerm for Desktop based deployments, there are a few command line options supported that control the behavior.

-c – Full path to the ini file to read. If not specified, it searches for the uniterm.ini in the paths documented in the uniterm.ini file
-p – Port for UniTerm to listen on for incoming connections. If not specified, the value in the ini file is used. The purpose of this configuration value is to aid in the ability to start multiple UniTerm instances on the same machine with the intention of using GUI mode for multiple user logins (e.g. Terminal Services).
-h – Help options are displayed.

Multiple Instances

Uniterm is designed to handle multiple devices. This allows deployment as a central system when used with network connected devices.

Deploying UniTerm in a public-facing environment

In some environments it may be beneficial to deploy UniTerm such that it is “public-facing”, meaning that untrusted (e.g. internet) users can access UniTerm. This is mostly useful for web-based POS systems which may need to talk to UniTerm via the back-end host rather than the front-end machine (while utilizing IP-enabled terminals). In this case, UniTerm may be running anywhere in the world, rather than on the POS system as is typically done.

There are a few requirements that must be followed to ensure UniTerm an sensitive data is protected and complies with the PCI Secure Software Standards requirements:

Deploy UniTerm in a DMZ, behind a firewall with only specific ingress and egress ports allowed.
Configure the use of external database, not the built-in default SQLite database.
The database must reside within a different, private, system and security zone, and not be deployed in the DMZ with UniTerm.
Ensure any terminals connecting via IP to UniTerm are using TLS v1.2 or higher, or are using P2PE encryption.
The only egress ports that should be open for UniTerm are to Transafe (443) restricted to that host, and a similar rule allowing access to the external database.
The only ingress ports should be the API port (by default 8123), and if using IP-enabled terminals, the port configured in the [device_server] section of uniterm.ini

Communication to UniTerm from Integration

The communication protocol for UniTerm is very similar to that Transafe A rest API is used and is documented in the UniTerm REST API Documentation.

Shutting Down Uniterm

UniTerm should only be shut down if it was started by the POS, and does not apply to overhead systems.

On Windows, a standard Window shutdown message may be sent, or on Unix a SIGTERM signal may be sent to the UniTerm process. Or universally UniTerm supports a shutdown message via the API.

User Setup Permissions and Requirements

All authentication is managed by Transafe.

To ensure that the integrated system has reduced PCI scope, UniTerm requires that sensitive data is never returned from Transafe.

UniTerm also requires these permissions to operate at a minimum. More may be needed depending on what functoinalitly the merchant wasn’t to allow with Uniterm. For example, refunds.

sys_perms

GETPERMS
REGISTERCLIENT

admin_perms

MERCH_INFO
IMAGEADD – Only required if device support signature capture.
STANDINKEY_GENERATE – Only required if supporting stand-in or chiptab operations.

trans_perms

CARDTYPE
SALE
VOID
REVERSAL
TERMLOAD – Required if supporting EMV, Canadian Interac Debit, orTransArmor
EMVCOMPLETE – Required only if supporting EMV
INTERACMAC – Required only if supporting Canadian Interac Debit

Please consult with your integration and development team for the features used to determine additional permissions.

Linux OS device access permissions

HID devices

Most Linux distributions, by default, do not allow non-root users to access HID devices. Since it is not desirable to run a POS or UniTerm as root, some system changes are required to grant access to normal users. In general, the udev subsystem controls device enumeration, so some rules must be added to tell it what permissions to grant for enumerated HID devices.

Before a udev rule can be added, a system administrator must determine what group to grant privileges to HID devices. On RedHat based systems, the most suitable pre-existing group name is probably input. For Debian based systems, the most suitable pre-existing group name is probably plugdev. If no suitable groups are pre-existing, the system administrator should create one with an appropriate name.

Next a file named /etc/udev/rules.d/99-hid.rules should be created with contents similar to: KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0660", GROUP="$group". Of course, replacing $group with the desired group name.

Finally, the system administrator should add the user that wishes to run UniTerm to the group, a command to do that might look like: usermod -a -G $group $user. Of course, replacing $group and $user as appropriate. If already logged in as the user being modified, it is necessary to log out and back in for the group membership to be updated.

Once these steps are performed, UniTerm should now be able to run as a non-root user and access HID devices.

Serial devices

If the user that runs UniTerm is unable to open a serial device, most likely it is simply a group permissions issue. Both RedHat based and Debian systems use the dialout group for serial port access. A system administrator might need to do further research in to what group may be used on their system.

In order to add your user to the appropriate group, a command to do that might look like: usermod -a -G $group $user. Of course, replacing $group and $user as appropriate. If already logged in as the user being modified, it is necessary to log out and back in for the group membership to be updated.

If your distribution is not setting group membership on serial devices during enumeration, it may be necessary to add specific udev rules to allow this.

Configuration Files

There is a single configuration file named uniterm.ini that must be configured before UniTerm can be used. Included with UniTerm is a file named uniterm_example.ini that can be used as a template.

The uniterm.ini file MUST be readable and writable by the UniTerm process.

The location of the uniterm.ini file may vary from system to system, and the default search paths, listed in priority order, are:

Windows
- %APPDATA%/UniTerm/uniterm.ini
- same path as the uniterm.exe executable
Linux
- ~/.config/UniTerm/uniterm.ini
- ~/.uniterm/uniterm.ini

Configuration Parameters

The parameters in this section are in standard ini format grouped by sections. Sections are in the format of “[section]”. The settings for each section are in key/value pair format of “key=value”. Each setting and section are delimited from each other using a new line, either Unix LF or Windows-style CRLF are acceptable.

The ini lists all configuration options and each one is fully documented in the ini as comments. Sections are also documented describing their use and functionality they pertain to.

Storage, Key Management, and Logging

UniTerm has a database backend for caching merchant and transaction data for offline processing, as well as logging facilities for monitoring and inspection of transaction processing.

Database Storage, Security, and Key Management

UniTerm supports data storage to just about any database backend, though the most commonly deployed is SQLite due to its zero-configuration nature. All sensitive data is encrypted prior to hitting the database layer using field-level encryption.

The location of data storage is defined in the database configuration (Section: [db]) in the ini file.

The UniTerm database serves two purposes. The first purpose is as a caching front-end for all of the loading data necessary to operate a terminal. This includes, but is not limited to, merchant metadata (name, address), EMV terminal parameters (AIDs, CAPKs), and card BIN tables. The second purpose is for Stand-in authorizations and ChipTab support, where sensitive cardholder data is stored until authorization, as well as tracking of metadata after authorization.

Data is cached to disk from Transafe to limit necessary round-trips which may add latency, especially if UniTerm is frequently stopped and restarted (as is the case on Mobile devices to conserve power), as well as facilitating offline terminal loading. Cache refresh times vary, but in general merchant-specific settings are refreshed every 24hrs and Transafe specific parameters such as large BIN tables may not be updated more than once per week.

For Stand-in and ChipTab support, sensitive cardholder data is stored encrypted using AES-256-CBC in the stored_trans table per key/value pair. The AES key used is an ephemeral key generated for that specific transaction, and is stored in the same stored_trans table in the e_id key mapping which itself is encrypted using a merchant-specific RSA public key retrieved from Transafe (but not private key). Once the transaction is encrypted, all in-memory traces are wiped and Uniterm can no longer access the sensitive cardholder data which can now only be decrypted by the Transafe instance holding the RSA private key. The merchant-specific RSA public keys are stored in the stored_keys table and are rotated automatically every 10-12 days. After authorization, all transaction request data is purged from the database. Data after authorization may be stored in Transafe up to gateway’s retention period.

For offline operation, requests must still be authenticated, therefore the last successfully validated password for the merchant is recorded to the user table using the secure hashing mechanism PBKDF2-SHA256 and the number of rounds as specified in the password_iterations configuration parameter. Once the password has been validated the first time, it is then cached in memory in an AES-256-CBC encrypted hash table to reduce the CPU load required in re-computing the hash for verification while still staying secure from common attack vectors such as memory scrapers.

Logging

The UniTerm log is a multi-purpose log format. It provides insight into the operations of UniTerm as well as a detailed audit trail of every operation performed by an end user, including, but not limited to, IP address, request types along with request and response parameters, and duration of connection. UniTerm’s logging does not exist to meet any PCI requirements since UniTerm does not provide any sort of access to cardholder data that would require authentication and is generally not relevant to PCI, but rather for debuggability and insight into system function.

The UniTerm log will never log sensitive merchant or cardholder data, any data that may be considered sensitive is completely masked in the logs.

UniTerm facilitates centralized logging via remote syslog facilities, either by using a system-provided syslog API, or by directly supporting Syslog over TCP.

PCI Secure Software Standards mandates that logging of all modifications to system level objects is done on systems containing payment applications. It is required that merchants deploy a logging facility such as file integrity monitoring on such payment systems to comply with this requirement. UniTerm does not provide such a facility directly, and is an external requirement which must be implemented by the merchant.

External Data Storage

If the merchant backs up the UniTerm database or otherwise stores sensitive data outside of the controls put in place by UniTerm or Transafe, it is the merchant’s responsibility to do so in a PCI Secure Software Standards compliant manner for the customer-defined retention period.

PCI Security and Implementation

Security and PCI requirements impact

The below details the various security and PCI requirements and how deployments may be impacted. Integrators and distributors should read this section prior to any production deployments. UniTerm is designed to be compliant with all PCI requirements and cannot be configured to be non-compliant.

PCI requirements mapping

TOPIC	DISCUSSION
Delete sensitive authentication data stored by previous payment application versions.	UniTerm has never stored any sensitive authentication data in a non-secured or non-approved manner.
Delete any sensitive authentication data (pre-authorization) gathered as a result of troubleshooting the payment application.	UniTerm does not have the ability to store sensitive authentication data for troubleshooting purposes.
Securely delete cardholder data after customer-defined retention period.	UniTerm never stores cardholder data after authorization and prior to authorization is stored encrypted in the database using a merchant specific RSA public key from Transafe.
Mask PAN when displayed so only personnel with a business need can see the full PAN.	It is not possible that the full PAN can ever be returned. There is no ability to configure UniTerm to return the PAN.
Render PAN unreadable anywhere it is stored (including data on portable digital media, backup media, and in logs).	Sensitive cardholder data is always unreadable.
Protect keys used to secure cardholder data against disclosure and misuse.	UniTerm does not have the keys to decrypt any stored cardholder data.
Implement key-management processes and procedures for cryptographic keys used for encryption of cardholder data.	Only ephemeral keys are used to store cardholder data, and those are protected by RSA Public keys rotated ever 10-12 days.
Implement secure key-management functions.	UniTerm requests RSA public keys from Transafe. Transafe handles management of the RSA private keys.
Provide a mechanism to render irretrievable cryptographic key material or cryptograms stored by the payment application.	UniTerm never has the keys to decrypt sensitive cardholder data.
Use unique user IDs and secure authentication for administrative access and access to cardholder data.	UniTerm does not provide or facilitate administrative access; all access controls are provided by Transafe.
Use unique user IDs and secure authentication for access to PCs, servers, and databases with payment applications.	UniTerm does not provide or facilitate administrative or remote access. UniTerm utilizes Transafe for access to UniTerm and its connected devices in conjunction with the policies as described. All access controls to cardholder data are provided by Transafe.
Note	It is the integrator’s responsibility to ensure unique user names and secure authentication are used to access any PCs, servers, and databases with payment applications and/or cardholder data. This requirement is external to UniTerm and not something that can be provided by UniTerm on behalf of the merchant or integrator.
Implement automated audit trails.	Audit trails are provided by Transafe as well as by UniTerm’s built-in logging mechanisms.
Facilitate centralized logging.	Centralized logging is facilitated by the syslog subsystem provided by UniTerm.
Implement and communicate application versioning methodology.	Please see the Versioning section.
Securely implement wireless technology.	UniTerm is not designed facilitate the use of wireless technologies; however, merchants may deploy UniTerm in environments where wireless technologies are in use. UniTerm always uses secure communications channels protected by TLS v1.2 or higher, which are designed for use in public/untrusted networks, to protect sensitive cardholder data while in transit. Requiring additional security mechanisms on any wireless technology in use is not a requirement as per PCI; however it is always a recommended best practice.
Secure transmissions of cardholder data over wireless networks.	UniTerm is not designed facilitate the use of wireless technologies; however, merchants may deploy UniTerm in environments where wireless technologies are in use. UniTerm always uses secure communications channels protected by TLS v1.2 or higher, which are designed for use in public/untrusted networks, to protect sensitive cardholder data while in transit. Requiring additional security mechanisms on any wireless technology in use is not a requirement as per PCI; however it is always a recommended best practice.
Provide instructions for secure use of wireless technology.	UniTerm is not designed facilitate the use of wireless technologies; however, merchants may deploy UniTerm in environments where wireless technologies are in use. UniTerm always uses secure communications channels protected by TLS v1.2 or higher, which are designed for use in public/untrusted networks, to protect sensitive cardholder data while in transit. Requiring additional security mechanisms on any wireless technology in use is not a requirement as per PCI; however it is always a recommended best practice. Integrators should ensure they secure any wireless technologies in use are in compliance with the requirements in Requirement 6.3 for other applications that may not deploy UniTerm’s secure practices.
Use only necessary and secure services, protocols, components and dependent software and hardware, including those provided by third parties.	UniTerm communicates only via TLS with Transafe across the Internet. A customer may choose to deploy UniTerm with one or more hardware card entry devices or terminals directly attached to the system via USB, Serial, BlueTooth, or Ethernet. It is the integrator’s responsibility to ensure only necessary and secure protocols, services, etc., are used on the system.
Store cardholder data only on servers not connected to the Internet.	Cardholder data is only stored within UniTerm prior to authorization with no ability to retrieve it in plain-text.
Implement two-factor authentication for all remote access to payment application that originates from outside the customer environment.	UniTerm does not facilitate remote access. Therefore, integrators or merchants choosing to provide an external means of remote access must ensure that all remote access originating from outside the customer’s network to a payment application must use two-factor authentication. Two-factor means two separate types of authentication: a username and password is one factor; a second password would not be considered a second factor. It should instead be something external such as a token.
Securely deliver remote payment application updates.	Integrators or merchants must securely deliver updates to UniTerm in compliance with the Deployment section. Deployments must be done in accordance with the PCI Secure Software Standards.
Securely implement remote-access software.	Transafe will never reach out to a remote customer network for this purpose. If an integrator or merchant chooses to support remote access for management, they must do so in compliance with PCI Secure Software Standards requirements.
Secure transmissions of cardholder data over public networks.	UniTerm communicates only via TLS to Transafe using proprietary protocols. UniTerm communicates using the PCI Secure Software Standards required protocols and cipher suites. No configuration is required of UniTerm to comply, nor is it possible to reconfigure UniTerm to a less secure protocol or cipher suite. Future versions may implement new protocols and cipher suites as they become available. UniTerm, by default, performs full validation of the Transafe’s certificate.
Encrypt cardholder data sent over end-user messaging technologies.	UniTerm does not facilitate or support the use of end-user messaging technologies.
Encrypt non-console administrative access.	UniTerm does not provide or facilitate administrative access.