integrate-google-pay

Payroc Google Pay 集成

版本检查（请先执行）

在宣布任何内容或启动流程之前，请确认此技能为最新版本：

1. 从上方的 frontmatter 中读取 metadata.version 字段，获取此技能的版本。
2. 获取已发布的副本，并读取其 metadata.version： https://raw.githubusercontent.com/payroc/skills/main/plugins/payroc/transaction/skills/integrate-google-pay/SKILL.md
3. 将两个版本作为语义化版本进行比较：

   • 此版本 >= 已发布版本 → 静默继续，不发送消息。（开发者运行尚未发布的较新版本属于预期情况，也没有问题。）

   • 此版本 < 已发布版本 → 告知开发者：

     ⚠️ 此技能的新版本（v<published>）已发布 — 你正在运行 v<current>。建议升级以获得最佳效果。

     然后询问他们是想继续使用当前版本，还是停止并先升级，并遵从他们的选择。

   • 无法获取（离线、网络错误、404）→ 简要说明无法验证版本，然后继续。

---

首次调用时，向开发者宣布：

Payroc Google Pay 集成 我将指导你完成从商户设置到成功进行 UAT 测试交易的全过程。 本指南介绍如何将 Google Pay 用作结账页面上的支付方式 — 使用 Google Pay JS API 展示支付界面，并使用 Payroc Payments API 处理加密支付数据。

Google Pay 与 Payroc 的协作方式（分为四个部分）：

1. 使用 Payroc 的网关详细信息（网关名称和网关商户 ID）配置 Google Pay JS API
2. 客户点击 Google Pay 按钮后，Google 会显示支付界面
3. 客户选择银行卡并确认；Google 会返回加密支付数据
4. 你的服务器将加密数据转换为十六进制，并向 Payroc 支付端点发送 POST 请求

重要的网关细节（输出之前，请阅读本地说明文档）： Payroc 通过 Worldnet 网关（由 Payroc 收购）处理 Google Pay。references/google-pay.md 中的说明文档记录了 Google Pay tokenizationSpecification.parameters 的具体值 — gateway（固定常量）和 gatewayMerchantId（根据你的处理终端 ID 得出）。输出这两个值之前，请先阅读 references/google-pay.md，并严格使用其中记录的值 — 不要凭记忆输出。

Google Pay 与 Hosted Fields / HPP 的区别： Google Pay 是一种独立的支付流程 — 不使用 Hosted Fields JS 库或 HPP 表单。它是这些集成的补充，而非替代方案。

生产环境需要注册： 上线前，你必须向 Google 注册你的集成。UAT 测试无需注册。

[如果有可用的 MCP 连接检查工具，请在此处运行，并在继续之前展示结果。]

---

快速参考

# Identity service (Bearer token — server-side only)
POST https://identity.uat.payroc.com/authorize
x-api-key: <api-key>

# Google Pay JS library (client-side — load in the browser)
https://pay.google.com/gp/p/js/pay.js

# Payments API (server-side — process the hex-encoded Google Pay token)
POST https://api.uat.payroc.com/v1/payments
Authorization:  Bearer <token>
Content-Type:   application/json

# Production base URLs (swap when going live — see Step 4 and Completion)
#   identity.payroc.com/authorize   |   api.payroc.com/v1/payments

具体值、枚举集合和 Payroc 专用网关常量并未列在此区块中 — 请按照各步骤的指示，从 references/ 文件中读取。这只是端点一览表，不能替代参考文档。

---

参考资料

所有枚举值、架构和 Payroc 专属值都保存在下面的本地 references/ 文件中——此技能依据这些文件生成内容，而不是实时查询或凭记忆生成。以下是三个互为补充的来源，分别负责解答不同类型的问题——用错来源是已知的常见错误：

