Google Pay

Details on working with the Google Pay frame.

URL

https://blocks.moonpay.com/platform/v1/google-pay

Requirements

Size

The frame container height must be 44px. Width is flexible; the Google Pay button inside the frame uses 100% of the container width.

Permissions

The payment permission policy is required.

Example

<iframe
  src="https://blocks.moonpay.com/platform/v1/google-pay"
  allow="payment"
/>

If you render the frame in a sandboxed iframe (for example, for PCI DSS v4 compliance), include all four sandbox values: allow-scripts allow-popups allow-same-origin allow-forms. Sandboxing is one way to isolate the frame when Google Pay’s pay.js cannot provide a stable Subresource Integrity hash. See Google Pay inside sandboxed iframe for PCI DSS v4 compliance for details.

When you use the sandbox attribute, each value serves a specific purpose:

• allow-scripts runs pay.js.
• allow-popups opens the payment window on user interaction.
• allow-same-origin grants the browser storage and cookie access needed for compatibility.
• allow-forms submits the Google Pay sign-in form.

Android WebView

Google Pay relies on the Payment Request API, which is disabled by default in Android WebView, so embedding this frame natively requires extra setup.

Requires Google Play services 25.18.30+ and Android WebView for Chrome 137+. The isReadyToPay API returns false when these requirements are not met. See Using Android WebView for full details.

Add the AndroidX WebKit dependency:

// build.gradle.kts (app level)
dependencies {
    implementation("androidx.webkit:webkit:1.14.0")
}

Declare the required intent queries in AndroidManifest.xml:

<queries>
  <intent>
    <action android:name="org.chromium.intent.action.PAY" />
  </intent>
  <intent>
    <action android:name="org.chromium.intent.action.IS_READY_TO_PAY" />
  </intent>
  <intent>
    <action android:name="org.chromium.intent.action.UPDATE_PAYMENT_DETAILS" />
  </intent>
</queries>

Enable the Payment Request API on the WebView, after settings.javaScriptEnabled = true:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature

if (WebViewFeature.isFeatureSupported(WebViewFeature.PAYMENT_REQUEST)) {
    WebSettingsCompat.setPaymentRequestEnabled(webView.settings, true)
}

For a complete native walkthrough that covers rendering the frame and wiring events, see Android manual integration.

Initialization parameters

Property	Type	Required	Description
clientToken	string	✅	The client token returned from the connect flow.
channelId	string	✅	A unique identifier for the frame generated on your client. This value is attached to each postMessage payload to help identify messages. The format of this string is up to you.
signature	string	✅	The quote signature from the quote endpoint. Pass signature as returned.
externalTransactionId	string		Your own identifier for the transaction. Stored and associated with the MoonPay transaction for correlation.
theme	string		Pass dark or light to force a specific appearance. If you omit this, the frame uses the user’s system appearance.

Events

All events are dispatched using the message pattern described in the frames protocol. Below are the event payloads specific to the Google Pay frame.

Outbound events

frame->parent

These events are sent from this frame to the parent window.

handshake

The frame requests that you open a message channel.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "handshake"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type HandshakeEvent = Message<{
  kind: "handshake";
}>;

ready

The frame finished loading and the UI is fully rendered. You can use this to coordinate UI transitions if needed.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ready"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type ReadyEvent = Message<{
  kind: "ready";
}>;

buttonPressed

The customer tapped the Google Pay button. The frame emits this the instant the button is tapped, before Android presents the Google Pay payment sheet. Treat it as an intent-to-buy signal: use it to react to the tap, for example to show a loading state or fire analytics.

This event carries no payload. Route it by channelId.

buttonPressed is not a purchase outcome. It still fires if the customer opens the payment sheet and then cancels, and it fires before any authorization happens. For the transaction result, listen for complete, which reports the outcome once the payment resolves.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "buttonPressed"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type ButtonPressedEvent = Message<{
  kind: "buttonPressed";
}>;

complete

The transaction is complete. Use the transaction ID to track status updates (for example, by polling or via webhooks).

