Google Pay Web Integration (API Integration)

1. Overview

This document describes how external merchants integrate Google Pay Web API through UseePay. This flow does not require the frontend to create a PaymentIntent first, and it does not require merchant validation like Apple Pay.

The correct Google Pay API payment flow is:

Contact UseePay support to enable Google Pay for your merchant account

Follow the official Google Pay Web integration guide to complete the frontend SDK integration: https://developers.google.com/pay/api/web/guides/tutorial

The frontend requests Google Pay configuration from the merchant backend

The merchant backend calls UseePay payment_method_configurations to get Google Pay configuration

The frontend sends the token and order data to the merchant backend

The merchant backend directly calls paymentIntents()->create(...)

The merchant backend passes:
payment_method_data.type = google_pay
payment_method_data.google_pay.encrypted_payment_data = Google Pay token
and sets:
confirm = true
auto_capture = true

If the payment/create response returns status = requires_customer_action, the merchant must present the URL in next_action.redirect.url to the consumer and wait for the consumer to complete the 3D Secure verification

Production release:

Backend interaction with UseePay must use the production merchant number, production API key, and the UseePay production environment

Google Pay production go-live must follow the official guide: https://developers.google.com/pay/api/web/guides/test-and-deploy/publish-your-integration

2. Merchant Responsibilities

The merchant frontend is responsible for:

Loading the Google Pay SDK

Getting Google Pay configuration

Using the Google Pay SDK to check whether Google Pay is available on the current page

Rendering the Google Pay button

Launching the Google Pay payment sheet

Receiving the Google Pay payment token

Sending the token and order data to the merchant backend

The merchant backend is responsible for:

Providing the Google Pay configuration API

Calling UseePay payment_method_configurations

Receiving the Google Pay token and order data

Directly creating and confirming the payment

UseePay is responsible for:

Returning Google Pay configuration

Processing the Google Pay token during payment creation

3. High-Level Flow

1. Frontend loads Google Pay SDK
2. Frontend calls merchant backend to get Google Pay configuration
3. Merchant backend calls UseePay payment_method_configurations
4. Frontend gets allowedAuthMethods and allowedCardNetworks
5. Frontend calls Google Pay SDK isReadyToPay(...)
6. Frontend renders Google Pay button
7. User clicks Google Pay button
8. Frontend calls loadPaymentData(...)
9. Frontend receives Google Pay token
10. Frontend sends token + order data to merchant backend
11. Merchant backend calls paymentIntents.create(...)
12. Merchant backend sets confirm=true and auto_capture=true
13. If status=requires_customer_action, redirect the customer to next_action.redirect.url

4. Key Integration Points

4.1 Load the Google Pay SDK

The merchant page must first load the official Google Pay SDK:

Without this step, the frontend cannot check Google Pay availability or launch payment.

4.2 `tokenizationSpecification` must declare `PAYMENT_GATEWAY` and use UseePay

When the frontend builds Google Pay allowedPaymentMethods, it must explicitly declare tokenizationSpecification.

Key requirements:

type = PAYMENT_GATEWAY

parameters.gateway = useepay

Example:

{
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "useepay",
    "gatewayMerchantId": "your_gateway_merchant_id"
  }
}

This means the Google Pay token uses gateway mode and is processed by UseePay.

4.3 `payment_method_configurations` must be requested first

The frontend must not hardcode all Google Pay card networks and authentication methods.

The merchant backend should first call:

The frontend must obtain at least:

allowed_card_auth_methods

allowed_card_networks

Then map them to the Google Pay SDK fields:

allowedAuthMethods = allowed_card_auth_methods

allowedCardNetworks = allowed_card_networks

In most integrations, the frontend gets this configuration through the merchant backend API, for example:

POST /api/payment/google-pay/configuration

4.4 The Google Pay SDK must be used to check whether the current page is available for Google Pay

Before displaying the Google Pay button, the frontend must use the Google Pay SDK to check whether Google Pay can be used on the current page.

This usually includes:

Creating PaymentsClient

Calling isReadyToPay(...)

Only when the result is available should the frontend render the Google Pay button and allow the user to start payment.

This step is used to confirm:

Whether the current browser supports Google Pay

Whether the current device supports Google Pay

Whether the current user environment meets the conditions required for Google Pay

4.5 After receiving the payment token, it must be placed into `payment_method_data.google_pay.encrypted_payment_data`

After the frontend calls Google Pay SDK loadPaymentData(...), it receives the Google Pay payment token.

That token must be sent to the merchant backend and included in the payment creation request as:

{
  "payment_method_data": {
    "type": "google_pay",
    "google_pay": {
      "encrypted_payment_data": "Google Pay payment token"
    }
  }
}

Please note:

The correct field path is payment_method_data.google_pay.encrypted_payment_data

It is not the top-level field payment_method_data.encrypted_payment_data

When the merchant backend creates the payment, it must also set:

confirm = true

auto_capture = true

5. Merchant Backend APIs

The merchant backend is recommended to provide the following APIs:

POST /api/payment/google-pay/configuration

POST /api/payment

Responsibilities:

POST /api/payment/google-pay/configuration
Used to return Google Pay configuration

POST /api/payment
Used to receive the Google Pay token and order data, and directly create the payment

6. UseePay APIs Used by Merchant Backend

