Method: getDisputeInquiryReport

• HTTP 要求
• 要求主體
  • JSON 表示法
• 回應主體
  • JSON 表示法
• RequestHeader
  • JSON 表示法
• 版本
  • JSON 表示法
• PaymentLookupCriteria
  • JSON 表示法
• ArnCriteria
  • JSON 表示法
• GoogleTransactionReferenceNumberCriteria
  • JSON 表示法
• RequestOriginator
  • JSON 表示法
• GetDisputeInquiryReportResultCode
• PurchaseReport
  • JSON 表示法
• CustomerAccount
  • JSON 表示法
• 訂單
  • JSON 表示法
• 地址
  • JSON 表示法
• 項目
  • JSON 表示法
• 稅金
  • JSON 表示法
• 付款
  • JSON 表示法
• 退款
  • JSON 表示法
• PaymentCardDetails
  • JSON 表示法
• AuthResult

請取得相關報表，以便協助客戶針對可能的付款爭議，進行客戶服務對話。

如果端點在處理要求時發生錯誤，來自這個端點的回應就會是 ErrorResponse 類型。

如果這個方法未傳回 HTTP 200，這項查詢的回應可能會空白。在某些情況下，使用 ErrorResponse 搭配清楚的說明，協助攻擊者瞭解其他整合商的帳戶 ID，則回應主體是空白的。在這類情況下，只要簽署金鑰不相符、找不到付款整合商 ID，或是加密金鑰不明，這個方法就會傳回主體為空白的 HTTP 404。如果要求簽章可供驗證，回應主體中會傳回與錯誤相關的其他資訊。

以下是要求範例：

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 1,
      "revision": 0
    },
    "requestId": "HsKv5pvtQKTtz7rdcw1YqE",
    "requestTimestamp": "1519996751331"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA",
  "paymentLookupCriteria": {
    "googleTransactionReferenceNumberCriteria": {
      "googleTransactionReferenceNumber": "714545417102363157911822",
      "authorizationCode": "111111"
    }
  },
  "existingGoogleClaimId": "138431383281",
  "requestOriginator": {
    "organizationId": "ISSUER_256",
    "organizationDescription": "Community Bank of Some City",
    "agentId": "982749"
  }
}

回應範例如下所示：

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  },
  "result": "SUCCESS",
  "googleClaimId": "138431383281",
  "report": {
    "customerAccount": {
      "customerEmail": "[e-mail]",
      "customerName" : "Example Customer"
    },
    "order": {
      "timestamp": "1517992525972",
      "orderId": "SOP.8976-1234-1234-123456..99",
      "currencyCode": "USD",
      "subTotalAmount": "206990000",
      "totalAmount": "212990000",
      "shippingAddress": {
        "name": "Example Customer",
        "addressLine": ["123 Main St"],
        "localityName": "Springfield",
        "administrativeAreaName": "CO",
        "postalCodeNumber": "80309",
        "countryCode": "US"
      },
      "taxes": [
        {
          "description": "Colorado Sales Tax",
          "amount": "6000000"
        }
      ],
      "items": [
        {
          "description": "Super cool gizmo",
          "merchant": "HTC",
          "googleProductName": "Google Store",
          "quantity": "2",
          "totalPrice": "198000000"
        },
        {
          "description": "Gizmo charger",
          "merchant": "HTC",
          "googleProductName": "Google Store",
          "quantity": "1",
          "totalPrice": "8990000"
        }
      ]
    },
    "payment": {
      "billingAddress" : {
        "name": "Example Customer",
        "addressLine": ["123 Main St"],
        "localityName": "Springfield",
        "administrativeAreaName": "CO",
        "postalCodeNumber": "80309",
        "countryCode": "US"
      },
      "amount": "100000000",
      "refunds": [
        {
          "amount": "9250000",
          "initiatedTimestamp": "1518811245384"
        }
      ],
      "cardDetails": {
        "authResult": "APPROVED"
      }
    }
  }
}

HTTP 要求

POST https://vgw.googleapis.com/secure-serving/gsp/v1/getDisputeInquiryReport/:PIAID

要求主體

要求主體的資料會採用以下結構：

JSON 表示法
{ "requestHeader": { object (RequestHeader) }, "paymentIntegratorAccountId": string, "paymentLookupCriteria": { object (PaymentLookupCriteria) }, "existingGoogleClaimId": string, "requestOriginator": { object (RequestOriginator) } }

