Getting started with Google Pay for JavaScript Library

Trust Payments hosts a publicly-accessible JavaScript Library that you can embed in your checkout to allow your web-app solution to accept payments with Google Pay.

To begin your integration you will need to confirm/request the following details from our Support Team:

Confirm your acquiring bank supports Google Pay as a payment option.
Request a test and live site reference, with Google Pay added as an enabled feature and enable 3-D Secure for both test and live accounts.
Request a JWT username & secret key linked to your test site reference.

Set up your Google account for testing

To begin testing Google Pay when targeting a test environment, you will need a Google account and you will need to join a group Google provides that allows you to use a set of API test cards for testing your Google Pay solution.

Click here for more information about the test card suite provided by Google (link to external site).

Once you have registered a Google account, sign in to the account in your browser, navigate to the following page:
https://groups.google.com/g/googlepay-test-mode-stub-data
Then click "Join group".
Once you have set your preferences, click "Join group".
You will be presented with a page that confirms you have been granted access to the Google test suite:
To ensure this is working, Google provide a demo page where you can click a Google Pay button to view the payment form.
Click here to open this in a new tab (link to external site).

If everything is working as expected, you should be able to select any of the example payment methods and click "CONTINUE". This will process a test payment.

Configuring your payment checkout

Ensure you have completed all of the steps above before proceeding.

Include a link to our v3 JS library in your web page <script src=<DOMAIN>/js/v3/st.js></script>
For <DOMAIN>, please refer to the information found under the JavaScript Library / Webservices API heading on this page.
For the Google Pay button to appear on screen on initialisation, you must include a div in your html source with an id that is configured in the subsequent steps of this guide <div id="st-google-pay"></div>
The st.js library will require you to have a form with the following id <form id="st-form"/> - The name of the id can be modified by setting property stform in the SecureTrading config.
The notification frame is an optional div that can be added to your page to display a success, error or cancel message to the customer on payment completion. If you find the messaging useful, you may wish to alter the text. This can be done using the translations property set in the SecureTrading config. Click here to learn more.

<html>
  <head>
  </head>
  <body>
    <div id="st-notification-frame"></div>
    <form id="st-form" action="https://www.example.com"/>
    <div id="st-google-pay"></div>
    <script src="<CDN_DOMAIN>"></script>
    <script> 
      (function() {
        var st = SecureTrading({  
          <! -- st.js configuration -->       
        });  
        st.GooglePay({
          <! -- Google Pay configuration -->
        });
      })(); 
    </script>
  </body>
</html>

Replace <CDN_DOMAIN> with a supported domain. Click here for a full list.

Initialise st.js library

When initialising the st.js library, you must set property jwt, with a JSON Web Token generated on your server side.

JSON Web Tokens (JWT) are an open, industry-standard RFC 7519 method for securely transmitting data between two parties. It protects against the modification of critical transaction data (e.g. the amount to be debited) by unauthorised parties during the payment session.

If you have yet to receive a JWT username and secret key, as described in the getting started section, please get in touch with our Support Team.

<html>
  <head>
  </head>
  <body>
    <div id="st-notification-frame"></div>
    <form id="st-form" action="https://www.example.com"/>
    <div id="st-google-pay"></div>
    <script src="<CDN_DOMAIN>"></script>
    <script> 
      (function() {
        var st = SecureTrading({  
          jwt : 'INSERT YOUR JWT HERE'      
        });  
        st.GooglePay({
          <! -- Google Pay configuration -->
        });
      })(); 
    </script>
  </body>
</html>

Replace <CDN_DOMAIN> with a supported domain. Click here for a full list.

Configuring the JSON Web Token (JWT)

You must refer to our JSON Web Token guidance to confirm the required content for the JWT.

Click here to open info in a new tab

Initialise Google Pay

The following example shows a basic Google Pay configuration that includes the required fields.

While the example below contains what you need to get started, you can tailor the Google Pay checkout to better fit your needs with optional fields. For a full list of properties provided by Google Pay, please visit their API documentation:

st.GooglePay({
  "buttonOptions": {
    "buttonRootNode": "st-google-pay"
  },
  "paymentRequest": {
    "allowedPaymentMethods": [{
      "parameters": {
        "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        "allowedCardNetworks": ["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"]
      },
      "tokenizationSpecification": {
        "parameters": {
          "gateway": "trustpayments",
          "gatewayMerchantId": "test_site12345"
        },
        "type": "PAYMENT_GATEWAY"
      },
      "type": "CARD"
    }],
    "environment":"TEST",
    "apiVersion": 2,
    "apiVersionMinor": 0,
    "merchantInfo": {
      "merchantId": "<e.g. 1234567890>"
    },
    "transactionInfo": {
      "countryCode": "US",
      "currencyCode": "USD",
      "checkoutOption": "COMPLETE_IMMEDIATE_PURCHASE",
      "totalPriceStatus": "FINAL",
      "totalPrice": "10.00",
      "totalPriceLabel": "Total",
      "displayItems": [{
        "label": "Example item",
        "price": "10.00",
        "type": "LINE_ITEM",
        "status": "FINAL"
      }]
    }
  }
});

The following are additional considerations that are specific to your Trust Payments account:

Property	Format	Description
allowedCardNetworks	List	The supported values for this property will depend on the payment methods supported on your Trust Payments account. Please contact our Support Team to confirm.
gatewayMerchantId	String	The Trust Payments site reference configured in the Google Pay manager instance acts as your gateway merchant Id. When you are ready to move to the PRODUCTION environment, the gatewayMerchantId must be set to your live site reference.
gateway	String	In your configuration, please set the property with value “trustpayments”.

Processing a payment

Having completed the steps above, the mark-up of your checkout page should resemble the following example, allowing you to complete a Google Pay payment in the TEST environment.

<html>
  <head>
  </head>
  <body>
    <div id="st-notification-frame"></div>
    <form id="st-form" action="https://www.example.com"/>
    <div id="st-google-pay"></div>
    <script src="<CDN_DOMAIN>"></script>
    <script> 
      (function() {
        var st = SecureTrading({  
          jwt: 'INSERT YOUR JWT HERE',          
        });  
        st.GooglePay({
          "buttonOptions": {
            "buttonRootNode": "st-google-pay"
          },
          "paymentRequest": {
            "allowedPaymentMethods": [{
              "parameters": {
                "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
                "allowedCardNetworks": ["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"]
              },
              "tokenizationSpecification": {
                "parameters": {
                  "gateway": "trustpayments",
                  "gatewayMerchantId": "test_site12345"
                },
                "type": "PAYMENT_GATEWAY"
              },
              "type": "CARD"
            }],
            "environment":"TEST",
            "apiVersion": 2,
            "apiVersionMinor": 0,
            "merchantInfo": {
              "merchantId": "<e.g. 1234567890>"
            },
            "transactionInfo": {
              "countryCode": "US",
              "currencyCode": "USD",
              "checkoutOption": "COMPLETE_IMMEDIATE_PURCHASE",
              "totalPriceStatus": "FINAL",
              "totalPrice": "10.00",
              "totalPriceLabel": "Total",
              "displayItems": [{
                "label": "Example item",
                "price": "10.00",
                "type": "LINE_ITEM",
                "status": "FINAL"
              }]
            }
          }
        });
      })(); 
    </script>
  </body>
</html>

Replace <CDN_DOMAIN> with a supported domain. Click here for a full list.

Dynamic Price Updates

Optionally, you can dynamically:

Update the transaction information on the payment sheet based on the shipping option chosen by your customer.
Update the shipping options and transaction information on the payment sheet based on the shipping address chosen by your customer.

To get started with dynamic price updates, you will need to modify the configuration passed to the st.js GooglePay method by:

Configuring the callbackIntents.
Subscribing to onPaymentDataChanged callback to update the payment sheet whenever the customer changes their shipping address or shipping option.
Subscribing to onPaymentAuthorized callback to ensure the authorised amount matches the amount displayed and agreed to on the Google Pay payment sheet.

