Google Pay

Merchant can use Converge to integrate with Google Pay to process payments. Google Pay is available through the following Converge integration options:

  • Converge Hosted Payments Page (HPP)
  • Buy Button (Require merchant ID from Google)
  • Checkout.js (Require merchant ID from Google)
  • XML API

Google Pay needs to be enabled on Payment Extensions settings of Converge. Refer to Set Up Google Pay for Your Payment PageLink opens new window for more details. This applies for all the integration methods.

note

  • For more details on demo environment test card / wallet setup, refer to Google Pay test card suiteLink opens new window.
  • Google Pay does not support Internet Explorer (IE) browser
  • If 3DS is supported for your terminal, Converge will automatically enable 3DS for PAN_ONLY method.

Google Pay Website Requirements

To integrate Google Pay, make sure your website meet the following requirements:

Hosted Payments Pages

Google Pay needs to be enabled on the HPP setup. Refer to Set Up Google Pay for Your Payment PageLink opens new window for more details on how to enable Google Pay on the HPP setup.

Buy Button

Google Pay needs to be enabled to display on the Buy Button setup. Refer to Set Up Google Pay for Your Payment PageLink opens new window for more details on how to enable Google Pay on the Buy Button.

Checkout.js

Before your website becomes active, perform the following:

  • Apply access request for production environment by registering your website with Google. Once your website is approved, you will receive a Google merchant ID. You must include your Google merchant ID with each Google Pay request. To know more about the integration checklist, click hereLink opens new window.
  • Complete all the steps mentioned in the Deploy Production Environment of Google Pay APILink opens new window.

Checkout.js Sample Code

note

  • During the session token request, make sure to include the value for the parameter ssl_googlepay_merchant_id with your merchant ID provided by Google.
<!DOCTYPE HTML>
<html>

<head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Embedded Payment Demo</title>
  <script src="https://demo.convergepay.com/hosted-payments/Checkout.js"></script>
  <script>
    var callback = {
      onError: function (error) {
        showResult("error", error);
      },
      onDeclined: function (response) {
        showResult("declined", JSON.stringify(response));
      },
      onApproval: function (response) {
        showResult("approval", JSON.stringify(response));
      },
      onCancelled: function () {
        showResult("cancelled", "");
      }
    };

    function initiateEwallets() {
      var paymentData = {
        ssl_txn_auth_token: document.getElementById('token').value
      };
      ConvergeEmbeddedPayment.initGooglePay('googlepay-button', paymentData, callback);
      return false;
    }

    function showResult(status, msg, hash) {
      document.getElementById('txn_status').innerHTML = "<b>" + status + "</b>";
      document.getElementById('txn_response').innerHTML = msg + "</b>";
      document.getElementById('txn_hash').innerHTML = hash;
    }
  </script>

</head>

<body>
  <form>
    Transaction Token: <input type="text" id="token" name="token"> <br>
    <button onclick="return initiateEwallets();">Initiate Checkout.js</button> <br>
  </form>
  <br>
  <br /><br />
  <div id="googlepay-button"></div>
  <br>

  Transaction Status:<div id="txn_status"></div>
  <br>
  Transaction Response:<div id="txn_response"></div>
  <br>
  Transaction Hash Value:<div id="txn_hash"></div>
</body>

</html>

XML API

Before your website becomes active, complete all the steps mentioned in the Deploy Production Environment of Google Pay APILink opens new window and obtain the Merchant ID from the business console.

Follow the procedure on Google Pay documentationLink opens new window to integrate your web and obtain the Google Pay Payload.

XML API Integration Sample Code

