Google Pay™

Accept Google Pay on your website using Finix.


This guide details how to get started accepting Google Pay on web.

Make sure your website fulfils requirements before getting started.

Step 1: Add the Google Pay Library

First, load the Google Pay API JavaScript library into your app. You can add the Google Pay library by following these steps:

  1. Include this JavaScript in your website to add Google Pay's JavaScript Library so your website can make calls to Google Pay’s API.
    Copy
    Copied
    <script async src="https://pay.google.com/gp/p/js/pay.js" onload="onGooglePayLoaded()">
     function onGooglePayLoaded() {
       window.googlePayClient = new google.payments.api.PaymentsClient({
         environment: "TEST"
       });
     }
    </script>
  2. Once you've added the code and the library loads, create a PaymentsClient object.
    • For a sandbox environment, pass in TEST for environment. This returns test payment methods that can be used for sandbox transactions.
    • For a live environment, pass in LIVE for environment.
Copy
Copied
const paymentsClient =
    new google.payments.api.PaymentsClient({environment: 'TEST'});

Step 2: Define Google Pay API Version

After you've added the Google Pay API JavaScript library, declare the version of the Google Pay API that your site uses. The major and minor versions are required in the fields of each passed object and are included in the response. The following code sample shows the declared API versions.

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

Step 3: Request a Finix Payment Token

Now that you've defined your Google Pay API Version, request a Finix payment token.

Copy
Copied
const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'finix',
    'gatewayMerchantId': 'IDxxx'
  }
};

Request Arguments

Field Type Description
gateway string, required Pass in finix.
gatewayMerchantId string, required The Identity ID.

Step 4: Define Allowed Card Networks

Now that we've requested a Finix payment token, you can set which card networks will be accepted on your site by:

  • Defining allowedCardNetworks .
  • Defining allowedCardAuthMethods which sets the authentication methods supported by your site and gateway.
Copy
Copied
const allowedCardNetworks = ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"];
const allowedCardAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"];

For both PAN_ONLY and CRYPTOGRAM_3DS authorization methods, support for 3D Secure is dictated by the processors you integrate with in allowedCardNetworks. Finix accepts both PAN_ONLY and CRYPTOGRAM_3DS authorization methods.

Step 5: Describe Allowed Payment Methods

After you've defined the supported payment card networks, you need to describe your allowed payment methods. You can do this with the following steps:

  1. Combine allowedAuthMethods and allowedCardNetworks to describe how your site supports the CARD payment method.
  2. Extend the baseCardPaymentMethod object and describe the information you expect to be returned to your application. Include a description of the tokenized payment data.
Copy
Copied
const baseCardPaymentMethod = {
  type: 'CARD',
  parameters: {
    allowedAuthMethods: allowedCardAuthMethods,
    allowedCardNetworks: allowedCardNetworks
  }
};
const cardPaymentMethod = Object.assign(
  {tokenizationSpecification: tokenizationSpecification},
  baseCardPaymentMethod
);

Step 6: Check Readiness to Pay with Google Pay

Now that you've described your allowed payment methods, you need to check readiness to pay with the Google Pay API. To check readiness to pay with Google Pay's API:

  1. Add allowedPaymentMethods to the baseRequest object.
  2. Call isReadyToPay() to see if Google Pay's API is supported by the current device and browser for the payment methods specified.
Copy
Copied
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 the Google Pay Button

Now that you've checked readiness to pay with Google Pay API, you can add a Google Pay payment button to your website.

Copy
Copied
const button =
    paymentsClient.createButton({onClick: () => console.log('TODO: click handler'),
    allowedPaymentMethods: []}); // make sure to provide an allowed payment method
document.getElementById('container').appendChild(button);
Copy
Copied
<google-pay-button
  environment="TEST"
  button-color="default"
  button-type="subscribe"
></google-pay-button>

CSS Properties

Field Type Description
button-color string, optional Color of the button. Available values are default, black, and white.
button-type string, optional Available values are black, white, and white-outline.
button-locale string, required Set the language of the button. There's a variety of buttons that you can use on your website to begin the transaction. This includes: book, buy, checkout, donate, order, pay, plain, and subscribe.

Step 8: Create a Payment Data Request

After creating a Google Pay payment button, you need to create a PaymentDataRequest object. Follow these steps:

  1. Build a JavaScript object that describes your site's support for the Google Pay API. See the PaymentDataRequest object for a list of supported properties.
Copy
Copied
const paymentDataRequest = Object.assign({}, baseRequest);
paymentDataRequest.allowedPaymentMethods = [cardPaymentMethod];
paymentDataRequest.transactionInfo = {
  countryCode: 'US',
  currencyCode: 'USD',
  totalPrice: '123.45',
  totalPriceStatus: 'FINAL'
};
paymentDataRequest.merchantInfo = {
  merchantId: '12345678901234567890'
  merchantName: 'Example Merchant'
};

transactionInfo Request Arguments

Field Type Description
countryCode string, required The ISO country code.
currencyCode string, required The currency code of the locale.
totalPrice string, required Total value of the transaction with an optional decimal precision of two decimal places.
totalPriceStatus string, required The status of the total price used.
  • Pass FINAL if the total price doesn’t change from the amount presented to the buyer.
  • Pass ESTIMATED if the total price might adjust based on the details of the response, such as sales tax collected that’s based on a billing address.
  • Pass NOTCURRENTLYKNOWN when using totalPriceStatus for a capability check.

merchantInfo Request Arguments

