Technical Issues ​

Common technical fixes for integration and runtime issues

Global Acquiring

1. Recommended way to open the cashier in an app

Applicable scenario: Merchants using the "all payment methods cashier" or the "specified payment method cashier".

Recommendation: Prefer opening the Checus cashier in the user's mobile system browser. Avoid opening the cashier inside an in-app WebView whenever possible.

Some payment methods require redirecting the user to an e-wallet, banking app, or payment-channel page during the transaction. The system browser provides better compatibility for external app redirection, Deep Links, Universal Links, and similar behaviors. This reduces the risk of the payment flow being blocked by the WebView container.

If your business must use WebView, make sure the WebView allows the following channel links to redirect properly.

Region	Institution	Redirect URL - Web	Redirect URL - App
Brazil	MERCADOPAGO	https://www.mercadopago.com.br/	-
Indonesia	DANA	https://m.dana.id/	-
Indonesia	GOPAY	https://gopay.co.id/	gopay.co.id/* *.gopay.co.id/*
Indonesia	SHOPEEPAY	https://app.shopeepay.co.id/	shopeepayid://
Japan	PAYPAY	https://www.paypay.ne.jp/	-
South Korea	NAVERPAY	https://m.pay.naver.com/	-
South Korea	PAYCO	https://bill.payco.com/	-
South Korea	TOSS	https://pay.toss.im/	-
Malaysia	TNG	https://m.tngdigital.com.my/	-
Philippines	GCASH	https://payments.gcash.com/	-
Russia	SBERPAY	https://securepayments.sberbank.ru/ https://epay.sberbank.ru/	sberpay://
Russia	TPAY	https://pay.tbank.ru/ https://securepay.tinkoff.ru/	https://o.tbank.ru/tpay/
Singapore	SHOPEEPAY	shopeesg://	https://shopeepay.sg/
Thailand	PAOTANGPAY	paotang://	-
Thailand	SHOPEEPAY	https://app.shopeepay.co.th/	shopeeth://
Thailand	TRUEMONEY	https://tmn.app.link/	-

For Russian payment methods, SberPay and T-Pay may involve external app redirection or mobile redirection. If the merchant app opens the cashier in WebView, make sure the WebView does not block the domains, HTTPS App Links, or custom schemes listed above. In production, the complete URLs that need to be allowed should follow the redirect URLs returned by the Checus cashier.

2. WebView cannot launch a third-party app (ERR_UNKNOWN_URL_SCHEME, etc.)

Symptom: When using GoPay, LinePay, or similar payment methods, the WebView page shows ERR_UNKNOWN_URL_SCHEME, or the corresponding third-party app cannot be launched.

Cause: WebView handles regular links such as http and https by default. If the channel returns an intent:// URL or a custom scheme, and the merchant app does not intercept it and pass it to the system, the redirection may fail.

Solution: If the cashier is opened in Android WebView, override shouldOverrideUrlLoading in WebViewClient. Handle intent:// URLs and non-http/https schemes by launching them through the system or using a fallback URL.

Core example:

@Override
public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
    String url = request != null && request.getUrl() != null
            ? request.getUrl().toString()
            : "";
    return handleExternalUrl(view, url) || super.shouldOverrideUrlLoading(view, request);
}

private boolean handleExternalUrl(WebView view, String url) {
    if (TextUtils.isEmpty(url)) {
        return false;
    }

    Uri uri = Uri.parse(url);
    String scheme = uri.getScheme();

    if ("intent".equals(scheme)) {
        try {
            Intent intent = Intent.parseUri(url, Intent.URI_INTENT_SCHEME);
            if (intent.resolveActivity(context.getPackageManager()) != null) {
                context.startActivity(intent);
                return true;
            }

            String fallbackUrl = intent.getStringExtra("browser_fallback_url");
            if (!TextUtils.isEmpty(fallbackUrl)) {
                view.loadUrl(fallbackUrl);
                return true;
            }
        } catch (Exception ignored) {
        }
    }

    if (!"http".equalsIgnoreCase(scheme) && !"https".equalsIgnoreCase(scheme)) {
        try {
            context.startActivity(new Intent(Intent.ACTION_VIEW, uri));
            return true;
        } catch (Exception ignored) {
        }
    }

    return false;
}

Full example: TestWebViewClient.java

If the cashier is opened in iOS WKWebView, intercept non-http/https schemes in the navigation policy and pass them to the system.

Objective-C example:

- (void)webView:(WKWebView *)webView
decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {

    NSURL *requestUrl = navigationAction.request.URL;
    NSString *scheme = requestUrl.scheme;

    if (scheme && ![scheme isEqualToString:@"http"] && ![scheme isEqualToString:@"https"]) {
        decisionHandler(WKNavigationActionPolicyCancel);

        UIApplication *application = [UIApplication sharedApplication];
        if (@available(iOS 10.0, *)) {
            [application openURL:requestUrl options:@{} completionHandler:nil];
        } else {
            [application openURL:requestUrl];
        }
        return;
    }

    decisionHandler(WKNavigationActionPolicyAllow);
}

