This is an old revision of the document!
There are variety of reasons why a transaction or api call may take longer than expected, from processor lag to systems issues or network outages. While we make every effort to minimize the total time an api call takes, there will be situations where a time out will be exceeded. In the typical configuration there are several timeouts in play:
Item 1 varies depending on the backend processor, available failover options and the type of request (ie authorization vs batch close). Max timeouts range from 45s to 10min.
The developer typically has control over items 2 and 3. Developers often try to set #2 as low as possible to cover the majority of transactions and maintain a consistent user experience. Setting #2 too high can lead to end users giving up and either abandoning the sale or making a duplicate attempt. Setting #2 too low and transactions that would have been approved are lost.
In scenarios where an end customer is connecting to the developer's server, you must also take into account the web browser's timeout. ThS last item is dependent on the software being used by the customer and typically ranges from 1 to 5 minutes.
When running transactions the biggest problem merchants encountered is multiple authorizations hitting the customer's account. Take the scenario where the developer has their timeout set to 15 seconds but the processor is slow and returns an approval after 18 seconds. These funds are now held on the customers account and the approved transaction will show up in the merchant's batch. The problem is that the developer's software gave up at 15 seconds and reported the transaction as an error. Assuming this error was also reported to the clerk or customer, chances are that the transaction is going to be retried. If the retry was also approved, there is now a duplicate transaction in the batch and the customer has double the funds held in their account.
The easiest solution is to pass in to the gateway the requested maximum time you are willing to wait for a reply. This value should be equal to or less than items #2 (HTTP timeout), #3 (application timeout) and #4 (customer browser timeout) above. The gateway starts a timer as soon as the request is received. There are three possible outcomes:
The timeout value can be configured three ways, listed in order of precedence: