Google Pay

Google Pay

Introduction

Google Pay can be utilized as a checkout option on a payment page as well as a direct checkout option on the cart page. Loading the Google Pay button via Payment Button payment widget is just like loading any other brand, i.e. in step 2, GOOGLEPAY must be specified as a brand. Once the Google Pay button will be used by the consumer, the Google Pay payment sheet will appear on the device.

As soon as the consumer starts to interact with the Google Pay payment sheet, several events will be triggered. All events can be consumed by implementing the Payment Button API callback functions. All callback functions offered by the Google Pay are wrapped into the Payment Button API. No interaction with the Google Pay is required.

For steering the Google Pay payment sheet or for updating data on the Google Pay payment sheet after the consumer started to interact with it, several options are available.

Google Pay on the payment page

Loading the Google Pay button via Payment Button payment widget is just like loading any other brand, i.e. in step 2, GOOGLEPAY must be specified as a brand.

See an example below.


Google Pay on the cart page

Sometimes you might want to display the Google Pay button early on the payment workflow where you do not yet have a checkout ID. Usually, the shopper can decide whether to continue with the normal checkout, or to immediately pay with Google Pay.

It is possible to display the Google Button first and create a checkout ID later. In step 2:

  • Use paymentWidgets.js without a checkout ID
    <script src="https://test.emetec.pro/v1/paymentWidgets.js"></script>
  • Define a callback function in wpwlOptions.createCheckout to create a checkout
We will call the callback function once the Google Pay button is clicked. The function should return a checkout ID, or a promise that will return a checkout ID. Specifically, the returned object can be any thenable object. In particular, both JavaScript Promise and jQuery Promise are supported.

Example:

wpwlOptions.createCheckout = function() {
    // Call your server to create a checkout
    return $.post("https://your.server")
    .then(function(response) {
        // Assume that your server returned the response containing checkoutId
        return response.checkoutId;
    });
};

Google Pay Options

As with other options, you can modify the Google Pay behavior by using wpwlOptions.googlePay. The full reference of all available options is shown below in this page.

References

The following table lists all available Google Pay options that you can use with wpwlOptions.googlePay.

ParameterDescriptionExamples
gatewayMerchantId Your merchant ID provided by us. gatewayMerchantId: "8a829418622a195c01622b1a5c6c024e"
allowedAuthMethods Fields supported to authenticate a card transaction.
  • PAN_ONLY: this authentication method is associated with payment cards stored on file with the user's Google Account. Returned payment data includes personal account number (PAN) with expiration month and year.
  • CRYPTOGRAM_3DS: This authentication method is associated with cards stored as Android device tokens. Returned payment data includes a 3-D Secure (3DS) cryptogram generated on the device.
allowedAuthMethods: ["PAN_ONLY", "CRYPTOGRAM_3DS"]
allowedCardNetworks One or more card networks you support also supported by the Google Pay API.:
  • AMEX
  • DISCOVER
  • JCB
  • MASTERCARD
  • VISA
allowedCardNetworks: ["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"]
merchantId A Google merchant identifier issued after your website is approved by Google. Required when going Live. See Google Pay's Integration checklist for more information about the approval process and obtaining a Google merchant identifier. merchantId: "your_merchantId"
merchantName A user-visible merchant name encoded as UTF-8. This name may be shown to the user in the Google Pay payment sheet to describe the merchant requesting payment data. merchantName: "Example Merchant"
emailRequired An optional parameter. Set to true to request an email address. emailRequired: true
shippingAddressParameters An optional parameter. If onPaymentDataChanged is passed in, shippingAddressParameters is used to specify shipping address restrictions. The user's shipping address will then abide to these specified restrictions. Refer ShippingAddressParameters
  • shippingAddressParameters: { allowedCountryCodes: ["US"], phoneNumberRequired: true } - This will restrict the allowed country to be US only and will display/mandate the phone number.
  • shippingAddressParameters: { allowedCountryCodes: ["US", "IN"], phoneNumberRequired: false } - This will restrict the allowed country to be US or India only and the phone number is not displayed/mandated.
shippingOptionRequired An optional parameter. The shippingOptionRequired when set to true, indicates that we are providing the shipping options to the user. When set to true, shippingOptionParameters must be passed in. shippingOptionRequired: true
shippingOptionParameters An optional parameter. shippingOptionParameters is set when shippingOptionRequired when set to true. This element basically defines the shipping options that are to be presented to the user. Refer ShippingOptionParameters shippingOptionParameters : {
  defaultSelectedOptionId: "shipping-002",
  shippingOptions: [
    {
      id: "shipping-001",
      label: "Free: Standard 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.00: Express shipping",
      description: "Express shipping delivered in 1 business day."
    }
    ]
  }
billingAddressRequired An optional parameter. Set to true if you require a billing address. A billing address should only be requested if it's required to process the transaction. Additional data requests can increase friction in the checkout process and lead to a lower conversion rate. If set to true, the billing address is passed as part of the parameter passed by Google to onPaymentDataAuthorized(paymentData). Can be retrieved as paymentData.paymentMethodData.info.billingAddress billingAddressRequired: true
billingAddressParameters An optional parameter. The expected fields returned if billingAddressRequired is set to true. Refer BillingAddressParameters billingAddressParameters : { "format": "FULL", phoneNumberRequired : true }
displayItems An optional parameter. All of the available charges for the current payment request. This is only populated in the payment sheet if you use Authorize Payments or Dynamic Price Updates. This field is required if you implement support for Authorize Payments or Dynamic Price Updates. Refer DisplayItem displayItems: [
   {
      label: "Subtotal",
      type: "SUBTOTAL",
      price: "11.00"
   },
   {
      label: "Tax",
      type: "TAX",
      price: "1.00"
   },
   {
      label: "GST",
      type: "TAX",
      price: "1.00"
   }
]

