Prerequisites

The following is required for a Google Pay™ API integration:

• An active merchant account with our Payment Gateway
• Your Ecentric API credentials (API Key and Secret)

Supported Browsers, Authentication Methods and Card Networks

Google Pay availability depends on device and browser compatibility. A list of supported browsers can be found on the documentation from Google Pay.

The recommendation from Google Pay is to use the isReadyToPay(isReadyToPayRequest) method to determine a user's ability to return a form of payment from the Google Pay API.

Authentication Methods

Google Pay supports card payments via two authentication methods:

• PAN_ONLY: returns a primary account number (PAN).
• CRYPTOGRAM_3DS: returns a device token with a 3-D Secure cryptogram.

📘

NOTE: CRYPTOGRAM_3DS is only supported on Android devices.

For more information, see CardParameters in Google’s Object reference documentation.

Allowed Card Networks

The Payment Gateway supports the following networks for Google Pay:

• VISA
• MASTERCARD

These will be used in your integration when you define the allowedCardNetworks.

Getting Started with Google Pay

1: Register as a Google Pay Merchant

In order to process Google Pay payments via your website or app, merchants using our API are required to register with Google and will be issued with a merchantID.

Follow the steps to register on the Google Pay and Wallet Console:

• Web - Publish your integration | Google Pay API | Google for Developers
• Android - Publish your integration | Google Pay API for Android | Google for Developers

Ensure that you accept the Google Pay API Terms of Service and Acceptable Use Policy.

2: Enable Google Pay on your Ecentric merchant account

• Contact our Product Support team to enable Google Pay on your merchant account.
• You will be issued with a gatewayMerchantId which is a unique identifier that Ecentric uses for merchant verification.
• You will also receive Ecentric's gateway Id which is used by Google to identify Ecentric as the Payment Processor.

3. Integrate to Google Pay API to implement the Google Pay Button

Follow the Integration Steps to integrate to the Google Pay API for your Android app or website.

4. Send the Encrypted Payload to the Payment Gateway

4.1 Customer Authentication

Use the Secure3DLookup Payment Gateway API to send the encrypted payload from Google Pay to the Payment Gateway in the DigitalWalletPayload field for authentication.

This will cater for both PAN_ONLY and CRYPTOGRAM_3DS authentication methods (described above in "Supported Authentication Methods").

• PAN_ONLY: the Payment Gateway performs a 3D Secure step-up flow by sending a request for customer authentication to Bankserv.
• CRYTOGRAM_3DS: this contains a 3DS cryptogram which means that no further customer authentication is required and the Payment Gateway will respond with a "Fully Authenticated" response.

Merchants Accepting Liability

If a merchant does not wish to implement a 3D Secure step-up flow for PAN_ONLY transactions, and is willing to accept financial liability in the possible case of chargebacks, then this can be configured in the merchant's Payment Gateway account. Please contact our Product Support team if you wish to accept liability for these transactions.

4.2 Payment Processing

Use the Payment Gateway Authorize API for dual messaging and Payment API for single messaging payments processing and ensure that the DigitalWalletPayload field is populated with the encrypted payload from Google Pay.

Integration Steps for Google Pay API

Ensure that you follow the guidance from Google Pay for your Web or Android integration listed below.

We have also included a summary of the steps required for your convenience.

Web Integration

• Ensure that you follow the brand guidelines for Google Pay Web integration.
• Follow the Google Pay Web developer documentation to implement your integration.
• Complete the Integration checklist to ensure that you've completed all the required steps in your web integration.

Android App Integration

• Ensure that you follow the brand guidelines for Google Pay Android integration.
• Follow the Google Pay Android developer documentation to implement your integration.
• Complete the Integration checklist to ensure that you've completed all the required steps in your Android integration.

Summary of integration steps

Step 1: Define your Google Pay API version

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

Step 2: Request a payment token: using the gateway Id and gatewayMerchantId that you received during Step 2 in Getting Started (above).

For example:

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'ecentric',	
    'gatewayMerchantId': 'exampleGatewayMerchantId'		/*Issued by our Product Support team*/
  }
};

Step 3: Describe your allowed payment methods: as defined above where

• allowedCardAuthMethods should be defined for CRYPTOGRAM_3DS and PAN_ONLY.
• allowedCardNetworks should be defined for VISA and MASTERCARD where the merchant accepts both of these.
• tokenizationSpecification is defined in the previous step.

📘

NOTE: Billing Address parameters are not required for Google Pay. Merchants can optionally send a customer's billing address in the Payment Gateway API Authorize or Payment methods.

For example:

const baseCardPaymentMethod = {
	type: 'CARD',
	parameters: {
		allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
		allowedCardNetworks: ['MASTERCARD', 'VISA']
	},
	tokenizationSpecification: tokenizationSpecification
};

Step 4: Include Google Pay JavaScript on your checkout page: for example

<script
  async
  src="https://pay.google.com/gp/p/js/pay.js"
  onload="console.log('TODO: add onload function')">
    </script>

Step 5: Initialize a PaymentsClient object: for example for TEST

const paymentsClient =
      new google.payments.api.PaymentsClient({environment: 'TEST'});

When your integration checklist has been completed then the PRODUCTION environment can be configured.

Step 6: Determine readiness to pay with the Google Pay API

• Add your allowed payment methods to your base request object.
• 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:

const isReadyToPayRequest = Object.assign({}, baseRequest);
isReadyToPayRequest.allowedPaymentMethods = [baseCardPaymentMethod];

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: ensuring that the Google brand guidelines are adhered to.

See the following payment button code sample:

const button =
    paymentsClient.createButton({onClick: () => console.log('TODO: click handler'),
    allowedPaymentMethods: []}); // same payment methods as for the loadPaymentData() API call
document.getElementById('container').appendChild(button);

Step 8: Create a PaymentDataRequest object

• Add the allowed payment methods supported by your app, such as any configuration of additional data that's expected in the response.
• Define a total price and currency (use ZAR) for a shopper to authorize.
• Provide a user-visible merchant name, and use our TEST merchantId value when in TEST.

const paymentDataRequest = Object.assign({}, baseRequest);

paymentDataRequest.allowedPaymentMethods = [cardPaymentMethod];

paymentDataRequest.transactionInfo = {
  totalPriceStatus: 'FINAL',
  totalPrice: '123.45',
  currencyCode: 'ZAR',
  countryCode: 'ZA'
};

paymentDataRequest.merchantInfo = {
  merchantName: 'Example Merchant',
  merchantId: '12345678901234567890'
};

Step 9: Register an event handler for user gestures

• Register a click event handler for the purchase button. The event handler calls loadPaymentData() immediately after it interacts with the Google Pay, payment button.
• 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.
• Extract the payment token from the paymentData response and pass this token without any modifications to the Payment Gateway using the Payment Gateway API as detailed in Step 4 above.

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);
});

Further optional steps can be found on the Google Pay developer documentation for Web and Android.

Testing

Testing Google Pay can be done in our Sandbox environment before enabling Google Pay in production.

Test Cards

The test cards that follow can be used to simulate different transaction outcomes.

📘

Test cards must be added to a Google Pay wallet signed in with a Google test account and used only in the Sandbox environment.