menu
Return to solutions

What's on this page

General / Error Handling

Error object

The Error object consists of 2 attributes:

  • MAPIError enum
  • Optional Result containing a ResultState. This is the result that you also get with a successful transaction or terminal action.

When you receive an Error object with only the MAPIError present, you will need to follow the recommended solution in the MAPIError list below. If you get the Error object with an MAPIError and a Result object then you need to check the ResultState of the result object and follow the recommended solution for the ResultState from the ResultState list below.

Examples:

  1. Error(MAPIError.TERMINAL_CONNECTION_LOST) → See MAPIError enum list for recommended action
  2. Error(MAPIError.PAYMENT_ERROR, PaymentResult(state = “PrintLastTicket”)) → See ResultState list for recommended action

MAPIError

The MAPIError class is our only error-enum which contains all of the possible error-codes. It is part of the Error.class, which is returned in the onErrorDelegate when an issue occurs.

MAPIError without Result

MAPIError Description of root-cause Recommended solution
AMOUNT_REQUIRED Payment requires an amount and the amount must be positive. Pass a positive amount during a transaction.
BARCODE_SCAN_FAILED Something went wrong while scanning the barcode. Retry scanning the barcode. If this error still occurs, try scanning a different barcode to verify or contact support.
BARCODE_SCANNER_INITIALIZATION_FAILED Something went wrong while initializing the barcode scanner. Retry scanning the barcode. If this error still occurs, please contact support.
CARD_SERVICE_RESPONSE_DESERIALIZATION_FAILED Failed to deserialize the CardServiceResponse. Contact support.
CONNECTION_ERROR No network connection. This error can occur during the TerminalDiscovery action. Please check network settings.
CUSTOMER_SIGNATURE_NOT_PROVIDED The customer signature must be provided. Pass a customer signature that is not null or empty.
FAILED_TO_CONNECT_TO_TERMINAL Failed to connect to the terminal. Check terminal settings and network connectivity.
FLOW_ALREADY_HAPPENING A flow is currently already happening. Finish the transaction/terminal action before starting a new one.
GERMAN_EICHRECHT_VALUE_ERROR Public key and Signed Meter Value may not be empty and must be of type Hexadecimal. Pass a Public key and Signed Meter Value that is not empty and is of type Hexadecimal.
MERCHANT_REFERENCE_INVALID Merchant reference may not be empty and has a max length of 100 characters. Pass a merchant reference with a maximum length of 100 characters.
MODULE_DOES_NOT_EXISTS This module does not exist on this Pax device. Please contact support to verify if your device supports this action.
NO_CAMERA_PERMISSION No camera permission granted. Please grant camera permission to the application.
NOT_A_FLOW_HAPPENING There isn’t a flow happening at the moment. This error occurs when trying to abort a transaction when no transaction is happening.
PAYMENT_ID_INVALID Payment ID is not of type unsigned integer with a max length of 9 characters. Please start a payment with a correct requestId.
PRINTING_RECEIPT_NULL_OR_EMPTY The payment receipt that needs to be printed may not be null or empty. Pass a payment receipt that is not null or empty.
RECEIVED_UNKNOWN_MESSAGE_FROM_TERMINAL Received an unknown message from the payment terminal. Contact support.
REQUEST_ID_NOT_EQUAL The provided requestId from the Payment object is not equal to the requestId of the last payment retrieved from the terminal. Pass the RequestId of the transaction you want to recover. If the error still occurs, please contact support.
RESPONSE_TIMEOUT Response timeout occurred. When this occurs during a transaction, please perform a RecoverPayment to retrieve the transaction result.
RETRY_REPEAT_LAST_MESSAGE Terminal is unavailable, automatically retrying every 10 seconds for a maximum of 5 minutes in total The RepeatLastMessage has failed because the terminal is unavailable or busy. We will automatically retry the action every 10 seconds. You will be informed when the RepeatLastMessage has succeeded or failed completely.
SECONDARY_FLOW_ALREADY_HAPPENING A secondary flow is already happening. This error occurs when trying to abort a transaction that is already being aborted.
SEND_PASSWORD_ERROR Generating password hashcode has failed. This error occurs when trying to send the terminal password to the terminal during a terminal menu interaction. Please try again, and if this still occurs, please contact support.
SET_CAMERA_PREVIEW_FAILED Could not set camera preview. Retry scanning the barcode. If this error still occurs, please contact support.
SHIFTNUMBER_REQUIRED ShiftNumber must be present on the terminal object to get a transaction overview from the terminal. Pass a ShiftNumber when retrieving a TransactionOverview.
SOCKET_CONNECTION_ISSUE Issue with the socket connection. When this occurs during a transaction, please perform a RecoverPayment to retrieve the transaction result.
STOPPING_BARCODE_SCANNER_FAILED Could not stop the barcode scanner. Retry stopping the barcode scanner. If this error still occurs, please contact support.
TERMINAL_CONNECTION_LOST Connection lost to the terminal. When this occurs during a transaction, please perform a RecoverPayment to retrieve the transaction result.
TOKEN_ERROR An error has occurred while performing a task token transaction. The token request has failed. Please try again. If the error still occurs, please contact support.
UNSUPPORTED This operation is currently not supported. Verify the documentation for more information. Check the documentation or contact support.
WORKSTATION_ID_INVALID WorkstationId has a max length of 16 characters. Pass a WorkstationId with a maximum length of 16 characters.

