Knowledge Base Best Practices

Response Failure

Timeouts, response failures, and communication failures occur in any environment where two or more systems are communicating with each other. There are many reasons for these failures, most benign, that can leave one system or the other with limited information about the results of the request in question. It is important to understand how these failures can occur and to account for them within your system to avoid discrepancies between the point of sale system and the payment gateway or processor. Below in this guide we will detail some of the sources of these failures to help you better understand why they can occur, as well as best practices you want to employ to ensure you are always getting as much detail back from the gateway as possible. 


There are a number of different timeout settings that can impact communications. These are in place to prevent a service from being held up indefinitely. Some of these timeouts are built into TSYS systems, some are more universal. 
  • Host Timeout Returned from Genius: This occurs when the connection between the Genius device and the TSYS host has timed out. The important thing to note here is that the transaction in question will not have completed on the Genius device as the POS to Genius connection is still valid and active, but the connection to the host is no longer available.
  • Genius Device Timeout (Genius Screen Timeout): The Genius software has a built in timeout that will return the device to its idle screen and configuration if a set amount of time has passed. This timeout will be communicated back to the POS as the connection between the two has not been terminated. This timeout defaults to 240 seconds and is configurable on a per terminal basis. This setting is set this high because customers may wish to spend a long time on any given screen before they are able to proceed with their transaction, and failing to wait here will force the POS to initiate another request to the Genius device. 
  • Standard Environment Timeouts: Most frameworks have built in timeout settings for open connections to ensure that an operation does not lock a system up if a set amount of time has passed before getting a response. As these are different on different frameworks or systems, it is important to be aware of the environment you are using when creating your point of sale, and any built in or default timeout settings that come along with it.
  • No Response Timeout: Some POS developers choose to institute specific timeouts when no response is returned after a set timeframe. As this one is specifically implemented by the POS developer it is critical to take steps to follow up any timeout of this nature with further investigation into the status of the initial request.
In all cases of timeouts as with other response failures (such as a "FAILED/Communication Error" response), it is critical to investigate further to determine if the requested operation was in fact completed. There are a number of steps that can be taken to ensure the POS has all available information, and to avoid potential issues such as duplicate transactions or uncompleted orders and sales. 
  • Always Check on the Request: The most important thing to do in these scenarios is to ensure that the POS is following up with the gateway in the event of a timeout. Never make an assumption that a lack of response indicates that the gateway did not process the request. While not the only option, below is a detailed description of how TSYS recommends this type of failure be handled. 
    • When creating a request to initiate a transaction pass in a Transaction ID GUID
      • In the Genius or TransportWEB API this value can be submitted in the CreateTransaction request and is submitted in the transactionId field
      • In the MerchantWARE API this value can be submitted in the Sale (or like) request and is submitted in the merchantTransactionId field
    • In the event that a transaction times out or the POS is left without knowledge of the end results of a request retry the following steps over a 60 second period of time or in a retry loop up to 10 times with a small delay between attempts. 
      • Call out to the reporting API using the Transaction ID GUID that was submitted in the initial step.
      • Submit the Name, SiteId, Key, and TransactionId or MerchantTransactionId
      • If the reporting call returns results, this indicates the transaction did complete and the results of this reporting request should be sufficient to populate any invoice or receipt data. With the relevant transaction data in hand, the incomplete invoice or order can now be completed and the POS should proceed as if this was the response it was initially waiting for. 
      • If the reporting call returns no response repeat again until a sufficient amount of time or retry attempts has been met, we recommend 60 seconds or 10 times with a small delay between attempts. 
      • If no results are returned after the above steps have been met then proceed as if the transaction has not completed. 
  • Pay Attention to the Timeout Type: Some of the listed timeouts above such as the screen timeout will respond with a specific timeout message indicating it was a screen timeout. This specific type of response will allow you to clearly make a decision as to the status of the transaction because it is only returned in the scenario where the Genius device was waiting and did not receive input from a user for too long. Make yourself aware of the possible timeouts that can be returned from the services you are using. 
  • Make Sure Timeouts are Coordinated: Not all timeouts are controlled but be sure you are aware of the ones that are. If the POS has a timeout setting built in that will sever a transaction in process, make sure you clearly explain that to the TSYS team and figure out how to coordinate these settings. Genius device timeouts can be configured, so it is important that the POS timeouts are not shorter than Genius timeouts. In the event the POS timeout needs to be short, inform TSYS so the device or devices can be configured to timeout first. If the POS timeouts are set shorter than the TSYS timeouts there is a higher risk of these types of failures. 

