跳轉至

网络 PG 付款

網頁 PG 付款 API 是一個在您想要在網站上實現 PG 付款時使用的 API,儘管在開發 Windows 應用程式時不使用Hive SDK 付款。網頁 PG 付款 API 與在應用程式中實現 PG 付款的 API 不同。

Note

要在應用程式中實現PG支付,您需要使用Hive SDK Billing一般PG支付API

產品列表檢索

獲取產品資訊。用於在應用程式中實現產品列表。

請求 URL

環境 網址
生產網址 https://store.withhive.com/external/api/product
沙盒網址 https://sandbox-store.withhive.com/external/api/product
HTTP 方法 POST
內容類型 text/html; charset=utf-8
數據格式 JSON
授權 Bearer (token)

持有者令牌對應於在 Hive 控制台的 應用中心 > 專案管理 > 選擇遊戲公司 > 遊戲詳細資訊 > 基本資訊 中找到的 Hive 認證金鑰。

請求參數

欄位 類型 必填 描述
api 字串 API 識別值(使用固定值 `product`)
market_id 字串 Hive 市場 ID(PG 付款:使用固定值 `15`)
appid 字串 Hive 應用程式 ID
hive_country 字串 國家代碼(ISO 3166-1 兩個字母)
game_language 字串 語言(ISO 639-1 兩個字母)
vid 字串 Hive 帳戶資訊(玩家 ID)
vid_type 字串 帳戶類型(v4)
market_pid_type 字串 產品類型(消耗品)

回應元素

欄位 類型 必要 描述
result 整數 回應代碼(0表示成功,其他表示錯誤)
result_msg 字串 回應訊息
product_list 物件 產品資訊列表
product_list > market_pid 字串 產品PID
product_list > price 整數 產品價格(數值)
product_list > currency 字串 產品價格的貨幣
product_list > display_price 字串 產品價格(包含貨幣符號)
product_list > title 字串 產品名稱
product_list > description 字串 產品描述
product_list > product_type 字串 產品分類(消耗品)
update_date 字串 產品PID資訊的最後更新日期和時間

請求範例

curl -L -v \
    -d '{"api": "product","market_id": 15,"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal","hive_country": "KR","game_language": "ko","vid": "100000000000","vid_type": "v4","market_pid_type": "consumable"}' \
    -H "Content-Type: text/html" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
    https://sandbox-store.withhive.com/external/api/product

回應範例

{
    "result": 0,
    "result_msg": "success",
    "product_list": [
        {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
            "price": 1200,
            "currency": "KRW",
            "display_price": "₩1,200",
            "title": "크리스탈 한 줌",
            "description": "크리스탈 한 줌",
            "product_type": "consumable"
        }, {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item02",
            "price": 2500,
            "currency": "KRW",
            "display_price": "₩2,500",
            "title": "크리스탈 묶음",
            "description": "크리스탈 묶음",
            "product_type": "consumable"
        }, {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item03",
            "price": 3900,
            "currency": "KRW",
            "display_price": "₩3,900",
            "title": "크리스탈 더미",
            "description": "크리스탈 더미",
            "product_type": "consumable"
        }
    ],
    "update_date": "2022-10-28 16:11:23"
}

產品訂單請求

使用從產品列表中選擇的 PID(產品 ID)信息請求產品訂單。

請求 URL

環境 網址
生產網址 https://store.withhive.com/external/api/order
沙盒網址 https://sandbox-store.withhive.com/external/api/order
HTTP 方法 POST
內容類型 text/html; charset=utf-8
數據格式 JSON
授權 Bearer (token)

持有者令牌對應於在應用中心 > 專案管理 > 選擇遊戲公司 > 遊戲詳細資訊 > 基本資訊中找到的Hive 認證金鑰,該金鑰位於Hive 控制台中。

請求參數

