更新到最新版本

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

付款方式

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

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

  1. 如果您的应用支持 PAYMENT_METHOD_CARD
    • 请将 "PAN_ONLY" 添加到 allowedAuthMethods 数组中。
  2. 如果您的应用支持 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 对象,并将其传递给 PaymentsClientloadPaymentData 方法。请从 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_ONLYCRYPTOGRAM_3DS 的卡都会将 paymentMethod 显示为 CARD,并包含该身份验证方法的相关信息以及在 paymentMethodDetails 中提供的身份验证方法的特定字段。

因此,如果您尚未更新服务器,则无法将 Android 设备令牌转发给您的网关或处理方。这是因为服务器无法区分响应中的多种类型的卡身份验证。卡的 paymentMethodCARD,并在 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"
  }
}