This document provides an integration guideline for seamless redirection between merchants and wallets. To achieve a seamless redirection between merchants and wallets, understand the differences between different terminal types and follow the integration guide provided in this document to keep redirection successful.

The redirection for a merchant's terminal type of APP is the most complex case, therefore, this document explains only this case. The merchant needs to get authUrl by calling the consult interface and ensure a successful redirection from the merchant side to the wallet side by opening authUrl. This document provides demo codes to facilitate the redirection process. The demo code applies for iOS 9.2 or later and Android 6.0 or later.

Terms and definitions

The following terms and definitions are used in this document.

Table 1. Terms and definitions

Authorization URL

To arrive at the wallet's authorization page, redirect the user to the address specified by authUrl. The value of authUrl is obtained from the consult interface's response.

The following table shows the type of authUrl for each digital wallet and the subsequent redirection experience.

• If the wallet specifies the authUrl to be opened by browser, including default browser, webview, and others, the redirection experience is the same no matter whether the user has installed the wallet.
• If the wallet doesn't specify that the authUrl needs to be opened by the browser, the redirection experience depends on whether the user has installed the wallet.

Table 2. authUrl type for each digital wallet and corresponding user experience

Notes:

• Universal Links (iOS) and App Links (Android) are abbreviated as UL/AL.
• Three types of redirection experience might be encountered when redirecting to the wallet's authorization page:

• Wallet app: The user opens the authorization page in the wallet app. This type is not supported by Dana.
• WAP authorization page: The user enters an account in the authorization page opened by the browser, instead of opening the authorization page in the wallet app. This type is not supported by TrueMoney and KakaoPay.
• Wallet downloading WAP page: The user is redirected to a WAP page for downloading the wallet's app. This type of page is opened by the browser by TrueMoney and KakaoPay when the user doesn't install the wallet app.

Integration methods

There are three possible ways to make redirection from the merchant side to the wallet side:

• Jump out and open: Jump out of the merchant app and open the wallet app
• Stay in and open: Open the wallet page in the merchant app
• Determine by case: Check whether the user has installed the wallet app and then choose the corresponding solutions:

• If the user has installed the wallet app, use the Jump-out-and-open solution.
• If the user doesn't install the wallet app, use the Stay-in-and-open solution.

Each way has its benefits and drawbacks. Select the way wisely according to your preference.

Jump out and open Recommended

To complete the client integration from the merchant app to the wallet at the lowest cost, it is recommended to use this method to make redirection: Jump out of the merchant app, and provide the authUrl to the application system to open the wallet.

Benefits:

• High compatibility. Different types of authUrl that are provided by different wallets can be compatible. For example, the authUrl type of Dana is WAP, KaKaoPay is WAP-Scheme, while others are UL/AL.
• Easy integration. No need to consider whether the user has installed the wallet app when making redirection.
• No additional customization. Compatible with new wallets to join in the future.

Drawbacks:

• Poor user experience for some wallets. The authorization process needs to be completed out of the merchant app. For example, Dana can only provide a WAP authorization page opened by an external browser instead of opening the authorization page in the wallet app.
• When the user does not install the wallet app, some wallets such as Gcash, Touch'n go and AlipayHK will present a WAP authorization page. The WAP authorization page is opened by the default browser instead of in the merchant app.

This solution is supported by the following wallets:

Table 3. Supported wallets

Demo code

In the Android app

The following demo code shows redirection from the merchant to the wallet in an Android app:

try {
    Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(authUrl));
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); 
    // use startActivity function redirect to wallet app 
    startActivity(intent);
} catch (Exception e) {
    e.printStackTrace();
}

In the iOS app

The following demo code shows redirection from the merchant to the wallet in an iOS app:

if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 10.0) {
     // use openURL function redirect to wallet app 
    [[UIApplication sharedApplication] openURL:[NSURL URLWithString:authUrl] options:@{} completionHandler:nil];
}else{
     // use openURL function redirect to wallet app 
    [[UIApplication sharedApplication] openURL:[NSURL URLWithString:authUrl]];
}

User experience

The user has installed the wallet app

In this case, the wallet app is opened. Only Dana doesn't support opening the wallet app.

Table 4. User experience when the wallet app is installed

