更新到最新版本

Google Pay API 于 2018 年 8 月推出了新版 Android 客户端库。这些新库支持根据序列化为字符串的 JSON 对象构建 IsReadyToPayRequest 或 PaymentDataRequest。本指南介绍如何将使用 Builder 对象的 Android 代码更新为等效的 JSON 格式的字符串。该字符串可传递给 IsReadyToPayRequest 和 PaymentDataRequest 的 fromJson() 方法。

重要提示：使用旧版 Builder 实现的应用不支持基于 JSON 的新版请求对象所包含的特性和功能。

付款方式

在旧版的 Google Pay API 中，我们使用的 Builder 对象仅支持卡作为 IsReadyToPayRequest 或 PaymentDataRequest 的付款方式。而在最新版的 Google Pay API 中，CARD 付款方式只是 IsReadyToPayRequest 或 PaymentDataRequest 的多种可能付款方式的其中一种。

不再使用常量。旧版中使用的 Builder 对象引用了整数常量。而新版的 JSON 格式的字符串则是在 CardParameters 的 allowedAuthMethods 属性数组中设置等效的字符串值。要更新您的代码，请确认您所属的情况并按照以下说明操作：

如果您的应用支持 PAYMENT_METHOD_CARD：
- 请将 "PAN_ONLY" 添加到 allowedAuthMethods 数组。
如果您的应用支持 PAYMENT_METHOD_TOKENIZED_CARD：
- 请将 "CRYPTOGRAM_3DS" 添加到 allowedAuthMethods 数组。

在以前的版本中，如果您未指定允许的卡网络，系统会为应用分配一组默认的卡网络。现在，您必须为应用提供一份允许的卡网络列表。

Builder

IsReadyToPayRequest.newBuilder()
    .addAllowedPaymentMethod(
        WalletConstants.PAYMENT_METHOD_CARD)
    .addAllowedPaymentMethod(
        WalletConstants.PAYMENT_METHOD_TOKENIZED_CARD);

PaymentDataRequest.newBuilder()
    .addAllowedPaymentMethod(
        WalletConstants.PAYMENT_METHOD_CARD)
    .addAllowedPaymentMethod(
        WalletConstants.PAYMENT_METHOD_TOKENIZED_CARD);

fromJson

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        "allowedAuthMethods": [
          "PAN_ONLY",
          "CRYPTOGRAM_3DS"
        ],
        "allowedCardNetworks": [
          "AMEX",
          "DISCOVER",
          "MASTERCARD",
          "VISA"
        ]
      }
    }
  ]
}

卡付款数据令牌化

Google Pay API 会返回加密的卡数据，该数据将由您的指定网关引用或在您的服务器上进行解密。以前提供给 PaymentMethodTokenizationParameters 构建者的信息应在 CARD 付款方式的 PaymentMethodTokenizationSpecification 中进行定义。

Builder

PaymentMethodTokenizationParameters.newBuilder()
    .setPaymentMethodTokenizationType(
        WalletConstants.PAYMENT_GATEWAY)
    .addParameter(
        "gateway",
        "example")
    .addParameter(
        "gatewayMerchantId",
        "exampleGatewayMerchantId")

fromJson

{
  "allowedPaymentMethods": [{
    "type": "CARD",
    "tokenizationSpecification": {
      "type": "PAYMENT_GATEWAY",
      "parameters": {
        "gateway": "example",
        "gatewayMerchantId": "exampleGatewayMerchantId"
      }
    }
  }]
}

帐单邮寄地址

您可以选择是否要求用户提供帐单邮寄地址或电话号码，与 CARD 付款方式进行关联。如果决定要求用户提供帐单邮寄地址或电话号码，您必须在 BillingAddressParameters JSON 对象中指定所需响应的配置。

Builder

PaymentDataRequest.newBuilder()
    .setPhoneNumberRequired(true)
    .setCardRequirements(
        CardRequirements.newBuilder()
            .setBillingAddressRequired(true)
            .setBillingAddressFormat(
                WalletConstants.BILLING_ADDRESS_FORMAT_FULL));

fromJson

