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

Web/WAP

In this topic, you will learn how to integrate the APM SDK into a web or WAP client, allowing you to render cashier pages in computer and mobile browsers.

 

Prerequisites

Before the integration, ensure that you have completed the following tasks:

  • Install npm (Node Package Manager).
  • Properly handle compatibility issues: Provide corresponding polyfills for Internet Explorer and other old browser versions. We recommend that you use babel-preset-env to address browser compatibility issues when you build a project.
  • Use the following recommended browser versions:
    • For mobile browsers:
      • iOS 11 and later
      • Android 5.0 and later
    • For computer browsers, use the following recommended versions:

imageEdge

  Lastest 2 versions

imageFirefox

 Lastest 2 versions

imageChrome

 Lastest 2 versions

imageSafari

 Lastest 2 versions

imageOpera

 Lastest 2 versions

imageElectron

 Last 2 versions

Key integration steps

Integrate the SDK by following these steps:

1

Integrate the SDK package

Merchant client

To integrate the SDK package, please refer to Integrate the SDK Package for Web/WAP.

 

2

Create the SDK instance by using the AMSCashierPayment

Merchant client
  • Create a config object: Required. The object must contain all of the following configuration parameters:
    • locale: Optional. String type. It is used to pass in language information. Valid values are listed as follows. You can choose the value to pass based on the region of the payment method. If other values are passed, English is used by default:
      • en_US: English
      • pt_BR: Portuguese
      • ko_KR: Korean
      • es_ES: Spanish
      • fr_FR: French
      • nl_NL: Dutch
      • it_IT: Italian
      • de_DE: German
      • zh_CN: Simplified Chinese
      • zh_HK: Traditional Chinese
      • ms_MY: Malay
      • vi_VN: Vietnamese
      • in_ID: Indonesian
      • th_TH: Thai
    • environment: Required string. It is used to pass in environmental information. Valid values are:
      • sandbox: Sandbox environment
      • prod: Production environment
    • analytics: Optional object. It is used to configure and analyze data. It contains a value below:
      • enabled: Optional Boolean. It defaults to true, which indicates that you allow the SDK to upload and analyze operational data to deliver a better service. If you do not allow the data to be uploaded and analyzed, specify it as false.
    • onLog: Optional. It is a callback method that is used to generate the error information about logs and API exceptions during the execution of the SDK.
    • onError: Optional. Triggered when an error occurs during SDK usage (initialization exception, network timeout, etc.). Refer to the References for more details.
    • onEventCallback: Required. A callback function that returns a specific event code when a payment event occurs during the runtime of the SDK, such as payment result, payment cancellation. Refer to the References for more details.
  • Instantiate AMSCashierPayment.

Note: The environment set by environment should be consistent with the environment in which you call the createPaymentSession API in step 3.

Obtain the browser language.
Javascript
Editor
Create an SDK instance.
npm
CDN
Editor
3

Initiate a createPaymentSession request

Merchant server

The merchant client monitors the click events of the Payment button itself. When the buyer selects the card payment method and clicks the Payment button, the merchant client initiates createPaymentSession request to the APO server. Once the response to the createPaymentSession request is received, the paymentSessionData value in the response is used in Step 4.

createPaymentSession request
JSON
Editor
4

Create a payment component using the createComponent method in the instance object

Merchant client
  • Create a configuration object using the sessionData parameter: Pass in the complete data of the paymentSessionData field obtained in the response of the createPaymentSession request into the sessionData parameter.
  • Call the createComponent() method in the instance object, returning a Promise with the component instance object obtained using this method. The payment block DOM node can render a pop-up view on the current page based on parameters.
    • appearance: Optional. Object type for customized appearance theme configuration, and it contains the following parameters:
      • showLoading: Optional. Boolean type. The default value is true, which shows the default loading animation. If you don't use the default loading animation, you need to specify this value as false.

  • Free resources of the SDK component by calling the unmount() method in the instance object. You need to unmount a component in the following cases:

    • When the user exits the checkout page, free the component resources created in the createPaymentSession.
    • When the user initiates multiple payments, free the component resources created in the previous createPaymentSession.
Call the createComponent() method
Javascript
Editor
5

Display payment events and payment results

Merchant client

Payment events:

Implement the onEventCallback function to listen for payment events. Pay attention to the following event codes for further actions:

  • When showLoading in step 4 is false, you receive the following event codes:
    • SDK_START_OF_LOADING: display a custom loading animation.
    • SDK_END_OF_LOADING: end the custom loading animation.
  • When a user exits the payment page without submitting an order, you receive the following event code:
    • SDK_PAYMENT_CANCEL: Guide the user to retry the payment.

 

Payment results:

  • Redirect payment: After the payment flow completes, users are redirected to the provided callback URL. Guide users through the next steps on the redirected page.
  • Non-redirect payment: The non-redirect payment return event codes related to the payment results. Handle different payment results based on the following event codes:
    • SDK_PAYMENT_SUCCESSFUL: Payment was successful. Suggest redirecting users to the payment result page.
    • SDK_PAYMENT_FAIL: Payment failed. We suggest that you check the value of paymentResultCode in the onEventCallback result data for details. Guide users to retry the payment based on the provided information.
    • SDK_PAYMENT_ERROR: The payment status was abnormal. We suggest that you check the value of paymentResultCode in the onEventCallback result data for details. Guide users to retry the payment based on the provided information.
    • SDK_PAYMENT_PROCESSING: Payment was being processed. We suggest that you check the value of paymentResultCode in the onEventCallback result data for details. Guide users to retry the payment based on the provided information.

Note: The payment results displayed on the frontend are for informational purposes only. Verify the final order status on the server-side.

Implement the onEventCallback function
JavaScript
Editor
Result data
Payment successful
Payment failed
Editor
References

The References offer callback event codes and integration key step code examples. For further details, please refer to the References.