REST Resource: externaltransactions

資源：ExternalTransaction

外部交易的詳細資料。

JSON 表示法 
{
  "packageName": string,
  "externalTransactionId": string,
  "originalPreTaxAmount": {
    object (Price)
  },
  "originalTaxAmount": {
    object (Price)
  },
  "currentPreTaxAmount": {
    object (Price)
  },
  "currentTaxAmount": {
    object (Price)
  },
  "testPurchase": {
    object (ExternalTransactionTestPurchase)
  },
  "transactionTime": string,
  "createTime": string,
  "transactionState": enum (TransactionState),
  "userTaxAddress": {
    object (ExternalTransactionAddress)
  },
  "transactionProgramCode": integer,

  // Union field transaction_type can be only one of the following:
  "oneTimeTransaction": {
    object (OneTimeExternalTransaction)
  },
  "recurringTransaction": {
    object (RecurringExternalTransaction)
  }
  // End of list of possible types for union field transaction_type.

  // Union field program_details can be only one of the following:
  "externalOfferDetails": {
    object (ExternalOfferDetails)
  }
  // End of list of possible types for union field program_details.
}
欄位
packageName

string

僅供輸出。外部交易的資源名稱。售出應用程式內商品的應用程式套件名稱 (例如「com.some.app」)。
externalTransactionId

string

僅供輸出。這筆交易的 ID。同一套件名稱下的所有交易 ID 不得重複。建立外部交易時設定。
originalPreTaxAmount

object (Price)

必填。原始交易金額 (不含稅金)。這代表原始通知 Google 的稅前金額，不含任何退款。
originalTaxAmount

object (Price)

必填。原始稅額。這代表 Google 原先通知的稅額，也就是套用退款前的稅額。
currentPreTaxAmount

object (Price)

僅供輸出。目前交易的稅前金額。這是目前的稅前金額，包括可能已套用至這筆交易的任何退款。
currentTaxAmount

object (Price)

僅供輸出。目前的稅額。這代表目前的稅額，包括可能已套用至這筆交易的任何退款。
testPurchase

object (ExternalTransactionTestPurchase)

僅供輸出。如果已設定，這筆交易為測試購買。Google 不會針對測試交易收費。
transactionTime

string (Timestamp format)

必填。交易完成的時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
createTime

string (Timestamp format)

僅供輸出。這筆交易的建立時間。這是 Google 收到交易通知的時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
transactionState

enum (TransactionState)

僅供輸出。交易目前的狀態。
userTaxAddress

object (ExternalTransactionAddress)

必填。用於計算稅金的使用者地址。
transactionProgramCode

integer

