Google Pay 付款處理常式規格

處理常式名稱： com.google.pay
版本： 2026-01-11

1. 簡介

商家可透過 UCP 相容平台，使用 com.google.pay 處理常式提供 Google Pay 做為快速結帳選項。Google Pay API 可讓使用者存取儲存在 Google 帳戶中的付款方式，進而加快結帳速度。

這個處理常式可啟用無標題整合模型，讓商家提供 Google Pay 設定 (例如允許的信用卡網路和閘道參數)，平台則處理與 Google Pay API 的用戶端互動，產生安全付款權杖。

1.1 主要優點

通用設定：商家使用標準 JSON 設定 Google Pay 一次，即可授權任何平台顯示付款介面，不需自訂前端程式碼。
前端分離：平台會處理 Google Pay JavaScript API 或 SDK 整合的複雜性，而商家則會使用產生的權杖。
安全代碼化：運用 Google 內建的代碼化功能，將加密憑證直接傳送給商家的付款服務供應商 (PSP)。

2. 商家整合

2.1 規定

商家必須先完成下列事項，才能透過 UCP 宣傳 Google Pay：

取得 Google Pay 商家 ID：在 PRODUCTION 環境中處理交易時必須使用此 ID (請在 Google Pay 和錢包主控台中註冊)。
確認 PSP 支援：確認您的付款服務供應商 (PSP) 位於 Google Pay 權杖化支援的處理方和閘道清單中。

2.2 處理常式設定

商家只要在付款處理常式陣列中加入處理常式，即可宣傳 Google Pay 支援。設定會嚴格遵循初始化 Google Pay API 時所需的結構。

2.2.1 設定結構定義

設定物件會定義環境、商家身分和允許的付款方式。

Google Pay 付款方式

根據 Google Pay 的 PaymentMethod。

權杖化規格

根據 Google Pay 的 TokenizationSpecification。

2.2.2 處理常式宣告範例

{
  "payment": {
    "handlers": [
      {
        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "name": "com.google.pay",
        "version": "2026-01-11",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
        "config_schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/config.json",
        "instrument_schemas": [
          "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/card_payment_instrument.json"
        ],
        "config": {
          "api_version": 2,
          "api_version_minor": 0,
          "environment": "TEST",
          "merchant_info": {
            "merchant_name": "Example Merchant",
            "merchant_id": "01234567890123456789",
            "merchant_origin": "checkout.merchant.com"
          },
          "allowed_payment_methods": [
            {
              "type": "CARD",
              "parameters": {
                "allowed_auth_methods": ["PAN_ONLY"],
                "allowed_card_networks": ["VISA", "MASTERCARD"]
              },
              "tokenization_specification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "example",
                  "gatewayMerchantId": "exampleGatewayMerchantId"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

2.3 實體

2.3.1 儀器結構定義

Google Pay 付款方式 (card_payment_instrument) 會擴充基本信用卡付款方式。這個物件會沿用標準顯示欄位 (例如 brand 和 last_digits)，確保收據的顯示方式一致，同時調整 credential 欄位，以攜帶特定的 Google Pay 權杖化酬載。

平台行為：平台負責將 Google PayPaymentMethodData 回應對應至這個結構，然後傳送給商家。

名稱	類型	必要	說明
id	字串	是	平台指派的付款方式專屬 ID。
handler_id	字串	是	Google Pay 處理常式的 ID。
類型	字串	是	常數 = `card`。表示這項工具的行為類似於卡片 (會繼承卡片顯示欄位)。
brand	字串	是	發卡機構 (例如 `visa`、`mastercard`)。對應自 Google Pay 的 `info.cardNetwork`。
last_digits	字串	是	卡號末 4 碼。對應自 Google Pay 的 `info.cardDetails`。
rich_text_description	字串	否	資訊卡的選用複合式文字說明 (例如末碼為 1234 的 Visa 卡，有效期限至 2025 年 12 月)。
rich_card_art	字串 (URI)	否	代表卡片的複合式圖片 (例如發卡機構卡片圖片) 的選用 URI。
billing_address	郵政地址	否	與卡片相關聯的帳單地址。
憑證	憑證酬載	否	Google Pay 傳回的安全權杖化資料。

憑證酬載

這個物件是樂器的 credential。這會直接對應至 Google Pay 權杖化資料。

郵寄地址

這個物件做為 address 欄位。可直接對應至 PostalAddress。

3. 平台整合

3.1 規定

平台必須先完成下列事項，才能處理 com.google.pay 付款：

能夠載入 Google Pay API for Web (或 Android 相當於此 API 的項目)。
在顯示付款按鈕時，請遵守 Google Pay 品牌宣傳指南。

3.2 付款通訊協定

平台「必須」遵循這個流程來處理處理常式：

步驟 1：探索及設定

平台會初始化用戶端，以管理 API 生命週期。

參考資料： PaymentsClient

步驟 2：檢查付款準備情況

平台會先檢查使用者是否能透過指定付款方式付款，再顯示按鈕。

參考資料： isReadyToPay

步驟 3：建構付款要求

平台會組裝付款資料要求物件，包括商家設定、付款方式和交易詳細資料 (價格和幣別)。

參考資料： PaymentDataRequest

步驟 4：叫用使用者互動

當使用者與付款按鈕互動時，平台會觸發付款畫面顯示。

參考資料： loadPaymentData

步驟 5：完成結帳

使用者成功互動後，Google Pay API 會在 payment_data 鍵底下傳回 PaymentInstrument 物件。平台會將這項回應對應至 card_payment_instrument 結構定義，並提交結帳完成要求。

POST /checkout-sessions/{checkout_id}/complete

{
  "payment_data": {
    "id": "pm_1234567890abc",
    "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
    "type": "card",
    "brand": "visa",
    "last_digits": "4242",
    "billing_address": {
      "street_address": "123 Main Street",
      "extended_address": "Suite 400",
      "address_locality": "Charleston",
      "address_region": "SC",
      "postal_code": "29401",
      "address_country": "US",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "credential": {
      "type": "PAYMENT_GATEWAY",
      "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
    }
  },
  "risk_signals": {
      ...
  }
}

4. 商家處理

收到 Google Pay 付款工具後，商家「必須」採取下列行動：

驗證處理常式：確認 handler_id 對應至 Google Pay 處理常式。
擷取權杖：從 payment_data.credential.token 擷取權杖字串。
處理付款：將權杖字串和交易明細傳遞至 PSP 的端點。
- 注意：大多數 PSP 都有「Google Pay 酬載」或「網路權杖」的專屬欄位。
回覆：回覆最終結帳狀態 (成功/失敗)。

5. 安全性考量

5.1 權杖安全性

PAYMENT_GATEWAY:使用這種代碼化類型時，系統會專為代碼化當事人加密代碼。中介方無法解密這個權杖，應將權杖原封不動地傳送給權杖化方。
直接：如果使用 DIRECT 權杖化，商家會收到加密的卡片資料，必須解密。這會大幅擴大 PCI DSS 法規遵循範圍，因此一般不建議使用，除非商家是第 1 級 PCI 法規遵循服務供應商。

5.2 環境隔離

測試模式：在 TEST 環境中，Google Pay 會傳回虛擬權杖。因此無法收費。
正式版模式：使用真實卡片。商家必須確保 config.allowed_payment_methods 中的 PSP 憑證與環境相符。

Google Pay 付款處理常式規格 透過集合功能整理內容 你可以依據偏好儲存及分類內容。