PG 支付
以下是 Windows 操作系统游戏中，为支持 PG 付款而需要在游戏服务器上实现的 PG 付款 API。有关 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 (令牌) |
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¶
| 商用 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 | 市场收据对象值 (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 | 数字 | 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 | 通知类型（paid: 支付完成，cancelled: 支付取消或退款） |
| 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..."
}