Skip to main content

Transaction Failures on Sunmi Devices (Overlays & App Visibility)

If transactions are failing on Sunmi devices with "must remain in background" (800.-10) or visibility errors (900.860 / 1100.-860), this article explains the cause and how to resolve it.

Updated today

Transactions Fail on Sunmi Devices with "must remain in background" or Visibility Errors

If you're using the Softpay AppSwitch SDK on a Sunmi device and transactions are consistently failing, you may be seeing one or both of the following errors:

800.-10 - must remain in background

1100.-860 - Transaction runtime invalid: [visibility=invalid:RESTRICTED]
900.860 - Transaction runtime invalid: [visibility=invalid:RESTRICTED]

This article explains why these errors occur on Sunmi hardware and how to resolve them.

Symptoms

  • Charge or payment operations fail immediately or mid-flow

  • Error 800.-10 is returned to the POS app while Softpay is still processing

  • Error 1100.-860 or 900.860 is returned with the detail visibility=invalid:RESTRICTED

  • The issue occurs repeatedly on the same device but not on other hardware

  • Transactions are correctly aborted — no double charges occur

What These Errors Mean

800.-10 — Must Remain in Background

The AppSwitch SDK requires that the calling POS app stays in the background while Softpay handles a transaction. If the POS app is brought back to the foreground while a request is still PROCESSING, the SDK sends a coerced abort and returns 800.-10.

On Sunmi devices (and some other Android-fork devices), the operating system's custom app lifecycle manager can resume the POS app unexpectedly — without any action from the user or the app itself. This is a device OS-level behaviour and cannot be worked around in the SDK.

1100.-860 / 900.860 — Visibility Restricted

The AppSwitch SDK continuously monitors a set of runtime traits during a transaction, including screen visibility. When it detects that visibility is RESTRICTED — meaning a system-level overlay is drawn over the payment screen — it marks the transaction runtime as invalid and aborts.

Common causes of a RESTRICTED visibility state:

  • Android developer options such as Show touches or Pointer location (these draw persistent overlay windows)

  • Any app granted "Display over other apps" permission that has an active overlay

  • Sunmi's own launcher or system service maintaining a window layer above the transaction UI

Affected Devices

This behaviour is most commonly reported on Sunmi devices running SUNMI OS (Sunmi's Android fork).

Similar issues have been observed on other devices with heavily customised Android distributions (e.g. Xiaomi, Huawei). The root cause in all cases is the same: the device's OS layer interferes with Android's standard foreground/background lifecycle or draws persistent system overlays.

Resolution Steps

Work through these steps in order. Most cases are resolved by steps 1–3.

Step 1: Disable developer options overlays

On the Sunmi device, go to Settings → Developer options and check for the following — disable all of them if enabled:

  • Show touches (draws circles on screen wherever taps occur)

  • Pointer location (displays a crosshair overlay)

  • Simulate secondary displays or any other display overlay setting

Developer options shouldn't be enabled at all in your production setup, disable them entirely: Settings → Developer options → toggle off at the top.

Step 2: Revoke "Display over other apps" permissions

Go to Settings → Apps → Special app access → Display over other apps. Review the list and revoke this permission for any app that does not strictly require it (especially non-system apps).

Step 3: Check Sunmi launcher or kiosk mode configuration

If the POS app is configured as the Sunmi default launcher or is running inside Sunmi's SunmiShop kiosk mode, this can keep its window active on top of the Softpay transaction UI. Change the device to use the standard Android launcher and ensure the POS app is not set to always-foreground.

Step 4: Update the device firmware

Check the Sunmi firmware version under Settings → About device → System version.

Important: Sunmi does not automatically push firmware updates to devices. New firmware versions are not made available unless explicitly requested. The device owner must contact Sunmi support directly and ask them to make the relevant firmware update available for their specific device. Contact your Sunmi distributor or reach out via Sunmi's support portal to initiate this. Once the update has been applied, retest the full transaction flow to confirm the issue is resolved.

Step 5: Test on an alternative device

If none of the above steps resolve the issue, the Sunmi model may have a fundamental OS-level incompatibility with AppSwitch's foreground/background handling. Test the same integration on a different certified device to confirm. If transactions succeed on another device, treat this as a hardware-specific limitation and work with the merchant to source compatible hardware.

Prevention

  • Do not enable developer options on production terminals. Options like "Show touches" are useful for testing but must be disabled before deployment.

  • Certify your hardware before deploying at scale. Always run a full transaction test cycle (charge, refund, void) on the specific device model and firmware version you plan to use.

  • Avoid kiosk/launcher configurations that give the POS app persistent window priority over the system.

Still Having Issues?

If you've worked through all the steps above and transactions are still failing, contact Softpay support with the following information:

  • Device model and firmware version

  • AppSwitch SDK version

  • POS app name and version

  • The full error message and stack trace

  • The terminal App ID (visible in the Softpay app or your integration logs)

  • Timestamp for issue

Did this answer your question?