API Reference

Google Pay Client Integration

Google Pay PXP integration script - Merchants

This README demonstrates the simple integration of Google Pay API using the PXP ANYpay gateway.

Table of Contents

Getting Started

Here are the instructions for how you can integrate with our online payments API.

The goal of this integration script is to allow a merchant to initiate a Google Pay transaction, using either the Google Pay button or a merchant defined button.

There are several steps that a merchant needs to complete when using the script.

  1. Import the PXP JS script (gp.js).
  2. Adding a button
    1. Adding a Google Pay button
    2. Adding a merchant button
  3. Execute the runGooglePay() function
  4. Handling the response
  5. What happens when the runGooglePay() function fails?
  6. What the merchant HTML should look like when using merchants own button.
  7. What the merchant HTML should look like when using Google Pay button.

1. Import the PXP JS script

You should import the gp.js script in the head of your checkout page.

For example:

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Merchant's Checkout Page</title>
    <script src="./gp.js"></script>
</head>
...

2. Adding a button

The merchant has two options for adding a button to their page, they can either add a DIV and the Google Pay button will automatically render inside the DIV, or they can choose to have their own button and not render the Google Pay button.

To switch between these two modes of operation the merchant must state true or false in the useGooglePayButton parameter of the runGooglePay function mentioned below.

Ensure that your site is served over HTTPS, as Google Pay requires a secure connection. This means that if your site is served over HTTP, it's not possible to integrate Google Pay.

2.1. Adding a Google Pay button

Add an HTML div to your checkout page, with the id attribute set to pxp-google-pay-button. For example:

<div id="pxp-google-pay-button"></div>

This will serve as the placeholder for the Google Pay button on your page.

2.2. Adding a merchant button

Add an HTML div to your checkout page, with the id attribute set to merchant-google-pay-button and a button with an onclick event that calls the onMerchantButtonClick() function. For example:

<div id="merchant-google-pay-button" hidden>
<input type="button" value="Merchant GooglePay Button" onclick="onMerchantButtonClick();">
</div>

When a merchant has chosen to use their own button, an additional function must be included on the merchant page to validate the merchant site can connect to the Google Pay API, and must not show the merchants own button until this has been completed. For example:

        function handleGooglePayReady(event) {
            	let element = document.getElementById("merchant-google-pay-button");
		element.removeAttribute("hidden");
	}

3. Invoke the runGooglePay function

The merchant must, call the runGooglePay function on page load, with the appropriate parameters to initiate the Google Pay payment process. These parameters need to match the merchants desired card networks, authentication methods, country code, currency code.

Here are the parameters that the runGooglePay function is expecting:

runGooglePay(
    mid,
    sid,
    clientSystemTransactionId,
    allowedMethods,
    allowedCardNetworks,
    countryCode,
    currencyCode,
    amountStatus,
    amount,
    profile,
    publicKeyApi,
    useGooglePayButton,
    merchantNo,
    merchantName
)

For example:

<script>
    runGooglePay(
        "123456789", // mid
        "987654321", // sid
        "111222333", // clientSystemTransactionId
        ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"],
        "GB",
        "GBP",
        "FINAL",
        "100.00",
        "test",
        "64900ef1-05ba-493c-92ec-e32570be1703",
        false,
        "123444",
        "myMerchant"
    );
</script>

Essentially, the PXP gp.js script requires you to to invoke the runGooglePay() function on page load and populate a number of arguments with the correct values:

  • mid
  • sid
  • clientSystemTransactionId
  • allowedMethods
  • allowedCardNetworks
  • countryCode
  • currencyCode
  • amountStatus
  • amount
  • profile
  • publicKeyApi
  • useGooglePayButton
  • merchantNo
  • merchantName

3.1 Parameters passed to the runGooglePay function

In this section, you will learn how the PXP gp.js script works.

3.1.1. mid

Merchant ID issued by PXP. It is a string used to identify the merchant in the PXP system.

3.1.2. sid

Store ID issued by PXP. It is a string similar to merchant but it is a subdivision on the merchant side, in case that the merchant has multiple labels.

3.1.3. clientSystemTransactionId

This is the merchant transaction id and created by merchant. It can be used for query and other operations.

3.1.4. allowedMethods

Always coded to ["PAN_ONLY", "CRYPTOGRAM_3DS"]

3.1.5. allowedCardNetworks

List of allowed card networks

3.1.6. countryCode

Two digit country code

3.1.7. currencyCode

A three-letter ISO 4217 currency code that represents the currency for the transaction.

3.1.8. amountStatus

Always coded to "FINAL".

3.1.9. amount

The total price for the transaction, represented as a string in the format "123.45" (without currency symbols).

3.2.0. profile

Always coded to "test" or "prod".

3.2.1. publicKeyApi

Key obtained from the Public Key Service.

3.2.3. useGooglePayButton

true or false if the merchant requires the Google Pay button to render on their page.

3.2.3. merchantNo

Merchant number to display on the Google Pay pop up screen

