Overview

UniTerm securely handles sensitive cardholder data independent of the merchant's application software. In addition, UniTerm provides a simple, consistent interface to multiple payment acceptance devices, such as card readers, pinpads, and terminals.

UniTerm is dependant on and intended to be used in conjunction with the Payment Server. UniTerm handles the customer-facing portion of the payment, while the Payment Server handles authorization requests using the customer's account information that UniTerm has securely read.

Communication between UniTerm and the Payment Server uses a TLS-encrypted connection. Account information is never transmitted in the clear between UniTerm and the Payment Server.

Communication to UniTerm from Integration

At the heart of the protocol is a simple key/value pair message structure, very similar to the Payment Server Specification. In fact, many of these key/value pairs sent to UniTerm are simply passed-through to the Payment Server for processing.

The API utilizes robust key/value pairs for flexibility. To make transport easier, all pairs are comprised of strings.

User Setup Permissions and Requirements

All authentication is managed by the Payment Server.

To ensure that the integrated POS is removed from PCI PA-DSS scope, UniTerm requires that sensitive data is never returned from the Payment Server. To enact this, UniTerm only allows merchant sub-users to authenticate. Sub-users are unique usernames that are tied to a merchant user with their own individual password, but they possess only a subset of the allowed permissions. These unique usernames, when passed to UniTerm, are prefixed with the username of the merchant user and delimited with a colon (:). (e.g. merchuser:subuser). UniTerm requires the sub-user to have the "obscure sensitive information" flag set, or it will generate a failure.

UniTerm also requires these permissions to operate:

  • 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

More permissions may be required based on the POS operations supported. Please consult with your integration and development team for the features used.

Prompting

UniTerm handles various types of common customer prompting requirements.

Tip Prompting

UniTerm supports prompting the cardholder for a tip amount at the time of payment. To do this, the Payment Server merchant account must have the merch_tippercent setting configured. Sending the u_flags parameter NOTIP will disable this prompting.

When a customer has chosen to add a tip amount to a transaction, the amount provided by the POS to UniTerm will be incremented to reflect the tip amount, and examount will be populated with the tip amount when the transaction is sent to the Payment Server.

In the response returned by UniTerm, the tip amount will be provided to the POS in the u_tip response parameter.

Note: Special care should be taken to validate whether or not the authamount response parameter is returned, indicating a partial authorization occurred, that split tender operations can occur. When prompting for a second payment method, an integrator should use the NOTIP u_flags in order to avoid tip prompting on the second method of payment, and respect the returned u_tip response for the chosen tip amount from the original response.

Cashback Prompting

UniTerm supports prompting a cardholder for cashback when a Debit or EBT Cash Benefits card is used for payment. UniTerm will automatically perform such prompting when the Payment Server account is configured to support cashback. The NOCASHBACK u_flags parameter will disable this behavior.

When a customer has chosen to request cashback with a transaction, the amount provided by the POS to UniTerm will be incremented to reflect the cashback amount and the cashbackamount parameter will be populated with the cashback amount when the transaction is sent to the Payment Server.

In the response returned by UniTerm, the cashback amount will be provided to the POS in the u_cashback response parameter.

Note: Special care should be taken to validate if the authamount response parameter is returned, indicating a partial authorization occurred. If the returned amount is less than the requested amount plus u_cashback then the POS must decide on the proper course of action. For instance if the authamount is greater than requested, but less than the amount plus u_cashback then partial cashback would be provided to the cardholder. Otherwise if the authamount is less than the requested amount, then the u_cashback returned should be completely ignored and the POS would need to prompt the cardholder for another method of payment.

EBT Processing

UniTerm supports EBT prompting when an EBT card is used for payment. If the u_foodamount parameter is populated with a non-zero dollar amount to indicate the amount of the transaction that applies to qualified food purchases (or for Transaction Start with a value of maybe), then the customer will also be prompted if they would like to use Food Stamps (SNAP) or Cash Benefits to complete the transaction. When the cardholder makes the selection, UniTerm will internally rewrite the action=sale request parameter to action=ebtfssale or action=ebtcbsale as appropriate.

For Transaction Start transactions where u_foodamount=maybe, the integrator must send a valid u_foodamount value with Transaction Finish, or else the transaction will be aborted.

If Food Stamps (SNAP) was selected, u_wasfood will be returned as yes/true to indicate this. If the requested amount is greater than u_foodamount, then a partial authorization will be returned (as indicated by the authamount response parameter), indicating the amount of the authorization was less than the requested. The returned authamount may be less than the u_foodamount if there are insufficient funds. Otherwise, it will be equal to the u_foodamount requested.

If a partial authorization is performed, the merchant should perform a split-tender operation and prompt for another method of payment for the remainder, which may also be EBT. The requested amount and u_foodamount need to be adjusted accordingly on the next request based on the amounts previously authorized.

EMV

EMV transactions, by nature, are much more complex than traditional magnetic stripe transactions. UniTerm hides this complexity from the application software. For instance, in the case of magnetic stripe and EMV transactions, the application software will send the request to UniTerm. UniTerm will use the device capabilities (like EMV contact and RFID) and the merchant account configuration to handle the appropriate prompting and flow aspects related to the determined capabilities. The application software simply needs to send a Transaction Request and let UniTerm handle the rest.

Transaction Flow and Prompting

Integrators unfamiliar with EMV may notice some specific flow cases that seem counterintuitive at first. This section is meant to address these EMV-specific cases.

Swipe prompts to insert

If a chip-enabled card is swiped on an EMV-capable terminal, it is mandated that the user be prompted to insert the card. This is an EMV certification requirement that cannot be lifted. It is meant to prevent fraud and to train consumers to insert their cards.

Tap prompts to insert

There are certain thresholds negotiated between the card and terminal which may request a chip-enabled card that is presented as a tap transaction to be inserted instead. When this occurs, it can be due to a number of factors, like fraud mitigation, or because the card has determined that it needs to be updated (for insert transactions, an issuer can choose to return issuer scripts to remotely reprogram cards).

Insert prompts to swipe

If a chip-enabled card is prompted to be swiped, this is usually an indication that there was a chip malfunction and the cardholder should have their card replaced, which is called a technical fallback. It is expected that, at some point in the future, a technical fallback will be disallowed due to fraud concerns. The other possibility is that the terminal does not support the card's application ID.

PIN required on Credit Cards

The cardholder verification method is negotiated between the card and the terminal. If both the card and terminal support PIN entry, it may be chosen as the desired verification method. Consumers in the US may not expect to enter a PIN on their credit cards, but it is common among foreign cards.

Signature not requested

The cardholder verification method is negotiated between the card and the terminal. They may negotiate Signature, PIN, or what is called NoCVM, which means no cardholder verification is required for the transaction. The decision is strictly made based on the terminal capabilities and card capabilities.

Tap transaction run as MSR on chip-capable card with no insert requested

It is a requirement by the card brands that a card cannot be prompted for insertion if it is presented as a tap and read as MSD. This can happen due to a terminal not being configured for contactless EMV support, or if a chip is malfunctioning.

Immediate decline without contacting the processor

EMV cards have the ability to make decisions about the transaction before it is even processed. From time to time, a merchant may see a chip-capable card presented that results in an immediate decline before requesting cardholder verification or connecting to a processing institution. This could happen because the card has exceeded some internal threshold, or the card has received a remote script on a previous transaction to explicitly block transactions, such as a card block or application block.

Pre-formatted Receipt Processing

Pre-formatted receipt processing has been added to simplify generation of receipts that are in compliance with the rules dictated by the card brands. Data is output in a series of sections so that merchants may insert their own custom data in-between sections of brand-required data as they see fit.

The u_rcpt key/value pair is sent in the request to UniTerm to indicate whether or not to output a series of pre-formatted receipt blocks. This can also specify format requirements. If set to yes, it will simply use the receipt formatting for plain text, suitable for printing on a standard receipt printer. Other output formats are supported and discussed in the transaction operations that can generate receipts.

Parameter and Response KVS

The parameters listed are only the subset that apply to UniTerm. A small subset of interchange or other required parameters is also documented. Additional request parameters specific to the Payment Server may need to be specified and passed through. The Payment Server may pass back additional response data.

Parameter Groups

Internally, all keys are a flat list and are not hierarchical. Throughout the documentation, parameters may be grouped together under a named object. The object name is not evaluated when processing the request. All key/value pairs are moved to the top level.

Parameter grouping is present simply to make it easier to understand the relationship between parameters. The parameters themselves do not need to be part of the documented object they may be under.

Standin Authorizations

Standin will take place when UniTerm cannot connect to the payment server or when the following codes are returned. The code and msoft codes indicate a connectivity failure to the processor.

The phard codes indicate the processor returned a connectivity failure either within their systems, or the brand network, or to the issuer. Not all processors return connectivity failure information. Most will return a generic decline without an indication if it was declined by the issuer or not.

code:

  • TIMEOUT

msoft_code:

  • CONN_MAXATTEMPTS
  • CONN_MAXSENDS

phard_code:

  • NOREPLY
  • RETRY
  • SYSTEM_ERROR

In order for standin to happen it must be enabled in the UniTerm configuration. All parameters related to standin must also be configured in order for it to be setup.

Not all card types can be approved standin. Merchant configuration can place restrictions on what types of cards and under what circumstances transactions can be standin approved. Please see the merchant account configuration on the payment server for more details in regard to these limits.

Finally, some processing insinuations place restrictions on standin approvals which can influence if a transaction can standin approve.

Time Formats

A value denoting a time can take on one of two different types:

  • formatted time
  • Unix timestamp

Formatted

Formatted times can either be a fixed time or based on an offset. The time zone for the date is the merchant's timezone.

Fixed

Fixed formats are very similar to written date and times.

Formats:

  • YYYY-MM-DD
  • YYYY/MM/DD
  • YYYY-MM-DD hh:mm
  • YYYY-MM-DD hh-mm
  • YYYY/MM/DD hh:mm
  • YYYY/MM/DD hh-mm
  • YYYY-MM-DD hh:mm:ss
  • YYYY-MM-DD hh-mm-ss
  • YYYY/MM/DD hh:mm:ss
  • YYYY/MM/DD hh-mm-ss
  • MM-DD-YYYY
  • MM/DD/YYYY
  • MM-DD-YYYY hh:mm
  • MM-DD-YYYY hh-mm
  • MM/DD/YYYY hh:mm
  • MM/DD/YYYY hh-mm
  • MM-DD-YYYY hh:mm:ss
  • MM-DD-YYYY hh-mm-ss
  • MM/DD/YYYY hh:mm:ss
  • MM/DD/YYYY hh-mm-ss
  • MM-DD-YY
  • MM/DD/YY
  • MM-DD-YY hh:mm
  • MM-DD-YY hh-mm
  • MM/DD/YY hh:mm
  • MM/DD/YY hh-mm
  • MM-DD-YY hh:mm:ss
  • MM-DD-YY hh-mm-ss
  • MM/DD/YY hh:mm:ss
  • MM/DD/YY hh-mm-ss
  • MMDDYYYY
  • MMDDYY

Offset

Offsets take this format:

+ or -
  magnitude
  space
  modifier

Modifiers:

  • year[s]
  • month[s]
  • week[s]
  • day[s]
  • hour[s]
  • min[s|ute|utes]
  • sec[s|ond|onds]

Example

+1 day
-5 years

Special keywords

  • now - current date/time
  • epoch - Unix timestamp of 0 = Jan 1, 1970 00:00:00 UTC

Unix Timestamp

Any keys that end with _ts, such as last_modified_ts, are a Unix timestamp. A Unix timestamp is the number of seconds since Jan 1, 1970 00:00:00 UTC. That date and time is called the "epoch", and its value is 0.

Unix timestamps are always in UTC time and do not have a time zone.

Authentication

API Keys and HTTP Basic authentication are currently supported.

An API key ID and secret need to be generated to use API keys.

The UniTerm username and password for the account setup to run transactions is used with the Basic authentication method.

API Key Authentication

API keys are composed of two parts. A public key id and a private key secret. The key secret must be protected by the integrator. Keys can represent a user or profile. It is recommended to create a profile key for unattended POS systems so the keys are not invalided if a user leaves.

These allow users to disassociate their username and password from authentication. They will be able to manage and revoke keys in case an application (POS) is compromised. Also, integrated applications will be able to use a key instead of storing the user's username and password.

API Key information is passed in the following headers when using ReST:

  • X-API-KEY-ID: <key id>
  • X-API-KEY: <key secret>

If using the libmonetra key value pair protocol, api keys use these fields:

  • auth_apikey_id
  • auth_apikey_secret

Programming language examples

Python

import urllib.request
import urllib.parse

URL = 'https://uniterm.test.transafe.com:8123/api/v1/transaction/quick'
KEY_ID = 'X123'
KEY_SECRET = 'b64a='

headers = {
    'X-API-KEY-ID': KEY_ID,
    'X-API-KEY': KEY_SECRET,
}

data = urllib.parse.urlencode([
    ('u_device', 'IPCLIENT:78909876'),
    ('u_devicetype', 'ingenico_upp'),
    ('u_foodamount', '92.44'),
    ('u_id', '0IDS425S'),
    ('action', 'sale'),
    ('amount', '92.44'),
    ('nsf', 'yes'),
    ('ordernum', '6893'),
    ('u_rcpt', 'yes')
])

req = urllib.request.Request(URL, data=data.encode(), headers=headers, method='POST')
with urllib.request.urlopen(req) as o:
    print(o.read().decode('utf-8'))
C#
using System;
using System.IO;
using System.Net;
using System.Text;

class AuthExample
{
    static void Main(string[] args)
    {
        var url        = "https://uniterm.test.transafe.com:8123/api/v1/transaction/quick";
        var key_id     = "X123";
        var key_secret = "b64a=";
        var json       = "{\"u_device\":\"IPCLIENT:78909876\",\"u_devicetype\":\"ingenico_upp\",\"u_foodamount\":\"92.44\",\"u_id\":\"0IDS425S\",\"action\":\"sale\",\"amount\":\"92.44\",\"nsf\":\"yes\",\"ordernum\":\"6893\",\"u_rcpt\":\"yes\"}";

        ServicePointManager.Expect100Continue = false;
        ServicePointManager.UseNagleAlgorithm = true;
        ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

        var request = WebRequest.Create(url);
        request.Method = "POST";
        request.Headers.Add("X-API-KEY-ID", key_id);
        request.Headers.Add("X-API-KEY", key_secret);
        request.ContentType = "application/json";
        request.ContentLength = json.Length;
        Stream requestStream = request.GetRequestStream();
        requestStream.Write(Encoding.ASCII.GetBytes(json), 0, json.Length);
        requestStream.Close();

        using (var response = (HttpWebResponse)request.GetResponse()) {
            Console.WriteLine(response.StatusDescription);

            using (var dataStream = response.GetResponseStream()) {
                using (var reader = new StreamReader(dataStream)) {
                    Console.WriteLine(reader.ReadToEnd());
                }
            }
        }
    }
}
PHP
<?php
$url = "https://uniterm.test.transafe.com:8123/api/v1/transaction/quick";
$key_id = "X123";
$key_secret = "b64a=";
$opts = array(
  "http"=>array(
    "method"=>"POST",
    "header" => "X-API-KEY-ID:" . $key_id . "\r\n" . "X-API-KEY: " . $key_secret . "\r\n"
    "content"=>array(
      "u_device"=>"IPCLIENT:78909876",
      "u_devicetype"=>"ingenico_upp",
      "u_foodamount"=>"92.44",
      "u_id"=>"0IDS425S",
      "action"=>"sale",
      "amount"=>"92.44",
      "nsf"=>"yes",
      "ordernum"=>"6893",
      "u_rcpt"=>"yes"
    ),
  ),
);
$context = stream_context_create($opts);
$file = file_get_contents($url, false, $context);
echo $file;
?>

Basic Authentication

HTTP Basic Authentication involves sending the Authorization HTTP header with the type Basic and the base64 encoded username:password.

E.g.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

If the authorization data is not present the response code 401 and WWW-Authenticate header is returned in the response indicating the authentication that must be used.

WWW-Authenticate: Basic realm="Payment Server Resource"

Colon escaping

Basic auth does not allow colons (':') to be present in usernames. However, most usernames for the system will include a colon. To deal with this, all colons must be replaced with a pipe ('|').

If a username contains a pipe, please contact support.

user:sub -> user|sub

For example, take the username test_retail:public and a password of publ1ct3st. Therefore, the username must be transformed to test_retail|public, resulting in basic authentication data to be encoded of test_retail|public:publ1ct3st. The resulting Authentication header data would be Authorization: Basic dGVzdF9yZXRhaWx8cHVibGljOnB1YmwxY3Qzc3Q=

Programming language examples

We do not recommend using most programming language's build in credential management APIs. Such as .Net's HTTPPasswordMgrWithDefaultRealm with a HTTPBasicAuthHandler object. Or Python's NetworkCredential with the CredentialCache. Instead we recommend sending the authorization data directly/explicitly in the request header.

Using the language API credential management can increase the transaction processing time. Many language APIs will first send the request without authorization data. The server will respond with a 401 authorization data required response. The request will be sent a second time with the authorization data. The extra request that is known to fail adds additional and unnecessary, messaging which increases request processing time.

Python

import urllib.request
import urllib.parse
import base64

