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

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Google Pay

> Google Pay is a mobile payment and digital wallet service. With Google Pay, consumers can enjoy a seamless checkout experience, eliminating the need to enter payment and shipping information manually.

export const AuthorizeRequestExample = ({paymentMethodCode, integrationType = "api", amount = "1000", currency = "USD", executionId = "c0fd1c51-e709-47e5-bfd1-5d1c98f7d990", orderLine, meta, paymentComposition, request, returnInfo = {
  success: "https://mysuccessurl.com",
  error: "https://myerrorurl.com"
}}) => {
  const line = orderLine || ({
    id: "UUID",
    name: "Order Name",
    quantity: 1,
    unitPrice: {
      currency,
      value: amount
    }
  });
  const composition = paymentComposition || [{
    integrationType,
    paymentMethodCode,
    amount: {
      value: amount,
      currency
    }
  }];
  const defaultRequest = {
    executionId,
    amount: {
      value: amount,
      currency
    },
    paymentComposition: composition,
    meta: meta || ({
      order: {
        lines: [line]
      }
    }),
    returnInfo: returnInfo === null ? undefined : returnInfo
  };
  const output = request || defaultRequest;
  return <CodeBlock language="json" lines>
      {JSON.stringify(output, null, 2)}
    </CodeBlock>;
};

export const LookupResponseExample = ({paymentMethodCode, description, integrationType = "api", options, actionId = "0bb6413e-cabb-4074-99e6-9e815c69f25b", executedAt = "2026-03-26T12:00:00.000000000Z", executionId = "83c534ac-13b7-43e6-b04b-f3e8b4eb4424", response}) => {
  const paymentCompositionOptions = options || [{
    integrationType,
    paymentMethodCode,
    description: description || paymentMethodCode
  }];
  const executionUrl = `https://api.payrails.io/merchant/workflows/payment-acceptance/executions/${executionId}`;
  const output = response || ({
    name: "lookup",
    actionId,
    executedAt,
    data: {
      paymentCompositionOptions
    },
    links: {
      execution: executionUrl,
      authorize: {
        method: "POST",
        href: `${executionUrl}/authorize`
      }
    }
  });
  return <CodeBlock language="json" lines>
      {JSON.stringify(output, null, 2)}
    </CodeBlock>;
};

export const PayrailsSDKIntro = ({method, element}) => <p>
    The simplest way to use {method} with Payrails is to use our{" "}
    <a href="/docs/orchestration/checkout-sdks/web-v5-legacy/drop-in">drop-in</a> in your checkout flow. With this
    integration type, no additional development work is required to accept payments with {method}.
    {element ? <>
        {" "}
        For a more flexible implementation using our SDK, you can use our <code>{element}</code> element.
      </> : null}
  </p>;

export const Prerequisites = ({method, providers = [], configureInDashboard = false, extraSteps = []}) => {
  const providerLinks = providers.flatMap((p, i) => {
    const link = p.href ? <a key={`link-${i}`} href={p.href}>
        {p.name}
      </a> : <strong key={`link-${i}`}>{p.name}</strong>;
    if (i === 0) {
      return [link];
    }
    const isLast = i === providers.length - 1;
    const separator = isLast && providers.length > 2 ? ", and " : isLast ? " and " : ", ";
    return [<span key={`sep-${i}`}>{separator}</span>, link];
  });
  return <ol>
      <li>
        Integrate with Payrails using one of our{" "}
        <a href="/docs/orchestration/checkout-sdks">SDKs</a> or our{" "}
        <a href="/docs/orchestration/checkout-sdks/accept-payments-via-api">API</a>
      </li>
      <li>
        Configure a new <a href="/docs/orchestration/integrations">integration account</a> for{" "}
        {method} via {providerLinks.length > 0 ? providerLinks : "your Payment Service Provider"}.
        {providers.length === 1 && providers[0].setupGuideHref ? <>
            {" "}
            If you do not have a {providers[0].name} integration already configured in your workspace, please
            follow the{" "}
            <a href={providers[0].setupGuideHref}>{providers[0].name} integration setup guide</a> first.
          </> : null}
      </li>
      {configureInDashboard && providers[0] && <li>
          Enable {method} as a payment method in your {providers[0].name} integration configuration. In the
          Payrails portal, navigate to <strong>Settings → Integrations</strong>, select your {providers[0].name}{" "}
          integration instance, and enable the <strong>{method}</strong> checkbox under Payment methods, then save
          the account.
        </li>}
      <li>
        Enable {method} as a <a href="/docs/orchestration/payment-methods/set-up-payment-methods">payment option</a>.
      </li>
      {extraSteps.map((step, i) => <li key={i}>{step}</li>)}
      <li>
        Make sure you're sending the {method}-specific meta fields (found under Merchant configurations -&gt; Meta
        fields on your Payrails dashboard and in the examples below) in your requests.
      </li>
    </ol>;
};

