Set up Google Pay
Introduction
Google Pay is a digital wallet payment method that supports in-app, online, and in-person contactless payments on mobile devices. Currently, Zuora supports setting up Google Pay on the following payment gateway integrations through either the JavaScript SDK or the API approach. The following sections describe how to set up Google Pay by using either the JavaScript SDK or the API approach. For information on setting up Google Pay through Payment Form, see Payment Form.
Payment Gateway Integration | Implementation Instructions |
---|---|
Adyen Integration v2.0 | |
Braintree v2.0 | Set up Google Pay with Zuora JavaScript SDK |
Chase Paymentech Orbital Gateway | Set up Google Pay on Chase through REST API |
Stripe v2 | Set up Google Pay with Zuora JavaScript SDK |
Creation of Google Pay payment methods is not supported through the Zuora UI or Payments Page 2.0.
After a Google Pay payment method has been added to a customer account, it can be used to make payments similar to using credit cards. You can use Google Pay payment methods in all Payments API operations. Processing Google Pay transactions is not supported by the legacy CRUD API operations. You can also view the Google Pay payment method in Zuora UI and process payments through the UI.
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. This integration supports Google Pay's Hosted Checkout feature, simplifying the process by bypassing complex certification and domain registration. Both the PAN_ONLY and CRYPTOGRAM_3DS authentication methods are supported, ensuring compatibility across both Android devices and Google Pay compatible browsers.
In the hosted checkout flow, Zuora's merchant ID is used. You do not need to register your own merchant ID.
Currently, this integration is supported on the following payment gateway integrations:
- Adyen Integration v2.0
- Braintree v2.0
- Stripe v2
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 team.
This section describes how to add Google Pay to your checkout flow by integrating with the latest version of JavaScript SDK provided by Zuora. If you need guidance for the legacy version of the JavaScript SDK, see Set up Google Pay with legacy version of Zuora JavaScript SDK.
Overview
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 client-side SDK integration.
- Implement the server-side API integration.
- Perform integration testing.
This feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters.
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.
- For Google Pay on Stripe, contact Stripe for gated access to the Processing Google Pay Decrypted Tokens API.
- Turn on the Payment Form feature in Zuora:
The JavaScript SDK integration utilizes the publishable key from the Payment Form feature for authentication. This integration supports embedding the Google Pay button within an iframe hosted by Zuora. To enable Payment Form on your tenant, see the "Before you start" section in Configure payment forms. - Get your testing environment ready. See Supported browsers by Google Pay for more information.
Implement 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/v3/zuora.js"></script>
.
For production environments, use <script src="https://js.zuora.com/payment/v3/zuora.js"></script>
.
Step 2. Create a container
Create a container for the Google Pay button on your page and place it where you want the button to be rendered. Replace payment-form-container
with the ID you want to use.
<div id="payment-form-container"> <!-- The Google Pay button will be inserted here. --> </div>
Step 3. Render the Google Pay button
- 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.
- Initialize an instance of the Zuora object with your publishable key.
- Populate the configuration parameters and generate a payment session when the end customers click the Google Pay button. The following table describes the parameters:
Parameter Type Description currency string Required.
The ISO 4217 alphabetic currency code, such as "USD".
amount string Required.
The total amount for the payment.
allowedCardNetworks array Default:
["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"]
The payment networks supported by your Google Pay integration. Specify the values as an array of strings, such as
["AMEX", "DISCOVER", "MASTERCARD", "VISA"]
Before specifying this field, check the following information:
- The networks supported by your payment gateway integration. See the Zuora Knowledge Center article specific to your payment gateway integration for details.
- The allowed values. See Google Pay documentation for details.
countryCode string The ISO 3166-1 alpha-2 code of the country where the transaction is processed, such as "US".
If it is not specified, the default value
US
is used.locale string The locale code, which is the combination of ISO language code and ISO country code, such as "en_US".
If it is not specified, the default value
en_US
is used.merchantInfo object Contains information about the merchant. You must specify the
merchantName
field (string) within this object. The provided merchant name and Zuora's merchant ID will be used to render the Google Pay button. There is no need to specify the merchant ID in this object, because Zuora's merchant ID is automatically applied.See Google Pay documentation for details.
Example:
merchantInfo: {
merchantName: "Example Merchant"
}
If
merchantName
andmerchantInfo
are not specified, the information configured in the Public Business Information setting for Payment Link will be used. Ensure you have enabled the Payment Link feature. See the following articles for instructions:- Follow the instructions in Enable payment features by yourself to enable the Payment Link feature.
- Follow the instructions in Add public business information to invoice payment page to configure the Public Business Information setting.
buttonColor string Default:
default
A string that indicates the button color that you can use. For details about allowed values, see buttonColor in Google Pay documentation.
buttonType string Default:
buy
A string that indicates the button type that you can display. For details about allowed values, see buttonType in Google Pay documentation.
buttonRadius string Default:
4px
The button corner radius in pixels, such as
5px
.buttonWidth string The button width in pixels, such as 10px
. If not specified, the container width is used.buttonHeight string The Button height in pixels, such as 10px
.The
accountId
parameter should not be specified when rendering the button. It must be provided when implementing the server-side API integration. See Implement server-side API integration to create payment session.Specifying a gateway instance is not supported when rendering the button. You can do it when implementing the server-side API integration. See Implement server-side API integration to create payment session.
- Mount the button component to the container.
- Handle the payment result.
Here is an example of the code implementation:
<script> const publishableKey = "pk_rO0ABXenAF2s7QAF…"; const renderForm = () => { const zuora = Zuora(publishableKey); zuora.createGooglePayButton({ countryCode: "US", locale: "en_US", currency: "USD", amount: "10.00", allowedCardNetworks: ["AMEX", "DISCOVER", "MASTERCARD", "VISA"], buttonHeight: "40px", buttonRadius: "5px", buttonColor: "black", buttonType: "pay", 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) => { console.log("=========="); console.log("Got Payment Session Token"); console.log("=========="); console.log(data.token); return resolve(data.token); }).catch((error) => { return reject(error); }); }); }, onComplete: (result) => { console.log("=========="); console.log("Payment Result"); console.log("=========="); console.log(result); resultMessage("Transaction Result: <br />" + " Success: " + result.success + "<br />" + " Payment Method Id: " + result.paymentMethodId + "<br />" + " Payment Id: : " + result.paymentId + "<br />" ); } }).then(function(googlePayButton) { googlePayButton.mount("#payment-form-container") }).catch(function(error) { console.error(error); }); } function resultMessage(message) { const container = document.querySelector("#result-message"); container.innerHTML = message; } </script>
The onComplete
function returns result
in the following structure:
On Success |
{ success: true, paymentMethodId?: string; paymentId?: string; } |
On Error |
{ success: false, error: { type: string; code: string; message: string; } } |
Implement the server-side API integration to create payment session
In your server, make an API request to the Create a payment session endpoint. For details about constructing the API request and implementing payment flows, see Create a payment session in the API Reference.
Perform integration testing
In your client code, provide a valid callback for createPaymentSession
, which makes a call to your backend API to create a payment session.
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.
View and export payment method data
After a Google Pay payment method is successfully created, it is shown as a Credit Card payment method type in Zuora. You can retrieve this payment method through the UI, API, Data Source Export, and Data Query.
Related information
Set up Adyen Google Pay through REST API
This article describes how to create an Adyen Google Pay payment method through the REST API operation. The payment method created through this approach is shown as an Adyen Google Pay payment method type in Zuora and an Adyen token for Google Pay is saved. You need to implement your own UI and payment processing integration.
For an end-to-end solution, it is recommended to set up Google Pay through the JavaScript SDK integration. For more information, see Set up Google Pay with Zuora JavaScript SDK.
Limitations
- This implementation of Google Pay on Adyen does not support 3D Secure.
- Adyen Google Pay payment methods created through the method in this article do not support non-referenced refunds.
- See Adyen documentation for more information about Google Pay availability limitations on Adyen.
Configure Google Pay for Adyen Integration v2.0
Prerequisites
- Enabled the Google Pay integration for your Adyen merchant account to be able to generate Google Pay tokens and process Google Pay transactions as described in Adyen documentation and the checklist before you go live.
- In your Adyen merchant account, enable the following fields for the additional card data in the Adyen dashboard:
- Card bin
- Subvariant
- Card summary
- Expiry date
- Ensure that an Adyen Integration v2.0 gateway instance is in active use in your Zuora tenant.
Procedure
Take the following steps to set up Adyen Google Pay:
- Obtain a Google Pay token.
- Enable Google Pay for Adyen in Zuora.
- Add a new Adyen Google Pay payment method in Zuora.
Obtain a Google Pay token
After Google Pay is enabled for your Adyen merchant account on the Adyen platform, obtain a Google Pay token from the Google Pay API PaymentData response. For more information about the fields this token contains, refer to Google Pay API documentation.
Enable Google Pay for Adyen in Zuora
Take the following steps to enable Adyen Google Pay in Zuora:
- In your Zuora tenant, navigate to Payments Settings > Payment Method.
- Click Edit and then select Adyen Google Pay.
- Click Save. The Google Pay payment method is then activated in your Zuora tenant.
Note that no update is required for your existing Adyen Integration v2.0 instance in Zuora to support Google Pay.
Add a new Adyen Google Pay payment method in Zuora
After you have enabled Google Pay in your Zuora tenant, you can create an Adyen Google Pay payment method and associate it with a customer account.
Adyen Google Pay payment methods can only be created through the Zuora REST APIs. You can use the Create a payment method API operation to create a new Adyen Google Pay payment method, and the following fields must be specified in the request:
accountKey
: Specify the customer account ID. This field is required unless the Orphan Payment Method feature is enabled.type
: SpecifyAdyenGooglePay
.googlePaymentToken
: Specify the stringified Google Pay token.
You can also pass the shopperEmail
information to the gateway through any of the following methods:
- Use the
email
field in any of the following API operations: - Use the
gatewayOptions
field in the Create a payment method API operation.
If shopperEmail
is not provided through either the email
or gatewayOptions
field, the shopperEmail
field in the payment request is set to the BillTo personal email if it is available. If BillTo personal email is not specified, the shopperEmail
field is set to the BillTo work email.
The following code is a sample request for creating a new Google Pay payment method:
Method and endpoint | POST https://rest.apisandbox.zuora.com/apps/v1/payment-methods |
Request body |
{ "accountKey": "2c92c0f97911f46a0179147510484b90", "type": "AdyenGooglePay", "email": "testemail@test.com", "googlePaymentToken": "{\"signature\":\"MEUCICeJTEEW+a9ak93yk8pYg4xGlPJbrBNjD8b6vahxD5TRAiEAyMiNhzosJDl2N46Dojzc53bwbT/O0t+VToLCqr01qs4\\u003d\",\"protocolVersion\":\"ECv1\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"aXpc95j3gEFJfaHF8PEpybNuV/k/IDKMa/FkbNnj2p/uaH8ll99hAUwWkH5EnHr2NwNgLuj3j9IhDomWI9gJ4n2fQlsQ9FsNuqsJjct/QuNvlzooLhu76HlzE3mScXcTUqPI1fgC8s/CVNz06aCUd7/oNMzyCw6VploO9abxp3zcpRvAO39bScaO3fri2Kl0WGozyiS0egXcUzMOpPxDw03SjmpgU/X5FjmxayOBUNxM9r/yOQyvY9mTUHOK855XVl3Xf9dpj6GDnDMp4bvCW8zpXWr76Snwtvv41dIaLxNWsBP0lS5PpJ5K1/rSRZg/dauIKQbWGmTTL24vz4Om7hVu25L7XrSM6F2PRUE4rqMblVDvXAlVsD+149r2fjXsB4DXmvGmwaDcuFeTDuI3ov7GDetgW3Fdl+n7RtBOK/luJYs76a9nPbVLhN/aKU5Hpd0ZrIO8ZUOoUYr6WuecD24tTzwic3k921eLJez8IJnG1k05kiqPpHEqMeLyP/WovjH/U7Vu3iDrH4yAxMEuh0MMi0tTgjXlVEezVnsU\\\",\\\"ephemeralPublicKey\\\":\\\"BGNnBpAd6WypQEYJmDH/DhUZ9mX2b/wJK6as8g6hZmDCDpHSWFC1BZ42UBrX/hrF/UarrT24CMcWLZp6fYl6PNw\\\\u003d\\\",\\\"tag\\\":\\\"j9fPmiEL/zj8R+0JRrTC1NgV9VVCYQ9zYaB7uZrEz9U\\\\u003d\\\"}\"}" } |
In addition to the Create a payment method operation, you can also use the following operations to create a Google Pay payment method together with other objects:
Once an Adyen Google Pay payment method is created, it cannot be edited.
View and export payment method data
After an Adyen Google Pay payment method is successfully created, you can view this payment method from the customer account details page in the Zuora UI or the response of the API operations for retrieving payment methods.
All related information about Adyen Google Pay payment methods can be exported using the Method Specific Data
field for the Payment Method data source. If you are not familiar with Data Source Exports, see Create a Data Source Export for instructions.
To filter only specific information about Adyen Google Pay payment methods, you can use several other Payment Method data source fields in combination. The following table provides the mapping relationship between Zuora data source fields and Adyen Google Pay fields.
Data source field | Adyen Google Pay field | Description |
---|---|---|
Method Reference Id | GoogleGatewayToken | The recurringDetailReference returned from Adyen after a successful response. |
Sub-Type | GoogleCardType | The brand or type of the card. For example, Visa and Mastercard. |
User Reference Id | GoogleCardNumber | The last 4 digits of the DPAN returned from Adyen as the card summary. |
Note that in the Credit Card Type field in the UI and the googleCardType
field in the API response, Zuora stores the first 100 characters of paymentMethodVariant returned from Adyen.
Make payments with Adyen Google Pay
After a Google Pay payment method for Adyen has been added to a customer account, it can be used to make payments and refunds through the Zuora UI and all Payments API operations except for CRUD operations.
Zuora's payment numbers are used as references when processing payments. When a payment method is created, a random string is generated and temporarily used as the payment number. It will be updated later with a real Zuora payment number in payment processing.
You can pass the shopperEmail information to the gateway by using the gatewayOptions
field in the Create a payment API operation. For more information about the logic of populating the shopperEmail
field in the request, see Gateway Options fields supported by Adyen Integration v2.0.
Additional Adyen fields supported for Adyen Google Pay
The following Adyen fields are supported for Adyen Google Pay through Zuora's Adyen Integration v2.0:
- expiryDate
- paymentMethodVariant
- cardSummary
- cardBin
Set up Chase Google Pay through REST API
Zuora supports setting up Google Pay and processing Google Pay payments and refunds with the Chase Paymentech Orbital Gateway integrations. You can use REST APIs to create Google Pay payment methods on Chase, and then it can be used to process payments and refunds through the UI and the REST APIs.
Limitations
- Zuora’s implementation of Google Pay on Chase does not support 3D Secure, and therefore European processing is not supported.
- Google Pay is not compatible with Zuora's Payment Pages 2.0 feature.
- Creation of Google Pay payment methods is only supported through the REST API. It is not supported through the Zuora UI.
- Gateway reconciliation for Google Pay is not supported yet.
Configure Google Pay for Chase Paymentech Orbital Gateway
Prerequisites
- Ensure that you have enabled the Google Pay integration for your Chase merchant account to be able to generate Google Pay tokens and process Google Pay transactions. To do this, you must provide Chase with Zuora’s Orbital Submitter ID, which is 056839.
- Ensure that a Chase Paymentech Orbital Gateway instance is in active use in your Zuora tenant.
Procedure
Take the following steps to set up the Google Pay payment method on the Chase Paymentech Orbital Gateway integration:
- Obtain a Google Pay token.
- Activate Google Pay on Chase in Zuora.
- Add a Google Pay on Chase in Zuora.
Obtain a Google Pay token
After Google Pay is enabled for your Chase merchant account on the Chase platform, obtain a Google Pay token from the Google Pay API PaymentData response. For more information about the fields that this token contains, see Google Pay API documentation.
Activate Google Pay on Chase in Zuora
After Zuora Global Support has enabled Google Pay for your tenant, take the following steps to enable Google Pay on Chase in Zuora:
- In your Zuora tenant, navigate to Settings > Payments > Payment Method.
- Click Edit and then select Google Pay.
- Click Save. The Google Pay payment method is then activated in your Zuora tenant.
Note that no update is required for your existing Chase Paymentech Orbital Gateway instance in Zuora to support Google Pay.
Add a Google Pay on Chase in Zuora
After you have enabled and activated Google Pay on Chase for your Zuora tenant, you can create a Google Pay payment method and associate it with a customer account.
Google Pay payment methods on Chase can only be created through the REST APIs. You can use the Create a payment method API operation to create a new Google Pay payment method, and the following fields must be specified in the request:
accountKey
: Specify the customer account ID. This field is required unless the Orphan Payment Method feature is enabled.type
: SpecifyGooglePay
.googlePaymentToken
: Specify the stringified Google Pay token.
Stored credential profiles will be automatically created and activated during the creation of the payment methods. If the Verify new payment method setting is enabled on the gateway instance configuration page, the network transaction ID (NTI) will be added when creating the payment method. See Overview of support for stored credential transactions for more information.
The following code is a sample request for creating a new Google Pay on Chase payment method:
Method and endpoint | POST https://rest.apisandbox.zuora.com/apps/v1/payment-methods |
Request body |
{ "accountKey": "2c92c0f97911f46a0179147510484b90", "type": "GooglePay", "googlePaymentToken": "{\"signature\":\"MEUCICeJTEEW+a9ak93yk8pYg4xGlPJbrBNjD8b6vahxD5TRAiEAyMiNhzosJDl2N46Dojzc53bwbT/O0t+VToLCqr01qs4\\u003d\",\"protocolVersion\":\"ECv1\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"aXpc95j3gEFJfaHF8PEpybNuV/k/IDKMa/FkbNnj2p/uaH8ll99hAUwWkH5EnHr2NwNgLuj3j9IhDomWI9gJ4n2fQlsQ9FsNuqsJjct/QuNvlzooLhu76HlzE3mScXcTUqPI1fgC8s/CVNz06aCUd7/oNMzyCw6VploO9abxp3zcpRvAO39bScaO3fri2Kl0WGozyiS0egXcUzMOpPxDw03SjmpgU/X5FjmxayOBUNxM9r/yOQyvY9mTUHOK855XVl3Xf9dpj6GDnDMp4bvCW8zpXWr76Snwtvv41dIaLxNWsBP0lS5PpJ5K1/rSRZg/dauIKQbWGmTTL24vz4Om7hVu25L7XrSM6F2PRUE4rqMblVDvXAlVsD+149r2fjXsB4DXmvGmwaDcuFeTDuI3ov7GDetgW3Fdl+n7RtBOK/luJYs76a9nPbVLhN/aKU5Hpd0ZrIO8ZUOoUYr6WuecD24tTzwic3k921eLJez8IJnG1k05kiqPpHEqMeLyP/WovjH/U7Vu3iDrH4yAxMEuh0MMi0tTgjXlVEezVnsU\\\",\\\"ephemeralPublicKey\\\":\\\"BGNnBpAd6WypQEYJmDH/DhUZ9mX2b/wJK6as8g6hZmDCDpHSWFC1BZ42UBrX/hrF/UarrT24CMcWLZp6fYl6PNw\\\\u003d\\\",\\\"tag\\\":\\\"j9fPmiEL/zj8R+0JRrTC1NgV9VVCYQ9zYaB7uZrEz9U\\\\u003d\\\"}\"}" } |
In addition to the Create a payment method operation, you can also use the following operations to create a Google Pay payment method on Chase together with other objects:
Once a Google Pay payment method on Chase is created, it cannot be edited.
View and export payment method data
After a Google Pay payment method on Chase is successfully created, you can view this payment method from the customer account details page in the Zuora UI.
You can use Data Source Export to export the Google Pay payment method data. The following four fields contain data of the Google Pay payment method. The definition data of Google Pay payment methods, excluding the encrypted fields such as the PAN field, can be exported through the Method Specific Data field of the Payment Method data source. For security reasons, the encrypted fields are removed from export results.
- Method Specific Data: The JSON string containing definition information of the Google Pay payment method.
- Method Reference Id: The identification reference of the Google Pay payment method.
- User Reference Id: The identification reference of the user or customer account.
- Sub-Type: The identification reference indicating the subtype of the Google Pay payment method.
The following table provides the mapping relationship between Zuora data source fields and Google Pay fields.
Data source field | Google Pay field | Description |
---|---|---|
Method Reference Id | MaskedPAN | The masked DPAN or PAN number. |
Sub-Type | GoogleCardType | The brand or type of the card. For example, Visa and Mastercard. |
For details about Data Source Exports, see Create a Data Source Export.
Make payments with Google Pay
After a Google Pay payment method on Chase has been added to a customer account, it can be used to make payments and refunds through the Zuora UI and all Payments API operations except for CRUD operations.
Zuora's payment numbers are used as references when processing payments. When a payment method is created, a random string is generated and temporarily used as the payment number. It will be updated later with a real Zuora payment number in payment processing.
When creating a Google Pay payment method on Chase through the REST API, a stored credential profile will be automatically created for the payment method. The profile contains important information such as NetworkTransactionId to ensure the success of the subsequence payments. If the stored credential profile is canceled, expired, or modified, subsequent payments might fail. Therefore, it is strongly not recommended to perform the following operations through either the Zuora UI or REST APIs:
- Cancel Stored Credential Profile
- Expire Stored Credential Profile
- Add another Stored Credential Profile