Google Pay™ for Web

Summary

Google Pay on the Web is a digital wallet that allows users to make online payments using compatible web browsers. Google Pay can be selected as a payment method at checkout and used to fulfill one-time payments.

This page covers everything needed to accept Google Pay payments through Preczn — from capabilities and requirements through to a full client-side implementation walkthrough.

Google Pay on the Web Capabilities

Topic	Support
Integration Method	Client-side (browser) script
Connections	Supported Connections
Supported Cards	American Express, Discover, Mastercard, UnionPay, and Visa
Countries	USA
Currencies	USD, CAD
Recurring	Not Supported
Devices	Google Pay can only be used in compatible web browsers: Google Chrome, Mozilla Firefox, Apple Safari, Microsoft Edge, Opera, and UCWeb UC Browser.
Acceptable Use Policy	Google Pay Acceptable Use Policy

Google Pay for Web Payment Flow

The Platform shows Google Pay as a payment option during checkout.
The user selects Google Pay as the payment option on the Platform checkout and completes steps on their device to authorize payment.
The payment information is encrypted by Google and securely transmitted to Preczn.
Preczn decrypts the Google Pay data and creates a single use token.
Preczn sends the single use token to the Platform.
The Platform creates a transaction using the single use token.

sequenceDiagram
    autonumber
    actor Shopper
    participant Platform
    participant Google as Google Pay
    participant Preczn

    Platform->>Shopper: Show Google Pay at checkout
    Shopper->>Google: Select Google Pay and authorize on device
    Google->>Preczn: Send encrypted payment data
    Note over Preczn: Decrypt data and create<br/>single-use token
    Preczn->>Platform: Return single-use token
    Platform->>Preczn: Create transaction with token (Process Transaction API)

Google Pay for Web Requirements

Preczn abstracts most of the Google Pay Integration Checklist for you. Your remaining responsibilities are mainly about branding and presentation.

Your responsibilities

Adhere to the Google Pay APIs Acceptable Use Policy and the Google Pay API Terms of Service.
Use only approved Google Pay assets and follow the Google Pay Brand guidelines.
Display Google Pay on parity with your other third-party payment methods.
Show the user a final price before the transaction is processed. If the amount can vary based on data returned from the Google Pay API, present a confirmation page with the final price.

Handled by Preczn

Keeping your existing risk checks and controls in place across all payment method types.
Confirming the card networks and authentication methods your payment processor accepts in your country.
Annually rotating encryption keys and providing our PCI Attestation of Compliance to Google.

You can skip testing the following Google Pay features, which Preczn does not currently support:

Google Pay for Android (in-app payments)
Dynamic price updates
Requesting the cardholder's telephone number
Requesting a shipping address separate from billing, or presenting shipping options in Google Pay

Preczn's Google Pay client is a client-side (browser) script which reduces the complexity of integrating to Google Pay for Web for transaction processing with Preczn.

You add a single <div> element to your page and Preczn renders the Google Pay button inside a secure Preczn-hosted iframe that is mounted into that div. Once a Google Pay payment method is obtained the Preczn client generates a secure single-use merchant-specific token, which you can then safely transmit from your client-side web application to your server-side for use processing a transaction.

📱 Implementing Google Pay

For a quick implementation crash course on the Preczn Google Pay client, see the following recipe:

1. Add the Google Pay button to your page

Add a <div> element with the data-preczn="googlepay" attribute on your page where you would like the Google Pay button displayed:

<div data-preczn="googlepay"></div>

📘
Use a div element specifically
The Preczn client locates the mount point using the [data-preczn="googlepay"] attribute selector and expects to find exactly one <div> element with this attribute. Place exactly one such <div> on your page. When initGooglePayButton is called, Preczn mounts a secure hosted <iframe> into that <div> and renders the Google Pay button, SDK, and payment sheet entirely inside the iframe — isolated from your merchant page.

❗ Your website must comply with the Google Pay acceptable use policy. For more information, see Google's Acceptable Use Policy for Google Pay API.

2. Include the Preczn client on your page

Add the secure Preczn JavaScript client reference to the <head> of your page:

<script
  fetchpriority="high"
  src="https://api.preczn.com/v1/clients/preczn.min.js?resources=googlepay&merchantId=mid_2zyd88xrnr90xskmjmqpd0x1vj&publicApiKey=2482re32338cd9z5048v7bhmb5"
></script>

The following query parameters appended the script src URL are required:

Parameter	Description
`merchantId`	The Preczn merchant ID for which you want to display the Google Pay button.
`publicApiKey`	Your platform public API key for authentication.
`resources`	A comma-delimited list of the client-side resources which you choose to utilize from the Preczn client. For Google Pay, include `googlepay` in this value.

❗️
Public Key Authentication
Ensure that you're using a public API key with the Preczn client, and not exposing and potentially compromising a sensitive private API key!

2.1. (Optional) Confirm all requisite Google Pay resources have loaded and initialized

Preczn provides 2 mechanisms to ensure the Preczn client and the Google Pay SDK have completed loading and initialization:

The Preczn.GooglePay.ready value.
1. If Preczn?.GooglePay?.ready is true you can proceed to initialize the Google Pay button with the Preczn client.
2. If the value is false or undefined then the resources have not yet loaded.
A Preczn.GooglePay.ready event on the document object.
1. When the Preczn client has completed loading requisite resources (such as the Google Pay SDK) and initialization, it will dispatch an Event of the type Preczn.GooglePay.ready on the document.
2. Add an event listener for the Preczn.GooglePay.ready event on document to be notified when loading and initialization have completed, then initialize the Google Pay button .
```
document.addEventListener(
  "Preczn.GooglePay.ready",
  (e) => {
    // Preczn and Google Pay SDKs loaded, initialize Google Pay button
    Preczn.GooglePay.initGooglePayButton(123, callback);
  },
  false,
);
```
3. ℹ️ If you subscribe to the Preczn.GooglePay.ready event, be sure to add your event listener to document before including the Preczn client on your page to avoid any chance the event is dispatched before the event listener is defined.

3. Define the required JavaScript callback function

Define a JavaScript callback function to handle tokenization result or errors:

var googlepayCallback = function (result, errors) {
  if (!errors) {
    // Utilize resulting Preczn single-use token here
    var precznToken = result.token;
  } else {
    console.error(`Google Pay errors:\r\n - ${errors.join("\r\n - ")}`);
  }
};

Callback function parameters

If no errors occurred the errors parameter value will be null, otherwise errors will contain an array of strings describing any error conditions.

Upon success Preczn creates a single-use merchant-specific token representing the Google Pay payment method and provides it in the callback result object. The callback result parameter object will consist of following properties:

Property	Description
`walletType`	The `walletType` property of the single use token which was created. Always `GOOGLEPAY`.
`type`	The account type of the card which the token represents: `CREDIT` or `DEBIT`.
`brand`	The brand of the card which the token represents: `VISA`, `MASTERCARD`, `AMEX`, `DISCOVER`, `DINERS`, `JCB`, `UNIONPAY`, or `OTHER`.
`bin`	The bank identification number (BIN) of the card which the token represents. Typically the first 6 digits of the card number.
`last4`	The last 4 digits of the card number which the token represents.
`token`	The Preczn token ID for the single-use, merchant-specific token representing this Google Pay payment method.
`billingContact` †	Object containing details about the billing contact associated with the payment method.
`billingContact.address`	Account holder's Address line 1.
`billingContact.address2`	Account holder's address line 2.
`billingContact.city`	Account holder's city.
`billingContact.region`	Account holder's region or state.
`billingContact.postal`	Account holder's postal or zip code.
`billingContact.country`	Account holder's ISO 3166-1 alpha-3 country code.
`billingContact.email`	Account holder's email address.

† If made available by Google Pay, the billingContact data will be included in the result object. (Preczn always sends the value FULL to Google Pay in the BillingAddressParameters format request field.)

Example result object:

{
  "walletType": "GOOGLEPAY",
  "type": "CREDIT",
  "brand": "VISA",
  "bin": "432100",
  "last4": "0012",
  "expiration": "1234",
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "token": "tkn_apkwm89dr8br9zvqw4b3xgktk",
  "billingContact": {
    "firstName": "Bob",
    "lastName": "Smith",
    "address": "1600 Amphitheatre Parkway",
    "address2": "Suite 1",
    "city": "Mountain View",
    "region": "CA",
    "postal": "94042",
    "country": "USA",
    "email": "[email protected]"
  }
}

📘
Google Pay Preczn Tokens are Single-use Only and Merchant-specific
Note that Preczn tokens returned for Google Pay payment methods are merchant-specific and single-use only. Due to the nature of the underlying data, a multi-use token cannot be returned when the token is used for a transaction. Therefore it is advised that these tokens not be stored as card-on-file and not be used for a verify type transaction. Instead these tokens should be used to conduct a 'final' transaction such as a sale type transaction.

Callback errors

