client.setupGooglePay()

Render the Google Pay frame into your UI and initiate a transaction with a quote signature. The quote must have executable: true. To let new customers buy with Google Pay before they have a MoonPay account, see Guest checkout. Guest checkout uses the same setupGooglePay call. Second-factor and KYC step-up arrive as a "challenge" event.

Setup Google Pay

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 "buttonPressed":
        // Customer tapped the button — show a loading state or fire analytics.
        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`.
`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`.

This method does not require a separate auth token. The client uses stored credentials from an active connection, or from the connection check on guest checkout.

`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.
`"buttonPressed"`	—	The customer tapped the Google Pay button, before Android presents the Google Pay sheet. An intent-to-buy signal with no payload — it still fires if the customer then cancels the sheet. Not a purchase outcome; listen for `"complete"` for the result.
`"complete"`	`{ transaction:` `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()`.
`"quoteExpired"`	`{ setQuote: (signature: string) => void }`	The quote signature expired. Fetch a new quote and call `payload.setQuote(...)`.
`"error"`	`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`		Present when `ok` is `true`.
`error`	`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.

TS Definitions

types.ts

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: "buttonPressed" }
  | {
      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;
};

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Parameters

`GooglePayEvent`

`FrameTransaction`

`GooglePayEventError`

Result

Result envelope

`GooglePayFrame`

`SetupGooglePayError`

​Parameters

​GooglePayEvent

​FrameTransaction

​GooglePayEventError

​Result

​Result envelope

​GooglePayFrame

​SetupGooglePayError

Parameters

`GooglePayEvent`

`FrameTransaction`

`GooglePayEventError`

Result

Result envelope

`GooglePayFrame`

`SetupGooglePayError`