Touch Screen Terminal Integration
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
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 3.01.
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.
Verification of the signature on the card
If the printing of receipts is not set up on the terminal (so only the cash register prints receipts) and if the terminal does not request another type of verification directly (PIN entry), signature verification on the card may be requested.
In this case, the responsibility for verifying the signature on the card lies with the POS system. In the "result" endpoint, the value SIGNATURE will be returned in the cvmTypeList attribute field. A signature should be requested on the receipt from the POS system for such a case, the operator should be prompted by the POS system to check the signature against the signature on the card. If the signature on the receipt does not match the signature on the card, the payment should be subsequently reversed at the POS terminal.
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.
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.
3) Test the PAYMENT SETUP
The merchant creates a new payment on the POS system. He enters the amount, currency and variable symbol.
The cash register initiates the payment request /payment and establishes a connection to the payment terminal.
The cash register then periodically polls the status of the payment by calling request /status.
The customer makes a payment by card (swiping, inserting) at the terminal.
The terminal accepts the payment and returns the payment status Finished to the cash register.
Then the cash register reads the payment setup result from /result
The payment must be confirmed from the POS system by calling /confirm within 60 seconds.
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.
Cash register calls the /transaction_status request to the original transactionId of the payment.
The system returns status "OK".
The cash register calls the /result request on the original transactionId of the payment, checks that the transactionType parameter in the response has the TRANSACTION_STATUS value and verifies the transaction status according to the responseCode parameter.
5) Test the establishment of REFUNDATION.
The merchant creates a refund on the POS system. He enters the amount, currency and variable symbol.
The cash register initiates the refund/refund request and establishes a connection to the payment terminal.
The cash register then periodically polls the status of the refundation by calling request /status.
The customer uses the payment card at the terminal (by swiping, inserting).
The terminal performs the refund and returns the status Finished to the cashier.
Then the cash register reads the refundation result from /result.
The refund must be confirmed from the POS system by calling /confirm within 60 seconds.
The terminal displays the execution of the refund and asks to print the receipt (if the function is active).
6) Test the reversal of the payment or refund.
This method will refund the last payment to the customer's account. This method can only be used for Payment and Refund operations.
The merchant makes the STORNO payment.
The cashier calls the /reverse request with the originalTransactionId of the payment.
The cashier again performs a periodic poll on the status of the reversal by calling the /status request.
The terminal performs the cancellation and returns the reversal status Finished to the cashier.
Then the cash register reads the reversal result from /result.
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 and only through cashier system. Subsequently, a refund can only be made by means of a refund if the terminal is enabled.
7) Test the execution of the CLOSURE.
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.
The merchant will request a daily closing on the POS system.
The cash register calls the /closing request.
The closing is executed, the cash register returns a successful completion and the transaction history on the terminal is cleared.
8) Test the PREAUTHORIZATION function.
The merchant creates a new preauthorization on the POS system. He enters the amount, currency and variable symbol.
The cash register initiates a /preauth request and establishes a connection to the payment terminal.
The terminal displays the instruction to use the payment card. During this state, the preauthorization can be canceled by calling /cancel.
The cash register periodically polls the preauthorization status by calling /status.
The customer makes a preauthorization by card (swiping, inserting) at the terminal.
The terminal accepts the preauthorization and returns the preautorization status Finished to the cash register.
Then the cash register reads the preauthorization result from /result.
The preauthorization must be confirmed from the POS system by calling /confirm within 60 seconds.
The terminal confirms the action and offers to print the receipt (if funkcional).
After the preauthorization is complete, the transaction can no longer be canceled by calling /cancel, but by calling 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.