Google Pay button in React and Next.js: GooglePayButton, the gateway token and a Server Action

Google's own React component, @google-pay/button-react, puts the official Google Pay button on your page and opens the payment sheet. What it hands back is an encrypted token for your payment gateway, not a payment: your server still has to send that token to Adyen, Checkout.com or whichever gateway you use. This page wires it up in the Next.js App Router with a Server Action, keeps the gateway part in one small file you swap, and then puts the button above the animated 3D card form so buyers without Google Pay can still pay by card.

One payment$3

By buying you agree to the Terms.

One payment, no subscription
Download right after paying
Use it in client projects
Won't run on the listed stack? We fix it or refund you

Ready forCursorv0Lovableshadcn CLI

Full product pageReact · Tailwind · TypeScript

Google Pay above the 3D card form, in the App Router

app/checkout/checkout.tsx

"use client";
import { useState } from "react";
import CardCheckout, { type CardCheckoutProps } from "@/components/CardCheckout";
import GooglePayRow from "./google-pay";
import { PLAN } from "@/lib/plan";

// Pass renderCardFields + onConfirm from your gateway's card fields (Adyen, Square, Braintree...).
// Without them the card shows its built-in inputs, which are for demos only.
type CardProps = Pick<CardCheckoutProps, "renderCardFields" | "onConfirm">;

export default function Checkout(card: CardProps) {
  const [walletShown, setWalletShown] = useState(false);

  return (
    <div className="mx-auto w-full max-w-[440px]">
      <GooglePayRow onShownChange={setWalletShown} />
      {walletShown && (
        <div className="my-4 flex items-center gap-3 text-xs uppercase tracking-wide text-white/50">
          <span className="h-px flex-1 bg-white/15" />
          or pay with card
          <span className="h-px flex-1 bg-white/15" />
        </div>
      )}
      <CardCheckout
        amount={PLAN.amount / 100}
        currency={PLAN.currency}
        productName={PLAN.name}
        resetAfter={null}
        {...card}
      />
    </div>
  );
}

app/checkout/google-pay.tsx

"use client";
import { useState, useTransition } from "react";
import GooglePayButton from "@google-pay/button-react";
import { googlePayEnv, paymentRequest } from "@/lib/google-pay";
import { payWithGooglePay } from "./actions";

type Props = { onShownChange?: (shown: boolean) => void };

export default function GooglePayRow({ onShownChange }: Props) {
  const [message, setMessage] = useState("");
  const [pending, startTransition] = useTransition();

  return (
    <div aria-busy={pending}>
      <GooglePayButton
        environment={googlePayEnv}
        paymentRequest={paymentRequest}
        buttonType="buy"
        buttonColor="white" // white is for dark backgrounds, black or default for light ones
        buttonSizeMode="fill" // fill takes the size you give it below
        style={{ width: "100%", height: 48 }}
        onReadyToPayChange={({ isButtonVisible }) => onShownChange?.(isButtonVisible)}
        onLoadPaymentData={(paymentData) => {
          // Pass the token on as is. Your server hands it to the gateway.
          const token = paymentData.paymentMethodData.tokenizationData.token;
          startTransition(async () => {
            setMessage("Paying...");
            const result = await payWithGooglePay(token);
            setMessage(result.ok ? "Paid. Thank you!" : result.error);
          });
        }}
        onCancel={() => setMessage("")} // the buyer closed the sheet
        onError={(error) => {
          console.error(error);
          setMessage("Google Pay didn't open. Try the card form below.");
        }}
      />
      <p role="status" className="mt-2 min-h-5 text-center text-sm text-white/70">
        {message}
      </p>
    </div>
  );
}

app/checkout/actions.ts

"use server";
import { randomUUID } from "node:crypto";
import { PLAN } from "@/lib/plan";
import { chargeGooglePay } from "@/lib/gateway";

export type PayResult = { ok: true; reference: string } | { ok: false; error: string };

export async function payWithGooglePay(token: string): Promise<PayResult> {
  if (typeof token !== "string" || token.length === 0 || token.length > 20_000) {
    return { ok: false, error: "That payment didn't come through. Please try again." };
  }
  // The amount comes from the server, never from the browser.
  const reference = `order_${randomUUID()}`;
  const result = await chargeGooglePay({ token, amount: PLAN.amount, currency: PLAN.currency, reference });
  if (!result.ok) return { ok: false, error: "The payment was declined. Try another card." };
  // Save the order here (or from the gateway's webhook) before you thank the buyer.
  return { ok: true, reference };
}

lib/google-pay.ts

import { PLAN } from "./plan";

