Skip to main content

GSA API

Comgate currently offers 2 ways to use the GSA protocol – primarily it can be used for communication between the cash register and terminal on a local network, or optionally via a cloud solution (GSA+).

Local Network Connection (GSA)​

Communication between the cash register and terminal occurs via a simple REST API by sending HTTP requests in JSON format to the IP address and port of the terminal on the local network. The GSA protocol documentation for cash register integration is available here.

Implementation and Best Practices​

Both devices (terminal and cash register) must be connected to the same local network. HTTP protocol must be used for communication (not HTTPS). The following operations are supported:

  • Get terminal status
  • Payment
  • Refund (only for selected clients)
  • Pre-authorization and its completion or cancellation (without incremental/decremental, only for selected clients)
  • MOTO payments (only for selected clients for limited purposes)
  • Transaction reversal
  • Get transaction status
  • Cancel payment waiting for card or PIN
  • Settlement

A minimal implementation should include at least Payment, Reversal, and Settlement.

IP Address, Port, and Password (secureString)​

The cash register communicates with the terminal using its IP address. This address must be known in the cash register system. It is also recommended to ensure that the terminal's IP address does not change on the network (for example, do not use DHCP and set a static IP address for the terminal) so that you do not need to constantly change the terminal's IP address in the cash register system. The value of the secureString attribute is 27924505. The password is valid not only for testing but also for the production environment. It is possible that the password will change in the future, so it is advisable to make it configurable and pre-filled in the cash register system. The same applies to the port, which is currently set to the default value of 33350.

Demo cash register and Postman Collection​

To test the GSA protocol, a Demo cash register is available that simulates cash register behavior. Open the Demo cash register in Firefox browser (connection with the terminal does not work in Chrome). The protocol of the demo cash register URL must be HTTP, not HTTPS. To log in, enter the IP and port number of the terminal and then the password mentioned above. For successful connection, both the terminal and computer must be connected to the same local network. In the Demo cash register, you can select GSA protocol v1 or v2 from the top menu and view the complete REQUEST – RESPONSE communication between the cash register and terminal. You can also use the prepared Postman collection.

GSA API Version​

The terminal through the Switchio Pay payment application offers several versions of the GSA API protocol. You can choose the version; we recommend using the highest one. At the same time, keep in mind that older versions of the Switchio Pay payment application do not support the latest GSA API versions (see the APPLICATION VERSION HISTORY table in the documentation). To determine the highest available GSA API version on a specific terminal, you can use, for example, calling the "info" endpoint. You need to iterate using a GET request to the endpoint address from the highest version to the lowest (according to documentation):

  1. GET http://{terminal_ip_address}:{port}/api/switchio/pay/v8/info
  2. GET http://{terminal_ip_address}:{port}/api/switchio/pay/v7/info
  3. GET http://{terminal_ip_address}:{port}/api/switchio/pay/v6/info
  4. GET http://{terminal_ip_address}:{port}/api/switchio/pay/v5/info
  5. GET http://{terminal_ip_address}:{port}/api/switchio/pay/v4/info
  6. GET http://{terminal_ip_address}:{port}/api/switchio/pay/v2/info
  7. GET http://{terminal_ip_address}:{port}/paya/info

If the terminal supports the protocol version, it will return a JSON object with HTTP 200 OK header containing the name and version of the protocol used and the terminal ID. Otherwise, the terminal will return the text "Endpoint not supported." and HTTP 404 Not Found header.

Note: We regularly update terminals; all should support at least version v2, or it is always possible to update the Switchio Pay payment application on the terminal to a higher version to achieve the required higher version of the GSA API protocol.

transactionId Attribute​

This attribute, which is always generated by the cash register, serves as the unique ID for the lifecycle of a single operation. For example, in the case of a payment, you must use the same transactionId for all requests to /payment, /status, /result, and /confirm. However, if this payment is subsequently reversed by the cash register, it is already another operation and a new transactionId must be generated for it. The value of the transactionId attribute must be unique for each operation (at least within one settlement). We recommend generating a random UUID composed only of "harmless" characters a-z, A-Z, 0-9, or the "-" character (no diacritics or wildcards, etc.), but the transactionId format is not strictly defined.

Checking the Status of an Ongoing Transaction​

We recommend calling the transaction status (endpoint /status) initially after 3 seconds from transaction creation and then cyclically after approximately 200–500 milliseconds. Once the Finished status is returned, you can retrieve the transaction result from the /result endpoint.

Transaction Confirmation​