export const SupportedWorkflowsTable = ({workflows, workflowKeys}) => {
  const hideUnsupportedWorkflows = ["interoperability"];
  if (!workflows) {
    return <p>
                <em>
                    No workflow data configured for this method yet — add it to
                    its file in <code>snippets/payment-methods/methods/</code>.
                </em>
            </p>;
  }
  return <table>
            <thead>
                <tr>
                    <th>Workflow</th>
                    <th>Supported</th>
                </tr>
            </thead>
            <tbody>
                {workflowKeys.filter(w => workflows[w.key] !== false || !hideUnsupportedWorkflows.includes(w.key.toLowerCase())).map(w => {
    const value = workflows[w.key];
    const display = value === true ? "✔" : value === false ? "✖" : value === "pending" ? "⏳" : value === null ? "N/A" : value;
    return <tr key={w.key}>
                                <td>
                                    {w.href ? <a href={w.href}>{w.label}</a> : w.label}
                                </td>
                                <td>{display}</td>
                            </tr>;
  })}
            </tbody>
        </table>;
};

export const SupportedCountriesTable = ({countries, continents, method, merchant = false}) => {
  const flagFor = code => code.toUpperCase().replace(/./g, ch => String.fromCodePoint(ch.charCodeAt(0) + 127397));
  if (!countries || countries.length === 0) {
    return <p>
                <em>
                    No countries configured for this method yet — add them to
                    its file in <code>snippets/payment-methods/methods/</code>.
                </em>
            </p>;
  }
  const byContinent = {};
  for (const continent of continents) {
    byContinent[continent] = [];
  }
  for (const country of countries) {
    if (!byContinent[country.continent]) {
      byContinent[country.continent] = [];
    }
    byContinent[country.continent].push(country);
  }
  const rows = continents.map(continent => ({
    continent,
    list: (byContinent[continent] || []).slice().sort((a, b) => a.name.localeCompare(b.name))
  })).filter(row => row.list.length > 0);
  const description = merchant ? `Merchants based in the following regions can accept ${method} payments:` : `${method} is available to customers based in:`;
  return <div>
            {method && <p>{description}</p>}
            <table>
                <thead>
                    <tr>
                        <th className="min-w-[115px]">Region(s)</th>
                        <th>Countries</th>
                    </tr>
                </thead>
                <tbody>
                    {rows.map(row => <tr key={row.continent}>
                            <td>
                                <b>{row.continent}</b>
                            </td>
                            <td>
                                <span className="inline-flex flex-row flex-wrap">
                                    {row.list.map(c => <span className="text-xs text-nowrap rounded-sm hover:mint-bg-gray-100 cursor-default px-1" key={c.code}>
                                            {flagFor(c.code)} {c.name}
                                        </span>)}
                                </span>
                            </td>
                        </tr>)}
                </tbody>
            </table>
        </div>;
};