// TEST returns dummy cards that can't be charged. PRODUCTION needs your site approved in the Google Pay & Wallet Console.
export const googlePayEnv: google.payments.api.Environment =
  process.env.NEXT_PUBLIC_GOOGLE_PAY_ENV === "PRODUCTION" ? "PRODUCTION" : "TEST";

// What your gateway told you to put here. Adyen: gateway "adyen", gatewayMerchantId = your merchant account name.
const tokenizationSpecification: google.payments.api.PaymentMethodTokenizationSpecification = {
  type: "PAYMENT_GATEWAY",
  parameters: {
    gateway: process.env.NEXT_PUBLIC_GOOGLE_PAY_GATEWAY ?? "example",
    gatewayMerchantId: process.env.NEXT_PUBLIC_GOOGLE_PAY_GATEWAY_MERCHANT_ID ?? "exampleGatewayMerchantId",
  },
};

export const paymentRequest: google.payments.api.PaymentDataRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
  allowedPaymentMethods: [
    {
      type: "CARD",
      parameters: {
        // Ask your gateway which of these it supports before you ship.
        allowedAuthMethods: ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        allowedCardNetworks: ["MASTERCARD", "VISA"],
      },
      tokenizationSpecification,
    },
  ],
  merchantInfo: {
    merchantName: "Example Store",
    // Your ID from the Google Pay & Wallet Console. The fallback is the docs' TEST value.
    merchantId: process.env.NEXT_PUBLIC_GOOGLE_PAY_MERCHANT_ID ?? "12345678901234567890",
  },
  transactionInfo: {
    totalPriceStatus: "FINAL",
    totalPriceLabel: "Total",
    totalPrice: (PLAN.amount / 100).toFixed(2), // a string, in major units
    currencyCode: PLAN.currency,
    countryCode: PLAN.country,
  },
};

lib/plan.ts

// One place for what you sell. The page shows it, the Server Action charges it.
export const PLAN = { id: "pro", name: "Pro plan", amount: 1000, currency: "USD", country: "US" } as const; // amount in cents

app/checkout/page.tsx

import Checkout from "./checkout";

export default function CheckoutPage() {
  return (
    <main className="grid min-h-dvh place-items-center overflow-hidden bg-[#0b0a14] p-4">
      <Checkout />
    </main>
  );
}

Good to know

The button only collects. GooglePayButton opens Google's sheet and gives you paymentData. paymentData.paymentMethodData.tokenizationData.token is a string your gateway decrypts; Google's tutorial says to pass it on without changing it. Nothing is charged until your server sends it to the gateway.
The amount lives on the server. totalPrice in transactionInfo is what the buyer sees in the sheet, and it's built from the same PLAN the Server Action charges. The action takes only the token from the browser, never an amount.
"use client" is required. GooglePayButton is a class component that loads Google's pay.js script when it mounts, so the file that renders it must be a Client Component. The page around it can stay a Server Component.
TEST hands back dummy cards. Google's docs say a TEST payment method can't be charged, so a TEST token is only good for checking the shape of the flow. Real tokens need environment PRODUCTION, your merchantId from the Google Pay & Wallet Console and an approved site.
What the 3D card does here, said plainly: Credit Card Checkout V1 doesn't render, style or animate the Google Pay button, and the card doesn't react to a Google Pay payment. Its flip, brand detection and success animation belong to the card path. Google Pay sits above it as its own row, with "or pay with card" between them, and the card's renderCardFields slot takes your gateway's hosted card fields.
What we didn't run: no Google Pay sheet opened (headless Chromium has no Google account), no token went to a gateway and nothing was paid. Every file on this page passes tsc --noEmit and next build with Next.js 15.5, React 19.1, TypeScript 5.9.3, @google-pay/button-react 4.1.0 and @types/googlepay 0.7.13.

The free route: just the Google Pay button

Everything except the 3D card is free. google-pay.tsx, lib/google-pay.ts, the Server Action and lib/gateway.ts above work on any page without our piece: drop GooglePayRow into your own layout and you have a working Google Pay button that sends its token to your server.
Install it with npm i @google-pay/button-react. Version 4.1.0 (August 2026) lists React 16.3 and up as a peer and brings @types/googlepay with it, which is where the global google.payments.api types used in lib/google-pay.ts come from. You don't add a script tag: the component loads pay.js itself.

app/buy/page.tsx

import GooglePayRow from "../checkout/google-pay";

// Free: only the Google Pay button, on a page you design yourself.
export default function BuyPage() {
  return (
    <main className="mx-auto grid min-h-dvh max-w-sm place-items-center p-4">
      <GooglePayRow />
    </main>
  );
}

GooglePayButton props and callbacks