URL = 'https://uniterm.test.transafe.com:8123/api/v1/transaction/quick'
USER = 'test_retail|public'
PASS = 'publ1ct3st'

auth_data = '%s:%s' % (USER, PASS)
auth_data = base64.b64encode(auth_data.encode()).decode('utf-8')
headers = {
    'Authorization': 'Basic %s' % auth_data
}

data = urllib.parse.urlencode([
    ('u_device', 'IPCLIENT:78909876'),
    ('u_devicetype', 'ingenico_upp'),
    ('u_foodamount', '92.44'),
    ('u_id', '0IDS425S'),
    ('action', 'sale'),
    ('amount', '92.44'),
    ('nsf', 'yes'),
    ('ordernum', '6893'),
    ('u_rcpt', 'yes')
])

req = urllib.request.Request(URL, data=data.encode(), headers=headers, method='POST')
with urllib.request.urlopen(req) as o:
    print(o.read().decode('utf-8'))
C#
using System;
using System.IO;
using System.Net;
using System.Text;

class AuthExample
{
    static void Main(string[] args)
    {
        var url      = "https://uniterm.test.transafe.com:8123/api/v1/transaction/quick";
        var username = "test_retail|public";
        var password = "publ1ct3st";
        var authData = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(username + ":" + password));
        var json     = "{\"u_device\":\"IPCLIENT:78909876\",\"u_devicetype\":\"ingenico_upp\",\"u_foodamount\":\"92.44\",\"u_id\":\"0IDS425S\",\"action\":\"sale\",\"amount\":\"92.44\",\"nsf\":\"yes\",\"ordernum\":\"6893\",\"u_rcpt\":\"yes\"}";

        ServicePointManager.Expect100Continue = false;
        ServicePointManager.UseNagleAlgorithm = true;
        ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

        var request = WebRequest.Create(url);
        request.Method = "POST";
        request.Headers.Add("Authorization", "Basic " + authData);
        request.ContentType = "application/json";
        request.ContentLength = json.Length;
        Stream requestStream = request.GetRequestStream();
        requestStream.Write(Encoding.ASCII.GetBytes(json), 0, json.Length);
        requestStream.Close();

        using (var response = (HttpWebResponse)request.GetResponse()) {
            Console.WriteLine(response.StatusDescription);

            using (var dataStream = response.GetResponseStream()) {
                using (var reader = new StreamReader(dataStream)) {
                    Console.WriteLine(reader.ReadToEnd());
                }
            }
        }
    }
}

Using the language API credential management increase the transaction processing time. Using the language API will first send the request without authorization data. The server will respond with a 401 authorization data required response. The request will be sent a second time with the authorization data. The extra request that is known to fail adds additional and unnecessary, messaging which increases request processing time.

PHP
<?php
$url = "https://uniterm.test.transafe.com:8123/api/v1/transaction/quick";
$username = "test_retail|public";
$password = "publ1ct3st";
$opts = array(
  "http"=>array(
    "method"=>"POST",
    "header" => "Authorization: Basic " . base64_encode("$username:$password")
    "content"=>array(
      "u_device"=>"IPCLIENT:78909876",
      "u_devicetype"=>"ingenico_upp",
      "u_foodamount"=>"92.44",
      "u_id"=>"0IDS425S",
      "action"=>"sale",
      "amount"=>"92.44",
      "nsf"=>"yes",
      "ordernum"=>"6893",
      "u_rcpt"=>"yes"
    ),
  ),
);
$context = stream_context_create($opts);
$file = file_get_contents($url, false, $context);
echo $file;
?>

HMAC fields

When UniTerm is configured to listen on a public network connection it unauthenticated commands are restricted and must authenticate using an HMAC. Please see the UniTerm Guide for configuration information and HMAC generation.

To prevent the HMAC values from being sent as query arguments, the data should be sent as header fields. Following is the mapping from the UniTerm Guide fields to HTTP headers.

Protocol key HTTP Header equivalent
u_req_sequence X-auth-sequence
u_req_timestamp X-auth-timestamp
u_req_hmacsha256 X-auth-hmacsha256

Device Parameter Loading

When a profile configuration used by a given user/device is updated on the payment server, UniTerm needs to be informed of this change in order to update the settings in the device.

Method 1: Manual

The u_action=deviceload can be issued immediately to by the user account that will be using the updated profile. This will force UniTerm to pull the updated configuration from payment server and load it into the device.

It is recommended integrators directly support this operation and provide a way for clerks to trigger this action. This way they can use configuration changes from the payment server immediately.

Method 2: Automatic

UniTerm will check for configuration changes on an account every 2-3 hours. The exact time is within this range to help stagger load on the payment server. If a change is detected the device will automatically be reloaded.

While the interval is every 2-3 hours the check does not take place until a transaction is performed with the account and using the device. Upon starting the transaction the check takes place and if configuration changes are detected the device will automatically reload the configuration. For most devices this will take less than 1 second and thus will not cause a customer disruption.

The check happens after 2-3 hours since the last check but only on the start of a transaction for several reasons.

  1. Ensures the device is online and accessible
  2. Ensures the user account is still being actively used
  3. Authentication credentials are necessary to perform the check and UniTerm wants to limit the time it holds these in memory.
  4. Reduces load on the payment server because only the most recent configuration will be loaded if it changes multiple times without the device being used to process transactions.

Quick Setup

UniTerm is designed to simply the device integration process including supporting both EMV and contactless payments. It provides a standardized API that work with multiple devices across several device vendors.

UniTerm can be used with a local installation, bundled into an mobile application as a library, or as a cloud service.

Local Installation

  1. Install UniTerm
  2. Copy the uniterm_example.ini from the installation directory into the following directory depending on your platform. The file should be named uniterm.ini when placing in the configuration directory. As indicated in the following full file paths. a. Windows: %APPDATA%/UniTerm/uniterm.ini b. macOS: ~/Library/Application Support/UniTerm/uniterm.ini c. Linux/Unix: ~/.config/UniTerm/uniterm.ini
  3. Make any desired configuration changes to the ini file. The file is documented and explains every section and setting. However, the only setting that needs to be verified and possibly changed is the gateway host setting. The configuration is designed to be secure by default and no chagnes should be necessary to have the UniTerm working out of the box.
  4. Start UniTerm
  5. Connect your device to the system using the connectivity method desired and supported by the device. You may need to use the device specific menus to set or ensure the connectivity method.
  6. Locate where the device is connected to the system. For example, on windows a USB<>SERIAL device will be assigned a COM port. Such as COM3.
  7. With the device location and type now known you can start using UniTerm. Please see the txnquick documentation for a complete example of running a transaction.

Library within Mobile Application

The library package provides a header file with a function that allows sending the key value pairs from the API to UniTerm. Please see the library package documentation for additional information.

Cloud Service

If you're using a cloud service offering of UniTerm no setup of UniTerm is required. The device needs to support cloud connections. The device also needs to be configured to connect to the cloud system. Typically, this is done by loading a configuration package to the device. Ingencio devices will have a 'tgz' package with all necessary configuration contained within.

A configured device will automatically connect to the cloud system. At which point the device can be used with the web based POS or virtual terminal being offered. Additionally, some devices can function as stand alone devices that do not require additional web based systems to initiate transactions. Please speak with your UniTerm representative on how to convert a cloud device into a stand alone cloud device.

Transaction

Transaction operations

Cancel

Attempts to cancel an outstanding transaction request

Requires username, password and u_id, which must match the pending request.

This will return u_errorcode=PENDING_TRAN if the transaction cannot be canceled. This could happen, for instance, while waiting on a response from the Payment Server, or if the device doesn't support canceling the outstanding request.

libmonetra KVS equivalent for endpoint

  • u_action = cancel
Authorizations:
basic_auth
path Parameters
u_id
required
string
Example: 1234

A unique ID (generated by the calling application) that identifies the transaction. This is used for checking the status or canceling the transaction. Without this ID, the transaction state cannot be queried.

Responses

Request samples

curl -X POST 'https://uniterm.test.transafe.com:8123/api/v1/transaction/U656789324/cancel' --basic -u 'test_retail|public:publ1ct3st' -d ''

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Cancel

Attempts to cancel an outstanding transaction request

Requires username, password and u_id, which must match the pending request.

This will return u_errorcode=PENDING_TRAN if the transaction cannot be canceled. This could happen, for instance, while waiting on a response from the Payment Server, or if the device doesn't support canceling the outstanding request.

libmonetra KVS equivalent for endpoint

  • u_action = cancel
Authorizations:
basic_auth
path Parameters
u_id
required
string
Example: 1234

A unique ID (generated by the calling application) that identifies the transaction. This is used for checking the status or canceling the transaction. Without this ID, the transaction state cannot be queried.

Responses

Request samples

curl -X DELETE 'https://uniterm.test.transafe.com:8123/api/v1/transaction/U656789324' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Non-Financial Card Data

Prompts for card entry and returns non-financial card data

This is only valid on non-financial cards, like manager cards or private-label gift cards, that are not processed through the Payment Server.

The card must be swiped, and the reader must be configured to return the card in unencrypted form.

libmonetra KVS equivalent for endpoint

  • u_action = cardrequest
Authorizations:
basic_auth
Request Body schema: application/json
u_device
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner

Responses

Request samples

Content type
application/json
{
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "trackdata": "string"
}

Set an external selection

Specify an external selection made by the customer

Used when the u_flag EXTERNALSELECT is specified. When selection of options external to the device is requested, this operation informs what the customer selected.

This flag and operation are only necessary when using a device that does not have a display or buttons for the customer to make a selection. If the flag is not specified, a default selection will be made on behalf of the customer.

If the flag is specified and an external selection is requested via the status operation, then this operation must be used to relay the customer's selection.

libmonetra KVS equivalent for endpoint

  • u_action = externalselect
Authorizations:
basic_auth
path Parameters
u_id
required
string
Example: 1234

A unique ID (generated by the calling application) that identifies the transaction. This is used for checking the status or canceling the transaction. Without this ID, the transaction state cannot be queried.

Request Body schema: application/json
u_selection
required
string

Chosen external selection ID

Responses

Request samples

Content type
application/json
{
  • "u_selection": "1"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Transaction Status

Requests the current status of a pending transaction

Requires username, password and u_id fields, which must match the pending request. This will provide a textual verbiage response suitable for clerk display.

This will normally return a u_errorcode of SUCCESS when either the transaction is still in-progress or UniTerm is in a cleanup phase after a transaction. Will return a value of UID_NOT_FOUND if the request is no longer being processed.

libmonetra KVS equivalent for endpoint

  • u_action = status
Authorizations:
basic_auth
path Parameters
u_id
required
string
Example: 1234

A unique ID (generated by the calling application) that identifies the transaction. This is used for checking the status or canceling the transaction. Without this ID, the transaction state cannot be queried.

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/transaction/U656789324/status' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "u_cancelable": "yes",
  • "u_status": "WORKING",
  • "u_external_select_rec": "string",
  • "u_external_select": "string"
}

Transaction Finish

Requests to finish a QuickChip transaction

Requires the integrator send the same u_id as was sent with the initial txnstart request. The integrator can choose to send additional parameters to pass through to the Payment Server with this request based on information returned from txnstart (e.g. card type). Will return the same response parameters as txnrequest.

libmonetra KVS equivalent for endpoint

  • u_action = txnfinish
Authorizations:
basic_auth
path Parameters
u_id
required
string
Example: 1234

A unique ID (generated by the calling application) that identifies the transaction. This is used for checking the status or canceling the transaction. Without this ID, the transaction state cannot be queried.

Request Body schema: application/json
nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
laneid
string\d+

Identifier for the register/lane running the transaction

Mastercard requires that each register or lane at a merchant's location be uniquely identified. This should be a numeric value no more than 8 digits in length. However, some processors cannot support more than 2 or 4 digits. It should be sent on all transactions, as it is not possible to know the card type prior to starting a transaction.

ordernum
string <= 128 characters

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to UniTerm, an order number should be sent on all transactions.

An order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

amount
required
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tax
string(?i)NT|\d*(\.\d{0,2})?

Amount of tax that applies to the order

The value 'NT' without the quotes indicates a non-taxable (tax exempt) transaction.

Requires:

  • amount
examount
string\d+(\.\d{0,2})?

Extra amount.

Typically used for Retail and Restaurant tipping

Requires:

  • amount
surchargeamount
string\d+(\.\d{0,2})?

Amount of funds being received as a surcharge

Surcharging rules are governed by the card brands. Compliance with brand rules need to be handled by the integrator because they can be highly industry and business type specific.

Also, some times when people talk about surcharging, they are really talking about service fees, convenience fees, or cash discounts, which all have different rules even though they are closely related.

Surcharges are the ONLY type that requires registration with the card brands and requires you pass the data along to the processing institution and therefore onto the card issuer. This is what this field does, is just pass that data along for transactions matching the surcharge classification (but not service fees, convenience fees, or cash discounts).

Requires:

  • amount
u_foodamount
string(?i)maybe|\d+(\.\d{0,2})?

Food-qualified amount (E.g. 1.00), or 'maybe' to indicate possible EBT-qualified full or partial order

If qualified amount is known, this is the amount of qualified food purchases for EBT Food Stamps (SNAP). It must be provided in order to allow customer prompting for EBT Food Stamp payments when an EBT card is presented. Otherwise, only EBT Cash Benefits will be available for payment.

This is a subset of the transaction amount. Meaning if the transaction is $15.00 and there is $10.00 worth of food qualified items, amount=15.00 and u_foodamount=10.00. It is not possible for the u_foodamount to exceed amount because the food amount is informational about how much of amount is food qualified for payment with EBT Food Stamps (SNAP).

During a txnstart, the food amount may not yet be known. However, to enable EBT prompting, a special value of maybe can be passed, followed by the real amount in txnfinish.

If the amount passed in txnfinish is 0, but EBT Food Stamps was selected by the cardholder, the transaction will be aborted.

u_tipeligibleamount
string\d+(\.\d{0,2})?

Amount of the order that can be used for tip calculation

Used when part of the order is not tip eligible or with a split payment method that's not capable of adding a tip.

An example of when part of the order is not tip eligible

A beauty salon wants to prompt for tip, but the order also has products that shouldn't be included in the tip-percent calculation. The customer would only tip on the service, not any products they're purchasing.

If the customer is prompted for a tip, the order total will still show on the screen, so the clerk will need to let the customer know that the tip is only going to be applied to the eligible part of the order. The screen doesn't show only the tip-eligible amount, because the customer could be confused if part of the order is missing, or if the order suddenly jumps to a much larger amount after entering their tip.

An example of split payment

A customer wants to pay part of the order with a gift card. They want to use the total amount on the gift card and pay the remainder with their credit card. The total tip should be applied to the credit card part of the transaction.

The gift card balance being exhausted does not leave room for the tip. Further, the customer could be confused by having to leave a tip on each part of the split order.

In this situation only one payment should prompt for tip. The rest should use the u_flag=NOTIP to disable tip prompting.

If the customer is prompted for a tip, the payment total not the order total will still show on the screen, so the clerk will need to let the customer know that the tip is going to be applied to an amount greater than what is shown on screen. The screen only shows the payment amount not the order amount, because the customer could be confused if they keep seeing the order total when they are only paying part of the total with that payment method.

Notes

If not sent, the entire amount will be used for any tip calculations. If sent as 0, tip prompting will be suppressed.

Clerk requirements

When using u_tipeligibleamount the clerk must clearly inform the customer the order total not the total shown on the device screen is used when calculating the tip percentage.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "nsf": "yes",
  • "laneid": "4",
  • "ordernum": "A13DDES345",
  • "amount": "19.92",
  • "tax": "1.29",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "u_foodamount": "maybe",
  • "u_tipeligibleamount": "string",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "msoft_code": "INT_SUCCESS",
  • "phard_code": "SUCCESS",
  • "authamount": "6.50",
  • "account": "XXXXXXXXXXXX1234",
  • "ttid": "96748596765467",
  • "u_emv_chip_malfunction": "yes",
  • "u_need_signature": "yes",
  • "u_tip": "string",
  • "cardtype": "VISA",
  • "u_cardclass": "UNKNOWN",
  • "u_cashback": "string",
  • "u_flowflags": "SIGCAPTURED",
  • "u_standin": "yes",
  • "u_wasfood": "yes",
  • "property1": "string",
  • "property2": "string"
}

Transaction Quick

Performs a full Transaction Request with cardholder's data

This will request that a transaction be performed. All normal Payment Server transaction parameters that may be required for processing or to comply with interchange requirements (e.g. action, amount, nsf, ordernum, etc) should be included in the request. Sensitive data, explicitly, should not be sent (e.g. trackdata, account, CVV2, PIN), as that data will be retrieved by UniTerm via a card-entry device and then forwarded to the Payment Server as part of the transaction request.

This operation is functionally similar to txnrequest. However, internally, it follows a QuickChip flow (like txnstart + txnfinish), which allows the cardholder to remove their card earlier. This may make a transaction appear to be faster to an end user.

libmonetra KVS equivalent for endpoint

  • u_action = txnquick
Authorizations:
basic_auth
Request Body schema: application/json
action
string

Action the Payment Server should perform on the captured data

u_device
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
laneid
string\d+

Identifier for the register/lane running the transaction

Mastercard requires that each register or lane at a merchant's location be uniquely identified. This should be a numeric value no more than 8 digits in length. However, some processors cannot support more than 2 or 4 digits. It should be sent on all transactions, as it is not possible to know the card type prior to starting a transaction.

