UniTerm (1.0.0)
Download OpenAPI specification:Download
UniTerm securely handles sensitive cardholder data independent of the merchants application software. In addition, UniTerm provides a simple consistent interface to multiple payment acceptance devices such as card readers, pinpads and terminals.
At the heart of the protocol is a simple key/value pair message structure, very similar to the Payment Server Interface Protocol Specification. In fact, some of these key/value pairs sent to UniTerm are simply passed-through to the Payment Server for processing.
All authentication is managed by the Payment Server.
UniTerm requires that sensitive data never be returned from the Payment Server in order to ensure that the integrated POS is removed from PCI PA-DSS scope. In order to ensure this, UniTerm only allows merchant sub-users to authenticate. Sub users are unique usernames that can be tied to a merchant user with their own individual password, but provided only a subset of the permissions allowed. 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 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.
UniTerm supports prompting the cardholder for a tip amount at the time of payment when the Payment Server merchant account configuration merch_tippercent setting is configured and the NOTIP u_flags parameter is NOT provided.
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 the 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 if 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 if they would like to request Cash Back when presenting a Debit or EBT Cash Benefits card for payment. UniTerm will automatically perform such prompting when the Payment Server account is configured to support cashback and the NOCASHBACK u_flags parameter is NOT set.
When a customer has chosen to request Cash Back with a transaction, the amount provided by the POS to UniTerm will be incremented to reflect the Cash Back amount and the cashbackamount parameter will be populated with the Cash Back amount when the transaction is sent to the Payment Server.
In the response returned by UniTerm, the Cash Back 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 Cash Back 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 prompting if the card presented is an EBT card. If the u_foodamount parameter is populated with a non-zero dollar amount indicating the amount of the transaction that applies to qualified food purchases (or for txnstart 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 txnstart transactions where u_foodamount=maybe, the integrator must send a valid u_foodamount value with txnfinish otherwise 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 the authamount response parameter) indicating the amount of the authorization was less than the requested. This 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. In the case of magnetic stripe and EMV transaction, the application software will send the request to UniTerm. The device capabilities (EMV for example) will be determined by UniTerm, along with the merchant account configuration. From these UniTerm will handle the appropriate prompting and flow aspects related to the determined capabilities. The application software simply needs to send a u_action=TXNREQUEST and let UniTerm handle the rest.
Integrators unfamiliar with EMV may notice some specific flow cases that seem counter- intuitive 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 which cannot be lifted and it is meant to train consumers to insert their cards and to prevent fraud.
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 be inserted instead. When this occurs, it can be due to a number of factors including fraud mitigation, or the card has determined 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, called a technical fallback. It is expected at some point in the future, technical fallback will be disallowed due to fraud concerns. The other possibility is if the application id in use by the card is not supported by the terminal.
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 card, no insert requested
It is a requirement by the card brands that if a chip-capable card is presented as a tap that the card NOT be prompted for insertion. 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 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 compliant receipts 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 specifying format requirements. If set to yes it will simply use the receipt formatting for plain text. Suitable for printing on a standard receipt printer. Multiple other output formats are supported and discussed in within 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 are also documented. Additional request parameters specific to the Payment Server may be specified and passed through. The Payment Server may pass back additional response data.
Only HTTP Basic authentication is currently support.
Basic auth does not allow colons (':') to be present in usersnames. However, most usernames for the system will include a colon. To deal with this all colon's must be replaced with a pipe ('|').
If a username contains a pipe please contact support.
Example
user:sub -> user|subCancel
Will attempt to cancel an outstanding transaction request. Requires username, password and u_id which must match the pending request. If the transaction cannot be canceled, such as if it is ineligible (such as when waiting on a response from the Payment Server), or the device doesn't support canceling the outstanding request, u_errorcode will return PENDING_TRAN.
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
processed operation
Production server
Test server
Request samples
- cURL Form
- cURL JSON
curl "https://uniterm.test.transafe.com/api/v1/transaction/1234/cancel" \ --basic -u "test_retail|public:publ1ct3st" \ -X POST \ -d ""
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Non-Financial Card Entry
UniTerm will prompt for card entry, and if it is determined the card is non-financial, it will return the card data. This can be used for manager cards and private label gift cards that are not processed through 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 | string 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.
|
| u_devicetype | string The unique device type supported as found via a device types request. |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp"
Response samples
- 200
- "trackdata": "string",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
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. 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
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/transaction/1234/status" \ --basic -u "test_retail|public:publ1ct3st" \ -X GET \ -d ""
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Transaction Finish
Transaction Finish Request. Request 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 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
| amount required | string Amount of money including decimal. E.g '1.00' |
| u_foodamount | string Food qualified amount (E.g. 1.00) or 'maybe' indicating possible EBT qualified full or partial order If qualified amount is known, dollar amount indicating amount of qualified food purchases for EBT Food Stamps (SNAP). Or during an Txnstart the food amount may not yet be known, but to enable EBT prompting, a special value of 'maybe' may be passed, followed by the the real amount in Txnfinish. If the amount passed in Txnfinish is zero, but EBT Food Stamps was selected by the card holder, the transaction will be aborted. |
| nsf | string Enum: "yes" "no" Approve transactions even if there are insufficient funds (NSF). Will result in a partial approval if there are insufficient funds, an authamount response parameter will be returned for partial authorizations. 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 support partial authorizations, merchants can be subjected to fines. Some issuers may return partial approvals even without this flag because of the requirements in place. |
| laneid | string The lane ID is a Mastercard requirement 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 A merchant order number is required on all card not present (mail order and ecommerce) transactions, Restaurant, and all Level2 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 normally alpha-numeric up to 25 characters, however for restaurant a 6 digit order number should be used |
| tax | string Amount of tax that applies to the order. |
| examount | string If a tip amount is known at the time of sale it must be populated, if using the built-in tip-prompting, this field should not be passed in. |
| surchargeamount | string Amount of funds being recived as a surcharge |
| property name* | string |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "amount": "19.92",
- "u_foodamount": "maybe",
- "nsf": "yes",
- "laneid": "4",
- "ordernum": "A13DDES345",
- "tax": "1.29",
- "examount": "0.33",
- "surchargeamount": "1.25",
- "property1": "string",
- "property2": "string"
Response samples
- 200
- "u_wasfood": "yes",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string",
- "msoft_code": "string",
- "phard_code": "string",
- "authamount": "string",
- "account": "XXXXXXXXXXXX1234",
- "ttid": "string",
- "u_emv_chip_malfunction": "yes",
- "u_need_signature": "yes",
- "u_tip": "string",
- "cardtype": "string",
- "u_cardclass": "UNKNOWN",
- "u_cashback": "string",
- "u_flowflags": "SIGCAPTURED",
- "u_standin": "yes",
- "property1": "string",
- "property2": "string"
Transaction Quick
Full Transaction Request for card holder data. Request a transaction be performed, all normal Payment Server transaction parameters should be included in the request that may be required for processing or to comply with interchange requirements (e.g. action, amount, nsf, ordernum, etc). Sensitive data, explicitly, should not be sent (e.g. trackdata, account, cvv2, pin) as that data will be retrieved by UniTerm either via the GUI or via a card entry device and forwarded to the Payment Server server as part of the transaction request.
This operation is functionally similar to txnrequest however internally it follows a Quick Chip 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
| amount required | string Amount of money including decimal. E.g '1.00' |
| action required | string Action the Payment Server should perform on the captured data |
| u_device required | string 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.
|
| 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 insufficient funds (NSF). Will result in a partial approval if there are insufficient funds, an authamount response parameter will be returned for partial authorizations. 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 support partial authorizations, merchants can be subjected to fines. Some issuers may return partial approvals even without this flag because of the requirements in place. |
| laneid | string The lane ID is a Mastercard requirement 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 A merchant order number is required on all card not present (mail order and ecommerce) transactions, Restaurant, and all Level2 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 normally alpha-numeric up to 25 characters, however for restaurant a 6 digit order number should be used |
| tax | string Amount of tax that applies to the order. |
| examount | string If a tip amount is known at the time of sale it must be populated, if using the built-in tip-prompting, this field should not be passed in. |
| surchargeamount | string Amount of funds being recived as a surcharge |
| u_foodamount | string Food qualified amount (E.g. 1.00) or 'maybe' indicating possible EBT qualified full or partial order If qualified amount is known, dollar amount indicating amount of qualified food purchases for EBT Food Stamps (SNAP). Or during an Txnstart the food amount may not yet be known, but to enable EBT prompting, a special value of 'maybe' may be passed, followed by the the real amount in Txnfinish. If the amount passed in Txnfinish is zero, but EBT Food Stamps was selected by the card holder, the transaction will be aborted. |
| 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. |
| 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. |
| 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 u_rcpt key/value pair is sent in the request to indicate whether or not to output a series of pre-formatted receipt blocks. This can also specifying format requirements. If set to 'yes', a default output will be returned. When passing formatting configuration to u_rcpt, it will take the key/value pairs from the table below and encode them in a set of semi-colon separated key/value pairs such as: Receipt configuration options:
|
| property name* | string |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "amount": "19.92",
- "action": "sale",
- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp",
- "nsf": "yes",
- "laneid": "4",
- "ordernum": "A13DDES345",
- "tax": "1.29",
- "examount": "0.33",
- "surchargeamount": "1.25",
- "u_foodamount": "maybe",
- "u_flags": "NOSIGNATURE|CARDMETA|DELAYRESPONSE",
- "u_language": "en",
- "u_id": "1234",
- "u_rcpt": "yes",
- "property1": "string",
- "property2": "string"
Response samples
- 200
- "u_wasfood": "yes",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string",
- "msoft_code": "string",
- "phard_code": "string",
- "authamount": "string",
- "account": "XXXXXXXXXXXX1234",
- "ttid": "string",
- "u_emv_chip_malfunction": "yes",
- "u_need_signature": "yes",
- "u_tip": "string",
- "cardtype": "string",
- "u_cardclass": "UNKNOWN",
- "u_cashback": "string",
- "u_flowflags": "SIGCAPTURED",
- "u_standin": "yes",
- "property1": "string",
- "property2": "string"
Transaction Request
Full Transaction Request for card holder data.
Request a transaction be performed, all normal Payment Server transaction parameters should be included in the request that may be required for processing or to comply with interchange requirements (e.g. action, username, password, amount, nsf, ordernum, etc).
Sensitive data, explicitly, should not be sent (e.g. trackdata, account, cvv2, pin) as that data will be retrieved by UniTerm either via the GUI or via a card entry device and forwarded to the Payment Server server as part of the transaction request.
UniTerm will fully control the transaction flow and user prompting for such a transaction. 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.",
Authorizations:
Request Body schema: application/json
| amount required | string Amount of money including decimal. E.g '1.00' |
| action required | string Action the Payment Server should perform on the captured data |
| u_device | string 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.
|
| u_devicetype | string The unique device type supported as found via a device types request. |
| nsf | string Enum: "yes" "no" Approve transactions even if there are insufficient funds (NSF). Will result in a partial approval if there are insufficient funds, an authamount response parameter will be returned for partial authorizations. 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 support partial authorizations, merchants can be subjected to fines. Some issuers may return partial approvals even without this flag because of the requirements in place. |
| laneid | string The lane ID is a Mastercard requirement 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 A merchant order number is required on all card not present (mail order and ecommerce) transactions, Restaurant, and all Level2 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 normally alpha-numeric up to 25 characters, however for restaurant a 6 digit order number should be used |
| tax | string Amount of tax that applies to the order. |
| examount | string If a tip amount is known at the time of sale it must be populated, if using the built-in tip-prompting, this field should not be passed in. |
| surchargeamount | string Amount of funds being recived as a surcharge |
| u_foodamount | string Food qualified amount (E.g. 1.00) or 'maybe' indicating possible EBT qualified full or partial order If qualified amount is known, dollar amount indicating amount of qualified food purchases for EBT Food Stamps (SNAP). Or during an Txnstart the food amount may not yet be known, but to enable EBT prompting, a special value of 'maybe' may be passed, followed by the the real amount in Txnfinish. If the amount passed in Txnfinish is zero, but EBT Food Stamps was selected by the card holder, the transaction will be aborted. |
| 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. |
| 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. |
| 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 u_rcpt key/value pair is sent in the request to indicate whether or not to output a series of pre-formatted receipt blocks. This can also specifying format requirements. If set to 'yes', a default output will be returned. When passing formatting configuration to u_rcpt, it will take the key/value pairs from the table below and encode them in a set of semi-colon separated key/value pairs such as: Receipt configuration options:
|
| property name* | string |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "amount": "19.92",
- "action": "sale",
- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp",
- "nsf": "yes",
- "laneid": "4",
- "ordernum": "A13DDES345",
- "tax": "1.29",
- "examount": "0.33",
- "surchargeamount": "1.25",
- "u_foodamount": "maybe",
- "u_flags": "NOSIGNATURE|CARDMETA|DELAYRESPONSE",
- "u_language": "en",
- "u_id": "1234",
- "u_rcpt": "yes",
- "property1": "string",
- "property2": "string"
Response samples
- 200
- "trackdata": "string",
- "u_wasfood": "yes",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string",
- "msoft_code": "string",
- "phard_code": "string",
- "authamount": "string",
- "account": "XXXXXXXXXXXX1234",
- "ttid": "string",
- "u_emv_chip_malfunction": "yes",
- "u_need_signature": "yes",
- "u_tip": "string",
- "cardtype": "string",
- "u_cardclass": "UNKNOWN",
- "u_cashback": "string",
- "u_flowflags": "SIGCAPTURED",
- "u_standin": "yes",
- "property1": "string",
- "property2": "string"
Transaction Start
Transaction Start Request for card holder data. Request to start a QuickChip transaction, similar in function to a txnrequest message, but does not accept a transaction amount. 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.
Authorizations:
Request Body schema: application/json
| action required | string Action the Payment Server should perform on the captured data |
| 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_foodamount | string Food qualified amount (E.g. 1.00) or 'maybe' indicating possible EBT qualified full or partial order If qualified amount is known, dollar amount indicating amount of qualified food purchases for EBT Food Stamps (SNAP). Or during an Txnstart the food amount may not yet be known, but to enable EBT prompting, a special value of 'maybe' may be passed, followed by the the real amount in Txnfinish. If the amount passed in Txnfinish is zero, but EBT Food Stamps was selected by the card holder, the transaction will be aborted. |
| u_device required | string 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.
|
| u_devicetype required | string The unique device type supported as found via a device types request. |
| 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. |
| 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. |
| u_rcpt | string The u_rcpt key/value pair is sent in the request to indicate whether or not to output a series of pre-formatted receipt blocks. This can also specifying format requirements. If set to 'yes', a default output will be returned. When passing formatting configuration to u_rcpt, it will take the key/value pairs from the table below and encode them in a set of semi-colon separated key/value pairs such as: Receipt configuration options:
|
| property name* | string |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "action": "sale",
- "u_id": "1234",
- "u_foodamount": "maybe",
- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp",
- "u_flags": "NOSIGNATURE|CARDMETA|DELAYRESPONSE",
- "u_language": "en",
- "u_rcpt": "yes",
- "property1": "string",
- "property2": "string"
Response samples
- 200
- "code": "AUTH",
- "cardtype": "string",
- "u_errorcode": "SUCCESS",
- "verbiage": "string",
- "trackdata": "string",
- "u_cardclass": "UNKNOWN",
- "property1": "string",
- "property2": "string"
Device Information
Requests the information about the connected device.
Authorizations:
query Parameters
| u_device required | string Example: u_device=SER%3ACOM3 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.
|
| u_devicetype required | string Example: u_devicetype=ingenico_upp The unique device type supported as found via a device types request. |
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/device?u_device=SER%3ACOM3&u_devicetype=ingenico_upp" \ --basic -u "test_retail|public:publ1ct3st" \ -X GET \ -d ""
Response samples
- 200
- "device_app": "string",
- "device_appver": "string",
- "device_functionality": "string",
- "device_kernver": "string",
- "device_manuf": "string",
- "device_model": "string",
- "serialnum": "string",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Load terminal configuration
Load a device with EMV and/or Interac parameters. This request will start a terminal download of EMV and/or Interac parameters to load into the device being used. Requires username, password, u_device, and u_devicetype parameters.
If the load for the device is identical to the previous load, the load will be skipped.
Please note 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.
Authorizations:
Request Body schema: application/json
| u_forceload | string Enum: "yes" "no" "full" Ignore device load checks and force reload terminal configuration |
| u_device required | string 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.
|
| u_devicetype required | string The unique device type supported as found via a device types request. |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "u_forceload": "yes",
- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp"
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string",
- "property1": "string",
- "property2": "string"
Update the device pole display
Only valid after a Quick Chip (txnstart) message, before txnfinish is called.
Requires the integrator 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 message (u_message) must be pre-formatted for the proper width of the display.
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 Textual request message to show to the customer |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "u_message": "Hello Customer"
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Device Print
Requests printing the given text to a built-in receipt printer if available. The text provided must be formatted properly for the, given device. Only plain text receipts are supported.
Authorizations:
Request Body schema: application/json
| u_text required | string ASCII pre-formatted text to print to receipt printer |
| u_device required | string 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.
|
| u_devicetype required | string The unique device type supported as found via a device types request. |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- "u_text": "string",
- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp"
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Device Reboot
Requests the device to reboot.
Authorizations:
Request Body schema: application/json
| u_device required | string 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.
|
| u_devicetype required | string The unique device type supported as found via a device types request. |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp"
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Upload a file to a device
Requests uploading the given file to the device at the requested device path. Not all devices support the concept of file uploads.
Typically used for updating device firmware.
Authorizations:
Request Body schema: application/json
| u_b64data required | string Base64-encoded file data |
| 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. |
| u_device required | string 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.
|
| u_devicetype required | string The unique device type supported as found via a device types request. |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "u_b64data": "ABC=",
- "u_filename": "UPDATE.BIN",
- "u_device": "SER:COM3",
- "u_devicetype": "ingenico_upp"
Response samples
- 200
- "u_needreboot": "yes",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
BLE supported devices
List of 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 if there are any devices nearby 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 CSV will contain these headers:
devicetype,name,serviceWhere:
- 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 near by 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 if 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 CSV will contain these headers:
devicetype,name,identifierWhere:
- 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
query Parameters
| u_blelist | object Value: "scan" Example: u_blelist=scan Type of BLE action |
| timeout | string Example: timeout=30 Lenght of time to wait before giving up. This is a hint/estimate and not a hard value |
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/device/list/ble" \ -X GET \ -d ""
Response samples
- 200
- "report": [ ],
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Bluetooth connected devices
List all Bluetooth (classic) devices that have been paired with the machine UniTerm is running on. The device may or may not be present. Currently only supported on Android and MacOS.
The resulting CSV will contain these headers:
name,mac,uuidWhere:
- name - The textual name of the device as registered with the operating system.
- mac - The device bluetooth MAC address
- uuid - The device bluetooth UUID
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/device/list/bluetooth" \ -X GET \ -d ""
Response samples
- 200
- "report": [ ],
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
List supported device types
Will return a comma separated list of device types supported. Headers:
- 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)
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/device/list" \ -X GET \ -d ""
Response samples
- 200
- "code": "AUTH",
- "report": [ ]
HID connected devices
List all supported HID (possibly USB-HID) devices that are currently attached to the machine UniTerm is running on.
The resulting CSV will contain these headers:
devicetype,manufacturer,model,product,serialnum,pathWhere:
- devicetype - The devicetype (device internal name) associated with the HID entry
- manufacturer - The manufacturer as advertised by the device.
- model - The pretty name for the device type as it is known to UniTerm
- product - The product as advertised by the device.
- serialnum - The serial number as advertised by the device
- path - The internal OS path the device is attached at
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/device/list/hid" \ -X GET \ -d ""
Response samples
- 200
- "report": [ ],
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Made for iOS connected devices
List all Made For iOS paired devices
Only supported on iOS
The resulting CSV will contain these headers:
devicetype,name,protocol,serialnumWhere:
- devicetype - The 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.Where:
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/device/list/mfi" \ -X GET \ -d ""
Response samples
- 200
- "report": [ ],
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Serial connected devices
List of all serial ports enumerated on the system.
The resulting CSV will contain these headers:
port,descWhere:
- port - The port pah
- desc - Description of port if applicable
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/device/list/serial" \ -X GET \ -d ""
Response samples
- 200
- "report": [ ],
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Close a Chip Tab
Close 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.
Authorizations:
path Parameters
| ttid required | string Transition identifier |
Request Body schema: application/json
| u_up_amount | string Tabs can have the stored amount increased or decreased using the u_up_amount key. Positive numbers will increase and negative will decrease. This is useful if the POS wants UniTerm to track the tab amount instead of tracking itself. For example, the current amount is $15.00. Sending u_up_amount=2.00 will change the current amount that is stored to $17.00. Next, sending u_up_amount=-3.00 will reduce the amount to $14.00. Note: u_up_amount is different than amount. Amount is the total and sending this key will replace the current value. u_up_amount modifies the current amount. |
| amount | string Amount of money including decimal. E.g '1.00' |
| tax | string Amount of tax that applies to the order. |
| examount | string If a tip amount is known at the time of sale it must be populated, if using the built-in tip-prompting, this field should not be passed in. |
| cashbackamount | string Amount of funds requested is for cash to be given to the client. Required if customer is receiving cash |
| surchargeamount | string Amount of funds being recived as a surcharge |
| clerkid | string Id of the clerk processing the transaction |
| comments | string Free form informationa about the transaction |
| custref | string Customer reference number. Applies to the customer, not the order |
| ordernum | string A merchant order number is required on all card not present (mail order and ecommerce) transactions, Restaurant, and all Level2 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 normally alpha-numeric up to 25 characters, however for restaurant a 6 digit order number should be used |
| ptrannum | string Numeric only order number. Superseded by ordernum and ordernum is preferred over ptrannum |
| stationid | string Identifier for the physical station accepteing the transaction |
| u_device | string 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.
|
| u_devicetype | string The unique device type supported as found via a device types request. |
| 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. |
| 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. |
| 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 u_rcpt key/value pair is sent in the request to indicate whether or not to output a series of pre-formatted receipt blocks. This can also specifying format requirements. If set to 'yes', a default output will be returned. When passing formatting configuration to u_rcpt, it will take the key/value pairs from the table below and encode them in a set of semi-colon separated key/value pairs such as: Receipt configuration options:
|
Responses
processed operation
Production server
Test server
Request samples
- Payload
- "u_up_amount": "12.00",
- "amount": "19.92",
- "tax": "1.29",
- "examount": "0.33",
- "cashbackamount": "1.25",
- "surchargeamount": "1.25",
- "clerkid": "12",
- "comments": "Test transaction",
- "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": "string",
- "msoft_code": "string",
- "phard_code": "string",
- "authamount": "string",
- "account": "XXXXXXXXXXXX1234",
- "ttid": "string",
- "u_emv_chip_malfunction": "yes",
- "u_need_signature": "yes",
- "u_tip": "string",
- "cardtype": "string",
- "u_cardclass": "UNKNOWN",
- "u_cashback": "string",
- "u_flowflags": "SIGCAPTURED",
- "u_standin": "yes",
- "property1": "string",
- "property2": "string"
Force close a Chip Tab
The transaction is sent directly to the Payment Server without customer interaction. Useful when a customer leaves without explicitly closing their tab
Authorizations:
path Parameters
| ttid required | string Transition identifier |
Request Body schema: application/json
| u_up_amount | string Tabs can have the stored amount increased or decreased using the u_up_amount key. Positive numbers will increase and negative will decrease. This is useful if the POS wants UniTerm to track the tab amount instead of tracking itself. For example, the current amount is $15.00. Sending u_up_amount=2.00 will change the current amount that is stored to $17.00. Next, sending u_up_amount=-3.00 will reduce the amount to $14.00. Note: u_up_amount is different than amount. Amount is the total and sending this key will replace the current value. u_up_amount modifies the current amount. |
| amount | string Amount of money including decimal. E.g '1.00' |
| tax | string Amount of tax that applies to the order. |
| examount | string If a tip amount is known at the time of sale it must be populated, if using the built-in tip-prompting, this field should not be passed in. |
| cashbackamount | string Amount of funds requested is for cash to be given to the client. Required if customer is receiving cash |
| surchargeamount | string Amount of funds being recived as a surcharge |
| clerkid | string Id of the clerk processing the transaction |
| comments | string Free form informationa about the transaction |
| custref | string Customer reference number. Applies to the customer, not the order |
| ordernum | string A merchant order number is required on all card not present (mail order and ecommerce) transactions, Restaurant, and all Level2 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 normally alpha-numeric up to 25 characters, however for restaurant a 6 digit order number should be used |
| ptrannum | string Numeric only order number. Superseded by ordernum and ordernum is preferred over ptrannum |
| stationid | string Identifier for the physical station accepteing the transaction |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- "u_up_amount": "12.00",
- "amount": "19.92",
- "tax": "1.29",
- "examount": "0.33",
- "cashbackamount": "1.25",
- "surchargeamount": "1.25",
- "clerkid": "12",
- "comments": "Test transaction",
- "custref": "55",
- "ordernum": "A13DDES345",
- "ptrannum": "1987",
- "stationid": "7"
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string",
- "msoft_code": "string",
- "phard_code": "string",
- "authamount": "string",
- "account": "XXXXXXXXXXXX1234",
- "ttid": "string",
- "u_emv_chip_malfunction": "yes",
- "u_need_signature": "yes",
- "u_tip": "string",
- "cardtype": "string",
- "u_cardclass": "UNKNOWN",
- "u_cashback": "string",
- "u_flowflags": "SIGCAPTURED",
- "u_standin": "yes",
- "property1": "string",
- "property2": "string"
List open Chip Tabs
List all tabs for the user returning a CSV result.
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,timestampAuthorizations:
query Parameters
| ttid | string Transition identifier |
| bdate | string Beginning date in search date range. See date format for more information |
| edate | string Ending date in search date range. See date format for more information |
| amount | string Example: amount=19.92 Amount of money including decimal. E.g '1.00' |
| examount | string Example: examount=0.33 If a tip amount is known at the time of sale it must be populated, if using the built-in tip-prompting, this field should not be passed in. |
| tax | string Example: tax=1.29 Amount of tax that applies to the order. |
| card | string Example: card=VISA Type of card that was used |
| pclevel | object Enum: "0" "1" "2" Example: pclevel=0 Purchase card identifier |
| account | string Example: account=1234 Last 4 digits of account number |
| expdate | string Example: expdate=1144 Expiration data of the card. MMYY format |
| cardholdername | string Example: cardholdername=John%20Doe Name of the cardholder. My not always be present |
| ordernum | string Example: ordernum=A13DDES345 A merchant order number is required on all card not present (mail order and ecommerce) transactions, Restaurant, and all Level2 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 normally alpha-numeric up to 25 characters, however for restaurant a 6 digit order number should be used |
| custref | string Example: custref=55 Customer reference number. Applies to the customer, not the order |
| ptrannum | string Example: ptrannum=1987 Numeric only order number. Superseded by ordernum and ordernum is preferred over ptrannum |
| clerkid | string Example: clerkid=12 Id of the clerk processing the transaction |
| stationid | string Example: stationid=7 Identifier for the physical station accepteing the transaction |
| comments | string Example: comments=Test%20transaction Free form informationa about the transaction |
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/tab" \ --basic -u "test_retail|public:publ1ct3st" \ -X GET \ -d ""
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Open a Chip Tab
Open a tab and capture customer card data
Authorizations:
Request Body schema: application/json
| amount | string Amount of money including decimal. E.g '1.00' |
| u_device required | string 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.
|
| u_devicetype required | string The unique device type supported as found via a device types request. |
| 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. |
| 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. |
| 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 u_rcpt key/value pair is sent in the request to indicate whether or not to output a series of pre-formatted receipt blocks. This can also specifying format requirements. If set to 'yes', a default output will be returned. When passing formatting configuration to u_rcpt, it will take the key/value pairs from the table below and encode them in a set of semi-colon separated key/value pairs such as: Receipt configuration options:
|
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "amount": "19.92",
- "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
- "ttid": "string",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string",
- "msoft_code": "string",
- "phard_code": "string",
- "authamount": "string",
- "account": "XXXXXXXXXXXX1234",
- "u_emv_chip_malfunction": "yes",
- "u_need_signature": "yes",
- "u_tip": "string",
- "cardtype": "string",
- "u_cardclass": "UNKNOWN",
- "u_cashback": "string",
- "u_flowflags": "SIGCAPTURED",
- "u_standin": "yes"
Chip Tabs totals
Total number of open tabs and total tracked amount of across all tabs. The total amount is only useful is using UniTerm to track the total for each tab by utilizing u_up_amount. If the POS is tracking 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.
Authorizations:
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/tab/totals" \ --basic -u "test_retail|public:publ1ct3st" \ -X GET \ -d ""
Response samples
- 200
- "num_trans": "44",
- "total_amount": "172.01",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Update a Chip Tab
Update metadata on file associated with a Chip Tab.
Authorizations:
path Parameters
| ttid required | string Transition identifier |
Request Body schema: application/json
| u_up_amount | string Tabs can have the stored amount increased or decreased using the u_up_amount key. Positive numbers will increase and negative will decrease. This is useful if the POS wants UniTerm to track the tab amount instead of tracking itself. For example, the current amount is $15.00. Sending u_up_amount=2.00 will change the current amount that is stored to $17.00. Next, sending u_up_amount=-3.00 will reduce the amount to $14.00. Note: u_up_amount is different than amount. Amount is the total and sending this key will replace the current value. u_up_amount modifies the current amount. |
| amount | string Amount of money including decimal. E.g '1.00' |
| tax | string Amount of tax that applies to the order. |
| examount | string If a tip amount is known at the time of sale it must be populated, if using the built-in tip-prompting, this field should not be passed in. |
| cashbackamount | string Amount of funds requested is for cash to be given to the client. Required if customer is receiving cash |
| surchargeamount | string Amount of funds being recived as a surcharge |
| clerkid | string Id of the clerk processing the transaction |
| comments | string Free form informationa about the transaction |
| custref | string Customer reference number. Applies to the customer, not the order |
| ordernum | string A merchant order number is required on all card not present (mail order and ecommerce) transactions, Restaurant, and all Level2 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 normally alpha-numeric up to 25 characters, however for restaurant a 6 digit order number should be used |
| ptrannum | string Numeric only order number. Superseded by ordernum and ordernum is preferred over ptrannum |
| stationid | string Identifier for the physical station accepteing the transaction |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- "u_up_amount": "12.00",
- "amount": "19.92",
- "tax": "1.29",
- "examount": "0.33",
- "cashbackamount": "1.25",
- "surchargeamount": "1.25",
- "clerkid": "12",
- "comments": "Test transaction",
- "custref": "55",
- "ordernum": "A13DDES345",
- "ptrannum": "1987",
- "stationid": "7"
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Void a Chip Tab
Deletes a tab. The tab is closed but never sent online for authorization.
Authorizations:
path Parameters
| ttid required | string Transition identifier |
Responses
processed operation
Production server
Test server
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
List stored transactions
List all stored transactions for the user returning a CSV result
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, timestampAuthorizations:
query Parameters
| ttid | string Transition identifier |
| bdate | string Beginning date in search date range. See date format for more information |
| edate | string Ending date in search date range. See date format for more information |
| 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 |
| amount | string Example: amount=19.92 Amount of money including decimal. E.g '1.00' |
| examount | string Example: examount=0.33 If a tip amount is known at the time of sale it must be populated, if using the built-in tip-prompting, this field should not be passed in. |
| tax | string Example: tax=1.29 Amount of tax that applies to the order. |
| card | string Example: card=VISA Type of card that was used |
| pclevel | object Enum: "0" "1" "2" Example: pclevel=0 Purchase card identifier |
| account | string Example: account=1234 Last 4 digits of account number |
| expdate | string Example: expdate=1144 Expiration data of the card. MMYY format |
| cardholdername | string Example: cardholdername=John%20Doe Name of the cardholder. My not always be present |
| ordernum | string Example: ordernum=A13DDES345 A merchant order number is required on all card not present (mail order and ecommerce) transactions, Restaurant, and all Level2 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 normally alpha-numeric up to 25 characters, however for restaurant a 6 digit order number should be used |
| custref | string Example: custref=55 Customer reference number. Applies to the customer, not the order |
| ptrannum | string Example: ptrannum=1987 Numeric only order number. Superseded by ordernum and ordernum is preferred over ptrannum |
| clerkid | string Example: clerkid=12 Id of the clerk processing the transaction |
| stationid | string Example: stationid=7 Identifier for the physical station accepteing the transaction |
| comments | string Example: comments=Test%20transaction Free form informationa about the transaction |
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/stored" \ --basic -u "test_retail|public:publ1ct3st" \ -X GET \ -d ""
Response samples
- 200
- "report": [ ],
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Send stored transactions for authorization
Initiate sending stored transactions to the Payment Server. 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 transactions may remain in a stored state if there are connectivity issues.
Since this triggers the timer it applies to stored transactions of all users on the system. You cannot selectivity send transactions.
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.
Authorizations:
Responses
processed operation
Production server
Test server
Request samples
- cURL Form
- cURL JSON
curl "https://uniterm.test.transafe.com/api/v1/stored/send" \ --basic -u "test_retail|public:publ1ct3st" \ -X POST \ -d ""
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Stored transaction totals
Number of stored transactions and total stored amount for the requesting user
Authorizations:
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/stored/totals" \ --basic -u "test_retail|public:publ1ct3st" \ -X GET \ -d ""
Response samples
- 200
- "num_trans": "44",
- "total_amount": "172.01",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Update a stored transaction
Update metadata on file associated with a stored transaction.
Authorizations:
path Parameters
| ttid required | string Transition identifier |
Request Body schema: application/json
| amount | string Amount of money including decimal. E.g '1.00' |
| tax | string Amount of tax that applies to the order. |
| examount | string If a tip amount is known at the time of sale it must be populated, if using the built-in tip-prompting, this field should not be passed in. |
| cashbackamount | string Amount of funds requested is for cash to be given to the client. Required if customer is receiving cash |
| clerkid | string Id of the clerk processing the transaction |
| comments | string Free form informationa about the transaction |
| custref | string Customer reference number. Applies to the customer, not the order |
| ordernum | string A merchant order number is required on all card not present (mail order and ecommerce) transactions, Restaurant, and all Level2 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 normally alpha-numeric up to 25 characters, however for restaurant a 6 digit order number should be used |
| ptrannum | string Numeric only order number. Superseded by ordernum and ordernum is preferred over ptrannum |
| stationid | string Identifier for the physical station accepteing the transaction |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- "amount": "19.92",
- "tax": "1.29",
- "examount": "0.33",
- "cashbackamount": "1.25",
- "clerkid": "12",
- "comments": "Test transaction",
- "custref": "55",
- "ordernum": "A13DDES345",
- "ptrannum": "1987",
- "stationid": "7"
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Void a stored transaction
Deletes a stored transaction. The transaction is never sent online for authorization.
Authorizations:
path Parameters
| ttid required | string Transition identifier |
Responses
processed operation
Production server
Test server
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Delete a stored transaction response
Purge the Payment Server response for a stored transaction that was successfully sent online.
Authorizations:
path Parameters
| ttid required | string Transition identifier |
Responses
processed operation
Production server
Test server
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Get a stored transaction response
Get 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.
Authorizations:
path Parameters
| ttid required | string Transition identifier |
Responses
processed operation
Production server
Test server
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string",
- "property1": "string",
- "property2": "string"
List stored transaction responses
A CSV report with basic information about stored transaction that have been successfully sent online. The TTID returned by UniTerm when stored will appear in the u_ttid column and the Payment Server's TTID will appear in the ttid column. Follow up transactions, such as 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 CSV will contain these headers:
u_ttid,ttid,timestamp,code,verbiageAuthorizations:
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/stored/response" \ --basic -u "test_retail|public:publ1ct3st" \ -X GET \ -d ""
Response samples
- 200
- "report": [ ],
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Request Customer Confirmation
Requests the user confirm a message presented on the device screen.
Authorizations:
query Parameters
| u_message required | string Example: u_message=Hello%20Customer Textual request message to show to the customer |
| u_device required | string Example: u_device=SER%3ACOM3 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.
|
| u_devicetype required | string Example: u_devicetype=ingenico_upp The unique device type supported as found via a device types request. |
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/prompt/confirm?u_message=Hello%20Customer&u_device=SER%3ACOM3&u_devicetype=ingenico_upp" \ --basic -u "test_retail|public:publ1ct3st" \ -X GET \ -d ""
Response samples
- 200
- "u_confirmed": "yes",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Prompt Customer for Input
Requests the user enter the requested input type.
Authorizations:
query Parameters
| u_inputtype required | object Enum: "PHONENUM" "INVOICENUM" "ZIP" "TIP" Example: u_inputtype=ZIP Type of user input being requested |
| u_device required | string Example: u_device=SER%3ACOM3 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.
|
| u_devicetype required | string Example: u_devicetype=ingenico_upp The unique device type supported as found via a device types request. |
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/prompt/input?u_inputtype=ZIP&u_device=SER%3ACOM3&u_devicetype=ingenico_upp" \ --basic -u "test_retail|public:publ1ct3st" \ -X GET \ -d ""
Response samples
- 200
- "u_input": "string",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Request Customer Signature
Requests the device to prompt for signature capture for non- financial requests. This should only be used outside of a transaction flow (e.g txnrequest or txnstart/txnfinish).
For financial transactions, a signature will be automatically captured and stored within Payment Server so there is no need to call this function.
Authorizations:
query Parameters
| u_device required | string Example: u_device=SER%3ACOM3 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.
|
| u_devicetype required | string Example: u_devicetype=ingenico_upp The unique device type supported as found via a device types request. |
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/prompt/signature?u_device=SER%3ACOM3&u_devicetype=ingenico_upp" \ --basic -u "test_retail|public:publ1ct3st" \ -X GET \ -d ""
Response samples
- 200
- "u_signature": "string",
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Data Passthrough
This action performs a direct pass-through of parameters to the Payment Server server. This method will simply proxy requests to the Payment Server and 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, it will not be returned.
Sensitive cardholder data is explicitly prohibited to be sent as pass-through.
Users may wish to send their requests directly to Payment Server rather than using this feature.
Authorizations:
Request Body schema: application/json
| property name* | string |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "property1": "string",
- "property2": "string"
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string",
- "property1": "string",
- "property2": "string"
Clear Cached Merchant Information
Clear all cached merchant-related data both within the client and host sides to ensure full load data is pulled during the next transaction or deviceload
Authorizations:
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/merchant/cache/clear" \ --basic -u "test_retail|public:publ1ct3st" \ -X DELETE \ -d ""
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Modify UniTerm Configuration
Allows a select number of ini configuration settings to be set via the API. In order to activate the ability to use this feature, an integrator must enable the shared secret in the configuration and the connection must come from the local machine.
Parameters are the same parameters as the ini with the section prepended.
Sections and keys are separated by either a '/' or a '.' E.g. standin.enabled
Authorizations:
Request Body schema: application/json
| property name* | string |
Responses
processed operation
Production server
Test server
Request samples
- Payload
- cURL Form
- cURL JSON
- "property1": "string",
- "property2": "string"
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/system" \ -X GET \ -d ""
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
Shutdown UniTerm
Terminates execution of the UniTerm process. This should be called when the application software terminates.
Authorizations:
Responses
processed operation
Production server
Test server
Request samples
- cURL Form
- cURL JSON
curl "https://uniterm.test.transafe.com/api/v1/system/shutdown" \ --basic -u "test_retail|public:publ1ct3st" \ -X POST \ -d ""
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"
The UniTerm 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.
Responses
processed operation
Production server
Test server
Request samples
- cURL
curl "https://uniterm.test.transafe.com/api/v1/system/version" \ -X GET \ -d ""
Response samples
- 200
- "code": "AUTH",
- "u_errorcode": "SUCCESS",
- "verbiage": "string"