跳轉至

网络 PG 付款

網頁 PG 付款 API 在開發 Windows 應用程式時不使用 Hive SDK 付款,但當希望在網站上實現 PG 付款時使用的 API。網頁 PG 付款 API 與應用程式中實現 PG 付款的 API 不同。

Note

要在應用程式中實現 PG 付款,必須使用 Hive SDK 付款一般 PG 付款 API

商品列表查詢

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

請求 URL

環境 URL
正式 URL https://store.withhive.com/external/api/product
沙盒 URL https://sandbox-store.withhive.com/external/api/product
HTTP 方法 POST
內容類型 text/html; charset=utf-8
數據格式 JSON
授權 Bearer (令牌)

Bearer 令牌是 Hive 控制台 应用中心 > 项目管理 > 游戏公司选择 > 游戏详情 > 基本信息 中的 Hive 认证密钥。

請求參數

字段 类型 必需 描述
api 字符串 api 区分值 (`product` 固定值使用)
market_id 字符串 Hive 市场 ID (PG 付款: `15` 固定值使用)
appid 字符串 Hive Appid
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 字符串 商品分类 (消耗品: consumable)
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
內容類型 text/html; charset=utf-8
數據格式 JSON
授權 Bearer (令牌)

Bearer 令牌是 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\"}"}' \
    -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 (令牌)

Bearer 令牌是 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 Number M 回應代碼 (0: 成功)
    result_msg String M 根據回應代碼的結果訊息
    unconsumed_lists Object Array M
    ┕ market_pid String M 商品唯一 ID
    ┕ order_id String M 訂單號
    ┕ server_id String M 購買用戶所連接的遊戲伺服器區分代碼
    ┕ vid String M 購買用戶的 PlayerID,v1 認證的情況下為 VID
    ┕ uid String O 購買用戶的 uid
    ┕ amount String M 支付金額
    ┕ currency String M 支付貨幣
    ┕ quantity Number M 購買數量
    ┕ started_datetime Datetime M 開始支付的時間 (Y-m-d H:i:s)
    ┕ paid_datetime Datetime M 完成支付的時間 (Y-m-d H:i:s)
    ┕ hiveiap_receipt String M 支付信息加密 HASH
    ┕ purchase_bypass_info String M 驗證收據請求所需的必要信息
    ┕ additionalInfo String 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...",
            "additionalInfo": null
        }
    ]
}

付款信息验证

支付结果验证 API 基于 IAP v4 收据验证

支付结果验证是利用之前传递的 purchase_bypass_infopurchase_bypass_info 包含在支付进行之前通过 SDK 传递的各种信息,并将其发送到 Hive 分析。 如果在发送收据验证请求时需要 销售日志,请使用 game_info。 传递的 game_info 代替 Hive IAP 向分析服务器发送日志。

請求 URL

    商用 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 (令牌)

Bearer 令牌是 Hive 控制台 应用中心 > 项目管理 > 游戏公司选择 > 游戏详情 > 基本信息 中的 Hive 认证密钥。

請求參數

    名稱 類型 必填性 (必填: M, 選填: O) 說明
    purchase_bypass_info String M 收據替代及分析傳送用數據
    game_info Object Array O 當有遊戲日誌、銷售日誌等需要傳遞給遊戲的日誌時,將此值添加到遊戲中傳遞,Hive IAP將代為傳送至分析伺服器。在收據驗證階段,無法得知物品發放完成(itemsendok)的狀態,因此此部分需另行實現並提供附加信息。
    ⠀⠀server_uid bigint O 遊戲伺服器發放的 user_id 若無則為 0
    ⠀⠀giftee_uid bigint O null: 自己使用的付款 0: 有受贈者但無法確認 UID,Derby Days 客戶端帳號因為沒有 Hub 客戶端帳號而符合此條件
    ⠀⠀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 模擬器連接時輸入 "1",其他情況輸入 "0"

回應元素

    名稱 類型 必要性 (必要: M, 選項: O) 說明
    result 數字 M 回應代碼 (Response Code 參考)
    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 市場收據 Object 值 (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 (令牌)

Bearer 令牌对应于 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 用戶類型 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 項目名稱
    ⠀⠀quantity 數字 O 發放的項目數量

回應元素

    名稱 類型 必填性 (必填: M, 選填: O) 說明
    result Number M 回應代碼 (0: 成功)
    result_msg String 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 為 paid 時,才需要進行收據驗證和商品發放。

Note

要使用此 API,您需要先在 Hive 控制台中设置使用的 PG 公司。 为了进行收据验证和商品发放,建议仅使用此 API 或支付完成记录查询 API 之一。

付款結果傳送基本事項

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

付款結果傳送資訊

    名稱 類型 必填與否 (必填: M, 選填: O) 說明
    type String M 通知類型(paid: 付款完成, cancelled: 付款取消或退款)
    market_pid String M 商品唯一ID
    order_id String M 訂單號碼
    server_id String M 購買用戶所連接的遊戲伺服器區分碼
    vid Number M 購買用戶的PlayerID, v1認證的情況下為VID
    vid_type String O 根據SDK版本的vid類型值(默認v4)
    uid Number O 購買用戶的uid
    amount String M 付款金額
    currency String M 付款貨幣
    quantity Number M 購買數量
    started_datetime Datetime M 開始付款的時間 (Y-m-d H:i:s)
    paid_datetime Datetime M 完成付款的時間 (Y-m-d H:i:s)
    cancelled_datetime Datetime O 付款被取消或退款的時間 (Y-m-d H:i:s)
    cancelled_reason String O 付款被取消或退款的原因
    hiveiap_receipt String M 付款信息加密HASH
    purchase_bypass_info String M 收據驗證請求所需的必要信息
    additionalInfo String 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,
    "additionalInfo": null,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "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,    
    "additionalInfo": null,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "purchase_bypass_info": "eyJ0eXBlIjoiY2FuY2VsbGVkIiwibWFya2V0X2lkIjoiMT..."
}