Client side integration with wallet

    This document provides an integration guide for seamless redirection between merchants and wallets.


    #Terms and definitions

    The following terms and definitions are used in this document.

    Term

    Definition

    Merchant

    Person or institution that provides goods or services at a bilaterally agreed price.

    Payment Method Provider (PMP)

    Institution that processes payments on behalf of users.

    H5

    Merchant or PMP HTML pages, which can be opened in mobile browsers.

    APP

    Merchant or PMP app, which is an iOS App or an Android App.

    Scheme

    URL Scheme allows users to open your app from other apps by tapping a custom URL, which is not recommended by iOS and Android any more. For more information about Scheme, see Defining a URL Scheme in iOS and Creating Deep Links to App Content in Android.

    Table 1. Terms and definitions


    #Integration

    To achieve a seamless redirection between merchants and wallets, merchants need to follow best practices for integration.


    #Redirection from merchant to digital wallet

    Three payment terminals on the merchant side that digital wallets might support are:

    • Website
    • WAP (Wireless Application Protocol)
    • App


    The following table shows the payment terminals each digital wallet supports. Payment terminals that are currently not supported yet will be included in the future.

    Digital Wallet

    Auto Debit Payment

    WEB

    APP

    WAP

    GCASH




    Dana


    • 🔲

    Touch'n Go




    KakaoPay



    • 🔲

    TrueMoney



    • 🔲

    AlipayCN



    • 🔲

    AlipayHK




    bKash

    • 🔲
    • 🔲
    • 🔲

    Table 2. Payment terminals supported by each digital wallet


    Redirections from merchant to digital wallet side might involve the following terminal types:

    • APP to APP: Merchant app to digital wallet app

    (Note: If the user did not install the digital wallet app, an H5 page will be used instead.)

    • APP to WAP: Merchant app to digital wallet H5 page (WAP)

    (Note: When the user did not install the digital wallet app, this case is used.)

    • WAP to WAP: Merchant WAP to digital wallet H5 page (WAP)
    • WEB to WEB: Merchant website to digital wallet website:

    (Note: The digital wallet website might require payment password for payment or provide a QR code for customers to scan and pay.)


    #Best practice for seamless integration

    Usually, interaction between merchant website and digital wallet website can be processed smoothly. However, interaction between the merchant and digital wallet app or H5 page can sometimes be unsuccessful due to different implementation methods of the merchant and digital wallet terminals. To ensure a smooth redirection process, follow these integration best practices.


    #1. Use demo code and provide URL scheme

    Due to various reasons, redirection failure often occurs in the process of evoking the authorization page or redirecting to the merchant side. The following actions need to be taken for the corresponding process:

    • Evoke the authorization page: to avoid a failed redirection during this process, it is suggested to use Alipay demo code. For more information, see Demo code for launching a Scheme/H5-Scheme in Apps.
    • Redirect to the merchant side: to avoid a failed redirection during this process, it is suggested to provide the URL scheme or allow the H5 page to evoke the app through URL scheme (H5-Scheme). For more information, see Recommended actions for merchant to take.


    The following graphic shows an example of the two processes that often fail during a redirection between the merchant app and wallet app:

    代扣无线跳转.png

    Figure 1. Redirection between the merchant app and wallet app


    #Demo code for launching the Scheme/H5-Scheme in Apps

    In the iOS App

    The following code can be used to launch the Scheme/H5-Scheme in an iOS app:

    copy
    //url is the redirectUrl of merchant from wallet
    if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 10.0) {
        [[UIApplication sharedApplication] openURL:url options:@{} completionHandler:nil];
    }else{
        [[UIApplication sharedApplication] openURL:url];
    }

    The following sample shows a payment redirection URL:

    copy
    https://reddit.app.link/?domain=www.reddit.com&geoip_country=US&user_agent=Mozilla%2F5.0%20(Linux%3B%20Android%208.0.0%3B%20MI%205s%20Plus%20Build%2FOPR1.170623.032%3B%20wv)%20AppleWebKit%2F537.36%20(KHTML%2C%20like%20Gecko)%20Version%2F4.0%20Chrome%2F71.0.3578.99%20Mobile%20Safari%2F537.36%20MMWEBID%2F3813%20MicroMessenger%2F7.0.5.1421(0x27000540)%20Process%2Ftools%20NetType%2FWIFI%20Language%2Fzh_CN&base_url=%2F&referrer_domain=&referrer_url=&language=&dnt=false&compact_view=true&adblock=false&session_id=P8DTBHyQMksj867rgU&loid=000000000059j450lg&loid_created=1576836949648&reddaid=&utm_term=control_2&utm_medium=mweb&utm_source=xpromo&utm_name=in_feed_refresh&campaign=in_feed_refresh&channel=xpromo&feature=mweb&keyword=control_2&%24og_redirect=https%3A%2F%2Fwww.reddit.com%2F&%24deeplink_path=%2F&%24android_deeplink_path=reddit%2F&mweb_loid=000000000059j450lg&mweb_loid_created=1576836949648&mweb_user_id36=&mweb_user_name=&tags=topbutton_xpromo_listing&utm_content=topbutton_xpromo_listing&nsukey=JDVI%2F0BwufuUTFKh0GcscJ4KqnmdeBzLzfUJMgVfGHPWg0T7ywU0eFpHTN5QkeIrAO2yYgUIw4nDf1E4ctG0CyG3pXgc3BzSNL80%2FsFEkU4ZNIZAzdHjgCcXd6ouC0NGX%2F1U4osY8YSBfDpNhPhyKgZ8hego3Q%2BQ4YW2ERyP7BAjxr%2BG%2F%2FCQU%2FTgh7bnmVohJmG%2Bmrj2n7rApgXhxzbrAg%3D%3D


    In the Android App

    The following code can be used to launch the Scheme/H5-Scheme in an Android app:

    copy
    // paymentRedirectUrl is the AppLinks or Scheme of merchant or wallet
    // Solution 1:
    try {
        Intent intent = Intent.parseUri(paymentRedirectUrl, Intent.URI_INTENT_SCHEME);
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); 
        startActivity(intent);
    } catch (Exception e) {
        e.printStackTrace();
    }
    
    // Solution 2:
    try {
        Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(paymentRedirectUrl));
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); 
        startActivity(intent);
    } catch (Exception e) {
        e.printStackTrace();
    }


    #Recommended actions for merchant or acquirer to take

    The merchant needs to provide the URL scheme, an H5 redirection page, or a website redirection URL for different redirections between various terminals. The following table provides details about the recommended actions for merchants to take when processing redirections in different cases.


    If you are an acquirer that serves to help merchants integrate with Alipay, you need to ensure:

    • The merchant provides the URL scheme.
    • The local app can be opened with the address of the scheme protocol in the H5 page.

    Merchant terminal type

    Recommended actions for merchants

    The merchant terminal type is APP. terminalType=APP


    • The merchant needs to provide the URL scheme for redirection to merchant app or allow the H5 page to evoke merchant app through URL scheme (H5-Scheme).
    • The merchant needs to use the code provided by Alipay to open the app link. Do not open the link in app embedded WebView, container, or middle page.


    Note:

    If the user did not install the digital wallet app, an H5 page is triggered. The H5 page is a login page or the digital wallet app download page.

    The merchant terminal type is WAP. terminalType=WAP

    The H5 page of the digital wallet is a login page or a digital wallet download page. To successfully redirect to the H5 page of the digital wallet, the merchant needs to provide an H5 redirection page with a URL. 

    The merchant terminal type is WEB. terminalType=WEB

    The merchant needs to provide a website redirection URL.


    Note:

    The PC website can be a page that requires account and password to authorize or a page with QR code to be scanned for authorization.

    Table 3. Recommended actions to take for a seamless integration


    #2. Use sandbox to test

    In sandbox, you can download a test digital wallet to simulate the process of evoking the cashier and redirecting to the merchant side. Test wallets are provided for iOS and Android systems respectively. The download links are as follows:

    • Test wallet for the iOS system

    Download guide:https://testflight.apple.com/join/3MwgvR4k

    • Test wallet for the Android system

    Download address: Download

    Note: Alipay provides test accounts for merchants to use in the test wallet. The following table shows the details about the provided test accounts:

    Account

    Password

    amsmerchant01@163.com

    Alipay123

    amsmerchant02@163.com

    Alipay123

    amsmerchant03@163.com

    Alipay123

    amsmerchant04@163.com

    Alipay123

    amsmerchant05@163.com

    Alipay123

    amsmerchant06@163.com

    Alipay123

    amsmerchant07@163.com

    Alipay123

    amsmerchant08@163.com

    Alipay123

    amsmerchant09@163.com

    Alipay123

    amsmerchant10@163.com

    Alipay123

    Table 4. Test accounts