Technical Issues ​

Common technical fixes for integration and runtime issues

1. WebView cannot open third-party apps (ERR_UNKNOWN_URL_SCHEME, etc.)

Symptom: When redirecting to GoPay / LinePay / AirPay, you see ERR_UNKNOWN_URL_SCHEME or the target app does not open.

Cause: The WebView does not intercept and handle intent:// or custom schemes.

Fix (Android): Override WebViewClient.shouldOverrideUrlLoading and perform a system intent jump or fallback for intent:// and non-http/https schemes. Simplified example:

@Override
public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
    String url = request.getUrl().toString();
    Uri uri = Uri.parse(url);
    if ("intent".equals(uri.getScheme())) {
        try {
            Intent intent = Intent.parseUri(url, Intent.URI_INTENT_SCHEME);
            if (intent.resolveActivity(context.getPackageManager()) != null) {
                context.startActivity(intent);
            } else {
                String fb = intent.getStringExtra("browser_fallback_url");
                if (!TextUtils.isEmpty(fb)) view.loadUrl(fb);
            }
            return true;
        } catch (Exception e) { /* ignore */ }
    }
    if (!"http".equals(uri.getScheme()) && !"https".equals(uri.getScheme())) {
        try { context.startActivity(new Intent(Intent.ACTION_VIEW, uri)); return true; }
        catch (Exception ignored) {}
    }
    return false;
}

2. Return to your app after successful payment

Key points: If the cashier is opened in an in-app WebView, ensure frontCallBackUrl uses a scheme or deep link your app can handle. If opened in an external browser, use a scheme/Universal Link for the return.

3. Asynchronous callback notes

   • The callback endpoint must be reachable and respond with application/json.
   • Validate signatures and implement idempotency.
   • If your server uses an IP allowlist, add Checus callback IPs.

4. No navigation after clicking "Confirm Payment"

Cause: WebViewClient not set or overridden.

Fix: If using Android WebView as the API container, configure WebView as follows

mWebView.setWebViewClient(new WebViewClient());

5. Cashier shows "invalid parameter format" (amount formatting garbled)

Cause: Formatting amounts using device Locale (may introduce thousand separators or different decimal separators).

Fix: Use English locale consistently: String amt = String.format(Locale.ENGLISH, "%.2f", price);

6. Cashier layout incomplete or messy (adaptation issues)

Suggestion: Ensure meta viewport and responsive layout support.

mWebView.getSettings().setTextZoom(100);

7. Soft keyboard covers input fields

Checklist and fix:

• Avoid fullscreen mode.
• Set windowSoftInputMode to adjustResize (avoid adjustPan).
• If using immersive status bar, set layout fitSystemWindows=true.

8. URI scheme auto lowercased (APP:// → app://)

Cause: Browsers/WebViews treat schemes as case-insensitive and normalize to lowercase.

Fix: Use lowercase scheme and host in AndroidManifest.

9. Page reports X-Frame-Options

Cause: The channel page disallows iframe embedding.

Fix: Do not embed in an iframe; open the page directly.

10. Recommended Android WebView settings (important)

   WebSettings webSettings = mWebView.getSettings();
   webSettings.setJavaScriptEnabled(true);

   webSettings.setSupportMultipleWindows(true);
   webSettings.setJavaScriptCanOpenWindowsAutomatically(true);

   webSettings.setPluginState(WebSettings.PluginState.ON); //enable plugin. Ex: flash. deprecated on API 18
   //whether the zoom controls display on screen.
   webSettings.setBuiltInZoomControls(true);
   webSettings.setSupportZoom(true);
   webSettings.setDisplayZoomControls(false);

   //disable the webview font size changes according the phone font size.
   webSettings.setTextZoom(100);
   webSettings.setSaveFormData(true);
   webSettings.setUseWideViewPort(true);
   webSettings.setLoadWithOverviewMode(true);
   webSettings.setAllowFileAccess(true);

   if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
       webSettings.setMixedContentMode(WebSettings.MIXED_CONTENT_ALWAYS_ALLOW);
       CookieManager.getInstance().setAcceptThirdPartyCookies(this, true);
   }
   if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN) {
       webSettings.setAllowUniversalAccessFromFileURLs(true);
   }

   webSettings.setAppCacheEnabled(true);
   String appCacheDir = getDir("cache", Context.MODE_PRIVATE).getPath();
   webSettings.setAppCachePath(appCacheDir);
   webSettings.setAppCacheMaxSize(1024*1024*20);
   webSettings.setDomStorageEnabled(true);
   webSettings.setDatabaseEnabled(true);
   webSettings.setCacheMode(WebSettings.LOAD_DEFAULT);

   try {
       mWebView.removeJavascriptInterface("searchBoxJavaBridge_");
       mWebView.removeJavascriptInterface("accessibility");
       mWebView.removeJavascriptInterface("accessibilityTraversal");
   } catch (Exception e) {}

   if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
       mWebView.enableSlowWholeDocumentDraw();
   }

11. Error net::ERR_CACHE_MISS

Cause: Network permissions or request flow blocked.

Troubleshoot: Check AndroidManifest permissions and cross-origin/cache policies; see community help.

12. iOS WKWebView redirect failure (# encoded as %23)

Cause: WKWebView encodes URLs by default, causing # to be encoded.

Fix: Customize the allowed-character set when encoding. Example (Swift): ensure # is allowed.

var charSet = CharacterSet.urlQueryAllowed
charSet.insert(charactersIn: "#")
let enc = urlStr.addingPercentEncoding(withAllowedCharacters: charSet)

13. Android 9+ (P) cannot open http pages

Cause: Android P disables cleartext (http) traffic by default.

Solutions (two options):

• Prefer migrating pages/APIs to HTTPS; or
• Use network_security_config.xml to allow cleartext, or add usesCleartextTraffic="true" in AndroidManifest.

14. Error: net::ERR_BLOCKED_BY_RESPONSE (blocked)

Cause: The page disallows iframe embedding or is blocked by response headers.

Fix: Open the page directly and avoid iframes.