欄位 類型 必填 描述
market_id 字串 O Hive 市場 ID
appid 字串 O Hive Appid
hive_country 字串 O 國家代碼 (ISO 3166-1 兩個字母)
game_language 字串 O 語言 (ISO 639-1 兩個字母)
vid 字串 O Hive 帳戶資訊 (玩家 ID)
vid_type 字串 O 帳戶類型 (v4)
market_pid 字串 O 產品 PID
server_id 字串 O 伺服器 ID
os 字串 O Windows: W, MAC: M, Android: A
quantity 整數 X 購買數量 (如果未發送,預設值為 1)
iap_payload 字串 X 由應用程式開發人員定義的購買元數據 購買元信息
fixed_currency 字串 X 支付方式曝光的貨幣 (ISO 4217 三個字母)
* 如果未提供 fixed_currency 參數,則根據 hive_country 曝光支付方式,但如果添加了 fixed_currency 參數,則根據 fixed_currency 貨幣曝光支付方式。
refund_idx 整數 X 退款用戶重新付款列表 IDX
* 只有在退款用戶重新付款請求時才需要
is_repayment 整數 X 是否為退款用戶重新付款 (0: 正常付款, 1: 退款用戶重新付款)
* 只有在退款用戶重新付款請求時才需要
expiration_time 整數 X 這是支付窗口的過期時間。它以 Unix 時間戳毫秒格式表示 (例如,1745395211)。如果 Hive 計費伺服器的當前時間 (Unix 時間戳毫秒) 超過此值,則將返回不同的指導頁面,而不是響應中的支付窗口 HTML 頁面。

請求範例

curl -L -v \
    -d '{"market_id": 15,"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal","hive_country": "KR","game_language": "ko","vid": "100000000000","vid_type": "v4","market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01","server_id": "KR1","os": "A","quantity": 1,"iap_payload": "{\"character_id\":\"hivesdk01\"}", "expiration_time": 1745395211}' \
    -H "Content-Type: text/html" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
    https://sandbox-store.withhive.com/external/api/order

回應範例

當產品訂單請求成功處理時,將返回一個選擇付款方式的彈出窗口。以下是組成彈出窗口的 HTML 頁面。

付款完成詳情查詢

當付款完成後,付款機構(PG)會直接將付款結果傳送到 Hive IAP v4 伺服器。這種方法彌補了網絡的不穩定性,並防止了付款數據的篡改。 在預工作期間,通過將註冊的付款信息與付款機構(PG)提供的信息進行比較來進行交叉驗證。一旦確認付款信息的完整性,將確保額外的安全措施,並存儲付款信息。存儲的付款信息可以通過付款完成歷史查詢 API 進行查詢。

客戶在需要用戶支付完成信息的時候,向遊戲伺服器請求信息,遊戲伺服器通過 Hive IAP v4 伺服器檢索支付信息。如果用戶有支付歷史,則使用 purchase_bypass_info 進行支付信息驗證。

請求 URL

    生產 URL https://hiveiap.qpyou.cn/api_v4/purchases/unconsumed
    沙盒 URL https://sandbox-hiveiap.qpyou.cn/api_v4/purchases/unconsumed
    HTTP 方法 POST
    內容類型 application/json
    數據格式 JSON
    授權 Bearer (token)

持有者令牌對應於在 Hive 控制台的 應用中心 > 專案管理 > 選擇遊戲公司遊戲 > 遊戲詳情 > 基本信息 中找到的 Hive 認證密鑰。

請求參數

    名稱 類型 必要性 (必要: M, 可選: O) 描述
    appid 字串 M 從 Hive 控制台 > 應用中心註冊並發放的 ID
    market_id 數字 M 唯一市場 ID(使用固定值 `15`)
    server_id 字串 M 用於區分支付發生的遊戲伺服器的代碼
    user_id_type 字串 M Hive 用戶類型(使用固定值 `player_id`)
    user_id 數字 M Hive 用戶 ID (`player_id`)

