Transaction recovery

Overview

While a transaction is in progress, your POS is continuously polling the SCI API for updates. In normal operation, this polling loop runs until the transaction reaches FINALISED. However, real-world conditions - a network drop or a terminal going offline - can leave the polling loop without a response for the POS to act on.

Without an exit strategy, the POS would poll indefinitely, leaving the transaction unresolved and the merchant unable to continue. The override flow is the mechanism that prevents this: after a defined period of inactivity, the POS exits the polling loop and presents the merchant with a dialog to manually confirm the outcome.

Failure scenarios

Terminal network disconnection

The terminal loses its network connection and goes offline. The SCI API is unable to reach the terminal and returns the following:

Example response:

{
  "error": {
    "code": "device_not_connected",
    "message": "The payment device is not connected."
  }
}

Expected behaviour: The POS displays an error message.

• Suggested wording: "Please check network and terminal connections and try again."

POS network disconnection

The POS loses its own network connection and can no longer reach the SCI API. In this case the POS will not receive an API response at all - polling calls will fail at the network level before reaching the API.

Expected behaviour: The POS displays an error message.

• Suggested wording: "Please check network and terminal connections and try again."
• The POS allows the merchant to retry the transaction once connectivity is restored.

📘

In a POS disconnection scenario, the terminal may have completed the transaction even though the POS never received confirmation. This is precisely the scenario the override flow is designed to handle - if polling cannot be resumed, present the merchant with the override dialog rather than automatically treating the transaction as failed.

The override flow

When no response has been received from the SCI API for a POS-determined period of time, the POS must exit the polling loop and present the merchant with an override dialog.

The override dialog asks the merchant to manually verify the outcome of the transaction by checking the terminal or receipt:

"Was the transaction successful?"

Yes - Close the sale. The transaction is treated as approved.

No - The sale remains open. The merchant can retry the transaction.

Transaction timeout

If the POS receives no response from the SCI API for a defined period during a transaction, the polling loop should be exited and the override dialog presented.

Cancellation timeout

If the merchant initiates a cancellation from the POS and no finalised response is received within a defined period, the polling loop should be exited and the same override dialog presented.

📘

The timeout threshold for a cancellation scenario can differ from the general transaction timeout - this is intentional and depends on your POS's UX and the expected time for a cancellation to be confirmed.

Determining your timeout thresholds

The timeout values are not mandated by mx51 - your POS determines them based on your intended merchant UX, industry norms, business type, or other considerations.

As a reference point, the mx51 demo POS application Espresso POS uses the following thresholds:

⚠️

These values are indicative only. They reflect the UX decisions made for a demo application and should not be treated as requirements or recommendations for your integration.