Method: getOrderDetails

• HTTP 要求
• 要求主體
  • JSON 表示法
• 回應主體
  • JSON 表示法
• RequestHeader
  • JSON 表示法
• 版本
  • JSON 表示法
• OrderLookupCriteria
  • JSON 表示法
• ArnCriteria
  • JSON 表示法
• GoogleTransactionReferenceNumberCriteria
  • JSON 表示法
• RequestOriginator
  • JSON 表示法
• ResponseHeader
  • JSON 表示法
• GetOrderDetailsResultCode
• 訂單
  • JSON 表示法
• 商品
  • JSON 表示法
• 稅金
  • JSON 表示法

取得訂單，供 Google 合作夥伴向使用者收費。

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

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

要求範例如下：

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 1,
      "revision": 0
    },
    "requestId": "HsKv5pvtQKTtz7rdcw1YqE",
    "requestTimestamp": "1519996751331"
  },
  "paymentIntegratorAccountId": "IntegratorFakeAccount",
  "orderLookupCriteria": {
    "googleTransactionReferenceNumberCriteria": {
      "googleTransactionReferenceNumber": "714545417102363157911822",
      "authorizationCode": "111111"
    }
  },
  "requestOriginator": {
    "organizationId": "ISSUER_256",
    "organizationDescription": "Community Bank of Some City"
  }
}

回應範例如下所示：

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  },
  "result": "SUCCESS",
  "order": {
    "timestamp": "1517992525972",
    "orderId": "UPG.DEFC.X6F4.MEOM.CDWF",
    "currencyCode": "USD",
    "subTotalAmount": "399000000",
    "totalAmount": "459000000",
    "taxes": [],
    "items": [
      {
        "description": "YouTube TV membership",
        "merchant": "fake org",
        "googleProductName": "YouTube TV",
        "quantity": "1",
        "totalPrice": "399000000"
      },
      {
        "description": "Showtime",
        "merchant": "fake org",
        "googleProductName": "YouTube TV",
        "quantity": "1",
        "totalPrice": "6000000"
      }
    ]
  }
}

HTTP 要求

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

要求主體

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

JSON 表示法
{ "requestHeader": { object (RequestHeader) }, "paymentIntegratorAccountId": string, "orderLookupCriteria": { object (OrderLookupCriteria) }, "requestOriginator": { object (RequestOriginator) } }

欄位
requestHeader	object (RequestHeader) 必要項目：所有要求的通用標頭。
paymentIntegratorAccountId	string 必要項目：付款整合商帳戶 ID，用於識別呼叫者以及此互動的相關合約限制。
orderLookupCriteria	object (OrderLookupCriteria) 必要項目：用來指示要查詢訂單的條件。
requestOriginator	object (RequestOriginator) 選填：提出要求的機構或機構子群組的相關資訊 (如果整合商代表其他機構致電給我們)。

回應主體

getOrderDetails 方法的回應酬載。

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

JSON 表示法
{ "responseHeader": { object (ResponseHeader) }, "result": enum (GetOrderDetailsResultCode), "order": { object (Order) } }

欄位
responseHeader	object (ResponseHeader) 必要項目：所有回應的通用標頭。
result	enum (GetOrderDetailsResultCode) REQUIRED：呼叫的結果。
order	object (Order) 選用：付款訂單相關資訊。(只有在 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) REQUIRED：這項要求的時間戳記，以 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 必要項目：子版本。這代表微小的錯誤修正。

OrderLookupCriteria

訂單查詢條件。

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

欄位
聯集欄位 criteria。 criteria 只能採用下列其中一種設定：
dcb3CorrelationId	string 查詢 Google 產生的直接併入電信費關聯 ID，用於識別該筆款項。這個值是由 Google 產生，並在驗證呼叫期間傳送給電信代扣付款整合商。
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 }

欄位
organizationId	string 必要項目：提出要求的公司、機構或機構群組的 ID，在這個 paymentIntegratorAccountId 中不得重複。
organizationDescription	string 必要項目：人類可讀的機構名稱或說明，有助於 Google 員工和該機構的整合商順利溝通。

ResponseHeader

這個標頭物件定義於伺服器傳送的所有回應上。

JSON 表示法
{ "responseTimestamp": string }

欄位
responseTimestamp	string (int64 format) REQUIRED：此回應的時間戳記，以 Epoch 紀元時間起算的毫秒數表示。接收端應驗證這個時間戳記是否為「現在」的 ±60 秒。

GetOrderDetailsResultCode

getOrderDetails 方法呼叫的結果。

列舉
GET_ORDER_DETAILS_RESULT_CODE_UNKNOWN	切勿設定這個預設值！
SUCCESS	已找到訂單並退回。
ORDER_CANNOT_BE_RETURNED	要求的訂單已存在，但無法傳回。原因包括系統擁有者要求移除命令。 注意：此狀態為永久狀態。
PAYMENT_TOO_OLD	系統找到您要求的付款，但因付款年齡而未提供訂單詳細資料。
PAYMENT_NOT_FOUND	找不到你要求的付款。
NO_ADDITIONAL_DETAILS	已找到您要求的付款，但無法提供訂單詳細資料。

訂單

訂單相關資訊。

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

欄位
timestamp	string (int64 format) OPTIONAL：下單時間的時間戳記，以 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)。不適用於部分訂單類型。
items[]	object (Item) 必要項目：這筆訂單包含的商品清單。
taxes[]	object (Tax) 選用：這筆訂單的稅金清單。

項目

訂單中項目的資訊。

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

欄位
description	string 選用：購買商品的說明。不適用於部分訂單類型。
merchant	string 必要項目：商品的賣家、藝人或製造商。
quantity	string (Int64Value format) 選用：訂購商品的數量。 如果整數數量不適用於產品，系統就會省略這個欄位 (例如計量產品可能有小數點)。
totalPrice	string (Int64Value format) 選用：這個項目的總價，以 order.currencyCode 指定貨幣的百萬分之一表示。如果填入 quantity，這會反映全部數量的總價。不適用於部分訂單類型。
googleProductName	string 必填：商品的 Google 產品或服務名稱。

稅金

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

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

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