回應元素

    名稱 類型 必需 (必需: M, 可選: O) 描述
    result 數字 M 響應代碼 (0: 成功)
    result_msg 字符串 M 根據響應代碼的結果消息
    unconsumed_lists 對象數組 M
    ┕ market_pid 字符串 M 產品唯一ID
    ┕ order_id 字符串 M 訂單號
    ┕ server_id 字符串 M 區分購買用戶訪問的遊戲服務器的代碼
    ┕ vid 字符串 M 購買用戶的PlayerID
    ┕ amount 字符串 M 支付金額
    ┕ currency 字符串 M 支付貨幣
    ┕ quantity 數字 M 購買數量
    ┕ started_datetime 日期時間 M 支付開始的時間 (Y-m-d H:i:s)
    ┕ paid_datetime 日期時間 M 支付完成的時間 (Y-m-d H:i:s)
    ┕ started_datetime_ms 數字 M 支付開始的時間 (Unix 時間戳毫秒)
    ┕ paid_datetime_ms 數字 M 支付完成的時間 (Unix 時間戳毫秒)
    ┕ hiveiap_receipt 字符串 M 支付信息加密HASH
    ┕ purchase_bypass_info 字符串 M 收據驗證請求所需的信息
    ┕ iap_payload 字符串 O 從客戶端接收的額外信息以發送到遊戲服務器 (以JSON字符串格式) (如果未接收到信息,則返回null)

請求範例

curl -L -v
 -d '{"appid" : "com.com2us.hivesdk.windows.microsoftstore.global.normal","market_id" : 15,"server_id" : "kr","user_id_type": "player_id", "user_id": 30000056996}' \
 -H "Content-Type: text/html" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
 https://sandbox-hiveiap.qpyou.cn/api_v4/purchases/unconsumed

回應範例

{
    "result": 0,
    "result_msg": "SUCCESS",
    "unconsumed_lists": [
        {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
            "order_id": "h2164792542890731850",
            "server_id": "kr",
            "vid": "30000056996",
            "uid": "13079",
            "amount": "1200",
            "currency": "KRW",
            "quantity": 1,            
            "started_datetime": "2022-03-22 14:03:49",
            "paid_datetime": "2022-03-22 14:04:39",
            "market_id": "15",
            "hiveiap_receipt": "2YnGzfTCGycoMjcSyYyNXBjANwmFyB6m\/c0bYazQ8VQ=",
            "purchase_bypass_info": "eyJtYXJrZXRfcGlkIjoiY29tLmNvbTJ1cy5oaXZlc2R...",
            "started_datetime_ms": 1647925429000,
            "paid_datetime_ms": 1647925479000,
            "iap_payload": null
        }
    ]
}

付款信息验证

付款結果驗證 API 基於 IAP v4 收據驗證

支付結果驗證使用先前收到的 purchase_bypass_infopurchase_bypass_info 包含在進行支付之前通過 SDK 接收的各種信息,並發送至 Hive Analytics。如果您需要在收據驗證請求中發送 銷售日誌,請使用 game_info。接收到的 game_info 作為將日誌從 Hive IAP 發送到分析伺服器的中介。

請求 URL

    生產 URL https://hiveiap-verify.qpyou.cn/api_v4/verify
    沙盒 URL https://sandbox-hiveiap-verify.qpyou.cn/api_v4/verify
    HTTP 方法 POST
    內容類型 text/html
    數據格式 JSON
    授權 Bearer (token)

持有者令牌對應於在應用中心 > 專案管理 > 選擇遊戲公司 > 遊戲詳情 > 基本資訊中找到的Hive 認證金鑰,該金鑰位於Hive 控制台中。

請求參數

    名稱 類型 必要性 (必要: M, 選擇性: O) 描述
    purchase_bypass_info 字串 M 收據替代和分析傳輸的數據
    game_info 物件陣列 O 當有日誌需要發送到遊戲時,例如遊戲日誌或收入日誌,將此值添加到遊戲中以發送,並且 Hive IAP 將代表分析伺服器進行傳輸。在收據驗證階段,無法知道項目是否已交付 (itemsendok),因此這部分必須單獨實現並提供作為附加信息。
    ⠀⠀server_uid bigint O 由遊戲伺服器發出的用戶 ID 如果沒有,則為 0
    ⠀⠀giftee_uid bigint O null: 個人使用的付款
    0: 收到禮物的人存在,但 UID 無法驗證
    ⠀⠀level int O 用戶的遊戲內等級 如果沒有等級則不必要。如果沒有,則為 0。
    ⠀⠀character_id bigint O 伺服器內的唯一角色識別值 如果沒有角色的概念,則為 "0"
    ⠀⠀character_type_id int O 角色類型識別值 對於沒有角色概念的遊戲,輸入 "0"
    ⠀⠀character_level int O 角色類型識別值 對於沒有角色概念的遊戲,輸入 "0"
    ⠀⠀is_emulator int O 當通過像 BlueStacks 這樣的 PC 模擬器訪問時,輸入 "1",否則輸入 "0"