environment is required: "TEST" or "PRODUCTION". paymentRequest is required too: apiVersion 2, apiVersionMinor 0, allowedPaymentMethods with one CARD method (allowedAuthMethods, allowedCardNetworks and a tokenizationSpecification), merchantInfo and transactionInfo. totalPrice is a string like "10.00", not a number.
Callbacks: onLoadPaymentData gets the paymentData when the buyer picks a card. onCancel runs when the buyer closes the sheet. onError gets an Error or Google's PaymentsError. onReadyToPayChange tells you isButtonVisible, which the layout above uses to show or hide the "or pay with card" line. onClick runs before the sheet opens.
Looks: buttonType takes book, buy, checkout, donate, order, pay, plain or subscribe (default buy). buttonColor takes default, black or white; white is for dark backgrounds. buttonSizeMode "fill" sizes the button from your CSS width and height, "static" sizes it to its label. buttonRadius sets the corners (at most 20 at the default 40 px height), buttonBorderType takes no_border or default_border, and buttonLocale sets the label language.
existingPaymentMethodRequired shows the button only to buyers who already have a card saved. Google's reference recommends against relying on it, because the answer doesn't come back when cookies or cross-site tracking are blocked.

Keep the sheet open until your server answers

With onLoadPaymentData the sheet closes as soon as the buyer picks a card, and your page shows the result afterwards. onPaymentAuthorized keeps the sheet open with a spinner while your Server Action runs, then closes it on SUCCESS or shows your message on ERROR so the buyer can try another card.
It only fires when paymentRequest.callbackIntents includes "PAYMENT_AUTHORIZATION", as the README says. Return transactionState "SUCCESS" or "ERROR"; an error needs intent, reason and message.

app/checkout/authorized.tsx

"use client";
import GooglePayButton from "@google-pay/button-react";
import { googlePayEnv, paymentRequest } from "@/lib/google-pay";
import { payWithGooglePay } from "./actions";

// The sheet stays open with a spinner until your server answers, and shows your error if it fails.
export default function GooglePayAuthorized({ onPaid }: { onPaid: (reference: string) => void }) {
  return (
    <GooglePayButton
      environment={googlePayEnv}
      paymentRequest={{ ...paymentRequest, callbackIntents: ["PAYMENT_AUTHORIZATION"] }}
      buttonType="pay"
      buttonSizeMode="fill"
      style={{ width: "100%", height: 48 }}
      onPaymentAuthorized={async (paymentData) => {
        const result = await payWithGooglePay(paymentData.paymentMethodData.tokenizationData.token);
        if (result.ok) {
          onPaid(result.reference);
          return { transactionState: "SUCCESS" };
        }
        return {
          transactionState: "ERROR",
          error: { intent: "PAYMENT_AUTHORIZATION", reason: "PAYMENT_DATA_INVALID", message: result.error },
        };
      }}
    />
  );
}

Which gateway needs what

Google's tutorial has a table with the gateway and gatewayMerchantId to put in tokenizationSpecification for each supported processor. Most take gateway plus gatewayMerchantId. A few from that table, read on October 26, 2026:
Adyen: gateway "adyen", gatewayMerchantId is your merchant account name. On the server, Adyen's API only Google Pay guide sends a /payments request with paymentMethod.type "googlepay" and googlePayToken set to the token, which is what lib/gateway.ts does. Cards that need 3D Secure come back with an action you have to handle.
Checkout.com: gateway "checkoutltd", gatewayMerchantId is your public key. Its guide first turns the Google Pay data into a Checkout.com token (POST /tokens with type "googlepay" and token_data), then requests a payment with that token.
Braintree: no gatewayMerchantId. It takes braintree:apiVersion, braintree:sdkVersion, braintree:merchantId and braintree:clientKey, and Braintree's guide uses its own google-payment component, which turns the result into a payment method nonce. Square: gateway "square", but Square's Web Payments SDK also has its own Google Pay method, so most Square apps use that. Mollie, Worldpay, Airwallex, Authorize.net and Cybersource are in the table too.
Whatever the gateway, the browser side on this page stays the same. Only lib/gateway.ts and the two env vars for gateway and gatewayMerchantId change.

lib/gateway.ts (the Adyen example)

import "server-only";

// One gateway as the example: Adyen. Swap this file for your own gateway's call.
// Adyen's API-only Google Pay guide: POST /payments with paymentMethod.type "googlepay" and googlePayToken.
type Charge = { token: string; amount: number; currency: string; reference: string };
type ChargeResult = { ok: true; pspReference: string } | { ok: false; resultCode: string };

