客户端参考文档

本页中的参考内容介绍了用于在 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。

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

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

参数

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

返回

类型	说明
Promise	已解决 ：一个对象，包含有关用户能否付款的信息。如需了解详情，请参阅IsReadyToPayResponse。 遭拒：一个错误对象，包含有关 遭拒原因的详情。如需了解详情，请参阅 PaymentsError.

错误

statusCode	说明
DEVELOPER_ERROR	所传递的 IsReadyToPayRequest 对象格式不正确，缺少用于确定 用户是否准备好付款所需的最基本参数，或包含无效参数和/或值。 相应请求是从支付代理或浏览器 选择不实现的安全上下文发起的。出现这一错误最常见的原因就是 浏览器上下文不安全。

loadPaymentData(paymentDataRequest)

此方法可显示 Google Pay 付款表格，您可以使用该表格选择付款 方式和可以视需要进行配置的参数。

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

参数

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

返回

类型	说明
Promise	已解决 ：一个对象，包含所请求的买家数据。如需了解详情，请参阅 PaymentData 。 遭拒：一个对象，其中包含错误代码以及有关遭拒原因的更多信息 关于遭拒原因。如需了解详情，请参阅 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	已解决 ：一个对象，包含有关付款交易结果的信息。 如需了解详情， 请参阅 PaymentAuthorizationResult。 遭拒：一个错误对象，包含要在 付款表格中呈现的错误 Intent 和消息。如需了解详情， 请参阅 PaymentDataError。

onPaymentDataChanged(intermediatePaymentData)

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

注意 ：还必须设置 onPaymentAuthorized 回调，才能使用 onPaymentDataChanged 回调。您必须在 30 秒内 来解析 onPaymentDataChanged 回调 返回的 Promise。如果 ，Promise 将不会解析 ，请求将超时，Google Pay 表格会向用户显示 CALLBACK_TIMED_OUT 错误。

参数

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

返回

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