回應元素

    名稱 類型 必需 (必需: M, 可選: O) 描述
    result 數字 M 響應代碼 (參考響應代碼)
    result_msg 字符串 M 根據響應代碼的結果消息
    hiveiap_transaction_id 字符串 M 為每個成功驗證的收據生成的交易 ID。此值應儲存在遊戲伺服器上以執行重複收據檢查。
    hiveiap_market_id 字符串 O 市場唯一編號 (PG 付款: 固定為 15)
    hiveiap_market_pid 字符串 O 付款產品 PID
    hiveiap_market_transaction_id 字符串 O 訂單的唯一訂單號
    hiveiap_receipt 字符串 O 市場收據對象值 (PG 付款: 固定為 null)
    hiveiap_purchase_test 字符串 O 測試付款狀態 (Y: 測試付款 / N: 正常付款)
    hiveiap_iap_payload 字符串 O 從客戶端接收的額外信息以發送到遊戲伺服器。它是 JSON 字符串格式,如果沒有接收到信息,則返回 `null`。

回應代碼

    代碼 訊息 註解
    0 成功,重複的收據 驗證成功
    1000001 缺少請求參數 未發送任何參數
    1000003 數據庫連接錯誤 當數據庫連接失敗時
    1000005 內部伺服器錯誤 內部伺服器錯誤
    1000006 缺少必要的參數資訊 當缺少必要的參數值時
    1000503 驗證收據失敗 驗證收據失敗或是被駭的收據 (例如,欺騙性駭客)
    1000507 保存購買資訊失敗 保存購買歷史失敗
    1000524 驗證收據失敗。(訂單不存在) 收據驗證失敗(不存在的訂單)
    1000525 驗證收據失敗。(參數錯誤) 收據驗證失敗(參數錯誤)

請求範例

curl -L -v \
 -d '{"purchase_bypass_info":"eyJtYXJrZXRfaWQiOiIxNSIsIm9yZGVyX2lkIjoiSDMxNjQ3OTI1NDI4OTA3MzE4NTAiLCJtYXJrZXRfcGlkIjoiY29tLmNvbTJ1cy5oaXZlc2RrLndpbmRvd3MubWljcm9zb2Z0c3RvcmUuZ2xvYmFsLm5vcm1hbC5pdGVtMDEiLCJ2aWQiOiIzMDAwMDA1Njk5NiIsInVpZCI6IjEzMDc5Iiwic2VydmVyX2lkIjoia3IiLCJhcHBpZCI6ImNvbS5jb20ydXMuaGl2ZXNkay53aW5kb3dzLm1pY3Jvc29mdHN0b3JlLmdsb2JhbC5ub3JtYWwiLCJhbW91bnQiOiIxMjAwIiwic3RhcnRlZF9kYXRldGltZSI6bnVsbCwicGFpZF9kYXRldGltZSI6bnVsbCwiY3VycmVuY3kiOiJLUlciLCJoaXZlaWFwX3JlY2VpcHQiOiIyWW5HemZUQ0d5Y29NamNTeVl5TlhCakFOd21GeUI2bVwvYzBiWWF6UThWUT0ifQ=="}' \
 -H "Content-Type: text/html" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
 https://sandbox-hiveiap-verify.qpyou.cn/api_v4/verify

回應範例