🛑 The following are errors which the Preczn Google Pay client may send to your callback function:

Invalid API Key
- Invalid Preczn public API key provided in publicApiKey query string parameter.
Invalid Merchant ID
- Invalid Preczn merchant ID provided in merchantId query string parameter.
Unauthorized Request
- HTTP 401 or 403 response received from Preczn API during attempt to validate merchant payment session or tokenize Google Pay payment data. Confirm public API key and merchant ID values and try again. Contact Preczn support if the problem persists.
Google Pay not enabled for merchant
- The merchant has had Google Pay disabled, review the merchant settings and contact Preczn support if the problem persists.
Google Pay can only be initialized on a secure (HTTPS) connection
- Google Pay will only work when the button is served via secure HTTPS connection.
No Google Pay container element found on page
- The Preczn client found no <div data-preczn="googlepay"> element on your page. Ensure you have exactly one such <div> on your page.
Google Pay merchant ID not configured for this merchant
- The merchant has no Google merchant ID configured in their Preczn wallet settings. Review merchant settings or contact Preczn support.
Failed to decrypt and tokenize Google Pay payment data
- The Preczn API failed to decrypt the Google Pay payment data and create a single-use token from the result. Try again and contact Preczn support if the problem persists.

4. Initialize the Google Pay button with the Preczn client

Call the Preczn JavaScript client to initialize the Google Pay button:

<script type="text/javascript">
  Preczn.GooglePay.initGooglePayButton(123, callback);
</script>

The initGooglePayButton function takes up to 5 parameters, in this order:

Parameter	Type	Description
Amount †	`Number`	The amount to charge for the transaction as a whole integer ($1.00 is `100`).
Callback Function †	`function`	The function which is called when a single-use token is successfully generated for a cardholder's Google Pay payment method, or upon errors.
Country Code	`string` enum value	ISO 3166-1 alpha-2 country code. Defaults to `US`.
Currency Code	`string` enum value	ISO-4217 3-character currency code. Defaults to `USD`.
Options	`object`	Optional button styling. See Customize the button's appearance below.

† Denotes a required parameter.

Customize the button's appearance (optional)

By default the button renders with Google's standard "Buy with G Pay" label. To control its appearance, pass an optional trailing options object as the fifth argument to initGooglePayButton. The existing four-argument call is unchanged, so current integrations keep working without any modification.

<script type="text/javascript">
  // Default — renders Google's "Buy with G Pay"
  Preczn.GooglePay.initGooglePayButton(123, callback);

  // With styling — renders "Pay"
  Preczn.GooglePay.initGooglePayButton(123, callback, "US", "USD", {
    buttonType: "pay",            // label shown on the button
    buttonColor: "black",         // default | black | white
    buttonSizeMode: "fill",       // static | fill — fill requires a sized container (see note below)
    buttonLocale: "en",           // 2-letter language code
    buttonRadius: 4,              // corner radius in px (0 = square corners)
    buttonBorderType: "no_border" // no_border | default_border
  });
</script>

You can pass any subset of these keys. Any key you omit falls back to Google's own default for that property.

Option	Accepted values	Google default
`buttonType`	`book`, `buy`, `checkout`, `donate`, `order`, `pay`, `plain`, `subscribe`	`buy` ("Buy with G Pay")
`buttonColor`	`default`, `black`, `white`	`default`
`buttonSizeMode`	`static`, `fill`	`static`
`buttonLocale`	ISO 639-1 language code (e.g. `en`, `es`, `fr`)	browser/Google default
`buttonRadius`	number — corner radius in px (`0` = square corners)	Google default radius
`buttonBorderType`	`no_border`, `default_border`	`default_border`

📘
Styling values are forwarded as-is
Preczn forwards these values to Google's <google-pay-button> component without validation. These six keys are the complete set of appearance attributes the component exposes — there is no arbitrary CSS surface. An unsupported value (for example, an unrecognized buttonType) is passed straight through and handled by the component itself.

📘
Sizing the button with buttonSizeMode: "fill"
By default (buttonSizeMode: "static") the button renders at Google's standard size, and your [data-preczn="googlepay"] container does not need an explicit size.
With buttonSizeMode: "fill" the button sizes itself to fill your [data-preczn="googlepay"] container on both axes, so you can size the button to your checkout layout with CSS. When using fill you must give the container an explicit width and height — if the container has no height, the button collapses and will not render.
<div data-preczn="googlepay" style="width: 320px; height: 48px;"></div>

🧪 Testing Google Pay

