Troubleshooting
Diagnosing the Flutter SDK by what the buyer sees.
The screen shows an error panel instead of the payment block
Either the WebView itself failed to load the page, or one of two load deadlines elapsed — the copy tells you which:
| Panel says | Deadline | Likely cause |
|---|---|---|
| "Couldn't load the payment page" | the WebView itself never finished loading (load_error) | no connection, a blocked host |
| "Couldn't reach the payment page" | 12s after the screen opened, no alive | a slow or stalled connection, or the page loaded but the app never heard from it (see below) |
| "The payment page is taking too long" | 25s after alive, no ready | the page ran but the block never mounted |
"Close" completes the session as SuqoClosed, the same as a buyer backing out. "Try again" reloads the checkout.
"Couldn't reach the payment page" on a connection that works
The page loaded, but none of its messages reached the app. Two causes:
baseUrlredirects to another host. The package only accepts messages from the exact scheme, host and port it opened — sohttp://redirecting tohttps://, or a bare domain redirecting toapp., drops every message. SetbaseUrlto the final URL, after any redirect.- The checkout page does not recognise the app as a native host. This package names its JavaScript channel
SuqoWebView, and the page must probe for it. See Requirements on the SUQO web app in the SDK README.
Read onEvent before assuming it is this package rather than the session itself (expired, wrong environment). Events are delivered whether or not debug is on; debug only adds this package's own log output.
open throws immediately
SuqoConfigError, for one of its three reasons. Check you are not passing an empty session id, that baseUrl (if set) is an http(s) URL, and that baseUrl and checkoutPath together form a valid URL. Also confirm mode or baseUrl points at the environment the session was actually created against.
The page says the session can't be paid
The session itself is the problem, not the app. Watch for an unavailable event — its reason says why. The most common are notFound (a sandbox session opened in live mode, or the reverse), expired, spent and noCustomer. See Debug with events.
The buyer paid but the app shows cancelled
Should not happen: the page reports cancelled only from the gateway's own return URL, never from the screen closing. If you see it, check the checkout page against the protocol in suqo-checkout-js rather than assuming this SDK invented the status.
A bank or wallet deeplink does nothing
Watch for a handoff_failed event — the OS had no app registered for that scheme. Either the bank app is not installed, the scheme is missing from <queries> on Android 11+, or the scheme is wrong for the platform you are testing on. See step 5 of the quickstart.
If the event's scheme is intent, the gateway sent an Android intent URI. Do not declare intent — it does nothing. Declare the scheme named by scheme= inside the URI instead (for intent://pay#Intent;scheme=fonepayApp;…;end, that is fonepayApp).
Debug console output from the page is missing its first moments
Expected, and debug-only. webview_flutter has no document-start script injection (flutter#105202), so the earliest hook is onPageStarted, which races the page's first scripts. A throw during the page's very first moments can be missed. It does not affect payments.