Failures due to Gateway Settings

Our gateway can be configured to block specific types of transactions. This can be set up intentionally, but if an account is misconfigured or specific settings are not requested upon setup it is possible that transaction failures can result. Proper handling of these failures can prevent missing charges or confusing user interactions. 
  • Duplicate Validation: The TSYS gateway can enable duplicate transaction validation. This validation compares any transaction processed on the same card, for the same amount, within the same batch or day. If this validation is on, any transaction that qualifies under these conditions will trigger a duplicate decline failure. This failure can indicate a few things, but the most common is that the initial transaction response was not received back by the POS and another transaction was attempted. 
  • Refund by Reference Only: The TSYS gateway can be configured to only allow refunds when a reference number is supplied. This is to prevent refunds without a previous transaction on a card. With this setting on, it is possible that a refund will be attempted and will fail. In this case, there would not be missing transaction information, but it would be important to properly reflect the failure to the user so they would know what to ask for when contacting point of sale support. 
In all cases of settings related failures as with other response failures, it is critical to investigate further to determine the source of the failure. There are two scenarios with these types of failures that have different avenues of investigation to resolve. 
  • Settings Unintentionally Enabled: In the event that duplicate declines or rejected refunds are occurring when your customers should not be configured for them, these types of failures should result in a request to have the customer reach out to our support staff and verify the settings of their account. This should only be the case when the POS explicitly allows duplicates or refunds without reference values. 
  • Valid Failures: Both cases of duplicate and refund by reference only errors can be handled differently
    • Duplicates should be clearly indicated to the user in the event this is not a programmatic issue but a user issue. It is also possible that a duplicate is the result of some of the failures discussed above in the timeout section of this article, being followed up by a subsequent transaction without proper validation. In this case, you will want to follow the steps above to use reporting calls to verify any subsequent failed transaction id and populate the transaction results with the identified information.
    • Refunds blocked due to no reference should simply be indicated to the user in a manner that clarifies that refunds without a reference number are not allowed for their account. 

Request Errors

There are a number of failures that will be returned immediately that are not a result of gateway settings but rather due to issues with the request itself. Properly reacting to these failures is important to prevent confusion for users and generate unnecessary support requests. 
  • 403 Bad Request: This failure message indicates that the request being sent to Genius or to the TSYS Gateway is invalid or improperly formatted. 
  • 405 Method Not Allowed: This failure message indicates that the request being sent to Genius or to the TSYS Gateway is for a function that is not allowed by that device or service.
  • Invalid Request, Terminal Busy: This failure message is an indication from a Genius device that there is already a request in process and that it cannot be interrupted. 
In all cases of request related failures as with other failures, it is critical to investigate further to determine the source of the error. The cases listed in this section are failures that immediately indicate that no processing has occurred on the specific request sent. The handling of them can be a little different depending on the scenario but most of these errors should be handled programmatically and if they occur will likely require the development team for the POS to investigate. 
  • Bad Request: This error is specifically indicating that the format of a request is invalid. In the event of this type of failure the request itself should be verified with the help of the TSYS Certification Engineering team. To help facilitate this it is always recommended that the POS properly log requests and responses for review. Having a record of the specific request exactly as it was sent to TSYS' services will go a long way to resolving any issue of this nature. 
  • Method Not Allowed: This indicates that the function being attempted is not supported by the configuration or device being contacted. This most commonly occurs in the event of a request to a Genius device for a type of transaction that is not supported by that specific device. In this case it is possible the issue lies with the POS requesting a feature that is not supported by their certification, or that the configuration of the device itself is to blame. In the event of this failure, please verify the request is valid and if so reach out to TSYS support to ensure the correct settings are configured for the device in question. 
  • Terminal Busy: This failure is fairly simple, and indicates that a device that is being contacted is currently processing a previous request and cannot be contacted. In the event of this, the most common practice is to issue a status request to the device and act upon the results. If the status shows the device is on a screen or process that the POS does not believe it should be, a cancel command can be issued to reset the device to its default state. If this occurs during a processing transaction then the steps above for verifying if a transaction completed should be followed if relevant.