客户端参考文档

本参考文档介绍了在 Web 应用中实现 Google Pay API 时要使用的 JavaScript 客户端方法。

构造函数

初始化 PaymentsClient 对象。您必须先调用此构造函数，然后才能调用成员方法。

new PaymentsClient(paymentOptions)

参数

属性	说明
paymentOptions	包含 Google Pay API 配置数据的键值对的对象。如需了解可配置的不同属性，请参阅 PaymentOptions。 示例：{environment:'PRODUCTION'}

返回

类型	说明
google.payments.api.PaymentsClient	PaymentsClient 对象。

抛出

类型	说明
Error	不支持传递的环境属性值。

对象方法

createButton(options)

此便捷方法用于生成采用最新 Google Pay 品牌设计的 Google Pay 付款按钮，以便插入到网页中。

生成的 HTMLElement 包含动态插入的 CSS 和托管在 Google CDN 上的 SVG 图片。

如需详细了解如何根据网站设计选择合适的按钮颜色和按钮类型，请参阅我们的品牌推广指南。您可能需要更改按钮的尺寸，使其与页面上的类似按钮或结账元素相匹配。您可以使用我们的自定义按钮工具，针对您的使用场景配置按钮。

注意：在实现 createButton API 时，剥离 onLoad 和 onClick 事件监听器可能会导致 Google Pay 付款按钮无法按预期运行。

参数

名称	说明
options	包含按钮配置的键值对的对象。 如需了解可配置的属性，请参阅 ButtonOptions。 示例：{onClick:onGooglePaymentButtonClicked}

返回

类型	说明
HTMLElement	通用流内容容器（例如 <div>）内的 HTML <button>。

抛出

类型	说明
Error	未设置必需属性。

isReadyToPay(isReadyToPayRequest)

使用 isReadyToPay(isReadyToPayRequest) 方法确定用户是否能够从 Google Pay API 返回支付方式。

如果浏览器支持 Google Pay，isReadyToPay 会返回 true。如需确定用户是否已登录 Google 账号，或是否已在 Google Pay 中保存支付方式，请将 IsReadyToPayRequest.existingPaymentMethodRequired 设置为 true，并验证 paymentMethodPresent 是否在已解析的 promise 中返回 true。如需了解详情，请参阅 IsReadyToPayResponse。

如果 PaymentsClient 使用环境属性 TEST 进行初始化，paymentMethodPresent 始终返回 true。

警告：在确定是否显示 Google Pay 按钮时，不应依赖 existingPaymentMethodRequired。existingPaymentMethodRequired 属性依赖于 Cookie 和跨网站跟踪。 如果这些信息不可用，则即使 isReadyToPayRequest.existingPaymentMethodRequired 设置为 true，系统也不会返回 paymentMethodPresent 属性。

参数

名称	说明
isReadyToPayRequest	一个包含商家支持的付款方式的对象。如需详细了解可配置的不同属性，请参阅 IsReadyToPayRequest。

返回

类型	说明
Promise	已解析：一个对象，其中包含有关用户支付能力的信息。如需了解详情，请参阅 IsReadyToPayResponse。 Rejected：一个错误对象，其中包含有关拒绝原因的更多信息。如需了解详情，请参阅 PaymentsError。

错误

statusCode	说明
DEVELOPER_ERROR	传递的 IsReadyToPayRequest 对象的格式不正确，缺少确定用户是否准备好付款所需的最低参数，或者包含无效的参数和/或值。 该请求是从支付代理或浏览器选择不满足的安全上下文发起的。最常见的是不安全的浏览器上下文错误。

loadPaymentData(paymentDataRequest)

此方法会显示一个 Google Pay 付款表格，用户可以在其中选择付款方式和可选配置参数。

当浏览器因点击事件而处理激活行为时，必须调用此方法。系统可能会向用户显示一个弹窗，供其选择支付方式或传入的请求参数中指定的其他必需数据。

参数

名称	说明
paymentDataRequest	一个包含完整 Google Pay API 配置的键值对的对象。 如需了解可配置的属性，请参阅 PaymentDataRequest。

返回

类型	说明
Promise	Resolved：包含所请求买家数据的对象。如需了解详情，请参阅 PaymentData。 Rejected：一个对象，其中包含错误代码以及有关拒绝原因的更多信息。如需了解详情，请参阅 PaymentsError。

错误

statusCode	说明
CANCELED	当前浏览器或已登录的 Google 用户不受支持。 买家关闭了 Google Pay 付款页面，未授权付款。 请求是从支付代理或浏览器选择不履行的安全上下文中发起的。最常见的是不安全的浏览器上下文。 在 Google Pay 付款表格已显示的情况下调用了该方法。 传递的 PaymentDataRequest 对象被 Google Pay 付款表格拒绝。网关的PaymentMethodTokenizationSpecification 参数缺失或不完整，或者参数值无效，是常见原因。
DEVELOPER_ERROR	传递的 PaymentDataRequest 对象格式不正确、缺少最低要求的参数，或者包含无效的参数和/或值。

prefetchPaymentData(paymentDataRequest)

使用此方法可预提取 PaymentDataRequest 配置，以缩短后续用户互动时的 loadPaymentData 执行时间。不返回任何值。

Chrome（Android 版）提供预提取优化功能。

参数

名称	说明
paymentDataRequest	一个包含完整 Google Pay API 配置的键值对的对象。 如需了解可配置的属性，请参阅 PaymentDataRequest。transactionInfo 属性的更改不会影响缓存的预提取值。

付款数据回调

以下回调处理程序可以传递给 PaymentOptions.paymentDataCallbacks，以支持授权付款和动态价格更新。

onPaymentAuthorized(paymentData)

当付款在付款表格中获得授权时，系统会调用此方法。

注意：您必须 解析 onPaymentAuthorized 回调返回的 promise 。如果 且 promise 未 在此时间范围内解析，则请求会超时，并且 Google Pay 页面会向用户显示 CALLBACK_TIMED_OUT 错误。

参数

名称	说明
paymentData	一个包含所请求的买家数据的对象。如需了解详情，请参阅 PaymentData。

返回

类型	说明
Promise	Resolved：一个包含付款交易结果相关信息的对象。 如需了解详情，请参阅 PaymentAuthorizationResult。 Rejected：一个错误对象，其中包含要在付款表格中呈现的错误 intent 和消息。如需了解详情，请参阅 PaymentDataError。

onPaymentDataChanged(intermediatePaymentData)

此方法用于处理付款表格中的付款数据更改，例如送货地址和运费选项。

注意：还必须设置 onPaymentAuthorized 回调，才能使用 onPaymentDataChanged 回调。您必须 解析 onPaymentDataChanged 回调返回的 promise （在 30 秒内）。如果 且 promise 未 在此时间范围内解析，则请求会超时，并且 Google Pay 页面会向用户显示 CALLBACK_TIMED_OUT 错误。

参数

您好

名称	说明
intermediatePaymentData	一个对象，其中包含在付款表格中选择的地址和送货选项。如需了解详情，请参阅 IntermediatePaymentData。

返回

类型	说明
Promise	Resolved：一个对象，其中包含有关新交易信息、运费选项和付款数据错误的信息。如需了解详情，请参阅 PaymentDataRequestUpdate。 Rejected：一个错误对象，其中包含要在付款表格中呈现的错误 intent 和消息。如需了解详情，请参阅 PaymentDataError。 注意：拒绝操作不会更新付款单的内容，只会向用户显示出错提示。