Method: getDisputeInquiryReport

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

如果這個方法未傳回 HTTP 200，這項查詢的回應可能會空白。

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

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

以下是要求範例：


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

回應範例如下所示：


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

HTTP 要求

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

要求主體

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

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

object (RequestHeader)

必要項目：所有要求的通用標頭。
paymentLookupCriteria

object (PaymentLookupCriteria)

必要項目：用來表示查詢這項查詢的付款條件。
existingGoogleClaimId

string

選用：這是 Google 產生的字串，由先前呼叫 getDisputeInquiryReport 傳回，可專門用來識別客戶爭議版權聲明。

如果沒有，系統會產生新的版權聲明 ID。如果持續發生相同的客戶爭議，呼叫端可能會提供先前呼叫 getDisputeInquiryReport 傳回的 googleClaimId。

在這裡填入或產生的版權聲明 ID 會顯示在回應的 googleClaimId 欄位中。

無法提供先前呼叫 getDisputeInquiryReport 時未傳回的 googleClaimId，如果發生這種情況，系統會傳回「HTTP 400 不正確的要求」。
requestOriginator

object (RequestOriginator)

必要項目：提出要求的機構或機構子群組相關資訊，

回應主體

這個方法支援多種傳回類型。如要進一步瞭解要使用 ErrorResponse 傳回的 4XX 或 5XX HTTP 狀態碼，請參閱 ErrorResponse 物件和 HTTP 狀態碼說明文件。

這個方法支援多種傳回類型。如要進一步瞭解要使用 ErrorResponse 傳回的 4XX 或 5XX HTTP 狀態碼，請參閱 ErrorResponse 物件和 HTTP 狀態碼說明文件。

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

可能的回應訊息
HTTP 200 狀態

object (GetDisputeInquiryReportResponse)
HTTP 4XX / 5XX 狀態

object (ErrorResponse)

RequestHeader

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

JSON 表示法 
{
  "requestId": string,
  "requestTimestamp": {
    object (Timestamp)
  },
  "protocolVersion": {
    object (Version)
  },
  "paymentIntegratorAccountId": string
}
欄位
requestId

string

必要項目：這項要求的專屬 ID。

這是一個長度上限為 100 個字元的字串，並且只包含「a-z」、「A-Z」、「0-9」、「:」、「-」和「_」等字元。
requestTimestamp

object (Timestamp)

必要項目：這項要求的時間戳記。接收端必須驗證這個時間戳記是「現在」的 ±60 號，如果並非「現在」，請拒絕要求。重試時，此要求時間戳記並不是冪等的。
protocolVersion

object (Version)

必要項目：這項要求的版本。
paymentIntegratorAccountId

string

必要項目：識別具有合約限制的專屬帳戶。

時間戳記

時間戳記物件，代表 ISO 時間軸中的一個時間點 (從 Unix 紀元開始算起，以毫秒為單位)。

JSON 表示法 
{
  "epochMillis": string
}
欄位
epochMillis

string (Int64Value format)

必要項目：自 Unix 紀元以來的毫秒數

版本

Version 物件包含 API 的主要版本。同一個主要版本的版本保證相容。整合商必須支援相同主要版本的所有要求。

JSON 表示法 
{
  "major": integer
}
欄位
major

integer

必要項目：主要版本。標示為不同版本的廣告素材不保證能夠相容。

PaymentLookupCriteria

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

JSON 表示法 
{

  // Union field criteria can be only one of the following:
  "arnCriteria": {
    object (ArnCriteria)
  },
  "googleTransactionReferenceNumberCriteria": {
    object (GoogleTransactionReferenceNumberCriteria)
  },
  "captureRequestCriteria": {
    object (CaptureRequestCriteria)
  }
  // End of list of possible types for union field criteria.
}
欄位

聯集欄位 criteria。

criteria 只能採用下列其中一種設定：
arnCriteria

object (ArnCriteria)

選用：根據收銀員參考編號 (ARN) 查詢。
googleTransactionReferenceNumberCriteria

object (GoogleTransactionReferenceNumberCriteria)

選用：根據 Google 交易參考號碼查詢。
captureRequestCriteria

object (CaptureRequestCriteria)

選用：根據原始擷取要求查詢。

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

必要項目：交易的授權碼。

CaptureRequestCriteria

以原始擷取要求為依據的付款查詢條件。

