Web PG 付款

網頁 PG 付款 API 是在網站上實作 PG 付款時使用的 API，雖然在開發 Windows 應用程式時不使用 Hive SDK 付款。網頁 PG 付款 API 與在應用程式中實作 PG 付款的 API 不同。

Note

若要在應用程式中實作 PG 付款，必須使用 Hive SDK 付款 與 一般 PG 付款 API。

產品列表檢索

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

請求 URL

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

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

請求參數

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

回應元素

字段	类型	是否必填	描述
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: application/json" \
    -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 信息請求產品訂單。

自訂金額付款

自訂金額支付是一項功能，允許您請求以遊戲伺服器指定的金額（custom_price）而不是產品PID中設定的金額進行支付。

如果您想在您的遊戲中對產品應用優惠券、積分、活動折扣等，遊戲伺服器必須在應用所有折扣後計算最終付款金額，並使用該金額作為 custom_price 值調用 API。如果未提供 custom_price 值，則付款將按照產品 PID 中設置的金額進行。

請求 URL

環境	網址
生產網址	https://store.withhive.com/external/api/order
沙盒網址	https://sandbox-store.withhive.com/external/api/order
HTTP 方法	POST
內容類型	application/json; 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	應用程式開發商定義的 [購買中繼資訊](../../../dev/billing/iapv4-purchase.md#iap-payload)
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 页面。
from_url	字符串	X	网络商店域名 URL
close_redirect_url	字符串	X	当点击 PG 支付完成弹出窗口关闭按钮时重定向的 URL
fixed_currency	字符串	X	支付方式曝光的货币（ISO 4217 三个字母） * 常规支付不需要。如果未提供 `fixed_currency` 参数，则根据 `hive_country` 曝光支付方式。如果添加了 `fixed_currency` 参数，则根据 `fixed_currency` 货币曝光支付方式。 * 使用自定义金额支付功能时必需，因为价格信息是固定的。
gameserver_price_verify_key	字符串	X	游戏服务器支付金额验证密钥 * 游戏服务器生成验证密钥，存储与生成的验证密钥匹配的货币和价格信息，并需要实现如果从收据验证 API 响应的支付价格和货币信息不同，则不授予该物品。 * 使用自定义金额支付功能时必需。
custom_price	字串	X	自訂金額 * 當要求支付的金額由遊戲伺服器指定，而不是PID中設定的金額時使用。
折扣券	字串	X	百分比折扣券代碼 * 使用百分比折扣券時必須提供。 * 只能使用從Hive控制台發出的百分比折扣券。支付完成後，券的狀態將變為已使用。

Note

使用百分比折扣優惠券時，您必須在請求付款前使用百分比折扣優惠券驗證 API，確認在 Hive 控制台發行的百分比折扣優惠券是否有效。

要使“关闭 PG 付款完成弹出窗口”按钮正常工作，您需要将以下脚本添加到 PG 付款调用页面。

window.addEventListener('message', function(event) {
    const data = event.data;

    if (data?.type === 'REFRESH_PARENT') {
        if (typeof data.url === 'string' && data.url.trim() !== '') {
            window.location.href = data.url;
        } else {
            window.location.reload();
        }
    }
});

請求範例

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: application/json" \
    -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 認證金鑰，該金鑰位於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	收據驗證請求所需的必要資訊。 此值在呼叫收據驗證 API 時，必須以原樣作為輸入值使用。建議勿用於其他用途。不建議在應用程式用戶端或應用程式伺服器端直接剖析或變更此值。
┕ iap_payload	字符串	O	從客戶端接收的額外信息以發送到遊戲服務器 (以 JSON 字符串格式) (如果未接收到信息，則返回 null)
┕ price_type	字符串	O	價格類型 (none: 不使用, custom_price: 自定義金額支付)
┕ gameserver_price_verify_key	字符串	O	遊戲服務器付款金額驗證密鑰

請求範例

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: application/json" \
 -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,
            "price_type": "none",
            "gameserver_price_verify_key": null
        }
    ]
}

付款信息验证

支付結果驗證 API 以 IAP v4 收據驗證 為基礎。

付款結果驗證使用先前接收的 purchase_bypass_info。purchase_bypass_info 包含在付款前透過 SDK 接收的各種資訊，並傳送至 Hive Analytics。若需在收據驗證請求中一併傳送 銷售日誌，請使用 game_info。收到的 game_info 會由 IAP 代為將日誌傳送至分析伺服器。

請求 URL

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

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

請求參數