{
  "allowedPaymentMethods": [{
    "type": "CARD",
    "parameters": {
      "billingAddressRequired": true,
      "billingAddressParameters": {
        "format": "FULL",
        "phoneNumberRequired": true
      }
    }
  }]
}

送货地址

您可以选择是否要求用户提供送货地址。用户可以使用存储的送货地址，也可以输入新的送货地址。送货地址是 PaymentDataRequest JSON 对象中的顶层属性。您允许的送货地址的国家/地区部分以前是添加到 ShippingAddressRequirements 构建器中，而现在应在 ShippingAddressParameters JSON 对象中指定。

Builder

PaymentDataRequest.newBuilder()
    .setPhoneNumberRequired(true)
    .setShippingAddressRequired(true)
    .setShippingAddressRequirements(
        ShippingAddressRequirements.newBuilder()
            .addAllowedCountryCode("US")
            .addAllowedCountryCode("CA"))

fromJson

{
  "shippingAddressRequired": true,
  "shippingAddressParameters": {
    "allowedCountryCodes": [
      "US",
      "CA"
    ],
    "phoneNumberRequired": true
  }
}

PaymentData 响应

响应是指包含 JSON 格式的响应的 PaymentDataRequest 对象，可供 toJson() 类方法使用。要接收此响应，请使用 fromJson() 类方法创建一个 PaymentDataRequest 对象，并将其传递给 PaymentsClient 的 loadPaymentData 方法。请从 Intent 中提取 PaymentData 实例。JSON 格式的字符串可由 JSONObject 或其他可识别 JSON 的库解析为 JSON 名称/值对。

以前的 Getter

PaymentData paymentData =
    PaymentData.getFromIntent(data);

现在的 JSON

PaymentData paymentData =
    PaymentData.getFromIntent(data);
String json = paymentData.toJson();
if (json != null) {
  JSONObject paymentDataJson =
      new JSONObject(json);
  JSONObject paymentMethodData =
      paymentDataJson.get("paymentMethodData");
}

所选付款方式的摘要文本位于 description 属性中。如需了解在返回 CARD 类型时可用的其他属性，请参阅 CardInfo JSON 对象参考。

以前的 Getter

paymentData
    .getCardInfo()
    .getCardDescription();

现在的 JSON

paymentMethodData.get("description");

所选付款方式及其令牌化的相关信息位于 paymentMethodData 属性中。

以前的 Getter

paymentData
    .getPaymentMethodToken()
    .getToken();

现在的 JSON

paymentMethodData
    .get("tokenizationData")
    .get("token");

加密的消息响应

如果应用指定 DIRECT 付款方式令牌化类型，并接受 Android 设备令牌（以前为 WalletConstants.PAYMENT_METHOD_TOKENIZED_CARD），则必须更新其在服务器上处理解密的 encryptedMessage 属性的方式。类型为 PAN_ONLY 和 CRYPTOGRAM_3DS 的经过身份验证的卡都会将 paymentMethod 显示为 CARD，并包含该身份验证方法的相关信息以及专用于 paymentMethodDetails 中提供的身份验证方法的字段。

因此，如果您尚未更新服务器，则无法将 Android 设备令牌转发给您的网关或处理方。这是因为您的服务器无法区分响应中的多种类型的卡身份验证。卡是 CARD 的一种 paymentMethod，其中包含有关在 paymentMethodDetails.authMethod 中所选卡的身份验证方法的额外信息。令牌则使用 3D 安全密文和可选的电子商务指标 (ECI) 进行身份验证。

ECI

{
  "paymentMethod": "TOKENIZED_CARD",
  "paymentMethodDetails": {
    "authMethod": "3DS",
    "dpan": "1111222233334444",
    "expirationMonth": 10,
    "expirationYear": 2020,
    "3dsCryptogram": "AAAAAA...",
    "3dsEciIndicator": "eci indicator"
  }
}

3D 安全密文

{
  "paymentMethod": "CARD",
  "paymentMethodDetails": {
    "authMethod": "CRYPTOGRAM_3DS",
    "pan": "1111222233334444",
    "expirationMonth": 10,
    "expirationYear": 2020,
    "cryptogram": "AAAAAA...",
    "eciIndicator": "eci indicator"
  }
}