跳轉至

网络 PG 付款

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

Note

要在應用程式中實現 PG 付款,您需要使用 Hive SDK BillingGeneral PG Payment 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 控制台中**應用中心 > 項目管理 > 選擇遊戲公司遊戲 > 遊戲詳細信息 > 基本信息**中的身份驗證密鑰。

請求參數

字段 类型 必需 描述
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)

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

請求範例

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

請求參數

    名稱 類型 必要性 (必要: M, 可選: O) 描述
    appid 字串 M 從 Hive 控制台 > 應用中心註冊和發佈的 ID
    market_id 數字 M 唯一市場ID(使用固定值 `15`)
    server_id 字串 M 發生支付的遊戲伺服器識別碼
    user_id_type 字串 M HIVE 用戶類型 player_id : 認證 v4 (v4)
    user_id 數字 M HIVE 用戶 ID 根據 user_id_type 發送 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
    ┕ 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 分析。如果您需要將 銷售日誌 與收據驗證請求一起發送,請使用 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 如果通過模擬器訪問 PC,例如 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 用戶類型 v4: 認證 v4 (player_id)
    user_id 數字 M 用戶 ID 如果 user_id_type 是 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_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 支付信息的加密哈希
    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

環境 URL
生產 URL https://store.withhive.com/external/api/refund_info
沙盒 URL 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)
* 如果设备项不存在,响应中将设置为 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,以進行身份驗證釋放流程。