Google Pay™

The purpose of this guide is to help merchants accept Google Pay using our APIs and build their own payment form to have full control over the look and feel of their checkout page.

Adding Google Pay to your payment methods allows your customers to use their stored Google Pay data to quickly and securely pay for goods and services.

With Google Pay, shoppers can make purchases using credit or debit cards stored in their Google account. Shoppers get to experience a simpler checkout process whether they are buying from their Android devices, on the web, or in-store through POS terminals.

When a shopper pays with Google Pay in apps and on websites, Google Pay shows a payment sheet where they select their preferred card payment method and confirm their purchase. Watch this video to see how shoppers pay with Google Pay.

Learn What the Google Pay App Is & How To Use It

How would you like to integrate?

Android
Check out the Google Pay Android Developer Documentation

Web
Check out the Google Pay Web Developer Documentation

📘

Compatibility

For more information on Google Pay™ availability, refer to:
List of countries where you can use Google Pay
List of supported browsers
Adhere to Google Pay Acceptable Use Policy

Before You Begin

These instructions explain how to add Google Pay to your existing API-only integration. The API-only integration works the same way for all payment methods. If you have not yet done this integration, refer to our API only integration guide.

Requirements

For merchants who want to integrate Google Pay™ through APIs.

Step 1: Load the Google Pay™ API JavaScript library
To load the Google Pay™ API JavaScript library, complete the following steps:

  1. Include Google's hosted JavaScript on your page. See the following code sample:
<script
  async
  src="https://pay.google.com/gp/p/js/pay.js"
  onload="console.log('TODO: add onload function')">
</script>
  1. After the Google Pay API JavaScript library loads, initialize a PaymentsClient object. Initial development uses a TEST environment, which returns dummy payment methods that are suitable to reference the structure of a payment response. In this environment, a selected payment method is not capable of a transaction. See the following code sample:
const paymentsClient =
  new google.payments.api.PaymentsClient({environment: 'TEST'});
  1. For more information about the requirements for a production environment that returns chargeable payment methods, see the Integration checklist.

Step 2: Define Google Pay API Version

const baseRequest = {
  apiVersion: 2,
  apiVersionMinor: 0
};

Step 3: Request a Payment Token for Your Payment Provider

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'bluefin',
    'gatewayMerchantId': '000000000001'
  }
};

Step 4: Define a Supported Payment Card Network.

Payconex supports all the major card brands: Visa, MasterCard, Amex & Discover.

const allowedCardNetworks = ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"];

The Google Pay API might return cards on file with Google (PAN_ONLY), and/or a device token on an Android device that is authenticated with a 3-D Secure cryptogram (CRYPTOGRAM_3DS). See the following code sample:

const allowedCardAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"];

For more information, see CardParameters in our Object reference documentation. Also, check with your gateway or processor for the card networks that are supported, and for support for Android device tokens.

🚧

Important

  • Make sure that you apply your existing risk checks and controls for payment transactions to Google Pay transactions. Google Pay validation and fraud checks are not intended to replace your risk management processes.
  • If you support PAN_ONLY, ensure that you trigger 3D Secure (step-up authentication) for Google Pay PAN_ONLY transactions in the same way that you trigger 3D Secure for normal card transactions.
  • Currently, PayConex only supports 3D Secure on Elavon and Chase PaymentTech.

Step 5: To describe your allowed payment methods, complete the following steps:

  1. Combine your supported authentication methods and supported card networks in order to describe your site's support for the CARD payment method. See the following code sample:
const baseCardPaymentMethod = {
  type: 'CARD',
  parameters: {
    allowedAuthMethods: allowedCardAuthMethods,
    allowedCardNetworks: allowedCardNetworks
  }
};
  1. Extend the base card payment method object to describe information you expect to be returned to your application. Include a description of the tokenized payment data. See the following code sample:
const cardPaymentMethod = Object.assign(
  {tokenizationSpecification: tokenizationSpecification},
  baseCardPaymentMethod
);
  1. For more information about supported parameters, see CardParameters.

Step 6: Determine Readiness to Pay with the Google Pay API

  1. Add your allowed payment methods to your base request object. See the following code sample:
const isReadyToPayRequest = Object.assign({}, baseRequest);
isReadyToPayRequest.allowedPaymentMethods = [baseCardPaymentMethod];
  1. Call isReadyToPay() to determine if the Google Pay API is supported by the current device and browser for your specified payment methods. See the following code sample:
paymentsClient.isReadyToPay(isReadyToPayRequest)
    .then(function(response) {
        if (response.result) {
            // add a Google Pay payment button
        }
    })
    .catch(function(err) {
      // show error in developer console for debugging
      console.error(err);
    });

