Error Handling and Recovery

The following sections describe some failure scenarios together with recommended recovery actions to be performed by the ECR and/or cashier.

[!WARNING]
This is not an exhaustive overview of failure scenarios or recovery actions. The ECR implementer must implement the necessary error handling based on the merchant's use cases and requirements.

The ECR should be able to handle the below ErrorCondition codes which can be received in response to request messages.

Communication breakdown

Scenario

Communication between the ECR and the terminal breaks down in the middle of a transaction, for example after sending a transaction request but before receiving the response.

Possible reasons include:

• ECR power failure
• Terminal power failure
• Communication failure

Recommended action

Reconnect if necessary and use TransactionStatus to determine the result of the transaction before retrying the transaction.

Terminal busy

Scenario

The ECR sends a new service request while the terminal is busy with another operation. The terminal responds with an error indicating its busy state.

{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Payment",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "AT12345",
      "ProtocolVersion": "3.1",
      "SaleID": "ECR123",
      "ServiceID": "3"
    },
    "PaymentResponse": {
      "Response": {
        "ErrorCondition": "Busy",
        "Result": "Failure"
      }
    }
  }
}

Recommended action

Retry the request after a delay.

Malformed input

Scenario

The ECR sends a message that is malformed and cannot be parsed or processed. The terminal responds with an event notification.

{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageCategory": "Event",
      "MessageClass": "Event",
      "MessageType": "Notification",
      "ProtocolVersion": "3.1"
    },
    "EventNotification": {
      "EventDetails": "Invalid Nexo message",
      "EventToNotify": "Reject"
    }
  }
}

Recommended action

Review the message format and correct the request before resending it.

Logged out

Scenario

The ECR sends a service request but receives an error response with ErrorCondition=LoggedOut.

{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Payment",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "AT12345",
      "ProtocolVersion": "3.1",
      "SaleID": "ECR123",
      "ServiceID": "3"
    },
    "PaymentResponse": {
      "Response": {
        "ErrorCondition": "LoggedOut",
        "Result": "Failure"
      }
    }
  }
}

LoggedOut means that the terminal is connected and available, but no active login session exists between the ECR and the terminal. This may occur, for example, if the terminal has rebooted after the original Login request.

Recommended action

When receiving ErrorCondition=LoggedOut, the ECR should automatically:

1. Send a Login request.
2. Retry the original request.

Unavailable device

Scenario

The ECR sends a service request but receives an error response with ErrorCondition=UnavailableDevice.

{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Login",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "AT12345",
      "ProtocolVersion": "3.1",
      "SaleID": "ECR123",
      "ServiceID": "1"
    },
    "LoginResponse": {
      "Response": {
        "AdditionalResponse": "'AE123456' not connected.",
        "Result": "Failure",
        "ErrorCondition": "UnavailableDevice"
      }
    }
  }
}

UnavailableDevice means that a terminal with the specified terminal ID (POIID) is not currently connected to AIC.

Recommended action

If the terminal ID is correct:

• Retry the operation after a delay.
• Alternatively, use GET /poi-list to retrieve the IDs of currently connected terminals.

Timeout values

Current timeout values used by the terminal:

Recommendations for ECR implementations

In addition to the terminal timeouts listed above, the ECR must account for situations where the cardholder:

• Takes time to present a card.
• Is slow to enter a PIN.
• Enters an incorrect PIN and must retry.

For this reason, the ECR should use sufficiently long timeouts for payment transactions.

Requests such as TransactionStatus, Login, and similar management operations are normally handled directly by the terminal and typically complete in less than one second. For these requests, a timeout of approximately 5–10 seconds is generally sufficient.