Preczn Test Mode configurations utilize the Google Pay test mode sandbox. See the Google Pay mock test cards page for information regarding test card data to use for testing google pay in test mode.

Using with a Content Security Policy

If you are using a Content Security Policy to secure your client-side web application, you will need to extend your policy to allow preczn.min.js to load and connect to the Preczn API.

The Preczn-hosted checkout iframe is embedded from api.preczn.com (hence frame-src api.preczn.com), and the Google Pay SDK and button resources load inside that iframe.

Please add the following directives to your content security policy:

Directive	Value
`script-src`	`api.preczn.com pay.google.com`
`connect-src`	`api.preczn.com pay.google.com www.google.com google.com`
`frame-src`	`api.preczn.com pay.google.com`
`img-src`	`www.gstatic.com`

💳 Process a Google Pay Transaction

In order to process a transaction using the Google Pay data you receive from this integration, send the merchant-specific single-use token and customer billing information, which you obtained from the client-side, to the Process Transaction API endpoint.

Frequently Asked Questions

Do I need to obtain a Google Pay merchant ID?

No. Neither the platforms nor their merchants need to register with Google or obtain a Google Pay (Google) merchant ID. Preczn manages the Google Pay merchant configuration on your behalf — you only need the Preczn merchant ID and public API key to initialize the button.

Can I make the button say "Pay" instead of "Buy with G Pay"?

Yes. Pass an options object as the fifth argument to initGooglePayButton with buttonType: "pay". See Customize the button's appearance for the full list of styling options.

Can I style the button with my own CSS?

No. The button renders inside a secure Preczn-hosted iframe, so your page's CSS does not reach it. You can only adjust the six appearance attributes Google's <google-pay-button> component exposes (buttonType, buttonColor, buttonSizeMode, buttonLocale, buttonRadius, buttonBorderType) via the options argument — there is no arbitrary CSS surface.

Can I size the button to fit my own container?

Yes — use buttonSizeMode: "fill", which sizes the button to your [data-preczn="googlepay"] container so you can control it with CSS. In fill mode the container must have an explicit width and height (e.g. style="width: 320px; height: 48px;"). Use static mode (the default) to render the button at its standard size with no container sizing required.

My button disappeared after I set buttonSizeMode: "fill". Why?

fill mode sizes the button to your [data-preczn="googlepay"] container. If that container has no explicit width and height, it collapses to zero and the button has nothing to fill, so nothing renders. Give the container a size via CSS (e.g. style="width: 320px; height: 48px;"), or use static mode, which renders the button at its default size with no container sizing required.

Can I save the Google Pay token to charge the customer again later?

No. Preczn tokens for Google Pay payment methods are single-use and merchant-specific, and recurring payments are not supported. Use the token to conduct a single 'final' transaction such as a sale; do not store it as card-on-file or use it for a verify type transaction.

Google Pay™ for Web

Summary

Google Pay on the Web Capabilities

Google Pay for Web Payment Flow

Google Pay for Web Requirements

📱 Implementing Google Pay

1. Add the Google Pay button to your page

Use a `div` element specifically

2. Include the Preczn client on your page

Public Key Authentication

2.1. (Optional) Confirm all requisite Google Pay resources have loaded and initialized

3. Define the required JavaScript callback function

Callback function parameters

Google Pay Preczn Tokens are Single-use Only and Merchant-specific

Callback errors

4. Initialize the Google Pay button with the Preczn client

Customize the button's appearance (optional)

Styling values are forwarded as-is

Sizing the button with `buttonSizeMode: "fill"`

🧪 Testing Google Pay

Using with a Content Security Policy

💳 Process a Google Pay Transaction

Frequently Asked Questions

Summary

Google Pay on the Web Capabilities

Google Pay for Web Payment Flow

Google Pay for Web Requirements

📱 Implementing Google Pay

1. Add the Google Pay button to your page

Use a div element specifically

2. Include the Preczn client on your page

Public Key Authentication

2.1. (Optional) Confirm all requisite Google Pay resources have loaded and initialized

3. Define the required JavaScript callback function

Callback function parameters

Google Pay Preczn Tokens are Single-use Only and Merchant-specific

Callback errors

4. Initialize the Google Pay button with the Preczn client

Customize the button's appearance (optional)

Styling values are forwarded as-is

Sizing the button with buttonSizeMode: "fill"

🧪 Testing Google Pay

Using with a Content Security Policy

💳 Process a Google Pay Transaction

Frequently Asked Questions

Use a `div` element specifically

Sizing the button with `buttonSizeMode: "fill"`