Step 7: Add a Google Pay Payment Button

Add a Google Pay payment button to your page to encourage shoppers to check out with payment methods that are supported by the Google Pay API and your site. For more information about available button types, colors, and display requirements, see the brand guidelines.

See the following payment button code sample:

const button =
    paymentsClient.createButton({onClick: () => console.log('TODO: click handler'),
    allowedPaymentMethods: []}); // make sure to provide an allowed payment method
document.getElementById('container').appendChild(button);

Step 8: Create a PaymentDataRequest Object

  1. Build a JavaScript object that describes your site's support for the Google Pay API. For a full list of supported properties, see PaymentDataRequest. See the following code sample:
const paymentDataRequest = Object.assign({}, baseRequest);
  1. Add the payment methods supported by your app, such as any configuration of additional data that is expected in the response. See the following code sample:
paymentDataRequest.allowedPaymentMethods = [cardPaymentMethod];
  1. Define a total price and currency for a shopper to authorize. See the following code sample:
paymentDataRequest.transactionInfo = {
  totalPriceStatus: 'FINAL',
  totalPrice: '123.45',
  currencyCode: 'USD',
  countryCode: 'US'
};

🚧

Important

Merchants who process transactions in the European Economic Area (EEA) or any other countries that are subject to Strong Customer Authentication (SCA) must include the countryCode, totalPrice, and merchantName parameters to meet SCA requirements.

  1. Provide a user-visible merchant name, and use our TEST merchantId value when in TEST. For more details, and for information on when to replace the TEST merchantId value, see MerchantInfo. See the following code sample of a user-visible merchant name:

Step 9: Register an Event Handler for User Gestures

  1. Register a click event handler for the purchase button. The event handler calls loadPaymentData() immediately after it interacts with the Google Pay payment button.

  2. After a Google user grants permission for your site to receive information about the user's selected form of payment and optional contact data, handle the response from the Google Pay API.

  3. Extract the payment token from the paymentData response. If you implement a gateway integration, pass this token to your gateway without any modifications.

📘

Note

In a TEST environment, a payment response includes summary data about the selected payment method that is suitable for display on a confirmation page. The payment response does not include a payment method that is capable of a transaction.

paymentsClient.loadPaymentData(paymentDataRequest).then(function(paymentData){
  // if using gateway tokenization, pass this token without modification
  paymentToken = paymentData.paymentMethodData.tokenizationData.token;
}).catch(function(err){
  // show error in developer console for debugging
  console.error(err);
});

Developer Resources

Google Pay provides APIs for both Android and web applications and comprehensive developer documentation for each version of the API. The specific Google Pay API integration details depend on the type of application you are developing.

See the following resources for detailed Google Pay API integration details:

All merchants must adhere to the Google Pay APIs [Acceptable Use Policy]
(https://payments.developers.google.com/terms/aup) and accept the terms defined in the Google Pay API Terms of Service.

How it works

  1. PayConex verifies authentication requests that come in from a merchant. If the proper variables/values are not valid, we indicate "Authentication is incorrect."

  2. Request parameter must contain

"tender_type": "GPay",
"gpay_payload": "<TOKEN_FETCHED_FROM_GOOGLE>"
  1. Once the request is received, depending on the response, the transaction could be returned to the merchant as decline with reason information, etc.

  2. The transaction is then sent to the end processor.

Testing & Go-live

To test Google Pay, you have two different options:

  • Login to a Google account and create a Google Pay wallet with valid card details.
  • Use a sample card from Google's test card suite.

For more information, see Google Pay's test environment setup for Web or for Android.

📘

Before You Go Live

In production, Google Pay will only be available if:

  • The shopper is logged in to their Google account.
  • The shopper has at least one valid payment method on their Google Pay account.

Processing a Payment

curl --location --request POST 'https://staging.payconex.net/api/qsapi/3.8' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'account_id=<PAYCONEX_ACCOUNT_ID>' \
--data-urlencode 'api_accesskey=<PAYCONEX_API_KEY>' \
--data-urlencode 'response_format=JSON' \
--data-urlencode 'transaction_type=SALE' \
--data-urlencode 'tender_type=GPay' \
--data-urlencode 'transaction_amount=10' \
--data-urlencode 'gpay_payload=<TOKEN_PROVIDED_BY_GOOGLE>'

Support

For assistance with your PayConex merchant account, or any integration needs contact
For assistance with integrating the Google Pay API, see the [Google Pay API Troubleshooting page] (https://developers.google.com/pay/api/android/support/troubleshooting) or complete the Google Pay API Integration Support Request Form.