网络 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_info
。 purchase_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
回應範例¶
付款結果通知服務¶
付款結果通知服務在付款完成或取消時立即將結果發送到遊戲伺服器。此 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,以進行身份驗證釋放流程。