响应对象

本参考文档介绍了可用于您网站的 Google Pay API 响应对象选项。 响应对象是由 Google Pay API 客户端方法返回的对象。

IsReadyToPayResponse

此对象可提供网站访问者向请求付款信息的网站提供付款信息的能力。

属性 类型 始终存在 说明
result 布尔值 是 当前访问者能够向请求付款信息的网站提供付款信息。 访问者能否付款可能取决于其网络浏览器能否显示指定支付方式所需的组件。这包括他们登录 Google 账号并提供支付方式的情况。
paymentMethodPresent 布尔值 否

如果为 true，则表示访问者具有所提供的 IsReadyToPayRequest 的 allowedPaymentMethods 属性中指定的一种或多种支付方式。

仅当在 IsReadyToPayRequest 中将 existingPaymentMethodRequired 设置为 true 时才存在。

如果 PaymentsClient 是使用 TEST 的 environment 属性初始化的，则系统始终认为存在支付方式。

示例

以下示例展示了当前访问者何时能够向请求付款信息的网站提供付款信息。

{
  "result": true
}

PaymentData

这是付款人批准付款后由 Google 返回的响应对象。

PaymentDataRequest.PaymentDataRequest.PaymentDataRequest。
属性 类型 始终存在 说明
apiVersion 数值 是 主要 API 版本。响应中的值与 PaymentDataRequest 中提供的值一致。
apiVersionMinor 数值 是 次要 API 版本。响应中的值与 PaymentDataRequest 中提供的值一致。
paymentMethodData PaymentMethodData 是 所选支付方式的相关数据。
email 字符串 否 邮箱（如果在 PaymentDataRequest 中将 emailRequired 设置为 true）。 如果另一个请求将该属性设置为 true，则没有任何影响。
shippingAddress 地址 否 送货地址（如果在 PaymentDataRequest 中将 shippingAddressRequired 设置为 true）。

示例

此 Google Pay API 2.0 版响应示例显示了在 Google Pay 付款表格中选择的 CARD 支付方式。已为 example 网关生成支付方式令牌。

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "paymentMethodData": {
    "type": "CARD",
    "description": "Visa •••• 1234",
    "info": {
      "cardNetwork": "VISA",
      "cardDetails": "1234",
      "cardFundingSource": "CREDIT"
    },
    "tokenizationData": {
      "type": "PAYMENT_GATEWAY",
      "token": "examplePaymentMethodToken"
    }
  }
}

IntermediatePaymentData

当付款表格中的送货地址或运费选项发生更改时，Google Pay API onPaymentDataChanged() 输入会返回此对象。

属性 类型 必要性 说明
callbackTrigger 字符串 可选

描述调用付款数据回调的原因。

  • INITIALIZE
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION
  • PAYMENT_METHOD
  • OFFER
offerData OfferData 可选 用户提供的促销代码。
shippingAddress IntermediateAddress 可选 付款表格中选择的地址。
shippingOptionData SelectionOptionData 可选 付款表格中选择的运费选项。
paymentMethodData IntermediatePaymentMethodData 可选 在付款页面中选择的支付方式数据。

示例

此示例展示了 Google Pay API 针对送货地址更改返回的中间载荷。

{
  "callbackTrigger": "SHIPPING_ADDRESS",
  "offerData": {
    "redemptionCode": "exampleCode"
  },
  "shippingAddress": {
    "administrativeArea": "NY",
    "countryCode": "US",
    "locality": "New York",
    "postalCode": "10011"
  },
  "shippingOptionData": {
    "id": "shipping-001"
  }
}

此示例展示了支付方式发生变化时返回的中间载荷。

{
  "callbackTrigger": "PAYMENT_METHOD",
  "paymentMethodData": {
    "type": "CARD",
    "info": {
      "cardNetwork": "VISA",
      "cardFundingSource": "CREDIT",
      "billingAddress": {
        "administrativeArea": "NY",
        "countryCode": "US",
        "locality": "New York",
        "postalCode": "10011"
      }
    }
  }
}

PaymentMethodData

此对象可提供所选支付方式的数据。

属性 类型 始终存在 说明
type 字符串 是 PaymentMethod 在 Google Pay 付款表格中选择的 type。
description 字符串 是

面向用户的消息，用于描述为这笔交易提供资金的支付方式。
info 对象 是 此属性的值取决于返回的支付方式 type。对于 CARD，请参阅 CardInfo。
tokenizationData PaymentMethodTokenizationData 否 所选支付方式的支付令牌化数据。