• Payroc API 架构（references/api-schema.md）——所有传输到 Payroc API 的内容的权威来源：字段名称、枚举值（channel、paymentMethod.type、paymentMethod.serviceProvider、transactionResult.status 等）、必填字段、请求／响应结构。这是从 Payroc OpenAPI 规范中整理出的部分内容。
• Payroc 说明文档（references/google-pay.md）——组合方式和 Payroc 专属网关值的权威来源：如何将 Google Pay JS 接入 Payroc、tokenizationSpecification.parameters 中应填写的内容（gateway 常量和 gatewayMerchantId 的推导方式）、十六进制编码要求。
• Google API 接口说明（references/third-party/google-request-objects.md 和 references/third-party/google-client.md）——Google Pay JS API 结构的权威来源：PaymentDataRequest、tokenizationSpecification、支持的网络和身份验证方法、PaymentsClient 方法（isReadyToPay、loadPaymentData、createButton）、paymentData 回调结构。这些说明以我们自己的措辞整理自 Google 记录的 API 接口说明——需要确认属性名称、可接受的子键或 PaymentsClient 上的方法名称时，请查阅这些文件。

如果你想问“Payroc 支付请求正文的结构是什么？”，请查阅 references/api-schema.md。如果你想问“gateway 应该是什么，以及如何推导 gatewayMerchantId？”，请查阅 references/google-pay.md。如果你想问“PaymentDataRequest 的确切结构是什么，以及 tokenizationSpecification 应放在其中的什么位置？”，请查阅 references/third-party/ 下的 Google 说明。Payroc 决定 tokenizationSpecification.parameters 内部的值；Google 决定外层容器的结构。

来源	本地文件	用途
Payroc API 架构	references/api-schema.md	Payroc API 字段名称、枚举值、请求／响应结构
错误响应格式	references/error-response-format.md	错误封装（RFC 7807）+ Payroc errors[] + 标准错误类型目录
将 Google Pay 添加到集成中（Payroc 说明文档）	references/google-pay.md	与 Payroc 的组合方式 + 标准 gateway 值 + gatewayMerchantId 推导方式
Google — 请求对象	references/third-party/google-request-objects.md	PaymentDataRequest、tokenizationSpecification、支持的网络、JS 对象结构
Google — 客户端	references/third-party/google-client.md	PaymentsClient 构造函数、isReadyToPay、loadPaymentData、createButton、回调结构

这些是本地快照，是此技能的权威资料。它们的来源 URL 和最后同步日期记录在 references/_sources.md 中——如果内容看起来过时，请从该文件重新生成。

---

核心原则

1. 先检查，再提问 — 先阅读代码库再提问；根据所发现的内容跳过显而易见的问题，并提出有针对性的问题。
2. 先提问，再编码 — 在编写实现代码之前，通过提问了解未知事项。
3. 先验证，再推进 — 在开发者确认当前步骤的检查点已通过 UAT 之前，不要进入下一步。
4. 阅读参考资料，不要猜测——并为问题选择正确的参考资料。 此集成有 三个 资料来源，而不是两个。针对问题使用错误的来源，会导致凭记忆得出的错误值混入代码。
   • Payroc API 架构、字段名称、枚举、必填字段 → references/api-schema.md。 任何会传输到 Payroc API 的内容。接受特定字符串的字段值（channel、paymentMethod.type、paymentMethod.serviceProvider、货币、国家/地区以及其他任何枚举类参数）都应以架构参考为准，而不是训练数据。即使某个字符串听起来很合理，只要它不在参考资料中，就会导致 API 错误。
   • 组合方式、Payroc 专用网关值（gateway、gatewayMerchantId 的推导）、十六进制编码要求 → references/google-pay.md。“Payroc 要求的 gateway 常量是什么？”和“如何推导 gatewayMerchantId？”属于叙述性文档问题，不属于架构或 Google 相关问题。
   • Google Pay JS API 结构、PaymentDataRequest、tokenizationSpecification、支持的网络、PaymentsClient 方法 → references/third-party/ 下的 Google 说明。 Payroc 叙述性文档会提及这些名称，但不能作为 Google 属性路径、子键拼写或方法签名的权威依据。如需核实 JS API 的任何内容，请阅读 Google 说明。
   • 不要混淆不同来源。 channel 属于 Payroc 支付请求（其枚举值位于 references/api-schema.md），不属于 Google Pay 请求。Google 支持的网络常量（例如 "VISA"、"MASTERCARD"）来自 Google 说明，属于 PaymentDataRequest，不属于 Payroc 支付请求。每个值都要查阅正确的参考资料。