The user does not install the wallet app

In this case, the authorization page, or wallet download page is opened by the default browser. One of the following types of WAP page is provided for different wallets:

• A WAP wallet download page
• A WAP authorization page

The following table shows the two types of WAP pages for each wallet:

Table 5. User experience when the wallet app is not installed

Notes:

• For each wallet, the user experiences of downloading the wallet app vary for different types of mobile phones, operation systems, and browsers used to open the WAP page. For example, the user might be redirected to the Google Play app store after choosing to download the wallet app, or be redirected automatically to the manufacturer-specific App Stores.
• For AlipayHK, when the user doesn't install the wallet app, a wallet download WAP page will be opened by all the browsers except Chrome. When the default browser of the user's mobile phone is Chrome, the system automatically redirects to the Google Play download page and closes the default browser in the meanwhile. In this case, the user cannot choose to send the verification code on the WAP authorization page by entering the account. The user experience is shown below:

Disambiguation dialog handling

This section is only needed for an Android system and when the user has installed the wallet app.

App Links ask the Google server for authentication when installing the application. If the authentication fails, App Links will become invalid. In this case, a disambiguation dialog appears when the user opens an application through such a link, and the user needs to manually select how to open an application.
Note: The iOS system does not have the disambiguation dialog handling problem.

When a disambiguation dialog appears, the user needs to manually make a selection, which will impact the authorization success rate. Therefore, it is suggested to avoid the appearance of the disambiguation dialog by taking the following actions:

• For users that have installed the wallet app, specify the wallet's packageName to open the wallet URL.
• For users that have not installed the wallet app, use the following demo code to realize a jump-out-and-open redirection:

Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(authUrl));
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); 
//set wallet package name
intent.setPackage(walletPackageName);
PackageManager packageManager = MainActivity.this.getPackageManager();
// Retrieve all activities that can be performed for the given intent.
List<ResolveInfo> activities = packageManager.queryIntentActivities(intent, 0);
if (activities.size() <= 0) {
   // The wallet app is not installed. Reinitialize the Intent. Use the system method to open the app. Redirect to the default browser.
   intent = new Intent(Intent.ACTION_VIEW, Uri.parse(authUrl));
   intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
     startActivity(intent);
} else {
  // The wallet app is installed. Open the wallet url by specified walletPackageName. The disambiguation dialog does not appear.
     startActivity(intent);
}

Note: The following list shows packageName value for each wallet:

• AlipayCN: com.eg.android.AlipayGphone
• AlipayHK: hk.alipay.wallet
• GCash: com.globe.gcash.android
• TrueMoney: th.co.truemoney.wallet
• KakaoPay: com.kakao.talk
• Touch'n Go: my.com.tngdigital.ewallet
• Dana: id.dana

The following table takes Touch'n Go as an example to show the user experience with and without the disambiguation dialog.

Table 6. The user experience with and without the disambiguation dialog.

Intermediate page handling

If the type of authUrl is WAP-Scheme, the user will be redirected to the intermediate page opened by the default browser first, then redirected to the wallet app. The following table shows an example of KakaoPay:

Table 7. Intermediate page of KakaoPay

For a better user experience, it is recommended to use the app's embedded browser to load the WAP page first, then redirect the user to the wallet app by scheme. Therefore, the user is directly redirected to the wallet app without redirecting the default browser. See the following sample codes for details.

In the iOS app

The following demo code shows how to use SFSafariViewController to load the WAP page in an iOS app:

if (@available(iOS 11.0, *)) {
        SFSafariViewControllerConfiguration *configuration =  [[SFSafariViewControllerConfiguration alloc]init];
        configuration.barCollapsingEnabled = NO;
        configuration.entersReaderIfAvailable = NO;
        //Use SFSafariViewController to open url
        SFSafariViewController *safariVC = [[SFSafariViewController alloc] initWithURL:url configuration:configuration];
        safariVC.delegate = self;
        [self.navigationController presentViewController:safariVC animated:YES completion:nil];
    } else {
        SFSafariViewController *safariVC = [[SFSafariViewController alloc] initWithURL:url entersReaderIfAvailable:NO];
        safariVC.delegate = self;
        [self.navigationController presentViewController:safariVC animated:YES completion:nil];
    }

