Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

      Client side integration with wallet

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


      #Terms and definitions

      The following terms and definitions are used in this document.

      Term

      Definition

      Merchant

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

      Alipay+ Mobile Payment Partner (Alipay+ MPP)

      An institution that processes payments on behalf of users.

      WAP

      The client-side terminal type is an HTML page that is opened via a mobile browser.

      APP

      The client-side terminal type is a mobile application.

      Scheme

      URL Scheme allows users to open a merchant's app from other apps by tapping a custom URL. However, this is not recommended by iOS and Android anymore. 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

      Cashier 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 the merchant to the 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, a WAP page, will be used instead.)

      • APP to WAP: Merchant app to digital wallet WAP page

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

      • WAP to APP: Merchant WAP page to digital wallet app

      (Note: If the user does not install the digital wallet app, a WAP page will be used instead.)

      • WAP to WAP: Merchant WAP to digital wallet WAP page
      • WEB to WEB: Merchant website to digital wallet website.

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


      #Best practice for seamless integration

      The interaction between the merchant and digital wallet's websites can usually be processed smoothly.


      The interaction between the merchant and digital wallet's apps or WAP page, however, is more complicated due to the terminals' different implementation methods. 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 when evoking the cashier's authorization page or when redirecting to the merchant side.


      Follow the corresponding actions to when failure occurs:

      • Evoking cashier's 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/WAP-Scheme in Apps.
      • Redirecting to merchant side: to avoid a failed redirection during this process, it is suggested to provide the URL scheme or allow the WAP page to evoke the app through URL scheme (WAP-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:  

      图片1.png

      Figure 1. Redirection between the merchant app and wallet app


      #Demo code for launching the Scheme/WAP-Scheme in apps

      In the iOS app

      The following code can be used to launch the Scheme/WAP-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/WAP-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 merchants and acquirers

      The merchant needs to provide the URL scheme, a WAP 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 WAP 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 WAP page to evoke merchant app through URL scheme (WAP-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 WAP page is triggered. The WAP page of the digital wallet is a login page or the digital wallet app download page.

      The merchant terminal type is WAP. terminalType=WAP

      The merchant needs to provide an WAP redirection page with a URL.


      Notes:

      • If the user has the digital wallet app, the digital wallet app will be triggered. If the user did not install the digital wallet app, the WAP page is triggered. The WAP page is a login page or the digital wallet app download page.
      • If the digital wallet app is triggered, users need to manually redirect themselves to the merchant WAP page after completing the payment process.

      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 an account and password for payment, or a page with a QR code to be scanned for payment.

      Table 3. Recommended actions 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:

      • The e-wallet simulator for the iOS system

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

      • The e-wallet simulator for the Android system

      Download address: Download

      Note: Alipay provides test accounts for merchants to use in The e-wallet simulator. 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