示例

此示例响应展示了在 Google Pay 付款页面中选择的 CARD 支付方式如何为 example 网关生成支付方式令牌。

{
  "type": "CARD",
  "description": "Visa •••• 1234",
  "info": {
    "cardNetwork": "VISA",
    "cardDetails": "1234"
  },
  "tokenizationData": {
    "type": "PAYMENT_GATEWAY",
    "token": "examplePaymentMethodToken"
  }
}

CardInfo

此对象可提供所选支付卡的相关信息。

属性 类型 始终存在 说明
cardDetails 字符串 是 卡片的详细信息。此值通常是所选支付账号的后四位数字。
assuranceDetails AssuranceDetailsSpecifications 是 如果 CardParameters 中的 assuranceDetailsRequired 设置为 true，则此对象可提供对返回的付款数据执行验证的相关信息。
cardNetwork 字符串 是

所选付款方式的支付卡网络。 返回的值与 CardParameters 中的 allowedCardNetworks 格式一致。

此卡组织值不应向买家显示。当需要买家的卡详细信息时，可以使用此方法。例如，如果客户服务需要此值来识别买家用于交易的卡。如需提供用户可见的说明，请改用 PaymentMethodData 的 description 属性。
billingAddress 地址 否 与所提供支付方式关联的账单邮寄地址（如果 CardParameters 中的 billingAddressRequired 设置为 true）。
cardFundingSource 字符串 是

所选支付方式的卡片资金来源。

  • UNKNOWN
  • CREDIT
  • DEBIT
  • PREPAID

示例

此示例展示了 Visa 网络中的卡。

{
  "cardNetwork": "VISA",
  "cardDetails": "1234",
  "cardFundingSource": "CREDIT",
  "assuranceDetails": {
    "cardHolderAuthenticated": false,
    "accountVerified": true
  }
}

AssuranceDetailsSpecifications

此对象可提供对返回的付款凭据执行了何种验证的相关信息，以便进行适当的付款方式风险检查。

名称 类型 说明
accountVerified 布尔值 如果为 true，则表示已对返回的付款凭据执行了Cardholder所有权验证。
cardHolderAuthenticated 布尔值

如果为 true，则表示已对返回的付款凭据执行了身份验证和识别 (ID&V)。

如果为 false，则可以执行与卡交易相同的基于风险的身份验证。这种基于风险的身份验证可以包括但不限于使用 3D Secure 协议进行升级（如果适用）。

即使您不使用 assuranceDetails 字段，也可以接收和处理响应对象。如需接收此对象，请在 Request 对象的 CardParameters 中添加 assuranceDetailsRequired: true。

PaymentMethodTokenizationData

此对象可提供支付方式的令牌化数据。

属性 类型 始终存在 说明
type 字符串 是 要应用于所选支付方式的令牌化类型。 此值与 PaymentMethodTokenizationSpecification 中设置的 type 匹配。
token 字符串 否

生成的支付方式令牌。

示例

以下是为 example 网关准备的令牌化响应示例。

{
  "type": "PAYMENT_GATEWAY",
  "token": "examplePaymentMethodToken"
}

PaymentAuthorizationResult

此对象可提供付款授权结果的相关信息。

属性 类型 必要性 说明
transactionState 字符串 必填 交易状态由以下某个商家结果决定：
  • SUCCESS
  • ERROR
error PaymentDataError 可选 当需要重试付款时，在付款单中向用户显示的错误。

示例

以下示例展示了付款处理完毕后返回的付款结果：

{
  "transactionState": "ERROR",
  "error": {
    "reason": "PAYMENT_DATA_INVALID",
    "message": "Cannot pay with payment credentials",
    "intent": "PAYMENT_AUTHORIZATION"
  }
}

PaymentDataError

属性 类型 必要性 说明
reason 字符串 必填

预定义错误原因列表：

  • OFFER_INVALID
  • PAYMENT_DATA_INVALID
  • SHIPPING_ADDRESS_INVALID
  • SHIPPING_ADDRESS_UNSERVICEABLE
  • SHIPPING_OPTION_INVALID
  • OTHER_ERROR
message 字符串 必填 在对话框中向用户显示的出错提示。
intent 字符串 必填

错误的 intent。 此 intent 必须是从流程开始时就在 PaymentDataRequest 中注册的 intent。

  • OFFER
  • PAYMENT_AUTHORIZATION
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION

示例

此示例展示了要在付款表格中呈现的错误 intent 和消息。

