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 card payment SDK into a web or WAP client so that you can render cashier pages in a computer browser or a mobile browser.

Prerequisites

Before integrating the card payment SDK, familiarize yourself with the Integration guide and Overview. This will enable you to understand the steps for integrating server APIs and notes for calling the APIs. Also, ensure that you have completed the following tasks:

  • Obtain a client ID.
  • Properly configure keys.
  • Configure a URL for receiving an asynchronous notification.
  • 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 9 and above
      • Android 5.0 and above
    • For computer browsers, use the following recommended versions:

卡支付 SDK 集成
Edge

 

卡支付 SDK 集成
Firefox

Last 2 versions

卡支付 SDK 集成
Chrome

Last 2 versions

卡支付 SDK 集成
Safari

Last 2 versions

卡支付 SDK 集成
Opera

Last 2 versions

卡支付 SDK 集成
Electron

Last 2 versions
Key Integration steps

Integrate the card payment SDK by following these steps:

1

Import the SDK package

Merchant client

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

  • Import the Web SDK package into your project by using npm: Input the install command in the command line interface.
  • Use CDN resources: Use the script tag in a HTML file.
Add the SDK package by using npm.
Shell
Editor
Add the SDK package by using CDN resources.
HTML
Editor
2

Create an SDK instance by using the AMSCheckout()method:

 

Merchant client
  1. Create a config object: Required. The object must contain all of the following configuration parameters:
    • locale: An optional string. It is used to pass in language information. Valid values are listed as follows. If other values are passed, English is used by default:

      • en_US: English

      • pt_BR: Portuguese

      • ko_KR: Korean

      • es_ES: Spanish

    • environment: A required string. It is used to pass in environmental information. Valid values are:
      • sandbox: sandbox environment
      • prod: production environment
    • mode: A required string. It is used to specify the display mode of the cashier page. A valid value is:
      • component: used to display pre-built payment method components in your application.
    • networkMode: A required string. It is used to specify a network mode. A valid value is:
      • session: In this mode, your server only needs to send a request through the createPaymentSession API once to communicate the payment data between your client and the Alipay server.
    • analytics: an optional object. It is used to configure and analyze data. It contains the 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, specify it as false.
    • onLog: Optional. It is a callback function that is used to generate the error information about log and API exceptions during the execution of the SDK.
    • onEventCallback: Optional. It is a callback function that is used to generate the end event about payment exceptions during the execution of the SDK, such as a payment failure and a 3D verification failure.
  2. Instantiate the AMSCheckout method.
Obtain the browser language.
Javascript
Editor
Create an SDK instance.
npm
CDN
Editor
3

Send a createPaymentSession request to the Alipay server.

Merchant client

After the buyer selects a card payment method for payment, your client starts monitoring the payment button click event. When your client detects that the payment button is clicked, your server needs to send a createPaymentSession request. After you receive the response from the API call, use the value of the paymentSessionData parameter to complete Step 4.

The following sample for calling the createPaymentSession API includes mandatory parameters and several optional parameters.
JSON
Editor
The response sample of the API call is shown as follows:
JSON
Editor
4

Create a component for collecting payment factors by using the createComponent method in the instantiated object:

    Merchant client
    1. Create a configuration object by using the paymentSessionData parameter: Pass the complete data in the paymentSessionData parameter obtained in the response through the createPaymentSession API to the paymentSessionData parameter.
    2. Call the createComponent method in the instantiated object. The return value is Promise, and the content is the instantiated object. The DOM node in the payment component can render the card payment methods according to the environmental parameters and display them on the current page.
    Call the createComponent method:
    JavaScript
    Editor
    Event codes

    The card payment SDK provides the following event codes:

    • SDK_INTERNAL_ERROR: represents one of the following cases:
      • The data returned from the server does not follow JSON format. Contact Alipay Technical Support for help.
      • The browser does not support the postMessage communication mode. Replace or update the browser.
      • The iFrame element cannot be created. Replace or update the browser, or try again later.
    • SDK_INIT_PARAMETER_ERROR: represents one of the following cases:
      • The environmental information passed during initialization is incorrect. Check the value of the environment parameter.
      • The mode information passed during initialization is incorrect. Check the value of the mode parameter.
      • The language information passed during initialization is incorrect. Check the value of the local parameter.
      • The network information passed during initialization is incorrect. Check the value of the networkMode parameter.
      • The onlog method passed during initialization is incorrect. Check whether onlog is a method.
    • SDK_CREATECOMPONENT_ERROR: The card component failed to be created. Use the correct parameters to call the createComponent method again.
    Code sample in key steps

    The following code sample shows the key steps during integration. The sample does not include the code used for calling the createPaymentSession API.

    npm
    CDN
    Editor