Skip to main content

Set up Alipay payment methods with Zuora JavaScript SDK

Zuora

Set up Alipay payment methods with Zuora JavaScript SDK

This article describes how to set up Alipay payment methods by integrating with a JavaScript SDK provided by Zuora. With this integration, Zuora renders the Alipay button in an iFrame. After the end user clicks the button, a QR code is displayed and the end user follows the instructions on the page to complete the authorization. A token is returned to Zuora. Zuora stores the token and uses it to create an Apliay payment method in Zuora.

The created Alipay payment method can be retrieved through the Zuora UI and API operations. You can also retrieve the following token information in the Electronic Payment Methods section of the customer account page. Token ID will be used in subsequent recurring payments.

Zuora UI field Zuora API field Value
Token ID paymentMethodId The access token obtained from applyToken.

Alipay Auto Debit does not support one-time payments. To handle one-time payments, you must implement your custom solution for processing one-time payments after the end user completes the authorization and a payment token is returned by Alipay.

If the Alipay payment method is deleted or closed in Zuora, Zuora sends the token to Alipay and Alipay will revoke the token.

Complete the following tasks to implement the integration:

  1. Complete prerequisite tasks.
  2. Implement the client-side SDK integration.
  3. Implement the server-side API integration.
  4. Perform integration testing.

Complete prerequisite tasks

  1. Turn on the Payment Form feature.

    The JavaScript SDK integration utilizes the publishable key from the Payment Form feature for authentication. To enable Payment Form on your tenant, see the "Before you start" section in Configure payment forms.

  2. Configure an Alipay payment gateway instance.

    Ensure that an Alipay payment gateway instance has been created and is active on your Zuora tenant.

  3. Enable the Alipay payment method type.

    In the Zuora UI, enable the Alipay payment method type. See Activate payment methods for instructions.

Implement the client-side SDK integration

Step 1. Load zuora.js

Import the Zuora JavaScript client library to your page.

For sandbox environments, use <script src="https://js.zuora.com/payment/sandbox/1.4.0/zuora.js"></script>.

For production environments, use <script src="https://js.zuora.com/payment/1.4.0/zuora.js"></script>.

Step 2. Create a container

Create a container for the Alipay button on your page and place it where you want the button to be rendered. Replace alipay-button-container with the ID you want to use.

<div id="alipay-button-container">
<!-- The Alipay button will be inserted here. -->
</div>

Step 3. Render the Alipay button

  1. Copy the publishable key from Payment Form. In the Zuora UI, click your username in the upper right and navigate to Settings > Payments > Payment Form. On the Publishable Keys tab, copy the key.
  2. Initialize an instance of the Zuora object with your publishable key.
  3. Populate the payment request parameters and generate a payment session when the end customers click the button. The following table describes the payment request parameters:
    Parameter Type Description
    buttonHeight string

    Optional.

    The button height in pixels, such as 100px.

    buttonWidth string

    Optional.

    The button width in pixels, such as 100px.

  4. Mount the button component to the container.
  5. Handle the payment result.  

Here is an example of the code implementation:

<script>
    const publishableKey = "pk_rO0AB…";
    
    const renderForm = () => {
      const zuora = Zuora(publishableKey);
      zuora.createAlipayButton({
        buttonWidth: "300px",
        createPaymentSession: () => {
          return new Promise((resolve, reject) => {
            fetch("/sdk-test/payment-session.json?seed=" + Math.random(), {
              method: "GET",
            }).then((response) => {
              if (response.ok) {
                return response.json();
              } else {
                return reject("Payment session request is rejected.");
              }
            }).then((data) => {
              return resolve(data.token);
            }).catch((error) => {
              return reject(error);
            });
          });
        },
        onComplete: (result) => {
          console.log("==========");
          console.log("Payment Result");
          console.log("==========");
          console.log(`transaction result: ${JSON.stringify(result)}`);
          alert(`transaction result: ${JSON.stringify(result)}`);
        }
      }).then(function(alipayButton) {
        alipayButton.mount("#payment-form-container")
      }).catch(function(error) {
        console.error(error);
      });
    }

    function resultMessage(message) {
        const container = document.querySelector("#result-message");
        container.innerHTML = message;
      }
  </script>

Implement the server-side API integration to create payment session

In your server, make an API request to the Create a payment session endpoint. 

Because only the payment method creation flow is supported, specify the following required fields in the API request:

  • processPayment: false
  • storePaymentMethod: true
  • amount
  • currency

For details about the API request parameters, see Create a payment session in the API Reference.

Perform integration testing

In client code, make a call to your backend API to create a payment session.