5. 逐个值先读后输出。 输出任何枚举值之前（Payroc：channel、paymentMethod.type、paymentMethod.serviceProvider、货币、国家/地区、transactionResult.status；Google：支付网络、授权方式、环境）、任何 PaymentDataRequest 属性路径、任何 PaymentsClient.* 方法调用，或 Payroc 的 gateway 常量和 gatewayMerchantId 推导方式之前，都要先阅读相关的本地参考资料。Payroc 叙述性文档（references/google-pay.md）包含 gateway 常量和 gatewayMerchantId 的推导方式；references/api-schema.md 包含 Payroc REST 枚举；Google 说明包含 JS API 结构。不要凭记忆输出这些内容——请阅读对应的权威参考资料。
6. 绝不硬编码凭据 — API 密钥和终端 ID 必须来自环境变量或机密管理器，绝不能写入源代码。
7. 继续之前先诊断 — 如果某一步失败，请暂停并按照错误分类逐项排查后再继续。

---

需求收集

首先，扫描代码库。 查找：

• 服务端语言和框架
• 现有的结账或付款相关路由和处理程序
• 是否已有 Payroc 集成（HF 或 HPP）——可能已经配置了 API 密钥和终端 ID
• 环境变量或配置的管理方式
• 是否已配置任何 Google Pay JS 或 Google Pay 商户 ID

利用你发现的信息，避免询问可以直接推断出的内容。

然后询问仍需要确认的信息。至少确认：

问题 1 — Google Pay 是否是合适的产品？这是新增功能还是独立构建？

	Google Pay（此技能）	Hosted Fields	Hosted Pages (HPP)
客户体验	点击 Google Pay 按钮；使用已保存到 Google 钱包的银行卡付款——无需输入卡片信息	在你自己的表单中填写嵌入的 Payroc 组件里的卡片信息	重定向到 Payroc 托管的页面进行付款，然后返回你的网站
卡片数据所在位置	Google 钱包；你的服务器接收加密令牌	你页面中的 Payroc 组件	Payroc 托管的页面
兼容性	任何现代浏览器——Chrome、Edge、Firefox，以及 iOS 上的 Chrome；不包括 Safari（Safari 使用 Apple Pay）	所有现代浏览器	所有现代浏览器
此技能	✓ 涵盖	单独的技能	单独的技能

Google Pay 是银行卡输入方式的补充，而非替代品——大多数集成会将其与 Hosted Fields 或 HPP 一同提供。它并非仅限 Android：iOS 用户可以像 Android 用户一样在 Chrome 上使用 Google Pay。关键在于浏览器，而非设备——任何设备上的 Safari 都不支持 Google Pay。明确这一点后，确认这是新增功能还是独立构建：

• 将 Google Pay 添加到现有 Payroc 集成（HF 或 HPP）中 → 很可能已经配置了 API 密钥和终端 ID；重点关注 Google Pay 专属步骤
• 新集成，仅使用 Google Pay → 从头开始，包括配置凭据

问题 2 — Google 商户 ID：

Google Pay 用于生产环境时需要 Google 商户 ID（注册集成时由 Google 分配）。UAT 测试可以使用测试商户 ID。

• 已有 Google 商户 ID → 记录下来；Google Pay JS 配置会用到它
• 尚未向 Google 注册 → 可以使用测试 ID 进行 UAT 测试；上线前必须完成注册

等待开发者回答后再继续。

---

前置条件

