> For a complete page index, fetch https://docs.transak.com/llms.txt

# Headless Google Pay

**Headless Google Pay** is a lightweight, embeddable UI module that allows partners to offer Google Pay as a payment method directly within their own application without loading any widget.

## Watch: How Headless Google Pay Works

A short walkthrough of Headless Google Pay and how it embeds the Google Pay flow directly inside your own app.

## Our Solution

Headless Google Pay exposes just the Google Pay button as a standalone, embeddable component. Partners control where it sits, how it looks, and what happens after payment. Transak handles all the payment infrastructure in the background.

Here are some of the **key benefits** of the Headless Google Pay solution:

<table>
  <tbody>
    <tr>
      <td>
        **Just the Google Pay button**

        Embed only the Google Pay button — no full widget required.
      </td>
    </tr>

    <tr>
      <td>
        **One tap to payment**

        Users see the Google Pay button immediately and complete payment in a single tap, reducing drop-off.
      </td>
    </tr>

    <tr>
      <td>
        **Seamless checkout integration**

        The Google Pay button sits inside the partner's own checkout UI, keeping the experience continuous.
      </td>
    </tr>

    <tr>
      <td>
        **Full partner control**

        Partners decide where the button appears, how it looks, and what happens after payment.
      </td>
    </tr>
  </tbody>
</table>

## How does it work?