ordernum
string <= 128 characters

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to UniTerm, an order number should be sent on all transactions.

An order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

u_flags
string
Enum: "DEVICEONLY" "GUIONLY" "KEY" "AVS" "CVV" "GIFTPIN" "NOEXPDATE" "NOTIP" "NOCASHBACK" "NOCONFIRM" "NOSIGNATURE" "DELAYRESPONSE" "CARDMETA" "NOSTANDIN" "PERSISTDEVICE" "EXTERNALSELECT" "DENYLISTQUEUE"

Multiple flags may be sent per data ticket request. All flags are separated by a pipe (|) symbol.

Flag values (pipe separated):

  • DEVICEONLY - Suppress display of clerk-facing prompting and feedback, also known as GUI Mode. For instance, on a swipe request, no swipe dialog would be presented nor would the clerk be informed of the status for customer-facing device interaction. Note: Setting this mode will prevent keyboard emulation readers from working. It will also prevent the ability for accepting clerk-keyed input via a keyboard. On Android, iOS, and UniTerm launched in console mode, this flag is automatically implied, as none of those support a GUI mode of operation.
  • GUIONLY - Suppress use of a referenced physical device. This flag can be used to utilize the physical device's UniTerm license for a clerk-facing GUI request, without using the device itself for card input. Without this flag, the GUI would register an additional UniTerm license based on the machine's unique ID.
  • KEY - Perform capture of manually-keyed data. Not valid on cardrequest. If an account or expdate field is passed in on the request to UniTerm, the fields will be pre-populated in GUI mode. Note: If a manually keyed EBT card is to be entered for a Food Stamp (SNAP) transaction, pass the qualified food amount via u_foodamount in order to go through the EBT flow and PIN prompting. Do NOT pass u_foodamount if you are NOT intending to run a Food Stamp transaction as keyed.
  • AVS - Request AVS data. Only allowed on keyed transactions. If a street or zip field is passed in on the request to UniTerm, those fields will be pre-populated in GUI mode.
  • CVV - Request for CVV data. Only allowed on keyed transactions.
  • GIFTPIN - Request a PIN for gift cards, when a gift card is presented. Does nothing if a different card type is presented.
  • NOEXPDATE - Disable expiration date prompting.
  • NOTIP - Disable tip prompting. This will override the merch_tippercent option in the Payment Server merchant account configuration.
  • NOCASHBACK - Disable cashback prompting. This will override the merch_cashbackmax option in the Payment Server merchant account configuration.
  • NOCONFIRM - When performing a QuickChip finalization via txnfinish, do not prompt the cardholder to confirm the amount prior to running the authorization.
  • NOSIGNATURE - If using a signature-capable device, but an integrator does not want to use the auto signature-capture capabilities in the UniTerm flow, treat the device as if it is not capable of accepting a signature. The u_need_signature response flag will be set appropriately for the transaction requirements.
  • DELAYRESPONSE - Send the transaction response back to the caller after the device has been closed. The device can be used immediately for a subsequent transaction with this flag. Otherwise, device closing will happen in the background, which will hold a lock on the device for at least 100ms, possibly longer.
  • CARDMETA - Request the card metadata directly from the Payment Server (v8.9.0+) rather than relying on less-detailed internal information. The relevant metadata would be from a Global BIN table, which contains information such as if a card is Debit-capable, HSA/FSA-capable, and so on. When used during a txnstart request, it allows an integrator to make decisions based on the card presented (such as for support of Debt Repayment or Healthcare transactions). When used during a txnrequest or txnquick, it optimizes the flow on transactions such as not prompting for Debit on a swipe transaction if the card is not debit capable.
  • NOSTANDIN - Transaction is not eligible for standin approval
  • PERSISTDEVICE - Maintain a persistent device connection
  • EXTERNALSELECT - Customer input for selection can be handled externally to the device. The status action must be polled to determine when and what external prompting should take place. The response needs to be provided to the external response action once the customer has made their selection.
  • DENYLISTQUEUE - Check if card is on block list and if not queue the transaction for later processing
u_language
string
Enum: "en" "fr" "es" "de" "it"

Used to override terminal defaults for display of text prompts. Not all devices support all languages.

Values:

  • en - English
  • fr - French
  • es - Spanish
  • de - German
  • it - Italian
u_id
string

A unique ID (generated by the calling application) that identifies the transaction. This is used for checking the status or canceling the transaction. Without this ID, the transaction state cannot be queried.

u_rcpt
string

The rcpt key/value pair is sent in the request to indicate whether or not to output a series of pre-formatted receipt blocks, as well as optional formatting requirements.

A value of no (the default) will not return a receipt.

A value of yes will return a receipt with a default format.

All other values are key/value pairs indicating formatting configurations, separated by semicolons, as in this example:

rcpt=type=plain;line_len=24;use_merch_lang=no;line_break="\n"

rcpt=type=plain|html

Receipt configuration options:

  • type - Values can be specified pipe-delimited (|) if more than one receipt output format is desired. When specifying more than one type, the response keys will indicate the format in the key name, but if only one type is specified, the type is omitted.
    • plain - Plain Text (default).
    • html - HTML. Needs style sheet applied.
    • xml - XML. Suitable for XSLT transformations. Typically used to generate complex HTML when CSS alone is not capable of providing the desired formatting.
    • json - JSON. Typically used for easy manipulation with JavaScript.
  • line_len - Only relevant for type=plain. Number of characters per line. Default is 24.
  • line_break - Only relevant for type=plain. Character sequence for newlines. Default is \r\n.
  • use_merch_lang - True/False. Use the merchant's selected language rather than the cardholder's language for the receipt. Default is True.
amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tax
string(?i)NT|\d*(\.\d{0,2})?

Amount of tax that applies to the order

The value 'NT' without the quotes indicates a non-taxable (tax exempt) transaction.

Requires:

  • amount
examount
string\d+(\.\d{0,2})?

Extra amount.

Typically used for Retail and Restaurant tipping

Requires:

  • amount
surchargeamount
string\d+(\.\d{0,2})?

Amount of funds being received as a surcharge

Surcharging rules are governed by the card brands. Compliance with brand rules need to be handled by the integrator because they can be highly industry and business type specific.

Also, some times when people talk about surcharging, they are really talking about service fees, convenience fees, or cash discounts, which all have different rules even though they are closely related.

Surcharges are the ONLY type that requires registration with the card brands and requires you pass the data along to the processing institution and therefore onto the card issuer. This is what this field does, is just pass that data along for transactions matching the surcharge classification (but not service fees, convenience fees, or cash discounts).

Requires:

  • amount
u_foodamount
string(?i)maybe|\d+(\.\d{0,2})?

Food-qualified amount (E.g. 1.00), or 'maybe' to indicate possible EBT-qualified full or partial order

If qualified amount is known, this is the amount of qualified food purchases for EBT Food Stamps (SNAP). It must be provided in order to allow customer prompting for EBT Food Stamp payments when an EBT card is presented. Otherwise, only EBT Cash Benefits will be available for payment.

This is a subset of the transaction amount. Meaning if the transaction is $15.00 and there is $10.00 worth of food qualified items, amount=15.00 and u_foodamount=10.00. It is not possible for the u_foodamount to exceed amount because the food amount is informational about how much of amount is food qualified for payment with EBT Food Stamps (SNAP).

During a txnstart, the food amount may not yet be known. However, to enable EBT prompting, a special value of maybe can be passed, followed by the real amount in txnfinish.

If the amount passed in txnfinish is 0, but EBT Food Stamps was selected by the cardholder, the transaction will be aborted.

u_tipeligibleamount
string\d+(\.\d{0,2})?

Amount of the order that can be used for tip calculation

Used when part of the order is not tip eligible or with a split payment method that's not capable of adding a tip.

An example of when part of the order is not tip eligible

A beauty salon wants to prompt for tip, but the order also has products that shouldn't be included in the tip-percent calculation. The customer would only tip on the service, not any products they're purchasing.

If the customer is prompted for a tip, the order total will still show on the screen, so the clerk will need to let the customer know that the tip is only going to be applied to the eligible part of the order. The screen doesn't show only the tip-eligible amount, because the customer could be confused if part of the order is missing, or if the order suddenly jumps to a much larger amount after entering their tip.

An example of split payment

A customer wants to pay part of the order with a gift card. They want to use the total amount on the gift card and pay the remainder with their credit card. The total tip should be applied to the credit card part of the transaction.

The gift card balance being exhausted does not leave room for the tip. Further, the customer could be confused by having to leave a tip on each part of the split order.

In this situation only one payment should prompt for tip. The rest should use the u_flag=NOTIP to disable tip prompting.

If the customer is prompted for a tip, the payment total not the order total will still show on the screen, so the clerk will need to let the customer know that the tip is going to be applied to an amount greater than what is shown on screen. The screen only shows the payment amount not the order amount, because the customer could be confused if they keep seeing the order total when they are only paying part of the total with that payment method.

Notes

If not sent, the entire amount will be used for any tip calculations. If sent as 0, tip prompting will be suppressed.

Clerk requirements

When using u_tipeligibleamount the clerk must clearly inform the customer the order total not the total shown on the device screen is used when calculating the tip percentage.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "action": "sale",
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp",
  • "nsf": "yes",
  • "laneid": "4",
  • "ordernum": "A13DDES345",
  • "u_flags": "NOSIGNATURE|CARDMETA|DELAYRESPONSE",
  • "u_language": "en",
  • "u_id": "1234",
  • "u_rcpt": "yes",
  • "amount": "19.92",
  • "tax": "1.29",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "u_foodamount": "maybe",
  • "u_tipeligibleamount": "string",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "msoft_code": "INT_SUCCESS",
  • "phard_code": "SUCCESS",
  • "authamount": "6.50",
  • "account": "XXXXXXXXXXXX1234",
  • "ttid": "96748596765467",
  • "u_emv_chip_malfunction": "yes",
  • "u_need_signature": "yes",
  • "u_tip": "string",
  • "cardtype": "VISA",
  • "u_cardclass": "UNKNOWN",
  • "u_cashback": "string",
  • "u_flowflags": "SIGCAPTURED",
  • "u_standin": "yes",
  • "u_wasfood": "yes",
  • "property1": "string",
  • "property2": "string"
}

Transaction Request

Performs a full Transaction Request with cardholder's data

This will request that a transaction be performed. All normal Payment Server transaction parameters that may be required for processing or to comply with interchange requirements (e.g. action, amount, nsf, ordernum, etc) should be included in the request. Sensitive data, explicitly, should not be sent (e.g. trackdata, account, CVV2, PIN), as that data will be retrieved by UniTerm via either the GUI or a card-entry device and then forwarded to the Payment Server as part of the transaction request.

UniTerm will fully control the transaction flow and user prompting. This request should only be used when card data entry is required as part of the transaction. For other operations, passthrough may be a more appropriate action.

libmonetra KVS equivalent for endpoint

  • u_action = txnrequest
Authorizations:
basic_auth
Request Body schema: application/json
action
string

Action the Payment Server should perform on the captured data

u_device
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
nsf
string
Enum: "yes" "no"

Approve transactions even if there are non-sufficient funds (NSF). This will result in a partial approval if there are not enough funds to cover the full requested amount, in which case an authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

Gift cards default to yes while other cards default to no if not sent.

If a partial approval is received, it will automatically be reversed internally and the returned decline will have msoft_code=NSFAUTODENY set.

Values:

  • yes - Allow partial approvals
  • no - Request that partial approvals are not returned
laneid
string\d+

Identifier for the register/lane running the transaction

Mastercard requires that each register or lane at a merchant's location be uniquely identified. This should be a numeric value no more than 8 digits in length. However, some processors cannot support more than 2 or 4 digits. It should be sent on all transactions, as it is not possible to know the card type prior to starting a transaction.

ordernum
string <= 128 characters

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to UniTerm, an order number should be sent on all transactions.

An order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

u_flags
string
Enum: "DEVICEONLY" "GUIONLY" "KEY" "AVS" "CVV" "GIFTPIN" "NOEXPDATE" "NOTIP" "NOCASHBACK" "NOCONFIRM" "NOSIGNATURE" "DELAYRESPONSE" "CARDMETA" "NOSTANDIN" "PERSISTDEVICE" "EXTERNALSELECT" "DENYLISTQUEUE"

Multiple flags may be sent per data ticket request. All flags are separated by a pipe (|) symbol.

Flag values (pipe separated):

  • DEVICEONLY - Suppress display of clerk-facing prompting and feedback, also known as GUI Mode. For instance, on a swipe request, no swipe dialog would be presented nor would the clerk be informed of the status for customer-facing device interaction. Note: Setting this mode will prevent keyboard emulation readers from working. It will also prevent the ability for accepting clerk-keyed input via a keyboard. On Android, iOS, and UniTerm launched in console mode, this flag is automatically implied, as none of those support a GUI mode of operation.
  • GUIONLY - Suppress use of a referenced physical device. This flag can be used to utilize the physical device's UniTerm license for a clerk-facing GUI request, without using the device itself for card input. Without this flag, the GUI would register an additional UniTerm license based on the machine's unique ID.
  • KEY - Perform capture of manually-keyed data. Not valid on cardrequest. If an account or expdate field is passed in on the request to UniTerm, the fields will be pre-populated in GUI mode. Note: If a manually keyed EBT card is to be entered for a Food Stamp (SNAP) transaction, pass the qualified food amount via u_foodamount in order to go through the EBT flow and PIN prompting. Do NOT pass u_foodamount if you are NOT intending to run a Food Stamp transaction as keyed.
  • AVS - Request AVS data. Only allowed on keyed transactions. If a street or zip field is passed in on the request to UniTerm, those fields will be pre-populated in GUI mode.
  • CVV - Request for CVV data. Only allowed on keyed transactions.
  • GIFTPIN - Request a PIN for gift cards, when a gift card is presented. Does nothing if a different card type is presented.
  • NOEXPDATE - Disable expiration date prompting.
  • NOTIP - Disable tip prompting. This will override the merch_tippercent option in the Payment Server merchant account configuration.
  • NOCASHBACK - Disable cashback prompting. This will override the merch_cashbackmax option in the Payment Server merchant account configuration.
  • NOCONFIRM - When performing a QuickChip finalization via txnfinish, do not prompt the cardholder to confirm the amount prior to running the authorization.
  • NOSIGNATURE - If using a signature-capable device, but an integrator does not want to use the auto signature-capture capabilities in the UniTerm flow, treat the device as if it is not capable of accepting a signature. The u_need_signature response flag will be set appropriately for the transaction requirements.
  • DELAYRESPONSE - Send the transaction response back to the caller after the device has been closed. The device can be used immediately for a subsequent transaction with this flag. Otherwise, device closing will happen in the background, which will hold a lock on the device for at least 100ms, possibly longer.
  • CARDMETA - Request the card metadata directly from the Payment Server (v8.9.0+) rather than relying on less-detailed internal information. The relevant metadata would be from a Global BIN table, which contains information such as if a card is Debit-capable, HSA/FSA-capable, and so on. When used during a txnstart request, it allows an integrator to make decisions based on the card presented (such as for support of Debt Repayment or Healthcare transactions). When used during a txnrequest or txnquick, it optimizes the flow on transactions such as not prompting for Debit on a swipe transaction if the card is not debit capable.
  • NOSTANDIN - Transaction is not eligible for standin approval
  • PERSISTDEVICE - Maintain a persistent device connection
  • EXTERNALSELECT - Customer input for selection can be handled externally to the device. The status action must be polled to determine when and what external prompting should take place. The response needs to be provided to the external response action once the customer has made their selection.
  • DENYLISTQUEUE - Check if card is on block list and if not queue the transaction for later processing
u_language
string
Enum: "en" "fr" "es" "de" "it"

Used to override terminal defaults for display of text prompts. Not all devices support all languages.

Values:

  • en - English
  • fr - French
  • es - Spanish
  • de - German
  • it - Italian
u_id
string

A unique ID (generated by the calling application) that identifies the transaction. This is used for checking the status or canceling the transaction. Without this ID, the transaction state cannot be queried.

u_rcpt
string

The rcpt key/value pair is sent in the request to indicate whether or not to output a series of pre-formatted receipt blocks, as well as optional formatting requirements.

A value of no (the default) will not return a receipt.

A value of yes will return a receipt with a default format.

All other values are key/value pairs indicating formatting configurations, separated by semicolons, as in this example:

rcpt=type=plain;line_len=24;use_merch_lang=no;line_break="\n"

rcpt=type=plain|html

Receipt configuration options:

  • type - Values can be specified pipe-delimited (|) if more than one receipt output format is desired. When specifying more than one type, the response keys will indicate the format in the key name, but if only one type is specified, the type is omitted.
    • plain - Plain Text (default).
    • html - HTML. Needs style sheet applied.
    • xml - XML. Suitable for XSLT transformations. Typically used to generate complex HTML when CSS alone is not capable of providing the desired formatting.
    • json - JSON. Typically used for easy manipulation with JavaScript.
  • line_len - Only relevant for type=plain. Number of characters per line. Default is 24.
  • line_break - Only relevant for type=plain. Character sequence for newlines. Default is \r\n.
  • use_merch_lang - True/False. Use the merchant's selected language rather than the cardholder's language for the receipt. Default is True.
amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tax
string(?i)NT|\d*(\.\d{0,2})?

Amount of tax that applies to the order

The value 'NT' without the quotes indicates a non-taxable (tax exempt) transaction.

Requires:

  • amount
examount
string\d+(\.\d{0,2})?

Extra amount.

Typically used for Retail and Restaurant tipping

Requires:

  • amount
surchargeamount
string\d+(\.\d{0,2})?

Amount of funds being received as a surcharge

Surcharging rules are governed by the card brands. Compliance with brand rules need to be handled by the integrator because they can be highly industry and business type specific.

Also, some times when people talk about surcharging, they are really talking about service fees, convenience fees, or cash discounts, which all have different rules even though they are closely related.

Surcharges are the ONLY type that requires registration with the card brands and requires you pass the data along to the processing institution and therefore onto the card issuer. This is what this field does, is just pass that data along for transactions matching the surcharge classification (but not service fees, convenience fees, or cash discounts).

Requires:

  • amount
u_foodamount
string(?i)maybe|\d+(\.\d{0,2})?

Food-qualified amount (E.g. 1.00), or 'maybe' to indicate possible EBT-qualified full or partial order

If qualified amount is known, this is the amount of qualified food purchases for EBT Food Stamps (SNAP). It must be provided in order to allow customer prompting for EBT Food Stamp payments when an EBT card is presented. Otherwise, only EBT Cash Benefits will be available for payment.

This is a subset of the transaction amount. Meaning if the transaction is $15.00 and there is $10.00 worth of food qualified items, amount=15.00 and u_foodamount=10.00. It is not possible for the u_foodamount to exceed amount because the food amount is informational about how much of amount is food qualified for payment with EBT Food Stamps (SNAP).

During a txnstart, the food amount may not yet be known. However, to enable EBT prompting, a special value of maybe can be passed, followed by the real amount in txnfinish.

If the amount passed in txnfinish is 0, but EBT Food Stamps was selected by the cardholder, the transaction will be aborted.

u_tipeligibleamount
string\d+(\.\d{0,2})?

Amount of the order that can be used for tip calculation

Used when part of the order is not tip eligible or with a split payment method that's not capable of adding a tip.

An example of when part of the order is not tip eligible

A beauty salon wants to prompt for tip, but the order also has products that shouldn't be included in the tip-percent calculation. The customer would only tip on the service, not any products they're purchasing.

If the customer is prompted for a tip, the order total will still show on the screen, so the clerk will need to let the customer know that the tip is only going to be applied to the eligible part of the order. The screen doesn't show only the tip-eligible amount, because the customer could be confused if part of the order is missing, or if the order suddenly jumps to a much larger amount after entering their tip.

An example of split payment

A customer wants to pay part of the order with a gift card. They want to use the total amount on the gift card and pay the remainder with their credit card. The total tip should be applied to the credit card part of the transaction.

The gift card balance being exhausted does not leave room for the tip. Further, the customer could be confused by having to leave a tip on each part of the split order.

In this situation only one payment should prompt for tip. The rest should use the u_flag=NOTIP to disable tip prompting.

If the customer is prompted for a tip, the payment total not the order total will still show on the screen, so the clerk will need to let the customer know that the tip is going to be applied to an amount greater than what is shown on screen. The screen only shows the payment amount not the order amount, because the customer could be confused if they keep seeing the order total when they are only paying part of the total with that payment method.

Notes

If not sent, the entire amount will be used for any tip calculations. If sent as 0, tip prompting will be suppressed.

Clerk requirements

When using u_tipeligibleamount the clerk must clearly inform the customer the order total not the total shown on the device screen is used when calculating the tip percentage.

property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "action": "sale",
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp",
  • "nsf": "yes",
  • "laneid": "4",
  • "ordernum": "A13DDES345",
  • "u_flags": "NOSIGNATURE|CARDMETA|DELAYRESPONSE",
  • "u_language": "en",
  • "u_id": "1234",
  • "u_rcpt": "yes",
  • "amount": "19.92",
  • "tax": "1.29",
  • "examount": "0.33",
  • "surchargeamount": "1.25",
  • "u_foodamount": "maybe",
  • "u_tipeligibleamount": "string",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "trackdata": "string",
  • "msoft_code": "INT_SUCCESS",
  • "phard_code": "SUCCESS",
  • "authamount": "6.50",
  • "account": "XXXXXXXXXXXX1234",
  • "ttid": "96748596765467",
  • "u_emv_chip_malfunction": "yes",
  • "u_need_signature": "yes",
  • "u_tip": "string",
  • "cardtype": "VISA",
  • "u_cardclass": "UNKNOWN",
  • "u_cashback": "string",
  • "u_flowflags": "SIGCAPTURED",
  • "u_standin": "yes",
  • "u_wasfood": "yes",
  • "property1": "string",
  • "property2": "string"
}

Transaction Start

Requests to start a QuickChip transaction with cardholder's data

This is similar in function to a txnrequest message, but it does not accept a transaction amount. It needs to be followed up with a txnfinish or cancel request. Once a card is presented and the cardholder has completed any necessary verification and removed their card, a response will be returned with card information metadata such as the card type, some basic EMV card parameters, and the last 4 digits of the card number.

Though the purpose of this request is to support QuickChip, it still supports non-EMV transactions.

A u_id unique parameter is required to be sent with this request for completing the transaction.

libmonetra KVS equivalent for endpoint

  • u_action = txnstart
Authorizations:
basic_auth
Request Body schema: application/json
action
string

Action the Payment Server should perform on the captured data

u_device
required
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
u_flags
string
Enum: "DEVICEONLY" "GUIONLY" "KEY" "AVS" "CVV" "GIFTPIN" "NOEXPDATE" "NOTIP" "NOCASHBACK" "NOCONFIRM" "NOSIGNATURE" "DELAYRESPONSE" "CARDMETA" "NOSTANDIN" "PERSISTDEVICE" "EXTERNALSELECT" "DENYLISTQUEUE"

Multiple flags may be sent per data ticket request. All flags are separated by a pipe (|) symbol.

Flag values (pipe separated):

  • DEVICEONLY - Suppress display of clerk-facing prompting and feedback, also known as GUI Mode. For instance, on a swipe request, no swipe dialog would be presented nor would the clerk be informed of the status for customer-facing device interaction. Note: Setting this mode will prevent keyboard emulation readers from working. It will also prevent the ability for accepting clerk-keyed input via a keyboard. On Android, iOS, and UniTerm launched in console mode, this flag is automatically implied, as none of those support a GUI mode of operation.
  • GUIONLY - Suppress use of a referenced physical device. This flag can be used to utilize the physical device's UniTerm license for a clerk-facing GUI request, without using the device itself for card input. Without this flag, the GUI would register an additional UniTerm license based on the machine's unique ID.
  • KEY - Perform capture of manually-keyed data. Not valid on cardrequest. If an account or expdate field is passed in on the request to UniTerm, the fields will be pre-populated in GUI mode. Note: If a manually keyed EBT card is to be entered for a Food Stamp (SNAP) transaction, pass the qualified food amount via u_foodamount in order to go through the EBT flow and PIN prompting. Do NOT pass u_foodamount if you are NOT intending to run a Food Stamp transaction as keyed.
  • AVS - Request AVS data. Only allowed on keyed transactions. If a street or zip field is passed in on the request to UniTerm, those fields will be pre-populated in GUI mode.
  • CVV - Request for CVV data. Only allowed on keyed transactions.
  • GIFTPIN - Request a PIN for gift cards, when a gift card is presented. Does nothing if a different card type is presented.
  • NOEXPDATE - Disable expiration date prompting.
  • NOTIP - Disable tip prompting. This will override the merch_tippercent option in the Payment Server merchant account configuration.
  • NOCASHBACK - Disable cashback prompting. This will override the merch_cashbackmax option in the Payment Server merchant account configuration.
  • NOCONFIRM - When performing a QuickChip finalization via txnfinish, do not prompt the cardholder to confirm the amount prior to running the authorization.
  • NOSIGNATURE - If using a signature-capable device, but an integrator does not want to use the auto signature-capture capabilities in the UniTerm flow, treat the device as if it is not capable of accepting a signature. The u_need_signature response flag will be set appropriately for the transaction requirements.
  • DELAYRESPONSE - Send the transaction response back to the caller after the device has been closed. The device can be used immediately for a subsequent transaction with this flag. Otherwise, device closing will happen in the background, which will hold a lock on the device for at least 100ms, possibly longer.
  • CARDMETA - Request the card metadata directly from the Payment Server (v8.9.0+) rather than relying on less-detailed internal information. The relevant metadata would be from a Global BIN table, which contains information such as if a card is Debit-capable, HSA/FSA-capable, and so on. When used during a txnstart request, it allows an integrator to make decisions based on the card presented (such as for support of Debt Repayment or Healthcare transactions). When used during a txnrequest or txnquick, it optimizes the flow on transactions such as not prompting for Debit on a swipe transaction if the card is not debit capable.
  • NOSTANDIN - Transaction is not eligible for standin approval
  • PERSISTDEVICE - Maintain a persistent device connection
  • EXTERNALSELECT - Customer input for selection can be handled externally to the device. The status action must be polled to determine when and what external prompting should take place. The response needs to be provided to the external response action once the customer has made their selection.
  • DENYLISTQUEUE - Check if card is on block list and if not queue the transaction for later processing
u_language
string
Enum: "en" "fr" "es" "de" "it"

Used to override terminal defaults for display of text prompts. Not all devices support all languages.

Values:

  • en - English
  • fr - French
  • es - Spanish
  • de - German
  • it - Italian
u_foodamount
string(?i)maybe|\d+(\.\d{0,2})?

Food-qualified amount (E.g. 1.00), or 'maybe' to indicate possible EBT-qualified full or partial order

If qualified amount is known, this is the amount of qualified food purchases for EBT Food Stamps (SNAP). It must be provided in order to allow customer prompting for EBT Food Stamp payments when an EBT card is presented. Otherwise, only EBT Cash Benefits will be available for payment.

This is a subset of the transaction amount. Meaning if the transaction is $15.00 and there is $10.00 worth of food qualified items, amount=15.00 and u_foodamount=10.00. It is not possible for the u_foodamount to exceed amount because the food amount is informational about how much of amount is food qualified for payment with EBT Food Stamps (SNAP).

During a txnstart, the food amount may not yet be known. However, to enable EBT prompting, a special value of maybe can be passed, followed by the real amount in txnfinish.

If the amount passed in txnfinish is 0, but EBT Food Stamps was selected by the cardholder, the transaction will be aborted.

u_id
required
string

A unique ID (generated by the calling application) that identifies the transaction. This is used for checking the status or canceling the transaction. Without this ID, the transaction state cannot be queried.

u_rcpt
string

The rcpt key/value pair is sent in the request to indicate whether or not to output a series of pre-formatted receipt blocks, as well as optional formatting requirements.

A value of no (the default) will not return a receipt.

A value of yes will return a receipt with a default format.

All other values are key/value pairs indicating formatting configurations, separated by semicolons, as in this example:

rcpt=type=plain;line_len=24;use_merch_lang=no;line_break="\n"

rcpt=type=plain|html

Receipt configuration options:

  • type - Values can be specified pipe-delimited (|) if more than one receipt output format is desired. When specifying more than one type, the response keys will indicate the format in the key name, but if only one type is specified, the type is omitted.
    • plain - Plain Text (default).
    • html - HTML. Needs style sheet applied.
    • xml - XML. Suitable for XSLT transformations. Typically used to generate complex HTML when CSS alone is not capable of providing the desired formatting.
    • json - JSON. Typically used for easy manipulation with JavaScript.
  • line_len - Only relevant for type=plain. Number of characters per line. Default is 24.
  • line_break - Only relevant for type=plain. Character sequence for newlines. Default is \r\n.
  • use_merch_lang - True/False. Use the merchant's selected language rather than the cardholder's language for the receipt. Default is True.
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "action": "sale",
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp",
  • "u_flags": "NOSIGNATURE|CARDMETA|DELAYRESPONSE",
  • "u_language": "en",
  • "u_foodamount": "maybe",
  • "u_id": "1234",
  • "u_rcpt": "yes",
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "cardtype": "VISA",
  • "trackdata": "string",
  • "u_cardclass": "UNKNOWN",
  • "property1": "string",
  • "property2": "string"
}

Device

Device operations

Close Persistent Device Connection

Close a persistent device connection

Operations using the u_flags=PERSISTDEVICE will have the device connection persist internally to speed up subsequent usage of the device. This is advantageous when using a slow to connect connective method. For example, Bluetooth LE is a notoriously slow type in regard to to opening a connection.

In some rare situations it is necessary to close a persistent connection that is being maintained with a device. Only very specific circumstances would this be necessary.

An example, that this operation may apply to is, barcode readers. Some barcode reads have very slow initialization when opening a connection. Upwards of 4 seconds. The PERSISTDEVICE flag would be necessary to scan multiple items in a reasonable amount of time.

However, the reader will remain in a reading state with all lights on until the underlying connection is closed. This will drain battery for wireless scanners very quickly. To prevent this the following pattern should be used.

  • Start barcode read with PERSISTDEVICE flag
  • Continuously send additional barcode reads until all items are read
  • Close the persistent device connection to turn off the reader

Again, this example is specific to barcode readers and limitations some models have. This would not apply to EMV card terminals.

Errors returned by this operation can be safely ignored.

libmonetra KVS equivalent for endpoint

  • u_action = deviceunpersist
Authorizations:
basic_auth
Request Body schema: application/json
u_device
required
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner

Responses

Request samples

Content type
application/json
{
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Condition of Device

Provides information about the overall device condition (not configuration). Such as, paper status on printers

libmonetra KVS equivalent for endpoint

  • u_action = devicecondition
Authorizations:
basic_auth
query Parameters
u_device
required
string
Example: u_device=SER:COM3

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
object
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"
Example: u_devicetype=ingenico_upp

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/condition' \
  --basic -u 'test_retail|public:publ1ct3st' \
  -G \
  -d 'u_device=IPCLIENT:78909876' \
  -d 'u_devicetype=ingenico_upp'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "property1": "string",
  • "property2": "string"
}

List Connected Device Information

Lists information about the connected device.

libmonetra KVS equivalent for endpoint

  • u_action = deviceinfo
Authorizations:
basic_auth
query Parameters
u_device
required
string
Example: u_device=SER:COM3

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
object
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"
Example: u_devicetype=ingenico_upp

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device' \
  --basic -u 'test_retail|public:publ1ct3st' \
  -G \
  -d 'u_device=IPCLIENT:78909876' \
  -d 'u_devicetype=ingenico_upp'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "device_app": "string",
  • "device_appver": "string",
  • "device_functionality": "string",
  • "device_kernver": "string",
  • "device_manuf": "string",
  • "device_model": "string",
  • "serialnum": "string"
}

Load Configuration

Loads a device with EMV and/or Interac parameters

This request will start a terminal download of EMV and/or Interac parameters to load onto the device being used. Requires username, password, u_device, and u_devicetype parameters.

If the loading data for the device is identical to the previous load, this load will be skipped.

Please note that this process may take up to 3 or 4 minutes depending on the processing institution being used and the device being used. The device may also reboot during this process. It is strongly recommended to call this function when a lane opens. However, if it is not called, it will automatically be performed prior to the first transaction.

If the device or merchant account does not support EMV or Interac, this command will simply return success.

libmonetra KVS equivalent for endpoint

  • u_action = deviceload
Authorizations:
basic_auth
Request Body schema: application/json
u_device
required
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
u_forceload
string
Enum: "yes" "no" "full"

Ignore device load checks and force reload terminal configuration

Values:

  • yes - Load EMV parameters and encryption keys
  • no - Do not perform a force load
  • full - Load EMV parameters, encryption keys, and all device UI components. Will wipe out any UI customizations.

Responses

Request samples

Content type
application/json
{
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp",
  • "u_forceload": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "property1": "string",
  • "property2": "string"
}

Update Pole Display

Updates the pole display (secondary monitor)

This is only valid after a Quick Chip (txnstart) message, before txnfinish is called.

The integrator must send the same u_id as was sent with the initial txnstart request. Devices that support a pole display can have it updated until the transaction is completed. The text to display in u_message must be pre-formatted for the proper width of the display.

libmonetra KVS equivalent for endpoint

  • u_action = devicepolemsg
Authorizations:
basic_auth
path Parameters
u_id
required
string
Example: 1234

A unique ID (generated by the calling application) that identifies the transaction. This is used for checking the status or canceling the transaction. Without this ID, the transaction state cannot be queried.

Request Body schema: application/json
u_message
required
string

Request message to show to the customer

Requires:

  • u_device
  • u_devicetype

Responses

Request samples