In the Android app

The following demo code shows how to rewrite shouldOverrideUrlLoading in the webview in an Android app:

WebView webView = findViewById(R.id.webview);
WebSettings webSettings = webView.getSettings();
//Enable javascript
webSettings.setJavaScriptEnabled(true);
//Enable scaling
webSettings.setSupportZoom(true);
//Enable scaling controls (buttons)
webSettings.setBuiltInZoomControls(true);
//2 cache mode for WebView (web and WAP). Load no cache here.
webSettings.setCacheMode(WebSettings.LOAD_NO_CACHE);
//Allow JavaScript to open new windows (false by default).
webSettings.setJavaScriptCanOpenWindowsAutomatically(true);
//Allow JavaScript to load the local cache.
webSettings.setDomStorageEnabled(true);
//WAP cache size (No need to manually set)
//webSettings.setAppCacheMaxSize(1024 * 1024 * 8);
//WAP cache path
String absolutePath = getApplicationContext().getCacheDir().getAbsolutePath();
///WAP cache size
webSettings.setAppCachePath(absolutePath);
//Whether allow WebView to access files (true by default)
webSettings.setAllowFileAccess(true);
//Enable to save WAP cache
webSettings.setAppCacheEnabled(true);
//When using overview mode, if the the page width exceeds WebView dispaly, scale the page to adapt to the WebView (false by default)
webSettings.setLoadWithOverviewMode(true);
// support for the viewport HTML meta tag
webSettings.setUseWideViewPort(true);

// load the wallet authUrl 
webView.loadUrl(authUrl);
//
webView.setWebViewClient(new WebViewClient() {
    @Override
    public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
        if (request.getUrl().toString().startsWith("http")) {
            view.loadUrl(request.getUrl().toString());
            return super.shouldOverrideUrlLoading(view, request);
        }
        
        Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(request.getUrl().toString()));
        intent.setPackage(packageName);
        PackageManager packageManager = WebViewActivity.this.getPackageManager();
        List<ResolveInfo> activities = packageManager.queryIntentActivities(intent, 0);
        if (activities.size() > 0) {
           intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
             WebViewActivity.this.startActivity(intent);
            }
        return true;

});

User experience

In this case, a wallet downloading WAP page is opened by the default browser for KakaoPay with WAP-Scheme type.

Table 8. User experience of KakaoPay

Stay in and open Not recommend

If the merchant wants the user to complete the entire authorization process in the merchant app, the app's embedded browser can be used to open the authorization page. This method is not recommended.

Benefits:

• The user will not leave the merchant app during the entire authorization process.
• For the Dana wallet, which only supports a WAP authorization page, this solution can avoid the user leaving the merchant app and redirecting to an external browser.

Drawbacks:

• For wallets not support a WAP authorization page, such as KakaoPay and TrueMoney. If the merchant uses the app's embedded browser to load, a WAP page for downloading the wallet's app will be opened. The authorization cannot be completed.
• For wallets that support a WAP authorization page, such as GCash, Touch 'n Go, and AlipayHK, the authorization success rate will decrease. After the wallet is opened by an embedded browser, the user needs to enter an account in the authorization page rather than directly open the wallet app and confirm to authorize in the wallet app, which causes the loss of authorization success rate.

This solution is supported by the following wallets:

Table 9. Supported wallets

Demo code

In the iOS app

The following demo code uses WKWebView to load the wallet in the iOS app.

// initialize the webview configuration
WKWebViewConfiguration *configuration = [[WKWebViewConfiguration alloc]init];
// initialize the webView 
WKWebView *webView = [[WKWebView alloc]initWithFrame:CGRectMake(0, 0, [UIScreen mainScreen].bounds.size.width, [UIScreen mainScreen].bounds.size.height) configuration:configuration];
webView.navigationDelegate = self;
// load the wallet auth url 
[webView loadRequest:[NSURLRequest requestWithURL:[NSURL URLWithString:authUrl]]];
[self.view addSubview:self.webView];

In the Android app

The following demo code uses WebView to load the wallet in the Android app.