export const method = {
  slug: "google-pay",
  name: "Google Pay",
  href: "/docs/orchestration/payment-methods/google-pay",
  icon: "https://assets.payrails.io/img/logos/googlepay/logo.svg",
  workflows: {
    sdk: true,
    api: true,
    delayedCapture: true,
    instantCapture: true,
    cancelVoid: true,
    refund: true,
    saveInstruments: true,
    mit: true,
    interoperability: "PSP tokens, Network tokens"
  },
  countries: [{
    code: "AE",
    name: "United Arab Emirates",
    continent: "Middle East"
  }, {
    code: "AT",
    name: "Austria",
    continent: "Europe"
  }, {
    code: "AU",
    name: "Australia",
    continent: "Asia Pacific"
  }, {
    code: "BE",
    name: "Belgium",
    continent: "Europe"
  }, {
    code: "BG",
    name: "Bulgaria",
    continent: "Europe"
  }, {
    code: "BR",
    name: "Brazil",
    continent: "Latin America"
  }, {
    code: "CA",
    name: "Canada",
    continent: "North America"
  }, {
    code: "CH",
    name: "Switzerland",
    continent: "Europe"
  }, {
    code: "CY",
    name: "Cyprus",
    continent: "Europe"
  }, {
    code: "CZ",
    name: "Czech Republic",
    continent: "Europe"
  }, {
    code: "DE",
    name: "Germany",
    continent: "Europe"
  }, {
    code: "DK",
    name: "Denmark",
    continent: "Europe"
  }, {
    code: "EE",
    name: "Estonia",
    continent: "Europe"
  }, {
    code: "ES",
    name: "Spain",
    continent: "Europe"
  }, {
    code: "FI",
    name: "Finland",
    continent: "Europe"
  }, {
    code: "FR",
    name: "France",
    continent: "Europe"
  }, {
    code: "GB",
    name: "United Kingdom",
    continent: "Europe"
  }, {
    code: "GI",
    name: "Gibraltar",
    continent: "Europe"
  }, {
    code: "GR",
    name: "Greece",
    continent: "Europe"
  }, {
    code: "HK",
    name: "Hong Kong",
    continent: "Asia Pacific"
  }, {
    code: "HR",
    name: "Croatia",
    continent: "Europe"
  }, {
    code: "HU",
    name: "Hungary",
    continent: "Europe"
  }, {
    code: "IE",
    name: "Ireland",
    continent: "Europe"
  }, {
    code: "IS",
    name: "Iceland",
    continent: "Europe"
  }, {
    code: "IT",
    name: "Italy",
    continent: "Europe"
  }, {
    code: "JP",
    name: "Japan",
    continent: "Asia Pacific"
  }, {
    code: "LI",
    name: "Liechtenstein",
    continent: "Europe"
  }, {
    code: "LT",
    name: "Lithuania",
    continent: "Europe"
  }, {
    code: "LU",
    name: "Luxembourg",
    continent: "Europe"
  }, {
    code: "LV",
    name: "Latvia",
    continent: "Europe"
  }, {
    code: "MA",
    name: "Morocco",
    continent: "Africa"
  }, {
    code: "MT",
    name: "Malta",
    continent: "Europe"
  }, {
    code: "MX",
    name: "Mexico",
    continent: "Latin America"
  }, {
    code: "MY",
    name: "Malaysia",
    continent: "Asia Pacific"
  }, {
    code: "NL",
    name: "Netherlands",
    continent: "Europe"
  }, {
    code: "NO",
    name: "Norway",
    continent: "Europe"
  }, {
    code: "NZ",
    name: "New Zealand",
    continent: "Asia Pacific"
  }, {
    code: "PL",
    name: "Poland",
    continent: "Europe"
  }, {
    code: "PR",
    name: "Puerto Rico",
    continent: "Latin America"
  }, {
    code: "PT",
    name: "Portugal",
    continent: "Europe"
  }, {
    code: "RO",
    name: "Romania",
    continent: "Europe"
  }, {
    code: "SE",
    name: "Sweden",
    continent: "Europe"
  }, {
    code: "SG",
    name: "Singapore",
    continent: "Asia Pacific"
  }, {
    code: "SI",
    name: "Slovenia",
    continent: "Europe"
  }, {
    code: "SK",
    name: "Slovakia",
    continent: "Europe"
  }, {
    code: "TH",
    name: "Thailand",
    continent: "Asia Pacific"
  }, {
    code: "US",
    name: "United States",
    continent: "North America"
  }, {
    code: "ZA",
    name: "South Africa",
    continent: "Africa"
  }]
};

export const CONTINENTS = ["Africa", "Asia Pacific", "Europe", "Latin America", "Middle East", "North America"];

export const WORKFLOW_KEYS = [{
  key: "sdk",
  label: "Payrails SDK"
}, {
  key: "api",
  label: "Payrails API"
}, {
  key: "delayedCapture",
  label: "Delayed / Manual Capture",
  href: "/docs/orchestration/payment-acceptance/capture-and-cancel-modes#capture-mode"
}, {
  key: "instantCapture",
  label: "Instant Capture",
  href: "/docs/orchestration/payment-acceptance/capture-and-cancel-modes#capture-mode"
}, {
  key: "cancelVoid",
  label: "Cancel / Void",
  href: "/docs/orchestration/payment-acceptance/cancel-a-payment"
}, {
  key: "refund",
  label: "Refund / Reverse",
  href: "/docs/orchestration/payment-acceptance/refund-a-payment"
}, {
  key: "saveInstruments",
  label: "Save Instruments",
  href: "/docs/resources/manage-instruments"
}, {
  key: "mit",
  label: "Merchant Initiated Transaction (MIT)",
  href: "/docs/resources/payments/authorization-flags"
}, {
  key: "interoperability",
  label: "Interoperability"
}];

## Introduction