{
    "result": 0,
    "result_msg": "success",
    "hiveiap_transaction_id": "HS_13",
    "hiveiap_market_id": 15,
    "hiveiap_market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
    "hiveiap_market_transaction_id": "h2164792542890731850",
    "hiveiap_receipt": null,
    "hiveiap_purchase_test": "N",
    "hiveiap_iap_payload": null
}

付款結果處理

支付結果處理API 基於 IAP v4 項目支付結果傳輸。通過支付結果處理API,從項目購買到支付完成的處理過程得以完成。如果支付處理未完成,用戶將無法購買相同的產品。在嘗試購買並進入支付頁面時,將顯示一條消息,指出「您已擁有此產品。」並且支付將不會進行。

當嘗試通過打開多個支付窗口進行購買和支付時,所有未處理的產品將自動取消。在處理所有支付流程(例如檢查購買限制和遊戲伺服器進行的物品分配)之後,支付結果將發送以通知 Hive IAP v4 伺服器支付已完成。如果您希望請求取消支付,您也可以通過分配結果處理 API 請求取消。

請求 URL

    生產 URL https://hiveiap.qpyou.cn/api_v4/item_result
    沙盒 URL https://sandbox-hiveiap.qpyou.cn/api_v4/item_result
    HTTP 方法 POST
    內容類型 text/html
    數據格式 JSON
    授權 Bearer (token)

承載者令牌對應於在Hive控制台的應用中心 > 專案管理 > 選擇遊戲公司遊戲 > 遊戲詳情 > 基本信息中找到的Hive身份驗證密鑰。

請求參數

    名稱 類型 必需 (必需: M, 選填: O) 描述
    hiveiap_transaction_id 字串 M 收據驗證結果的 hiveiap_transaction_id
    result_status 數字 M 項目授予成功狀態 0: 授予失敗 1: 授予成功 2: 付款取消退款請求(僅限 PG)
    result_status_message 字串 O 授予失敗或付款取消請求的原因
    user_id_type 字串 M Hive 用戶類型(使用固定值 `player_id`)
    user_id 數字 M Hive 用戶 ID (`player_id`)
    asset 物件陣列 O 授予項目的信息 只有在授予成功時提供值,授予失敗時回應空陣列 ([])
    asset_id 字串 O 項目 ID
    asset_name 字串 O 項目名稱
    ⠀⠀數量 數字 O 授予項目的數量

回應元素

    名稱 類型 必需 (必需: M, 可選: O) 描述
    result 數字 M 響應代碼 (0: 成功)
    result_msg 字符串 M 根據響應代碼的結果消息

請求範例

curl -L -v
 -d '{"hiveiap_transaction_id" : "HS_13","result_status": 1,"user_id_type": "player_id","user_id": 30000056996,"asset": [ {"asset_id":"item_id","asset_name":"item_name","quantity":1}
,{"asset_id":"item_id","asset_name":"item_name","quantity":1}]}' \
 -H "Content-Type: text/html" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
 https://sandbox-hiveiap.qpyou.cn/api_v4/item_result

回應範例

{
    "result": 0,
    "result_msg": "success"
}

付款結果通知服務

支付結果通知服務在支付完成或取消後立即將結果發送到遊戲伺服器。此 API 以與檢查支付完成歷史相同的方式傳輸purchase_bypass_info值,允許遊戲使用此值來驗證收據並將物品授予用戶。只有當支付結果傳輸信息中的type為已支付時,收據驗證和物品授予才應繼續進行。

Note

要使用此 API,您必須先在 Hive 控制台中設置 PG 公司。 建議使用此 API 或付款完成歷史查詢 API 進行收據驗證和產品交付。

付款結果傳輸的基本信息

    HTTP 方法 POST
    內容類型 application/json
    數據格式 JSON

