Google Pay

You can implement Google Pay™ directly on your website, by using our client JavaScript SDK. By doing so you directly integrate the Google Pay button on your website. In this case you will be responsible for bringing up the Google Pay payment sheet and retrieving the payment token. Thereafter you can send the payment token to our Create Payment API via the server-to-server SDK to complete the payment. We will handle the decryption for you. This requires more work from your development team, but there are some benefits:

Implementing the Google Pay button yourself allows you to show the Google Pay button directly on your website. For example on the product detail page of your products to increase conversion.
You can use the Google Pay API to retrieve your customer's personal details such as their address or e-mail address.

You need to take care of the following steps:

Enable Google Pay with us
Follow the setup guidelines provided by Google
Implement Google Pay on your website
Apply with Google for production access (on Google's side)

Enabling Google Pay on your account with us

First make sure Google Pay is enabled for the account (merchantId) you have with us. To do so contact your account manager who will work together with your implementation manager. They will be able to set the product up for you. You will also need to have regular card products configured in case you use Google Pay, as Google Pay allows consumers to pay with regular PANs. The transactions which are paid with regular PANS will be processed as regular card payments and it is highly recommended to apply 3-D Secure and fraud validations on these transactions.

Follow the setup guidelines provided by Google

Google has a clear overview of the prerequisites you need to follow before you implement the Google Pay API, which are described on the setup section of the Google documentation. This includes adhering to the Google Pay API Acceptable Use Policy.

Implementing Google Pay on your checkout page

After you have followed the setup guidelines of Google, you can start with the technical integration. Google offers a very clear and concise tutorial on how to implement Google Pay on your website, which you can find here. The technical integration section on this page, explains you the additional steps you need to take to add Google Pay to your checkout page and to send the token to us, which includes:

Checking whether Google Pay is currently available
Rendering the Google Pay button
Initializing the Payment sheet
And more!

Since you decrypt the sensitive payment data yourself, the tokenizationSpecification as referred to by Google is the type: DIRECT and below steps explain what you need to do additional to the tutorial of Google in order to implement Google Pay on your checkout page and send us the payment details for decryption.

1. Retrieve Google Pay via the payment product(s) API

The easiest way to check whether Google Pay is available, is by using the JavaScript Client SDK. The JavaScript SDK allows you to retrieve the Google Pay payment product via the payment product(s) API. This will retrieve data that is required in the next steps, such as the supported networks. While retrieving the payment product details, the SDK will also perform a call to Google isReadyToPay API, checking whether Google Pay is available with the device and settings your consumer is using. If this check fails, the Google Pay payment product will not be returned by the SDK, indicating that Google Pay is not available for the current transaction.

Get payment product

try {
  // session is an instance of the Session object, which is the main entry point for the SDK
  const paymentRequest = session.getPaymentRequest();

  const paymentProduct = await session.getPaymentProduct(
    320,
    paymentDetails,
    paymentProductSpecificInputs
  );
  paymentRequest.setPaymentProduct(paymentProduct);
} catch (err) {
  // Google Pay is not available, offer your customer another payment option to complete the payment
}

2. Available credit card networks

You have to provide the card networks allowed for the current Google Pay transaction. You can retrieve the available card networks by a GET payment product call via the server-to-server, or the client-to-server API. The networks will be available in the paymentProduct320SpecificData. The values that are returned are accepted by the Google Pay API directly.

merchantID: this is the merchantID you get from Google after registration with the Google Pay Business Console.
merchantName: this is the name that is rendered in the payment sheet. It is mandatory to provide this in case you are based in the European Economic Area (EEA) to meet the Strong Customer Authentication (SCA) requirements. The merchantName must be encoded as UTF-8 as per Google's specifications.
gatewayMerchantId: your merchantID with us, with which you process all your payments with us

Below is an extended code snippet, that also shows how you should initialize the allowedCardNetworks as well as the tokenizationSpecification after having retrieved the Google Pay payment product.

Initialize Google Pay

// If you want to use Google Pay in your application, you are required to register
// with Google in order to receive a Google Merchant ID
const paymentProductSpecificInputs = {
  googlePay: {
    merchantId: '<Your Google Merchant ID>',
    merchantName: '<Your merchant name>',
    gatewayMerchantId: '<Your merchant ID with us>'
  }
};

// Retrieve the Google Pay Payment Product via the client to server API
try {
  const paymentProduct = await session.getPaymentProduct(
    320,
    paymentDetails,
    paymentProductSpecificInputs
  );
  const allowedCardNetworks =
    paymentProduct.paymentProduct320SpecificData.networks;
  const tokenizationSpecification = {
    type: "DIRECT",
    parameters: {
      protocolVersion: "ECv2",
      publicKey: "BOdoXP1aiNp.....kh3JUhiSZKHYF2Y="
    }
  };

  // Store the payment product in the payment request which is required for
  // creating the encryptedCustomerData later on
  const paymentRequest = session.getPaymentRequest();
  paymentRequest.setPaymentProduct(paymentProduct);
} catch (err) {
  // Google Pay is not available, offer your customer another payment option to complete the payment
}

3. Strong Customer Authentication (SCA) compliance

In case you use an acquirer that is based in one of the European Economic Area (EEA) countries, you need to make sure that you provide information about the country of the acquirer in transactionInfo.countryCode towards Google, to be compliant with the PSD2 Strong Customer Authentication (SCA) requirements. Google Pay will return the appropriate credentials for transactions based on the country of the acquirer used for this transaction.

The acquirerCountry which you need to provide to Google can be retrieved by a payment product call via the server-to-server API or the client-to-server API. This code snippet below shows you how to obtain the acquirerCountry for the transactionInfo object. You also need to include the totalPrice and merchantName parameters as described in step 8.3 of the Google Pay tutorial as well as in the Strong Customer Authentication section on Google's documentation site.

More information on Strong Customer Authentication compliance for Google Pay can be found at Google Pay API documentation.

The code snippet below shows how to obtain the Acquirer Country code from the payment product response, and use it to initialize Google Pay.

Strong Customer Authentication (SCA) compliance

// If you want to use Google Pay in your application, you are required to register
// with Google in order to receive a Google Merchant ID
const paymentProductSpecificInputs = {
  googlePay: {
    merchantId: "<Your Google Merchant ID>",
    merchantName: "<Your merchant name>",
    gatewayMerchantId: "<Your gateway ID with us>",
  },
};

try {
  //Retrieve the Google Pay Payment Product via the client to server API
  // It is assumed that the session, paymentDetails and paymentProductSpecificInputs objects here are all valid
  const paymentProduct = await session.getPaymentProduct(
    320,
    paymentDetails,
    paymentProductSpecificInputs
  );

  //https://developers.google.com/pay/api/web/reference/request-objects#TransactionInfo
  const countryCode = paymentProduct.acquirerCountry;
  const transactionInfo = Object.assign(
    {
      currencyCode: "<Currency code>",
      totalPriceStatus: "<FINAL>",
      totalPrice: "<Amount>",
    },
    countryCode && { countryCode }
  );
} catch (err) {
  // Google Pay is not available, offer your customer another payment option to complete the payment
}

4. Rendering the Google Pay button

Once you know Google Pay is available, you can show the Google Pay button to your customer. Please consult Google's documentation on displaying the Google Pay button and ensure you adhere to Google's brand guidelines.

Add Google Pay button

function addGooglePayButton() {
  const paymentsClient = getGooglePaymentsClient();
  const button =
    paymentsClient.createButton({
      onClick: onGooglePaymentButtonClicked
    });
  document.getElementById('container').appendChild(button);
}

5. Initialise and execute the payment

The next step is to respond to your consumer clicking the Google Pay button, by creating a Google Pay payment session and finishing the payment.

Show Google Pay payment sheet

async function onGooglePaymentButtonClicked() {
  try {
    const paymentDataRequest = getGooglePaymentDataRequest();
   paymentDataRequest.transactionInfo = getGoogleTransactionInfo();
    
    const paymentsClient = getGooglePaymentsClient();
    const paymentData = await paymentsClient.loadPaymentData(paymentDataRequest);
    
    // handle the response
    processPayment(paymentData);
  } catch(err) {
    // show error in developer console for debugging
    console.error(err);
  }
}

6. Sending the Google Pay payment token to us

If you decrypt the payment token yourself, your systems are required to be PCI DSS compliant to handle sensitive payment data.

In this case you will have to set the tokenizationSpecification type to "DIRECT" when creating the Google Pay paymentDataRequest. In that step you will also have to provide a public key to Google. Google will use this key to encrypt the payment details, which you will be able to decrypt with the corresponding private key. Information on how to do the decryption can be found in the Google Pay tutorial. The decrypted payment details can then be sent to us via our Create Payment API. Please note that Google Pay returns two different styles of payment data. The first are regular card details (PAN_ONLY), whereas the other is a tokenized card (CRYPTOGRAM_3DS). Depending on the authMethod (PAN_ONLY or CRYPTOGRAM_3DS) contained in the paymentMethodDetails you have to provide different fields. Please have a look at the Create Payment API documentation for the specifics.

Below is an example for a decrypted Google Pay payment token with authMethod PAN_ONLY. Please note that that in case of PAN_ONLY transactions we process these transactions as regular card transactions for which 3-D Secure applies as well, as described in step 7. In our API you can send in these transactions with the paymentMethod CARD.

Create Payment and authMethod PAN_ONLY

{
    "mobilePaymentMethodSpecificInput": {
        "paymentProductId": "320",
        "decryptedPaymentData": {
            "pan": "4***************", //paymentMethodDetails.pan
            "expiryDate": "**25",      //paymentMethodDetails.expirationMonth + paymentMethodDetails.expirationYear
            "paymentMethod": "CARD"
        }
    }
}

In case your consumer paid using a card stored in the Google Pay app on their device, the authMethod CRYPTOGRAM_3DS is returned and you need to send in additional properties to us to process these type of transactions as shown in the example below. In our API you can send in these transactions with the paymentMethod TOKENIZED_CARD.

Create Payment and authMethod CRYPTGORAM_3DS

    "mobilePaymentMethodSpecificInput": {
        "paymentProductId": "320",
        "decryptedPaymentData": {
            "cryptogram": "ABCDEFGH12345",    //paymentMethodDetails.cryptogram
            "dpan": "4****************",      //paymentMethodDetails.dpan 
            "eci": 7 ,                        //paymentMethodDetails.eciIndicator
            "expiryDate": "**25",             //paymentMethodDetails.expirationMonth + paymentMethodDetails.expirationYear
            "paymentMethod": "TOKENIZED_CARD"
        }
    }
}