Every transaction successfully authorized on the terminal requires confirmation from the cash register that it has received the transaction result (endpoint /confirm). While waiting for this request, a 60-second countdown runs on the terminal. If the transaction is not confirmed by the cash register using /confirm within this time from successful authorization, the transaction will be automatically reversed. At the same time, always verify that the isConfirmed attribute is returned with the value true in the response to your /confirm request. If false is returned, the transaction was not confirmed and has probably already been reversed.

Transaction Reversal​

When initiating a reversal (endpoint /reverse), specify in the originalTransactionId attribute the original transactionId of the payment you want to reverse. If you do not fill in this attribute, the last executed transaction will be reversed. A transaction can only be reversed before the accounting settlement is completed and only from the cash register system. For an older payment, it is subsequently possible to return funds only through refund, if enabled on the terminal or in the Client Portal.

Pre-authorization​

After a pre-authorization has been completed, it is no longer possible to cancel the transaction by calling /reverse, but by calling /preauth/cancel. If the pre-authorization is not completed using /preauth/complete, it will automatically cancel after several days. Incremental pre-authorization (/preauth/increment – increase of pre-authorization amount) or decremental pre-authorization (/preauth/decrement – decrease of pre-authorization amount) are not supported.

Signature Verification on Card​

If receipt printing is not set on the terminal (so only the cash register prints receipts) and 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 rests with the cash register and its operator. The value SIGNATURE will be returned in the cvmTypeList attribute in the /result endpoint. A signature should be requested on the receipt from the cash register system in such a case, and the operator should be prompted by the cash register 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 must then be reversed on the terminal from the cash register.

Verifying the Final Transaction Status​

Verifying the transaction status using the /transaction_status endpoint can mainly help in cases where network communication between the terminal and cash register breaks down at the moment when the transaction has already been authorized, but it was not possible to send the /confirm request from the cash register, or the response to this request was not received. Two situations may occur:

  1. the /confirm request reached the terminal and the transaction is successfully closed, but the response with "isConfirmed: true" did not reach back to the cash register,
  2. the /confirm request did not reach the terminal and the terminal automatically reversed the payment after 60 seconds.

Subsequently (or later, when the network connection to the terminal is active again), you can request the transaction status from the authorization host using the terminal. You need to account for a time delay according to point b), then the transaction status can be considered final.

The transaction status can be obtained using the following procedure. In the first step, you need to request the terminal to determine the transaction status using the /transaction_status endpoint. The terminal will return a JSON response in the form:

{
  "transactionId": "xxxx-transaction-id-xxxx",
  "isStarted": true,
  "status": "OK"
}

If the terminal returns different data for isStarted and status, the transaction status request was not successful for some reason (for example, isStarted: false, status: Server busy indicates an incomplete operation, typically for example if the terminal is displaying a receipt printing prompt for the customer).

Next, you need to call the /result endpoint, which will return transaction data. Here you need to check that the transactionType parameter has the value TRANSACTION_STATUS!

If the transaction was successfully completed, then responseCode will have the value OK and responseMessage will have the text confirmed. However, if the transaction was reversed, responseCode will have the value TransactionReversed and responseMessage will have the text Transaction reversed!.

Note: TransactionType = TRANSACTION_STATUS is returned only on the first call to the /result endpoint following a call to the /transaction_status endpoint and only in it is the correct transaction status. The transaction status can only be checked until the settlement on the terminal is completed; after that (or if the transaction is not found), the responseCode is returned with the value TransactionCardholderAuthorizationDataNotFound and the transaction status can no longer be verified in such a case.

Cloud Connection (GSA+)​

The GSA+ protocol allows you to control terminals from a cash register or other business system over the internet in essentially the same way as with the original GSA protocol over a local network. This solution can be used especially in situations where you already have GSA protocol communication implemented in your cash register over a local network and can easily switch to terminal communication over the internet with relatively minor modifications. However, if you are starting a new integration of cash register and terminal connection, please use REST API – CloudPOS instead of the GSA+ solution.

Security​

To ensure the integrity and confidentiality of transmitted data, all communication takes place exclusively over the encrypted HTTPS protocol. Each request must contain an authorization header. Access to all API methods must also be allowed only from pre-configured (ranges of) IP addresses.

Implementation​