JSON 表示法 
{
  "captureRequestId": string
}
欄位
captureRequestId

string

必要項目：這筆交易的專屬 ID。這是 Google 在查詢 capture 呼叫期間產生的 requestId。

RequestOriginator

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

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

string

必要項目：提出要求的公司、機構或機構群組的 ID。在這項paymentIntegratorAccountId中不得重複。
organizationDescription

string

必要項目：使用者可理解的機構名稱或說明，以便讓 Google 員工和整合商更容易與機構溝通。
agentId

string

OPTIONAL：organizationId 所識別的機構組織特定服務專員 (員工) 的專屬 ID，可由此要求產生。在這項organizationId中不得重複。

GetDisputeInquiryReportResponse

getDisputeInquiryReport 方法的回應酬載。

JSON 表示法 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "result": {
    object (GetDisputeInquiryReportResult)
  }
}
欄位
responseHeader

object (ResponseHeader)

必要項目：所有回應的通用標頭。
result

object (GetDisputeInquiryReportResult)

必要項目：這個呼叫的結果。

ResponseHeader

從伺服器傳送的所有回應中定義的標頭物件。

JSON 表示法 
{
  "responseTimestamp": {
    object (Timestamp)
  }
}
欄位
responseTimestamp

object (Timestamp)

必要項目：這個回應的時間戳記。接收端必須驗證這個時間戳記是「現在」的 ±60 秒，如果無效，則拒絕回應。

GetDisputeInquiryReportResult

JSON 表示法 
{

  // Union field result can be only one of the following:
  "success": {
    object (SuccessDetails)
  },
  "paymentNotFound": {
    object (Empty)
  },
  "paymentTooOld": {
    object (Empty)
  },
  "orderCannotBeReturned": {
    object (Empty)
  },
  "noAdditionalDetails": {
    object (Empty)
  }
  // End of list of possible types for union field result.
}
欄位

聯集欄位 result。

result 只能採用下列其中一種設定：
success

object (SuccessDetails)

已找到付款，並提供了報表。
paymentNotFound

object (Empty)

找不到您要求的款項。
paymentTooOld

object (Empty)

已找到要求的款項，但由於付款期限不足，我們並未提供報表。
orderCannotBeReturned

object (Empty)

您要求的款項屬於現有訂單，但無法傳回。原因包括訂單擁有者依要求移除訂單的情形。
noAdditionalDetails

object (Empty)

已找到要求的付款，但無法產生報表。

SuccessDetails

JSON 表示法 
{
  "googleClaimId": string,
  "report": {
    object (PurchaseReport)
  }
}
欄位
googleClaimId

string

必要項目：Google 產生的字串，專門用來識別客戶爭議。

如果在要求中填入 existingGoogleClaimId，這個值就會相同。否則就會是新產生的值。日後的 getDisputeInquiryReport 要求若涉及同一個客戶爭議，則可在日後要求提供這個值。
report

object (PurchaseReport)

必要項目：要求中指明的付款爭議相關詳細資料。

PurchaseReport

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

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

object (CustomerAccount)

必要項目：客戶及其帳戶的相關資訊。
order

object (Order)

OPTIONAL：付款訂單相關資訊。不適用於部分購買報表。
payment

object (Payment)

必要項目：付款相關資訊，注意：單筆訂單可能分筆數筆付款，但只提供原始要求中指明的付款資訊。

CustomerAccount

客戶帳戶的相關資訊。

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

string

選用：與客戶 Google 帳戶相關聯的電子郵件地址。
customerName

string

必要項目：客戶的名稱。

訂單

訂單相關資訊。

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

object (Timestamp)

必要項目：下單時的時間戳記。
orderId

string

必要項目：專門用來識別此訂單的字串。
subTotalAmount

object (Amount)

必填：這筆訂單的稅前總金額。
totalAmount

object (Amount)

必填：這筆訂單的總金額 (含稅)。
shippingAddress

object (Address)

選填：這張訂單中實體商品的運送地址。
items[]

object (Item)

必要項目：屬於此訂單的項目清單。
taxes[]

object (Tax)

必要項目：此訂單中的稅金清單。這份清單可能沒有任何內容。

金額

將金額以微量單位與貨幣代碼建立關聯。

JSON 表示法 
{
  "amountMicros": string,
  "currencyCode": string
}
欄位
amountMicros

string (Int64Value format)

必要項目：微量中的金額。
currencyCode

