Skip to content

Google Pay on Web

Let buyers pay with Google Pay on your website, using any debit or credit card saved to their Google account.

Overview

To add Google Pay to your website, you load the Google Pay JavaScript library, configure the payment methods and tokenization your site accepts, and add the Google Pay button. When a buyer pays, you process the resulting token with the Finix API.

After setup, buyers can complete checkout with Google Pay and you process the payment like any other Finix transaction.

Collect the billing address to avoid extra fees

Finix recommends passing the address field shown in the steps below. If you do not pass the address, the card network charges additional dues and assessments per transaction.

Prerequisites

Before you start, familiarize yourself with the Google Pay requirements for Finix, including the Finix API key, seller onboarding, and Google Pay merchant account steps.

Google Pay demo

See a live demo of Google Pay on the Finix sample store. All of the sample store code is available in the accept-a-payment GitHub project.

In the sample store, add a few items to your cart and click Checkout with Tokenization Form.

Sample store checkout with a tokenization form and express checkout option

An express checkout button brings up the Google Pay modal.

Express checkout with the Google Pay button

The sample store uses Sandbox credentials, so you are not charged.

Google Pay payment modal in the sample store

Integration steps

Step 1: Add the Google Pay library

First, load the Google Pay API JavaScript library into your site.

  1. Include the following script in your website so your site can call the Google Pay API.
Google Pay JS Script
<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>
  1. After the library loads, create a PaymentsClient object.
    • For a Sandbox environment, use environment: "TEST". This returns test payment methods for Sandbox transactions.
    • For a Live environment, use environment: "PRODUCTION".
Google Pay PaymentsClient Object
const paymentsClient = new google.payments.api.PaymentsClient({
  environment: "TEST",
});

Step 2: Define the Google Pay API version

After you add the library, declare the version of the Google Pay API that your site uses. The major and minor versions are required in each passed object and are included in the response.

Google Pay API Version
const baseRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
};

Step 3: Request a Finix payment token

Configure the tokenization specification so Google Pay returns a Finix payment token.

  • Set gateway to finix.
  • Set gatewayMerchantId to the application owner Identity or merchant owner Identity. To choose the appropriate Identity ID, see Choose a Merchant identifier value.
Google Pay Tokenization Specification
const tokenizationSpecification = {
  type: "PAYMENT_GATEWAY",
  parameters: {
    gateway: "finix",
    gatewayMerchantId: "IDxxx",
  },
};

Step 4: Define allowed card networks

Set which card networks your site accepts:

  • Define allowedCardNetworks to list the accepted networks.
  • Define allowedCardAuthMethods to set the authentication methods your site and gateway support.
Google Pay Allowed Card Networks
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 depends on 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 define the supported card networks, describe your allowed payment methods:

  1. Combine allowedAuthMethods and allowedCardNetworks to describe how your site supports the CARD payment method.
  2. Extend the baseCardPaymentMethod object with the information you expect returned to your site, including a description of the tokenized payment data.
Google Pay Payment Methods
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

After you describe your allowed payment methods, check readiness to pay with the Google Pay API:

  1. Add allowedPaymentMethods to the baseRequest object.
  2. Call isReadyToPay() to check whether the current device and browser support the Google Pay API for the payment methods you specified.
Google Pay Readiness Check
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

After you check readiness to pay, add a Google Pay payment button to your website.

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

The button element supports the following attributes.

FieldTypeDescription
button-colorstring, optionalColor of the button. Available values are default, black, and white.
button-typestring, optionalThe button type that initiates the transaction. Available values include book, buy, checkout, donate, order, pay, plain, and subscribe.
button-localestring, requiredThe language of the button.

Step 8: Create a payment data request

After you add the Google Pay button, create a PaymentDataRequest object.

  1. Build a JavaScript object that describes your site's support for the Google Pay API. For the supported properties, see the PaymentDataRequest object.
paymentDataRequest
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",
};

The transactionInfo object accepts the following arguments.

FieldTypeDescription
countryCodestring, requiredThe ISO country code.
currencyCodestring, requiredThe currency code of the locale.
totalPricestring, requiredTotal value of the transaction, with optional decimal precision of two places.
totalPriceStatusstring, requiredThe status of the total price. Pass FINAL if the total price does not change from the amount presented to the buyer. Pass ESTIMATED if the total price might adjust based on the response, such as sales tax based on a billing address. Pass NOT_CURRENTLY_KNOWN when using totalPriceStatus for a capability check.

The merchantInfo object accepts the following arguments.

FieldTypeDescription
merchantIdstring, requiredA Google merchant identifier issued after registration with the Google Pay Business Console. Required when PaymentsClient is initialized with an environment property of PRODUCTION.
merchantNamestring, requiredThe name of the Merchant.
  1. Add the payment methods your site supports and any additional data you expect in the response.
  2. Set a totalPrice and currencyCode for the buyer to authorize.
  3. Provide a buyer-visible merchantName. In a Sandbox environment, use the TEST Merchant ID.
Strong Customer Authentication (SCA)

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

Step 9: Use a Buyer Identity

A Buyer Identity is required before you can process a payment. You can create a new Buyer Identity with the Finix API, or use an existing one.

