Troubleshooting
Diagnosing the React Native SDK by what the buyer sees.
The sheet 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, no suqo:alive | the document loaded but never ran its scripts |
| "The payment page is taking too long" | 25s after alive, no suqo:ready | the page ran but the block never mounted |
"Try again" remounts the WebView fresh; "Close" settles the session as closed, same as a buyer backing out. Turn on debug and read onEvent / the forwarded console output before assuming it is this package rather than the session itself (expired, wrong environment).
open() rejects immediately
Either a checkout is already open (call close() or wait for the current one to settle before opening another), or the sessionId / resolved baseUrl could not build a URL — check you are not passing an empty string, and that mode or baseUrl points at the environment the session was actually created against.
The buyer paid but the app shows cancelled
Should not happen: the page only reports cancelled from the gateway's own return URL, never from the WebView closing. If you see it, check that the SUQO checkout page you are pointing at is current (a closed gateway window must not be treated as an outcome) rather than assuming this SDK invented the status, and contact SUQO support with the session id if it persists.
Nothing comes back at all; the sheet just sits there
The checkout page is not recognising this as a native host — confirm it still checks for window.SuqoWebView / window.ReactNativeWebView, treats a native host as a gateway window (skips return_url), and hands off to gateways in the same window rather than a popup. See Requirements on the SUQO web app in the SDK README.
A bank/wallet deeplink does nothing
Watch for onEvent({ type: 'handoff_failed', scheme }) — it means the OS had no app registered for that scheme (the bank app isn't installed, or the scheme is wrong for the platform you're testing on).