Integrating GCash on mobile applications

Overview

GCash requires customers to complete payment inside the GCash mobile app, using multi-factor authentication. On mobile web (browser), this happens automatically — the browser intercepts the gcash:// redirect and opens the GCash app.

Inside a native mobile app, however, the WebView that loads PayMongo's redirect URL does not handle gcash:// deep links by default. The "Open in GCash" button will appear but do nothing when tapped — the customer cannot complete payment.

To fix this, you need to intercept URL loading in your WebView and manually open the GCash deep link using the OS's app-opening mechanism.

What changes in the checkout flow

Desktop — Shows a QR code. Customer scans with any banking app. No deep link needed.

Mobile browser — Shows QR code plus an "Open in GCash" button. Browser handles the gcash:// redirect automatically.

Mobile app (your case) — Shows QR code plus "Open in GCash" button. Without deep link handling, the button does nothing. With it, tapping opens GCash directly.

Android implementation (Java)

Override shouldOverrideUrlLoading in your WebViewClient to intercept the GCash deep link:

webView.setWebViewClient(new WebViewClient() {
    @Override
    public boolean shouldOverrideUrlLoading(WebView view, String url) {
        if (url.startsWith("gcash://")) {
            Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url));
            startActivity(intent);
            return true;
        }
        return false;
    }
});

When the URL starts with gcash://, create an Intent with ACTION_VIEW and the parsed URI, start the activity, and return true to prevent the WebView from trying to load the URL itself.

iOS implementation (Objective-C)

Set your WebView's navigation delegate and handle policy decisions:

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

    NSURL *url = navigationAction.request.URL;

    if ([url.scheme isEqualToString:@"gcash"]) {
        if (@available(iOS 10.0, *)) {
            [[UIApplication sharedApplication] openURL:url
                                               options:@{}
                                     completionHandler:nil];
        } else {
            [[UIApplication sharedApplication] openURL:url];
        }
        decisionHandler(WKNavigationActionPolicyCancel);
        return;
    }

    decisionHandler(WKNavigationActionPolicyAllow);
}

Check if the navigation URL's scheme is gcash://. If so, use UIApplication to open it and cancel the WebView navigation. Otherwise, allow the navigation to proceed normally.

React Native

React Native developers should consult the React Native deep linking documentation to handle gcash:// scheme navigation. Official GCash guidance for React Native is pending.

Important notes

• QR code payments are not affected — customers can still pay via QR even without deep link implementation
• No customer funds are at risk if deep links are not implemented — the "Open in GCash" button won't work
• This implementation is specific to native mobile apps — browser-based integrations handle deep links automatically
• This guide covers GCash. Other e-wallets (Maya, GrabPay, ShopeePay) use standard web redirects and do not currently require deep link handling