Terminals APIs
Version
Current Specification Version: V8.2.2
General
Settlement
Gift/Loyalty Cards
Miscellaneous
Ticket Management
Supported Operations
General 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 TidyPay 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.
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 TidyPay 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.
During transaction processing, a disconnect may occur for the following reasons:
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:
In these areas, the following instances are responsible for identifying if a disconnect is present:
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.
- 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:
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
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-auth and capture in a single process.
credit-auth and capture in a single process
confirms a previously requested authorization (sale or credit)
allows conversion of a credit card number or a bank account number into a PCI compliant token value.
URL supplied by a submitter for receiving notifications about offline sale, decline, chargeback and reversal operations.
Settlement
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.
Gift/Loyalty Cards
Miscellaneous
allows a submitter to find transactions by transaction code or transaction ID.
allows capturing of a signature submitted with the transaction. This operation is applicable to touch screen terminals only. See integration notes for more information.
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.
Ticket Management
allows to finalize the ticket and prepare it for the authorization request to the gateway.
allows to add a purchase item to an open ticket. An item captures information about a specific item that a customer purchased.
allows to add a list of purchase items to an open ticket. List of items captures information about items that a customer purchased.
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. |
Copyright ©
TidyPay. All Rights Reserved.
All Logos and Trademarks used or mentioned on this page are copyrighted property of their respective owners and are used for display purposes only.