PG 付款
以下是遊戲伺服器必須實現的PG支付API,以支持Windows操作系統遊戲中的PG支付。 有關Windows環境中PG支付的更多詳細信息,請查看以下內容。
付款完成歷史查詢¶
當付款完成後,付款閘道(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_info
。purchase_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 控制台 App Center > 項目管理 > 選擇遊戲公司 > 遊戲詳細資訊 > 基本資訊 中找到的 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 | 當通過像 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: 正常付款) |
回應代碼¶
代碼 | 訊息 | 註解 |
---|---|---|
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 控制台 應用中心 > 項目管理 > 選擇遊戲公司 > 遊戲詳情 > 基本信息 中找到的 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 為 v4,請發送 player_id |
asset | 物件陣列 | O | 有關交付項目的信息 只有在交付成功時提供值,交付失敗時回應空陣列 ([]) |
⠀⠀asset_id | 字串 | O | 項目 ID |
⠀⠀asset_name | 字串 | O | 項目名稱 |
⠀⠀quantity | 數字 | O | 交付的項目數量 |
回應元素¶
名稱 | 類型 | 必需 (必需: M, 可選: O) | 描述 |
---|---|---|---|
result | 數字 | M | 回應代碼 (0: 成功) |
result_msg | 字串 | M | 根據回應代碼的結果訊息 |
請求範例¶
- Call
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
值,就像获取购买结果 API一样,允许游戏使用此值验证收据,然后将产品授予用户。只有在支付结果传输信息中的type
为已支付时,收据验证和产品授予才应继续进行。
Note
要使用此 API,您必須先在 Hive 控制台中設置 PG 公司。 為了驗證收據和產品交付,建議使用此 API 或支付完成歷史查詢 API。
有關支付結果傳輸的基本信息¶
HTTP 方法 | POST |
---|---|
內容類型 | application/json |
數據格式 | JSON |
付款結果傳輸資訊¶
名稱 | 類型 | 是否必填 (必填: M, 選填: O) | 描述 |
---|---|---|---|
類型 | 字串 | M | 通知類型 (paid: 付款完成, cancelled: 付款取消或退款) |
市場產品ID | 字串 | M | 唯一產品ID |
訂單編號 | 字串 | M | 訂單號碼 |
伺服器ID | 字串 | M | 區分購買用戶訪問的遊戲伺服器的代碼 |
玩家ID | 字串 | M | 購買用戶的玩家ID |
vid類型 | 字串 | O | 根據SDK版本的vid類型值 (默認v4) |
uid | 字串 | O | 購買用戶的uid |
金額 | 字串 | M | 付款金額 |
貨幣 | 字串 | M | 付款貨幣 |
數量 | 數字 | M | 購買數量 |
開始時間 | 日期時間 | M | 付款開始時間 (Y-m-d H:i:s) |
付款時間 | 日期時間 | M | 付款完成時間 (Y-m-d H:i:s) |
取消時間 | 日期時間 | O | 付款取消或退款時間 (Y-m-d H:i:s) |
開始時間毫秒 | 數字 | M | 付款開始時間 (Unix時間戳毫秒) |
付款時間毫秒 | 數字 | M | 付款完成時間 (Unix時間戳毫秒) |
取消時間毫秒 | 數字 | O | 付款取消或退款時間 (Unix時間戳毫秒) |
取消原因 | 字串 | O | 付款取消或退款的原因 |
hiveiap收據 | 字串 | M | 付款信息的加密HASH |
購買繞過信息 | 字串 | M | 收據驗證請求所需的信息 |
iap有效負載 | 字串 | 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..."
}