Overview

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

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

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

Communication to UniTerm from Integration

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

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

User Setup Permissions and Requirements

All authentication is managed by the Payment Server.

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

UniTerm also requires these permissions to operate:

  • CHKPWD
  • 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
  • ADMIN:MERCHINFO - Used for populating receipt metadata and determining merchant card brands and capabilities in use
  • ADMIN:GETPERMS - Used for verifying account setup.
  • ADMIN:IMAGEADD - Only required if device support signature capture.
  • ADMIN:CARDSHIELDPROVISION - Only required if supporting stand-in or chiptab operations.

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

Prompting

UniTerm handles various types of common customer prompting requirements.

Tip Prompting

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

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

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

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

Cashback Prompting

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

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

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

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

EBT Processing

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

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

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

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

EMV

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

Transaction Flow and Prompting

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

Swipe prompts to insert

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

Tap prompts to insert

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

Insert prompts to swipe

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

PIN required on Credit Cards

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

Signature not requested

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

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

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

Immediate decline without contacting the processor

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

Pre-formatted Receipt Processing

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

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

Parameter and Response KVS

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

Parameter Groups

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

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

Time Formats

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

  • formatted time
  • Unix timestamp

Formatted

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

Fixed

Fixed formats are very similar to written date and times.

Formats:

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

Offset

Offsets take this format:

+ or -
  magnitude
  space
  modifier

Modifiers:

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

Example

+1 day
-5 years

Special keywords

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

Unix Timestamp

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

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

Authentication

Only HTTP Basic authentication is currently supported.

basic_auth

Security scheme type: HTTP
HTTP Authorization Scheme basic

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.

Example

user:sub -> user|sub

Transaction

Transaction operations

Cancel

Attempts to cancel an outstanding transaction request

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

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

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

200

processed operation

post /transaction/{u_id}/cancel

Production server

https://uniterm.live.transafe.com:8123/api/v1/transaction/{u_id}/cancel

Test server

https://uniterm.test.transafe.com:8123/api/v1/transaction/{u_id}/cancel

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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.

Authorizations:
Request Body schema: application/json
u_device
stringHID(:?|:.*)|(SER||MFI|BT|BLE|BLESRV|IP|IPCLIENT):.+

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

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

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

Responses

200

processed operation

post /transaction/cardrequest

Production server

https://uniterm.live.transafe.com:8123/api/v1/transaction/cardrequest

Test server

https://uniterm.test.transafe.com:8123/api/v1/transaction/cardrequest

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "trackdata": "trackdata",
  • "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.

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

200

processed operation

get /transaction/{u_id}/status

Production server

https://uniterm.live.transafe.com:8123/api/v1/transaction/{u_id}/status

Test server

https://uniterm.test.transafe.com:8123/api/v1/transaction/{u_id}/status

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "code": "AUTH",
  • "u_cancelable": "yes",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "u_status": "WORKING"
}

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.

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 authamount response parameter will be returned. When a partial authorization is received, a merchant should request another payment method for the remaining funds. It is acceptable to request a reversal if no additional payment methods are possible.

All card brands are requiring merchants to support partial authorizations. Not doing so could result in a fine. Some issuers may return partial approvals even without this flag because of the requirements in place.

Values:

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

Identifier for the register/lane running the transaction

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

ordernum
string <= 128 characters

Order number

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

Normally, an order number is alphanumeric, max 25 characters. However, for the Restaurant industry, a 6-digit number should be used.

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

Amount of money, including decimal. E.g 1.00

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

tax
string(?s)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

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

Amount of funds being received as a surcharge

u_foodamount
string(?s)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).

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

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

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

Amount of the order that can be used for tip calculation

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

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

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

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

An example of split payment

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

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

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

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

Notes

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

Clerk requirements

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

property name*
string

Responses

200

processed operation

post /transaction/{u_id}/finish

Production server

https://uniterm.live.transafe.com:8123/api/v1/transaction/{u_id}/finish

Test server

https://uniterm.test.transafe.com:8123/api/v1/transaction/{u_id}/finish

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "code": "AUTH",
  • "u_errorcode": "SUCCESS",
  • "verbiage": "Transaction approved",
  • "msoft_code": "INT_SUCCESS",
  • "phard_code": "SUCCESS",
  • "authamount": "string",
  • "account": "XXXXXXXXXXXX1234",
  • "ttid": "string",
  • "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.

Authorizations:
Request Body schema: application/json
action
required
string

Action the Payment Server should perform on the captured data

u_device
required
stringHID(:?|:.*)|(SER||MFI|BT|BLE|BLESRV|IP|IPCLIENT):.+

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

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

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

nsf
string
Enum: "yes" "no"

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

All card brands are requiring merchants to support partial authorizations. Not doing so could result in a fine. Some issuers may return partial approvals even without this flag because of the requirements in place.

Values:

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

Identifier for the register/lane running the transaction

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

ordernum
string <= 128 characters

Order number

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

Normally, an order number is alphanumeric, max 25 characters. However, for the Restaurant industry, a 6-digit number should be used.

u_flags
string
Enum: "DEVICEONLY" "GUIONLY" "KEY" "AVS" "CVV" "GIFTPIN" "NOTIP" "NOCASHBACK" "NOCONFIRM" "NOSIGNATURE" "DELAYRESPONSE" "CARDMETA"

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

Flag values:

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

Used to override terminal defaults for display of text prompts. Not all de