Touch Screen Terminal Integration

      Touch Screen Terminal Integration


        Article summary

        The payment terminal can be controlled from another device on the local network using a simple REST API. Supported operations include:

        • Setting up (initiating) a payment

        • Getting the payment status

        • Cancellation

        • Refund

        • Preauthorization

        • Daily deadline

        • Printing a document

        Due to the number and variety of supported POS systems, we advise that you also consult their customer support if you require further clarification.

        The terminal and the cash register has to be connected to the same local network and that the HTTP protocol (not HTTPS) must be used for communication (see Final testing).

        Integration background

        The protocol for connecting to the POS system is available here. The current version of the documentation is 2.0.

        To test the protocol, a Demo application is available that simulates the behavior of the POS system. Open the demo in Firefox. The URL must be in http format. To log in, enter the IP and port number of the terminal and then the password 27924505 (the password is valid not only for the demo, but also for a live connection). The terminal and the computer must be connected to the same local network.

        You can also use the collections prepared for the Postman application.

        Final testing

        To successfully complete the integration of the payment terminal with the cash register, always perform the final testing according to the test protocol here. Fill in the protocol and send it to podpora@comgate.cz.

        The extent of integration and testing depends on the functions supported by your POS system and enabled on the terminal. We also recommend using the highest possible API version.

        Testing procedure:

        1) Check that the terminal and the cash register are connected to the same local network and that the HTTP protocol (not HTTPS) is used for communication (protocol page 61).

        2) Make sure that you have configured the correct IP address and port number in the cash register for communication, which you can see on the terminal (protocol page 32).

        3) Test the PAYMENT SETUP (protocol page 62). 

        1. The merchant creates a new payment on the POS system. He enters the amount, currency and variable symbol.

        2. The cash register initiates the payment request /payment and establishes a connection to the payment terminal.

        3. The cash register then periodically polls the status of the payment by calling request /status.

        4. The customer makes a payment by card (swiping, inserting) at the terminal.

        5. The terminal accepts the payment and returns the payment status Finished to the cash register.

        6. The cash register then requests the terminal to confirm the payment with a request /result.

        7. The payment must be confirmed from the POS system by calling /confirm within 60 seconds.

        8. The terminal displays the receipt of payment and asks to print the receipt (if the function is active).

        It is recommended to call the payment status /status initially after 3 seconds from the transaction creation and then cyclically after about 200–500 milliseconds. If you do not perform a confirmation /confirm within 60 seconds of receiving a positive payment status, the transaction will be automatically cancelled. If the terminal is set to print receipts for the customer as well as the merchant, a new payment cannot be made until the print queue is settled (the terminal asks to print a receipt for the customer after the transaction).


        4) Test the TRANSACTION STATUS verification on the authorization server (protocol page 106).

        1. Checkout calls the /transaction_status request to the original transactionId of the payment.

        2. The system returns the transaction status "OK".

        5) Test the establishment of REFUNDATION (protocol page 71).

        1. The merchant creates a refund on the POS system. He enters the amount, currency and variable symbol.

        2. The cash register initiates the refund/refund request and establishes a connection to the payment terminal.

        3. The cash register then periodically polls the status of the payment by calling request /status.

        4. The customer uses the payment card at the terminal (by swiping, inserting).

        5. The cash register calls the /reverse request with the originalTransactionId of the payment.

        6. The terminal performs the refund and returns the status Finished to the cashier.

        7. Subsequently, the cash register requests the terminal to confirm the refund with the /result request.

        8. The refund must be confirmed from the POS system by calling /confirm within 60 seconds.

        9. The terminal displays the execution of the refund and asks to print the receipt (if the function is active).


        6) Test the AGAINST (reversal) of the payment or refund (protocol page 79).

        This method will refund the last payment to the customer's account. This method can only be used for Payment and Refund operations.

        1. The merchant creates a new payment on the POS system. He enters the amount, currency and variable symbol.

        2. The cash register initiates the payment request /payment and establishes a connection to the payment terminal.

        3. The cash register then periodically polls the status of the payment by calling request /status.

        4. The merchant makes the STORNO payment.

        5. The cashier calls the /reverse request with the originalTransactionId of the payment.

        6. The cashier again performs a periodic poll on the status of the payment by calling the /status request.

        7. The terminal performs the cancellation and returns the payment status Finished to the cashier.

        8. Subsequently, the cash register requests the terminal to confirm the cancellation with the /result request.

        9. From the POS system, the cancellation must be confirmed by calling /confirm within 60 seconds.

        10. The terminal confirms the action and prints the receipt.

        When creating a STORNO, the original transactionId of the payment you want to cancel must be used. If you do not fill in this parameter, the last transaction made will be cancelled. You can only reverse a payment until the closing of the accounts. Cancellation can be performed from both the POS system and the payment terminal. Subsequently, a refund can only be made by means of a refund if the terminal is enabled.


        7) Test the execution of the CLOSURE (protocol page 38). 

        Closing is performed to check the actual status of transactions made over a period of time. After the closing, the transaction totals are reset and the transactions are deleted from the terminal history. Each subsequent transaction will be reflected in a new closing.

        1. The merchant will request a daily closing on the POS system.

        2. The cash register calls the /closing request.

        3. The closing is executed, the cash register returns a successful completion and the transaction history on the terminal is cleared.


        8) Test the PREAUTORIZATION function (protocol page 83).

        1. The merchant creates a new preauthorization on the POS system. He enters the amount, currency and variable symbol.

        2. The cash register initiates a /preauth request and establishes a connection to the payment terminal.

        3. The terminal displays the instruction to use the payment card. During this state, the preauthorization can be canceled by calling /cancel.

        4. The cash register periodically polls the payment status by calling /status.

        5. The customer makes a payment by card (swiping, inserting) at the terminal.

        6. The terminal accepts the payment and returns the payment status Finished to the cash register.

        7. Subsequently, the cash register requests the terminal to confirm the pre-authorization with the request /result.

        8. The payment must be confirmed from the POS system by calling /confirm within 60 seconds.

        9. The terminal confirms the action and offers to print the receipt.

        After the preauthorization is complete, the transaction can no longer be canceled by calling /cancel, but by using the /preauth/cancel parameter. If the preauthorization is not completed, it is automatically canceled after a few days. Incremental /preauth/increment preauthorizations are not supported.

        FAQ

        How do I call up a subtotal from the cash register?

        Only the standard closing can be called from the cash desk. Calling up a subtotal is only possible via the terminal.

        What is the difference between the concepts of refund and reversal?

        Reimbursement is the process by which funds are returned to the payer. Refunds can be triggered for a variety of reasons, such as the return of goods or services or when the payer disagrees with the payment made and requests a refund. A refund is not tied to a specific transaction or card, any amount can be refunded to any card.

        Reversal or cancellation is when the transaction is cancelled and the funds are returned to the payer's account. A reversal is related to a specific transaction and the payer is always refunded the full amount of that transaction. No interaction with the payment card is required for a reversal.

        What is the distinction between the concepts of refund and reversal?

        Reimbursement is the process by which funds are returned to the payer. Refunds can be triggered for a variety of reasons, such as the return of goods or services or when the payer disagrees with the payment made and requests a refund. A refund is not tied to a specific transaction or card, any amount can be refunded to any card.

        Reversal or cancellation is when the transaction is cancelled and the funds are returned to the payer's account. A reversal is related to a specific transaction and the payer is always refunded the full amount of that transaction. No interaction with the payment card is required for a reversal.

        Which currencies can the terminal handle?

        Please note that the supported currencies are CZK and EUR. Please note that the option to pay in EUR is dependent on the settings configured on the Comgate side for the specific terminal.

        Is it possible to switch off printing receipts from the terminal?

        It is possible to disable the printing of receipts on each terminal at the client's request by setting this option on the Comgate side. In line with standard practice, receipts should be printed via the cash register, and clients can request that Comgate cancel the printing of receipts from the terminal.

        What are the requirements of a receipt?

        • Date of payment

        • Receipt number

        • Merchant designation

        • Address of the establishment

        • BUSINESS ID NUMBER

        • Masked number of the card used

        • Amount

        How to handle tipping at the terminal?

        The terminal allows users to enter tips directly on the display. This feature is set by Comgate, however, by default Comgate does not enable tipping on POS terminals. If active tipping is enabled on the terminal, the POS system must be prepared for the fact that the resulting amount of a successful transaction may be higher than the amount with which the transaction was originated from the POS terminal, and must be able to properly account for the difference as a tip. The tip amount is returned in the tipAmount attribute in the /result endpoint.

        If you wish to handle terminal tipping in your integration, please inform us of this fact so that we can enable the ability to set up tipping for clients with your POS system.


        Was this article helpful?

        Changing your password will log you out immediately. Use the new password to log back in.
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.