Field Type Description
merchantID string, required A Google merchant identifier issued after registration with the Google Pay Business Console. Required when PaymentsClient is initialized with an environment property of LIVE.
merchantName string, required Pass in the name of the Merchant .
  1. Add the payment methods supported by your site and any configurations of additional data that are expected in the response.
  2. Set a totalPrice and currencyCode for the buyer to authorize.
  3. Provide a user-visible merchantName .
    • Use the TEST Merchant ID if you're in a sandbox environment.
info

Merchants that 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.

Step 9: Create a Payment

After calling loadPaymentData using the Google Pay payments client object, a token will be returned in that response.

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

Pass the third_party_token in and include a value for name when creating a Payment Instrument.

Copy
Copied
curl https://finix.sandbox-payments-api.com/payment_instruments \
-H 'Content-Type: application/json' \
-H 'Finix-Version:2022-02-01' \
-u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
    "identity": "ID78Fh8mcnnzukVzbdoyex5y",
    "merchant_identity": "IDwhCCvPwCDEmiFd8Be7pDzN",
    "name": "Finix Sandbox",
    "third_party_token": "{\"signature\":\"MEYCIQCYTkaEMgug7pcjzEEdbIn+R57kYO5yYc2KYj41AQQn9wIhAN1QvylvZ2XydVecfejwi2xYS9y3Y9y/MmDnRnUfNw5H\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE4xc3fjeM9SMTjd1TL2GQCPmgqPf2h42aM3akPh/mTUBqWEgOITruK10A02rQ+4YZOvLCpQKQZzLSAd09nctnuA\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1648843199734\\\"}\",\"signatures\":[\"MEQCICwCI4s5YCLu4qRCyXwSJ3qG8y3ocFtP1Mque4Uzysl8AiARoD/0qbj5W0Q2PWKpxkEnfcP+nU5kwYS8FyQ9boDTmQ\\u003d\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"roD4ikTpZ7Srunq+0zUnp+eiXzcuZBfIFSuZAJu1PQLXcP0RvnGDiGKtoarNCHvn+cnXsHCzIBWXMZSJ9Aglqky9VfP5a+qsXQhf5m5AFUbT2xnihtKwageGQQK6HzyjHSXXSjvuCzeo75ToOgIUxLFASZyaZ89u3Jifqhhc2c4a0Mtlx564BxXiwcxDFdtNkOle7uAIsJzsryk7Rcwgr8ZMJJM//XpvaeE5wNmkVFHUtR2uTqPm0BvkoYkFHCTRo4NHXWpxeLjXWzKGk2ELyTK1diuCa6c9ig0jO3t8BIh1cR63UeP8Ar7u5fh8C9FPPAsgPbTGLfiaRe615e4SxASgcZ4/8uWo5mikEPFqA5s2K2mid9ncXoMNYaHUc3qzJAyxHVYSd5SRNZYXHMkEcWcjnpDx+ErYjR1sMo1LMYXfrfGyZz3M69bQLKPYFe7ChjvgFI9MnfcFTNB4HAdNKMhbZT0EKinfxxGWkT7LVbGnUuqPlHp4toCe4kpbx7fulwXTj3bAFvg/qvxxwGOS38iP0HR/f+4GF0xHspqYVbdWdIJ5iJUdpBG8Nu5P56h2GEDxXMkKSmh+qbvKWlYipNNGoeg8uHc\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BMqIyb1IyXhuZ4YpWm1PiRr74i3tCwDfQqJ1P4OZ3zK4Rq16SuwgJ605fCEvlViwSQuo2Hpv+CcR+2D3+/YrLB8\\\\u003d\\\",\\\"tag\\\":\\\"5K4LlTucDK7jAThbIozYtyoxX95hRNd5cJJGfxWAxw8\\\\u003d\\\"}\"}",
    "type": "GOOGLE_PAY"
}'

Example Response

Copy
Copied
{
  "id" : "PIf8dyFFcEGBqPhaG22hPyYs",
  "created_at" : "2022-10-10T05:36:55.27Z",
  "updated_at" : "2022-10-10T05:36:55.27Z",
  "application" : "APeUfzF5qdNkBCtdgcf3333n",
  "created_via" : "API",
  "currency" : "USD",
  "enabled" : true,
  "fingerprint" : "FPRrcobjtdU98gr4sjiqYR1Qg",
  "identity" : "ID78Fh8mcnnzukVzbdoyex5y",
  "instrument_type" : "GOOGLE_PAY",
  "bin" : "411111",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "expiration_month" : 12,
  "expiration_year" : 2027,
  "issuer_country" : "UNKNOWN",
  "last_four" : "1111",
  "name" : "Finix Sandbox",
  "tags" : { },
  "type" : "GOOGLE_PAY",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIf8dyFFcEGBqPhaG22hPyYs"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIf8dyFFcEGBqPhaG22hPyYs/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIf8dyFFcEGBqPhaG22hPyYs/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIf8dyFFcEGBqPhaG22hPyYs/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUfzF5qdNkBCtdgcf3333n"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID78Fh8mcnnzukVzbdoyex5y"
    }
  }
}

Request Arguments

Field Type Description
identity string, required ID of the Identity that the card should be associated with.
merchant_identity string, required The merchant_identity_id used when registering the business with Google Pay through our registration API.
name string, required Full name of the registered card holder.
third_party_token string, required Stringified token provided by Google. Required to process Google Pay transactions.
type string, required Type of Payment Instrument. Use GOOGLE_PAY for transactions using Google Pay.

For security purposes, Google Pay tokens are only active for a short period of time.

Due to this limited lifetime, the third_party_token used in the request above has expired. To test the request, use your third_party_token and Finix credentials.

Once complete, similar to other Finix transactions, you can create a transfer or an authorization.