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
Authorize payment method without immediate settlement.
- Amounts must be specified in cents.
- Requires capture operation to complete funds transfer.
- Without capture, authorization is automatically voided at processing cut-off time.
- If no valid transaction response is received, use transaction find with original transactionCode to verify status.
- For capture after cut-off time, contact support for configuration assistance.
- Suitable for verifying funds before completing a transaction.
- Terminal guides customers through amount confirmation and card processing steps.
- Amounts must be specified in cents.
- Requires capture operation to complete funds transfer.
- Without capture, authorization is automatically voided at processing cut-off time.
- If no valid transaction response is received, use transaction find with original transactionCode to verify status.
- For capture after cut-off time, contact support for configuration assistance.
- Suitable for verifying funds before completing a transaction.
- Terminal guides customers through amount confirmation and card processing steps.
Authorize and capture transaction in a single operation for immediate settlement.
- Terminal displays amount for customer confirmation before card swipe or dip.
- Terminal operations such as signature capture must complete before API response is returned.
- If no valid transaction response is received, use transaction find with original transactionCode to check status.
- Transaction may exist but not be approved.
- Sale transactions are automatically settled at processing cut-off time.
- Implement error handling for communication interruptions to improve customer experience.
- Terminal displays amount for customer confirmation before card swipe or dip.
- Terminal operations such as signature capture must complete before API response is returned.
- If no valid transaction response is received, use transaction find with original transactionCode to check status.
- Transaction may exist but not be approved.
- Sale transactions are automatically settled at processing cut-off time.
- Implement error handling for communication interruptions to improve customer experience.
Issue refund or credit without referencing a previous transaction.
- Authorizes and captures funds in a single process, transferring them immediately to the customer's account.
- May not be available for all merchant accounts; contact support to enable.
- Use for standalone credit transactions, not for refunding a specific purchase.
- For refunds on previous transactions, use refund operation instead.
- Authorizes and captures funds in a single process, transferring them immediately to the customer's account.
- May not be available for all merchant accounts; contact support to enable.
- Use for standalone credit transactions, not for refunding a specific purchase.
- For refunds on previous transactions, use refund operation instead.
Cancel pending transaction before settlement.
- Supports cancellation of sales, authorizations, and credits.
- Transactions can be voided only until daily cut-off time.
- Compatible terminals automatically print receipts upon void.
- Void requests after cut-off may be converted to refunds or rejected.
- Use for same-day cancellations to avoid refund fees and release funds immediately to customers.
- Supports cancellation of sales, authorizations, and credits.
- Transactions can be voided only until daily cut-off time.
- Compatible terminals automatically print receipts upon void.
- Void requests after cut-off may be converted to refunds or rejected.
- Use for same-day cancellations to avoid refund fees and release funds immediately to customers.
Refund payments by reversing completed sale transactions.
- Refund amount cannot exceed the original transaction amount.
- Partial refunds are supported for order adjustments.
- Refunds can only be issued for previously completed transactions.
- Ensure account has sufficient privileges to process refunds.
- Refund transactions impact settlement and reconciliation.
- Refund amount cannot exceed the original transaction amount.
- Partial refunds are supported for order adjustments.
- Refunds can only be issued for previously completed transactions.
- Ensure account has sufficient privileges to process refunds.
- Refund transactions impact settlement and reconciliation.
Capture previously authorized transaction to complete payment.
- Include the transactionId from the original sale-auth transaction.
- Terminal displays capture notification but requires no user interaction.
- Authorized transactions are automatically voided after daily cut-off time.
- Contact support for extended capture timeframes beyond standard cut-off.
- Keep record of all sale-auth transactionIds for successful capture.
- Include the transactionId from the original sale-auth transaction.
- Terminal displays capture notification but requires no user interaction.
- Authorized transactions are automatically voided after daily cut-off time.
- Contact support for extended capture timeframes beyond standard cut-off.
- Keep record of all sale-auth transactionIds for successful capture.
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.
Capture digital signature from signature-capable terminals without processing payment.
- Only compatible with touchscreen terminals.
- Captured signature is cropped to boundaries, encoded, and returned in API response.
- Signatures are not stored in the gateway system by default.
- To store a signature permanently, use upload-resource API call after capture.
- Suitable for signing agreements, contracts, or receipts without payment.
- Only compatible with touchscreen terminals.
- Captured signature is cropped to boundaries, encoded, and returned in API response.
- Signatures are not stored in the gateway system by default.
- To store a signature permanently, use upload-resource API call after capture.
- Suitable for signing agreements, contracts, or receipts without payment.
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.
Display custom messages on payment terminals and collect customer responses.
- Messages appear as dialog prompts on the terminal with selectable response options.
- Ensure your application handles customer responses from the API to maintain transaction flow.
- Can be used to gather feedback, show transaction details, or present additional options to enhance payment experience.
- Messages appear as dialog prompts on the terminal with selectable response options.
- Ensure your application handles customer responses from the API to maintain transaction flow.
- Can be used to gather feedback, show transaction details, or present additional options to enhance payment experience.
Capture string values from customers through terminal interactions.
- Supports collecting loyalty IDs, email addresses, or other text inputs during transaction flow.
- Enables gathering of various string data to enhance customer profiles.
- Can be used to support loyalty programs or collect contact information for marketing.
- Supports collecting loyalty IDs, email addresses, or other text inputs during transaction flow.
- Enables gathering of various string data to enhance customer profiles.
- Can be used to support loyalty programs or collect contact information for marketing.
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.