Google Pay callback functions

Google Pay provides us with two call back functions namely onPaymentAuthorized and onPaymentDataChanged. To use these call back functions, we need to follow the below steps :

  • Provide implementations of onPaymentAuthorized, onPaymentDataChanged based on the need. Either OR both of the functions can be implemented and passed via wpwlOption.googlePay
  • A default implementation of onPaymentAuthorized is provided by ACI, but merchants can override and provide their own implementations of onPaymentmentAuthorized.

The following table details the onPaymentAuthorized and onPaymentDataChanged Google Pay callback functions that you can use with wpwlOptions.googlePay.

Callback functionDescriptionExamples
onPaymentAuthorized This method is called when a payment is authorized in the payment sheet. The default implementation by ACI, processes the payment on ACI side and returns a SUCCESS back to Google. Merchants can override this behavior by providing an implementation of onPaymentAuthorized. If an implementation is provided by the merchant, ACI processes the payment on ACI side only when the implementation returns a SUCCESS.
If billingAddressRequired is set to true, the billing address is passed as part of the parameter passed by Google to this method. Billing address can then be retrieved as paymentData.paymentMethodData.info.billingAddress.
The method parameter, PaymentData, is an object that contains the requested shopper data that's returned by Google after a payer approves payment. PaymentData contains:
  • apiVersion - Major API version. The value in the response matches the value provided in googlePay.apiVersion
  • apiVersionMinor - Minor API version. The value in the response matches the value provided in googlePay.apiVersionMinor.
  • paymentMethodData - Data about the selected payment method. Refer PaymentMethodData.
  • email - Email Address
  • shippingAddress - The shipping address. Refer Address.
The implemented handler should return an Promise which can be in a Resolved or Rejected status:
  • If Resolved, should return object that contains information about payment transaction results. Refer PaymentAuthorizationResult
  • If Rejected, should return an error object with an error intent and message to be rendered in the payment sheet. Refer PaymentDataError
onPaymentAuthorized:
Example 1.
function onPaymentAuthorized(paymentData) {
  Use or Save full shipping address(
  return new Promise(function(resolve, reject) {
    // Custom merchant logic
    resolve(
      { transactionState: 'SUCCESS' }
    );
  });
}
Example 2.
function onPaymentAuthorized(paymentData) {
  Use or Save full shipping address(
  return new Promise(function(resolve, reject) {
    // Custom merchant logic
    resolve(
      {
         transactionState: 'ERROR' ,
         error: {
            reason: "PAYMENT_DATA_INVALID",
            message: "Custom merchant message",
            intent: "PAYMENT_AUTHORIZATION"
         }
      }
    );
  });
}
onPaymentDataChanged This method handles payment data changes in the payment sheet such as shipping address and shipping options. The method parameter, is an object that contains the selected address and shipping option in the payment sheet. For details, see IntermediatePaymentData. The IntermediatePaymentData object contains :
  • callbackTrigger - The value of this parameter can be any of the below and specifies the type of event being passed in.
    • INITIALIZE
    • SHIPPING_ADDRESS
    • SHIPPING_OPTION
    For example, callbackTrigger has a value of SHIPPING_OPTION, when the user selects any one of the presented shipping options.
  • IntermediateAddress - This is an object which represents the key elements of an address and can be used to calculate, say shipping cost. For details, refer IntermediateAddress.
  • SelectionOptionData - This is an object that represents the shipping option selected in the payment sheet. For details, refer SelectionOptionData.
The implemented handler should return an Promise which can be in a Resolved or Rejected status:
  • If Resolved, An object that contains information about new transaction information, shipping options, and payment data errors. For details, see PaymentDataRequestUpdate.
  • If Rejected, An error object with an error intent and message to be rendered in the payment sheet. For details, see PaymentDataError.
onPaymentDataChanged:
onPaymentDataChanged : function onPaymentDataChanged(intermediatePaymentData) {
   console.log('Google Pay User induced function and returning');
   var returnMe = new Promise(function(resolve, reject) {
   var paymentDataRequestUpdate = {};
   var shippingOptionData = intermediatePaymentData.shippingOptionData;
   if (intermediatePaymentData.callbackTrigger == "SHIPPING_OPTION") {
      console.log('SHIPPING_OPTION selected with shipping option id selected as ', shippingOptionData.id)
      paymentDataRequestUpdate = {
         newShippingOptionParameters: {
            defaultSelectedOptionId: shippingOptionData.id,
            shippingOptions: [
               {
                  id: "shipping-001",
                  label: "Free: Standard 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.00: Express shipping",
                  description: "Express shipping delivered in 1 business day."
               }
            ]
         },
         newTransactionInfo: {
            currencyCode: "INR",
            totalPriceStatus: "FINAL",
            transactionId: "MyTranId",
            totalPrice: "12.00",
            totalPriceLabel: "Total",
            checkoutOption: "COMPLETE_IMMEDIATE_PURCHASE",
            displayItems: [
               {
                  label: "Subtotal",
                  type: "SUBTOTAL",
                  price: "5.00",
               },
               {
                  label: "Tax",
                  type: "TAX",
                  price: "1.00",
               }
            ]
         }
      };
   }
   resolve(paymentDataRequestUpdate);
   });
   return returnMe; }

Options and callback example

To quick start your integration, we recommend use our example code below as a guidance (Click js tab to see the code example).