WebView webView = findViewById(R.id.webview);
// set the webview client 
webView.setWebViewClient(new WebViewClient() {
    @Override
    public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
        view.loadUrl(request.getUrl().toString());
        return super.shouldOverrideUrlLoading(view, request);
    }});

WebSettings webSettings = webView.getSettings();
//Enable javascript
webSettings.setJavaScriptEnabled(true);
//Enable scaling
webSettings.setSupportZoom(true);
//Enable scaling controls (buttons)
webSettings.setBuiltInZoomControls(true);
//2 cache mode for WebView (web and WAP). Load no cache here.
webSettings.setCacheMode(WebSettings.LOAD_NO_CACHE);
//Allow JavaScript to open new windows (false by default).
webSettings.setJavaScriptCanOpenWindowsAutomatically(true);
//Allow JavaScript to load the local cache.
webSettings.setDomStorageEnabled(true);
//WAP cache size (No need to manually set)
//webSettings.setAppCacheMaxSize(1024 * 1024 * 8);
//WAP cache path
String absolutePath = getApplicationContext().getCacheDir().getAbsolutePath();
///WAP cache size
webSettings.setAppCachePath(absolutePath);
//Whether allow WebView to access files (true by default)
webSettings.setAllowFileAccess(true);
//Enable to save WAP cache
webSettings.setAppCacheEnabled(true);
//When using overview mode, if the the page width exceeds WebView dispaly, scale the page to adapt to the WebView (false by default)
webSettings.setLoadWithOverviewMode(true);
// support for the viewport HTML meta tag
webSettings.setUseWideViewPort(true);


// load the wallet auth url 
webView.loadUrl(authUrl);

User experience

No matter whether the user has installed the wallet app or not, the user experience remains the same:

Table 10. User experience

Determine by case

The merchant can also determine how to make redirection based on whether the user has installed the wallet app:

• If the user has installed the wallet app: use the system method to invoke the wallet app, which means the user will jump out of the merchant app and then open the wallet app.
• If the user doesn't install the wallet app: use the embedded browser to load the WAP authorization page, which means the user will stay in the merchant app and open the wallet page in the merchant app.

Benefits

• High authorization success rate. The user will be redirected to the wallet app to authorize if the user installed the app.
• Better user experience. The user can complete the authorization in the merchant app when the user does not install the wallet app.

Drawbacks

• High development cost. The merchant needs to declare the wallet scheme (for the iOS system) or application package name (for the Android system) in the configuration file in advance to check whether the user has installed the wallet app.
• When the user does not install the wallet app:

• For wallets that cannot display WAP authorization page, such as KakaoPay and TrueMoney, there is no need to invoke the wallet in an embedded browser because the wallet doesn't support the WAP authorization page.

This solution is supported by the following wallets:

Table 11. Supported wallets

Demo code

In the iOS app

The following demo code shows how to use canOpenURL to check whether the user has installed the wallet app.

// The wallet scheme URL that the merchant registered in advance in info.plist. Here is an example of GCash.
NSString *walletSchemeUrl = @"gcash://";
// The wallet authorization link authUrl 
NSString *authUrl = @"";
// USe canOpenUrl to check whether the wallet app has installed.
if ([[UIApplication sharedApplication] canOpenURL:[NSURL URLWithString:walletSchemeUrl]]){
    // The wallet app has installed, use openUrl to invoke the wallet app.
    if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 10.0) {
        
        [[UIApplication sharedApplication] openURL:[NSURL URLWithString:authUrl] options:@{} completionHandler:nil];
    }else{
        [[UIApplication sharedApplication] openURL:[NSURL URLWithString:authUrl]];
    }
} else {
    // The wallet app has not installed, use WebView to load the wallet link.
    WKWebViewConfiguration *configuration = [[WKWebViewConfiguration alloc]init];
    // initialize the webView 
    WKWebView *webView = [[WKWebView alloc]initWithFrame:CGRectMake(0, 0, [UIScreen mainScreen].bounds.size.width, [UIScreen mainScreen].bounds.size.height) configuration:configuration];
    webView.navigationDelegate = self;
    // load the wallet auth url 
    [webView loadRequest:[NSURLRequest requestWithURL:[NSURL URLWithString:authUrl]]];
    [self.view addSubview:self.webView];
}

