Skip to main content

Set up Google Pay with Zuora JavaScript SDK


Set up Google Pay with Zuora JavaScript SDK

You can add a Google Pay™ button to your checkout flow by integrating with a JavaScript SDK provided by Zuora. For now, this feature is only supported on the Stripe v2 payment gateway integration, and only CRYPTOGRAM_3DS authentication method is supported. Zuora is continuing to evaluate other payment gateways for Google Pay integration. If you have any requests on other gateways, please contact your Zuora account manager.

The Google Pay button implemented through the approach described in this document can work in Chrome browsers on Android devices.

This feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters.


The following diagram shows how the Google Pay JavaScript SDK integration works in a checkout experience:


Overall, you need to complete the following tasks to set up Google Pay by integrating with Zuora’s JavaScript SDK:

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


  • Understand the guidelines and requirements of Google Pay:
  • Ensure that the requirements for the gateway are met:
    • You have signed up for a merchant account for the gateway.
    • Contact Stripe for gated access to the Processing Google Pay Decrypted Tokens API.
  • Get your testing environment ready:
    • Chrome browser on an Android device
    • Add a card on the Android device
  • Before your Google Pay goes live, ensure that your domains have been registered with Google Pay in one of the following ways:
    • Register domains on your own by following the instructions in Google Pay documentation.
    • Contact Zuora Global Support to access Zuora’s Hosted Google Pay Checkout feature. This feature eliminates the need for you to register domains on your own. Note that this feature is in the final stage of testing and will be released soon.

Implement server-side API integration

Use the Create a payment session REST API operation to create a payment session on your server. To prevent malicious price tampering on the client side, always decide the charge amount on the server side. The response of this API operation contains a token for the payment session data. Send the token back to the client to use it in step 3 of the client-side SDK integration when initiating an instance of the Zuora object.

For details about how to construct the API request, see Create a payment session in the API Reference. You can control whether to validate payment methods only or make payments through specifying processPayment.

Here are examples of the request and response.


    "processPayment": true,
    "currency": "USD",
    "amount": "100",


Status code: 200


Implement client-side SDK integration

This section provides instructions on implementing the client-side SDK integration and a code example.


Complete the following steps to implement the JavaScript SDK integration on the client side:

Step 1. Import Zuora's JavaScript SDK

Insert the following script to your page:

<script src=""></script>

The legacy Zuora JavaScript SDK is being deprecated. It is highly suggested to use the new version

Step 2. Create a container

Create a container for the Google Pay button on your checkout page and place it where you want the payment method form to be rendered. Replace payment-request-button with the ID you want to use.


<div id="payment-request-button">
<!-- The Google Pay button will be inserted here. -->

Step 3. Initialize an instance of the Zuora object

Initialize an instance of the Zuora object with the token returned from the Create a payment session API operation. This token is required for identifying your website to Zuora.


const zuora = Zuora(token);

Step 4. Initialize and define the configuration object

Create an instance of the configuration object and define the following configuration properties and events:

  • Button style properties
  • Payment request objects
  • A callback function to handle successful responses
  • A callback function to handle error responses

You can configure the options listed in the following tables for button properties and payment request data objects.

Button property Description
environment Required

Type: enum

Specify your Zuora environment with one of the following allowed values:

For more information about Zuora environments, see Zuora Data Centers and Zuora Testing Environments.

style Specify the following properties to define the button style:
  • buttonType: A string that indicates the button type that you can display. For details about allowed values, see buttonType in Google Pay documentation.
  • buttonStyle: A string that indicates the color of a Google Pay button. For details about allowed values, see buttonColor in Google Pay documentation.
  • locale: The ISO 639-1 code represents the desired button language. For details about allowed values, see buttonLocale in Google Pay documentation.

For more information about the brand guidelines for Google Pay Button, see Google Pay documentation.


Payment request object Description
country Required.

The ISO 3166-1 alpha-2 code of country where the transaction is processed. For more information, see countryCode in Google Pay documentation.

currency Required.

The ISO 4217 alphabetic currency code. For more information, see currencyCode in Google Pay documentation.

amount Required.

The total amount for the payment.


Specify any of the following card networks that will be supported by your Google Pay integration:

  • amex: Indicates American Express
  • discover: Indicates Discover
  • jcb: Indicates JCB
  • masterCard: Indicates MasterCard
  • visa: Indicates Visa

The default value is:

['amex', 'jcb', 'masterCard', 'discover', 'visa']

You can also define a callback function to handle successful responses and a callback function to handle error responses. For error codes available for now, see Error codes. We are continuously improving the codes and messages.

For an example of how to specify button properties and payment request objects, see Code example for client-side integration.

Step 5. Create and mount the button element

Create an instance of the button element, pass in your configuration of the button, and mount the button element to the container for displaying the Google Pay button. Replace payment-request-button with the ID specified in Step 2. Create a container.


zuora.create('GooglePay', configuration).mount("#payment-request-button")

Code example for client-side integration

const zuora = Zuora('vIMyxqZKEk7gzUQtGZ1M1fTJBMHhKZH1');
const configuration = {
    environment: "api_sandbox",
    paymentRequest: {
        country: "US",
        currency: "USD",
        amount: 100,
        supportedNetworks: ['visa','masterCard','amex', 'discover']
    style: {
        buttonStyle: "default",
        buttonType: "buy",
        locale: "en"
    onSuccess: function (response) {'paymentMethodId: ' + response.paymentMethodId);'paymentId: ' + response.paymentId);
    onError: function (response) {
        console.error('code: ' + response.code);
        console.error('message: ' + response.message);
zuora.create('GooglePay', configuration).mount("#payment-request-button");

Error codes

The following table lists the error codes returned in the onError callback function.

Code Description
PAYMENT_SESSION_CANNOT_BE_REUSED The payment session is invalid because it is reused. A payment session can only be used for one payment transaction. Refresh your session token to initialize a new session for the new transaction.
AMOUNT_INCONSISTENT The amount from the client is not consistent with the amount in the payment session.
GOOGLE_PAY_UNAVAILABLE The device does not support processing payments with Google Pay. Ensure the device supports Google Pay.
NETWORK_IS_NOT_SUPPORTED The card network is not supported. Ensure the card network is one or any of the allowed values. See Step 4. Initialize and define the configuration object for more information.

Process the payment

Zuora will handle the payment processing and complete the payment. You do not need to implement any integration for this.

View and export payment method data

After a Google Pay payment method is successfully created, you can retrieve this payment method through the UI, API, Data Source Export, and Data Query. 

Test your integration

We suggest that you test your integration by using a real card with a test gateway. You can make test payments by using a real card without it being charged.

Google Pay payments are processed through several parties, such as the payment gateway, the card network, Google Pay, and your integration with Zuora. You might encounter issues beyond Zuora’s control. If you encounter any issues during your testing, you can submit a request to Zuora Global Support. Zuora will actively work with you to investigate the problems. If the problem is with other parties, please contact the relevant parties for support.