Handling GCash deep link
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.
New GCash Checkout Flow Behavior
💡 A deep link is a special type of link that opens a specific app and screen directly, rather than a webpage.
Desktop Users
- GCash Checkout displays a QR code.
- Users 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.

Integration Requirements
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.
Implementation Guide
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.
2. 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:
This page will be updated once GCash provides more official code samples.
Updated about 11 hours ago