發送消費信息

當應用程式使用者申請退款時，該介面將使用者消費資訊傳輸至應用程式商店。

消費資訊傳輸API使用Hive伺服器和應用伺服器之間的伺服器到伺服器通訊。 Hive伺服器向應用程式伺服器發送消費資訊請求，應用伺服器向Hive伺服器回傳回應。

Info

消費資訊傳輸支援Apple App Store和Google Play。由於每個商店都有不同的觸發器和回應資料規範，因此請從下面的標籤中選擇要整合的商店。

Apple App StoreGoogle Play

Apple App Store¶

發送到商店的一些消費資訊僅存在於應用程式伺服器上。要將此資料傳送到 Apple App Store，應用程式伺服器必須將其提供給 Hive 伺服器。

應用程式伺服器 URL 是應用程式伺服器開啟的 API 端點，用於向 Hive 伺服器提供資料。根據以下規範配置端點並將其註冊為應用程式伺服器 URL。每當用戶要求退款時，Hive 伺服器都會向此端點發送 POST 請求，並從應用程式伺服器接收所需的資料。 Hive 伺服器匯總這些數據並代表應用程式開發人員將消費資訊傳輸到 Apple App Store。

整體流程如下。

App：根據下面的規範配置API端點並準備伺服器URL
App：在Hive控制台的附加服務設定>消費資訊傳輸中，啟用Apple App Store並註冊伺服器URL 3.應用客戶端：應用程式運行時，獲得同意傳輸應用程式內商品消費資訊
App用戶：在App中申請退款 5.蘋果：向Hive伺服器發送消費資訊請求（CONSUMPTION_REQUEST）
Hive 伺服器：向應用程式註冊的伺服器 URL 發送 POST API 請求，並接收應用程式伺服器回應中的消費訊息 7.Hive伺服器：向Apple App Store發送消費資訊。 Apple 在成功時回應 HTTP 202

Warning

如果應用程式使用者未在同意彈窗中同意傳送資訊，即使 Hive 伺服器已從應用程式伺服器接收到資料，也不會將其傳送到商店。應用程式伺服器無需傳送使用者同意狀態（customerConsented），該狀態由 Hive 伺服器直接設定。

停用防火牆規則¶

註冊為伺服器 URL 的 API 端點必須使用請求參數中的使用者資訊 (player_id) 和交易資訊 (transaction_id) 檢索消費訊息，並傳回符合下列規範的資料。

若要允許 Hive 伺服器向應用程式伺服器 API 端點傳送請求，請在應用程式伺服器上停用下列 IP 位址的防火牆入站規則。

Hive 伺服器IP
15.165.223.210
3.34.158.195
43.202.20.33
13.209.91.38
3.34.235.15
15.165.134.120

設定API請求（Hive伺服器到應用程式伺服器）¶

以下是從Hive伺服器傳送到應用程式伺服器的POST請求。

API資訊	描述
方法	郵政
回應格式	JSON
內容類型	應用程式/json

請求正文¶

請求正文如下。

名稱	類型	必填（M：必填，O：可選）	描述
gameindex	整數	M	App Center Game Index
appid	字串	M	App Center 應用程式 ID
server_id	字串	M	應用程式伺服器ID
player_id	字串	M	應用程式中的使用者識別碼（用於購買驗證的使用者識別值）。對應V1中的`user_seq`
transaction_id	字串	M	Apple原始交易ID（`originalTransactionId`）
hiveiap_transaction_id	字串	M	為每個成功驗證的收據產生交易 ID。 Hive IAP v4 收據驗證傳回的 `hiveiap_transaction_id` 值

以下是請求正文範例。

{
        "gameindex": 539,
        "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
        "server_id": "server_01",
        "player_id": "222333",
        "transaction_id": "2000000123456789",
        "hiveiap_transaction_id": "AP_13"
}

設定API回應（應用程式伺服器到Hive伺服器）¶

應用伺服器將處理結果碼（code）、結果訊息（message）和消費資訊（data）傳送給Hive伺服器。

回應正文¶

Hive 伺服器根據 code 值確定成功。如果值為200，則請求成功，伺服器使用data。對於任何其他程式碼，伺服器不會傳輸該項目並記錄 message 作為原因。需要 code。如果省略，則該請求將被視為錯誤並且不會傳輸該項目。

名稱	類型	必填（M：必填，O：可選）	描述
code	整數	M	處理結果代碼。只有200表示成功；所有其他代碼被視為錯誤
message	字串	O	處理結果訊息。描述錯誤的原因
data	物件	M	響應數據（成功時需要）
┕ delivery_status	字串	M	消耗品交付狀態。以下交貨狀態中的數值之一
┕ refund_preference	字串	O	退款優惠。以下退款偏好中的數值之一
┕ consumption_percentage	整數	O	消耗百分比。 0-100000，以毫百分比表示 (100000 = 100%)
┕ sample_content_provided	整數	O	是否提供樣品內容。 0 或 1

