Error scenarios

Learn how to handle Terminal API errors.

Here we provide information on error handling for our Terminal API, including how to:

Handle common API request errors.
Troubleshoot the error conditions you can receive when making a payment, verifying the status of a transaction, or refunding a payment.

Handling API request errors

Here we explain common Terminal API request errors, and how to resolve them.

No result received

If you do not receive a transaction result, either synchronously or asynchronously, your connection may have dropped after you sent the transaction request. For more information on how to handle these scenarios, refer to our documentation for verifying a transaction status.

Invalid message format

If you make a request with an invalid format, you receive a PaymentResponse.Response that specifies:

Result: Failure
ErrorCondition: MessageFormat
AdditionalResponse: Indicates why the message format is invalid.

The following example is for a response indicating that the SaleToPOIRequest was missing from an API request:

{
  "SaleToPOIResponse":{
    "PaymentResponse":{
      "SaleData":{},
      "Response":{
        "Result":"Failure",
        "ErrorCondition":"MessageFormat",
        "AdditionalResponse":"At toplevel, field SaleToPOIRequest: Missing"
      },
      "POIData":{...}
    },
    "MessageHeader":{...}
  }
}

Invalid JSON format

If your API request does not contain a valid JSON object, you receive a Bad JSON HTTP reply that specifies the line number and a description of the issue:

["Bad JSON:LINE_NUMBER: DESCRIPTION"]

Request not implemented

If we were unable to implement your request, we send a JSON response with a StoredValueResponse.Response object that contains:

ErrorCondition: UnavailableService
AdditionalResponse: Unavailable Device Service
Result: Failure

The following example is for a response indicating that a request was not implemented:

{
  "SaleToPOIResponse":{
    "MessageHeader":{...},
    "StoredValueResponse":{
      "Response":{
        "ErrorCondition":"UnavailableService",
        "AdditionalResponse":"Unavailable Device Service",
        "Result":"Failure"
      }
    }
  }
}

Error conditions

The table below lists error types, and troubleshooting steps specific to making a PaymentRequest, TransactionStatusRequest, or ReversalRequest.

Error condition	PaymentRequest	TransactionStatusRequest	ReversalRequest
MessageFormat	Fix Message and retry	Fix Message and retry	Fix Message and retry
DeviceOut	Retry different device	Wait and retry	Wait and retry
NotAllowed	Wait and retry or Retry different device	Wait and retry	Wait and retry or Retry different device
UnavailableService	Use a supported ProtocolVersion	Use a supported ProtocolVersion	Use a supported ProtocolVersion
InProgress	Not applicable	Wait and retry	Not applicable
Aborted	Optionally retry	Not applicable	Optionally retry
Cancel	Optionally retry	Not applicable	Not applicable
InvalidCard	Try with other card	Not applicable	Not applicable
WrongPIN	Retry	Not applicable	Not applicable
UnreachableHost	Retry	Retry	Retry
Refusal	Try with other card	Not applicable	Manual recovery
NotFound	Manual recovery	Manual recovery	Manual recovery