# Google Pay with Elements

> Add a Google Pay button to your custom Elements-based checkout with minimal setup.

VINR Elements is the component library for building a custom checkout UI inside your own page. You mount individual UI components — card fields, address collectors, wallet buttons — and VINR handles tokenization, 3DS, and submission. Adding Google Pay to an Elements checkout requires mounting a single `GooglePayElement`; you do not implement the Google Pay JavaScript API directly.

## Prerequisites

- Google Pay enabled on your VINR merchant account (**Settings → Payment methods**).
- VINR Elements loaded on your page.
- For production: Google merchant registration complete. See [Set up Google Pay](/docs/payments/payment-methods/add-payment-methods/wallets/google-pay/setup#register-with-google).
- Acceptance of Google's terms: using Google Pay requires agreement to the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos) and compliance with the [Google Pay API Acceptable Use Policy](https://payments.developers.google.com/terms/aup).

## Integration

### 1. Initialize VINR Elements

Obtain a `clientSecret` from a server-side `vinr.payments.create` call, then pass it to `vinr.elements`.

```javascript
import { loadVinr } from '@vinr/sdk';

const vinr = await loadVinr('YOUR_VINR_PUBLISHABLE_KEY');
const elements = vinr.elements({ clientSecret: 'YOUR_CLIENT_SECRET' });
```

### 2. Mount the GooglePayElement

Create and mount the wallet button element. VINR calls `isReadyToPay` internally — the element renders only when the customer's device is eligible.

```javascript
const googlePayElement = elements.create('googlePay', {
  style: {
    theme: 'black', // 'black' | 'white'
    type: 'buy',    // 'buy' | 'pay' | 'checkout' | 'subscribe' | 'donate' | 'plain'
  },
});

googlePayElement.mount('#google-pay-button');
```

```html
<div id="google-pay-button"></div>
```

### 3. Handle the payment

Listen for the `completed` event. When the customer authenticates in the Google Pay sheet, VINR calls your handler. Call `confirmPayment` to complete the transaction.

```javascript
googlePayElement.on('completed', async (event) => {
  const { error } = await vinr.confirmPayment({
    elements,
    confirmParams: {
      return_url: 'https://yoursite.com/order/complete',
    },
  });

  if (error) {
    document.getElementById('error-message').textContent = error.message;
  }
  // On success, VINR redirects to return_url
});
```

VINR handles all 3DS challenges and the PAN\_ONLY step-up automatically. If a challenge is required, the customer completes it in a modal managed by VINR Elements before the redirect fires.

## Authentication methods

The `allowedAuthMethods` offered in the Google Pay sheet are determined by your merchant account configuration — you do not set them in the Elements call. To check or change your configuration, contact your VINR account manager.

See [Authentication methods](/docs/payments/payment-methods/add-payment-methods/wallets/google-pay/authentication-methods) for the difference between `CRYPTOGRAM_3DS` and `PAN_ONLY` and when to restrict to one.

## Showing Google Pay alongside card fields

Mount the `GooglePayElement` and `CardElement` (or `PaymentElement`) in the same Elements instance. VINR renders the wallet button only when the device is eligible, so the layout degrades gracefully for customers who cannot use Google Pay.

```javascript
// Both elements share the same `elements` instance
const cardElement = elements.create('card');
cardElement.mount('#card-element');

const googlePayElement = elements.create('googlePay');
googlePayElement.mount('#google-pay-button');
```

> Place the Google Pay button on visual parity with your card input — not smaller or hidden. Google's brand guidelines require wallet buttons to receive equal prominence with other payment methods.

## Testing

Set the `environment` to `TEST` by using your VINR sandbox publishable key. In test mode, VINR passes `TEST` to the Google Pay client internally — no configuration change is needed.

See [Test & go live](/docs/payments/payment-methods/add-payment-methods/wallets/google-pay/test-and-go-live) for the test card reference covering both `CRYPTOGRAM_3DS` and `PAN_ONLY` scenarios.

## See also

[Authentication methods](/docs/payments/payment-methods/add-payment-methods/wallets/google-pay/authentication-methods) — CRYPTOGRAM\_3DS vs PAN\_ONLY: security, SCA, and per-merchant configuration.

[Set up Google Pay (API)](/docs/payments/payment-methods/add-payment-methods/wallets/google-pay/setup) — Direct Google Pay JS API integration without Elements.

[Test & go live](/docs/payments/payment-methods/add-payment-methods/wallets/google-pay/test-and-go-live) — Test Google Pay and complete production approval.