回應物件

本參考資料說明要用於網站的 Google Pay API 回應物件選項。回應物件是由 Google Pay API 用戶端方法傳回的物件。

IsReadyToPayResponse

這個物件會提供相關資訊，說明網站訪客是否能向要求提供付款資訊的網站提供這類資訊。

屬性 類型 一律存在 說明
result 布林值 是 目前訪客可以向要求提供付款資訊的網站提供相關資訊。 訪客能否付款，可能與網頁瀏覽器能否顯示指定付款方式的必要元件有關。包括登入 Google 帳戶並提供付款方式。
paymentMethodPresent 布林值 否

如果 true，訪客有一或多個付款方式，如所提供 IsReadyToPayRequest 的 allowedPaymentMethods 屬性中所指定。

只有在 existingPaymentMethodRequired 於 IsReadyToPayRequest 中設為 true 時，才會存在。

如果 PaymentsClient 是以 environment 屬性的 TEST 屬性初始化，系統一律會視為有付款方式。

範例

以下範例說明目前訪客何時能向要求提供付款資訊的網站提供這類資訊。

{
  "result": true
}

PaymentData

這是付款人核准付款後，Google 傳回的回應物件。

PaymentDataRequest.PaymentDataRequest.PaymentDataRequest。
屬性 類型 一律存在 說明
apiVersion 數字 是 主要 API 版本。回應中的值與 中提供的值相符。PaymentDataRequest
apiVersionMinor 數字 是 API 子版本。回應中的值與 中提供的值相符。PaymentDataRequest
paymentMethodData PaymentMethodData 是 所選付款方式的相關資料。
email 字串 否 電子郵件地址 (如果 emailRequired 在 PaymentDataRequest 中設為 true)。 如果其他要求已將屬性設為 true，則不會有任何影響。
shippingAddress 地址 否 運送地址 (如果 shippingAddressRequired 在 PaymentDataRequest 中設為 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
  • OFFER
offerData OfferData 選用 使用者提供的促銷代碼。
shippingAddress IntermediateAddress 選用 付款單中選取的地址。
shippingOptionData SelectionOptionData 選用 付款畫面中選取的運送選項。

範例

這個範例顯示 Google Pay API 傳回的中繼酬載。

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

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 是 如果 assuranceDetailsRequired 在 CardParameters 中設為 true，這個物件會提供相關資訊，說明系統對傳回的付款資料執行的驗證作業。
cardNetwork 字串 是

所選付款方式的支付卡網路。 傳回的值符合 CardParameters 中 allowedCardNetworks 的格式。

這個卡片網路值不應向買家顯示。需要買家卡片詳細資料時，就會使用這項功能。舉例來說，如果客戶服務需要這個值，才能識別買家交易時使用的卡片。如要提供使用者可見的說明，請改用 PaymentMethodData 的 description 屬性。
billingAddress 地址 否 如果 billingAddressRequired 在 CardParameters 中設為 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 欄位，您也可以接收及處理回應物件。如要接收這個物件，請在要求物件的 CardParameters 中加入 assuranceDetailsRequired: true。

PaymentMethodTokenizationData

這個物件會提供付款方式的權杖化資料。

屬性 類型 一律存在 說明
type 字串 是 要套用至所選付款方式的權杖化類型。 這個值與 中設定的 type 相符。PaymentMethodTokenizationSpecification
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 電話號碼 (如果 phoneNumberRequired 在 PaymentDataRequest 中設為 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"]
}