7. Minimal payment request

Below you find an example request with the minimal set of fields that are required to process a Google Pay payment. Please note that the fields required for 3-D secure are not in this example. We highly recommend to add these as shown in the next step.

You need to provide a value for the field order.customer.merchantCustomerId. In case your consumer pays with a card stored in their Google account, which is not tokenized on the device, this card is considered a regular card. To ensure this regular card is processed correctly on our platform, the merchantCustomerID needs to be provided, which is your identifier for the customer. It is a string which can have up to 15 characters. The merchantCustomerId can be used as a search criteria in the Payment Console and is also included in the GlobalCollect report files.

Create payment and authMethod PAN_ONLY is returned by Google

{
    "order" : {
        "amountOfMoney" : {
            "currencyCode" : "EUR",
            "amount" : 2300
        },
        "customer" : {
            "merchantCustomerId": "<Your ID of the consumer>",
            "billingAddress" : {
                "countryCode" : "NL"
            }
        }
    },
    "mobilePaymentMethodSpecificInput" : {
    "paymentProductId": "320",
        "decryptedPaymentData": {
            "pan": "4***************", 
            "expiryDate": "**25",
            "paymentMethod": "CARD"
        }
    }
}

Create payment and authMethod CRYPTOGRAM_3DS is returned by Google

