Search

Are you looking for test card numbers?

Would you like to contact support?

Error scenarios

Learn how to handle Terminal API errors.

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

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

See also