This is an old revision of the document!

API Timeout Handling


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:

  1. time the gateway will wait for a response from the processing networks
  2. time the developers HTTP client will wait for a response from the gateway
  3. max execution time of the developers script
  4. time the customer web browser will wait for a response from the developer's server

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.

What Can Go Wrong

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.


Timeout Auto-Reversal

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:

  1. Transaction takes less than the timeout requested and everything proceeds normally
  2. The timer is checked just before the request is sent out to the platform for authorization. If the timer exceeds the requested timeout, the transaction will be immediately returned as an error. The authorization does not get sent to the platform and no funds are held.
  3. The timer is checked again right before the response is sent back to the developer. If the timeout was exceeded, the system automatically performs a void::release. Any funds that were held should be automatically returned to the cardholder immediately (depending on issuer participation) and the transaction will be marked as a void. This will prevent the transaction from being settled.

The timeout value can be configured three ways, listed in order of precedence:

  1. API Parameter: In the transaction api, the UMtimeout field can be set to the number of seconds desired. In soap UMtimeout can be passed into the runTransactionAPI method. For runTransaction, UMtimeout can be specified in the CustomFields array.
  2. HTTP Header: The transaction and soap api support the HTTP Header “ApiTimeout”.
  3. Source key setting: The merchant can log into their console and edit the settings of the source key. The API Timeout field contains the default timeout in seconds for all calls to this source key
developer/timeouts.1422304262.txt.gz · Last modified: 2015/01/26 12:31 by tem

Page Tools