Communication failures can occur at various points in the transaction process and cause the transaction to timeout. This section outlines the amount of time that your interface should allow for transaction responses, the communication error codes your interface should receive, and guidelines for handling communication failures.
Interfaces will need to implement a Global Timer to monitor the time between a request and a response. The Global Timer should be configurable because the values may need to be changed later.
- For transactions with card entry using a UTG or Commerce Engine controlled PIN pad, initially set the Global Timer to 120 seconds. The device-timer setting in UTG TuneUp must have a lower value than your chosen Global Timer duration.
- For transactions with card entry other than a UTG or Commerce Engine PIN pad, initially set the Global Timer to 65 seconds.
When a transaction response exceeds the time limit configured in the Global Timer, the interface will need to treat the timeout as a communication error.
The following is a list of the communication error codes:
- 1001
- 2011
- 4003
- 9012
- 9018
- 9020
- 9023
- 9033
- 9489
- 9901
- 9902
- 9951
- 9957
- 9960
- 9961
- 9962
- 9964
- 9978
If one of these error codes is received, follow the Transaction Flow Diagram to check the status of the invoice.
When a communication failure occurs, it is important to determine the status of the transaction in progress to determine the point at which the error occurred. For example, a communication failure does not mean that the card issuer did not receive or approve the transaction; if the failure occurred before the card issuer responded, the merchant could have a valid approval.
To determine the status of the transaction, an Invoice Information request must be sent by the interface. The Invoice Information request will need to include the invoice number in the Invoice header parameter. Using the information in the response to the Invoice Information request, the interface will either void, log, or continue the transaction. If the Invoice Information request is unsuccessful, the interface can resend the request once before logging the transaction for an auditor’s review.
When a communication failure occurs, the interface should complete the following steps:
- Wait for 1 to 3 seconds (in the production environment) or 3 to 5 seconds (in the test environment).
- Send an Invoice Information request to check the invoice status.
- If an "Invoice Not Found" error is returned, then the original transaction which timed out can be sent again (using the same invoice number).
- OR if the invoice was found, check the value in the
transaction.responseCodefield (if present). If the status still cannot be determined from the response, log the transaction for an auditor’s review. - OR if the Invoice Information request fails, one retry can be attempted before logging the transaction for review.
If a transaction fails, do not send a Void request. Your interface should log the error condition for the merchant’s review.
When a communication failure occurs while loading a balance on a gift card, send a Balance request to check the balance.
- If the Global Timer expires before receiving a response or if the interface receives a communication error, log the transaction for an auditor’s review.
- If you receive the Balance response and the correct balance (prior balance plus requested load amount) is not reflected, log the transaction for an auditor’s review and adjustment.
Never send a Void request for communication errors related to gift cards. Your interface should log the error condition for the merchant’s review.
When a communication failure occurs while redeeming a gift card (authorization or sale), the card's balance will not be returned in a subsequent Invoice Information request. The interface can send a Balance request to check the balance if this information is needed.
When unresolved exceptions, such as timeouts and communication errors, occur during the processing flow, a transaction should be logged for an auditor’s review. Logging the transaction allows the merchant’s auditor to review the batch of transactions and fix potential issues, such as double charges.