Google Pay is a widely used mobile payment solution that offers a convenient and secure way for customers to pay for goods and services. Integrating Google Pay with Payrails allows you to provide a fast, easy-to-use payment option for your customers while leveraging our platform to route the payment to any Payment Service Provider (PSP). This guide will explain the process of integrating Google Pay into your app or website using Payrails.

<img src="https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/orchestration/payment-methods/google-pay-workflow.svg?fit=max&auto=format&n=sujy1gNo9mr-Fy-6&q=85&s=4c54902eaaa4046543621552a661b740" alt="Google Pay payment flow overview through Payrails" className="mx-auto block rounded-lg object-cover" width="80%" data-path="images/docs/orchestration/payment-methods/google-pay-workflow.svg" />

## Pre-requisites

In order to start using Google Pay with Payrails, you must:

<Prerequisites
  method="Google Pay"
  providers={[
{ name: "Stripe", href: "/docs/orchestration/integrations/stripe" },
{ name: "Checkout.com", href: "/docs/orchestration/integrations/checkout-com" },
{ name: "Adyen", href: "/docs/orchestration/integrations/adyen" },
]}
  extraSteps={[
<>
  Follow the setup steps in the Google Pay documentation below. The exact steps you must follow depend on the
  nature of your integration with Payrails. In any case, you must get your Google Pay implementation approved
  by Google as described in{" "}
  <a href="https://developers.google.com/pay/api/web/guides/test-and-deploy/publish-your-integration">Publish your Google Pay integration</a>.
  Please then ensure to configure your Google Pay merchant ID in your SDK implementation as described in{" "}
  <a href="/docs/orchestration/checkout-sdks/web-v5-legacy/elements#google-pay-element">Google Pay Element</a>.
</>,
]}
/>

#### Google Pay on Android Devices