付款結果傳輸資訊

    名稱 類型 必填 (必填: M, 選填: O) 描述
    type 字串 M 通知類型 (paid: 付款完成, cancelled: 付款取消或退款)
    market_pid 字串 M 唯一產品ID
    order_id 字串 M 訂單號碼
    server_id 字串 M 區分購買用戶連接的遊戲伺服器的代碼
    vid 字串 M 購買用戶的PlayerID
    vid_type 字串 O SDK版本 (預設v4)
    uid 字串 O Hive 會員UID的購買用戶
    amount 字串 M 付款金額
    currency 字串 M 付款貨幣
    quantity 數字 M 購買數量
    started_datetime 日期時間 M 付款開始時間 (Y-m-d H:i:s)
    paid_datetime 日期時間 M 付款完成時間 (Y-m-d H:i:s)
    cancelled_datetime 日期時間 O 付款取消或退款時間 (Y-m-d H:i:s)
    started_datetime_ms 數字 M 付款開始時間 (Unix TimeStamp 毫秒)
    paid_datetime_ms 數字 M 付款完成時間 (Unix TimeStamp 毫秒)
    cancelled_datetime_ms 數字 O 付款取消或退款時間 (Unix TimeStamp 毫秒)
    cancelled_reason 字串 O 付款取消或退款的原因
    hiveiap_receipt 字串 M 付款信息的加密HASH
    purchase_bypass_info 字串 M 收據驗證請求所需的資訊
    iap_payload 字串 O 從客戶端接收的額外資訊,將發送到遊戲伺服器。它是JSON字串格式,如果未收到任何資訊,則返回null。

付款結果傳輸範例(付款完成後)

{
    "type": "paid",
    "market_id": "15",
    "order_id": "H2168993822440686730",
    "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
    "vid": "20000011337",
    "uid": "67200717",
    "vid_type": "v4",
    "server_id": "kr",
    "appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal",
    "amount": "1200",
    "started_datetime": "2023-07-21 20:17:06",
    "paid_datetime": "2023-07-21 20:18:13",
    "cancelled_datetime": null,
    "cancelled_reason": null,
    "currency": "KRW",
    "quantity": 1,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "started_datetime_ms": 1689938226000,
    "paid_datetime_ms": 1689938293000,
    "cancelled_datetime_ms": null,
    "iap_payload": null,
    "purchase_bypass_info": "eyJ0eXBlIjoicGFpZCIsIm1hcmtldF9pZCI6IjE1Iiwib3JkZXJfaWQiOi..."
}

付款結果傳輸範例(在付款取消的情況下)

{
    "type": "cancelled",
    "market_id": "15",
    "order_id": "H2168993822440686730",
    "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
    "vid": "20000011337",
    "uid": "67200717",
    "vid_type": "v4",
    "server_id": "kr",
    "appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal",
    "amount": "1200",
    "started_datetime": "2023-07-21 20:17:06",
    "paid_datetime": "2023-07-21 20:18:13",
    "cancelled_datetime": "2023-07-21 20:21:44",
    "cancelled_reason": "테스트 결제 취소",
    "currency": "KRW",
    "quantity": 1,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "started_datetime_ms": 1689938226000,
    "paid_datetime_ms": 1689938293000,
    "cancelled_datetime_ms": 1689938504000,
    "iap_payload": null,
    "purchase_bypass_info": "eyJ0eXBlIjoiY2FuY2VsbGVkIiwibWFya2V0X2lkIjoiMT..."
}

退款用戶重新付款目標退款歷史查詢 API

此API檢索已請求退款並需要重新付款的用戶的退款歷史記錄。
如果您已在自實現的網絡商店中為退款用戶啟用重新付款功能,則應使用“退款用戶重新付款目標退款歷史查詢”API的響應值為退款用戶實現重新付款通知彈出UI。

使用「退款用戶重新付款目標退款歷史查詢」API 時,請注意以下事項。

  • is_refund 回應項目來自 PlayerID 查詢 API,僅在其為真時可使用。
  • 在請求重付款案例的付款時,請求參數 json 必須包含 refund_idx(Integer)is_repayment(Integer) 作為必要項目。

請求 URL

環境 網址
生產網址 https://store.withhive.com/external/api/refund_info
沙盒網址 https://sandbox-store.withhive.com/external/api/refund_info
HTTP 方法 POST
內容類型 text/html; charset=utf-8
數據格式 JSON
授權 Bearer (token)

