PG 支付

以下是游戏服务器必须实现的PG支付API，以支持Windows操作系统游戏中的PG支付。有关Windows环境中PG支付的更多详细信息，请查看这里。

付款完成历史查询¶

在支付完成后，支付机构（PG）直接将支付结果传递给Hive IAP v4服务器。这种方法弥补了网络的不稳定性，并防止了支付数据的篡改。通过将支付信息与支付机构（PG）提供的信息进行比较，进行交叉验证，比较的是在准备工作期间注册的支付信息。一旦确认支付信息的完整性，将采取额外的安全措施，并存储支付信息。存储的支付信息可以通过支付完成历史查询API检索。当客户端需要用户的支付完成信息时，它会向游戏服务器请求信息，游戏服务器通过Hive IAP v4服务器检索支付信息。如果用户的支付历史存在，则使用purchase_bypass_info进行支付信息验证。

请求 URL¶

商业网址	https://hiveiap.qpyou.cn/api_v4/purchases/unconsumed
沙盒网址	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	购买用户的玩家ID
┕ uid	字符串	O	Hive 购买用户的会员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)
┕ 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: 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,
            "price_type": "none",
            "gameserver_price_verify_key": null
        }
    ]
}

支付信息验证¶

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

支付结果验证使用之前收到的 purchase_bypass_info。purchase_bypass_info 包含在进行支付之前通过 SDK 接收到的各种信息，并发送到 Hive Analytics。如果您需要在收据验证请求中发送 销售日志，请使用 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 控制台 应用中心 > 项目管理 > 选择游戏公司 > 游戏详情 > 基本信息 中找到的 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
⠀⠀level	int	O	用户的游戏内等级如果没有等级，则不必要。如果没有，则为 0。
⠀⠀character_id	bigint	O	服务器内唯一的角色标识符值如果没有角色概念，则为 "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: 正常支付)
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: 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",
    "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
内容类型	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 用户类型（固定值 `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	根据响应代码的结果消息

请求示例¶

Call

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: 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 为已支付时，收据验证和物品授予才能继续。

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	购买用户的uid
vid_type	字符串	O	SDK版本值: v4
server_id	字符串	M	购买用户连接的游戏服务器区分代码
appid	字符串	M	Hive应用
amount	字符串	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	付款取消或退款的原因
currency	字符串	M	付款货币
quantity	字符串	M	购买数量
hiveiap_receipt	字符串	M	付款信息加密HASH
started_datetime_ms	数字	M	付款开始时间 (Unix时间戳毫秒)
paid_datetime_ms	数字	M	付款完成时间 (Unix时间戳毫秒)
cancelled_datetime_ms	数字	O	付款取消或退款时间 (Unix时间戳毫秒)
iap_payload	字符串	O	从客户端接收的附加信息，将发送到游戏服务器。格式为JSON字符串，如果没有接收到信息，则返回null。
purchase_bypass_info	字符串	M	收据验证请求所需的必要信息
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": "Test payment cancellation",
    "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
}