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

Web/WAP

In this topic, you'll learn how to integrate the embedded payment experience SDK into a web or WAP client, and it will allow you to render cashier pages in a computer browser or a mobile browser.

 

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 an 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. The merchant client recognizes the language type used by the user's browser and passes in the browser's multilingual information. The SDK provides corresponding language pages based on this information. Valid values are listed as follows. If other values are passed, English is used by default:
      • en_US: English
      • es_ES: Spanish
      • fr_FR: French
      • nl_NL: Dutch
      • it_IT: Italian
      • de_DE: German
      • zh_CN: Simplified Chinese
    • 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 the following value:
      • 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.
    • onEventCallback: Optional. A callback function that returns various types of data or values, including event codes, cardPaymentResultInfo parameter for card payment, and popRiskDecisionResultInfo parameter for risk control. See the References for further information.
    • onError: Optional. Triggered when an error occurs during SDK usage (initialization exception, network timeout, etc.). Refer to the error codes in the References.
  • 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 for npm package importing method and CDN package importing method:
npm
CDN
Editor
3

Initiate a createPaymentSession request

Merchant server

For the buyer's unbound card payment and the token payment mode after the card has been bound, please operate them separately as follows:

Unbound card mode:

If the buyer is not bound to a bank card, your client needs to monitor the buyer's card payment method selection event on its own. After monitoring the buyer’s choice of card payment method, the merchant client initiates a createPaymentSession request to the POP server. Once the response to the createPaymentSession request is received, the paymentSessionData value in the response is used in Step 4.

 

Card token mode:

After the buyer selects the bound card payment method as the payment method, your client monitors the click event of the payment button. When the buyer selects the payment method and clicks the card binding button, the merchant client initiates the createPaymentSession request to the POP server. In card token mode, you need to pass in the paymentMethod.paymentMethodId field to the card token returned to you by POP after the buyer binds the card. The method of obtaining the card token is as follows:

  • Independent card binding: Obtain the card token through the card.cardToken field in the asset binding result notification sent to you by POP.
  • Non-independent card binding: Obtain the card token through the paymentResultInfo.cardToken field in the payment result notification sent to you by POP or the response to actively query the payment result.

Once the response to the createPaymentSession request is received, the paymentSessionData value in the response is used in Step 4 。

The following createPaymentSession request examples only include the required fields and some optional fields:
JSON: No card bound
JSON: Token payment
Editor
Response example for createPaymentSession request:
JSON
Editor
4

Create a payment element collection component using the mountComponent method in the instance object:

Merchant client
  • Create a configuration object using the sessionData parameter: Pass the complete data of the paymentSessionData field obtained in the response of the createPaymentSession request into the sessionData parameter.
  • Call the mountComponent() method in the instance object, returning a Promise with the component instance object obtained using this method. The Payment Block DOM node renders the Binding Elements collection view based on the environment parameters and inserts it into the current page. You can configure the following parameters。
    • appearance: Optional. Object type for customized appearance theme configuration, and 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.
      • showSubmitButton: Optional. Boolean type. The default value is false, which indicates that the payment button for component rendering is not enabled. If the value is false, then the submit method of the instance object should be called to trigger the submit button process.
    • notRedirectAfterComplete: Optional, Boolean type. The default value is false, which means it will redirect back to your page after the payment is completed. The same applies when the value is empty. true value means there will be no redirect after the payment is completed. You need to use the customer event code to control the card binding to complete the subsequent process. Please note that the payment result event code returned by the client is only used as a reference for the redirect operation of the client page. For transaction status updates, please refer to the results returned by the server's notifyPayment or inquiryPayment API.
    • merchantAppointmentParam: Optional object used for setting custom features. It contains a value below:
      • storedCard: Optional object used for setting custom features of stored cards. It contains a value below:
        • ​​needCVV: Optional Boolean. The default value is false, which indicates that the user do not need to input CVV number during the payment process. The same applies when the value is empty. true value means the user need to input CVV number during the payment process.
  • Calling the submit() method triggers the card-binding submission process, and the return value is a Promise that returns a specific event code. These event codes are also returned by events such as onError or onEventCallback.
  • If you need to pass in pre-collected billing address information for AVS validation, you can configure the following parameters to be passed in via the submit method.
    • billingAddress: Optional Object. Billing address information is used to identify and locate the payer. It contains the following parameters:
      • region: Required. String (2). ISO 3166 compliant 2-digit country code.
      • zipCode: Optional. String (32). Zip code.
      • address2: Optional. String (256). Address line 2, e.g., apartment, suite, unit, and building information.
      • address1: Optional. String (256). Address line 1, e.g., street address, P.O. Box, and company name.
      • city: Optional. String (32). Name of the city, region, suburb, town or village.
      • state: Optional. String (8). The name of the state, country, or province.
  • 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 switches views to exit 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.
    • When the user completes the payment and sets notRedirectAfterComplete to true, free the component resources after obtaining specific payment result codes.
Call the createComponent()
Javascript
Editor
References

The References offers callback data and code samples for integration steps. For further details, refer to the References.