{
    "order" : {
        "amountOfMoney" : {
            "currencyCode" : "EUR",
            "amount" : 2300
        },
        "customer" : {
            "merchantCustomerId": "<Your ID of the consumer>",
            "billingAddress" : {
                "countryCode" : "NL"
            }
        }
    },
    "mobilePaymentMethodSpecificInput" : {
        "paymentProductId": "320",
        "decryptedPaymentData": {
            "cryptogram": "ABCDEFGH12345", 
            "dpan": "4***************", 
            "eci": 7,
            "expiryDate": "**25",
            "paymentMethod": "TOKENIZED_CARD"  
        }
    }
}

8. Payment request including the 3-D Secure fields

Google Pay allows consumers to pay with a card on file (usually stored in the Google account of the consumer), which is referred to as PAN_ONLY in the Google Pay documentation. For these type of transactions, it is recommend to process them as regular card transactions, which means we recommend to send in the 3-D secure related fields. As you do not know at the start of the transaction whether your consumer will pay with a card on file stored in their Google account or with a card which they stored in the Google Pay app on their device, we recommend you to always send in the 3-D secure related fields.

In order to support 3-D Secure for cards which are represented in Google Pay as PAN_ONLY, you can fill the threeDSecure object inside the mobilePaymentMethodSpecificInput.paymentProduct320SpecificInput and the device object inside order.customer.

Create payment with 3-D Secure properties in case authMethod PAN_ONLY is returned

{
  "mobilePaymentMethodSpecificInput": {
    "paymentProductId": "320",
    "requiresApproval": true,
    "decryptedPaymentData": {
      "pan": "4***************",
      "expiryDate": "**25",
      "paymentMethod": "CARD",
      "paymentProduct320SpecificInput": {
        "threeDSecure": {
          "challengeIndicator": "no-preference",
          "challengeCanvasSize": "600x400",
          "skipAuthentication": false,
          "redirectionData": {
            "returnUrl": "https://hostname.myownwebsite.url",
            "variant": "100"
          }
        }
      }
    }
  },
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 2300
    },
    "customer": {
      "billingAddress": {
        "countryCode": "NL"
      },
      "device": {
        "acceptHeader": "texthtml,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
        "browserData": {
          "colorDepth": 24,
          "javaEnabled": false,
          "javaScriptEnabled": true,
          "screenHeight": "800",
          "screenWidth": "360"
        },
        "ipAddress": "123.123.123.123",
        "locale": "en-US",
        "userAgent": "Mozilla/5.0 (Linux; Android 10; SM-G980F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.101 Mobile Safari/537.36",
        "timezoneOffsetUtcMinutes": "420"
      },
      "locale": "en_US",
      "merchantCustomerId": "<Your ID for your consumer>"
    }
  }
}

Apply with Google for production access

After implementation of Google Pay on your own website, you do need to register with Google and get approval for the usage of Google Pay on your checkout page. You can find the details on Google's documentation site in the section "Request production access" as well as "deploy production environment".

Google Pay on your own checkout page: decryption is done by you