QuickStream REST API transaction error handling

QuickStream REST API transaction error handling

This API responds with Errors when a request is not processed successfully. When a transaction request is successfully processed this API returns a Transaction Response Code. Error information is provided in the summaryCode and a description of the error in the responseCode and responseDescription fields in the Transaction Response Model.

Use the table below to determine the appropriate system behaviour for each summaryCode.

Summary Code Description Recommended System Action
0 Transaction Approved Transaction is successful. No further action required.
1 Transaction Declined Transaction has been declined by the financial institution. See Transaction Response Code for common response codes.
In many cases, the problem can be addressed by either:
  • Carefully checking the card details and correcting any mistakes before creating a new transaction; or
  • Create a new transaction with an alternative card.
The reason for the decline may not always be obvious from the detailed response code. For example, Do Not Honour (05) may require offline follow up with the financial institution that issued the card.
2 Transaction Erred Transaction is of an unknown status. See Summary code 2 below.
3 Transaction Rejected Transaction request has been rejected by the API, often due to invalid system configuration. This is similar to the Transaction Declined (summaryCode of 1) in terms of error handling. Refer to the detailed response code and either:
  • Correct the transaction details if required and retry under as a new transaction; or
  • Handle offline through QuickStream Technical Support if unable to be resolved.

Summary code 2

A transaction may be received and processed by a financial institution but a system or network error may occur such that a response is not returned. Given that QuickStream does not know the status but it may have been successfully approved and the card debited, we must return the "Transaction Erred" status summaryCode = 2. An outage with the financial institution may last for some time and therefore your exception handling process must handle this rare but possible situation.

The recommended action is as follows:

  1. Request GET /transactions/{receiptNumber}. The API returns the most recent response and may be different to the response originally received.
  2. If summaryCode is 0, 1 or 3 in the response, then the transaction may be handled as if the response was received on the first attempt.
  3. If summaryCode is 2 after the first attempt, the transaction should be marked as held within your system. As the transaction may have been processed, it is not recommended that the transaction be retried by creating a new transaction. Your system should indicate to the end user that the status of the transaction is unknown and that they should contact your customer service personnel during applicable hours or provide a receipt number and contact the end user if the transaction is subsequently found to fail.
  4. If summaryCode is 2 after initial attempts, request GET /transactions/{receiptNumber} after settlement cutoff to try to automatically determine the status. QuickStream has processes in place to try to update these transactions with the final status and will endeavour to have statuses updated by settlement cutoff. This means that in many cases, the status will be available automatically if re-queries are attempted after this time.
  5. If summaryCode is 2 after settlement cutoff, we recommend re-querying at the same time on the following day as it may take up to 48 hours for the final status of transactions to be updated under some circumstances.
  6. For transactions that remain unresolved, your customer service would then try to resolve the situation by first using QuickStream Portal to query the transaction status. If this does not resolve the issue, the exception details should be communicated to QuickStream Technical Support for resolution. This would require details on the original transaction (particularly the receiptNumber), responses and exception handling actions attempted thus far.

Some customers, with a need for minimal customer impact of outages, have implemented additional business logic that tries to protect the end customer from such issues. As this may be useful in your implementation, a typical process is as follows:

  • If an API call returns a summaryCode of 0, 1 or 3 then your system handles this as per normal.
  • If an API call returns a summaryCode of 2 then your system handles this by returning a receipt number to the end customer and then tries to determine the transaction result in the background. This ensures that the end customer is not impacted by an outage period. If the transaction subsequently fails, this will require handling through an internal customer care process and may require contact with the end customer.