Property	Format	Description
callbackIntents	String[]	SHIPPING_ADDRESS - Receive a callback when the customer changes the shipping address in the payment sheet. SHIPPING_OPTION - Receive a callback when the customer changes the shipping option in the payment sheet. PAYMENT_AUTHORIZATION - Receive a callback once the customer clicks "Pay". OFFER - Receive a callback once the customer attempts to apply a promotional code. The PAYMENT_AUTHORIZATION must be included when SHIPPING_ADDRESS or SHIPPING_OPTION is in the list of intents.
shippingOptionRequired	Boolean	Must be set to true when SHIPPING_OPTION is set in the callbackIntents.
shippingAddressRequired	Boolean	Must be set to true when SHIPPING_ADDRESS is set in the callbackIntents.
onPaymentDataChanged	function	The onPaymentDataChanged callback is invoked when: callbackIntents includes SHIPPING_ADDRESS and the customer changes their address. callbackIntents includes SHIPPING_OPTION and the customer changes their shipping option. callbackIntents includes SHIPPING_ADDRESS and/or SHIPPING_OPTION when the customer is first presented the payment sheet. callbackIntents includes OFFER and the customer applies a promotional code on the payment sheet. When the payment sheet is initialised. onPaymentDataChanged returns an object called intermediatePaymentData. The intermediatePaymentData object includes which address and shipping option was chosen by the customer. Please note: When the payment sheet is initialised, the INITIALIZE intent is automatically sent in the intermediatePaymentData and this will allow you to validate the customer's shipping address and available shipping options immediately and update the sheet if required. Resolve onPaymentDataChanged with an object ( PaymentDataRequestUpdate (external link)) that includes the new transaction information to be displayed to the customer on the Google Pay payment sheet. An example use case is when the customer selects an express shipping option and the total amount must be updated on the payment sheet to reflect this choice. When an error occurs, the PaymentDataRequestUpdate (external link) object can be configured with an error property that allows you to notify the customer of the error reason on the payment sheet e.g. the customer shipping address could be not serviceable or their applied promotional code has expired. `error: { reason: "OFFER INVALID", message: "Promotional code has expired.", intent: "OFFER" }` Please refer to Google's documentation (external link) for all update properties that can be added to the PaymentDataRequestUpdate object. For a complete reference guide for the onPaymentDataChanged callback, please review the Google documentation (external link).
onPaymentAuthorized	function	When callbackIntents includes PAYMENT_AUTHORIZATION and the customer clicks "Pay" in the Google Pay payment sheet, the onPaymentAuthorized callback is invoked and you will need to return a promise that will resolve successfully and close the payment sheet, or resolve with an error and display an error message on the payment sheet. The transactionState must be "SUCCESS" or "ERROR": SUCCESS Create a new JWT on your server to include the final amount that the customer agreed to pay on the payment sheet. Update the JWT by invoking the updateJWT function on the SecureTrading instance. ERROR If an error occurs during the creation or updating of the JWT, ensure you resolve with an "ERROR" to ensure only the correct amount is authorised. The "error" property with the "message" is optional, but is recommended. function onPaymentAuthorized(paymentData) { return new Promise(function(resolve, reject){ /Generate a newJWT with the final amount to pay final amount must match the displayed amount on the payment sheet call st.updateJWT(newJWT) to ensure the correct amount is authorised resolve with SUCCESS to trigger a closure of the payment sheet and for the payment authorisation to proceed/ resolve({transactionState: 'SUCCESS'}); /If an issue occurs when updating the JWT return an error to the payment sheet to notify the customer/ resolve({ transactionState: 'ERROR', error: { message: 'An error occurred, please try again.' } }); }); }

The callback implementations for onPaymentDataChanged (external link) and onPaymentAuthorized (external link) are in line with the contracts established by Google, as detailed in their official documentation. Although the technical aspects of these callbacks remain consistent, Google's guidance does not consider custom integrations through third-party gateways. Kindly keep this distinction in mind when consulting external documentation.

Dynamic price Update Example