Buyer Identity data

All Buyer Identity fields are optional. Finix recommends including basic information (name, email, address, and phone) to make payment operations easier.

To find and reuse an existing Buyer Identity:

  1. Log in to your Finix Dashboard.
  2. In the left sidebar, select Data Resources → Identities.
  3. Search for the Buyer Identity you want to use, and confirm its Role is Buyer.
  4. Copy the Buyer Identity ID (for example, IDjWktr7BPDGhz4amrPJZoXg).

Step 10: Create a Payment Instrument

After you call loadPaymentData using the Google Pay payments client object, the response returns a token.

paymentsClient paymentToken
paymentsClient
  .loadPaymentData(paymentDataRequest)
  .then(function (paymentData) {
    // if using gateway tokenization, pass this token without modification
    paymentToken = paymentData.paymentMethodData.tokenizationData.token;
    // for billing details
    name = paymentData.paymentMethodData.info.billingAddress.name;
    address = {
      postal_code: paymentData.paymentMethodData.info.billingAddress.postalCode,
      country: paymentData.paymentMethodData.info.billingAddress.countryCode,
    };
  })
  .catch(function (err) {
    // show error in developer console for debugging
    console.error(err);
  });

Pass the third_party_token, address, and name when creating a Payment Instrument.

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/payment_instruments \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "address": {
      "city": "San Francisco",
      "country": "USA",
      "line1": "900 Metro Center Blv",
      "line2": "APT 200",
      "postal_code": "94404",
      "region": "CA"
    },
    "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"
  }'

A successful request returns the newly created Payment Instrument, which you use to process the payment.

Payment Instrument - Google Pay
{
  "id": "PIwpqpJZCharsZAt6WKVopPS",
  "created_at": "2025-05-08T18:44:58.56Z",
  "updated_at": "2025-05-08T18:44:58.56Z",
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_via": "API",
  "currency": "USD",
  "disabled_code": null,
  "disabled_message": null,
  "enabled": true,
  "fingerprint": "FPR88YBDbK4TqYMUNU8t8fbeQ",
  "identity": "IDmj1yA97RS4rMjiQgvK3Vio",
  "instrument_type": "APPLE_PAY",
  "address": {
    "line1": "900 Metro Center Blv",
    "line2": "APT 200",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94404",
    "country": "USA"
  },
  "bin": "370382",
  "brand": "AMERICAN_EXPRESS",
  "card_type": "CREDIT",
  "expiration_month": 11,
  "expiration_year": 2024,
  "issuer_country": "USA",
  "last_four": "8576",
  "name": "John Smith",
  "tags": {},
  "third_party": null,
  "third_party_token": null,
  "type": "GOOGLE_PAY",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwpqpJZCharsZAt6WKVopPS"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwpqpJZCharsZAt6WKVopPS/authorizations"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwpqpJZCharsZAt6WKVopPS/transfers"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwpqpJZCharsZAt6WKVopPS/verifications"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio"
    }
  }
}

For security, Google Pay tokens are active for only a short period of time. The third_party_token in the request above has expired. To test the request, use your own third_party_token and Finix credentials.

Step 11: Create a payment

After the Payment Instrument is created, use it to create a Transfer or an Authorization, the same as any other Finix transaction.

To process a sale:

  1. Set the source to the buyer's Payment Instrument ID.
  2. Set the merchant to an APPROVED Merchant account.
  3. Set the amount in cents.
Example Transfer Request
curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
        "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
        "currency": "USD",
        "amount": 662154,
        "source": "PIwpqpJZCharsZAt6WKVopPS"
    }'
Example Transfer Response
{
  "id": "TR29av3LN1TAGPbXscsup1tt",
  "amount": 662154,
  "tags": {},
  "state": "SUCCEEDED",
  "trace_id": "34f40e87-2599-414b-874b-f472790ff521",
  "currency": "USD",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "source": "PIwpqpJZCharsZAt6WKVopPS",
  "destination": null,
  "ready_to_settle_at": null,
  "externally_funded": "UNKNOWN",
  "fee": 0,
  "statement_descriptor": "FNX*FINIX FLOWERS",
  "type": "DEBIT",
  "messages": [],
  "raw": null,
  "created_at": "2022-08-25T20:39:37.59Z",
  "updated_at": "2022-08-25T20:39:38.17Z",
  "idempotency_id": null,
  "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
  "merchant_identity": "IDpYDM7J9n57q849o9E9yNrG",
  "subtype": "API",
  "failure_code": null,
  "failure_message": null,
  "additional_buyer_charges": null,
  "_links": {
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "self": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/payment_instruments"
    },
    "reversals": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/reversals"
    },
    "fees": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/fees"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/disputes"
    },
    "source": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwpqpJZCharsZAt6WKVopPS"
    },
    "fee_profile": {
      "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
    }
  }
}

Alternatively, create an Authorization and capture it later with two separate API calls. This is useful when you need to verify the payment details first and capture a specific amount later. For more information, see Creating and capturing an Authorization.

Next steps

Refunds

Refund all or part of a Google Pay payment.

Disputes

Respond to buyer disputes on Google Pay transactions.

Google Pay on Android

Accept Google Pay in your Android application using Finix.