PG 付款
以下是 Windows OS 遊戲中為了支持 PG 付款而需要在遊戲伺服器上實現的 PG 付款 API。 有關 Windows 環境中 PG 付款的詳細資訊，請查看以下。
查詢付款完成紀錄¶
支付完成时，支付代理商（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 | 數字 | 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) |
| ┕ hiveiap_receipt | 字串 | M | 付款信息加密 HASH |
| ┕ purchase_bypass_info | 字串 | M | 驗證收據請求所需的必要信息 |
| ┕ additionalInfo | 字串 | 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_info。 purchase_bypass_info 包含在支付进行之前通过 SDK 传递的各种信息，并会发送到 Hive 分析系统。 如果在发送收据验证请求时需要 销售日志，请使用 game_info。传递的 game_info 会在 Hive IAP 中代为发送日志到分析服务器。
請求網址¶
| 商用 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 | 字串 | M | 收據代用及分析傳送用數據 |
| game_info | 物件陣列 | 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 | 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 | 數字 | 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 为 paid 的情况下，才需要进行收据验证和商品发放。
Note
要使用此 API，您需要先在 [Hive 控制台中设置 PG 公司](../../../operation/billing/pg_mangement/#ftoc-heading-6)。
为了进行收据验证和商品发放，建议仅使用此 API 或支付完成记录查询 API 之一。
付款結果傳送基本事項¶
| HTTP 方法 | POST |
|---|---|
| 內容類型 | application/json |
| 數據格式 | JSON |
付款結果傳送資訊¶
| 名稱 | 類型 | 必填與否 (必填: M, 選填: O) | 說明 |
|---|---|---|---|
| type | 字串 | M | 通知類型(付費: 付款完成, 取消: 付款取消或退款) |
| market_pid | 字串 | M | 商品唯一 ID |
| order_id | 字串 | M | 訂單號碼 |
| server_id | 字串 | M | 購買用戶所連接的遊戲伺服器區分代碼 |
| vid | 數字 | M | 購買用戶的 PlayerID，v1 認證的情況下為 VID |
| 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) |
| cancelled_reason | 字串 | O | 付款取消或退款的原因 |
| hiveiap_receipt | 字串 | M | 付款信息加密 HASH |
| purchase_bypass_info | 字串 | M | 收據驗證請求所需的必要信息 |
| additionalInfo | 字串 | 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..."
}