Terminals APIs

Version

Current Specification Version: 210-ing

View Change History

* 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 cloud integration 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. 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:
  • Communication failure (E16 error code) - connection to the gateway is established, but a connection reset occurs during the transmission of an API request or an API response. In this case, the gateway or an intermediate instance terminates the connection, and the transaction result cannot be obtained. Connection reset can be caused by network interference or by a behavior of an application that receives the request.
  • Read timeout (E17 error code) - connection to the gateway is established, a request is submitted, but the response is not received due to a timeout (i.e. waiting time for the gateway response is exceeded).

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-Auth (deprecated)   
an operation used to deposit (return) specific amounts of money to the supplied credit card or bank account. Credit-Auth requires an explicit capture operation in order for the money to be transferred; otherwise, an automatic void is issued.
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.

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.

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.