<html>
  <head>
  </head>
  <body>
    <div id="st-notification-frame"></div>
    <form id="st-form" action="https://www.example.com"/>
    <div id="st-google-pay"></div>
    <script src="<CDN_DOMAIN>"></script>
    <script> 
      (function() {
        var st = SecureTrading({  
          jwt: 'INSERT YOUR JWT HERE',          
        });  
        st.GooglePay({
	  "buttonOptions": {
	    "buttonRootNode": "st-google-pay"
	  },
	  "paymentRequest": {
	    "allowedPaymentMethods": [{
	      "parameters": {
		  "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
		  "allowedCardNetworks": ["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"]
	      },
	    "tokenizationSpecification": {
	      "parameters": {
	        "gateway": "trustpayments",
	        "gatewayMerchantId": "test_site12345"
	      },
	      "type": "PAYMENT_GATEWAY"
	    },
	    "type": "CARD"
	    }],
	    "environment": "TEST",
	    "apiVersion": 2,
	    "apiVersionMinor": 0,
	    "merchantInfo": {
	      "merchantId": "<e.g. 1234567890>"
	    },
	    "shippingAddressRequired": true,
	    "shippingAddressParameters": {
	      "phoneNumberRequired": true,
	    },
	    "callbackIntents": [
	      "SHIPPING_ADDRESS",
	      "SHIPPING_OPTION",
	      "PAYMENT_AUTHORIZATION",
	    ],
	    "paymentDataCallbacks": {
	      "onPaymentAuthorized": onPaymentAuthorized,
	      "onPaymentDataChanged": onPaymentDataChanged
	    },
	    "shippingOptionRequired": true,
            "shippingOptionParameters": {
              defaultSelectedOptionId: "shipping-001",
              shippingOptions: [
                {
                  "id": "shipping-001",
                  "label": "$0.00: Free shipping",
                  "description": "Free Shipping delivered in 5 business days."
                },
                {
                  "id": "shipping-002",
                  "label": "$1.99: Standard shipping",
                  "description": "Standard shipping delivered in 3 business days."
                },
                {
                  "id": "shipping-003",
                  "label": "$10: Express shipping",
                  "description": "Express shipping delivered in 1 business day."
                }
              ]
            },
	    "transactionInfo": {
	      "countryCode": "US",
	      "currencyCode": "USD",
	      "totalPriceStatus": "ESTIMATED",
	      "totalPrice": "10.00",
	      "totalPriceLabel": "Total",
	      "displayItems": [{
	        "label": "Total Goods",
	        "price": "10.00",
	        "type": "LINE_ITEM",
	        "status": "FINAL"
	      }]
	    }
          }
       });
    })();
    </script>
  </body>
</html>

Capturing billing details from the customer Google Pay Wallet

To capture the billing details from the customer's Google Pay Wallet and use those details when processing the payment, the following steps are required:

In your signed jwt payload, you must include the field billingcontactdetailsoverride with a value of 1.
The billingAddressRequired must be set to true in the GooglePay method configuration.
To optionally capture the email address, include "emailRequired":true in the paymentRequest.

billingAddressParameters provides optional properties, which allow control over the amount of billing information required from the customer's wallet before they can proceed with the payment.

Property

Format

Description

format

String

The billing address format required to complete the transaction.

MIN: Name, country code, and postal code (default).
FULL: Name, street address, locality, region, country code, and postal code.

phoneNumberRequired

Boolean

Set to true if a phone number is required to process the transaction.

<html>
  <head>
  </head>
  <body>
    <div id="st-notification-frame"></div>
    <form id="st-form" action="https://www.example.com"/>
    <div id="st-google-pay"></div>
    <script src="<CDN_DOMAIN>"></script>
    <script> 
      (function() {
        var st = SecureTrading({  
          jwt: 'INSERT YOUR JWT HERE',          
        });  
        st.GooglePay({
          "buttonOptions": {
            "buttonRootNode": "st-google-pay"
          },
          "paymentRequest": {

            "emailRequired":true,

            "allowedPaymentMethods": [{
              "parameters": {
                "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
                "allowedCardNetworks": ["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"],
                "billingAddressRequired":true,
                "billingAddressParameters":{
                    "format":"FULL",
                    "phoneNumberRequired":true
                }
                ...

Further reading on this topic