运行和测试 Google Pay 需要以下内容——编写代码则不需要。开发者如果已经准备好这些内容，那就太好了。如果还没有，也不要停下来：让代码从环境变量读取每个值，然后继续构建。开发者可以在测试前提供实际值。

1. API 密钥——用于从 Payroc 的身份服务获取 Bearer 令牌。与 Hosted Fields 使用的是同一凭证，由 Payroc Integrations 团队提供。
2. 处理终端 ID——由 Payroc Integrations 团队提供的 UAT 终端 ID。此 ID 也用于推导 gatewayMerchantId（终端 ID 去掉最后三个字符）。
3. Google Merchant ID——UAT 可以使用测试值，因此它不会阻碍开发。生产环境需要通过向 Google 注册获取（参见步骤 4）；代码可以从 GOOGLE_MERCHANT_ID 之类的变量读取它。

如果缺少任何内容——发出提醒，不要阻止开发。 扫描代码库，查找现有的环境变量命名惯例并遵循；否则，建议使用 PAYROC_API_KEY、PAYROC_TERMINAL_ID 和 GOOGLE_MERCHANT_ID 之类的名称。编写代码从环境中读取这些值，然后明确告知开发者：

⚠️ 我已将代码配置为从 <VAR names> 读取 API 密钥、终端 ID 和 Google Merchant ID。要在 UAT 中运行或测试，你需要 Payroc UAT 终端和 API 密钥（请联系 Payroc Integrations 团队）；UAT 可以使用测试 Google Merchant ID，而生产环境需要真实的 Google Merchant ID（从 Google Pay Business Console 获取；参见步骤 4）。与此同时，我可以继续构建。

主动提出协助获取缺少的内容；如果开发者愿意，就继续开发。

检查点

凭证已确认，或者开发者已了解尚缺少哪些内容、如何获取，以及代码会从哪些环境变量读取这些内容，并已选择继续。不要对缺少的内容含糊其辞，但也不要因此阻止开发。

---

步骤 1 — 进行身份验证：获取 Bearer 令牌

阅读：references/identity-call.md——规范的 Bearer 令牌交换参考。不要猜测身份验证端点 URL、请求头名称或响应格式——只采用此文件记载的内容。 阅读：references/google-pay.md——Payroc 说明；用于确认 Bearer 身份验证在 Google Pay 流程中的作用。

开始编写任何内容之前，先阅读以上两个文件。根据参考资料，确认：

• 身份服务端点
• 必需的请求头及其格式
• 包含访问令牌的响应字段

实现一个服务端函数，向身份服务发送 POST 请求并附带 API 密钥，然后返回访问令牌。此函数必须在服务端运行——绝不能将 API 密钥发送到浏览器。

检查点

该调用是否返回包含 access_token 的 200 响应？

---

步骤 2 — 配置并加载 Google Pay JS

此步骤涉及两个来源——Google 定义 PaymentDataRequest 的结构和 PaymentsClient API；Payroc 定义 tokenizationSpecification.parameters 中的值。开始编写任何内容之前，先阅读两者：

• 阅读：references/third-party/google-request-objects.md——了解精确的属性路径（allowedPaymentMethods、tokenizationSpecification、merchantInfo、transactionInfo）、受支持网络常量的拼写，以及身份验证方法常量。
• 阅读：references/third-party/google-client.md——了解 PaymentsClient、isReadyToPay、loadPaymentData、createButton 及其参数和返回值结构。
• 阅读：references/google-pay.md——了解 gateway 常量、gatewayMerchantId 的推导方式，以及 tokenizationSpecification.parameters 中其他 Payroc 专属的值。

发出任何 PaymentDataRequest 或 PaymentsClient.* 调用之前——查阅 Google 说明

1. 要阅读什么。 上述两份 Google 说明（request-objects + client）。不要根据训练数据转述 API。
2. 要确认什么。
   • PaymentDataRequest 的确切属性层级，以及其中 tokenizationSpecification 所处的位置。
   • 支持的网络常量（Google 使用 "VISA" / "MASTERCARD"——请确认大小写）。
   • PaymentsClient 构造函数参数的形式、isReadyToPay 参数的形式，以及 loadPaymentData 的返回形式。