Content type
application/json
{
  • "u_message": "Hello, Customer"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Print a Receipt

Prints the given text to a built-in receipt printer, if available

The text provided must be formatted properly for the given device. Only plaintext receipts are supported.

libmonetra KVS equivalent for endpoint

  • u_action = deviceprint
Authorizations:
basic_auth
Request Body schema: application/json
u_device
required
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
u_text
required
string

ASCII pre-formatted text to send to receipt printer

Requires:

  • u_device
  • u_devicetype

Responses

Request samples

Content type
application/json
{
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp",
  • "u_text": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Reboot Device

Sends a reboot request to the device

libmonetra KVS equivalent for endpoint

  • u_action = devicereboot
Authorizations:
basic_auth
Request Body schema: application/json
u_device
required
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner

Responses

Request samples

Content type
application/json
{
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Upload a File

Uploads the given file to the device at the requested device path

Not all devices support the concept of file uploads.

This is typically used for updating device firmware.

libmonetra KVS equivalent for endpoint

  • u_action = deviceupload
Authorizations:
basic_auth
Request Body schema: application/json
u_device
required
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
u_b64data
required
string[a-zA-Z0-9+/\n]+={0,2}[\n]*

Base64-encoded file data

Requires:

  • u_device
  • u_devicetype
u_filename
required
string

The value should contain a properly formatted path for the device in use. Some devices like Ingenico RBA just want the filename with no path component.

Responses

Request samples

Content type
application/json
{
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp",
  • "u_b64data": "ABC=",
  • "u_filename": "UPDATE.BIN"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "u_needreboot": "yes"
}

Open Cash Drawer

Opens the device's cash drawer

libmonetra KVS equivalent for endpoint

  • u_action = opencashdrawer
Authorizations:
basic_auth
Request Body schema: application/json
u_device
required
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner

Responses

Request samples

Content type
application/json
{
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Read a Barcode

Authorizations:
basic_auth
query Parameters
u_device
required
string
Example: u_device=SER:COM3

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
object
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"
Example: u_devicetype=ingenico_upp

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/barcode' \
  --basic -u 'test_retail|public:publ1ct3st' \
  -G \
  -d 'u_device=IPCLIENT:78909876' \
  -d 'u_devicetype=ingenico_upp'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "u_barcode": "string"
}

Device List

Device List operations

List BLE-Supported Devices

Lists all Bluetooth Low Energy ports enumerated on the system

Currently only supported on iOS and MacOS.

Service

By default, only supported services will be returned. This does not check for any nearby devices that implement these services. When using a service with BLESRV:, the first device found that exposes the service will be used. This type of interaction is not recommended and should only be used in an environment where only a single device will ever be present.

The resulting report will contain these headers:

devicetype, name, service

Where:

  • devicetype - Device type as may be passed in u_devicetype
  • name - Textual name as advertised by device
  • service - Common service exposed by devices of this type, to be passed as part of u_device=BLESRV:

Scan

When requesting a scan, UniTerm will enumerate nearby devices that can be used. These devices are present and expose a supported service. When using an identifier with BLE:, that specific device will be used. The identifier can typically be reused and identifies a specific device. This method is necessary when using multiple of the same device in an environment.

Also, connecting to a device by identifier is faster than connecting using a service identifier.

The resulting report will contain these headers:

devicetype,name,identifier

Where:

  • devicetype - Device type as may be passed in u_devicetype
  • name - Textual name as advertised by device
  • identifier - Unique identifier of device to be passed as part

libmonetra KVS equivalent for endpoint

  • u_action = blelist
Authorizations:
None
query Parameters
u_blelist
object
Value: "scan"
Example: u_blelist=scan

Type of BLE action

Values:

  • scan - Scan for supported present devices instead of just known device services
timeout
string
Example: timeout=30

Length of time in seconds transaction can sit in send queue before sending to the processor. This is a hint/estimate and not a hard value.

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/ble'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

List Bluetooth-Connected Devices

List all Bluetooth (classic) devices that have been paired with the machine UniTerm is running on

The devices may or may not be present. Currently only supported on Android and MacOS.

The resulting report will contain these headers:

name, mac, uuid

Where:

  • name - Textual name of the device as registered with the operating system
  • mac - Device's bluetooth MAC address
  • uuid - Device's bluetooth UUID

libmonetra KVS equivalent for endpoint

  • u_action = bluetoothlist
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/bluetooth'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

List Supported Device Types

Returns a list of device types supported

The resulting report will contain these headers:

devicetype, manufacturer, model, connectivity, functionality

Where:

  • devicetype - Internal device name
  • manufacturer - Textual description of device manufacturer
  • model - Textual description of model
  • connectivity - Pipe-separated list of connectivity methods supported by the device (e.g. SERIAL|HID|BLUETOOTH|IP)
  • functionality - Pipe-separated list of functionality supported by the device. Some devices are families and may list features available in the family but not necessarily the device being used. (e.g. EMV|MAC|E2E|KEY|SIGNATURE|UPLOAD|PRINT|REBOOT|CONFIRM|FREEFORM|POLEDISPLAY). (FreeForm is used by reqinput.)

libmonetra KVS equivalent for endpoint

  • u_action = devicetypes
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "report": "..."
}

List HID-Connected Devices

Lists all supported HID (possibly USB-HID) devices that are currently attached to the machine UniTerm is running on

The resulting report will contain these headers:

devicetype, manufacturer, model, product, serialnum, path

Where:

  • devicetype - devicetype (device internal name) associated with the HID entry
  • manufacturer - Manufacturer as advertised by the device
  • model - Pretty name for the device type as it is known to UniTerm
  • product - Product as advertised by the device
  • serialnum - Serial number as advertised by the device
  • path - Internal OS path where the device is attached

libmonetra KVS equivalent for endpoint

  • u_action = hidlist
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/hid'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

List IP Client Connected Devices

Lists all IP Client connected devices

This is a Master Command secure operation with the following restrictions:

  • Request must be HMACed using the secure operation shared secret when remote access (localonly=no) is configured.
  • IP address of requester is allowed by configurable IP filter

The resulting report will contain these headers:

devicetype, serialnum, ipaddr, port, tls, idle, standalone,
connected_ts, last_used_ts, info

Where:

  • devicetype - devicetype (device internal name) associated with the HID entry
  • serialnum - Serial number of device
  • ipaddr - IP address of the device
  • port - Port device has connected to
  • tls - Whether the device is using a TLS secure connection
  • idle - Whether the device is idle or currently in use
  • standalone - Whether the device is operating in stand alone mode
  • connected_ts - Unix time stamp of when the device connected
  • last_used_ts - Last time the device was used
  • info - Meta data about the device

libmonetra KVS equivalent for endpoint

  • u_action = ipclientlist
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/ipclient'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

List Made for iOS-Connected Devices

Lists all Made For iOS (MFi) paired devices

The resulting report will contain these headers:

devicetype, name, protocol, serialnum

Where:

  • devicetype - devicetype (device internal name) associated with the HID entry
  • name - Textual name as advertised by device
  • protocol - Protocol advertised by device
  • serialnum - Serial number of device

libmonetra KVS equivalent for endpoint

  • u_action = mfilist
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/mfi'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

List Serial-Connected Devices

Lists all serial ports on the system

The resulting report will contain these headers:

port, desc

Where:

  • port - Port path
  • desc - Description of port (if applicable)

libmonetra KVS equivalent for endpoint

  • u_action = seriallist
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/serial'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

ChipTab

ChipTab operations

Close a ChipTab

Closes an existing tab

If a device is not specified, this works the same as force closing a tab. When using a device, the customer will be prompted to accept the amount and sign, if necessary.

libmonetra KVS equivalent for endpoint

  • u_action = tab
  • u_tab = close
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

Request Body schema: application/json
u_up_amount
string-?\d+(\.\d{0,2})?

Tabs can have the stored amount increased or decreased using the u_up_amount key. Positive numbers will increase the stored amount, and negative numbers will decrease it. This is useful if the POS wants UniTerm to track the tab amount instead of tracking it itself.

For example, the current amount is $15.00. Sending u_up_amount=2.00 will change the current amount that is stored to $17.00. Next, sending u_up_amount=-3.00 will reduce the amount to $14.00.

Note: u_up_amount is different than amount. amount is the total, and sending this key will replace the current value. u_up_amount modifies the current amount.

amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tax
string(?i)NT|\d*(\.\d{0,2})?

Amount of tax that applies to the order

The value 'NT' without the quotes indicates a non-taxable (tax exempt) transaction.

examount
string\d+(\.\d{0,2})?

Extra amount.

Typically used for Retail and Restaurant tipping

cashbackamount
string\d*(\.\d{0,2})?

Amount of funds requested as cash to be given to the customer

surchargeamount
string\d+(\.\d{0,2})?

Amount of funds being received as a surcharge

Surcharging rules are governed by the card brands. Compliance with brand rules need to be handled by the integrator because they can be highly industry and business type specific.

Also, some times when people talk about surcharging, they are really talking about service fees, convenience fees, or cash discounts, which all have different rules even though they are closely related.

Surcharges are the ONLY type that requires registration with the card brands and requires you pass the data along to the processing institution and therefore onto the card issuer. This is what this field does, is just pass that data along for transactions matching the surcharge classification (but not service fees, convenience fees, or cash discounts).

clerkid
string <= 2048 characters

Identifier for the clerk running the transaction

comments
string <= 2048 characters

User-defined comments related to the transaction

custref
string <= 128 characters

Customer reference number

Typically, a customer PO number but can be other customer reference number

ordernum
string <= 128 characters

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to UniTerm, an order number should be sent on all transactions.

An order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

ptrannum
string[^0]*\d+

Numeric-only transaction number. If ordernum is present, it will supersede and be preferred over ptrannum

stationid
string <= 128 characters

Identifier for the physical station running the transaction

u_device
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
u_flags
string
Enum: "DEVICEONLY" "GUIONLY" "KEY" "AVS" "CVV" "GIFTPIN" "NOEXPDATE" "NOTIP" "NOCASHBACK" "NOCONFIRM" "NOSIGNATURE" "DELAYRESPONSE" "CARDMETA" "NOSTANDIN" "PERSISTDEVICE" "EXTERNALSELECT" "DENYLISTQUEUE"

Multiple flags may be sent per data ticket request. All flags are separated by a pipe (|) symbol.

Flag values (pipe separated):

  • DEVICEONLY - Suppress display of clerk-facing prompting and feedback, also known as GUI Mode. For instance, on a swipe request, no swipe dialog would be presented nor would the clerk be informed of the status for customer-facing device interaction. Note: Setting this mode will prevent keyboard emulation readers from working. It will also prevent the ability for accepting clerk-keyed input via a keyboard. On Android, iOS, and UniTerm launched in console mode, this flag is automatically implied, as none of those support a GUI mode of operation.
  • GUIONLY - Suppress use of a referenced physical device. This flag can be used to utilize the physical device's UniTerm license for a clerk-facing GUI request, without using the device itself for card input. Without this flag, the GUI would register an additional UniTerm license based on the machine's unique ID.
  • KEY - Perform capture of manually-keyed data. Not valid on cardrequest. If an account or expdate field is passed in on the request to UniTerm, the fields will be pre-populated in GUI mode. Note: If a manually keyed EBT card is to be entered for a Food Stamp (SNAP) transaction, pass the qualified food amount via u_foodamount in order to go through the EBT flow and PIN prompting. Do NOT pass u_foodamount if you are NOT intending to run a Food Stamp transaction as keyed.
  • AVS - Request AVS data. Only allowed on keyed transactions. If a street or zip field is passed in on the request to UniTerm, those fields will be pre-populated in GUI mode.
  • CVV - Request for CVV data. Only allowed on keyed transactions.
  • GIFTPIN - Request a PIN for gift cards, when a gift card is presented. Does nothing if a different card type is presented.
  • NOEXPDATE - Disable expiration date prompting.
  • NOTIP - Disable tip prompting. This will override the merch_tippercent option in the Payment Server merchant account configuration.
  • NOCASHBACK - Disable cashback prompting. This will override the merch_cashbackmax option in the Payment Server merchant account configuration.
  • NOCONFIRM - When performing a QuickChip finalization via txnfinish, do not prompt the cardholder to confirm the amount prior to running the authorization.
  • NOSIGNATURE - If using a signature-capable device, but an integrator does not want to use the auto signature-capture capabilities in the UniTerm flow, treat the device as if it is not capable of accepting a signature. The u_need_signature response flag will be set appropriately for the transaction requirements.
  • DELAYRESPONSE - Send the transaction response back to the caller after the device has been closed. The device can be used immediately for a subsequent transaction with this flag. Otherwise, device closing will happen in the background, which will hold a lock on the device for at least 100ms, possibly longer.
  • CARDMETA - Request the card metadata directly from the Payment Server (v8.9.0+) rather than relying on less-detailed internal information. The relevant metadata would be from a Global BIN table, which contains information such as if a card is Debit-capable, HSA/FSA-capable, and so on. When used during a txnstart request, it allows an integrator to make decisions based on the card presented (such as for support of Debt Repayment or Healthcare transactions). When used during a txnrequest or txnquick, it optimizes the flow on transactions such as not prompting for Debit on a swipe transaction if the card is not debit capable.
  • NOSTANDIN - Transaction is not eligible for standin approval
  • PERSISTDEVICE - Maintain a persistent device connection
  • EXTERNALSELECT - Customer input for selection can be handled externally to the device. The status action must be polled to determine when and what external prompting should take place. The response needs to be provided to the external response action once the customer has made their selection.
  • DENYLISTQUEUE - Check if card is on block list and if not queue the transaction for later processing
u_language
string
Enum: "en" "fr" "es" "de" "it"

Used to override terminal defaults for display of text prompts. Not all devices support all languages.

Values:

  • en - English
  • fr - French
  • es - Spanish
  • de - German
  • it - Italian
u_id
string

A unique ID (generated by the calling application) that identifies the transaction. This is used for checking the status or canceling the transaction. Without this ID, the transaction state cannot be queried.

u_rcpt
string

The rcpt key/value pair is sent in the request to indicate whether or not to output a series of pre-formatted receipt blocks, as well as optional formatting requirements.

A value of no (the default) will not return a receipt.

A value of yes will return a receipt with a default format.

All other values are key/value pairs indicating formatting configurations, separated by semicolons, as in this example:

rcpt=type=plain;line_len=24;use_merch_lang=no;line_break="\n"

rcpt=type=plain|html

Receipt configuration options:

  • type - Values can be specified pipe-delimited (|) if more than one receipt output format is desired. When specifying more than one type, the response keys will indicate the format in the key name, but if only one type is specified, the type is omitted.
    • plain - Plain Text (default).
    • html - HTML. Needs style sheet applied.
    • xml - XML. Suitable for XSLT transformations. Typically used to generate complex HTML when CSS alone is not capable of providing the desired formatting.
    • json - JSON. Typically used for easy manipulation with JavaScript.
  • line_len - Only relevant for type=plain. Number of characters per line. Default is 24.
  • line_break - Only relevant for type=plain. Character sequence for newlines. Default is \r\n.
  • use_merch_lang - True/False. Use the merchant's selected language rather than the cardholder's language for the receipt. Default is True.

Responses

Request samples

Content type
application/json
{
  • "u_up_amount": "12.00",
  • "amount": "19.92",
  • "tax": "1.29",
  • "examount": "0.33",
  • "cashbackamount": "20.00",
  • "surchargeamount": "1.25",
  • "clerkid": "Doe-1553",
  • "comments": "Extra beef",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "ptrannum": "1987",
  • "stationid": "7",
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp",
  • "u_flags": "NOSIGNATURE|CARDMETA|DELAYRESPONSE",
  • "u_language": "en",
  • "u_id": "1234",
  • "u_rcpt": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "msoft_code": "INT_SUCCESS",
  • "phard_code": "SUCCESS",
  • "authamount": "6.50",
  • "account": "XXXXXXXXXXXX1234",
  • "ttid": "96748596765467",
  • "u_emv_chip_malfunction": "yes",
  • "u_need_signature": "yes",
  • "u_tip": "string",
  • "cardtype": "VISA",
  • "u_cardclass": "UNKNOWN",
  • "u_cashback": "string",
  • "u_flowflags": "SIGCAPTURED",
  • "u_standin": "yes",
  • "property1": "string",
  • "property2": "string"
}

Force Close a ChipTab

Forces an existing tab to close

The transaction is sent directly to the Payment Server without customer interaction. Useful when a customer leaves without explicitly closing their tab

libmonetra KVS equivalent for endpoint

  • u_action = tab
  • u_tab = force_close
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

Request Body schema: application/json
u_up_amount
string-?\d+(\.\d{0,2})?

Tabs can have the stored amount increased or decreased using the u_up_amount key. Positive numbers will increase the stored amount, and negative numbers will decrease it. This is useful if the POS wants UniTerm to track the tab amount instead of tracking it itself.

For example, the current amount is $15.00. Sending u_up_amount=2.00 will change the current amount that is stored to $17.00. Next, sending u_up_amount=-3.00 will reduce the amount to $14.00.

Note: u_up_amount is different than amount. amount is the total, and sending this key will replace the current value. u_up_amount modifies the current amount.

amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tax
string(?i)NT|\d*(\.\d{0,2})?

Amount of tax that applies to the order

The value 'NT' without the quotes indicates a non-taxable (tax exempt) transaction.

examount
string\d+(\.\d{0,2})?

Extra amount.

Typically used for Retail and Restaurant tipping

cashbackamount
string\d*(\.\d{0,2})?

Amount of funds requested as cash to be given to the customer

surchargeamount
string\d+(\.\d{0,2})?

Amount of funds being received as a surcharge

Surcharging rules are governed by the card brands. Compliance with brand rules need to be handled by the integrator because they can be highly industry and business type specific.

Also, some times when people talk about surcharging, they are really talking about service fees, convenience fees, or cash discounts, which all have different rules even though they are closely related.

Surcharges are the ONLY type that requires registration with the card brands and requires you pass the data along to the processing institution and therefore onto the card issuer. This is what this field does, is just pass that data along for transactions matching the surcharge classification (but not service fees, convenience fees, or cash discounts).

clerkid
string <= 2048 characters

Identifier for the clerk running the transaction

comments
string <= 2048 characters

User-defined comments related to the transaction

custref
string <= 128 characters

Customer reference number

Typically, a customer PO number but can be other customer reference number

ordernum
string <= 128 characters

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to UniTerm, an order number should be sent on all transactions.

An order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

ptrannum
string[^0]*\d+

Numeric-only transaction number. If ordernum is present, it will supersede and be preferred over ptrannum

stationid
string <= 128 characters

Identifier for the physical station running the transaction

Responses

Request samples

Content type
application/json
{
  • "u_up_amount": "12.00",
  • "amount": "19.92",
  • "tax": "1.29",
  • "examount": "0.33",
  • "cashbackamount": "20.00",
  • "surchargeamount": "1.25",
  • "clerkid": "Doe-1553",
  • "comments": "Extra beef",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "ptrannum": "1987",
  • "stationid": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "msoft_code": "INT_SUCCESS",
  • "phard_code": "SUCCESS",
  • "authamount": "6.50",
  • "account": "XXXXXXXXXXXX1234",
  • "ttid": "96748596765467",
  • "u_emv_chip_malfunction": "yes",
  • "u_need_signature": "yes",
  • "u_tip": "string",
  • "cardtype": "VISA",
  • "u_cardclass": "UNKNOWN",
  • "u_cashback": "string",
  • "u_flowflags": "SIGCAPTURED",
  • "u_standin": "yes"
}

List Open ChipTabs

Lists all open tabs for the user

This will return a list of comma-separated values.

The resulting CSV will contain these headers:

ttid, proc, type, entrymode, card, pclevel, account, amount, cardholdername,
clerkid, comments, custref, expdate, examount, cashback, ordernum, ptrannum,
stationid, tax, timestamp

libmonetra KVS equivalent for endpoint

  • u_action = tab
  • u_tab = list
Authorizations:
basic_auth
query Parameters
ttid
string
Example: ttid=96748596765467

Transaction identifier

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

examount
string
Example: examount=0.33

Extra amount.

Typically used for Retail and Restaurant tipping

tax
string
Example: tax=1.29

Amount of tax that applies to the order

The value 'NT' without the quotes indicates a non-taxable (tax exempt) transaction.

card
string
Example: card=VISA

Type of card that was used

pclevel
object
Enum: "0" "1" "2"
Example: pclevel=0

Indicates the level of payment card

Values:

  • 0 - Consumer card
  • 1 - Business card
  • 2 - Corporate or purchase card
account
string
Example: account=1234

Last 4 digits of account number

expdate
string
Example: expdate=0129

Expiration date of the card (MMYY format)

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to UniTerm, an order number should be sent on all transactions.

An order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

custref
string
Example: custref=55

Customer reference number

Typically, a customer PO number but can be other customer reference number

ptrannum
string
Example: ptrannum=1987

Numeric-only transaction number. If ordernum is present, it will supersede and be preferred over ptrannum

clerkid
string
Example: clerkid=Doe-1553

Identifier for the clerk running the transaction

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

comments
string
Example: comments=Extra beef

User-defined comments related to the transaction

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/tab' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Open a ChipTab

Opens a tab, and captures customer card data

libmonetra KVS equivalent for endpoint

  • u_action = tab
  • u_tab = open
Authorizations:
basic_auth
Request Body schema: application/json
u_device
required
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
u_flags
string
Enum: "DEVICEONLY" "GUIONLY" "KEY" "AVS" "CVV" "GIFTPIN" "NOEXPDATE" "NOTIP" "NOCASHBACK" "NOCONFIRM" "NOSIGNATURE" "DELAYRESPONSE" "CARDMETA" "NOSTANDIN" "PERSISTDEVICE" "EXTERNALSELECT" "DENYLISTQUEUE"

Multiple flags may be sent per data ticket request. All flags are separated by a pipe (|) symbol.

Flag values (pipe separated):

  • DEVICEONLY - Suppress display of clerk-facing prompting and feedback, also known as GUI Mode. For instance, on a swipe request, no swipe dialog would be presented nor would the clerk be informed of the status for customer-facing device interaction. Note: Setting this mode will prevent keyboard emulation readers from working. It will also prevent the ability for accepting clerk-keyed input via a keyboard. On Android, iOS, and UniTerm launched in console mode, this flag is automatically implied, as none of those support a GUI mode of operation.
  • GUIONLY - Suppress use of a referenced physical device. This flag can be used to utilize the physical device's UniTerm license for a clerk-facing GUI request, without using the device itself for card input. Without this flag, the GUI would register an additional UniTerm license based on the machine's unique ID.
  • KEY - Perform capture of manually-keyed data. Not valid on cardrequest. If an account or expdate field is passed in on the request to UniTerm, the fields will be pre-populated in GUI mode. Note: If a manually keyed EBT card is to be entered for a Food Stamp (SNAP) transaction, pass the qualified food amount via u_foodamount in order to go through the EBT flow and PIN prompting. Do NOT pass u_foodamount if you are NOT intending to run a Food Stamp transaction as keyed.
  • AVS - Request AVS data. Only allowed on keyed transactions. If a street or zip field is passed in on the request to UniTerm, those fields will be pre-populated in GUI mode.
  • CVV - Request for CVV data. Only allowed on keyed transactions.
  • GIFTPIN - Request a PIN for gift cards, when a gift card is presented. Does nothing if a different card type is presented.
  • NOEXPDATE - Disable expiration date prompting.
  • NOTIP - Disable tip prompting. This will override the merch_tippercent option in the Payment Server merchant account configuration.
  • NOCASHBACK - Disable cashback prompting. This will override the merch_cashbackmax option in the Payment Server merchant account configuration.
  • NOCONFIRM - When performing a QuickChip finalization via txnfinish, do not prompt the cardholder to confirm the amount prior to running the authorization.
  • NOSIGNATURE - If using a signature-capable device, but an integrator does not want to use the auto signature-capture capabilities in the UniTerm flow, treat the device as if it is not capable of accepting a signature. The u_need_signature response flag will be set appropriately for the transaction requirements.
  • DELAYRESPONSE - Send the transaction response back to the caller after the device has been closed. The device can be used immediately for a subsequent transaction with this flag. Otherwise, device closing will happen in the background, which will hold a lock on the device for at least 100ms, possibly longer.
  • CARDMETA - Request the card metadata directly from the Payment Server (v8.9.0+) rather than relying on less-detailed internal information. The relevant metadata would be from a Global BIN table, which contains information such as if a card is Debit-capable, HSA/FSA-capable, and so on. When used during a txnstart request, it allows an integrator to make decisions based on the card presented (such as for support of Debt Repayment or Healthcare transactions). When used during a txnrequest or txnquick, it optimizes the flow on transactions such as not prompting for Debit on a swipe transaction if the card is not debit capable.
  • NOSTANDIN - Transaction is not eligible for standin approval
  • PERSISTDEVICE - Maintain a persistent device connection
  • EXTERNALSELECT - Customer input for selection can be handled externally to the device. The status action must be polled to determine when and what external prompting should take place. The response needs to be provided to the external response action once the customer has made their selection.
  • DENYLISTQUEUE - Check if card is on block list and if not queue the transaction for later processing
u_language
string
Enum: "en" "fr" "es" "de" "it"

Used to override terminal defaults for display of text prompts. Not all devices support all languages.

Values:

  • en - English
  • fr - French
  • es - Spanish
  • de - German
  • it - Italian
u_id
string

A unique ID (generated by the calling application) that identifies the transaction. This is used for checking the status or canceling the transaction. Without this ID, the transaction state cannot be queried.

u_rcpt
string

The rcpt key/value pair is sent in the request to indicate whether or not to output a series of pre-formatted receipt blocks, as well as optional formatting requirements.

A value of no (the default) will not return a receipt.

A value of yes will return a receipt with a default format.

All other values are key/value pairs indicating formatting configurations, separated by semicolons, as in this example:

rcpt=type=plain;line_len=24;use_merch_lang=no;line_break="\n"

rcpt=type=plain|html

Receipt configuration options:

  • type - Values can be specified pipe-delimited (|) if more than one receipt output format is desired. When specifying more than one type, the response keys will indicate the format in the key name, but if only one type is specified, the type is omitted.
    • plain - Plain Text (default).
    • html - HTML. Needs style sheet applied.
    • xml - XML. Suitable for XSLT transformations. Typically used to generate complex HTML when CSS alone is not capable of providing the desired formatting.
    • json - JSON. Typically used for easy manipulation with JavaScript.
  • line_len - Only relevant for type=plain. Number of characters per line. Default is 24.
  • line_break - Only relevant for type=plain. Character sequence for newlines. Default is \r\n.
  • use_merch_lang - True/False. Use the merchant's selected language rather than the cardholder's language for the receipt. Default is True.

Responses

Request samples

Content type
application/json
{
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp",
  • "u_flags": "NOSIGNATURE|CARDMETA|DELAYRESPONSE",
  • "u_language": "en",
  • "u_id": "1234",
  • "u_rcpt": "yes"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "msoft_code": "INT_SUCCESS",
  • "phard_code": "SUCCESS",
  • "authamount": "6.50",
  • "account": "XXXXXXXXXXXX1234",
  • "ttid": "96748596765467",
  • "u_emv_chip_malfunction": "yes",
  • "u_need_signature": "yes",
  • "u_tip": "string",
  • "cardtype": "VISA",
  • "u_cardclass": "UNKNOWN",
  • "u_cashback": "string",
  • "u_flowflags": "SIGCAPTURED",
  • "u_standin": "yes"
}

Get ChipTab Totals

Gets the total number of open tabs and the total tracked amount across all tabs

The total amount is only useful if using UniTerm to track the total for each tab by utilizing u_up_amount. If the POS is tracking the amount itself and only sending the amount when closing the tab, the aggregate total amount will most likely be $0.00 and not accurately reflect the outstanding total amount.

libmonetra KVS equivalent for endpoint

  • u_action = tab
  • u_tab = totals
Authorizations:
basic_auth

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/tab/totals' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "num_trans": "44",
  • "total_amount": "172.01"
}

Adjust a ChipTab

Updates the metadata on file for a ChipTab.

libmonetra KVS equivalent for endpoint

  • u_action = tab
  • u_tab = update
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

Request Body schema: application/json
u_up_amount
string-?\d+(\.\d{0,2})?

Tabs can have the stored amount increased or decreased using the u_up_amount key. Positive numbers will increase the stored amount, and negative numbers will decrease it. This is useful if the POS wants UniTerm to track the tab amount instead of tracking it itself.

For example, the current amount is $15.00. Sending u_up_amount=2.00 will change the current amount that is stored to $17.00. Next, sending u_up_amount=-3.00 will reduce the amount to $14.00.

Note: u_up_amount is different than amount. amount is the total, and sending this key will replace the current value. u_up_amount modifies the current amount.

amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

tax
string(?i)NT|\d*(\.\d{0,2})?

Amount of tax that applies to the order

The value 'NT' without the quotes indicates a non-taxable (tax exempt) transaction.

examount
string\d+(\.\d{0,2})?

Extra amount.

Typically used for Retail and Restaurant tipping

cashbackamount
string\d*(\.\d{0,2})?

Amount of funds requested as cash to be given to the customer

surchargeamount
string\d+(\.\d{0,2})?

Amount of funds being received as a surcharge

Surcharging rules are governed by the card brands. Compliance with brand rules need to be handled by the integrator because they can be highly industry and business type specific.

Also, some times when people talk about surcharging, they are really talking about service fees, convenience fees, or cash discounts, which all have different rules even though they are closely related.

Surcharges are the ONLY type that requires registration with the card brands and requires you pass the data along to the processing institution and therefore onto the card issuer. This is what this field does, is just pass that data along for transactions matching the surcharge classification (but not service fees, convenience fees, or cash discounts).

clerkid
string <= 2048 characters

Identifier for the clerk running the transaction

comments
string <= 2048 characters

User-defined comments related to the transaction

custref
string <= 128 characters

Customer reference number

Typically, a customer PO number but can be other customer reference number

ordernum
string <= 128 characters

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to UniTerm, an order number should be sent on all transactions.

An order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

ptrannum
string[^0]*\d+

Numeric-only transaction number. If ordernum is present, it will supersede and be preferred over ptrannum

stationid
string <= 128 characters

Identifier for the physical station running the transaction

Responses

Request samples

Content type
application/json
{
  • "u_up_amount": "12.00",
  • "amount": "19.92",
  • "tax": "1.29",
  • "examount": "0.33",
  • "cashbackamount": "20.00",
  • "surchargeamount": "1.25",
  • "clerkid": "Doe-1553",
  • "comments": "Extra beef",
  • "custref": "55",
  • "ordernum": "A13DDES345",
  • "ptrannum": "1987",
  • "stationid": "7"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Void a ChipTab

Deletes a tab

The tab is closed but never sent online for authorization.

libmonetra KVS equivalent for endpoint

  • u_action = tab
  • u_tab = void
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

Responses

Request samples

curl -X DELETE 'https://uniterm.test.transafe.com:8123/api/v1/tab/U1294139' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Stored

Stored transaction operations

Get Stored Transaction Activity

Returns a summary of stand-in authorized transactions for the requesting user

Report includes both pending and already uploaded transactions. The intended use is to provide an overview for further analysis of stand-in processing. For example, easily determine the number of approved or declined. Number of partial approvals. Or the ratio of pending vs finalized at the given time the report is generated.

Data life is dependant on two factors. Pending transactions will only show when they are pending. Finalized transaction data is available as long as the stored transaction response data has not been deleted.

Transactions which have not yet been uploaded will not have values for ttid, uploaded_timestamp, authamount, or code. The lack of either ttid, or uploaded_timestamp can be used to determine if the transaction is still pending.

authamount will be empty unless the response from the payment server included an authamount response value.

The resulting report will contain these headers:

u_ttid, ttid, standin_timestamp, stored_timestamp, uploaded_timestamp,
ordernum, account, cardtype, amount, authamount, code

libmonetra KVS equivalent for endpoint

  • u_action = standin
  • u_standin = activity
Authorizations:
basic_auth

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/stored/activity' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

List Stored Transactions

Lists all stored transactions for the user

The resulting report will contain these headers:

ttid, proc, type, entrymode, card, pclevel, account, amount, cardholdername,
clerkid, comments, custref, expdate, examount, cashback, ordernum, ptrannum,
stationid, tax, timestamp, store_type

libmonetra KVS equivalent for endpoint

  • u_action = standin
  • u_standin = list
Authorizations:
basic_auth
query Parameters
ttid
string
Example: ttid=96748596765467

Transaction identifier

bdate
string
Example: bdate=-6 months

Start of date range

edate
string
Example: edate=now

End of date range

timestamp
string
Example: timestamp=1567008057

The Unix timestamp returned from the original transaction response

type
string
Example: type=sale

Type of action that was taken.

Can be a pipe (|) separated list of actions

amount
string
Example: amount=19.92

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

examount
string
Example: examount=0.33

Extra amount.

Typically used for Retail and Restaurant tipping

tax
string
Example: tax=1.29

Amount of tax that applies to the order

The value 'NT' without the quotes indicates a non-taxable (tax exempt) transaction.

card
string
Example: card=VISA

Type of card that was used

pclevel
object
Enum: "0" "1" "2"
Example: pclevel=0

Indicates the level of payment card

Values:

  • 0 - Consumer card
  • 1 - Business card
  • 2 - Corporate or purchase card
account
string
Example: account=1234

Last 4 digits of account number

expdate
string
Example: expdate=0129

Expiration date of the card (MMYY format)

cardholdername
string
Example: cardholdername=John Doe

Name of the cardholder.

Will be read from account data (EMV, Track 1, etc.) but is not guaranteed to be present. Some presentation methods, such as keyed, do not have any way to capture the name as part of the account data.

Further, Visa explicitly does not allow the cardholder name to be transmitted as part of a contactless read. Typically, a contactless read will result in a cardholder name of "/".

If the name is known by another means, it can be entered in this parameter to override what was read (or not read) from the card.

ordernum
string
Example: ordernum=A13DDES345

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to UniTerm, an order number should be sent on all transactions.

An order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

custref
string
Example: custref=55

Customer reference number

Typically, a customer PO number but can be other customer reference number

ptrannum
string
Example: ptrannum=1987

Numeric-only transaction number. If ordernum is present, it will supersede and be preferred over ptrannum

clerkid
string
Example: clerkid=Doe-1553

Identifier for the clerk running the transaction

stationid
string
Example: stationid=7

Identifier for the physical station running the transaction

comments
string
Example: comments=Extra beef

User-defined comments related to the transaction

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/stored' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

Send Stored Transactions for Authorization

Sends stored transactions to the Payment Server

This returns immediately and starts sending transactions as a background task within UniTerm. It does not return any indication about status of or number of transactions.

Transactions are sent on a configurable timer and can be triggered to start sooner with this sub-action. Transactions will attempt to be sent, but they may remain in a stored state if there are connectivity issues. Since this triggers the timer, it applies to stored transactions for all users on the system. You cannot selectively send transactions.

libmonetra KVS equivalent for endpoint

  • u_action = standin
  • u_standin = send
Authorizations:
basic_auth

Responses

Request samples

curl -X POST 'https://uniterm.test.transafe.com:8123/api/v1/stored/send' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Stored Transaction Totals

Returns the number of stored transactions and the total stored amount for the requesting user

libmonetra KVS equivalent for endpoint

  • u_action = standin
  • u_standin = totals
Authorizations:
basic_auth

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/stored/totals' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "num_trans": "44",
  • "oldest_trans": "string",
  • "total_amount": "172.01",
  • "uploaded_amount_auth": "string",
  • "uploaded_amount_deny": "string",
  • "uploaded_num_auth": "string",
  • "uploaded_num_deny": "string"
}

Adjust a Stored Transaction

Updates the metadata on file for a stored transaction

libmonetra KVS equivalent for endpoint

  • u_action = standin
  • u_standin = update
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

Request Body schema: application/json
amount
string\d*(\.\d{0,2})?

Amount of money, including decimal. E.g 1.00

This is the total amount and is an aggregate of all supplementary amounts.

cashbackamount
string\d*(\.\d{0,2})?

Amount of funds requested as cash to be given to the customer

clerkid
string <= 2048 characters

Identifier for the clerk running the transaction

comments
string <= 2048 characters

User-defined comments related to the transaction

custref
string <= 128 characters

Customer reference number

Typically, a customer PO number but can be other customer reference number

examount
string\d+(\.\d{0,2})?

Extra amount.

Typically used for Retail and Restaurant tipping

ordernum
string <= 128 characters

Order number

An order number is required for all Card Not Present (e.g. Mail Order / Telephone Order and E-commerce) transactions, all transactions for the Restaurant industry, and all Level 2 cards such as Purchase or Corporate cards. Since it is not possible to know the card type prior to a request to UniTerm, an order number should be sent on all transactions.

An order number is alphanumeric. However, for the restaurant industry, it should be numeric only.

Processors are limited in the number of characters that can be sent as part of a transaction. Non restaurant industry will only have 25 characters sent and restaurant will only have 6.

ptrannum
string[^0]*\d+

Numeric-only transaction number. If ordernum is present, it will supersede and be preferred over ptrannum

stationid
string <= 128 characters

Identifier for the physical station running the transaction

surchargeamount
string\d+(\.\d{0,2})?

Amount of funds being received as a surcharge

Surcharging rules are governed by the card brands. Compliance with brand rules need to be handled by the integrator because they can be highly industry and business type specific.

Also, some times when people talk about surcharging, they are really talking about service fees, convenience fees, or cash discounts, which all have different rules even though they are closely related.

Surcharges are the ONLY type that requires registration with the card brands and requires you pass the data along to the processing institution and therefore onto the card issuer. This is what this field does, is just pass that data along for transactions matching the surcharge classification (but not service fees, convenience fees, or cash discounts).

tax
string(?i)NT|\d*(\.\d{0,2})?

Amount of tax that applies to the order

The value 'NT' without the quotes indicates a non-taxable (tax exempt) transaction.

Responses

Request samples

Content type
application/json
{
  • "amount": "19.92",
  • "cashbackamount": "20.00",
  • "clerkid": "Doe-1553",
  • "comments": "Extra beef",
  • "custref": "55",
  • "examount": "0.33",
  • "ordernum": "A13DDES345",
  • "ptrannum": "1987",
  • "stationid": "7",
  • "surchargeamount": "1.25",
  • "tax": "1.29"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Void Stored Transaction

Deletes a stored transaction

The transaction is never sent online for authorization.

libmonetra KVS equivalent for endpoint

  • u_action = standin
  • u_standin = void
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

Responses

Request samples

curl -X DELETE 'https://uniterm.test.transafe.com:8123/api/v1/stored/U1294139' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Stored Response

Stored transaction response operations

Delete a Stored Transaction Response

Purges the Payment Server response for a stored transaction that was successfully sent online

libmonetra KVS equivalent for endpoint

  • u_action = standin
  • u_standin = delresp
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

Responses

Request samples

curl -X DELETE 'https://uniterm.test.transafe.com:8123/api/v1/stored/response/U921234' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Get a Stored Transaction Response

Gets the Payment Server response for a stored transaction that was successfully sent online

This will return the full key/value pair result returned by the Payment Server.

libmonetra KVS equivalent for endpoint

  • u_action = standin
  • u_standin = getresp
Authorizations:
basic_auth
path Parameters
ttid
required
string
Example: 96748596765467

Transaction identifier

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/stored/response/U921234' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "property1": "string",
  • "property2": "string"
}

List Stored Transaction Responses

Generates a report with basic information about stored transactions that have been successfully sent online

The TTID that was returned by UniTerm when it stored the transaction will appear in the u_ttid column, and the Payment Server's TTID will appear in the ttid column. Follow-up transactions, such as a reversal, can continue to use the UniTerm TTID as long as the response is still on file. It is highly recommended that the POS replace the UniTerm TTID with the Payment Server TTID internally as soon as possible.

The resulting report will contain these headers:

u_ttid, ttid, timestamp, code, verbiage

libmonetra KVS equivalent for endpoint

  • u_action = standin
  • u_standin = listresp
Authorizations:
basic_auth
query Parameters
ttid
string
Example: ttid=96748596765467

Transaction identifier

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/stored/response' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

Device Prompting

Customer Prompting operations

Request Customer Confirmation

Requests the user confirm a message presented on the device screen

This can also be used to display an agreement to the customer. If agreed the POS can follow up with a signature request if a record of the confirmation is required.

The optional u_long_message parameter is used to display additional message text. Such as agreement text. Not all devices support a long message. Will only be shown on devices with a screen large enough to accommodate additional message display.

libmonetra KVS equivalent for endpoint

  • u_action = reqconfirm
Authorizations:
basic_auth
query Parameters
u_device
required
string
Example: u_device=SER:COM3

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
object
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"
Example: u_devicetype=ingenico_upp

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
u_message
required
string
Example: u_message=Hello, Customer

Request message to show to the customer

Requires:

  • u_device
  • u_devicetype
u_flags
object
Enum: "DEVICEONLY" "GUIONLY" "KEY" "AVS" "CVV" "GIFTPIN" "NOEXPDATE" "NOTIP" "NOCASHBACK" "NOCONFIRM" "NOSIGNATURE" "DELAYRESPONSE" "CARDMETA" "NOSTANDIN" "PERSISTDEVICE" "EXTERNALSELECT" "DENYLISTQUEUE"
Example: u_flags=NOSIGNATURE|CARDMETA|DELAYRESPONSE

Multiple flags may be sent per data ticket request. All flags are separated by a pipe (|) symbol.

Flag values (pipe separated):

  • DEVICEONLY - Suppress display of clerk-facing prompting and feedback, also known as GUI Mode. For instance, on a swipe request, no swipe dialog would be presented nor would the clerk be informed of the status for customer-facing device interaction. Note: Setting this mode will prevent keyboard emulation readers from working. It will also prevent the ability for accepting clerk-keyed input via a keyboard. On Android, iOS, and UniTerm launched in console mode, this flag is automatically implied, as none of those support a GUI mode of operation.
  • GUIONLY - Suppress use of a referenced physical device. This flag can be used to utilize the physical device's UniTerm license for a clerk-facing GUI request, without using the device itself for card input. Without this flag, the GUI would register an additional UniTerm license based on the machine's unique ID.
  • KEY - Perform capture of manually-keyed data. Not valid on cardrequest. If an account or expdate field is passed in on the request to UniTerm, the fields will be pre-populated in GUI mode. Note: If a manually keyed EBT card is to be entered for a Food Stamp (SNAP) transaction, pass the qualified food amount via u_foodamount in order to go through the EBT flow and PIN prompting. Do NOT pass u_foodamount if you are NOT intending to run a Food Stamp transaction as keyed.
  • AVS - Request AVS data. Only allowed on keyed transactions. If a street or zip field is passed in on the request to UniTerm, those fields will be pre-populated in GUI mode.
  • CVV - Request for CVV data. Only allowed on keyed transactions.
  • GIFTPIN - Request a PIN for gift cards, when a gift card is presented. Does nothing if a different card type is presented.
  • NOEXPDATE - Disable expiration date prompting.
  • NOTIP - Disable tip prompting. This will override the merch_tippercent option in the Payment Server merchant account configuration.
  • NOCASHBACK - Disable cashback prompting. This will override the merch_cashbackmax option in the Payment Server merchant account configuration.
  • NOCONFIRM - When performing a QuickChip finalization via txnfinish, do not prompt the cardholder to confirm the amount prior to running the authorization.
  • NOSIGNATURE - If using a signature-capable device, but an integrator does not want to use the auto signature-capture capabilities in the UniTerm flow, treat the device as if it is not capable of accepting a signature. The u_need_signature response flag will be set appropriately for the transaction requirements.
  • DELAYRESPONSE - Send the transaction response back to the caller after the device has been closed. The device can be used immediately for a subsequent transaction with this flag. Otherwise, device closing will happen in the background, which will hold a lock on the device for at least 100ms, possibly longer.
  • CARDMETA - Request the card metadata directly from the Payment Server (v8.9.0+) rather than relying on less-detailed internal information. The relevant metadata would be from a Global BIN table, which contains information such as if a card is Debit-capable, HSA/FSA-capable, and so on. When used during a txnstart request, it allows an integrator to make decisions based on the card presented (such as for support of Debt Repayment or Healthcare transactions). When used during a txnrequest or txnquick, it optimizes the flow on transactions such as not prompting for Debit on a swipe transaction if the card is not debit capable.
  • NOSTANDIN - Transaction is not eligible for standin approval
  • PERSISTDEVICE - Maintain a persistent device connection
  • EXTERNALSELECT - Customer input for selection can be handled externally to the device. The status action must be polled to determine when and what external prompting should take place. The response needs to be provided to the external response action once the customer has made their selection.
  • DENYLISTQUEUE - Check if card is on block list and if not queue the transaction for later processing
u_long_message
string
Example: u_long_message=Item 1 Item2 Item3

Long message to show to the customer

The message will not be formatted to the device screen. It is imperative the message be formatted for the device being used. This includes required line ending type (\r\n vs \n) and line lengths.

Requires:

  • u_message
  • u_device
  • u_devicetype

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/prompt/confirm' \
  --basic -u 'test_retail|public:publ1ct3st' \
  -G \
  -d 'u_device=IPCLIENT:78909876' \
  -d 'u_devicetype=ingenico_upp' \
  -d 'u_message=Get+Special+Offers?'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "u_confirmed": "yes"
}

