回應物件

本參考資料說明可與網站搭配使用的 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 字串 必填

錯誤的意圖。 這必須是從流程開始時，就在 PaymentDataRequest 中註冊的意圖。

  • OFFER
  • PAYMENT_AUTHORIZATION
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION

範例

以下範例顯示要在付款表中顯示的錯誤意圖和訊息。

{
  "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