欄位
requestHeader	object (RequestHeader) 必要項目：所有要求的通用標頭。
paymentIntegratorAccountId	string 必要項目：付款整合商帳戶 ID，用於識別呼叫端和此互動的相關合約限制。
paymentLookupCriteria	object (PaymentLookupCriteria) 必要項目：用來表示查詢這項查詢的付款條件。
existingGoogleClaimId	string 選用：這是 Google 產生的字串，由先前呼叫 getDisputeInquiryReport 傳回，可專門用來識別客戶爭議版權聲明。 如果沒有，系統會產生新的版權聲明 ID。如果持續發生相同的客戶爭議，呼叫端可能會提供先前呼叫 getDisputeInquiryReport 傳回的 googleClaimId。 在這裡填入或產生的版權聲明 ID 會顯示在回應的 googleClaimId 欄位中。 無法提供先前呼叫 getDisputeInquiryReport 時未傳回的 googleClaimId，如果發生這種情況，系統會傳回「HTTP 400 不正確的要求」。
requestOriginator	object (RequestOriginator) 必要項目：提出要求的機構或機構子群組相關資訊，

回應主體

getDisputeInquiryReport 方法的回應酬載。

如果成功，回應主體即會包含具有以下結構的資料：

JSON 表示法
{ "responseHeader": { object (ResponseHeader) }, "result": enum (GetDisputeInquiryReportResultCode), "googleClaimId": string, "report": { object (PurchaseReport) } }

欄位
responseHeader	object (ResponseHeader) 必要項目：所有回應的通用標頭。
result	enum (GetDisputeInquiryReportResultCode) 必要項目：這個呼叫的結果。
googleClaimId	string 選用：Google 產生的字串，專門用來識別客戶爭議。(只有在 result 為「成功」時才會顯示)。 如果在要求中填入 existingGoogleClaimId，這個值就會相同。否則就會是新產生的值。日後的 getDisputeInquiryReport 要求若涉及同一個客戶爭議，則可在日後要求提供這個值。
report	object (PurchaseReport) 選用：與要求中指明的付款爭議相關的詳細資料。(只有在 result 為「成功」時才會顯示)。

RequestHeader

針對傳送至伺服器的所有要求所定義的標頭物件。

JSON 表示法
{ "requestId": string, "requestTimestamp": string, "userLocale": string, "protocolVersion": { object (Version) } }

欄位
requestId	string 必要項目：這項要求的專屬 ID。 這是一個長度上限為 100 個字元的字串，並且只包含「a-z」、「A-Z」、「0-9」、「:」、「-」和「_」等字元。
requestTimestamp	string (int64 format) 必要項目：這項要求的時間戳記，以 Epoch 紀元時間起算的毫秒為單位。接收端應驗證這個時間戳記是否為「現在」的 ±60 秒。重試時，此要求時間戳記並不是冪等的。
userLocale (deprecated)	string 目前從未實作過，將在日後的版本中移除。系統會忽略這個欄位。 已淘汰：由兩或三個字母組成的 ISO 639-2 Alpha 3 語言代碼，後面可選擇加上連字號和 ISO 3166-1 Alpha-2 國家/地區代碼，例如「pt」、「pt-BR」、「fil」或「fil-PH」。請使用這個屬性來驅動回應中的 userMessage 欄位。
protocolVersion	object (Version) 必要項目：這項要求的版本。

版本

版本物件是傳統版 a.b.c 版本結構的結構化格式。相同數字的主要版本保證能夠相容。請注意，輕微和修訂可能經常變更，恕不另行通知。整合商必須支援相同主要版本的所有要求。

JSON 表示法
{ "major": integer, "minor": integer, "revision": integer }

欄位
major	integer 必要項目：主要版本。標示為不同版本的廣告素材不保證能夠相容。
minor	integer 必要項目：子版本。這表示重大錯誤修正。
revision	integer 必要項目：子版本。這代表小錯誤修正。

PaymentLookupCriteria

用來裝載可明確查詢付款的條件的容器。必須填入一個成員欄位 (且只能有一個)。

