客户端参考文档

本页中的参考内容介绍了用于在 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。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 属性的变化不会影响缓存的预取值。

onPaymentAuthorized(paymentData)

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

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

参数

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

返回结果

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

onPaymentDataChanged(intermediatePaymentData)

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

注意：还必须设置 onPaymentAuthorized 回调，以使用 onPaymentDataChanged 回调。

参数

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

返回结果

类型	说明
Promise	已解决：一个对象，包含有关新交易、运费选项和付款数据错误的信息。如需了解详情，请参阅 PaymentDataRequestUpdate。 遭拒：一个错误对象，包含要在付款表格中呈现的错误 Intent 和消息。如需了解详情，请参阅 PaymentDataError。 注意：“拒绝”不用于使用新的运费选项和交易信息更新付款表格。如果可能，不要故意返回拒绝。