<html>
<head></head>
<body>
    <div id="container"></div>
    <br>
    Payload:
    <br>
    <div id="payload"></div>
    <script>
    /**
     * Define the version of the Google Pay API referenced when creating your
     * configuration
     *
     * @see {@link https://developers.google.com/pay/api/web/reference/request-objects#PaymentDataRequest|apiVersion in PaymentDataRequest}
     */
    const baseRequest = {
      apiVersion: 2,
      apiVersionMinor: 0
    };   
    /**
     * Card networks supported by your site and your gateway
     *
     * @see {@link https://developers.google.com/pay/api/web/reference/request-objects#CardParameters|CardParameters}
     * @todo confirm card networks supported by your site and gateway
     */
    const allowedCardNetworks = ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"];  
    /**
     * Card authentication methods supported by your site and your gateway
     *
     * @see {@link https://developers.google.com/pay/api/web/reference/request-objects#CardParameters|CardParameters}
     * @todo confirm your processor supports Android device tokens for your
     * supported card networks
     */
    const allowedCardAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"];   
    /**
     * Identify your gateway and your site's gateway merchant identifier
     *
     * The Google Pay API response will return an encrypted payment method capable
     * of being charged by a supported gateway after payer authorization
     *
     * @todo check with your gateway on the parameters to pass
     * @see {@link https://developers.google.com/pay/api/web/reference/request-objects#gateway|PaymentMethodTokenizationSpecification}
     */
    const tokenizationSpecification = {
      type: 'PAYMENT_GATEWAY',
      parameters: {
        'gateway': 'convergepay',     // This MUST be set to convergepay
        'gatewayMerchantId': 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxx'   // The Terminal ID you obtained from Elavon Support must be used here
      }
    };
       /**
     * Describe your site's support for the CARD payment method and its required
     * fields
     *
     * @see {@link https://developers.google.com/pay/api/web/reference/request-objects#CardParameters|CardParameters}
     */
    const baseCardPaymentMethod = {
      type: 'CARD',
      parameters: {
        allowedAuthMethods: allowedCardAuthMethods,
        allowedCardNetworks: allowedCardNetworks,
        billingAddressRequired: true,
        billingAddressParameters: {format: 'FULL'}
      }
    };
     /**
     * Describe your site's support for the CARD payment method including optional
     * fields
     *
     * @see {@link https://developers.google.com/pay/api/web/reference/request-objects#CardParameters|CardParameters}
     */
    const cardPaymentMethod = Object.assign(
      {},
      baseCardPaymentMethod,
      {
        tokenizationSpecification: tokenizationSpecification
      }
    );
        /**
     * An initialized google.payments.api.PaymentsClient object or null if not yet set
     *
     * @see {@link getGooglePaymentsClient}
     */
    let paymentsClient = null;
   
    /**
     * Configure your site's support for payment methods supported by the Google Pay
     * API.
     *
     * Each member of allowedPaymentMethods should contain only the required fields,
     * allowing reuse of this base request when determining a viewer's ability
     * to pay and later requesting a supported payment method
     *
     * @returns {object} Google Pay API version, payment methods supported by the site
     */
    function getGoogleIsReadyToPayRequest() {
      return Object.assign(
          {},
          baseRequest,
          {
            allowedPaymentMethods: [baseCardPaymentMethod]
          }
      );
    }
   
    /**
     * Configure support for the Google Pay API
     *
     * @see {@link https://developers.google.com/pay/api/web/reference/request-objects#PaymentDataRequest|PaymentDataRequest}
     * @returns {object} PaymentDataRequest fields
     */
    function getGooglePaymentDataRequest() {
      const paymentDataRequest = Object.assign({}, baseRequest);
      paymentDataRequest.allowedPaymentMethods = [cardPaymentMethod];
      paymentDataRequest.transactionInfo = getGoogleTransactionInfo();
      paymentDataRequest.merchantInfo = {
        // @todo a merchant ID is available for a production environment after approval by Google
        // See {@link https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist|Integration checklist}
        // merchantId: '12345678901234567890',
        merchantName: 'Example Merchant', // The merchant Name that you registered with Google Business Console must go here
        merchantOrigin:'www.yourwebsite.com', // The merchant website that you registered with Google Business Console must go here
        merchantId:'XXXXXXXXXXXXXX' //The Merchant ID that is available on the Google Business Console must be used here
      };
      return paymentDataRequest;
    }
   
    /**
     * Return an active PaymentsClient or initialize
     *
     * @see {@link https://developers.google.com/pay/api/web/reference/client#PaymentsClient|PaymentsClient constructor}
     * @returns {google.payments.api.PaymentsClient} Google Pay API client
     */
    function getGooglePaymentsClient() {
      if ( paymentsClient === null ) {
        paymentsClient = new google.payments.api.PaymentsClient({environment: 'PRODUCTION'});
      }
      return paymentsClient;
    }
   
    /**
     * Initialize Google PaymentsClient after Google-hosted JavaScript has loaded
     *
     * Display a Google Pay payment button after confirmation of the viewer's
     * ability to pay.
     */
    function onGooglePayLoaded() {
      const paymentsClient = getGooglePaymentsClient();
      paymentsClient.isReadyToPay(getGoogleIsReadyToPayRequest())
          .then(function(response) {
            if (response.result) {
              addGooglePayButton();
              // @todo prefetch payment data to improve performance after confirming site functionality
              // prefetchGooglePaymentData();
            }
          })
          .catch(function(err) {
            // show error in developer console for debugging
            console.error(err);
          });
    }
   
    /**
     * Add a Google Pay purchase button alongside an existing checkout button
     *
     * @see {@link https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions|Button options}
     * @see {@link https://developers.google.com/pay/api/web/guides/brand-guidelines|Google Pay brand guidelines}
     */
    function addGooglePayButton() {
      const paymentsClient = getGooglePaymentsClient();
      const button =
          paymentsClient.createButton({
            onClick: onGooglePaymentButtonClicked,
            allowedPaymentMethods: [baseCardPaymentMethod]
          });
      document.getElementById('container').appendChild(button);
    }
   
    /**
     * Provide Google Pay API with a payment amount, currency, and amount status
     *
     * @see {@link https://developers.google.com/pay/api/web/reference/request-objects#TransactionInfo|TransactionInfo}
     * @returns {object} transaction info, suitable for use as transactionInfo property of PaymentDataRequest
     */
    function getGoogleTransactionInfo() {
      return {
        countryCode: 'US',
        currencyCode: 'USD',
        totalPriceStatus: 'FINAL',
        // set to cart total price same as the amount in XML API
        totalPrice: '6.00'
      };
    }
   
    /**
     * Prefetch payment data to improve performance
     *
     * @see {@link https://developers.google.com/pay/api/web/reference/client#prefetchPaymentData|prefetchPaymentData()}
     */
    function prefetchGooglePaymentData() {
      const paymentDataRequest = getGooglePaymentDataRequest();
      // transactionInfo must be set but does not affect cache
      paymentDataRequest.transactionInfo = {
        totalPriceStatus: 'NOT_CURRENTLY_KNOWN',
        currencyCode: 'USD'
      };
      const paymentsClient = getGooglePaymentsClient();
      paymentsClient.prefetchPaymentData(paymentDataRequest);
    }
   
    /**
     * Show Google Pay payment sheet when Google Pay payment button is clicked
     */
    function onGooglePaymentButtonClicked() {
      const paymentDataRequest = getGooglePaymentDataRequest();
      paymentDataRequest.transactionInfo = getGoogleTransactionInfo();
   
      const paymentsClient = getGooglePaymentsClient();
      paymentsClient.loadPaymentData(paymentDataRequest)
          .then(function(paymentData) {
            // handle the response
            processPayment(paymentData);
          })
          .catch(function(err) {
            // show error in developer console for debugging
            console.error(err);
          });
    }
    /**
     * Process payment data returned by the Google Pay API
     *
     * @param {object} paymentData response from Google Pay API after user approves payment
     * @see {@link https://developers.google.com/pay/api/web/reference/response-objects#PaymentData|PaymentData object reference}
     */
    function processPayment(paymentData) {
      // show returned data in developer console for debugging
        console.log(paymentData);
        showResult(paymentData);
      // @todo pass payment token to your gateway to process payment
      paymentToken = paymentData.paymentMethodData.tokenizationData.token;
    }
    function showResult (paymentData) {
                             document.getElementById('payload').innerHTML = JSON.stringify(paymentData);
    }
    </script>
    <script async
      src="https://pay.google.com/gp/p/js/pay.js"
      onload="onGooglePayLoaded()"></script>
