Terminals APIs

Version

Current Specification Version: V9.1.4

View Change History

General

Settlement

Gift/Loyalty Cards

Miscellaneous

Ticket Management

Supported Operations

* Available for testing with host emulator

General Information

Overview

The purpose of this document is to provide documentation for 3rd parties to integrate with UniCharge terminal payments management.

Connectivity Information

The connection URL for the sandbox server is: https://[server-name]/terminals/xurl.
Authorization is done via service users. To access the API, a service user is required to be granted with a corresponding privilege. A user can submit API requests using either associated credentials or temporary password generated via authentication operation.

When submitting an API request, you can use either UniPay server URL or the Sanitizing Data Filter (Unibroker) server URL as an endpoint.
Requests that contain tokenized card numbers/bank account numbers can be submitted directly to {Unipay} server.
To reduce PCI exposure, requests with non-tokenized (raw) account data should be passed through the sanitizing data filter server. Otherwise, L04 error will be returned (Processing of raw account data is not allowed through the specified API end-point for the current user).
If you don’t have a specific reason, we recommend sending all the requests to the same endpoint (data filter).
To learn more about service users and end-points used for API submission, review Security Management guide.
Request method is POST. The content-type must be set to application/x-www-form-urlencoded.
Request fields are passed within HTTPS request body (including cases with callbacks) and are required to be URL-encoded.
Response fields are passed within HTTPS response body.
Both request and response field values are passed using name1=key1&name2=key2 format.

Connectivity Problems

During transaction processing, a disconnect may occur for the following reasons:

Connection timeout (error code E12) - the cloud doesn't receive a response from the terminal within 5 minutes while processing the transaction.
The terminal is unreachable (error code E22) - the connectivity issues between the terminal and the cloud may occur in the following cases:

1) The terminal was disconnected when the cloud was attempting to send a message to the terminal.
2) The channel between the terminal and cloud is inactive during a time period specified as one-minute timeout due to a bad connection.
3) The terminal disconnected and reregistered while processing the transaction (occurs when the terminal submits repeated registration request without interrupting the connection with cloud established before).

When using the HTTPS protocol, which is used in the communication architecture between a POS system and the gateway, the gateway cannot determine whether the disconnect has occurred. Thus, when the POS submits a request to the gateway, the gateway cannot determine that the connection has failed, and the POS has been disconnected. Therefore, in some cases, the transaction response may not be delivered to the final recipient, i.e. to the POS. In such cases, there is a possibility that the transaction has been approved but the gateway has marked it as a decline due to the disconnect.

If you look at the Transaction Processing Flow for Cloud diagram, you can see the following communication areas, which use the HTTPS protocol:

area between a POS and cloud;
area between a terminal and the gateway;
area between the gateway and a processor.

In these areas, the following instances are responsible for identifying if a disconnect is present:

area between a POS and cloud - the POS;
area between a terminal and the gateway - the terminal;
area between the gateway and a processor - the gateway.

If there is a disconnect, responsible instances must execute the void operation. In the first case, when the POS is the responsible instance, make sure that the void is executed by the POS. In the second and third cases, when the terminal or the gateway is responsible correspondingly, the void is executed automatically.

Note that when a terminal is disconnected from the gateway after a transaction request has been submitted, the terminal attempts to make a void on the transaction up to three times. If the connection is not restored, no void is made. Therefore, we recommend the POS to make three void attempts to ensure that the transaction is processed, the result is obtained, and the original transaction does not remain within the gateway.

Supported Operations

General

Sale-Auth

an operation used to withdraw specific amounts of money from the supplied credit card or bank account. Sale-Auth requires an explicit capture operation in order for the money to be transferred; otherwise, an automatic void is issued.

Sale

sale-auth and capture in a single process.

Credit

credit-auth and capture in a single process

Void

an operation used to reverse a sale operation.

Refund

an operation used to reverse a sale operation.

Capture

confirms a previously requested authorization (sale or credit)

Tokenization

allows conversion of a credit card number or a bank account number into a PCI compliant token value.

Callback

URL supplied by a submitter for receiving notifications about offline sale, decline, chargeback and reversal operations.

Settlement

Close Cycle

allows a submitter to close currently open retail cycle (batch) for an account, send all captured transactions within the cycle for settlement, see totals within a retail cycle and reverse any void transactions.

Clear Batch

allows to clear previously performed transactions within a terminal, thereby, assuming them to be settled. This operation is normally used for processors where host capture settlement is utilized.

Gift/Loyalty Cards

Capture Card

allows to process a gift card via a terminal.

Miscellaneous

Ping

allows to verify availability of the server and get the current version of the API.

Find

allows a submitter to find transactions by transaction code or transaction ID.

Capture Signature

allows capturing of a signature submitted with the transaction. This operation is applicable to touch screen terminals only. See integration notes for more information.

Show Splash

allows to call a splash screen that will be displayed on the terminal for a certain time amount.

Note: To make a splash screen disappear, press any button on a terminal or it will disappear automatically when the time specified as timeout gets over.

Show Message

allows to show a custom prompt dialog message that will be displayed on the terminal.

Capture-Value

allows to capture a string value (for example a rewards number or an email).

Ticket Management

Create Ticket

allows to create a ticket, which represents a purchase with items in the POS system.

Close Ticket

allows to finalize the ticket and prepare it for the authorization request to the gateway.

Add Item

allows to add a purchase item to an open ticket. An item captures information about a specific item that a customer purchased.

Add Item List

allows to add a list of purchase items to an open ticket. List of items captures information about items that a customer purchased.

Update Item

allows to update an existing item, e.g. quantity, price, discount or tax amount.

Remove Item

allows to remove item from an open ticket.

Get Configuration

Balance Inquiry Cycle

Merchant Info

Message Formats

Usage:

R	-	required in request/always present in response for direct debit transactions and credit card transactions of all levels (I, II, III).
O	-	optional in request/not always present in response.
C	-	conditional; conditions of the usage are defined below the corresponding section.
E	-	echo back from request; if present in request, it is present in response, if it is not present in request, it is not present in response.
R2	-	required in request/always present in response for credit card transactions of level II and III only; optional for direct debit and level I credit card transactions.
R3	-	required in request/always present in response for credit card transactions of III only; optional for direct debit and level I, II credit card transactions.
SR	-	required in request/always present in response for split transactions only.
I	-	for internal use only.
N	-	not used.
*	-	required fields in these specific sections are only required if this specific feature is used.