PG 付款

以下是遊戲伺服器必須實現的PG支付API，以支持Windows OS遊戲中的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 用戶類型 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 分析。如果您需要在收據驗證請求中發送 銷售日誌，請使用 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 (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	當通過 PC 模擬器（如 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¶

生產網址	https://hiveiap.qpyou.cn/api_v4/item_result
沙盒網址	https://sandbox-hiveiap.qpyou.cn/api_v4/item_result
HTTP 方法	POST
內容類型	text/html
數據格式	JSON
授權	Bearer (token)

持有者令牌對應於在 Hive 控制台 App Center > 專案管理 > 選擇遊戲公司 > 遊戲詳情 > 基本資訊 中找到的 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	根據回應代碼的結果訊息

請求範例¶

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

回應範例¶

{
    "result": 0,
    "result_msg": "success"
}

付款結果通知服務¶

付款結果通知服務在付款完成或取消後立即將結果發送到遊戲伺服器。此 API 像獲取購買結果 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，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)
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..."
}