{
  "error": {
    "reason": "SHIPPING_OPTION_INVALID",
    "message": "This shipping option is invalid for the given address",
    "intent": "SHIPPING_OPTION"
  }
}

地址

此对象提供有关所请求邮政地址的信息。所有属性都是字符串。

地址可以采用 MIN、FULL 和 FULL-ISO3166 格式返回。下表列出了每种格式对应的属性。

属性 地址格式 说明
name MIN、FULL、FULL-ISO3166 收件人的全名。
postalCode MIN、FULL、FULL-ISO3166 邮政编码。
countryCode MIN、FULL、FULL-ISO3166 ISO 3166-1 alpha-2 国家/地区代码。
phoneNumber MIN、FULL、FULL-ISO3166 如果 PaymentDataRequest 中的 phoneNumberRequired 设置为 true，则为电话号码。
address1 FULL、FULL-ISO3166 地址的第一行。
address2 FULL、FULL-ISO3166 地址的第二行。
address3 FULL、FULL-ISO3166 地址的第三行。
locality FULL、FULL-ISO3166 城市、城镇、社区或郊区。
administrativeArea FULL、FULL-ISO3166 国家/地区下属行政单位，例如州或省。
sortingCode FULL、FULL-ISO3166 汇兑代码。
iso3166AdministrativeArea FULL-ISO3166 与 administrativeArea 对应的 ISO 3166-2 行政区代码。

示例

以下是美国的一个 FULL-ISO3166 格式地址示例，其中包含多行街道地址数据。

{
  "name": "John Doe",
  "address1": "c/o Google LLC",
  "address2": "1600 Amphitheatre Pkwy",
  "address3": "Building 40",
  "locality": "Mountain View",
  "administrativeArea": "CA",
  "countryCode": "US",
  "postalCode": "94043",
  "sortingCode": ""
  "iso3166AdministrativeArea": "US-CA"
}

IntermediateAddress

中间地址包含经过隐去处理的送货地址（不含街道级地址行或收件人姓名），以便在用户授权付款之前计算适用的税费和送货选项。

属性 类型 必要性 说明
administrativeArea 字符串 必填 国家/地区的下属行政单位，例如州或省/直辖市/自治区。
countryCode 字符串 必填 ISO 3166-1 alpha-2 国家/地区代码。
locality 字符串 必填 城市、城镇、社区或郊区。
postalCode 字符串 必填 根据国家/地区隐去部分数字的邮政编码。对于加拿大和英国，此字段仅包含前三个字符。对于美国，此字段包含前五位数字。
iso3166AdministrativeArea 字符串 可选 与 administrativeArea 对应的 ISO 3166-2 行政区代码。仅当送货地址格式为 FULL-ISO3166 时才会存在。

示例

此示例展示了在付款表格中选择的地址。

{
  "administrativeArea": "NY",
  "countryCode": "US",
  "locality": "New York",
  "postalCode": "10011"
  "iso3166AdministrativeArea": "US-NY"
}

SelectionOptionData

属性 类型 必要性 说明
id 字符串 必填 与SelectionOption.id匹配

示例

此示例展示了在付款表格中选择的配送选项。

{
  "id": "shipping-001"
}

OfferData

此对象可提供在付款表格中输入的优惠代码的相关信息。

属性 类型 必要性 说明
redemptionCodes 数组 始终存在 在付款单中输入的促销代码集。包括已获批准的代码。

示例

以下示例展示了包含 redemptionCodes 数组的 OfferData 对象。

"offerData": {
    "redemptionCodes": ["PROMOTIONALCODE"]
}

IntermediatePaymentMethodData

此对象包含有关所选支付方式的有限信息，供开发者回调使用。

属性 类型 必要性 说明
type 字符串 必填 支付方式类型。此回调仅支持 CARD。
info IntermediateCardInfo 可选 所选卡片的相关信息。仅当 type 为 CARD 时才会存在。

IntermediateCardInfo

此对象包含所选卡片的有限信息，用于开发者回调。

属性 类型 必要性 说明
billingAddress IntermediateAddress 可选 与卡关联的账单邮寄地址。仅在账单邮寄地址设为必填时填充。
cardNetwork 字符串 可选

所选支付卡的支付卡网络。返回的值与 CardParameters 中 allowedCardNetworks 的格式一致。

此卡组织值不应向买家显示。
cardFundingSource 字符串 可选

所选支付卡的资金来源。

  • UNKNOWN
  • CREDIT
  • DEBIT
  • PREPAID