跳轉至

网络 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 控制台中 App Center > 專案管理 > 選擇遊戲公司遊戲 > 遊戲詳情 > 基本資訊 的 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

環境 URL
生產 URL https://store.withhive.com/external/api/order
沙盒 URL https://sandbox-store.withhive.com/external/api/order
HTTP 方法 POST
Content-Type text/html; charset=utf-8
數據格式 JSON
認證 Bearer (token)

持有者令牌對應於 Hive 控制台中的 App Center > 專案管理 > 選擇遊戲公司遊戲 > 遊戲詳情 > 基本資訊 中的 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 应用开发者定义的购买元信息 这里

請求範例

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\"}"}' \
    -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 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 控制台中的 App Center > 專案管理 > 選擇遊戲公司遊戲 > 遊戲詳情 > 基本資訊 中的 Hive 認證金鑰。

請求參數

    名稱 類型 必需 (必需: M, 選擇性: O) 描述
    appid 字串 M 從 Hive 控制台 > 應用中心註冊和發放的 ID
    market_id 數字 M 唯一市場 ID (使用固定值 `15`)
    server_id 字串 M 發生付款的遊戲伺服器識別碼
    user_id_type 字串 M HIVE 使用者類型 uid : 個人模組 (v0) vid : 認證 v1 (v1) player_id : 認證 v4 (v4)
    user_id 數字 M HIVE 使用者 ID 根據 user_id_type 發送 uid : 個人模組 (v0) vid : 認證 v1 (v1) player_id : 認證 v4 (v4)

回應元素

    名稱 類型 必需 (必需: M, 可選: O) 描述
    result 數字 M 響應代碼 (0: 成功)
    result_msg 字符串 M 根據響應代碼的結果消息
    unconsumed_lists 對象數組 M
    ┕ market_pid 字符串 M 產品唯一ID
    ┕ order_id 字符串 M 訂單號
    ┕ server_id 字符串 M 區分用戶購買的遊戲伺服器的代碼
    ┕ vid 字符串 M 用戶的PlayerID,v1身份驗證的VID
    ┕ uid 字符串 O 用戶的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)
    ┕ started_datetime_ms 數字 M 付款開始時間 (Unix TimeStamp 毫秒)
    ┕ paid_datetime_ms 數字 M 付款完成時間 (Unix TimeStamp 毫秒)
    ┕ 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 分析。如果您需要在收據驗證請求中發送 銷售日誌,請使用 game_info。收到的 game_info 作為從 Hive IAP 向分析伺服器發送日誌的中介。

請求網址

    生產 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 遊戲伺服器發出的 user_id 如果沒有,則為 0
    ⠀⠀giftee_uid bigint O null: 個人使用的付款 0: 收件人存在但 UID 無法驗證;Derby Days 客戶端帳戶沒有中心客戶端帳戶,因此這裡適用
    ⠀⠀level int O 用戶的遊戲內等級 如果沒有等級則不需要。如果沒有,則為 0。
    ⠀⠀character_id bigint O 伺服器內的唯一角色識別碼 (PK?)。 如果沒有角色概念,則為 "0"
    ⠀⠀character_type_id int O 角色類型識別碼 對於沒有角色概念的遊戲,輸入 "0"
    ⠀⠀character_level int O 角色類型識別碼 對於沒有角色概念的遊戲,輸入 "0"
    ⠀⠀is_emulator int O 如果通過模擬器(例如 BlueStacks)訪問,則輸入 "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: 正常付款)

回應代碼

    代碼 訊息 註解
    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"
}

付款結果處理

付款結果處理 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 控制台中 App Center > 專案管理 > 選擇遊戲公司遊戲 > 遊戲詳細資訊 > 基本資訊 的 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 使用者類型 v0: 個人模組 (uid) v1: 認證 v1 (vid) v4: 認證 v4 (player_id)
    user_id 數字 M 使用者 ID 如果 user_id_type 是 v0,發送 uid;如果 v1,發送 vid;如果 v4,發送 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": "vid","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 購買用戶的玩家ID,VID用於v1身份驗證
    vid_type 字串 O 根據SDK版本的vid類型值 (默認v4)
    uid 字串 O 購買用戶的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。

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

  • PlayerID查詢API的回應項目中,is_refund欄位僅在其為真時可用。
  • 當請求重新付款的案例時,請求參數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,以便進行身份驗證釋放流程。