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) 必要項目：這個呼叫的結果。
order	object (Order) OPTIONAL：付款訂單相關資訊。(只有在 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 必要項目：子版本。這代表小錯誤修正。

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 產生的 DCB 相關 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) 必要項目：此回應的時間戳記，以 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) 選用：下單時的時間戳記，以 Epoch 紀元時間起算的毫秒為單位。不適用於某些訂單類型。
orderId	string 選用：用來識別此順序的字串。不適用於某些訂單類型。
currencyCode	string 選用：這個訂單中所有金額的 ISO 4217 貨幣代碼，由 3 個字母組成。不適用於某些訂單類型。
subTotalAmount	string (Int64Value format) 選填：這筆訂單稅前的總金額，以 order.currencyCode 指定貨幣的百萬分之一表示。等於 SUM(items.totalPrice)。不適用於某些訂單類型。
totalAmount	string (Int64Value format) 選填：這筆訂單的總金額 (含稅金)，以 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) 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 指定貨幣的百萬分之一表示。