3. 然后才发出调用。 将 PaymentDataRequest 中的每个属性放在 Google 说明文档指定的路径上。按照文档中的接口调用每个 PaymentsClient.* 方法。如果你假设存在的方法或属性并未出现在 Google 说明中，不要臆造其他名称再试——应从源文件重新推导（参见 references/_sources.md），而不是猜测。

发出 gateway 和 gatewayMerchantId 之前——查阅 Payroc 说明文案

它们是 Payroc 专属值，而非 Google 值——位于 tokenizationSpecification.parameters 中。references/google-pay.md 是权威来源。

1. 要阅读什么。 references/google-pay.md——记录 tokenizationSpecification 配置的部分（说明步骤 1，“集成 Google Pay API”）。
2. 要确认什么。
   • 说明文案中记录的确切 gateway 常量。
   • gatewayMerchantId 的确切推导规则。如果文案没有明确说明推导方式，请升级处理，不要猜测。
3. 然后才发出调用。 严格使用说明文案中记录的值——不要替换成记忆中的值。

仅在阅读上述参考资料后实现客户端集成：

1. 加载 Google Pay JS 库：https://pay.google.com/gp/p/js/pay.js
2. 使用适当的环境（UAT 使用 TEST，正式环境使用 PRODUCTION）创建 PaymentsClient——请根据 Google client 说明确认环境常量。
3. 在渲染按钮之前，使用支持的支付方式调用就绪检查方法（根据 Google client 说明为 isReadyToPay）。
4. 仅当就绪检查返回 true 时，使用 createButton 渲染 Google Pay 按钮（根据 Google client 说明）。
5. 点击按钮时，使用完整的 PaymentDataRequest 调用 loadPaymentData。
6. 成功后，将 paymentData 发送到你的服务器（步骤 3）。

Google Pay JS 形态的已知故障模式

列出这些模式是为了帮助你识别症状——修复方法始终是阅读相关本地参考资料，并按文档内容发出调用，而不是“使用下方的值”。

• 症状： loadPaymentData 因 OR_BIBED_* 或类似的 Google 端错误而拒绝请求，错误指出令牌化规范存在问题。过去的错误： 将 gateway / gatewayMerchantId 放在 tokenizationSpecification.parameters 之外，或根据训练数据推断路径，而不是查阅 Google 说明。检查： references/third-party/google-request-objects.md，确认 tokenizationSpecification 的确切嵌套结构。
• 症状： Payroc 支付调用拒绝了经过网关令牌化的数据。过去的错误： 根据训练数据而不是 Payroc 说明文案确定 gateway 常量或 gatewayMerchantId 的推导方式。检查： references/google-pay.md，这是这两个值的权威来源。
• 症状： PaymentsClient 方法出现 TypeError 或返回形式异常。过去的错误： 假定了参数或返回形式。检查： references/third-party/google-client.md。

检查点

Google Pay 按钮是否在页面上显示？点击后是否会弹出支付界面？

---

第 3 步 — 处理付款

此步骤涉及两个来源——Google 负责 paymentData 中加密令牌的格式；Payroc 负责你将 POST 到 /v1/payments 的包装结构和枚举值。请阅读两者：

• **Google — paymentData 回调结构：**确认加密令牌在 paymentData 中的位置（例如 paymentData.paymentMethodData.tokenizationData.token）——阅读 references/third-party/google-request-objects.md，不要依赖训练数据。
• **Payroc 说明文档和架构：**阅读 references/google-pay.md 了解组成方式，并阅读 references/api-schema.md（paymentRequest、paymentMethod 的 digitalWallet 变体）了解确切的字段名称和枚举值。

**不要使用训练知识中的任何字段名称、端点 URL 或加密数据格式。**这里有两个不同的来源：Google 负责 paymentData 的结构（references/third-party/）；Payroc 负责 references/api-schema.md 中的请求正文结构。生成代码前请阅读两者。

loadPaymentData 解析后，paymentData 对象中包含加密的付款信息。你的服务器必须：

1. 从 paymentData 中提取加密付款令牌（确切路径请对照 Google 请求对象说明确认）。
2. 将其转换为十六进制格式（阅读 references/google-pay.md 中的确切要求；若其中没有明确说明，请查看 references/api-schema.md 中 encryptedData 字段所记录的格式限制）。
3. POST 到 Payroc 付款端点。其结构（请从 references/api-schema.md 中读取）通常类似于：
   • paymentMethod.type — 从 references/api-schema.md（paymentMethod.type 枚举）中读取数字钱包当前的枚举值；不要凭记忆假定为 "digitalWallet"。
   • paymentMethod.serviceProvider — 从 references/api-schema.md 中读取 Google Pay 当前的枚举值；不要凭记忆假定为 "google"。
   • paymentMethod.encryptedData — 第 2 步中经过十六进制编码的令牌。
   • 以及标准的 channel、processingTerminalId、order 字段（均须先读取再输出；请参阅下方的枚举提示）。
4. HTTP 状态码为 201 时——检查响应正文（请参阅下方的成功分支提示）后，向客户端返回成功并显示确认信息。
5. 发生任何错误时——向客户端显示错误。

从 references/api-schema.md 中读取 Payroc 的 channel 枚举。channel 属于 Payroc 付款请求，而不是 Google Pay 请求。**已知的过往问题（来自同类集成）：**模型输出了 channel: "internet"，因为这个值听起来适合浏览器内结账——Payroc 返回 HTTP 400，错误详情中列出了枚举值。解决方法不是在这里记住正确的值，而是在构造请求正文时，从架构参考中读取 paymentRequest.channel。听起来合理的相近值（internet、online、ecommerce、card-not-present）是这类错误最常见的表现。

**根据 responseCode 判断付款是否成功，不要猜测 transactionResult.status 的成功状态子集。**请阅读 references/api-schema.md。批准信号是 responseCode === 'A'（成功响应还会包含 approvalCode 和值为 OK 的 responseMessage）。transactionResult.status 表示生命周期状态：在 A 的情况下，ready（已排队／已捕获）和 pending（已授权、等待捕获——例如预授权或 autoCapture: false）都表示授权成功；declined／expired 等则不成功。**已知的过往问题（来自同类集成和我们的基准测试）：**模型创建了一个 APPROVAL_STATUSES 列表，却遗漏了部分状态（例如 pending），因而将真实授权静默地判定为失败。不要凭记忆枚举状态集合——在成功分支中以 responseCode === 'A' 为判断依据，并用 status 判断生命周期。请有意处理 E（延迟处理）和 P（部分批准）；将 D／R／C 视为拒绝。

检查点

支付 API 在 UAT 中是否返回 HTTP 201？结账页面是否显示了付款确认信息？

---

步骤 4 — 在 Google 注册（仅限生产环境）

上线前，必须先在 Google 注册集成：

1. 在 Google Pay Business Console 注册
2. Google 将分配一个生产环境 merchantId
3. 将 PaymentsClient 环境从 TEST 切换为 PRODUCTION
4. 联系 Payroc 集成团队（[email protected]），确认已为该终端启用 Google Pay 实时处理

UAT 测试不需要此步骤。

---

本地测试策略

Google Pay 完全采用客户端加服务端的方式——没有入站 Webhook，因此不同于 HPP，它不要求能够通过公共 URL 访问，也不需要隧道（ngrok、Dev Tunnels 等）。