回應程式碼¶

值	描述
200	成功
400	請求值無效
500	伺服器錯誤

交貨狀態 (`delivery_status`)¶

表示消耗性物品的交付狀態。此欄位為必填，必須指定以下五個值之一。

值	意義
DELIVERED	消耗品已交付且工作正常
UNDELIVERED_QUALITY_ISSUE	由於品質問題，該商品未交付
UNDELIVERED_WRONG_ITEM	交付了不同或不正確的物品
UNDELIVERED_SERVER_OUTAGE	由於伺服器中斷，該物品未送達
UNDELIVERED_OTHER	因其他原因該物品未送達

退款優惠 (`refund_preference`)¶

將應用程式的首選退款結果發送給 Apple。如果發送此可選字段，則它必須包含以下三個值之一。

值	意義
GRANT_FULL	更願意全額退款
DECLINE	寧願拒絕退款
GRANT_PRORATED	傾向於部分或按比例退款，主要用於訂閱

Warning

如果以下任何值無效，則該商品將被排除並且不會傳輸到商店。

delivery_status 為必填項，且必須包含上述五個值之一。
如果發送，refund_preference 必須包含上述三個值之一。
如果發送，consumption_percentage 必須是 0 到 100000 之間的整數。

Note

Hive伺服器根據Apple的規則自動調整以下值。

如果 delivery_status 不是 DELIVERED，則 consumption_percentage 傳送為 0。
如果refund_preference是GRANT_PRORATED（訂閱），則省略consumption_percentage。

以下是成功請求的回應正文範例。

{
        "code": 200,
        "message": "OK",
        "data": {
                "delivery_status": "DELIVERED",
                "refund_preference": "GRANT_FULL",
                "consumption_percentage": 100000,
                "sample_content_provided": 0
        }
}

Google Play¶

發送到商店的一些消費資訊僅存在於應用程式伺服器上。要將此資料傳送到 Google Play，應用程式伺服器必須將其提供給 Hive 伺服器。

應用程式伺服器 URL 是應用程式伺服器開啟的 API 端點，用於向 Hive 伺服器提供資料。根據以下規範配置端點並將其註冊為應用程式伺服器 URL。每當發生退款審核通知時，Hive 伺服器都會向此端點發送 POST 請求，並從應用程式伺服器接收所需的資料。 Hive 伺服器會匯總這些數據，並代表應用程式開發者將退款審核資訊傳送給 Google。

整體流程如下。

App：根據下面的規範配置API端點並準備伺服器URL
App：在Hive控制台的附加服務設定>消費資訊傳輸中，啟用Google Play並註冊伺服器URL
應用程式使用者：直接向信用卡發卡機構等金融機構申請交易退款（退款）
Google：向Hive伺服器發送退款審核通知（pendingRefundReviewNotification）
Hive 伺服器：向應用程式註冊的伺服器 URL 發送 POST API 請求，並接收回應中的數據
Hive 伺服器：使用 orders:reviewrefund 向 Google 發送退款審核資訊。如果成功，Google 將會傳回一個空的 HTTP 200 正文

Note

Google Play 退款審核不需要應用程式內同意流程。當用戶直接向金融機構要求退款（退款）時，Google 會將退款審核通知傳送至 Hive 伺服器進行處理。

停用防火牆規則¶

註冊為伺服器 URL 的 API 端點必須使用請求參數中的使用者資訊 (player_id) 和交易資訊 (order_id) 檢索消費訊息，並傳回符合下列規範的資料。

若要允許 Hive 伺服器向應用程式伺服器 API 端點傳送請求，請在應用程式伺服器上停用下列 IP 位址的防火牆入站規則。

Hive 伺服器IP
15.165.223.210
3.34.158.195
43.202.20.33
13.209.91.38
3.34.235.15
15.165.134.120

設定API請求（Hive伺服器到應用程式伺服器）¶

以下是從Hive伺服器傳送到應用程式伺服器的POST請求。

API資訊	描述
方法	郵政
回應格式	JSON
內容類型	應用程式/json

請求正文如下。

名稱	類型	必填（M：必填，O：可選）	描述
gameindex	整數	M	App Center Game Index
appid	字串	M	App Center 應用程式 ID
server_id	字串	M	應用程式伺服器ID
player_id	字串	M	應用程式中的使用者識別碼（用於購買驗證的使用者識別值）。對應V1中的`user_seq`
order_id	字串	M	Google 訂單 ID (`orderId`)
hiveiap_transaction_id	字串	M	Hive IAP v4 收據驗證傳回的 `hiveiap_transaction_id` 值