Request Customer Confirmation

Requests the user confirm a message presented on the device screen

This can also be used to display an agreement to the customer. If agreed the POS can follow up with a signature request if a record of the confirmation is required.

The optional u_long_message parameter is used to display additional message text. Such as agreement text. Not all devices support a long message. Will only be shown on devices with a screen large enough to accommodate additional message display.

libmonetra KVS equivalent for endpoint

  • u_action = reqconfirm
Authorizations:
basic_auth
Request Body schema: application/json
u_device
required
string(?i)(HID|USB|SDK)(:?|:.*)|(SER||MFI|BT|BLE|BL...

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
string
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
u_message
required
string

Request message to show to the customer

Requires:

  • u_device
  • u_devicetype
u_flags
string
Enum: "DEVICEONLY" "GUIONLY" "KEY" "AVS" "CVV" "GIFTPIN" "NOEXPDATE" "NOTIP" "NOCASHBACK" "NOCONFIRM" "NOSIGNATURE" "DELAYRESPONSE" "CARDMETA" "NOSTANDIN" "PERSISTDEVICE" "EXTERNALSELECT" "DENYLISTQUEUE"

Multiple flags may be sent per data ticket request. All flags are separated by a pipe (|) symbol.

Flag values (pipe separated):

  • DEVICEONLY - Suppress display of clerk-facing prompting and feedback, also known as GUI Mode. For instance, on a swipe request, no swipe dialog would be presented nor would the clerk be informed of the status for customer-facing device interaction. Note: Setting this mode will prevent keyboard emulation readers from working. It will also prevent the ability for accepting clerk-keyed input via a keyboard. On Android, iOS, and UniTerm launched in console mode, this flag is automatically implied, as none of those support a GUI mode of operation.
  • GUIONLY - Suppress use of a referenced physical device. This flag can be used to utilize the physical device's UniTerm license for a clerk-facing GUI request, without using the device itself for card input. Without this flag, the GUI would register an additional UniTerm license based on the machine's unique ID.
  • KEY - Perform capture of manually-keyed data. Not valid on cardrequest. If an account or expdate field is passed in on the request to UniTerm, the fields will be pre-populated in GUI mode. Note: If a manually keyed EBT card is to be entered for a Food Stamp (SNAP) transaction, pass the qualified food amount via u_foodamount in order to go through the EBT flow and PIN prompting. Do NOT pass u_foodamount if you are NOT intending to run a Food Stamp transaction as keyed.
  • AVS - Request AVS data. Only allowed on keyed transactions. If a street or zip field is passed in on the request to UniTerm, those fields will be pre-populated in GUI mode.
  • CVV - Request for CVV data. Only allowed on keyed transactions.
  • GIFTPIN - Request a PIN for gift cards, when a gift card is presented. Does nothing if a different card type is presented.
  • NOEXPDATE - Disable expiration date prompting.
  • NOTIP - Disable tip prompting. This will override the merch_tippercent option in the Payment Server merchant account configuration.
  • NOCASHBACK - Disable cashback prompting. This will override the merch_cashbackmax option in the Payment Server merchant account configuration.
  • NOCONFIRM - When performing a QuickChip finalization via txnfinish, do not prompt the cardholder to confirm the amount prior to running the authorization.
  • NOSIGNATURE - If using a signature-capable device, but an integrator does not want to use the auto signature-capture capabilities in the UniTerm flow, treat the device as if it is not capable of accepting a signature. The u_need_signature response flag will be set appropriately for the transaction requirements.
  • DELAYRESPONSE - Send the transaction response back to the caller after the device has been closed. The device can be used immediately for a subsequent transaction with this flag. Otherwise, device closing will happen in the background, which will hold a lock on the device for at least 100ms, possibly longer.
  • CARDMETA - Request the card metadata directly from the Payment Server (v8.9.0+) rather than relying on less-detailed internal information. The relevant metadata would be from a Global BIN table, which contains information such as if a card is Debit-capable, HSA/FSA-capable, and so on. When used during a txnstart request, it allows an integrator to make decisions based on the card presented (such as for support of Debt Repayment or Healthcare transactions). When used during a txnrequest or txnquick, it optimizes the flow on transactions such as not prompting for Debit on a swipe transaction if the card is not debit capable.
  • NOSTANDIN - Transaction is not eligible for standin approval
  • PERSISTDEVICE - Maintain a persistent device connection
  • EXTERNALSELECT - Customer input for selection can be handled externally to the device. The status action must be polled to determine when and what external prompting should take place. The response needs to be provided to the external response action once the customer has made their selection.
  • DENYLISTQUEUE - Check if card is on block list and if not queue the transaction for later processing
u_long_message
string

Long message to show to the customer

The message will not be formatted to the device screen. It is imperative the message be formatted for the device being used. This includes required line ending type (\r\n vs \n) and line lengths.

Requires:

  • u_message
  • u_device
  • u_devicetype

Responses

Request samples

Content type
application/json
{
  • "u_device": "SER:COM3",
  • "u_devicetype": "ingenico_upp",
  • "u_message": "Hello, Customer",
  • "u_flags": "NOSIGNATURE|CARDMETA|DELAYRESPONSE",
  • "u_long_message": "Item 1\nItem2\nItem3"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "u_confirmed": "yes"
}

Prompt Customer for Input

Requests input from the user for the given input type

libmonetra KVS equivalent for endpoint

  • u_action = reqinput
Authorizations:
basic_auth
query Parameters
u_device
required
string
Example: u_device=SER:COM3

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
object
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"
Example: u_devicetype=ingenico_upp

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
u_inputtype
required
object
Enum: "PHONENUM" "INVOICENUM" "ZIP" "EMAIL" "TIP" "AMOUNT" "LIST"
Example: u_inputtype=ZIP

Type of user input being requested

Values:

  • PHONENUM - Request phone number entry. This may be useful for loyalty card prompting
  • INVOICENUM - Request invoice/order/ticket number entry
  • ZIP - Request zip code entry
  • EMAIL - Request email entry
  • TIP - Request tip entry. Requires amount to be passed to calculate tip percentages. Uses the tip percentages configured within the Payment Server merchant account configuration.
  • AMOUNT - Request amount entry. Generic entry for a monetary amount.
  • LIST - Request list entry. Requires u_inputlist which is a pipe (|) separated list of items to select from. Will return the index (0 start) of the item selected.
u_message
string
Example: u_message=Hello, Customer

Request message to show to the customer

Used and required by LIST type

Requires:

  • u_device
  • u_devicetype
u_flags
object
Enum: "DEVICEONLY" "GUIONLY" "KEY" "AVS" "CVV" "GIFTPIN" "NOEXPDATE" "NOTIP" "NOCASHBACK" "NOCONFIRM" "NOSIGNATURE" "DELAYRESPONSE" "CARDMETA" "NOSTANDIN" "PERSISTDEVICE" "EXTERNALSELECT" "DENYLISTQUEUE"
Example: u_flags=NOSIGNATURE|CARDMETA|DELAYRESPONSE

Multiple flags may be sent per data ticket request. All flags are separated by a pipe (|) symbol.

Flag values (pipe separated):

  • DEVICEONLY - Suppress display of clerk-facing prompting and feedback, also known as GUI Mode. For instance, on a swipe request, no swipe dialog would be presented nor would the clerk be informed of the status for customer-facing device interaction. Note: Setting this mode will prevent keyboard emulation readers from working. It will also prevent the ability for accepting clerk-keyed input via a keyboard. On Android, iOS, and UniTerm launched in console mode, this flag is automatically implied, as none of those support a GUI mode of operation.
  • GUIONLY - Suppress use of a referenced physical device. This flag can be used to utilize the physical device's UniTerm license for a clerk-facing GUI request, without using the device itself for card input. Without this flag, the GUI would register an additional UniTerm license based on the machine's unique ID.
  • KEY - Perform capture of manually-keyed data. Not valid on cardrequest. If an account or expdate field is passed in on the request to UniTerm, the fields will be pre-populated in GUI mode. Note: If a manually keyed EBT card is to be entered for a Food Stamp (SNAP) transaction, pass the qualified food amount via u_foodamount in order to go through the EBT flow and PIN prompting. Do NOT pass u_foodamount if you are NOT intending to run a Food Stamp transaction as keyed.
  • AVS - Request AVS data. Only allowed on keyed transactions. If a street or zip field is passed in on the request to UniTerm, those fields will be pre-populated in GUI mode.
  • CVV - Request for CVV data. Only allowed on keyed transactions.
  • GIFTPIN - Request a PIN for gift cards, when a gift card is presented. Does nothing if a different card type is presented.
  • NOEXPDATE - Disable expiration date prompting.
  • NOTIP - Disable tip prompting. This will override the merch_tippercent option in the Payment Server merchant account configuration.
  • NOCASHBACK - Disable cashback prompting. This will override the merch_cashbackmax option in the Payment Server merchant account configuration.
  • NOCONFIRM - When performing a QuickChip finalization via txnfinish, do not prompt the cardholder to confirm the amount prior to running the authorization.
  • NOSIGNATURE - If using a signature-capable device, but an integrator does not want to use the auto signature-capture capabilities in the UniTerm flow, treat the device as if it is not capable of accepting a signature. The u_need_signature response flag will be set appropriately for the transaction requirements.
  • DELAYRESPONSE - Send the transaction response back to the caller after the device has been closed. The device can be used immediately for a subsequent transaction with this flag. Otherwise, device closing will happen in the background, which will hold a lock on the device for at least 100ms, possibly longer.
  • CARDMETA - Request the card metadata directly from the Payment Server (v8.9.0+) rather than relying on less-detailed internal information. The relevant metadata would be from a Global BIN table, which contains information such as if a card is Debit-capable, HSA/FSA-capable, and so on. When used during a txnstart request, it allows an integrator to make decisions based on the card presented (such as for support of Debt Repayment or Healthcare transactions). When used during a txnrequest or txnquick, it optimizes the flow on transactions such as not prompting for Debit on a swipe transaction if the card is not debit capable.
  • NOSTANDIN - Transaction is not eligible for standin approval
  • PERSISTDEVICE - Maintain a persistent device connection
  • EXTERNALSELECT - Customer input for selection can be handled externally to the device. The status action must be polled to determine when and what external prompting should take place. The response needs to be provided to the external response action once the customer has made their selection.
  • DENYLISTQUEUE - Check if card is on block list and if not queue the transaction for later processing
u_inputlist
string
Example: u_inputlist=TEST|123

List of elements to allow selection from

Only used by LIST type.

Pipe (|) separated list of elements. E.g TEST|123|ABC. The index of the item in the list (starting from 0) will be returned, in u_input, if an item is selected.

For example, with the list TEST|123|ABC if the customer chose 123, then u_input would be set to 1.

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/prompt/input' \
  --basic -u 'test_retail|public:publ1ct3st' \
  -G \
  -d 'u_device=IPCLIENT:78909876' \
  -d 'u_devicetype=ingenico_upp' \
  -d 'u_inputtype=ZIP'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "u_input": "string",
  • "u_tip": "string"
}