• Google Pay 按钮需要安全上下文。浏览器会将 http://localhost 视为安全，因此本地开发无需 HTTPS；其他主机必须通过 HTTPS 提供服务，按钮才能显示。
• 在 UAT 中，将 PaymentsClient 的环境设为 TEST——Google 会返回 Payroc 的 UAT 终端可接受的测试支付数据。在 TEST 环境中测试无需在 Google Business Console 注册。
• 生产环境需要在 Business Console 注册（步骤 4），并使用生产基础 URL 和 PRODUCTION 环境——但不需要按域名配置验证文件（这是 Apple Pay 的要求，而非 Google Pay 的要求）。

---

错误分类

症状	可能原因	修复方法
Google Pay 按钮始终未显示	isReadyToPay 返回了 false	检查支持的网络和认证方法是否符合测试环境的要求；在 TEST 环境中，任何设备都应可用
loadPaymentData 抛出错误或被拒绝	PaymentDataRequest 配置错误	检查浏览器控制台中的 Google Pay 错误详情；确认 gateway、gatewayMerchantId 和 merchantId 字段符合文档要求
支付界面已显示，但确认时失败	gatewayMerchantId 不正确	确认其推导方式：终端 ID 去掉最后 3 个字符——阅读 references/google-pay.md 验证公式
Payments API 返回 401	Bearer token 已过期或 API 密钥错误	重新获取 Bearer token；验证 x-api-key 的值
Payments API 返回 400	encryptedData 不是十六进制格式，或缺少必需字段	重新阅读 references/google-pay.md / references/api-schema.md 中对 encryptedData 格式的要求；确认十六进制转换逻辑
Payments API 已处理请求，但结果出乎意料	serviceProvider 的值错误	必须为 "google"（小写）；检查大小写是否有误
生产环境中的按钮在 TEST 中可用，但在 PRODUCTION 中不可用	尚未在 Google 注册，或未启用实时处理	完成 Google Pay Business Console 注册；联系 Payroc Integrations 团队
Payments API 返回 HTTP 400，错误详情中指出 "channel"（或其他枚举类型字段），并列出可接受的值	发出了非枚举值（过去其他集成的失败案例：channel: "internet"、"online"、"ecommerce"）；用听起来合理的近似值替代了架构中定义的值	从 references/api-schema.md 中读取 paymentRequest.channel（或相关字段），并发出列出的值之一。不要根据英文表达是否合理来推断枚举值。
Payroc API 拒绝 paymentMethod.type 或 paymentMethod.serviceProvider	技能发出了从训练数据中记住的 digitalWallet / google 值，而不是从 references/api-schema.md 中读取的值	从 references/api-schema.md 中读取当前的 paymentMethod.type 和 paymentMethod.serviceProvider 枚举，并发出其中列出的值。即使记住的值碰巧正确，没有读取参考文档这一流程错误本身也属于缺陷。
PaymentDataRequest 被 Google 端错误（OR_BIBED_* 或类似错误）拒绝，错误指出 tokenizationSpecification 有问题	gateway / gatewayMerchantId 的位置或值取自训练数据；或者 tokenizationSpecification 在请求中的嵌套路径错误	阅读 references/third-party/google-request-objects.md，了解准确的嵌套结构；阅读 references/google-pay.md，了解 gateway 常量和 gatewayMerchantId 的推导方式。必须同时查阅这两个来源；只查阅其中一个是不够的。
PaymentsClient 方法出现 TypeError 或返回意外的数据结构	构造函数参数结构、方法名或回调结构取自训练数据，而非 Google 客户端说明	阅读 references/third-party/google-client.md。确认构造函数及将要调用的每个方法。不要臆造或重命名——如果你假设的方法名未出现在 Google 说明中，请从源文件重新推导（参见 references/_sources.md）。
应用记录了支付失败，但银行实际上已批准——Payroc 响应显示 responseCode: "A"，并带有 approvalCode / OK 消息	成功分支依据猜测的 transactionResult.status 子集作出判断（过去的失败案例：APPROVAL_STATUSES 列表遗漏了 pending 等已授权状态，导致真实授权被静默判为失败）	根据 references/api-schema.md，以 responseCode === 'A' 作为成功分支的判断条件；将 ready 和 pending 视为已授权状态，status 仅表示生命周期状态。不要凭记忆枚举一组审批状态。