The merchant backend will call:

POST /api/v1/payment_method_configurations

paymentIntents()->create()

Environment base URLs:

Production: https://openapi.useepay.com

UAT: https://openapi1.uat.useepay.com

7. Payment Creation Rules

After receiving the Google Pay token, the merchant backend should create the payment according to the following rules:

Validate payment_method_data.type == "google_pay"

Read payment_method_data.google_pay.encrypted_payment_data

Build the payment creation parameters

Set payment_method_data.type = "google_pay"

Set payment_method_data.google_pay.encrypted_payment_data

Set confirm = true

Set auto_capture = true

Call paymentIntents()->create(...)

The key request structure is:

{
  "payment_method_data": {
    "type": "google_pay",
    "google_pay": {
      "encrypted_payment_data": "Google Pay payment token"
    }
  },
  "confirm": true,
  "auto_capture": true
}

If the payment/create response returns:

{
  "status": "requires_customer_action",
  "next_action": {
    "redirect": {
      "url": "https://..."
    }
  }
}

the merchant must display or redirect the consumer to next_action.redirect.url and wait for the consumer to complete the 3D Secure verification.

8. Common Mistakes

8.1 Google Pay SDK is not loaded

If the page does not load the official Google Pay SDK, Google Pay availability cannot be checked and payment cannot be launched.

8.2 `tokenizationSpecification` does not declare `PAYMENT_GATEWAY` / `useepay`

If the frontend does not correctly declare:

type = PAYMENT_GATEWAY

gateway = useepay

the Google Pay token cannot be processed in UseePay gateway mode.

8.3 `allowedAuthMethods` and `allowedCardNetworks` are not fetched first

If the frontend does not first get configuration through payment_method_configurations and instead hardcodes the parameters, device availability checks may fail or the payment sheet may behave unexpectedly.

8.4 `isReadyToPay` check is not performed

If the frontend shows the button without first checking whether the current page supports Google Pay, the user may click and fail immediately.

8.5 The token is placed in the wrong field

The Google Pay token must be placed in:

{
  "payment_method_data": {
    "type": "google_pay",
    "google_pay": {
      "encrypted_payment_data": "..."
    }
  }
}

Do not incorrectly place it in:

{
  "payment_method_data": {
    "encrypted_payment_data": "..."
  }
}

8.6 `confirm` and `auto_capture` are not set

In Google Pay API mode, the merchant backend must set:

confirm = true

auto_capture = true

8.7 `requires_customer_action` is not handled

If the backend response returns status = requires_customer_action, the merchant must continue the flow by sending the consumer to next_action.redirect.url to complete 3D Secure verification.

9. Integration Checklist

The page has loaded the Google Pay SDK

The frontend declares tokenizationSpecification.type = PAYMENT_GATEWAY when rendering Google Pay

The frontend declares tokenizationSpecification.parameters.gateway = useepay when rendering Google Pay

The merchant backend supports POST /api/payment/google-pay/configuration

The merchant backend has called POST /api/v1/payment_method_configurations

The frontend has obtained allowedAuthMethods and allowedCardNetworks

The frontend has used the Google Pay SDK to check whether the current page is available

The frontend has successfully received the Google Pay payment token

The backend has placed the token into payment_method_data.google_pay.encrypted_payment_data

10.

The backend has set confirm=true when creating the payment

11.

The backend has set auto_capture=true when creating the payment

12.

If the response returns requires_customer_action, the frontend or merchant page handles next_action.redirect.url

10. Summary

There are only five key integration points in Google Pay Web API mode:

The Google Pay SDK must be loaded

When rendering Google Pay, tokenizationSpecification must declare PAYMENT_GATEWAY and use useepay

payment_method_configurations must be requested to get allowedAuthMethods and allowedCardNetworks

The Google Pay SDK must be used to check whether Google Pay is available on the current page

After receiving the payment token, it must be placed into payment_method_data.google_pay.encrypted_payment_data to create the payment

The final principle is:

The frontend is responsible for getting the token

The backend is responsible for directly creating the payment with the token

The token is used once at payment creation time

If the payment result is requires_customer_action, the merchant must continue the flow with next_action.redirect.url

Google Pay Web Integration (API Integration)

1. Overview#

2. Merchant Responsibilities#

3. High-Level Flow#

4. Key Integration Points#

4.1 Load the Google Pay SDK#

4.2 tokenizationSpecification must declare PAYMENT_GATEWAY and use UseePay#

4.3 payment_method_configurations must be requested first#

4.4 The Google Pay SDK must be used to check whether the current page is available for Google Pay#

4.5 After receiving the payment token, it must be placed into payment_method_data.google_pay.encrypted_payment_data#

5. Merchant Backend APIs#

6. UseePay APIs Used by Merchant Backend#

7. Payment Creation Rules#

8. Common Mistakes#

8.1 Google Pay SDK is not loaded#

8.2 tokenizationSpecification does not declare PAYMENT_GATEWAY / useepay#

8.3 allowedAuthMethods and allowedCardNetworks are not fetched first#

8.4 isReadyToPay check is not performed#

8.5 The token is placed in the wrong field#

8.6 confirm and auto_capture are not set#

8.7 requires_customer_action is not handled#

9. Integration Checklist#

10. Summary#