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

# client.setupGooglePay()

> Render the Google Pay frame and start a transaction.

Render the Google Pay frame into your UI and initiate a transaction with a quote signature. The quote must have `executable: true`.

```ts Setup Google Pay focus={5-35} theme={null}
import { createClient, type GooglePayEvent } from "@moonpay/platform-sdk-web";

const client = createClient({ sessionToken: "c3N0XzAwMQ==" });

const googlePayResult = await client.setupGooglePay({
  quote: quoteResult.value.data.signature,
  container: document.querySelector("#googlePayContainer"),
  onEvent: (event: GooglePayEvent) => {
    switch (event.kind) {
      case "ready":
        break;
      case "complete":
        console.log(event.payload.transaction);
        break;
      case "quoteExpired":
        // Fetch a new quote, then update the frame:
        // event.payload.setQuote(newQuote.signature);
        break;
      case "challenge":
        // Render the challenge frame at the provided URL
        // See: /platform/guides/handling-challenges
        console.log(event.payload.url);
        break;
      case "error":
        console.error(event.payload.kind, event.payload.message);
        break;
      case "unsupported":
        // Google Pay isn't available in this environment — fall back to another method.
        break;
    }
  },
});

if (!googlePayResult.ok) {
  // Handle error
  console.error(googlePayResult.error.kind, googlePayResult.error.message);
  return;
}

const googlePay = googlePayResult.value;
```

***

## Parameters

| Property                | Type                              | Required | Description                                                                              |
| ----------------------- | --------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `quote`                 | `string`                          | ✅        | The quote `signature` returned from [`getQuote`](/platform/sdk-reference/web/get-quote). |
| `container`             | `HTMLElement`                     | ✅        | A DOM element to render the Google Pay frame into.                                       |
| `externalTransactionId` | `string`                          |          | Partner-assigned identifier for this transaction attempt. Useful for reconciliation.     |
| `onEvent`               | `(event: GooglePayEvent) => void` |          | Callback invoked for Google Pay flow events. See [`GooglePayEvent`](#googlepayevent).    |

This method does not require a separate auth token. The client uses stored credentials from an active connection.

### `GooglePayEvent`

`onEvent` receives events as the Google Pay flow progresses. Use `event.kind` to decide how to handle each event.

| kind             | Payload                                                      | When you receive it                                                                                                                            |
| ---------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `"ready"`        | —                                                            | The Google Pay UI is rendered and ready to be shown.                                                                                           |
| `"complete"`     | `{ transaction:` [`FrameTransaction`](#frametransaction) `}` | The Google Pay flow finished. Inspect the `FrameTransaction` for the outcome.                                                                  |
| `"challenge"`    | `{ kind: "frame"; url: string }`                             | Verification required. Render the challenge frame at the provided URL using [`setupChallenge()`](/platform/sdk-reference/web/setup-challenge). |
| `"quoteExpired"` | `{ setQuote: (signature: string) => void }`                  | The quote signature expired. Fetch a new quote and call `payload.setQuote(...)`.                                                               |
| `"error"`        | [`GooglePayEventError`](#googlepayeventerror)                | The flow encountered an error.                                                                                                                 |
| `"unsupported"`  | —                                                            | Google Pay isn't available in the user's current environment.                                                                                  |

#### `FrameTransaction`

The transaction object returned on `"complete"`. `FrameTransaction` is a discriminated union — the failure variant carries `failureReason`, the non-failure variant always carries `id`.

| Field           | Type     | Required | Description                                                                                                                   |
| --------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `status`        | `string` | ✅        | The transaction status. On the failure variant, `"failed"`.                                                                   |
| `id`            | `string` |          | Required on the non-failure variant; optional when `status` is `"failed"` (a transaction may not exist yet on early failure). |
| `failureReason` | `string` |          | Present only on the failure variant (`status === "failed"`).                                                                  |

#### `GooglePayEventError`

| Field     | Type                                                                               | Required | Description                 |
| --------- | ---------------------------------------------------------------------------------- | -------- | --------------------------- |
| `kind`    | `"configurationError"` \| `"invalidQuote"` \| `"quoteExpired"` \| `"genericError"` | ✅        | The error category.         |
| `message` | `string`                                                                           | ✅        | Developer-friendly details. |

Google Pay unavailability is signalled separately through the `"unsupported"` event, not as an error.

## Result

`client.setupGooglePay()` returns a `Result<GooglePayFrame, SetupGooglePayError>`.

### Result envelope

`Result<GooglePayFrame, SetupGooglePayError>`

| Field   | Type                                          | Required | Description                      |
| ------- | --------------------------------------------- | -------- | -------------------------------- |
| `ok`    | `boolean`                                     | ✅        | Whether the operation succeeded. |
| `value` | [`GooglePayFrame`](#googlepayframe)           |          | Present when `ok` is `true`.     |
| `error` | [`SetupGooglePayError`](#setupgooglepayerror) |          | Present when `ok` is `false`.    |

### `GooglePayFrame`

| Field      | Type                          | Required | Description                                                                                           |
| ---------- | ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `setQuote` | `(signature: string) => void` | ✅        | Updates the quote signature used by the frame. Use this in response to `quoteExpired`.                |
| `dispose`  | `() => void`                  | ✅        | Unmounts the frame. After you call this, no further events are dispatched to your `onEvent` callback. |

### `SetupGooglePayError`

| Field     | Type                                       | Required | Description                 |
| --------- | ------------------------------------------ | -------- | --------------------------- |
| `kind`    | `"configurationError"` \| `"genericError"` | ✅        | The error category.         |
| `message` | `string`                                   | ✅        | Developer-friendly details. |

Setup errors cover frame initialization only (for example, a handshake
timeout). Quote problems and Google Pay availability are reported through
`onEvent` after setup succeeds — as the `"error"`, `"quoteExpired"`, and
`"unsupported"` events respectively.

<Accordion title="TS Definitions">
  ```ts types.ts theme={null}
  type GooglePayFrame = {
    setQuote: (signature: string) => void;
    dispose: () => void;
  };

  type FrameTransaction =
    | { id: string; status: string }
    | { id?: string; status: "failed"; failureReason: string };

  type GooglePayEvent =
    | { kind: "ready" }
    | {
        kind: "complete";
        payload: { transaction: FrameTransaction };
      }
    | {
        kind: "challenge";
        payload: {
          kind: "frame";
          /** Fully-formed URL to pass directly to setupChallenge(). */
          url: string;
        };
      }
    | {
        kind: "quoteExpired";
        payload: { setQuote: (signature: string) => void };
      }
    | { kind: "error"; payload: GooglePayEventError }
    | { kind: "unsupported" };

  type GooglePayEventError = {
    kind: "configurationError" | "invalidQuote" | "quoteExpired" | "genericError";
    message: string;
  };

  type SetupGooglePayError = {
    kind: "configurationError" | "genericError";
    message: string;
  };
  ```
</Accordion>