---

验证清单

• API 密钥和终端 ID 从环境变量中读取，而非写在源代码中
• Bearer 令牌在服务器端生成，不会暴露给浏览器
• gateway 常量和 gatewayMerchantId 的推导方式已从 references/google-pay.md 中读取（而非凭记忆），且值与说明文本一致
• PaymentDataRequest 结构和 PaymentsClient.* 调用已对照 references/third-party/ 下的 Google 说明核验
• 每个 Payroc API 枚举值（channel、paymentMethod.type、paymentMethod.serviceProvider 等）均已从 references/api-schema.md 中读取
• 服务器端成功分支根据 responseCode === 'A' 进行判断（依据 references/api-schema.md），将 ready 和 pending 视为已授权，将 D/R/C 视为拒绝，而非猜测 transactionResult.status 的部分取值
• 仅当 isReadyToPay 返回 true 时才渲染 Google Pay 按钮
• 在发送到 Payroc API 前，已将加密的支付数据转换为十六进制格式
• 使用 Google Pay 测试交易时，支付 API 在 UAT 中返回 HTTP 201
• （生产环境）已完成 Google Pay Business Console 注册，并更新 merchantId
• （生产环境）Payroc Integrations 团队已确认启用实时处理

---

反模式

凭记忆输出 gateway 常量或推导 gatewayMerchantId，而不是依据说明文本。 这些值位于 references/google-pay.md 中。输出其中任一值前都要先阅读该文件，不要凭记忆输出。过去出现的问题包括 gateway 常量的大小写错误以及推导错误（例如删除了错误数量的字符），这两种情况都会导致身份验证或路由失败。

将记忆当作 tokenizationSpecification.parameters 的权威依据。 tokenizationSpecification.parameters 中的值是 Payroc 专用的，位于 references/google-pay.md 中。tokenizationSpecification 周围的结构（即它在 PaymentDataRequest 中的位置）由 Google 定义，位于 references/third-party/google-request-objects.md 中。两处都要阅读；只看其中一处并不足够。

无条件渲染 Google Pay 按钮——始终根据 isReadyToPay 的结果进行控制。渲染不可用的按钮会导致点击时出错。

对整个 paymentData 对象进行十六进制编码——只应对 paymentData 中的加密支付令牌进行十六进制编码；请从 references/third-party/google-request-objects.md 中确认具体字段。

上线前跳过 Google 注册——TEST 环境无需注册即可运行，但生产环境若未完成 Business Console 注册并联系 Payroc，则无法处理交易。

---

完成

确认 HTTP 201 且所有清单项均通过后：

集成完成。 以下是你已构建的内容：

• Google Pay 按钮——按条件渲染；点击后显示 Google Pay 支付界面。
• 网关配置——gateway 常量和 gatewayMerchantId 值均从 Payroc Google Pay 说明文本中读取；请求通过 Payroc 路由。
• 支付处理——将加密的支付数据转换为十六进制格式，并发送到 Payroc 支付端点。
• 已在 UAT 中验证——已确认端到端 Google Pay 交易。

**上线前：**完成 Google Pay Business Console 注册，使用生产环境的值更新 merchantId，将 PaymentsClient 切换到 PRODUCTION 环境，将 UAT 支付 API URL 替换为生产环境 URL，并向 Payroc Integrations 团队确认已启用实时处理。

提供后续步骤：

• Apple Pay——为使用 Safari（iOS 或 macOS）的客户添加 Apple Pay；它能覆盖 Google Pay 无法触达的 Safari 用户群。Apple Pay 使用 Apple Pay JS API，并需要验证域名——另有单独的技能介绍此流程。
• Hosted Fields——如果开发者还需要信用卡输入表单作为备用方案，请使用 Hosted Fields 技能