Note: If your app is linked on or after iOS 9.0, you must declare the URL schemes you pass to this method by adding the LSApplicationQueriesSchemes key to your app's Info.plist file. For more information, see canOpenURL:. The following figure shows the key.

Figure 1. Add the LSApplicationQueriesSchemes key

Note: The following list shows the URL schemes of each wallet:

• AlipayCN: alipays://
• AlipayHK: alipayhk://
• GCash: gcash://
• TrueMoney: ascendmoney://
• KakaoPay: kakaotalk://
• Touch'n Go: tngdwallet://

In the Android app

The following demo code shows how to use PackageManager to check whether the user has installed the wallet app.

Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(walletLink));
intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
//set wallet package name
intent.setPackage(walletPackageName);
PackageManager packageManager = MainActivity.this.getPackageManager();
List<ResolveInfo> activities = packageManager.queryIntentActivities(intent, 0);
if (activities.size() <= 0) {
    // The wallet app has not installed, use WebView to load the wallet URL.
    WebView webView = findViewById(R.id.webview);
    // set the webview client 
    webView.setWebViewClient(new WebViewClient() {
        @Override
        public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
            view.loadUrl(request.getUrl().toString());
            return super.shouldOverrideUrlLoading(view, request);
        }});
    webviewSettings(webView);
    // load the wallet auth url 
    webView.loadUrl(authUrl);
} else {
    // The wallet app has installed, use startActivity to redirect to the wallet app.
   startActivity(intent);
  
}



/**
     * Webview settings
     *
     * @param webView
     */
private void webviewSettings(WebView webView) {

    WebSettings webSettings = webView.getSettings();
    //Enable javascript
    webSettings.setJavaScriptEnabled(true);
    //Enable scaling
    webSettings.setSupportZoom(true);
    //Enable scaling controls (buttons)
    webSettings.setBuiltInZoomControls(true);
    //2 cache mode for WebView (web and WAP). Load no cache here.
    webSettings.setCacheMode(WebSettings.LOAD_NO_CACHE);
    //Allow JavaScript to open new windows (false by default).
    webSettings.setJavaScriptCanOpenWindowsAutomatically(true);
    //Allow JavaScript to load the local cache.
    webSettings.setDomStorageEnabled(true);
    //WAP cache size (No need to manually set)
    //webSettings.setAppCacheMaxSize(1024 * 1024 * 8);
    //WAP cache path
    String absolutePath = getApplicationContext().getCacheDir().getAbsolutePath();
    ///WAP cache size
    webSettings.setAppCachePath(absolutePath);
    //Whether allow WebView to access files (true by default)
    webSettings.setAllowFileAccess(true);
    //Enable to save WAP cache
    webSettings.setAppCacheEnabled(true);
    //When using overview mode, if the the page width exceeds WebView dispaly, scale the page to adapt to the WebView (false by default)
    webSettings.setLoadWithOverviewMode(true);
    //Enable to use the viewport HTML meta tag
    webSettings.setUseWideViewPort(true);
}

Note: If your app targets Android 11 or higher and needs to interact with apps other than the ones that are visible automatically, add the <queries> element in your app's manifest file. For more information, see Package visibility filtering on Android. The following sample takes AlipayHK as an example:

    <queries>
        <!-- declare the wallet packagename -->
        <package android:name="hk.alipay.wallet"/>
    </queries>

Note: The following list shows packageName value for each wallet:

• AlipayHK: hk.alipay.wallet
• GCash: com.globe.gcash.android
• TrueMoney: th.co.truemoney.wallet
• KakaoPay: com.kakao.talk
• Touch'n Go: my.com.tngdigital.ewallet
• Dana: id.dana

User experience

If the user has installed the wallet app, see Jump out and open - User experience for the user experience of each wallet. If the user doesn't install the wallet app, see Stay in and open - User experience for the user experience of each wallet.

If the wallets that provide a WAP authorization page, such as GCash, Touch'n Go and AlipayHK, different methods can be used to invoke the wallet according to whether the user has installed the wallet app:

• If the wallet app is installed, use the system method to invoke the wallet.
• If the wallet app is not installed, use the embedded browser to invoke the wallet.

Take GCash as an example, the following table shows the user experience:

Table 12. User experience