* [Google Pay Android Developer Documentation](https://developers.google.com/pay/api/android/overview)
* [Google Pay Android Integration Checklist](https://developers.google.com/pay/api/android/guides/test-and-deploy/integration-checklist)
* [Google Pay Android Brand Guidelines](https://developers.google.com/pay/api/android/guides/brand-guidelines)

### Google Pay on the Web

* [Google Pay Web Developer Documentation](https://developers.google.com/pay/api/web/overview)
* [Google Pay Web Integration Checklist](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist)
* [Google Pay Web Brand Guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines)

## Ways to integrate

### Payrails SDK

<PayrailsSDKIntro method="Google Pay" />

For a more flexible implementation using our SDK, you can use our Google Pay element. For your client-side implementation, see [Google Pay Element](/docs/orchestration/checkout-sdks/web-v5-legacy/elements#google-pay-element).

### Server-to-server integration

You also have the option to completely manage your own client-side implementation, and use Payrails APIs with a server-to-server integration to process payments with Google Pay. With this approach, follow the Google documentation linked above to build Google Pay into your applications.

#### Pass Google Pay configuration in lookup response to Google Pay SDK

With a server-to-server integration, you can call our [lookup payment options](/docs/orchestration/payment-acceptance/lookup-payment-options) endpoint to get available payment options and relevant configurations for each payment method. You can get `allowedAuthMethods` and `allowedCardNetworks` from the response here and pass it to the Google Pay SDK. Please contact your Payrails representative during the onboarding phase in order to set these configurations before going live.

<LookupResponseExample
  response={{
name: "lookup",
actionId: "bd879370-6935-4ff2-872e-fdb0c5ce3024",
executedAt: "2023-06-12T07:53:09.360484718Z",
data: {
  paymentCompositionOptions: [
    {
      integrationType: "api",
      paymentMethodCode: "googlePay",
      description: "GooglePay",
      config: {
        parameters: {
          allowedAuthMethods: ["PAN_ONLY", "CRYPTOGRAM_3DS"],
          allowedCardNetworks: ["MASTERCARD", "VISA", "AMEX", "DISCOVER"],
        },
        tokenizationSpecification: {
          parameters: {
            gateway: "payrails",
            gatewayMerchantId: "EXAMPLE_MERCHANT_ID",
          },
          type: "PAYMENT_GATEWAY",
        },
        type: "CARD",
      },
    },
  ],
},
links: {
  execution:
    "https://api.payrails.io/merchant/workflows/payment-acceptance/executions/2ef29a74-d1ae-4fa5-a1d9-84e2cd710c23",
  authorize: {
    method: "POST",
    href: "https://api.payrails.io/merchant/workflows/payment-acceptance/executions/2ef29a74-d1ae-4fa5-a1d9-84e2cd710c23/authorize",
  },
},
}}
/>

<Note>
  Please setup your `gatewayMerchantId` with Payrails before you start testing
  your Google Pay integration in case of client owned Google Pay integration.
  Payrails performs validations on the merchant Id we receive after decrypting
  the token to ensure that we did not receive a forged token.
</Note>

#### Pass Google Pay payment token in request to authorize payment with Payrails

When you initiate a transaction with the Google Pay SDK, a Payment Token (`paymentMethodData.tokenizationData.token`) containing a JSON-formatted string is sent to the merchant app. Pass the `paymentMethodData.tokenizationData.token` in your call to our [authorize a payment](/docs/orchestration/payment-acceptance/authorize-a-payment) endpoint. See an example below.

<AuthorizeRequestExample
  request={{
paymentComposition: [
  {
    amount: {
      currency: "USD",
      value: "1.00",
    },
    integrationType: "api",
    paymentInstrumentData: {
      billingAddress: {
        country: {
          code: "US",
        },
        postalCode: "78759",
      },
      card: null,
      paymentToken:
        '{"apiVersion":2,"apiVersionMinor":0,"paymentMethodData":{"description":"Amex •••• 0002","info":{"assuranceDetails":{"accountVerified":true,"cardHolderAuthenticated":false},"billingAddress":{"countryCode":"US","name":"Card Holder Name","postalCode":"94043"},"cardDetails":"0002","cardNetwork":"AMEX"},"tokenizationData":{"token":"{\\"signature\\":\\"MEUCIQCkwDXS2WcYP8ChfrNh55gow99Gw0/njq+ZN+L1S01dGgIgXxL+Ftb1PrWcgPiJSXQX8xSSkw2WW1wn66gKbEd9DC0\\u003d\\",\\"protocolVersion\\":\\"ECv1\\",\\"signedMessage\\":\\"{\\\\\\"encryptedMessage\\\\\\":\\\\\\"Z6NNDumB9omrYocB1hzmHRh8fP5iiqHlFtaohXS5C/RrelQgrmmLVpw8pLsbMsG64iMwsFIs5chSIOpbtJuRuhZ9b0NzbEbqVd0jweM2a5M0Ea1TlQi6YjnviLXjJCtCOhyFb/n2EuYUuMmqlUnu8pKrKEGjcS2TOkel6p2oN8N8BxLz2SNtJb8ubYhEuy7n7HKcaiuDwfnjr0a8tEcNSet0IeA8LXDKi/5OAM7/vCLFV+ZYlQ+UvSoF3O4ooKZXgpsRHc12IeneAev8+koA+omxoK5R8SInAogwQ0FclRVlA30T2C8VdR8IlL/9oGQK9KmSIjkIxYNakHptU41NTLrv/dH40ZwkBp9lGQ1Kuup4Y9M5IA8zjAM1vnIySNIv1lIGinrgALoEB6jt91qYDeHB9jtNArISiym5JfxZjCRUbj9SuyQH+ovKvuFhfqSoJgWaZYsAiwgTYpxLj8B8eSaFgFaUdjjNvvXkoBuLXYLVoU6Ecjkl30BTHnNfUa0XstNPQf6kAPnvMhl0e3KJ4g\\\\u003d\\\\u003d\\\\\",\\\\\\"ephemeralPublicKey\\\\\\":\\\\\\"BIHW3CPNcYs5v27HWo4fZDSMXNJetlJESpz5TKX5R9pzh5mE0RwMOiy9HZp9ll4DoPiEVLLsHQaQE4EhBZ5GYfc\\\\u003d\\\\\",\\\\\\"tag\\\\\\":\\\\\\"wzvb6aeZ6jmspk2vVq6O9uu+P1cfhzHLt5CExkPDOAU\\\\u003d\\\\\"}\\"}","type":"PAYMENT_GATEWAY"},"type":"CARD"}}',
      providerData: null,
      vaultToken: "",
    },
    paymentMethodCode: "googlePay",
    storeInstrument: false,
  },
],
}}
/>

## Supported regions / countries

<SupportedCountriesTable countries={method.countries} continents={CONTINENTS} method={method.name} />

Google Pay payments may be available in additional countries based on the status of their integrations and each provider's technology rollout.

## Supported workflows and services

<SupportedWorkflowsTable workflows={method.workflows} workflowKeys={WORKFLOW_KEYS} />


## Related topics

- [Server-to-server Integration](/docs/use-cases/server-to-server-integration-reference-architecture.md)
- [How to Gate Payment Authorization](/docs/orchestration/how-to-gate-payment-authorization.md)
- [Google Pay via Proxy](/docs/token-vault/vault-proxy/proxy-payment-instruments/google-pay-via-proxy.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.