3.2.4. merchantNane

Merchant name to display on the Google Pay pop up screen

4. Successful payment processing

What happens after the runGooglePay() call is successfully processed?

The merchant page is required to have a function handlePaymentResult(event) on their page to receive the Google Pay result from the PXP payment servers. Once this event has been triggered its the merchants responsability to continue the normal payment processing.

        function handlePaymentResult(event) {
            console.log("Payment complete", event.detail);
	}

5. Failed payment processing

What happens when runGooglePay() fails payment processing with an error?

The merchant page is required to have a function handlePaymentError(event) on their page to receive any errors from the PXP Google Pay process. Once this event has been triggered its the merchants responsability to show their user any relevant error message.

        function handlePaymentError(event) {
            console.log("Payment error", event.detail);
	}

6. Complete HTML MB

Below is an example of what should be in the merchant HTML when using a merchants own button.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Pxp Google Pay</title>
    <script src="./gp.js"></script>
    <style>
      body {
        font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
          Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue",
          sans-serif;
      }
      body p {
        width: 85%;
        margin: 0 auto;
        word-wrap: break-word;
        font-family: monospace;
      }
      #pxp-google-pay-error {
        background: whitesmoke;
        border: 2px solid darkred;
        border-radius: 4px;
        color: darkred;
        font-family: Arial, sans-serif;
        font-size: 16px;
        font-weight: bold;
        max-width: 500px;
        padding: 12px 16px;
        text-align: center;
        display: none;
      }
    </style>
  </head>

  <body>
    <h1>Google Pay With Merchant Own Button</h1>

    <section>
      <h2>Your shopping cart</h2>
      <h3>Item: test</h3>
      <h3>Total price: £100.00 GBP</h3>

      <div id="success"></div>

      <div id="merchant-google-pay-button" hidden>
        <input
          type="button"
          value="Merchant GooglePay Button"
          onclick="onMerchantButtonClick();"
        />
      </div>
    </section>

    <script>
      let envProfile = "test"; // 'prod', 'dev', 'test', if not provided, defaults to 'test'
      let merchantId = "GGP";
      let shopId = "GGP500000001";
      let clientSystemTransactionId = Date.now(); // unique clientSystemTransactionId


    runGooglePay(
        "123456789", // mid
        "987654321", // sid
        "111222333", // clientSystemTransactionId
        ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"],
        "GB",
        "GBP",
        "FINAL",
        "100.00",
        "test",
        "64900ef1-05ba-493c-92ec-e32570be1703",
        false,
        "123444",
        "myMerchant"
    );


      // Merchant takes over control (merchant's code)
      function handlePaymentResult(event) {
        // Merchant calls get payment account
        console.log("Payment complete", event.detail);

      }
      function handlePaymentError(event) {
        // Here, merchant can do anything they want with the error
        console.log("Error event", event.detail);

      }

      function handleGooglePayReady(event) {
        let element = document.getElementById("merchant-google-pay-button");
        element.removeAttribute("hidden");
      }
    </script>
  </body>
</html>

7. Complete HTML GB

Below is an example of what should be in the merchant HTML when using the Google Pay button.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Pxp Google Pay</title>
    <script src="./gp.js"></script>
    <style>
      body {
        font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
          Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue",
          sans-serif;
      }
      body p {
        width: 85%;
        margin: 0 auto;
        word-wrap: break-word;
        font-family: monospace;
      }
      #pxp-google-pay-error {
        background: whitesmoke;
        border: 2px solid darkred;
        border-radius: 4px;
        color: darkred;
        font-family: Arial, sans-serif;
        font-size: 16px;
        font-weight: bold;
        max-width: 500px;
        padding: 12px 16px;
        text-align: center;
        display: none;
      }
    </style>
  </head>

  <body>
    <h1>Google Pay With GooglePay Button</h1>

    <section>
      <h2>Your shopping cart</h2>
      <h3>Item: test</h3>
      <h3>Total price: £1.00 GBP</h3>
      <div id="pxp-google-pay-button"></div>
      <div id="success"></div>
    </section>

    <script>
      let envProfile = "test"; // 'prod', 'dev', 'test', if not provided, defaults to 'test'
      let merchantId = "GGP";
      let shopId = "GGP500000001";
      let clientSystemTransactionId = Date.now(); // unique clientSystemTransactionId

      runGooglePay(
        "123456789", // mid
        "987654321", // sid
        "111222333", // clientSystemTransactionId
        ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"],
        "GB",
        "GBP",
        "FINAL",
        "100.00",
        "test",
        "64900ef1-05ba-493c-92ec-e32570be1703",
        false,
        "123444",
        "myMerchant"
      );

      // Merchant takes over control (merchant's code)
      function handlePaymentResult(event) {
        // Merchant calls get payment account
        console.log("Payment complete", event.detail);
      
      }
      function handlePaymentError(event) {
        // Here, merchant can do anything they want with the error
        console.log("Error event", event.detail);
      
      }
    </script>
  </body>
</html>