名稱	類型	必填 (必填: M, 選填: O)	描述
purchase_bypass_info	字串	M	收據替代與分析傳輸用資料 此值必須原樣使用。不建議在應用程式用戶端或應用程式伺服器端直接剖析或變更此值。
game_info	物件陣列	O	當有要傳送至遊戲的日誌（例如遊戲日誌、銷售日誌）時，將此值附加到遊戲並傳遞後，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`。
hiveiap_account_uuid_compare	數字	O	表示傳遞至收據驗證 API 的帳號資訊，是否與進行收據驗證時登入的 Hive 帳號資訊一致。相同的市場帳號可能對應多個 Hive 帳號。(1: 一致, 2: 不一致, 9: 不支援)
hiveiap_price	字符串	O	付款金額。使用 PG 自定義金額付款時，為了防止濫用，您 **必須** 驗證自定義付款金額和實際訂單金額在遊戲伺服器上使用驗證密鑰 (`gameserver_price_verify_key`) 是否相同。
hiveiap_currency	字符串	O	付款貨幣。使用 PG 自定義金額付款時，為了防止濫用，您 **必須** 驗證自定義付款金額和實際訂單付款金額的付款貨幣在遊戲伺服器上使用驗證密鑰 (`gameserver_price_verify_key`) 是否相同。
gameserver_price_verify_key	字符串	O	遊戲伺服器付款金額驗證密鑰。使用 PG 自定義金額付款時，為了防止濫用，您必須使用此密鑰在遊戲伺服器上比較和驗證金額和貨幣信息。

回應代碼

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

請求範例

curl -L -v \
 -d '{"purchase_bypass_info":"eyJtYXJrZXRfaWQiOiIxNSIsIm9yZGVyX2lkIjoiSDMxNjQ3OTI1NDI4OTA3MzE4NTAiLCJtYXJrZXRfcGlkIjoiY29tLmNvbTJ1cy5oaXZlc2RrLndpbmRvd3MubWljcm9zb2Z0c3RvcmUuZ2xvYmFsLm5vcm1hbC5pdGVtMDEiLCJ2aWQiOiIzMDAwMDA1Njk5NiIsInVpZCI6IjEzMDc5Iiwic2VydmVyX2lkIjoia3IiLCJhcHBpZCI6ImNvbS5jb20ydXMuaGl2ZXNkay53aW5kb3dzLm1pY3Jvc29mdHN0b3JlLmdsb2JhbC5ub3JtYWwiLCJhbW91bnQiOiIxMjAwIiwic3RhcnRlZF9kYXRldGltZSI6bnVsbCwicGFpZF9kYXRldGltZSI6bnVsbCwiY3VycmVuY3kiOiJLUlciLCJoaXZlaWFwX3JlY2VpcHQiOiIyWW5HemZUQ0d5Y29NamNTeVl5TlhCakFOd21GeUI2bVwvYzBiWWF6UThWUT0ifQ=="}' \
 -H "Content-Type: application/json" \
 -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,
    "hiveiap_account_uuid_compare": 9,
    "hiveiap_price": "1200",
    "hiveiap_currency": "KRW",
    "gameserver_price_verify_key": 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
內容類型	application/json
數據格式	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	項目名稱
quantity	整數	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: application/json" \
 -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 為 paid 時，才應進行收據驗證與商品發放。

Note

若要使用此 API，請先在 Hive 控制台設定要使用的 PG 公司。 建議使用此 API 或付款完成歷史查詢 API 進行收據驗證和產品交付。

有關支付結果傳輸的基本信息

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

付款結果傳輸資訊

名稱	類型	必需 (必需: M, 可選: O)	描述
type	字串	M	通知類型 (paid: 付款完成, cancelled: 付款取消或退款)
market_id	字串	M	Hive市場ID
order_id	字串	M	訂單號碼
market_pid	字串	M	產品唯一ID
vid	字串	M	購買用戶的PlayerID
uid	字串	O	購買用戶的Hive會員UID
vid_type	字串	O	SDK版本 (預設v4)
server_id	字串	M	區分購買用戶訪問的遊戲伺服器的代碼
appid	字串	M	Hive Appid
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	收據驗證請求所需的必要資訊。 此值在呼叫收據驗證 API 時，必須以原樣作為輸入值使用。建議勿用於其他用途。不建議在應用程式用戶端或應用程式伺服器端直接剖析或變更此值。
iap_payload	字符串	O	從客戶端接收到的附加信息，將發送到遊戲服務器。它是JSON字符串格式，如果未收到任何信息，則返回null。
price_type	字符串	O	價格類型（none：不使用，custom_price：自定義金額支付）
gameserver_price_verify_key	字符串	O	遊戲服務器支付金額驗證密鑰

付款結果傳輸範例（付款完成後）

{
    "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...",
    "price_type": "none",
    "gameserver_price_verify_key": null
}

付款結果傳輸範例（在付款取消的情況下）

{
    "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...",
    "price_type": "none",
    "gameserver_price_verify_key": null
}

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

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

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

• 來自玩家ID查詢API的is_refund回應項目僅在其為真時可使用。
• 當請求重新付款的情況時，請求參數json必須包含refund_idx(Integer)和is_repayment(Integer)作為必填項目。
• 當重新支付自訂金額的付款情況時，您必須在發送付款請求時為custom_price和gameserver_price_verify_key字段設置值。在這種情況下，將gameserver_price_verify_key字段設置為refund。
• 當發送重新付款請求時，將server_id字段設置為refund。

請求 URL

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

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

請求參數

欄位	類型	必填	描述
appid	字串	O	Hive Appid
vid_type	字串	O	帳戶類型 ("v4")
vid	字串	O	Hive 帳戶資訊 (玩家 ID)
game_language	字串	O	語言 (ISO 639-1 兩個字母)
device	字串	X	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	整数	否	产品购买数量
refund_list > price	字符串	否	支付金额 * 用于自定义金额支付
refund_list > currency	字符串	否	支付货币 * 用于自定义金额支付
refund_list > display_price	字符串	否	显示的支付金额 * 用于自定义金额支付

請求範例

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: application/json" \
    -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,
      "price": "1200",
      "currency": "KRW",
      "display_price": "₩1,200"
    }
  ]
}

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

Warning

用户必须实现一个“刷新”按钮，以便在完成重新购买的付款后更新重新购买项目的列表。 在完成重新购买的付款后，必须重新调用“退款用户重新购买目标退款历史查询”API，以继续进行身份验证释放流程。