Terminal Error Handling

Guidelines for managing Zift Terminal Cloud transactions when an Approval, Declined, or Cancellation response is not received.

Due to potential factors like local Wi-Fi instability, network latency, or service disruptions, you might occasionally receive a response that isn't a standard approval, decline, or cancellation.

Error Handling and Transaction Reconciliation

For most terminal transactions you will receive an Approved, Declined or Cancelled response message from our servers. However, due to unanticipated circumstances such as network connectivity, you may occasionally receive an error response. In such cases, and to prevent duplicate transactions from being processed, it’s important to confirm whether or not we received the transaction request and determine its status.

To facilitate transaction tracking—particularly in the event of a network error—your system should include external identifying fields in each API sale request. These identifiers enable you to query our servers, prevent duplicates, and reconcile transactions reliably within your system. 

The primary handle for a transaction is the transactionId, a unique value generated by Zift for each transaction. This ID can be used to retrieve transaction status and details. However, if an error occurs before the transactionId is returned, you will not be able to query using this value.

To address this, we strongly recommend including a unique external identifier from your system in the transactionCode field with each sale request. If you receive an error response you can then make a find request using your original transactionCode to check for the transaction in our system and confirm its status. 

The section below outlines best practices for using the transactionCode parameter to handle these scenarios effectively.

Transaction Lookup Using  transactionCode

When your software includes a unique transactionCode with each terminal sale request, you can use this value to search for the transaction in the Zift system if an error or response exception is received.

Here's an example of a transaction find request using the transactionCode to lookup the transaction. See the full documentation for this request here. 

{
  "method": "POST",
  "url": "https://sandbox-portal.zift.io/gates/xurl",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "body": {
    "requestType": "find",
    "userName": "{api-user}",
    "password": "{api-pass}",
    "accountId": "2222001",
    "transactionCode": "8a3T54333-12jat35t"
  }
}

What To Do If a Transaction is Found

You can verify the status in the responseCode and/or responseMessage fields and treat it as if the response had been returned on the original request. To prevent duplicate transactions, if the response message is an Approval, you should treat the transaction as such and not run a subsequent transaction. We recommend implementing this business logic before presenting any results back to the user/customer.

What To Do If a Transaction is Not Found

Your software can treat the transaction request as incomplete. A new terminal sale request can be attempted to complete the transaction with the cardholder.

References

- Zift API Docs: https://api.zift.io/
- Cloud Sale Reference: https://api.zift.io/#cloudSale
- Find Transaction Reference: https://api.zift.io/#find
- HTTP Codes: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status