</body>
</html>

Google Pay Payload Request

The following information is supported for Google Pay transactions:

Field NameDescriptionRequired
ssl_merchant_idYour Merchant ID
Elavon-assigned Converge Account ID (AID).
Required
ssl_user_idConverge user ID
The user ID with Hosted Payment API user status that can send transaction requests through the terminal.
Required
ssl_pinTerminal ID
Unique identifier of the terminal that will process the transaction request and submit to the Converge gateway.
The ssl_user_id sending the transaction request must be associated with the terminal that will process the request.
Required
ssl_transaction_typeTransaction Type
Valid value:  CCSALE / CCAUTHONLY
Required
ssl_amountTransaction Amount
The sale amount that includes the net and sales tax amounts.
Format: Number with 2 decimal places.
Required
ssl_google_payThe wallet identifier
Note: Required for XML API to indicate that the Cardholder has opted to pay using Google Pay.
Required

Send Google Pay Payload via XML request as below.

xmldata=
<txn>
    <ssl_merchant_ID>my_merchant_id</ssl_merchant_ID>
    <ssl_user_id>my_user_id</ssl_user_id>
    <ssl_pin>my_pin</ssl_pin>
    <ssl_transaction_type>CCSALE</ssl_transaction_type>
    <ssl_transaction_source>X_HPP</ssl_transaction_source>
    <ssl_amount>6</ssl_amount>
    <ssl_google_pay>{"apiVersionMinor":0,"apiVersion":2,"paymentMethodData":{"description":"Mastercard •••• 1234","tokenizationData":{"type":"PAYMENT_GATEWAY","token":"{\"signature\":\"MEQCIDjr+WRi6hfeu6Gm7DqgNGtFvaFuTwKYWHkCir75Wc9+AiBAhgI0JIl24UKtCbP5JNXg0yfyec7V0XrwJB8u5oOhvw\\u003d\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEim7XiHFP7qYM6rzUxgN7vftdcJS796dOSTbjszxGv9FLPciMrI+JiW7os0Z/5Gc0UCCU8EsmVh8xHVD5FzozIg\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1645120118000\\\"}\",\"signatures\":[\"MEYCIQC97zOpzAfgqg/tWudyFxX+9YXCR5/+mKmxQuGTqOaHXwIhAMstaaH+eSgfudyaaGkFTgQZiTV167eSSVEJprUIFOcx\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"NQCA9L14WClLFq2Xbs//V6xz+UHQdsjnbMYQTbxQZVppZP1ukT3HACR5RQQx425W4eK3TpjIElv5C4dk/EpNv7Rou3nRTHDQ4iIKHEdhUlpr52OF5D3XdZ/V1cnDb6nY9kAstEonzbPYb7qBcW7EOP9Ofc/gkzi5td+Ww2JIlM54f93uZwlPyB/b7OQs/bd0qCGa6otIQwkGbD8LEBOiX4EoHGxyG6cR378/jW2lGZw+JZjwcfmVcRCfHxLeDolOvhsViTwbp7Th/nmmlc1nmVhatvrq1jDihDhgy8cXwwx7srClFBVx2/hvTMEUBEMKWYRvIbmgzM5gMGkKBOsNCq3ePd2corz7sQd2izEz8EEAOqeCJuqrEH9tPaeyp/WXy1AbH3fU80ac9BJOgjrS0ZrJvoqUUHcZWIOFN4/2EZNLlKV6sHoOnXq+4m4g7+sEfDY1SP9a0NxX/IPcdQJo5LqMr6yNqbNuUVrf0YTe2YPh6pir5e3UQEs1QV7qAbTeMRS3VYIfxlJbs3Mx2cRFYGcZNeGkP/RVFd77fN+UyRbHSMaV7lXs/FgSspPD9tvOUXj5VG66H9o3\\\",\\\"ephemeralPublicKey\\\":\\\"BLQRt9gDcei/S+rbGAldS41ZTzZzI77zL6fd2eS44D3yqDWMXRQm10QZK+9YCsqIdxuvZkEtoHUkmAcgJ9k7qFc\\\\u003d\\\",\\\"tag\\\":\\\"qDdXMG2cmcwoHU7f9Ysxl4GJR9kq8e6jTxr/eI2FVLk\\\\u003d\\\"}\"}"},"type":"CARD","info":{"cardNetwork":"MASTERCARD","cardDetails":"3954","billingAddress":{"address3":"","sortingCode":"","address2":"","countryCode":"","address1":"","postalCode":"","name":"","locality":"","administrativeArea":"ON"}}}}</ssl_google_pay>
</txn>