JSON 回應物件

本參考資料介紹可用於應用程式的 Google Pay API 回應物件選項。回應物件為 Google Pay API 用戶端方法傳回的物件。

PaymentData

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

PaymentDataRequest.PaymentDataRequest.PaymentDataRequest。
屬性 類型 永遠存在 說明
apiVersion number 是 主要 API 版本。回應中的值與您在
apiVersionMinor 數字 是 次要 API 版本。回應中的值與您在
paymentMethodData PaymentMethodData 是 所選付款方式的相關資料。
email string 否 電子郵件地址 (如果 PaymentDataRequest。如有其他要求將這項屬性設定為 true，則不具任何效力。
shippingAddress 地址 否 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"
    }
  }
}

PaymentMethodData

這個物件提供所選付款方式的資料。

屬性 類型 永遠存在 說明
type string 是 PaymentMethod 在 Google Pay 付款畫面中選取了 type。
description 字串 是

向使用者顯示的訊息，用於說明這項交易使用的付款方式。
info object 是 這項屬性的值會因傳回的付款方式 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 string 是 卡片詳細資料。這個值通常為所選付款帳號的末四碼。
assuranceDetails AssuranceDetailsSpecifications 是 如果 CardParameters。
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 欄位，您也可以接收及處理回應物件。如要接收這個物件，請在要求物件的 CardParameters。

PaymentMethodTokenizationData

這個物件提供付款方式的代碼化資料。

屬性 類型 永遠存在 說明
type string 是 要套用至所選付款方式的代碼化類型。這個值與 type 相符，該屬性是在 PaymentMethodTokenizationSpecification。
token 字串 否

產生的付款方式代碼。

範例

這是針對 example 閘道準備的代碼化回應範例。

{
  "type": "PAYMENT_GATEWAY",
  "token": "examplePaymentMethodToken"
}

PaymentAuthorizationResult

這個物件提供付款授權結果的相關資訊。

屬性 類型 必要性 說明
transactionState String 必要 交易狀態是以下列其中一項商家結果判定：
  • SUCCESS
  • ERROR
error PaymentDataError 選用 需要重新付款時，使用者付款畫面中顯示的錯誤。

範例

以下範例顯示付款處理完後，系統傳回的付款結果：

{
  "transactionState": "ERROR",
  "error": {
    "reason": "PAYMENT_DATA_INVALID",
    "message": "Cannot pay with payment credentials",
    "intent": "PAYMENT_AUTHORIZATION"
  }
}

PaymentDataError

屬性 類型 必要性 說明
reason String 必要

預先定義錯誤原因的清單：

  • PAYMENT_DATA_INVALID
  • SHIPPING_ADDRESS_INVALID
  • SHIPPING_ADDRESS_UNSERVICEABLE
  • SHIPPING_OPTION_INVALID
  • OTHER_ERROR
message String 必要 在對話方塊中向使用者顯示的錯誤訊息。
intent String 必填

錯誤的意圖。

  • PAYMENT_AUTHORIZATION
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION

範例

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

{
  "error": {
    "reason": "SHIPPING_OPTION_INVALID",
    "message": "This shipping option is invalid for the given address",
    "intent": "SHIPPING_OPTION"
  }
}

Address

這個物件提供有關所要求郵寄地址的資訊。所有屬性皆為字串。

地址可以 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。
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"
}

IntermediatePaymentData

如果付款畫面中的運送地址或運送選項發生變更，Google Pay API onPaymentDataChanged() 輸入內容就會傳回這個物件。

屬性 類型 必要性 說明
callbackTrigger String 選用

說明叫用付款資料回呼的原因。

  • INITIALIZE
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION
shippingAddress IntermediateAddress 選用 付款畫面中的所選地址。
shippingOptionData SelectionOptionData 選用 付款畫面中的所選運送選項。

範例

以下範例顯示了 Google Pay API 傳回的中繼酬載。

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

IntermediateAddress

中繼地址包含經過編輯的運送地址 (不含街道層級的地址行或收件者姓名)，方便在使用者授權付款前計算適用的稅金和運送選項。

屬性 類型 必要性 說明
administrativeArea String 必要 行政區 (例如州或省)。
countryCode String 必要 ISO 3166-1 alpha-2 國家/地區代碼。
locality String 必要 市、鎮、鄰或郊區。
postalCode String 必要 各個國家/地區特定的郵遞區號 (會經過遮蓋)。如為加拿大和英國，這個值僅含前三個字元。如為美國，則包含前五個數字。
iso3166AdministrativeArea 字串 選用 與 administrativeArea 對應的 ISO 3166-2 行政區代碼。只有在運送地址格式為 FULL-ISO3166 時才會顯示。

範例

以下範例顯示了付款畫面中的所選地址。

{
  "administrativeArea": "NY",
  "countryCode": "US",
  "locality": "New York",
  "postalCode": "10011"
  "iso3166AdministrativeArea": "US-NY"
}

SelectionOptionData

屬性 類型 必要性 說明
id String 必填 與 SelectionOption.id 相符

範例

以下範例顯示付款畫面中選取的運送選項。

{
  "id": "shipping-001"
}