MAPIError with Result

MAPIError Description of root-cause Recommended solution
ABORT_ERROR Something went wrong while performing an abort. The performed terminal action has failed. Check the included PaymentAdministrationResult for more details.
CARD_READ_FAILED Could not read the card. The performed terminal action has failed. Check the included CardReadResult for more details.
CARD_READER_STATUS_FAILED Could not retrieve card reader status. The performed terminal action has failed. Check the included CardReaderResult for more details.
CARD_VALIDATION_FAILED Failed to perform a card validation. The performed terminal action has failed. Check the included PaymentAdministrationResult for more details.
FINANCIAL_ADVICE_MESSAGES_FAILED Failed to receive financial advice messages. The performed transaction has failed. Check the included TokenResult for more details.
GETTING_MENU_FAILED Unable to retrieve the terminal menu. The performed terminal action has failed. Check the included PaymentAdministrationResult for more details.
INITIALISATION_ERROR An error has occurred while initializing the terminal. The performed terminal action has failed. Check the included PaymentAdministrationResult for more details.
OPENING_SERVICE_MENU_FAILED Unable to open the terminal service menu. The performed terminal action has failed. Check the included PaymentAdministrationResult for more details.
PAYMENT_ADMINISTRATION_ERROR An error has occurred while performing a payment administration task. The performed terminal action has failed. Check the included PaymentAdministrationResult for more details.
PAYMENT_ERROR Could not perform a payment. The performed transaction has failed. Check the included PaymentResult for more details.
PRE_AUTHENTICATION_FAILED Failed to perform a pre-authentication. The performed transaction has failed. Check the included TokenResult for more details.
READ_MIFARE_UID_FAILED Reading Mifare UID failed. The performed terminal action has failed. Check the included TokenResult for more details.
RECONCILIATION_WITH_CLOSURE_FAILED Could not reconcile with closure. The performed terminal action has failed. Check the included PaymentAdministrationResult for more details.
REPEAT_LAST_PAYMENT_FAILED Could not repeat the last payment. The performed terminal action has failed. Check the included PaymentAdministrationResult for more details.
REPRINT_LAST_TICKET_FAILED Could not reprint the last ticket. The performed terminal action has failed. Check the included PaymentAdministrationResult for more details.
REQUEST_TERMINAL_STATUS_FAILED Could not receive status from the terminal. The performed terminal action has failed. Check the included PaymentAdministrationResult for more details.

ResultState

ResultState is a part of the Result object (PaymentResult, PaymentAdministrationResult, TokenResult, CardReadResult, CardReaderResult)

ResultState Description of root-cause Recommended solution
Aborted Complete failure. The transaction was aborted on the terminal or on the POS. Retry or start a new transaction.
Busy The terminal is currently still processing a previous action. Retry every 5 seconds for a minimum of 5 times. For the RecoverPayment and RepeatLastMessage, this is done within the Android SDK.
CommunicationError Complete failure. Retry or start a new transaction.
DeviceUnavailable Complete failure. No further request will be successful because a device is temporarily unavailable due to a POS-initiated function. It is recommended to retry the function after 10 seconds. (It is up to the POS to select a proper value and limit the number of retries.)
Failure Complete failure. Retry or start a new transaction.
FormatError Complete failure. The request cannot be processed or is mistakenly formatted. Contact support.
MissingMandatoryData Complete failure. The XML request message is missing mandatory data. Contact support.
ParsingError Complete failure. The XML request message is not well formed. Contact support.
PartialFailure Some part went wrong. Unacceptable partial errors have to be reversed. Retry or start a new transaction.
PrintLastTicket Complete failure. The payment is rejected because the DeviceRequest towards Printer and/or JournalPrinter/E-Journal of the previous transaction is not answered with “Success” in time. The POS is supposed to send a ‘TicketReprint’ message to retrieve, confirm, and print/store the receipt and journal to unblock the terminal. Perform a TicketReprint.
Success Complete success. No action needed.
TimedOut Complete failure. No response from remote host or cardholder timeout. Retry or start a new transaction.
Unknown Unknown error. Contact support.
ValidationError Complete failure. The XML request message is not validated against the definition scheme. Contact support.