string

必要項目：以 3 個字母表示的 ISO 4217 貨幣代碼

地址

內含實際地址資訊的結構。

JSON 表示法 
{
  "addressLine": [
    string
  ],
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": 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": {
    object (Amount)
  },
  "googleProductName": string
}
欄位
description

string

必要項目：所購買商品的說明。
merchant

string

必要項目：商品的賣家、演出者或製造商。
quantity

string (Int64Value format)

OPTIONAL：此商品的訂購數量。

如果產品不適用的整數數量不適用 (例如計量付費產品可能會有小數點)，則會省略這個欄位。
totalPrice

object (Amount)

必要項目：這項商品的總價。
googleProductName

string

必要項目：商品的 Google 產品與服務名稱。

稅金

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

JSON 表示法 
{
  "description": string,
  "amount": {
    object (Amount)
  }
}
欄位
description

string

必要項目：稅金說明。
amount

object (Amount)

必要項目：稅金的金額。

付款

付款相關資訊。

JSON 表示法 
{
  "billingAddress": {
    object (Address)
  },
  "amount": {
    object (Amount)
  },
  "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

object (Amount)

必要項目：這筆款項的金額。
refunds[]

object (Refund)

必要項目：這筆款項的退款清單。這份清單可能沒有任何內容。

聯集欄位 fopDetails。

fopDetails 只能採用下列其中一種設定：
cardDetails

object (PaymentCardDetails)

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

退款

付款退款的相關資訊。

JSON 表示法 
{
  "amount": {
    object (Amount)
  },
  "initiatedTimestamp": {
    object (Timestamp)
  }
}
欄位
amount

object (Amount)

必要項目：退款金額。
initiatedTimestamp

object (Timestamp)

必要項目：辦理退款的時間戳記。

PaymentCardDetails

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

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

enum (AuthResult)

必要項目：付款驗證結果。

AuthResult

付款驗證結果。

列舉
UNKNOWN_RESULT 請勿設定此預設值。
APPROVED 授權已通過核准。
DENIED 授權遭拒。
NOT_ATTEMPTED 未嘗試授權。

空白

這個類型沒有任何欄位。

這個物件會用於擴充，因為布林值和列舉通常需要透過額外資料擴充。實作工具會使用此模式判斷內容是否存在。此代表的列舉可能會延伸以包含日後版本的資料。

Empty 的 JSON 表示法是空白的 JSON 物件 {}。

ErrorResponse

所有方法的錯誤回應物件。

JSON 表示法 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "errorDescription": string,
  "paymentIntegratorErrorIdentifier": string,
  "errorResponseResult": {
    object (ErrorResponseResult)
  }
}
欄位
responseHeader

object (ResponseHeader)

必要項目：所有回應的通用標頭。
errorDescription

string

選用：提供這個狀態的說明，以便支援代表進行偵錯。請注意，使用者不會看到這項資訊。其中可能包含用於偵錯的描述性非敏感文字。請注意，errorResponseCode 的某些值應在此欄位中隨附其他詳細資料。警告：除非權杖已定義為公開憑證，否則請勿在此訊息中加入任何權杖。
paymentIntegratorErrorIdentifier

string

選用：這個 ID 專屬於整合商，由整合商產生。這項資訊僅用於偵錯，才能辨識這個呼叫。這是整合商可辨識呼叫的 ID。
errorResponseResult

object (ErrorResponseResult)

選用：用於擷取所發生的錯誤類型的程式碼。

ErrorResponseResult

錯誤代碼

JSON 表示法 
{

  // Union field result can be only one of the following:
  "invalidApiVersion": {
    object (InvalidApiVersion)
  },
  "invalidPayloadSignature": {
    object (InvalidPayloadSignature)
  },
  "invalidPayloadEncryption": {
    object (InvalidPayloadEncryption)
  },
  "requestTimestampOutOfRange": {
    object (RequestTimestampOutOfRange)
  },
  "invalidIdentifier": {
    object (InvalidIdentifier)
  },
  "idempotencyViolation": {
    object (IdempotencyViolation)
  },
  "invalidFieldValue": {
    object (InvalidFieldValue)
  },
  "missingRequiredField": {
    object (MissingRequiredField)
  },
  "preconditionViolation": {
    object (PreconditionViolation)
  },
  "userActionInProgress": {
    object (UserActionInProgress)
  },
  "invalidDecryptedRequest": {
    object (InvalidDecryptedRequest)
  },
  "forbidden": {
    object (Forbidden)
  }
  // End of list of possible types for union field result.
}
欄位

