Nimiq Pay (iOS): mini-app WebView stays stacked over the wallet after re-opening a mini-app deeplink — force-quit is the only recovery

[surfstyk]

Filing here because there is no public repo for the Nimiq Pay app or the mini-apps host — the mini-apps docs point "Report an issue" to this repo. Please route to the right team.

Summary

On iOS, the mini-app WebView can get stuck rendered on top of the native wallet screen: the wallet's transaction list + PAY bar stay visible underneath the mini-app, input routing breaks, the ✕ (close) button does not dismiss, and the only way out is force-quitting Nimiq Pay. It has happened repeatedly and is not specific to one mini-app.

Steps to reproduce

1. Open a mini-app in Nimiq Pay (from the mini-apps section, or via a nimiqpay://miniapp?url=… deeplink).
2. Use it, then leave Nimiq Pay (switch to another app / background it) without tapping ✕ to close the mini-app.
3. Open a second mini-app deeplink.
4. → The mini-app WebView and the wallet UI end up stacked on top of each other; the ✕ is unresponsive; only force-quitting Nimiq Pay recovers.

Expected

Opening a mini-app presents a clean, full-screen WebView, and ✕ always dismisses back to the wallet.

Actual

The mini-app WebView is layered over the wallet screen (transaction list + PAY bar showing through), the ✕ is dead, and a force-quit of Nimiq Pay is required. Screenshot below.

Environment

• Nimiq Pay 2.19.1
• iOS 26.6.1
• iPhone 13 Pro
• Reproduced multiple times.

Likely cause (guess from the outside)

The mini-app appears to be presented as a modal WebView over the wallet. Re-entering via a deeplink while a previous mini-app presentation is still backgrounded/stale seems to leave the native view stack un-torn-down, so the new WebView layers over an un-dismissed wallet screen with broken input routing. It reproduces across different mini-apps, which points to a host/framework lifecycle issue rather than an app-specific bug.

Screenshot

Screenshot: the mini-app's screen with the wallet's transaction list + "PAY" bar visible underneath it, and an unresponsive ✕ in the mini-app chrome.

---

Happy to provide more detail. This affects any mini-app, so flagging it for the framework/Nimiq Pay team.

[surfstyk]

Update: no client-side fix works, and this reproduces on other mini-apps too — it's the host container.

Since the last update I built a client-side workaround and tested it on device. It does not fix the problem, and I now have it reproducing on a second, unrelated mini-app, so this is in Nimiq Pay's WebView container rather than any one app.

What I tried: a lifetime resume watcher (visibilitychange / pageshow / focus) that calls location.reload() when the app returns from the background, on the idea that re-navigating the WebView would make the container re-present it cleanly.

What I found on device (iPhone 13 Pro, iOS 26.6.1, Nimiq Pay 2.19.1):

• The resume events do fire in the frozen state and our JS keeps running. I put a live clock in the app and it keeps ticking while the app is frozen, so the WebView content is alive and only input is dead.
• The reload fires on every return, but the frozen composite comes straight back. In the attached screenshot the app is still frozen 25 seconds after a reload: it is drawn over the wallet's transaction list and PAY bar, taps are dead, and the in-app clock reads 25 seconds past the reload.

So the WebView content is alive and repainting, but the native container is presenting it over the wallet with input routing broken. A location.reload() only reloads the web content inside the WebView, so it cannot change how the native side layers or routes input. There is no lever a mini-app can pull from JS.

It also reproduces on another mini-app, "Pay It Sideways" (second screenshot): background Nimiq Pay, use another app, come back, and its WebView is stuck over the wallet with dead input. Different app, same failure.

Questions for the team:

1. Can you reproduce this with the single-app app-switch steps (open a mini-app, background Nimiq Pay, use another app, return)?
2. Is there any host or SDK hook a mini-app can call on resume to force a clean re-present? The current SDK surface (init, getHostLanguage, requestDeviceIdentifier) does not expose one.
3. If it is confirmed host-side, is a fix on the roadmap? With the competition running, a judge who backgrounds any entry and returns sees a broken app through no fault of the builder.

Happy to send a screen recording or test a build.