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:
- Complete prerequisite tasks before integration.
- Implement the server-side API integration.
- Implement the client-side SDK integration.
Prerequisites
- Understand the guidelines and requirements of Google Pay:
- Google Pay Web Brand Guidelines. Ensure that only approved branding by Google is used when referencing Google Pay.
- Review and adhere to Google Pay API Terms of Service and Acceptable Use Policy.
- 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.
Request
{
"accountId":"402880de8779e14f018779e82905000f",
"processPayment": true,
"currency": "USD",
"amount": "100",
"paymentGateway":"e884322ab8c711edab030242ac120004"
}
Response
Status code: 200
{
"token":"402880de8779e14f018779e82905000f"
}
Implement client-side SDK integration
This section provides instructions on implementing the client-side SDK integration and a code example.
Procedure
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="https://cdn.zuora.com/payment/v1/zuora-payment.js"></script>
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.
Example:
<div id="payment-request-button"> <!-- The Google Pay button will be inserted here. --> </div>
Step 3. Initiate an instance of the Zuora object
Initiate 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.
Example:
const zuora = Zuora(token);
Step 4. Initiate 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:
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. |
| supportedNetworks |
Specify any of the following card networks that will be supported by your Google Pay integration:
The default value is:
|
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.
Example:
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) {
console.info('paymentMethodId: ' + response.paymentMethodId);
console.info('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 initiate 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. Initiate 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.