聯集欄位 result。

result 只能採用下列其中一種設定：
invalidApiVersion

object (InvalidApiVersion)

如果不支援要求的 API 版本，即可使用此欄位。建議 HTTP 代碼：400
invalidPayloadSignature

object (InvalidPayloadSignature)

酬載的簽名是不明或無效的金鑰時使用。建議 HTTP 代碼：401
invalidPayloadEncryption

object (InvalidPayloadEncryption)

酬載的加密對像是不明或無效的金鑰時使用。建議 HTTP 代碼：400
requestTimestampOutOfRange

object (RequestTimestampOutOfRange)

如果 requestTimestamp 並非現在的 ±60s 時使用，建議 HTTP 代碼：400
invalidIdentifier

object (InvalidIdentifier)

要求中傳送的 ID 無效或不明時使用。這可能包括 PIAID、 captureRequestId、Google Payment Token 等。建議 HTTP 代碼：404
idempotencyViolation

object (IdempotencyViolation)

要求違反要求的冪等規定時使用。建議 HTTP 代碼：412
invalidFieldValue

object (InvalidFieldValue)

要求包含的欄位值不在支援的值集中時使用。建議 HTTP 代碼：400
missingRequiredField

object (MissingRequiredField)

如果要求中未設定必填欄位，系統會使用這個欄位。建議 HTTP 代碼：400
preconditionViolation

object (PreconditionViolation)

如果違反作業的限制 (例如要求的退款金額超過交易剩餘金額)，即可使用。建議 HTTP 代碼：400
userActionInProgress

object (UserActionInProgress)

如果目前無法處理要求，則使用這會中斷處理中使用者動作，這類動作會有效地做為系統鎖定。此程式碼不得用於表示因實作相關的內部並行錯誤而失敗。建議 HTTP 代碼：423
invalidDecryptedRequest

object (InvalidDecryptedRequest)

可以解密要求酬載，但無法剖析產生的訊息時使用。建議 HTTP 代碼：400
forbidden

object (Forbidden)

禁止存取要求的資源。建議 HTTP 代碼：403

InvalidApiVersion

JSON 表示法 
{
  "requestVersion": {
    object (Version)
  },
  "expectedVersion": {
    object (Version)
  }
}
欄位
requestVersion

object (Version)

必要項目：要求中指定的無效版本。
expectedVersion

object (Version)

必要項目：預期的版本。

InvalidPayloadSignature

這個類型沒有任何欄位。

這則訊息目前是空白的。日後可以加入新欄位。

InvalidPayloadEncryption

這個類型沒有任何欄位。

這則訊息目前是空白的。日後可以加入新欄位。

RequestTimestampOutOfRange

JSON 表示法 
{
  "requestTimestamp": {
    object (Timestamp)
  },
  "serverTimestampAtReceipt": {
    object (Timestamp)
  }
}
欄位
requestTimestamp

object (Timestamp)

必要項目：要求中提供的時間戳記
serverTimestampAtReceipt

object (Timestamp)

必要項目：接收到的伺服器時間，用於比較

InvalidIdentifier

JSON 表示法 
{
  "invalidIdentifierType": string
}
欄位
invalidIdentifierType

string

必要項目：無效 ID 類型，例如 PIAID、 captureRequestId 等。

IdempotencyViolation

這個類型沒有任何欄位。

這則訊息目前是空白的。日後可以加入新欄位。

InvalidFieldValue

JSON 表示法 
{
  "invalidFieldName": string
}
欄位
invalidFieldName

string

必要項目：經發現無效的欄位名稱。

MissingRequiredField

JSON 表示法 
{
  "missingFieldNames": [
    string
  ]
}
欄位
missingFieldNames[]

string

必要項目：缺少的欄位名稱。

PreconditionViolation

這個類型沒有任何欄位。

這則訊息目前是空白的。日後可以加入新欄位。

UserActionInProgress

這個類型沒有任何欄位。

這則訊息目前是空白的。日後可以加入新欄位。

InvalidDecryptedRequest

這個類型沒有任何欄位。

這則訊息目前是空白的。日後可以加入新欄位。

已禁止

這個類型沒有任何欄位。

這則訊息目前是空白的。日後可以加入新欄位。