選用。交易計畫代碼，用於判斷參與合作夥伴計畫的合格應用程式服務費。如果開發人員加入 Play 媒體體驗計畫 (https://play.google.com/console/about/programs/mediaprogram/)，回報其他結帳系統交易時必須提供計畫代碼。如果您是符合資格的開發人員，請與商務拓展經理聯絡，進一步瞭解如何設定這個欄位。注意：這個欄位無法用於外部優惠交易。
聯集欄位 transaction_type。執行的交易類型。transaction_type 只能是下列其中一項：
oneTimeTransaction

object (OneTimeExternalTransaction)

這是一次性交易，不屬於訂閱項目。
recurringTransaction

object (RecurringExternalTransaction)

這筆交易屬於週期性交易系列。
聯集欄位 program_details。交易報表所需的方案特定詳細資料。詳細資料只能針對與交易相關聯的計畫設定。program_details 只能是下列其中一項：
externalOfferDetails

object (ExternalOfferDetails)

選用。準確回報外部優惠交易的必要詳細資料。

ExternalTransactionTestPurchase

這個類型沒有任何欄位。

代表使用測試帳戶執行的交易。Google 不會收取這類交易的費用。

OneTimeExternalTransaction

代表一次性交易。

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

string

僅限輸入。在呼叫 Create 時提供。啟動其他結帳系統流程時，從用戶端擷取。

RecurringExternalTransaction

代表週期性付款系列中的一筆交易。這可能是訂閱項目，或需要多次付款的一次性產品 (例如預購)。

JSON 表示法 
{

  // Union field source can be only one of the following:
  "initialExternalTransactionId": string,
  "externalTransactionToken": string,
  "migratedTransactionProgram": enum (ExternalTransactionProgram)
  // End of list of possible types for union field source.

  // Union field product_details can be only one of the following:
  "externalSubscription": {
    object (ExternalSubscription)
  },
  "otherRecurringProduct": {
    object (OtherRecurringProduct)
  }
  // End of list of possible types for union field product_details.
}
欄位

聯集欄位 source。

source 只能是下列其中一個設定：
initialExternalTransactionId

string

這組週期性交易中第一筆交易的外部交易 ID。舉例來說，如果是訂閱交易，這就是第一筆款項的交易 ID。建立週期性外部交易時必須提供。
externalTransactionToken

string

僅供輸入。在呼叫 Create 時提供。啟動其他結帳系統流程時，從用戶端擷取。僅限首次購買時需要。
migratedTransactionProgram

enum (ExternalTransactionProgram)

僅限輸入。在呼叫 Create 時提供。僅適用於將訂閱項目從手動月度回報遷移至自動回報。
聯集欄位 product_details。必填。外部週期性交易中的產品詳細資料。product_details 只能是下列其中一項：
externalSubscription

object (ExternalSubscription)

外部訂閱方案的詳細資料。
otherRecurringProduct

object (OtherRecurringProduct)

不屬於任何其他特定類別的週期性外部交易產品詳細資料。

ExternalTransactionProgram

代表使用者完成交易時所參與的外部交易計畫。

列舉
EXTERNAL_TRANSACTION_PROGRAM_UNSPECIFIED 未指定交易計畫。未使用。
USER_CHOICE_BILLING 使用者自選結帳系統：使用者可選擇 Google Play 帳款服務或開發人員管理的結帳系統。
ALTERNATIVE_BILLING_ONLY 僅限其他帳單系統，使用者只能使用開發人員管理員帳單。

ExternalSubscription

外部訂閱方案的詳細資料。

JSON 表示法 
{
  "subscriptionType": enum (SubscriptionType)
}
欄位
subscriptionType

enum (SubscriptionType)

必填。外部訂閱方案類型。

SubscriptionType

外部訂閱的類型。

列舉
SUBSCRIPTION_TYPE_UNSPECIFIED 未指定，請勿使用。
RECURRING 這是週期性訂閱方案，系統會在每個帳單週期向使用者收費。
PREPAID 這是預付型訂閱方案，使用者會預先付款。

OtherRecurringProduct

這個類型沒有任何欄位。

不屬於任何其他更具體類別的週期性外部交易產品詳細資料。

TransactionState

交易的狀態。

列舉
TRANSACTION_STATE_UNSPECIFIED 未指定交易狀態。未使用。
TRANSACTION_REPORTED Google 已收到這筆交易的檢舉。
TRANSACTION_CANCELED 交易已全額退款。

ExternalTransactionAddress

使用者外部交易的地址。

JSON 表示法 
{
  "regionCode": string,
  "administrativeArea": string
}
欄位
regionCode

string

必填。根據 ISO-3166-1 Alpha-2 (聯合國區域代碼) 的雙字母區域代碼。
administrativeArea

string

選用。國家/地區的最上層行政區劃分。僅適用於在印度進行的交易。有效值包括「ANDAMAN AND NICOBAR ISLANDS」、「ANDHRA PRADESH」、「ARUNACHAL PRADESH」、「ASSAM」、「BIHAR」、「CHANDIGARH」、「CHHATTISGARH」、「DADRA AND NAGAR HAVELI」、「DADRA AND NAGAR HAVELI AND DAMAN AND DIU」、「DAMAN AND DIU」、「DELHI」、「GOA」、「GUJARAT」、「HARYANA」、「HIMACHAL PRADESH」、「JAMMU AND KASHMIR」、「JHARKHAND」、「KARNATAKA」、「KERALA」、「LADAKH」、「LAKSHADWEEP」、「MADHYA PRADESH」、「MAHARASHTRA」、「MANIPUR」、「MEGHALAYA」、「MIZORAM」、「NAGALAND」、「ODISHA」、「PUDUCHERRY」、「PUNJAB」、「RAJASTHAN」、「SIKKIM」、「TAMIL NADU」、「TELANGANA」、「TRIPURA」、「UTTAR PRADESH」、「UTTARAKHAND」和「WEST BENGAL」。

ExternalOfferDetails

外部優惠計畫專屬的報表詳細資料。

JSON 表示法 
{
  "linkType": enum (ExternalOfferLinkType),
  "installedAppPackage": string,
  "installedAppCategory": enum (ExternalOfferAppCategory),
  "appDownloadEventExternalTransactionId": string
}
欄位
installedAppPackage

string

選用。透過這筆交易下載的應用程式套件名稱。如果 linkType 為 LINK_TO_APP_DOWNLOAD，則為必填欄位。
installedAppCategory

enum (ExternalOfferAppCategory)

選用。透過這筆交易下載的應用程式類別。這必須與外部應用程式驗證程序期間，在 Play 管理中心提供的類別相符。僅適用於應用程式下載。
appDownloadEventExternalTransactionId

string

選用。透過外部連結與應用程式下載事件相關聯的外部交易 ID。回報在外部安裝應用程式中進行的交易時，此為必填屬性。

ExternalOfferLinkType

外部連結類型。

列舉
LINK_TO_DIGITAL_CONTENT_OFFER 購買數位內容的優惠。

ExternalOfferAppCategory

下載的應用程式類別。如要進一步瞭解應用程式類別，請參閱 https://support.google.com/googleplay/android-developer/answer/9859673。

列舉
EXTERNAL_OFFER_APP_CATEGORY_UNSPECIFIED 未指定，請勿使用。
APP 應用程式會歸類在應用程式類別下。
GAME 應用程式歸類在遊戲類別。

方法

createexternaltransaction

 建立新的外部交易。

getexternaltransaction

 取得現有的外部交易。

refundexternaltransaction

 退款或部分退款現有的外部交易。

錯誤代碼

這項資源的作業會傳回下列 HTTP 錯誤碼：

錯誤代碼 原因 說明 解析度
400 invalidValue 要求中提供的值無效。如果購買權杖格式有誤或無效，通常會傳回這個錯誤。 根據 API 參考資料，更正要求主體或參數中的無效欄位值。
400 required 要求缺少必要欄位或參數。 請參閱 API 說明文件，確認已包含所有必填欄位和參數。
403 userInsufficientPermission 使用者沒有足夠的權限可執行要求作業。 確認已驗證的使用者在 Google Play 管理中心具備必要權限。詳情請參閱「 使用服務帳戶」。
404 notFound 找不到要求的資源。 確認 ID (例如購買憑證、套件名稱、產品 ID、訂閱 ID) 正確無誤。
409 concurrentUpdate 嘗試更新正在同步更新的物件。 以指數輪詢方式重試要求。請避免同時修改相同資源。
5xx Generic error Google Play 伺服器發生一般錯誤。 請重試要求。

如果問題持續發生，請與 Google Play 帳戶管理員聯絡，或提交支援要求。建議查看 Play 狀態資訊主頁，瞭解是否有已知服務中斷情形。