Swift example:

func webView(_ webView: WKWebView,
             decidePolicyFor navigationAction: WKNavigationAction,
             decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {

    guard let url = navigationAction.request.url,
          let scheme = url.scheme else {
        decisionHandler(.allow)
        return
    }

    if scheme != "http" && scheme != "https" {
        decisionHandler(.cancel)
        UIApplication.shared.open(url, options: [:], completionHandler: nil)
        return
    }

    decisionHandler(.allow)
}

If the app cannot be opened, guide the user to install the corresponding app or redirect the user to the App Store / app marketplace search page based on your business requirements.

3. DANA payment page is blank or shows a network instability message

Symptom: When opening DANA through the standard API deposit integration, the page may appear blank. After scrolling, the following error message may be visible: The network connection is unstable. Please try again later.

Cause: Required storage or viewport settings are not enabled in Android WebView, causing channel page resources to load abnormally.

Solution: Confirm that the following WebView settings are enabled during initialization:

webSettings.setDomStorageEnabled(true);
webSettings.setTextZoom(100);
webSettings.setUseWideViewPort(true);

4. How to return to the merchant app after a successful payment

Description: After payment is completed, Checus opens the frontend callback URL frontCallBackUrl passed by the merchant.

• If the cashier is opened inside the merchant app's WebView, frontCallBackUrl will usually open in the same app container.
• If the cashier is opened in an external browser, frontCallBackUrl will open in the external browser. To return to the merchant app, design the callback URL as a scheme, Deep Link, or Universal Link.

We recommend supporting both "return to app" and "show result in browser" on the payment result page, so users can continue the business flow smoothly.

5. Notes on asynchronous callback notifications

Applicable scenario: The merchant obtains the payment result through server-side asynchronous notifications.

Confirm the following items:

1. The callback URL exists and is accessible from the public network.
2. The callback API supports application/json.
3. The callback handler verifies the signature and implements idempotency.
4. If the merchant server uses an IP allowlist, add the Checus callback server IPs to the allowlist.
5. For the callback response body, see Asynchronous Notification.

Note: The final payment status should be determined by the server-side asynchronous notification or active query result. Do not rely only on the frontend redirect result.

6. No subsequent payment page opens after clicking "Confirm Payment"

Symptom: In the standard API deposit integration, no subsequent payment page opens after the user clicks "Confirm Payment".

Cause: Android WebView does not have a WebViewClient set, or the relevant redirection is intercepted by the default container behavior.

Solution: At minimum, set a WebViewClient for the WebView:

mWebView.setWebViewClient(new WebViewClient());

If the payment method needs to launch a third-party app, also refer to "WebView cannot launch a third-party app".

7. The cashier shows "Request parameter format error"

Symptom: After entering the cashier, the page shows "Request parameter format error".

Common cause: The merchant formats the amount using the device's default locale, for example:

String.format(Locale.getDefault(), "%.2f", price)

Different Locale settings may produce different decimal separators or amount formats, causing the amount to fail the API requirement.

Solution: Use English locale for amount formatting:

String.format(Locale.ENGLISH, "%.2f", price)

8. Payment methods are incomplete or the cashier layout is abnormal

Symptom: Payment methods on the cashier page are incomplete, the layout is misaligned, or fonts look abnormal.

Cause: Android WebView font scaling follows the system setting, which may affect page layout.

Solution: Fix the WebView text zoom ratio:

mWebView.getSettings().setTextZoom(100);

9. Soft keyboard covers the input field during payment

Symptom: During payment, some payment methods require the user to enter a phone number, email address, or similar information. After the user taps the input field, the soft keyboard covers the input area.

Recommendations:

1. Do not set the payment page container to fullscreen mode.
2. windowSoftInputMode can be unset or set to adjustResize.
3. Avoid using adjustPan.
4. If immersive status bar mode is used, set fitSystemWindows=true in the layout.

10. URI scheme is automatically converted to lowercase

Symptom: The merchant passes a URI such as APP://, but it becomes app:// during redirection.

Cause: Browsers and WebView usually process schemes according to URL specifications. Schemes are case-insensitive, and some containers normalize them to lowercase.

Solution: Configure both scheme and host in AndroidManifest in lowercase to avoid app launch failures caused by case mismatch.

11. Page reports X-Frame-Options

Symptom: The page reports an X-Frame-Options related error during loading.

Cause: The channel page does not allow iframe embedding.

Solution: Do not open the page inside an iframe. Open the page URL directly.

12. Recommended Android WebView configuration

If the merchant must open the Checus cashier in Android WebView, we recommend confirming at least the following settings:

WebSettings webSettings = mWebView.getSettings();
webSettings.setJavaScriptEnabled(true);
webSettings.setDomStorageEnabled(true);
webSettings.setDatabaseEnabled(true);
webSettings.setCacheMode(WebSettings.LOAD_DEFAULT);
webSettings.setTextZoom(100);
webSettings.setUseWideViewPort(true);
webSettings.setLoadWithOverviewMode(true);
webSettings.setSupportMultipleWindows(true);
webSettings.setJavaScriptCanOpenWindowsAutomatically(true);

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

mWebView.setWebViewClient(new WebViewClient());

Also confirm the following:

• Hardware acceleration is enabled for the Activity: android:hardwareAccelerated="true".
• If the payment flow involves a third-party app, intent:// and custom schemes are handled properly.
• If the merchant has custom cache handling, avoid disabling cashier static resource caching.
• If the project still supports older Android versions, evaluate configurations such as allowFileAccess, allowUniversalAccessFromFileURLs, zoom controls, and multi-window support based on the actual security policy.
• If the project supports lower Android versions, remove high-risk JavaScript interfaces injected by default, such as searchBoxJavaBridge_, accessibility, and accessibilityTraversal.

13. Cashier domain pre-connect recommendation

Applicable scenario: The merchant wants to optimize the first-load time of the cashier.

Recommendation: After the app starts, or when the user enters the pending-payment page but has not clicked pay yet, pre-connect to the Checus cashier domain. This can reduce DNS and TLS handshake time when the cashier is actually opened.

• Android: Introduce androidx.browser:browser, then use CustomTabsClient.warmup() and mayLaunchUrl(Uri.parse("https://cashier.checus.com")) to warm up the underlying connection pool.
• iOS: Before entering payment, send a lightweight HTTPS request to https://cashier.checus.com, or use public pre-connect capabilities supported by the current iOS SDK.

14. Page reports net::ERR_CACHE_MISS

Cause: When Android network permissions are configured incorrectly, WebView may report net::ERR_CACHE_MISS.

Solution: Check the network permission in AndroidManifest.xml. The permission name must use uppercase INTERNET.

Incorrect example:

<uses-permission android:name="android.permission.internet"/>

Correct example:

<uses-permission android:name="android.permission.INTERNET"/>

15. iOS WKWebView redirection fails, but the system browser works

Symptom: The same link opens correctly in the system browser, but redirection fails in iOS WKWebView.

Possible cause: WKWebView encodes the URL and changes # in the link to %23, causing the channel page to fail to recognize the URL.

Solution: Add URL encoding compatibility logic to keep # as an allowed character.

Objective-C example:

-(NSString *)WM_FUNC_urlEncode:(NSString *)urlStr {
    NSMutableCharacterSet *set = [[NSCharacterSet URLQueryAllowedCharacterSet] mutableCopy];
    [set addCharactersInString:@"#"];
    return [urlStr stringByAddingPercentEncodingWithAllowedCharacters:set];
}

Swift example:

func WM_FUNC_urlEncode(_ urlStr: String) -> String {
    if urlStr.isEmpty {
        return ""
    }

    var charSet = CharacterSet.urlQueryAllowed
    charSet.insert(charactersIn: "#")
    return urlStr.addingPercentEncoding(withAllowedCharacters: charSet) ?? ""
}

16. Android 9.0 or later cannot open http pages

Symptom: Devices running Android 9.0 or later cannot open http pages, while devices below Android 9.0 work normally.

Cause: Starting from Android P, HTTP cleartext traffic is restricted by default. Unencrypted requests may be blocked by the system.

Solution: Prefer changing the related APIs or pages to HTTPS.

If HTTP is still required by the business, allow cleartext traffic in one of the following ways.

Option 1: Add res/xml/network_security_config.xml.

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
  <base-config cleartextTrafficPermitted="true" />
</network-security-config>

Then reference it in AndroidManifest.xml:

<application android:networkSecurityConfig="@xml/network_security_config">
  <uses-library android:name="org.apache.http.legacy" android:required="false" />
</application>

Option 2: Configure the following in AndroidManifest.xml:

<application android:usesCleartextTraffic="true">

17. WebView reports net::ERR_BLOCKED_BY_RESPONSE

Cause: The target page does not support opening inside an iframe, or the response header policy blocks embedding.

Solution: Do not embed the page through an iframe. Open the page URL directly.

Parameter Configuration

1. How do I generate a key?

Merchants can log in to the merchant portal and generate or reset keys in "Development Parameters".

Make sure to distinguish between the test environment and the production environment. Keys from different environments cannot be used interchangeably.

2. How do I add a callback URL?

Checus supports two ways to configure a callback URL:

1. An operator with development-parameter permission, or a super administrator, can configure the callback URL in "Development Parameters" in the merchant portal.
2. The merchant can pass the callback URL when creating an order.

If the callback URL passed in the API request is different from the callback URL configured in the merchant portal, the callback URL passed in the API request takes precedence.

3. Why did I not receive a callback notification?

Check the following items in order:

1. Whether a callback URL has been configured.
2. Whether the callback URL is correct.
3. Whether the callback URL can be accessed from the public network.
4. Whether the merchant server has an IP allowlist; if yes, add the Checus callback server IPs to the allowlist.
5. Whether the merchant server returns the response content required by Checus.

If all the above configurations are correct but no callback is received, contact the Checus platform for assistance.