For implementation, you can proceed from the information above and the GSA protocol documentation (for local network communication), but for using the internet GSA+, you need to make several of the following changes compared to the documentation:

  1. You need to modify the beginning of the called endpoint addresses so that instead of the original addresses http://{terminal_ip}:{port}/paya/, or http://{terminal_ip}:{port}/api/switchio/pay/v{x}/ the new address starts with https://payments.comgate.cz/ecr/api/v1.0/
  2. At the same time, each request must contain an authorization HTTP header in the form Authorization: Basic [base64_encode(merchant:secret)]. The 'merchant' parameter is the login to the specific terminal and 'secret' is the password. The client will find these details in the Client Portal in the Integration section – Shops Settings – Terminals tab. Here you can also set IP address ranges allowed to access the API for each terminal (IP address or addresses from which the cash register can communicate with the given terminal via API). Any incoming request from an IP address outside the configured range will be rejected.
  3. It is no longer necessary to send the 'secureString' attribute in requests (but it can remain in the requests).
  4. For correct terminal configuration, Comgate needs to know from the client (or from the cash register system supplier) whether the cash register system will communicate with the terminal locally over the local network (GSA) or remotely over the internet (GSA+) – especially in cases where the cash register system used by the client supports both communication methods.
Information

Warning: The GSA+ protocol now does not support any endpoints with callbacks or the /cancel endpoint for canceling a transaction waiting for a card or user input.

The API response can be, besides HTTP 200 OK, also the following:

  • HTTP 401 Unauthorized (in case of incorrect merchant/secret data),
  • HTTP 403 Forbidden (in case of a request from an unauthorized IP address)
  • HTTP 400 Bad Request (in case of incorrectly sent parameters)
  • HTTP 500 Internal Server Error in case of another error

Frequently Asked Questions​

How do I trigger a preliminary settlement (subtotal / intermediate settlement) from the cash register?​

From the cash register, only a standard settlement can be triggered. Intermediate settlement can only be triggered via the terminal.

What is the difference between intermediate settlement and settlement?​

Settlement is performed to verify the actual status of transactions performed during a specific time period. After settlement is completed, the transaction totals on the terminal are zeroed and transactions are deleted from history. Each subsequent transaction will be reflected in the new settlement. Intermediate settlement is used to continuously verify transaction totals. Intermediate settlement sums up the transactions that occurred on the terminal in the time period since the last settlement. Any number of intermediate settlements can be performed between two settlements. Transaction statuses and transaction records are not deleted by performing an intermediate settlement; therefore, intermediate settlement does not affect the next settlement.

What is the difference between refund and reversal?​

A refund is a process in which funds are returned to the payer. A refund can be initiated for various reasons, such as return of goods or services, or in the event that the payer disagrees with the transaction and requests a return. A refund is not tied to a specific transaction or card; any amount can be returned to any card. Reversal is a situation where a transaction is canceled and the funds are returned to the payer's account. Reversal applies to a specific transaction, and the payer is always returned the full amount of that transaction. No interaction with the payment card is required for reversal.

What currencies does the terminal support?​

Currently supported currencies are EUR (978) and CZK (203). The currency code (currencyCode) is based on ISO-4217; a complete list can be found here. However, the ability to pay in EUR depends on the configuration by Comgate for the specific terminal. For clients in Slovakia, it is the other way around; they typically have EUR available, while CZK is configured individually.

Is it possible to modify receipt printing settings from the terminal?​

Yes, receipt printing can be disabled or modified at the client's request by setting on the Comgate side for each terminal – you can print receipts only for the customer, only for the merchant, for both merchant and customer, or not print any receipts. From common practice, it is advisable to print documents through the cash register, and clients can request Comgate to stop receipt printing from the terminal. If receipt printing is set on the terminal for the customer, it will not be possible to perform a new operation with the terminal until the print queue is cleared (the terminal asks for a receipt to be printed for the customer after each transaction).

What are the required elements of a receipt?​

  • Date of payment
  • Receipt number
  • Merchant designation
  • Business address
  • ID/VAT number
  • Masked card number used
  • Amount

How do I handle tips on the terminal?​

The terminal allows you to enter tips directly on the display, or you can define tips directly from the cash register when initiating a payment in the "tipAmount" attribute. Enabling the tip feature is set by Comgate; however, by default, Comgate does not enable tips on terminals with cash register systems. If active tipping is enabled on the terminal, the cash register must be prepared for the fact that the final amount of a successful transaction may be higher than the amount the transaction was initiated with from the cash register (if the transaction was initiated from the cash register without a set tip), and it must be able to correctly account for this difference as a tip. The tip amount is returned in the "tipAmount" attribute in the /result endpoint. If you want to implement tipping on the terminal in your integration, please inform us of this so we can enable clients with your cash register system to set tips.