Handle GCash Deep Links

Deep Link Integration Guide for App-Based Merchants

Overview

GCash has introduced enhancements to their Online Payment experience that requires users to complete payments through the GCash mobile application. This new flow enhances security and supports a more seamless mobile checkout.

Key updates include:
All transactions must be completed in the GCash app. Multi-factor authentication (e.g., OTP, MPIN, Face Scan) is now required during checkout.

🚧

Integration with PayMongo remains the same. The update only impacts how users are redirected upon loading the GCash checkout page.

Non-App Based Merchants

✅ No changes needed.
Mobile browsers will handle the GCash deep link automatically.

App-Based Merchants (Android & iOS)

❗Code changes are required to handle and support the GCash deep link (gcash://) and enable smooth redirection of users.

Definition of Terms

Deep Link - a special type of URL that opens a specific app and screen directly, rather than a webpage.

New GCash Checkout Flow Behavior

Desktop Users

  • GCash Checkout displays a QR code.
  • Users can scan the QR code using the GCash app to complete the payment.

Mobile Users

  • GCash Checkout shows:
    • A QR code, and
    • An “Open in GCash” button (this button uses a deep link to redirect users to the GCash app).
  • Clicking the “Open in GCash” button redirects the User directly to the GCash app to complete the payment.

Implementation

Android App Changes

public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request)
 {
    String url = request.getUrl().toString();
    // Use gcash:// on production and sit environment
    if (url.startsWith("gcash://")) {
        val i = Intent(Intent.ACTION_VIEW);
        i.data = Uri.parse(url);
        startActivity(i);
        return true; // Let the WebView handle the URL normally
    } else {
        // Use existing logic
        return false; // Allow the WebView in your application to do its thing
    }
}

iOS App Changes

- (void)viewDidLoad {
    self.webView.navigationDelegate = self;
}

- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {
    NSString *scheme = [webView.URL scheme];
    NSString *query = [webView.URL query];
    NSURL *directUrl;

    if (scheme) {
        if ([scheme isEqualToString:@"gcash://"]) {
            // Scheme URL
            directUrl = webView.URL;
        }
    }

    if (directUrl) {
        UIApplication *application = [UIApplication sharedApplication];
        // Scheme
        if (@available(iOS 10.0, *)) {
            [application openURL:[NSURL URLWithString:targetUrl] options:@{} completionHandler:^(BOOL success) {
                if (success) {
                    // do something.
                }
            }];
        } else {
            [application openURL:[NSURL URLWithString:targetUrl]];
        }
    }

    decisionHandler(WKNavigationActionPolicyAllow);
}

Frequently Asked Questions

  1. What happens if I don’t implement this in time?

You can still accept payments via QR code, but the “Open in GCash” button won’t work properly in your app (it may do nothing or show an error). No customer funds will be affected.

  1. What if I’m using React Native?

GCash has not provided official guidance yet for other languages or frameworks. We recommend reviewing the following resources:

React Navigation: Deep Linking
React Native: Linking

This page will be updated once GCash provides more official code samples.