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.

  1. 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
  2. Then click "Join group".

    CP44-EN.png


  3. Once you have set your preferences, click "Join group".

    CP45-EN.png


  4. You will be presented with a page that confirms you have been granted access to the Google test suite:

    CP46-EN.png


  5. 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.

    CP47-EN.png

 

Configuring your payment checkout

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

  1. 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.

  2. 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>

  3. 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.

  4. 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.

Click here to learn more about JWTs - We strongly advise to use a third party library when generating a JWT on your backend server, to avoid having to create your own JWT encoding and decoding methods.

<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.

 

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",
"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
X1-EN.png 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.

X1-EN.png 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.

X1-EN.png 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",
"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
X1-EN.png 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.

X2-EN.png shippingOptionRequired Boolean

Must be set to true when SHIPPING_OPTION is set in the callbackIntents.

X2-EN.png shippingAddressRequired Boolean

Must be set to true when SHIPPING_ADDRESS is set in the callbackIntents.

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).

X1-EN.png 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>"
},
"transactionInfo": {
"countryCode": "US",
"currencyCode": "USD",
"checkoutOption": "COMPLETE_IMMEDIATE_PURCHASE",
"totalPriceStatus": "FINAL",
"totalPrice": "10.00",
"displayItems": [{
"label": "Example item",
"price": "10.00",
"type": "LINE_ITEM",
"status": "FINAL"
}]
}
},
"shippingAddressRequired": true,
"shippingAddressParameters": {
"phoneNumberRequired"
: true,
},
"shippingOptionParamaters": {
{
"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": "$1000: Express shipping",
"description": "Express shipping delivered in 1 business day."
}
]
},
"shippingOptionRequired": true,
"callbackIntents": [
"SHIPPING_ADDRESS",
"SHIPPING_OPTION",
"PAYMENT_AUTHORIZATION",
],
"paymentDataCallbacks": {
"onPaymentAuthorized": onPaymentAuthorized,
"onPaymentDataChanged": onPaymentDataChanged
},
}
}
});
})();
</script>
</body>
</html>
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request