JSON 表示法
{ // Union field criteria can be only one of the following: "arnCriteria": { object (ArnCriteria) }, "googleTransactionReferenceNumberCriteria": { object (GoogleTransactionReferenceNumberCriteria) } // End of list of possible types for union field criteria. }

欄位
聯集欄位 criteria。 criteria 只能採用下列其中一種設定：
arnCriteria	object (ArnCriteria) 選用：根據收銀員參考編號 (ARN) 查詢。
googleTransactionReferenceNumberCriteria	object (GoogleTransactionReferenceNumberCriteria) 選用：根據 Google 交易參考號碼查詢。

ArnCriteria

以收單號碼 (ARN) 為依據的付款查詢條件。

JSON 表示法
{ "acquirerReferenceNumber": string, "authorizationCode": string }

欄位
acquirerReferenceNumber	string 必要項目：可明確識別付款的收單銀行參考號碼 (ARN)。長度必須為 23 位數。
authorizationCode	string 必要項目：交易的授權碼。

GoogleTransactionReferenceNumberCriteria

付款查詢條件，以 Google 產生的交易參考號碼為依據。

JSON 表示法
{ "googleTransactionReferenceNumber": string, "authorizationCode": string }

欄位
googleTransactionReferenceNumber	string 必要項目：Google 產生的交易參考號碼，用於識別付款。
authorizationCode	string 必要項目：交易的授權碼。

RequestOriginator

提出這項要求的機構或機構子群組，以及員工 (選用) 的相關資訊。這可讓 Google 找出問題或濫用行為，並實作比 paymentIntegratorAccountId 更精細的控制項。如果呼叫端是提供多個外部用戶端要求的中介服務供應商，特別重要。

JSON 表示法
{ "organizationId": string, "organizationDescription": string, "agentId": string }

欄位
organizationId	string 必要項目：提出要求的公司、機構或機構群組的 ID。在這項paymentIntegratorAccountId中不得重複。
organizationDescription	string 必要項目：使用者可理解的機構名稱或說明，以便讓 Google 員工和整合商更容易與機構溝通。
agentId	string OPTIONAL：organizationId 所識別的機構組織特定服務專員 (員工) 的專屬 ID，可由此要求產生。在這項organizationId中不得重複。

GetDisputeInquiryReportResultCode

getDisputeInquiryReport 方法呼叫的結果。

列舉
UNKNOWN_RESULT	請不要設定這個預設值！
SUCCESS	已找到付款，並提供了報表。
PAYMENT_NOT_FOUND	找不到您要求的款項。
PAYMENT_TOO_OLD	已找到要求的款項，但由於付款期限不足，我們並未提供報表。
ORDER_CANNOT_BE_RETURNED	您要求的款項屬於現有訂單，但無法傳回。原因包括訂單擁有者依要求移除訂單的情形。 注意：這是永久性狀態。
NO_ADDITIONAL_DETAILS	已找到要求的付款，但無法產生報表。

PurchaseReport

包含與要求款項相關的購買詳細資料的報表。

JSON 表示法
{ "customerAccount": { object (CustomerAccount) }, "order": { object (Order) }, "payment": { object (Payment) } }

欄位
customerAccount	object (CustomerAccount) 必要項目：客戶及其帳戶的相關資訊。
order	object (Order) 必要項目：付款訂單相關資訊。
payment	object (Payment) 選用：付款相關資訊，注意：單筆訂單可能分筆數筆付款，但只提供原始要求中指明的付款資訊。不適用於某些訂單類型。

CustomerAccount

客戶帳戶相關資訊

JSON 表示法
{ "customerEmail": string, "customerName": string }

欄位
customerEmail	string 必要項目：與客戶 Google 帳戶相關聯的電子郵件地址。
customerName	string 必要項目：客戶的名稱。

訂購

訂單相關資訊。

JSON 表示法
{ "timestamp": string, "orderId": string, "currencyCode": string, "subTotalAmount": string, "totalAmount": string, "shippingAddress": { object (Address) }, "items": [ { object (Item) } ], "taxes": [ { object (Tax) } ] }

欄位
timestamp	string (int64 format) 選用：下單時的時間戳記，以 Epoch 紀元時間起算的毫秒為單位。不適用於某些訂單類型。
orderId	string 選用：用來識別此順序的字串。不適用於某些訂單類型。
currencyCode	string 選用：這個訂單中所有金額的 ISO 4217 貨幣代碼，由 3 個字母組成。不適用於某些訂單類型。
subTotalAmount	string (Int64Value format) 選填：這筆訂單稅前的總金額，以 order.currencyCode 指定貨幣的微量表示。等於 SUM(items.totalPrice)。不適用於某些訂單類型。
totalAmount	string (Int64Value format) OPTIONAL：該筆訂單的總金額 (含稅金)，以 order.currencyCode 指定貨幣的微量表示。等於 subTotalAmount + SUM(taxes.amount)。不適用於某些訂單類型。
shippingAddress	object (Address) 選填：這筆訂單中的實體商品運送地址。
items[]	object (Item) 必要項目：屬於此訂單的項目清單。
taxes[]	object (Tax) 必要項目：屬於此訂單的項目清單。這份清單可能沒有任何內容。

地址

保存地址資訊的結構。

JSON 表示法
{ "name": string, "addressLine": [ string ], "localityName": string, "administrativeAreaName": string, "postalCodeNumber": string, "countryCode": string }

欄位
name	string 選用：客戶的全名。
addressLine[]	string 選用：這個項目包含非結構化地址文字。
localityName	string 選填：這是模糊字詞，但通常是指地址的縣市/鄉鎮部分。如果是未明確定義縣市或不適用這個結構的地區 (例如日本和中國)，請將 localityName 留空，並使用 addressLine。 範例：美國城市、義大利市、英國郵鎮。
administrativeAreaName	string OPTIONAL：這個國家/地區的頂層行政區，例如：美國各州、義大利區域、中國省、日本都/道/府/縣。
postalCodeNumber	string 選用：儘管名稱不同，postalCodeNumber 值通常都是英數字元。例如：「94043」、「SW1W」、「SW1W 9TQ」。
countryCode	string 選用：客戶地址的國家/地區代碼，應為 ISO-3166-1 Alpha-2。

項目

訂單中項目的資訊。

JSON 表示法
{ "description": string, "merchant": string, "quantity": string, "totalPrice": string, "googleProductName": string }

欄位
description	string 選用：所購買商品的說明。不適用於某些訂單類型。
merchant	string 必要項目：商品的賣家、演出者或製造商。
quantity	string (Int64Value format) OPTIONAL：此商品的訂購數量。 如果產品不適用的整數數量不適用 (例如計量付費產品可能會有小數點)，則會省略這個欄位。
totalPrice	string (Int64Value format) OPTIONAL：此商品的總價，以 order.currencyCode 指定貨幣的微量表示。如果填入 quantity，這會反映整個商品數量的總價。不適用於某些訂單類型。
googleProductName	string 必要項目：商品的 Google 產品與服務名稱。

稅金

這筆訂單的稅金相關資訊。

JSON 表示法
{ "description": string, "amount": string }

欄位
description	string 必要項目：稅金說明。
amount	string (Int64Value format) 必要項目：稅金金額，以 order.currencyCode 指定貨幣的微量表示。

付款

付款相關資訊。

JSON 表示法
{ "billingAddress": { object (Address) }, "amount": string, "refunds": [ { object (Refund) } ], // Union field fopDetails can be only one of the following: "cardDetails": { object (PaymentCardDetails) } // End of list of possible types for union field fopDetails. }

欄位
billingAddress	object (Address) 必要項目：這筆款項的帳單地址。
amount	string (Int64Value format) 必要項目：這筆款項的金額，以order.currencyCode指定貨幣的微量表示。注意：如果訂單是以多次付款的方式付款，這筆金額可能會與 order.totalAmount 不一致。
refunds[]	object (Refund) 必要項目：這筆款項的退款清單。這份清單可能沒有任何內容。
聯集欄位 fopDetails。 fopDetails 只能採用下列其中一種設定：
cardDetails	object (PaymentCardDetails) 選用：信用卡和簽帳金融卡 FoP 專屬的付款詳情。

退款

付款退款的相關資訊。

JSON 表示法
{ "amount": string, "initiatedTimestamp": string }

欄位
amount	string (Int64Value format) 必要項目：退款金額，以 order.currencyCode 指定貨幣的正微量為正數。
initiatedTimestamp	string (int64 format) 必要項目：辦理退款的時間戳記，以 Epoch 紀元時間起算的毫秒為單位。

PaymentCardDetails

信用卡和簽帳金融卡專屬的付款詳情。

JSON 表示法
{ "authResult": enum (AuthResult) }

欄位
authResult	enum (AuthResult) 必要項目：付款驗證結果。

AuthResult

付款驗證結果。

列舉
UNKNOWN_RESULT	請不要設定這個預設值！
APPROVED	授權已通過核准。
DENIED	授權遭拒。
NOT_ATTEMPTED	未嘗試授權。