![headless-google-pay](https://files.buildwithfern.com/visual-editor-images/docs.transak.com/2026-07-06T06:52:23.008Z/payments/headless-google-pay/headless-google-pay.png "headless-google-pay")

## Current Limitations

<table>
  <thead>
    <tr>
      <th>
        Limitation
      </th>

      <th>
        Details
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **Headless Google Pay APIs ([Transaction Session API](/api/headless-google-pay/transaction-session-api), [Create Order API](/api/headless-google-pay/create-order-for-google-pay), [Transaction Request Status API](/api/headless-google-pay/transaction-request-status-api))**
      </td>

      <td>
        APIs are to be called only from the partner backend and subjected to the whitelisting of partner IP addresses. We don't support API calls from the frontend due to security restrictions.
      </td>
    </tr>

    <tr>
      <td>
        **Supported for JS, React, and React Native integrations**
      </td>

      <td>
        The Transak UI SDK is available for [JS, React, and React Native](/payments/headless-google-pay#load-the-google-pay-component-via-transak-ui-sdk) integrations.
      </td>
    </tr>

    <tr>
      <td>
        **Google pay availability**
      </td>

      <td>
        Google Pay payments are only supported if the [Get Fiat Currencies API](/api/whitelabel/lookup/get-fiat-currencies) response includes payment method `google_pay` for that particular fiat currency.
      </td>
    </tr>
  </tbody>
</table>

## How to integrate?

#### Whitelist Your API Key & Enable Headless Google Pay

| Action                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------------- |
| Follow the steps in the [Need help in Integration](/getting-started/help-and-support#need-help-in-integration) section |
| Request **API key whitelisting** and ask to **enable Headless Google Pay** for your API key                            |
| Share your public IP addresses with Transak for whitelisting to use our APIs in your backend                           |

#### User Authentication

You can use either of the following authentication options:

| Option               | Description                                                                                                                                                                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **White-label Auth** | Use the standard Transak authentication flow to generate a user access token. Partners can do this by calling the [Send User OTP API](/api/whitelabel/user/send-user-otp) followed by the [Verify User API](/api/whitelabel/user/verify-user-otp) to generate the access token. Learn more  |
| **Auth Reliance**    | Use [Auth Reliance](/features/auth-reliance) by passing these headers with every request: `x-user-identifier` and `x-access-token`                                                                                                                                                          |

Please refer to the tutorial on [how to create partner access token](/guides/how-to-create-partner-access-token).

#### User KYC

KYC is a mandatory step in compliance with regulatory requirements. Each user should be

KYC Approved

. You can use either of the following KYC options:

| Option                      | Description                                                                                                                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **White label KYC**         | Partners can collect the required KYC information on their end and then forward it to Transak for review and approval. Learn more: [Transak KYC using APIs](/features/transak-kyc-apis) |
| **KYC Reliance via Sumsub** | Partners can share their KYC data from their platform with Transak using Sumsub. Learn more: [KYC Reliance Guide](/features/kyc-reliance-sumsub)                                        |

#### Generate a quote using the Quote API

Call the [Get Quote API](https://docs.transak.com/api/whitelabel/lookup/get-quote) to get a quote for the transaction. Pass the apiKey, fiat amount, fiat currency, crypto currency, network, and order type.

Set `paymentMethod` to `google_pay` while creating a quote.

A successful response returns a `quoteId`.

#### Get KYC Requirement

Call [Get KYC Requirement](/api/whitelabel/kyc/get-kyc-requirement) with the `quoteId` to fetch the KYC status and route accordingly:

<table>
  <thead>
    <tr>
      <th>
        When
      </th>

      <th>
        Next step
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `data.kyc.status` = **APPROVED**
      </td>

      <td>
        No further steps in the KYC process. Proceed to **Get User Limits**.
      </td>
    </tr>

    <tr>
      <td>
        `data.kyc.status` = **NOT_SUBMITTED**
      </td>

      <td>
        User details need to be submitted. Proceed to **Patch User Details**.
      </td>
    </tr>

    <tr>
      <td>
        `data.kyc.status` = **ADDITIONAL_FORMS_REQUIRED**
      </td>

      <td>
        More steps in the KYC process are required. Proceed to **Get Additional Requirements**.
      </td>
    </tr>
  </tbody>
</table>

#### Get User Limits

Call [Get User Limits](/api/whitelabel/user/get-user-limits) with `paymentCategory = google_pay` and `fiatCurrency` to fetch the user's monthly, daily, and yearly limits.

On success → proceed to **Get Active Orders**.

#### Get Active Orders

Call [Get Active Orders](/api/whitelabel/orders/get-active-orders) to check for any existing pending orders. Transak doesn't support placing multiple orders simultaneously.

<table>
  <tbody>
    <tr>
      <td>
        **`activeOrder`** `exists`

        Proceed to **Cancel Order**

        ---

        **`activeOrder`** `not exists`

        Proceed to **Create a transaction session**

        ---
      </td>
    </tr>
  </tbody>
</table>

#### Cancel Order

Call [Cancel Order](/api/whitelabel/orders/cancel-order) with `orderId` and `cancelReason` to cancel the pending order.

This is only required when an active order is present. After cancellation, proceed to **Create a transaction session**.

#### Create a transaction session (using Backend only)

Call the [Transaction Session API](/api/headless-google-pay/transaction-session-api) from your backend using the `quoteId`, `successUrl`, `failureUrl` and the user's wallet address. You can optionally pass a `config` and `billingAddress` object to [customise the look and feel](/customization/customizing-theme-for-headless-payments#headless-google-pay) of the Google Pay component and billing details.

| Parameter       | Description                                                                                                             |
| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `quoteId`       | Quote ID returned by the [Get Quote API](https://docs.transak.com/api/whitelabel/lookup/get-quote) in the previous step |
| `walletAddress` | The user's wallet address for the selected cryptocurrency and network                                                   |
| `successUrl`    | URL or deep link to redirect the user to when the transaction completes successfully                                    |
| `failureUrl`    | URL or deep link to redirect the user to when the transaction fails or is cancelled                                     |

A successful response returns a `sessionId`.

#### Load the Google Pay Component via Transak UI SDK

Use the Transak UI SDK to render the Google Pay component. Pass the `sessionId` received in previous Step.

#### JS

```bash
npm install @transak/ui-components
```

```tsx
import { createTransakGooglePay } from '@transak/ui-components';

const googlePay = createTransakGooglePay({
  sessionId, // sessionId from Previous Step
  environment, // 'STAGING' | 'PRODUCTION'                       
  onReady: () => {
    // Component is ready
  },
  onSuccess: ({ requestId }) => {
    // Payment data captured — use requestId in the next step
  },  
  onError: ({ code }) => {
    // Handle error
  }      
});

await googlePay.mount('checkout-slot');
```

Call `googlePay.unmount()` to remove the component from the page after `onSuccess` fires, or when the user leaves the checkout screen.

#### React

```bash
npm install @transak/ui-components-react
```

```tsx
import { TransakGooglePay } from '@transak/ui-components-react';

<TransakGooglePay
  sessionId={sessionId} // sessionId from Previous Step
  environment={environment} // 'STAGING' | 'PRODUCTION'
  onReady: () => {
    // Component is ready
  },
  onSuccess: ({ requestId }) => {
    // Payment data captured — use requestId in the next step
  },  
  onError: ({ code }) => {
    // Handle error
  }      
/>
```

#### React Native

```bash
npm install @transak/ui-components-rn
```

```tsx
import { TransakGooglePay } from '@transak/ui-components-rn';

<TransakGooglePay
  sessionId={sessionId} // sessionId from Previous Step
  environment={environment} // 'STAGING' | 'PRODUCTION'
  onReady: () => {
    // Component is ready
  },
  onSuccess: ({ requestId }) => {
    // Payment data captured — use requestId in the next step
  },  
  onError: ({ code }) => {
    // Handle error
  }      
/>
```

#### `onError` callback

The `onError` callback returns one of the following error codes. Use it to handle each failure case.

| Code                       | Description                                        |
| -------------------------- | -------------------------------------------------- |
| `CONFIG_LOAD_FAILED`       | Google Pay configuration could not be loaded       |
| `PAYMENT_CAPTURE_FAILED`   | Google Pay payment capture failed                  |
| `INVALID_OPTIONS`          | Invalid or missing options passed to the SDK       |
| `IFRAME_LOAD_FAILED`       | The embedded iframe failed to load                 |
| `INVALID_STATE`            | SDK method called in an unexpected state           |
| `GOOGLE_PAY_NOT_SUPPORTED` | Google Pay is not supported in the device's region |

Here’s how the Google Pay module appears :

#### Place the order (using Backend only)

Once the SDK fires `onSuccess` with a `requestId`, call the [Create Order API](/api/headless-google-pay/create-order-for-google-pay) from your backend using the `requestId` to complete the payment and create the order.

A successful response returns the full order details with `redirectUrl`.

#### Open the redirectUrl in a browser or WebView

Always open the `redirectUrl` returned in the previous step in a browser or WebView.

| Scenario                   | What happens on the `redirectUrl` page                                                         |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| Authentication required    | User completes 3DS or bank verification and is then redirected to `successUrl` or `failureUrl` |
| No authentication required | Redirects directly to `successUrl` or `failureUrl`                                             |

Upon completing the transaction, the user is redirected based on the payment status:

| Outcome            | Redirect destination                                                                               |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| Payment successful | `successUrl` passed in [Transaction Session API](/api/headless-google-pay/transaction-session-api) |
| Payment failed     | `failureUrl` passed in [Transaction Session API](/api/headless-google-pay/transaction-session-api) |

#### Track the \`requestId\` (using Backend only)

Call the [Transaction Request Status API](/api/headless-google-pay/transaction-request-status-api) to check whether the request has been processed. Poll this endpoint until the status reaches a terminal state.

Once you receive an `orderId`, use the [Get Order by ID](https://docs.transak.com/api/public/get-order-by-order-id) API to fetch full order details.

## API Overview

#### [Transaction Session API](/api/headless-google-pay/transaction-session-api)

Creates a transaction session using a quote ID and wallet address, returns a `sessionId` to initialise the Google Pay component.

#### [Create Order API](/api/headless-google-pay/create-order-for-google-pay)

Places the order using the `requestId` returned by the SDK's onSuccess callback, completing the order creation.

#### [Transaction Request Status API](/api/headless-google-pay/transaction-request-status-api)

Polls the status of the `requestId` until it reaches a terminal state.

## API Errors

#### Transaction Session API

| Status Code | Error Code | Message                                                                                                       | Next Step                                                                                                                                                               | Terminal State |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| 400         | 6099       | successUrl and failureUrl are required for credit/debit card payments.                                        | Pass `successUrl` and `failureUrl` in the **[Transaction Session API](/api/whitelabel/payments/headless-google-pay/transaction-session-api)** request, then retry.      | No             |
| 401         | 1002       | Invalid or missing authentication token.                                                                      | Pass a valid `authorization` header, or `x-user-identifier` and `x-access-token` headers for [Auth Reliance](/features/auth-reliance), then retry creating the session. | No             |
| 422         | 6002       | KYC is not approved. Please complete KYC before creating a session.                                           | Check the KYC status using **[Get KYC Requirement](/api/whitelabel/kyc/get-kyc-requirement)**. If it is not `APPROVED`, complete KYC before retrying.                   | No             |
| 422         | 6003       | This feature is not enabled for your account. Please contact support.                                         | Contact Transak to enable Headless Google Pay for your account.                                                                                                         | Yes            |
| 422         | 6005       | Quote not found or could not be loaded.                                                                       | Get a new quote with **[Get Quote](/api/whitelabel/lookup/get-quote)**, then retry creating the session.                                                                | No             |
| 422         | 6005       | This payment method is not currently supported. Please try a different payment method.                        | Get a new quote with `paymentMethod` = `google_pay` using **[Get Quote](/api/whitelabel/lookup/get-quote)**, then retry creating the session.                           | No             |
| 422         | 6006       | The provided wallet address is invalid for the selected cryptocurrency and network.                           | Validate the address with **[Verify Wallet Address](/api/public/verify-wallet-address)**, then retry creating the session.                                              | No             |
| 400         | 2030       | Your account has been disabled. Please get in touch with us at [fraud@transak.com](mailto:fraud@transak.com). | Ask the user to contact [fraud@transak.com](mailto:fraud@transak.com).                                                                                                  | Yes            |
| 500         | 6005       | Failed to create a session for the user.                                                                      | Retry creating the session after a few seconds.                                                                                                                         | No             |

#### Create Order API

| Status Code | Error Code | Message                                                                                                       | Next Step                                                                                                                                                                                           | Terminal State |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| 404         | 6007       | Request ID not found.                                                                                         | Retry placing the order with a new `requestId`.                                                                                                                                                     | Yes            |
| 409         | 4005       | Order exists.                                                                                                 | Cancel the active order using **[Get Active Orders](/api/whitelabel/orders/get-active-orders)** → **[Cancel Order](/api/whitelabel/orders/cancel-order)**, then retry placing the order.            | No             |
| 422         | 4001       | Invalid wallet address. Please provide a valid wallet address to proceed.                                     | Validate the address with **[Verify Wallet Address](/api/public/verify-wallet-address)**, then retry placing the order.                                                                             | No             |
| 422         | 4003       | Please upgrade your kyc to next level to proceed with this transaction.                                       | Check the KYC requirements using **[Get KYC Requirement](/api/whitelabel/kyc/get-kyc-requirement)**, complete KYC, then retry placing the order.                                                    | No             |
| 422         | 4013       | Minimum amount should be more than \{amount}.                                                                 | Get a new quote above the minimum amount with **[Get Quote](/api/whitelabel/lookup/get-quote)**, then retry placing the order.                                                                      | No             |
| 422         | 4015       | Invalid payment method for currency combination.                                                              | Pick a supported currency from **[Get Fiat Currencies](/api/public/get-fiat-currencies)** and get a new quote with **[Get Quote](/api/whitelabel/lookup/get-quote)**, then retry placing the order. | No             |
| 422         | 4016       | FCA criteria not met, Please complete the assessments.                                                        | Complete the **[FCA assessments](/guides/how-to-submit-fca)**, then retry placing the order.                                                                                                        | No             |
| 422         | 6012       | KYC requirement is not approved for this transaction.                                                         | Check the KYC status using **[Get KYC Requirement](/api/whitelabel/kyc/get-kyc-requirement)**. If it is not `APPROVED`, complete KYC before retrying the order.                                     | No             |
| 422         | 6014       | Unable to process request. User location data is required for this transaction.                               | Pass the end user's IP address in the `x-user-ip` header of **[Transaction Session API](/api/whitelabel/payments/headless-google-pay/transaction-session-api)**, then retry placing the order.      | No             |
| 400         | 2030       | Your account has been disabled. Please get in touch with us at [fraud@transak.com](mailto:fraud@transak.com). | Ask the user to contact [fraud@transak.com](mailto:fraud@transak.com).                                                                                                                              | Yes            |
| 500         | 4021       | Something went wrong, try again later!                                                                        | Retry placing the order after a few seconds.                                                                                                                                                        | Yes            |
| 500         | 6099       | Unable to process the order. Please try again.                                                                | Retry placing the order after a few seconds.                                                                                                                                                        | Yes            |

#### Transaction Request Status API

| Status Code | Error Code | Message                                                                         | Next Step                                                                                                                                                                                           | Terminal State |
| ----------- | ---------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| 404         | 6007       | Request ID not found.                                                           | Retry placing the order with a new `requestId`.                                                                                                                                                     | Yes            |
| 409         | 4005       | Order exists.                                                                   | Cancel the active order using **[Get Active Orders](/api/whitelabel/orders/get-active-orders)** → **[Cancel Order](/api/whitelabel/orders/cancel-order)**, then retry placing the order.            | No             |
| 422         | 4001       | Invalid wallet address. Please provide a valid wallet address to proceed.       | Validate the address with **[Verify Wallet Address](/api/public/verify-wallet-address)**, then retry placing the order.                                                                             | No             |
| 422         | 4003       | Please upgrade your kyc to next level to proceed with this transaction.         | Check the KYC requirements using **[Get KYC Requirement](/api/whitelabel/kyc/get-kyc-requirement)**, complete KYC, then retry placing the order.                                                    | No             |
| 422         | 4013       | Minimum amount should be more than \{amount}.                                   | Get a new quote above the minimum amount with **[Get Quote](/api/whitelabel/lookup/get-quote)**, then retry placing the order.                                                                      | No             |
| 422         | 4015       | Invalid payment method for currency combination.                                | Pick a supported currency from **[Get Fiat Currencies](/api/public/get-fiat-currencies)** and get a new quote with **[Get Quote](/api/whitelabel/lookup/get-quote)**, then retry placing the order. | No             |
| 422         | 4016       | FCA criteria not met, Please complete the assessments.                          | Complete the **[FCA assessments](/guides/how-to-submit-fca)**, then retry placing the order.                                                                                                        | No             |
| 422         | 6011       | KYC requirement is not approved for this transaction.                           | Check the KYC status using **[Get KYC Requirement](/api/whitelabel/kyc/get-kyc-requirement)**. If it is not `APPROVED`, complete KYC before retrying the order.                                     | No             |
| 422         | 6014       | Unable to process request. User location data is required for this transaction. | Pass the end user's IP address in the `x-user-ip` header of **[Transaction Session API](/api/whitelabel/payments/headless-google-pay/transaction-session-api)**, then retry placing the order.      | No             |
| 500         | 4006       | Unable to create order.                                                         | Retry placing the order after a few seconds.                                                                                                                                                        | No             |
| 500         | 4021       | Something went wrong, try again later!                                          | Retry placing the order after a few seconds.                                                                                                                                                        | Yes            |
| 500         | 6099       | Unable to process the order. Please try again.                                  | Retry placing the order after a few seconds.                                                                                                                                                        | Yes            |

## Interactive Demo