> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Pay™

> Accept Google Pay through Clink Hosted Checkout or Elements, with gateway configuration and PAN_ONLY authentication requirements.

Google Pay™ lets customers pay with cards saved to their Google Account or device. Use [Hosted Checkout](/build-integration) or [Elements](/elements) to accept these payments through Clink.

<Note>
  **Clink gateway activation:** the `clink` gateway configuration below requires separate production activation. Ask Clink to confirm activation for your account before using it. Existing Google Pay integrations may use a linked PSP gateway; do not replace that gateway with `clink` yourself.
</Note>

## Before you integrate

1. Ask Clink to enable Google Pay for your merchant account and confirm your processing route, accepted card networks, payment currencies, and settlement countries. Availability depends on the account and route; a network requested in Google Pay is not a guarantee that a transaction can be processed.
2. Confirm your `PAN_ONLY` risk and 3D Secure (3DS) configuration with Clink. The policy is the same as for ordinary card payments: selectively request 3DS based on risk, including any authentication required for the transaction.
3. Use matching [sandbox API keys and endpoints](/integration). Your server uses the Secret Key; Elements uses the Publishable Key.

<Note>
  All merchants using Hosted Checkout or Elements must follow the [Google Pay and Wallet API Acceptable Use Policy](https://payments.developers.google.com/terms/aup) and accept the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos).
</Note>

## Choose an integration path

| Path | Merchant implementation | Google Pay handling |
| - | - | - |
| Hosted Checkout | Create a Session on your server and redirect the customer to the returned `url` | Clink hosts the payment button, collects the Google Pay response, submits the payment, and handles required authentication |
| Elements | Create a Session on your server, initialize Elements, and mount `paymentMethod` | Clink's embedded checkout renders the button and handles the Google Pay response and required authentication |

This guide covers Web integrations. It does not define a native Android integration.

### Hosted Checkout

Use `uiMode: "hostedPage"`. No Google Pay JavaScript library, Google request objects, or Google Merchant ID are required in your own website code for this path. Redirect to the Session URL; do not embed the hosted page in a custom iframe.

### Elements

Use `uiMode: "elements"` and supply `returnUrl`. Follow the [Elements installation and mounting instructions](/elements). Pin the SDK version tested by your application; Clink must confirm a compatible SDK and account configuration when activating the `clink` gateway.

Elements loads the Google Pay client and generates `IsReadyToPayRequest` and `PaymentDataRequest` inside the Clink-controlled checkout. You do not generate those requests, load a second Google Pay client, or pass a Google Merchant ID to `loadClinkElements()`.

If your site restricts third-party content through Content Security Policy, allow the Elements iframe origin in `frame-src` and the Clink API origin in `connect-src` for your environment. `loadClinkElements()` sends an initialization request to the API from your page before creating the iframe, so both origins must be allowed:

| Environment | Elements iframe origin (`frame-src`) | Clink API origin (`connect-src`) |
| - | - | - |
| Sandbox | `https://uat-elements.clinkbill.com` | `https://uat-api.clinkbill.com` |
| Production | `https://elements.clinkbill.com` | `https://api.clinkbill.com` |

Merge the matching origins into your existing policy. For example, the sandbox directives can include:

```text theme={null}
frame-src 'self' https://uat-elements.clinkbill.com;
connect-src 'self' https://uat-api.clinkbill.com;
```

Use both production origins when switching environments. Hosted Checkout uses the separate `uat-checkout.clinkbill.com` and `checkout.clinkbill.com` domains for redirects. Channel-specific 3DS flows may require additional iframe origins; obtain those requirements from Clink during activation. Check that checkout and authentication resources load without CSP errors before launch. The container must allow the checkout and 3DS UI to expand; see [Elements layout requirements](/elements#7-implementation-constraints).

## Gateway and merchant identifiers

The following values apply to an account activated for the **Clink gateway**:

| Google Pay field | Value | How to obtain it |
| - | - | - |
| `tokenizationSpecification.type` | `PAYMENT_GATEWAY` | Use the gateway integration type |
| `tokenizationSpecification.parameters.gateway` | `clink` | Clink's registered Google Pay gateway ID |
| `tokenizationSpecification.parameters.gatewayMerchantId` | The unique merchant identifier assigned by Clink for this integration | Obtain the environment-specific value from Clink during activation |
| `merchantInfo.merchantId` | The Google-issued Merchant ID for the production integration | Configured by Clink for its hosted or embedded checkout |

`gatewayMerchantId` and Google's `merchantId` are different identifiers. Do not substitute an order ID, customer ID, API key, or a linked PSP's merchant ID. Google onboarding sample values such as `googletest` are not merchant production identifiers.

Hosted Checkout and Elements receive gateway configuration from the Session. Merchants do not set these fields in the Create Session API or change them in the browser. This example shows the Google request configuration for an activated Clink gateway; it is not an additional merchant-side API call:

```json theme={null}
{
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "clink",
      "gatewayMerchantId": "<CLINK_ASSIGNED_GATEWAY_MERCHANT_ID>"
    }
  }
}
```

## Card credentials and 3DS

Google Pay can return two authorization methods. Enable only the methods approved for your account and processing route.

| Method | Credential | Authentication policy |
| - | - | - |
| `PAN_ONLY` | Card details saved to a Google Account | Apply the same risk-based 3DS criteria as ordinary card transactions. Google Pay does not replace cardholder step-up authentication for this method |
| `CRYPTOGRAM_3DS` | A device token with a payment cryptogram | Submit the token and cryptogram through the enabled processing route. Do not treat it as a `PAN_ONLY` card or impose the ordinary `PAN_ONLY` 3DS flow solely because Google Pay was selected |

To enable 3DS for `PAN_ONLY`, ask Clink to apply your ordinary-card risk and 3DS settings to Google Pay `PAN_ONLY` on the intended processing routes. Confirm this configuration before production activation. There is no Google Pay 3DS switch in the public Create Session request.

When step-up authentication is required, Hosted Checkout and Elements handle the customer interaction. Keep the payment open until the authentication and authorization finish. A Google Pay sheet closing, an SDK event, or a return redirect does not establish payment success; verify the server-side Order status or a signed `order.succeeded` webhook.

Settlement-country and currency eligibility must be confirmed separately for both authorization methods. Do not infer it from the customer's device, card issuer country, or Google's `countryCode`. See Google's [PSP step-up guidance](https://developers.googleblog.com/en/when-to-step-up-your-google-pay-transactions-as-a-psp/).

## Card networks and billing address

The Web checkout request includes these Google network values: `AMEX`, `DISCOVER`, `INTERAC`, `JCB`, `MASTERCARD`, and `VISA`. This is the request's network range, not a promise of processing or settlement support for every account. Ask Clink to confirm the supported subset and settlement countries for your route before launch.

Before activating the Clink gateway in production, Clink must confirm that `allowedCardNetworks` and `allowedAuthMethods` reflect the approved networks and authorization methods for the integration. This is an activation requirement, not a merchant-side configuration switch. Hosted Checkout and Elements own these request objects; merchants do not pass these arrays to the Create Session API.

The current Web checkout does not request a billing address in the Google Pay sheet (`billingAddressRequired` is not enabled). Clink may collect billing details separately in checkout for tax or processing requirements. Complete those fields when shown. Do not assume that the Google token contains a postal address or phone number.

If your processing route requires address verification, confirm the required address fields with Clink before activation. A separate Google request implementation that collects an address must use [`BillingAddressParameters`](https://developers.google.com/pay/api/web/reference/request-objects#BillingAddressParameters), including the required address format and whether a phone number is needed.

## Submit a transaction

### 1. Create a Checkout Session on your server

This is the merchant API call for both integration paths. The example uses sandbox configuration and a one-time USD 19.99 purchase. `originalAmount` and `unitAmount` use major currency units.

```bash theme={null}
# CLINK_SECRET_KEY is your sandbox Secret Key stored on the server.
curl --request POST 'https://uat-api.clinkbill.com/api/checkout/session' \
  --header "X-API-Key: ${CLINK_SECRET_KEY}" \
  --header "X-Timestamp: $(node -p 'Date.now()')" \
  --header 'Content-Type: application/json' \
  --data '{
    "customerEmail": "customer@example.com",
    "merchantReferenceId": "merchant_order_123",
    "originalAmount": 19.99,
    "originalCurrency": "USD",
    "paymentMethodType": "GOOGLEPAY",
    "uiMode": "hostedPage",
    "successUrl": "https://merchant.example.com/success",
    "cancelUrl": "https://merchant.example.com/cancel",
    "priceDataList": [
      {
        "name": "One-time purchase",
        "quantity": 1,
        "unitAmount": 19.99,
        "currency": "USD"
      }
    ]
  }'
```

Use a fresh millisecond `X-Timestamp` for every request. See [API Keys & Webhooks](/integration) and [Create checkout session](/api-reference/endpoint/create-checkout-session) for authentication and the full contract.

`paymentMethodType: "GOOGLEPAY"` selects Google Pay when available; it does not enable an unconfigured method. Do not include `GOOGLEPAY` in `paymentMethodTypeBlackList`. `merchantReferenceId` is for reconciliation and is not an idempotency key.

If you do not want cards saved through Google Pay to appear in the `CARD` bound-card list, set `filterGooglePayBoundCard: true` when creating the Session. The default is `false`. This filters only that list; it does not disable an otherwise available `GOOGLEPAY` payment method.

For Hosted Checkout, redirect to `data.url`. For Elements, change the request to `uiMode: "elements"`, provide `returnUrl`, and return only `data.sessionId` to your frontend.

### 2. Render the payment interface

For Elements, initialize with the Publishable Key from your application configuration:

```javascript theme={null}
import { loadClinkElements } from '@clink-ai/clink-elements';

const clink = await loadClinkElements({
  sessionId, // Created by your server
  publishKey: PUBLIC_CLINK_PUBLISHABLE_KEY, // Sandbox key: pk_uat_…
  environment: 'sandbox',
});

clink.on('submit-visible', (visible) => {
  merchantPayButton.hidden = !visible;
});

// Register before mounting so the initial availability event is not missed.
clink.on('sdk-button-initialized', ({ googlePay }) => {
  const googlePayHint = document.getElementById('google-pay-hint');
  if (googlePayHint) googlePayHint.hidden = googlePay !== true;
});

const paymentMethod = clink.createElement('paymentMethod');
paymentMethod.mount('#payment-method');
```

The optional `google-pay-hint` element above is your own explanatory text, not a payment button. `googlePay === true` means the button is available after initialization. `false` means the device is unsupported, the configuration or SDK load failed, or initialization timed out. An absent field means the current Session did not provide Google Pay. Availability can change during checkout, so keep the listener registered. When Google Pay is unavailable, the customer can choose another method available in the Session, such as `CARD` when enabled. See [SDK button availability](/elements#track-sdk-button-availability).

The SDK renders Google's button and handles its click. Do not draw a second Google Pay button or call `clink.submit()` for that button. See [Elements](/elements) for the complete frontend and event handling.

### 3. Handle encrypted data and payment results

Google returns the encrypted payload at `paymentMethodData.tokenizationData.token` in its `PaymentData` response. Hosted Checkout and Elements collect this value and forward it to Clink's checkout service with the Session's transaction context. The merchant server submits the amount, currency, customer, and merchant reference through Create Session; it does not extract, decrypt, or send the Google token through a separate public charge API.

The public `POST /payment` and Payment Instrument APIs are not direct Google Pay token submission interfaces. Do not send the blob or decrypted card data to those endpoints.

On an activated Clink gateway route, Clink is responsible for signature verification, expiration checks, decryption, and validating that `gatewayMerchantId` matches the merchant before processing the payment. Merchants keep the frontend integration unchanged when Clink changes the downstream processing route.

Use [signed webhooks](/integration#webhooks) or server-side [Order retrieval](/api-reference/endpoint/get-order) to establish the final payment result. Handle `pending`, failure, and required authentication using the integration path's normal state handling.

## Google resources and production checks

Use the official Google Pay logo and button assets without changing their colors, proportions, or appearance. Refer to the [Web brand guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines) when styling your checkout or mentioning Google Pay in your website.

For Elements, use `presetOptions.sdkButtons.googlePay` to configure the supported button theme, type, height, and radius. See [Elements button appearance](/elements#configure-sdk-button-appearance) for allowed values. Do not override the SDK-rendered button with custom CSS.

* [Google Pay Web developer documentation](https://developers.google.com/pay/api/web/)
* [Web integration checklist](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist)
* [Web production access](https://developers.google.com/pay/api/web/guides/test-and-deploy/request-prod-access)
* [Google Pay & Wallet Business Console](https://pay.google.com/business/console)

If you implement your own Google Pay request outside Clink's hosted or embedded checkout, a separate Clink integration agreement and a supported token-submission interface are required. Load the [Google Pay JavaScript client](https://developers.google.com/pay/api/web/guides/tutorial#js-load), obtain your own production Google Merchant ID through Business Console, and complete Google's production review for that integration. The configuration example above alone does not enable this path.

Before launching, confirm Clink gateway activation where applicable, your approved networks and settlement countries, both credential flows, risk-triggered `PAN_ONLY` 3DS, billing requirements, and server-side payment confirmation. Follow [Clink's go-live checks](/go-live) as well as Google's integration checklist.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.