回應物件

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

IsReadyToPayResponse

這個物件提供的資訊說明網站訪客是否能將付款資訊提供給要求該資訊的網站。

屬性 類型 永遠存在 說明
result 布林值 是 目前的訪客能將付款資訊提供給要求該資訊的網站。 訪客能否付款，可能取決於他們使用的瀏覽器可否顯示指定付款方式的所需元件。訪客登入 Google 帳戶並提供付款方式之後的狀態即屬於這種情況。
paymentMethodPresent 布林值 否

如為 true，代表訪客具備您在 IsReadyToPayRequest 的 allowedPaymentMethods 屬性中指定的一或多種付款方式。

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

如果 PaymentsClient 是在 environment 屬性設為 TEST 的情況下初始化，付款方式則視為一律存在。

範例

下列範例顯示目前訪客能將付款資訊提供給要求該資訊的網站的情況。

{
  "result": true
}

PaymentData

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

PaymentDataRequest.PaymentDataRequest.PaymentDataRequest。
屬性 類型 永遠存在 說明
apiVersion 數字 是 主要 API 版本。回應中的值與您在 PaymentDataRequest 中提供的值相符。
apiVersionMinor 數字 是 次要 API 版本。回應中的值與您在 PaymentDataRequest 中提供的值相符。
paymentMethodData PaymentMethodData 是 所選付款方式的相關資料。
email 字串 否 電子郵件地址 (如果 PaymentDataRequest 中的 emailRequired 設為 true)。 如有其他要求將這項屬性設定為 true，則不具任何效力。
shippingAddress 地址 否 shippingAddressRequired 設為 true 時的運送地址 (位在 PaymentDataRequest 中)。

範例

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

所選款項的付款卡發卡機構。傳回的值與 allowedCardNetworks 格式相符，後者 位在 CardParameters 中。

這個發卡機構值不應向買家顯示。在必須提供買家詳細資料時，您可以使用這個值 舉例來說，如果客戶服務需要這個值來識別買家用於交易的卡片。如要向使用者顯示相關說明，請改用 PaymentMethodData 的 description 屬性。
billingAddress 地址 否 billingAddressRequired 設為 true時，與所提供付款方式相關聯的帳單地址。該屬性 位在 CardParameters 中。
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 欄位，您也可以接收及處理回應物件。如要接收這個物件，請在要求物件的 中加入 assuranceDetailsRequired: true CardParameters。

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 電話號碼 (如果 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"]
}