持有者令牌對應於在 Hive 控制台的 應用中心 > 專案管理 > 選擇遊戲公司 > 遊戲詳情 > 基本資訊 中找到的 Hive 認證金鑰。

請求參數

字段 类型 必需 描述
appid 字符串 Hive Appid
vid_type 字符串 账户类型 ("v4")
vid 字符串 Hive 账户信息 (玩家 ID)
game_language 字符串 语言 (ISO 639-1 两个字母)
device 字符串 PC、移动区分 (pc, mobile)
* 如果设备项不存在,响应中将设置为移动

回應元素

欄位 類型 必填 描述
result 整數 回應代碼(0表示成功,其他則為錯誤)
result_msg 字串 回應訊息
guide_title 字串 指南標題
guide_content 字串 指南內容
customer_site 物件 客服地址
customer_site > pc 字串 PC客服地址
customer_site > mobile 字串 手機客服地址
refund_list 陣列 > 物件 退款重付款列表
refund_list > refund_idx 整數 重付款索引ID
refund_list > market_id 整數 Hive 市場ID
refund_list > market_pid 字串 產品PID
refund_list > refund_time 字串 退款日期和時間
refund_list > refund_time_ms 整數 退款日期和時間(Unix時間戳毫秒)
refund_list > quantity 整數 產品購買數量

請求範例

curl -L -v \
    -d '{"appid":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal","vid_type":"v4","vid":"20000015900","game_language":"ko","device":"pc"}' \
    -H "Content-Type: text/html" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
    https://sandbox-store.withhive.com/external/api/refund_info

回應範例

{
  "result": 0,
  "result_msg": "success",
  "guide_title": "환불 상품 재결제 안내",
  "guide_content": "고객님의 계정은 게임 서비스 약관 및 운영 정책 위반 행위(결제시스템 악용)가 확인되어, 
    게임 이용이 제한되었습니다.\n\n알 수없는 이유로 결제가 취소되었거나, 혹은 비정상적인 절차로 환불된 상품의 경우, 동일 상품 재결제 후 게임 이용이 가능합니다.\n\n 현재 접속한 단말OS의 마켓 상품만 재결제가 가능하오니, 다른 마켓은 해당 앱으로 접속하여 재결제 부탁드립니다. 
    스팀 환불 내역에 대한 재결제는 PC에서 진행하세요. 모든 마켓의 취소/환불 상품의 재결제가 완료되어야 게임 이용이 가능합니다.\n\n일부 마켓에서 한 상품을 여러 수량으로 한 번에 구매 후 환불한 경우, 
    동일한 수량으로 재결제 해야 합니다. 만약 환불한 수량과 재결제한 수량이 일치하지 않으면 해당 재결제 건은 자동 취소됩니다. 
    취소되는 시점은 마켓에 따라 상이하며 수일이 걸릴 수 있습니다.\n\n 재결제 도중 오류로 인하여 결제 실패한 경우, 현재 계정으로 다시 게임을 재실행해주세요. 디바이스를 변경하여 동일한 마켓계정이면서 다른 게임 계정으로 로그인하시면 결제가 정상적으로 완료되지 않을 수 있습니다.\n\n결제 불가상품을 비롯한 그밖의 문의사항은 고객센터로 접수 부탁드립니다.\n\n* 환불 시간은 UTC+9 기준입니다.",
  "customer_site": {
    "pc": "https://sandbox-customer.withhive.com/com2us/faq/game/539",
    "mobile": "https://sandbox-customer-m.withhive.com/com2us/faq/game/539"
  },
  "refund_list": [
    {
      "refund_idx": 20850,
      "market_id": 1,
      "market_pid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.cs01",
      "refund_time": "2023.02.02 15:47 (UTC+9)",
      "refund_time_ms": 1675320475000,
      "quantity": 1
    }
  ]
}

退款用戶重新付款通知彈出示例

Warning

使用者必須實作一個「刷新」按鈕,讓他們在完成再購付款後可以更新再購項目的列表。 在完成再購付款後,必須重新調用「退款使用者再購目標退款歷史查詢」API,以進行身份驗證釋放流程。