Web/WAP

You can use one of the following methods to add an SDK package:

• Use the npm package manager: enter the install command in the command line interface.
• Use CDN resources: use the <script> tag in an HTML file.

1. 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 specifies the browser's multilingual information. The SDK provides corresponding language pages based on this information. Valid values are listed as follows. If any other values are specified, English will be used as the default language:

     • en_US: English

     • pt_BR: Portuguese

     • ko_KR: Korean

     • es_ES: Spanish

   • environment: A Required string used to specify environmental information. Valid values are:
     • sandbox: sandbox environment
     • prod: production environment
   • analytics: An optional object used to configure and analyze data and contains the following value:
     • enabled: An 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, set it as false.
   • onLog: Optional. It is a callback method that is used to generate the error information about log and API exceptions during the execution of the SDK.
   • onEventCallback: Optional. A callback function returns a specific event code when a payment event happens during SDK runtime, like payment result or a form submission error. For further information, please refer to the References.
   • onError: Optional. Triggered when an error occurs during SDK usage (initialization exception, network timeout, etc.). Refer to the SDK error code for more details.
2. Instantiate the AMSCashierPayment method.

For the buyer's unbound card payment and the token payment mode after the card has been bound, 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. After monitoring the buyer’s choice of card payment method, the merchant server initiates a createPaymentSession request to the Alipay server.

Once the response to the createPaymentSession request is received, use the value of paymentSessionData 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 checkout button. When the buyer selects the payment method and clicks the card binding button, the merchant server initiates the createPaymentSession request to the Alipay server.

In card token mode, you need to specify the paymentMethod.paymentMethodId field to the card token returned to you by Alipay after the buyer binds the card. Obtain the card token through the paymentResultInfo.cardToken field in the payment result notification sent to you by Alipay or the response to actively query the payment result.

Once the response to the createPaymentSession request is received, use the value of paymentSessionData in Step 4.

• Create a configuration object using the sessionData parameter: Specify 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 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.
  • appearance: Optional. Object type for customized appearance theme configuration, and it contains the following child 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, 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. 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, refer to the results returned by the server's notifyPayment or inquiryPayment API.
• Call 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 specify pre-collected billing address information for AVS validation, you can configure the following parameters to be specified via the submit method.
  • billingAddress: Optional Object. Billing address information is used to identify and locate the user. It contains the following parameters:
    • region: Required. String (2). ISO 3166 compliant 2-digit country code.
    • state: Optional. String (8). The name of the state, country, or province.
    • city: Optional. String (32). Name of the city, region, suburb, town or village.
    • address1: Optional. String (256). Address line 1, e.g., street address, P.O. Box, and company name.
    • address2: Optional. String (256). Address line 2, e.g., apartment, suite, unit, and building information.
    • zipCode: Optional. String (32). Zip code.
• Recycle resources of the SDK component by calling the unmount method in the instance object. You need to call the method 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.