更新至最新版

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 Builder 的資訊，必須在的 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 Builder，現在則應在 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 執行個體。JSONObject 或其他可處理 JSON 的程式庫可將 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 類型的已驗證卡片都會顯示為 CARD 的 paymentMethod，其中包含驗證方式的其他資訊，以及 paymentMethodDetails 中所提供驗證方式的專屬欄位。

因此，如果尚未更新伺服器，就無法將 Android 裝置代碼轉送至自己的支付平台或處理方，這是因為伺服器無法區分回應中的多個卡片驗證類型。卡片是 CARD 的 paymentMethod，且含有 paymentMethodDetails.authMethod 中所選卡片驗證方法的額外資訊。憑證已經過 3-D 安全密文和選用電子商務指標 (ECI) 驗證。

ECI

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

3-D 安全密文

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