Example (success)

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "complete",
  "payload": {
    "transaction": {
      "id": "txn_01",
      "status": "pending"
    }
  }
}

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "complete",
  "payload": {
    "transaction": {
      "status": "failed",
      "failureReason": "Your payment was declined by your bank.",
      "failureCode": "authorizationDeclined"
    }
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

enum TransactionStatus {
  /** The transaction has successfully completed. The payment has been made and the crypto has been transferred. **/
  completed = "completed",
  /** The payment has been completed and the crypto transfer is underway. **/
  pending = "pending",
  /** The transaction has failed. No payment was applied and the crypto was not transferred. **/
  failed = "failed",
}

type FailureCode =
  | "transactionNotAllowed"
  | "validationError"
  | "serviceUnavailable"
  | "authorizationDeclined"
  | "unknown";

type Transaction =
  | {
      /** The MoonPay identifier for this transaction. **/
      id: string;
      /** The status of the transaction. **/
      status: TransactionStatus.completed | TransactionStatus.pending;
    }
  | {
      status: TransactionStatus.failed;
      /** A stable, machine-readable code identifying the failure category. Branch on this value for programmatic handling. May be omitted when the frame cannot classify the failure. **/
      failureCode?: FailureCode;
      /** A developer-friendly error message detailing the reason for the transaction failure. **/
      failureReason: string;
    };

type GooglePayCompleteEvent = Message<{
  kind: "complete";
  payload: {
    transaction: Transaction;
  };
}>;

Failure codes

When a complete event has status: "failed", the failureCode field indicates the failure category. Use this value — not failureReason — for programmatic branching. failureReason is a human-readable fallback suitable for display when you do not have custom copy for a given code.

failureCode is optional. When the frame cannot classify a failure, it sends failureReason alone — fall back to showing that message to the customer.

failureCode	Default failureReason	When it fires	Recommended handling
transactionNotAllowed	”This transaction is not allowed for your account.”	Payment method or account is not eligible (for example, region restriction or KYC limit).	Show the failureReason and guide the customer to resolve the issue or choose a different payment method.
validationError	”The transaction request was invalid.”	Request failed validation (unsupported currency, missing parameters).	Check the quote parameters and retry with corrected values.
serviceUnavailable	”Service temporarily unavailable. Please try again.”	Upstream payment service is degraded or returned a 5xx response.	Retry with exponential back-off.
authorizationDeclined	”Your payment was declined by your bank.”	The issuer or gateway rejected the authorization.	Prompt the customer to try a different card.
unknown	”An unexpected error occurred.”	Any unexpected or unclassified error, including thrown authorization exceptions and fraud blocks.	Show the failureReason to the customer and retry.

Quote expiry is reported through the error event with code: "quoteExpired", not through complete. Listen for both events to cover all failure paths.

challenge

Verification is required before the transaction can proceed. Render the challenge frame at the provided URL. Do not construct the URL yourself — use it as-is.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "challenge",
  "payload": {
    "kind": "frame",
    "url": "https://blocks.moonpay.com/platform/v1/challenge?challengeToken=..."
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type GooglePayChallengeEvent = Message<{
  kind: "challenge";
  payload: {
    kind: string;
    /** Fully-formed URL to pass directly as the challenge frame src. */
    url: string;
  };
}>;

error

This event dispatches errors that occur in the flow and, if available, provides steps for recovery.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "error",
  "payload": {
    "code": "configurationError",
    "message": "The frame configuration is invalid."
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type GooglePayError = Message<{
  kind: "error";
  payload: {
    code:
      | "configurationError"
      | "quoteExpired"
      | "invalidQuote"
      | "googlePayUnavailable"
      | "generic";
    /** A developer-facing error message with details on recovery or documentation. This message is not intended to be rendered in UI. */
    message: string;
  };
}>;

Code	Description
configurationError	The frame configuration is invalid. Check initialization parameters.
quoteExpired	The quote has expired. Fetch a new quote and send it via setQuote.
invalidQuote	The quote signature is invalid or malformed.
googlePayUnavailable	Google Pay is not available in the current environment or browser.
generic	An unexpected error occurred.

Inbound events

parent->frame

These events are sent from the parent window to this frame.

ack

Acknowledge the handshake.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ack"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type AckEvent = Message<{
  kind: "ack";
}>;

setQuote

Provide a new quote to the frame. Pass signature as returned by the quote endpoint. Upon receiving this event, the frame disables the Google Pay button until the quote is revalidated.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "setQuote",
  "payload": {
    "quote": {
      "signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type SetQuoteEvent = Message<{
  kind: "setQuote";
  payload: {
    quote: {
      /** The signature from a valid quote. **/
      signature: string;
    };
  };
}>;