Request Customer Signature

Prompts customer for signature

This is for non-financial requests. For financial transactions, a signature will be automatically captured and stored within the Payment Server, so there is no need to call this function.

This should only be used outside of a transaction flow (e.g. Request, Quick, Start, Finish).

libmonetra KVS equivalent for endpoint

  • u_action = reqsignature
Authorizations:
basic_auth
query Parameters
u_device
required
string
Example: u_device=SER:COM3

This specifies the path of the card entry device. Required parameter unless performing a GUI-based action (such as manual keyed entry, or swiping via a keyboard emulation card reader). Required if u_devicetype is provided.

  • HID[:serialnum] - HID (such as USB-HID), takes an optional serial number
  • SER:port - Serial
  • MFI:protocol,[serialnum] - Made for iOS (MFi), as retrieved from u_action=mfilist
  • BT:mac,[uuid] - Bluetooth
  • BLE:identifier - Bluetooth LE using device identifier as retrieved from u_action=blelist, u_blelist=scan
  • BLESRV:service_uuid - Bluetooth LE using the device service ID as retrieved from u_action=blelist
  • IP:ipaddr:port - IP
  • TLS:ipaddr:port - TLS encrypted IP
  • IPCLIENT:serialnum - IP Client Mode. Currently only supported for devices that support client mode for ethernet connectivity. For example, Ingencio RBA and UPP devices. UniTerm will act as a server, and the devices will connect to UniTerm and be referenced by their serial number.

