UniTerm (1.5.3)
Download OpenAPI specification:Download
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.
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.
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.
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.
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.
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 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.
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 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.
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.
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 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_MAXATTEMPTSCONN_MAXSENDS
phard_code:
NOREPLYRETRYSYSTEM_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.
A value denoting a time can take on one of two different types:
- formatted time
- Unix timestamp
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/timeepoch- Unix timestamp of 0 = Jan 1, 1970 00:00:00 UTC
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.
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 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_idauth_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;
?>
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;
?>
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 |
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.
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.
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.
- Ensures the device is online and accessible
- Ensures the user account is still being actively used
- Authentication credentials are necessary to perform the check and UniTerm wants to limit the time it holds these in memory.
- 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.
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.
- Install UniTerm
- Copy the
uniterm_example.inifrom the installation directory into the following directory depending on your platform. The file should be nameduniterm.iniwhen placing in the configuration directory. As indicated in the following full file paths. a. Windows:%APPDATA%/UniTerm/uniterm.inib. macOS:~/Library/Application Support/UniTerm/uniterm.inic. Linux/Unix:~/.config/UniTerm/uniterm.ini - Make any desired configuration changes to the
inifile. 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. - Start UniTerm
- 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.
- Locate where the device is connected to the system. For example, on windows a
USB<>SERIALdevice will be assigned aCOMport. Such asCOM3. - With the device location and type now known you can start using UniTerm. Please see the
txnquickdocumentation for a complete example of running a transaction.
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.
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.
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:
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
curl -X POST 'https://uniterm.test.transafe.com:8123/api/v1/transaction/U656789324/cancel' --basic -u 'test_retail|public:publ1ct3st' -d ''
Response samples
- 200
{- "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:
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
curl -X DELETE 'https://uniterm.test.transafe.com:8123/api/v1/transaction/U656789324' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
Responses
Request samples
- Payload
- cURL JSON
- cURL Form
{- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp"
}Response samples
- 200
{- "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:
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
- Payload
- cURL JSON
- cURL Form
{- "u_selection": "1"
}Response samples
- 200
{- "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:
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
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/transaction/U656789324/status' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "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:
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 Gift cards default to If a partial approval is received, it will automatically be reversed internally
and the returned decline will have Values:
|
| 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 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:
|
| examount | string\d+(\.\d{0,2})? Extra amount. Typically used for Retail and Restaurant tipping Requires:
|
| 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:
|
| 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 During a If the amount passed in |
| 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 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 Clerk requirements When using |
| property name* additional property | string |
Responses
Request samples
- Payload
- cURL JSON
- cURL Form
{- "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
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
| 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 Gift cards default to If a partial approval is received, it will automatically be reversed internally
and the returned decline will have Values:
|
| 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):
|
| 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:
|
| 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 A value of A value of All other values are key/value pairs indicating formatting configurations, separated by semicolons, as in this example: Receipt configuration options:
|
| amount | string\d*(\.\d{0,2})? Amount of money, including decimal. E.g 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:
|
| examount | string\d+(\.\d{0,2})? Extra amount. Typically used for Retail and Restaurant tipping Requires:
|
| 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:
|
| 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 During a If the amount passed in |
| 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 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 Clerk requirements When using |
| property name* additional property | string |
Responses
Request samples
- Payload
- cURL JSON
- cURL Form
- cURL JSON - Keyed
- cURL Form - Keyed
{- "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
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
| 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 Gift cards default to If a partial approval is received, it will automatically be reversed internally
and the returned decline will have Values:
|
| 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):
|
| 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:
|
| 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 A value of A value of All other values are key/value pairs indicating formatting configurations, separated by semicolons, as in this example: Receipt configuration options:
|
| amount | string\d*(\.\d{0,2})? Amount of money, including decimal. E.g 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:
|
| examount | string\d+(\.\d{0,2})? Extra amount. Typically used for Retail and Restaurant tipping Requires:
|
| 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:
|
| 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 During a If the amount passed in |
| 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 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 Clerk requirements When using |
| property name* additional property | string |
Responses
Request samples
- Payload
- cURL JSON
- cURL Form
- cURL JSON - Keyed
- cURL Form - Keyed
- cURL JSON - Keyed GUI
- cURL Form - Keyed GUI
{- "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
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
| 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):
|
| 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:
|
| 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 During a If the amount passed in |
| 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 A value of A value of All other values are key/value pairs indicating formatting configurations, separated by semicolons, as in this example: Receipt configuration options:
|
| property name* additional property | string |
Responses
Request samples
- Payload
- cURL JSON
- cURL Form
{- "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
- 200
{- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "Transaction approved",
- "cardtype": "VISA",
- "trackdata": "string",
- "u_cardclass": "UNKNOWN",
- "property1": "string",
- "property2": "string"
}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
PERSISTDEVICEflag - 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:
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
Note: Requires:
|
| 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:
Values:
|
Responses
Request samples
- Payload
- cURL
{- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp"
}Response samples
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
Responses
Request samples
- cURL
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
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
Responses
Request samples
- cURL
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
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
| u_forceload | string Enum: "yes" "no" "full" Ignore device load checks and force reload terminal configuration Values:
|
Responses
Request samples
- Payload
- cURL
{- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp",
- "u_forceload": "yes"
}Response samples
- 200
{- "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:
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:
|
Responses
Request samples
- Payload
- cURL JSON
- cURL Form
{- "u_message": "Hello, Customer"
}Response samples
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
| u_text required | string ASCII pre-formatted text to send to receipt printer Requires:
|
Responses
Request samples
- Payload
- cURL JSON
- cURL Form
{- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp",
- "u_text": "string"
}Response samples
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
Responses
Request samples
- Payload
- cURL JSON
- cURL Form
{- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp"
}Response samples
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
| u_b64data required | string[a-zA-Z0-9+/\n]+={0,2}[\n]* Base64-encoded file data Requires:
|
| 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
- Payload
- cURL JSON
- cURL Form
{- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp",
- "u_b64data": "ABC=",
- "u_filename": "UPDATE.BIN"
}Response samples
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
Responses
Request samples
- Payload
- cURL
{- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp"
}Response samples
- 200
{- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "Transaction approved"
}Read a Barcode
Authorizations:
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
Note: Requires:
|
| 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:
Values:
|
Responses
Request samples
- cURL
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
- 200
{- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "Transaction approved",
- "u_barcode": "string"
}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:
query Parameters
| u_blelist | object Value: "scan" Example: u_blelist=scan Type of BLE action Values:
|
| 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
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/ble'
Response samples
- 200
{- "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:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/bluetooth'
Response samples
- 200
{- "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:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list'
Response samples
- 200
{- "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:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/hid'
Response samples
- 200
{- "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:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/ipclient'
Response samples
- 200
{- "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:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/mfi'
Response samples
- 200
{- "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:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/device/list/serial'
Response samples
- 200
{- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "Transaction approved",
- "report": "..."
}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=tabu_tab=close
Authorizations:
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 For example, the current amount is $15.00. Sending Note: |
| amount | string\d*(\.\d{0,2})? Amount of money, including decimal. E.g 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
Note: Requires:
|
| 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:
Values:
|
| 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):
|
| 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:
|
| 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 A value of A value of All other values are key/value pairs indicating formatting configurations, separated by semicolons, as in this example: Receipt configuration options:
|
Responses
Request samples
- Payload
- cURL JSON
- cURL Form
- cURL JSON - Device
- cURL Form - Device
{- "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
- 200
{- "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=tabu_tab=force_close
Authorizations:
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 For example, the current amount is $15.00. Sending Note: |
| amount | string\d*(\.\d{0,2})? Amount of money, including decimal. E.g 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
- Payload
- cURL JSON
- cURL Form
{- "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
- 200
{- "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=tabu_tab=list
Authorizations:
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 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:
|
| 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
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/tab' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "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=tabu_tab=open
Authorizations:
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
Note: Requires:
|
| 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:
Values:
|
| 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):
|
| 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:
|
| 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 A value of A value of All other values are key/value pairs indicating formatting configurations, separated by semicolons, as in this example: Receipt configuration options:
|
Responses
Request samples
- Payload
- cURL JSON
- cURL Form
{- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp",
- "u_flags": "NOSIGNATURE|CARDMETA|DELAYRESPONSE",
- "u_language": "en",
- "u_id": "1234",
- "u_rcpt": "yes"
}Response samples
- 200
{- "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=tabu_tab=totals
Authorizations:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/tab/totals' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "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=tabu_tab=update
Authorizations:
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 For example, the current amount is $15.00. Sending Note: |
| amount | string\d*(\.\d{0,2})? Amount of money, including decimal. E.g 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
- Payload
- cURL JSON
- cURL Form
{- "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
- 200
{- "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=tabu_tab=void
Authorizations:
path Parameters
| ttid required | string Example: 96748596765467 Transaction identifier |
Responses
Request samples
- cURL
curl -X DELETE 'https://uniterm.test.transafe.com:8123/api/v1/tab/U1294139' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "Transaction approved"
}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=standinu_standin=activity
Authorizations:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/stored/activity' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "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=standinu_standin=list
Authorizations:
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 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:
|
| 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
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/stored' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "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=standinu_standin=send
Authorizations:
Responses
Request samples
- cURL
curl -X POST 'https://uniterm.test.transafe.com:8123/api/v1/stored/send' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "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=standinu_standin=totals
Authorizations:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/stored/totals' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "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=standinu_standin=update
Authorizations:
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 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
- Payload
- cURL JSON
- cURL Form
{- "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
- 200
{- "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=standinu_standin=void
Authorizations:
path Parameters
| ttid required | string Example: 96748596765467 Transaction identifier |
Responses
Request samples
- cURL
curl -X DELETE 'https://uniterm.test.transafe.com:8123/api/v1/stored/U1294139' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "Transaction approved"
}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=standinu_standin=delresp
Authorizations:
path Parameters
| ttid required | string Example: 96748596765467 Transaction identifier |
Responses
Request samples
- cURL
curl -X DELETE 'https://uniterm.test.transafe.com:8123/api/v1/stored/response/U921234' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "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=standinu_standin=getresp
Authorizations:
path Parameters
| ttid required | string Example: 96748596765467 Transaction identifier |
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/stored/response/U921234' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "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=standinu_standin=listresp
Authorizations:
query Parameters
| ttid | string Example: ttid=96748596765467 Transaction identifier |
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/stored/response' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "Transaction approved",
- "report": "..."
}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:
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
Note: Requires:
|
| 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:
Values:
|
| u_message required | string Example: u_message=Hello, Customer Request message to show to the customer Requires:
|
| 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):
|
| 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:
|
Responses
Request samples
- cURL JSON
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
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
| u_message required | string Request message to show to the customer Requires:
|
| 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):
|
| 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:
|
Responses
Request samples
- Payload
- cURL JSON
- cURL Form
{- "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
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
| u_inputtype required | object Enum: "PHONENUM" "INVOICENUM" "ZIP" "EMAIL" "TIP" "AMOUNT" "LIST" Example: u_inputtype=ZIP Type of user input being requested Values:
|
| u_message | string Example: u_message=Hello, Customer Request message to show to the customer Used and required by Requires:
|
| 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):
|
| u_inputlist | string Example: u_inputlist=TEST|123 List of elements to allow selection from Only used by Pipe (|) separated list of elements. E.g For example, with the list |
Responses
Request samples
- cURL
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
- 200
{- "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:
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
Note: Requires:
|
| 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:
Values:
|
| 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):
|
Responses
Request samples
- cURL
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
- 200
{- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "Transaction approved",
- "u_signature": "string"
}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:
Request Body schema: application/json
| property name* additional property | string |
Responses
Request samples
- Payload
{- "property1": "string",
- "property2": "string"
}Response samples
- 200
{- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "Transaction approved",
- "property1": "string",
- "property2": "string"
}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=sysinfou_sysinfo=access
Authorizations:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/access'
Response samples
- 200
{- "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=sysinfou_sysinfo=banned_history
Authorizations:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/banned/history'
Response samples
- 200
{- "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=sysinfou_sysinfo=banned
Authorizations:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/blacklisted'
Response samples
- 200
{- "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 -
yesif port is listening for a device to connect - ts - Unix timestamp when the IP address failed to
libmonetra KVS equivalent for endpoint
u_action=sysinfou_sysinfo=connection_fails
Authorizations:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/connection/failures'
Response samples
- 200
{- "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:
Responses
Request samples
- cURL
curl -X DELETE 'https://uniterm.test.transafe.com:8123/api/v1/merchant/cache/clear' --basic -u 'test_retail|public:publ1ct3st'
Response samples
- 200
{- "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 -
connectedif conencted event, otherwisedisconnected - ts - Unix timestamp when the event took place
libmonetra KVS equivalent for endpoint
u_action=sysinfou_sysinfo=ipclient_history
Authorizations:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/connection/ipclients'
Response samples
- 200
{- "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:
Responses
Request samples
- cURL
curl -X POST 'https://uniterm.test.transafe.com:8123/api/v1/system/shutdown'
Response samples
- 200
{- "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=sysinfou_sysinfo=stats
Authorizations:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/stats'
Response samples
- 200
{- "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:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system'
Response samples
- 200
{- "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=sysinfou_sysinfo=version
Authorizations:
Responses
Request samples
- cURL
curl -X GET 'https://uniterm.test.transafe.com:8123/api/v1/system/version'
Response samples
- 200
{- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "Transaction approved"
}