以下是請求正文範例。

{
        "gameindex": 539,
        "appid": "com.com2us.hivesdk.normal.freefull.google.global.android.universal",
        "server_id": "server_01",
        "player_id": "222333",
        "order_id": "GPA.3300-1234-5678-90123",
        "hiveiap_transaction_id": "GO_13"
}

設定API回應（應用程式伺服器到Hive伺服器）¶

應用伺服器將處理結果碼（code）、結果訊息（message）和消費資訊（data）傳送給Hive伺服器。

Hive 伺服器根據 code 值確定成功。如果值為200，則請求成功，伺服器使用data。對於任何其他程式碼，伺服器不會傳輸該項目並記錄 message 作為原因。需要 code。如果省略，則該請求將被視為錯誤並且不會傳輸該項目。

名稱	類型	必填（M：必填，O：可選）	描述
code	整數	M	處理結果代碼。只有200表示成功；所有其他代碼被視為錯誤
message	字串	O	處理結果訊息。描述錯誤的原因
data	物件	M	響應數據（成功時需要）
┕ refund_preference	字串	M	退款優惠。以下退款偏好中的數值之一
┕ sample_content_provided	整數	M	是否提供樣本內容。 0 或 1
┕ consumption_percentage_milliunits	整數	M	消費百分比。 0-100000，以毫百分比表示 (100000 = 100%)
┕ consumption_usage_events	陣列	O	消費事件列表（最多1000個）。參見下面的消費事件

回應程式碼¶

值	描述
200	成功
400	請求值無效
500	伺服器錯誤

退款優惠 (`refund_preference`)¶

將應用程式的首選退款結果發送給 Google。此必填欄位必須包含以下四個值之一。

值	意義
APPROVE	更願意批准退款
DECLINE	寧願拒絕退款
NEUTRAL	無偏好（中立）
REFUND_PREFERENCE_UNSPECIFIED	未指定偏好

消費事件（`consumption_usage_events`）¶

每個消費事件包含以下欄位。所有欄位都是可選的，但如果發送 location，則 location.region_code 是必需的。

名稱	類型	必需的	描述
obfuscated_account_id	字串	O	混淆的帳戶標識符
obfuscated_profile_id	字串	O	混淆的設定檔標識符
consumption_time	字串	O	消耗時間（RFC 3339，例如`2026-07-20T00:00:00Z`）
ip_address	字串	O	消費時的IP位址
consumption_item_description	字串	O	消耗物品的描述
location	物件	O	消費地點資訊
┕ region_code	字串	M（內含 `location` 時）	區域代碼（CLDR，例如 `KR`）
┕ administrative_area	字串	O	行政區
┕ locality	字串	O	城市
┕ sublocality	字串	O	次地方性

Warning

如果以下任何值無效，則該項目將被排除並且不會傳輸給 Google。

refund_preference 是必需的，並且必須包含上述四個值之一。
sample_content_provided 為必填項，且必須為 0 或 1。
consumption_percentage_milliunits 為必填項，且必須是 0 到 100000 之間的整數。
如果發送，consumption_usage_events 最多可包含 1000 個事件。如果事件包含 location，則需要 location.region_code。

以下是成功請求的回應正文範例。

{
        "code": 200,
        "message": "OK",
        "data": {
                "refund_preference": "APPROVE",
                "sample_content_provided": 0,
                "consumption_percentage_milliunits": 100000,
                "consumption_usage_events": [
                        {
                                "consumption_time": "2026-07-20T00:00:00Z",
                                "ip_address": "203.0.113.10",
                                "consumption_item_description": "Sample consumed item",
                                "location": {
                                        "region_code": "KR"
                                }
                        }
                ]
        }
}

發送消費信息

Apple App Store¶

停用防火牆規則¶

設定API請求（Hive伺服器到應用程式伺服器）¶

請求正文¶

設定API回應（應用程式伺服器到Hive伺服器）¶

回應正文¶

回應程式碼¶

交貨狀態 (delivery_status)¶

退款優惠 (refund_preference)¶

Google Play¶

停用防火牆規則¶

設定API請求（Hive伺服器到應用程式伺服器）¶

設定API回應（應用程式伺服器到Hive伺服器）¶

回應程式碼¶

退款優惠 (refund_preference)¶

消費事件（consumption_usage_events）¶

交貨狀態 (`delivery_status`)¶

退款優惠 (`refund_preference`)¶

退款優惠 (`refund_preference`)¶

消費事件（`consumption_usage_events`）¶