跳轉至

网络 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 字符串 产品类型(消耗品:consumable)

回應元素

字段 类型 必需 描述
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 2 字符)
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 参数,则支付方式将根据指定的货币显示。
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)

持有者令牌對應於 App Center > 專案管理 > 選擇遊戲公司遊戲 > 遊戲詳情 > 基本信息 中的 Hive 認證金鑰,在 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 時間戳毫秒)
    ┕ 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

    生產網址 https://hiveiap-verify.qpyou.cn/api_v4/verify
    沙盒網址 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)

Bearer 令牌對應於 Hive 控制台中 App Center > 專案管理 > 選擇遊戲公司遊戲 > 遊戲詳細資訊 > 基本資訊 的身份驗證金鑰。

請求參數

    名稱 類型 必要 (必要: 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 時間戳毫秒)
    paid_datetime_ms 數字 M 付款完成時間 (Unix 時間戳毫秒)
    cancelled_datetime_ms 數字 O 付款被取消或退款的時間 (Unix 時間戳毫秒)
    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)

Bearer 令牌對應於 App Center > 專案管理 > 選擇遊戲公司遊戲 > 遊戲詳細資訊 > 基本資訊 中的 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,以進行身份驗證釋放流程。