export async function chargeGooglePay({ token, amount, currency, reference }: Charge): Promise<ChargeResult> {
  // ADYEN_CHECKOUT_URL is the Checkout API base from your Adyen account, version included.
  const res = await fetch(`${process.env.ADYEN_CHECKOUT_URL}/payments`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-API-Key": process.env.ADYEN_API_KEY! },
    body: JSON.stringify({
      merchantAccount: process.env.ADYEN_MERCHANT_ACCOUNT,
      amount: { currency, value: amount }, // minor units
      reference,
      paymentMethod: { type: "googlepay", googlePayToken: token },
      channel: "Web",
      returnUrl: `${process.env.NEXT_PUBLIC_SITE_URL}/checkout/done`,
    }),
    cache: "no-store",
  });
  const data: { resultCode?: string; pspReference?: string; action?: unknown } = await res.json();
  // A card that needs 3D Secure comes back with an action. This page doesn't handle that; see Adyen's redirect guide.
  if (data.resultCode === "Authorised" && data.pspReference) return { ok: true, pspReference: data.pspReference };
  return { ok: false, resultCode: data.resultCode ?? `HTTP ${res.status}` };
}

Using Stripe? Use the Express Checkout Element instead

Google's table does list Stripe (gateway "stripe" with stripe:version and stripe:publishableKey). But if Stripe is your processor, its Express Checkout Element in @stripe/react-stripe-js already shows Google Pay, Apple Pay and Link from one component, and you confirm through Stripe.js, so you never handle a raw Google Pay token. Our guide for it builds the same wallet row above the 3D card.

Stripe Express Checkout Element in React

Going live: TEST to PRODUCTION

Google's setup guide asks for an HTTPS page with a domain validated TLS certificate, a supported browser and a payment method saved in the Google account you test with.
To go live, Google's publish guide has you create a business profile in the Google Pay & Wallet Console, accept the Terms of Service and the Acceptable Use Policy, add your website with screenshots for review, then put your merchant ID in merchantInfo.merchantId and switch environment to PRODUCTION. Here that's NEXT_PUBLIC_GOOGLE_PAY_ENV and NEXT_PUBLIC_GOOGLE_PAY_MERCHANT_ID.
Before you go live, ask your gateway which card networks and auth methods it takes. Google's tutorial says to confirm CRYPTOGRAM_3DS (Android device tokens) with your processor, and to keep your own fraud checks: Google Pay's checks don't replace them.

Troubleshooting

The button doesn't show. Look at onReadyToPayChange: isButtonVisible false means Google Pay said this browser can't pay. Check the page is on HTTPS, the browser is one Google lists as supported, and nothing blocks Google's pay.js script (a strict Content Security Policy, for example; the component takes a nonce prop for that).
onLoadPaymentData never runs. The buyer may have closed the sheet (onCancel) or the request may be invalid (onError). Log the error object Google passes to onError.
onPaymentAuthorized never runs. Add callbackIntents: ["PAYMENT_AUTHORIZATION"] to the paymentRequest.
The gateway rejects the token. In TEST with gateway "example" there is no real token to charge; set your real gateway and gatewayMerchantId. Also make sure nothing parses or rewraps the token string on the way to your server.

Install

Copy from the zipPut react/src/components into src/, then npm i framer-motion @google-pay/button-react server-only.
Or ask your AIPaste PROMPT.md into Cursor, Lovable or v0.

Props

renderCardFields: your gateway's hosted card fields, under the Google Pay row
onConfirm: the card path only; Google Pay pays through its own sheet
amount / currency: what the card shows, from the same PLAN as transactionInfo
resetAfter: null keeps the success state

How qodesign compares

qodesign vs 21st.dev21st.dev is best for: browsing a huge marketplace and copying many components a month.
qodesign vs Skiper UISkiper UI is best for: unusual interaction details for landing pages: image reveals, cursor trails, tooltips, drag-and-scroll galleries.

All comparisons, with prices read on each library's own site.

From the blog: Stripe Elements With a Custom Card Design in React and Next.js

Questions

Does @google-pay/button-react work with Next.js App Router?

Yes, from a Client Component. Put "use client" at the top of the file that renders GooglePayButton, since it loads Google's script in the browser. The token can then go to a Server Action. Every snippet here builds with Next.js 15.5 and React 19.1.

Does the Google Pay button take the payment?

No. It returns an encrypted token for your gateway. Your server sends that token to the gateway, which charges the card. In TEST the cards are dummies and can't be charged.

Do I need a merchant ID to test?

Not a real one. In TEST you can use the docs' sample merchantId. For PRODUCTION you get your own from the Google Pay & Wallet Console after Google reviews your site.

Does the 3D card form show Google Pay inside it?

No. Credit Card Checkout V1 has no Google Pay of its own. Google Pay sits above the card as a separate button, and the card's animation only plays for card payments.

Can Cursor or v0 add it for me?

Yes. Each download has a PROMPT.md. Paste it into Cursor, Lovable, v0 or Claude Code and it fits the piece into your app.

Can I use it in client work?

Yes, in personal and client projects. You can't resell the code itself as a kit.