Note: USB is a deprecated alias for HID. It should not be used and will be removed in a future release.

Requires:

  • u_devicetype
u_devicetype
required
object
Enum: "ingenico_rba" "ingenico_upp" "ingenico_tcpx" "idtech_spectrum_pro" "idtech_augusta" "bbpos_cros" "equinox_epe" "idtech_neo" "epson_esc" "star_line" "seiko" "generic_barcode"
Example: u_devicetype=ingenico_upp

The unique device type supported as found via a device types request.

Requires:

  • u_device

Values:

  • ingenico_rba - Ingenico iSC/iPP/iUN/iSMP (RBA)
  • ingenico_upp - Ingenico Lane/Move/Link (UPP)
  • ingenico_tcpx - Ingenico iPP/iUN (TCPX-Canada)
  • idtech_spectrum_pro - ID TECH Spectrum Pro
  • idtech_augusta - ID TECH Augusta
  • bbpos_cros - BBPos Chipper 2X BT (Cros)
  • equinox_epe - Equinox LUXE 6200m/8500i
  • idtech_neo - ID Tech VP3300/VP5300
  • epson_esc - Epson POS Printer, and/or cash drawer
  • star_line - Star POS Printer, cash drawer, and/or barcode scanner
  • seiko - Seiko POS Printer, and/or cash drawer
  • generic_barcode - Barcode Scanner
u_flags
object
Enum: "DEVICEONLY" "GUIONLY" "KEY" "AVS" "CVV" "GIFTPIN" "NOEXPDATE" "NOTIP" "NOCASHBACK" "NOCONFIRM" "NOSIGNATURE" "DELAYRESPONSE" "CARDMETA" "NOSTANDIN" "PERSISTDEVICE" "EXTERNALSELECT" "DENYLISTQUEUE"
Example: u_flags=NOSIGNATURE|CARDMETA|DELAYRESPONSE

Multiple flags may be sent per data ticket request. All flags are separated by a pipe (|) symbol.

Flag values (pipe separated):

  • DEVICEONLY - Suppress display of clerk-facing prompting and feedback, also known as GUI Mode. For instance, on a swipe request, no swipe dialog would be presented nor would the clerk be informed of the status for customer-facing device interaction. Note: Setting this mode will prevent keyboard emulation readers from working. It will also prevent the ability for accepting clerk-keyed input via a keyboard. On Android, iOS, and UniTerm launched in console mode, this flag is automatically implied, as none of those support a GUI mode of operation.
  • GUIONLY - Suppress use of a referenced physical device. This flag can be used to utilize the physical device's UniTerm license for a clerk-facing GUI request, without using the device itself for card input. Without this flag, the GUI would register an additional UniTerm license based on the machine's unique ID.
  • KEY - Perform capture of manually-keyed data. Not valid on cardrequest. If an account or expdate field is passed in on the request to UniTerm, the fields will be pre-populated in GUI mode. Note: If a manually keyed EBT card is to be entered for a Food Stamp (SNAP) transaction, pass the qualified food amount via u_foodamount in order to go through the EBT flow and PIN prompting. Do NOT pass u_foodamount if you are NOT intending to run a Food Stamp transaction as keyed.
  • AVS - Request AVS data. Only allowed on keyed transactions. If a street or zip field is passed in on the request to UniTerm, those fields will be pre-populated in GUI mode.
  • CVV - Request for CVV data. Only allowed on keyed transactions.
  • GIFTPIN - Request a PIN for gift cards, when a gift card is presented. Does nothing if a different card type is presented.
  • NOEXPDATE - Disable expiration date prompting.
  • NOTIP - Disable tip prompting. This will override the merch_tippercent option in the Payment Server merchant account configuration.
  • NOCASHBACK - Disable cashback prompting. This will override the merch_cashbackmax option in the Payment Server merchant account configuration.
  • NOCONFIRM - When performing a QuickChip finalization via txnfinish, do not prompt the cardholder to confirm the amount prior to running the authorization.
  • NOSIGNATURE - If using a signature-capable device, but an integrator does not want to use the auto signature-capture capabilities in the UniTerm flow, treat the device as if it is not capable of accepting a signature. The u_need_signature response flag will be set appropriately for the transaction requirements.
  • DELAYRESPONSE - Send the transaction response back to the caller after the device has been closed. The device can be used immediately for a subsequent transaction with this flag. Otherwise, device closing will happen in the background, which will hold a lock on the device for at least 100ms, possibly longer.
  • CARDMETA - Request the card metadata directly from the Payment Server (v8.9.0+) rather than relying on less-detailed internal information. The relevant metadata would be from a Global BIN table, which contains information such as if a card is Debit-capable, HSA/FSA-capable, and so on. When used during a txnstart request, it allows an integrator to make decisions based on the card presented (such as for support of Debt Repayment or Healthcare transactions). When used during a txnrequest or txnquick, it optimizes the flow on transactions such as not prompting for Debit on a swipe transaction if the card is not debit capable.
  • NOSTANDIN - Transaction is not eligible for standin approval
  • PERSISTDEVICE - Maintain a persistent device connection
  • EXTERNALSELECT - Customer input for selection can be handled externally to the device. The status action must be polled to determine when and what external prompting should take place. The response needs to be provided to the external response action once the customer has made their selection.
  • DENYLISTQUEUE - Check if card is on block list and if not queue the transaction for later processing

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/prompt/signature' \
  --basic -u 'test_retail|public:publ1ct3st' \
  -G \
  -d 'u_device=IPCLIENT:78909876' \
  -d 'u_devicetype=ingenico_upp'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "u_signature": "string"
}

Payment Server

Payment Server operations

Send data to Payment Server

Performs a direct pass-through of parameters to the Payment Server

This method will simply proxy requests to the Payment Server. It can be used for transaction modifications (e.g. voids) or for pulling reports from the Payment Server.

Do not use this request if cardholder data needs to be retrieved for the transaction, as it will not be returned.

Sensitive cardholder data is explicitly prohibited from being sent as pass-through.

Users may wish to send their requests directly to the Payment Server rather than using this feature.

libmonetra KVS equivalent for endpoint

  • u_action = passthrough
Authorizations:
basic_auth
Request Body schema: application/json
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "property1": "string",
  • "property2": "string"
}

System

System operations

Get User Access Information

User access information

This is a Master Command secure operation with the following restrictions:

  • Request must be HMACed using the secure operation shared secret when remote access (localonly=no) is configured.
  • IP address of requester is allowed by configurable IP filter

Tracks users and their last action with UniTerm. The action is logged in this report when it has completed. Meaning, the currently running operation will not be listed until it has finished.

Only one entry per use will appear in the report. The user entry is updated with each completed operation. Not all fields will have data if they were not present in the operation. For example, device may be empty if a device was not used.

The resulting report will contain these headers:

username, device, u_action, action, u_errcode, code, ttid, tran_finish_ts

Where:

  • username - User
  • device - Last device used. Format <Connecivity>:<location>:<type>. For example, SER:/dev/cu.usbmodem142401:ingenico_upp.
  • u_action - UniTerm action performed
  • action - Payment server action requested
  • u_errcode - UniTerm response code returned
  • code - General result code
  • ttid - Transaction identifier
  • tran_finish_ts - Time stamp of when the last transaction finished

libmonetra KVS equivalent for endpoint

  • u_action = sysinfo
  • u_sysinfo = access
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/access'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

Get Banned IP History Report

Banned connection history information

This is a Master Command secure operation with the following restrictions:

  • Request must be HMACed using the secure operation shared secret when remote access (localonly=no) is configured.
  • IP address of requester is allowed by configurable IP filter

An IP address that has been banned may appear multiple times in the report. It is added each time the IP is banned. This does not include extensions to an existing ban. Only the event that triggered a ban is included. It is not possible to tell with this report if an IP is currently banned. The banned report should be used for this information.

The resulting report will contain these headers:

ipaddr, ban_event, banned_ts

Where:

  • ipaddr - Banned IP address
  • ban_event - Event that caused the ban
  • banned_ts - Unix timestamp when the IP address was banned

libmonetra KVS equivalent for endpoint

  • u_action = sysinfo
  • u_sysinfo = banned_history
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/banned/history'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

Get Banned IPs

Banned connection information

This is a Master Command secure operation with the following restrictions:

  • Request must be HMACed using the secure operation shared secret when remote access (localonly=no) is configured.
  • IP address of requester is allowed by configurable IP filter

Only currently banned IP address are reported here.

The resulting report will contain these headers:

ipaddr, ban_event, expire_ts

Where:

  • ipaddr - Banned IP address
  • ban_event - Event that caused the ban
  • expire_ts - Unix timestamp when the IP address will be removed from the ban

libmonetra KVS equivalent for endpoint

  • u_action = sysinfo
  • u_sysinfo = banned
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/blacklisted'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

Get Connection Failure Report

Connection failure information

This is a Master Command secure operation with the following restrictions:

  • Request must be HMACed using the secure operation shared secret when remote access (localonly=no) is configured.
  • IP address of requester is allowed by configurable IP filter

The resulting report will contain these headers:

ipaddr, port, error, device_port, ts

Where:

  • ipaddr - IP address
  • port - Port the connection was attempted on
  • error - Error message describing the failure
  • device_port - yes if port is listening for a device to connect
  • ts - Unix timestamp when the IP address failed to

libmonetra KVS equivalent for endpoint

  • u_action = sysinfo
  • u_sysinfo = connection_fails
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/connection/failures'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

Clear Cached Merchant Information

Clears all cached merchant-related data within both the client and host

This ensures full loading data is pulled during the next transaction or deviceload

libmonetra KVS equivalent for endpoint

  • u_action = expirecached
Authorizations:
basic_auth

Responses

Request samples

curl -X DELETE 'https://uniterm.test.transafe.com:8123/api/v1/merchant/cache/clear' --basic -u 'test_retail|public:publ1ct3st'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Get IP Client History Report

IP device client history information

This is a Master Command secure operation with the following restrictions:

  • Request must be HMACed using the secure operation shared secret when remote access (localonly=no) is configured.
  • IP address of requester is allowed by configurable IP filter

The resulting report will contain these headers:

ipaddr, port, serialnum, dev_type, event_type, ts

Where:

  • ipaddr - IP address
  • port - Port the connection was attempted on
  • serialnum - Serial number of device
  • dev_type - Device type
  • event_type - connected if conencted event, otherwise disconnected
  • ts - Unix timestamp when the event took place

libmonetra KVS equivalent for endpoint

  • u_action = sysinfo
  • u_sysinfo = ipclient_history
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/connection/ipclients'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "report": "..."
}

Shut Down

Terminates execution of the UniTerm process

This should be called when the application software terminates.

libmonetra KVS equivalent for endpoint

  • u_action = shutdown
Authorizations:
basic_auth

Responses

Request samples

curl -X POST 'https://uniterm.test.transafe.com:8123/api/v1/system/shutdown'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Get UniTerm Status

Request general information about the current status of UniTerm"

This is a Master Command secure operation with the following restrictions:

  • Request must be HMACed using the secure operation shared secret when remote access (localonly=no) is configured.
  • IP address of requester is allowed by configurable IP filter

libmonetra KVS equivalent for endpoint

  • u_action = sysinfo
  • u_sysinfo = stats
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/stats'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "modify_config_pending": "yes",
  • "shutdown_pending": "yes",
  • "txn_pending": "0",
  • "txn_running": "1"
}

Check Health

Checks that UniTerm is running

libmonetra KVS equivalent for endpoint

  • u_action = ping
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}

Get Version

Requests the current version of UniTerm

The version information is output in human-readable format in the verbiage response field. The version information also contains the build number.

libmonetra KVS equivalent for endpoint

  • u_action = sysinfo
  • u_sysinfo = version
Authorizations:
None

Responses

Request samples

curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/version'

Response samples

Content type
application/json
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved"
}