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) |
Bearer令牌对应于在Hive控制台中找到的Hive身份验证密钥,路径为_App Center > 项目管理 > 选择游戏公司 > 游戏详情 > 基本信息_。
请求参数¶
名称 | 类型 | 必需 (必需: 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) |
Bearer令牌对应于在Hive控制台 _App Center > 项目管理 > 选择游戏公司 > 游戏详情 > 基本信息_中找到的Hive身份验证密钥。
请求参数¶
名称 | 类型 | 必需 (必需: M, 可选: O) | 描述 |
---|---|---|---|
purchase_bypass_info | 字符串 | M | 用于收据替代和分析传输的数据 |
game_info | 对象数组 | O | 当有日志需要发送到游戏时,例如游戏日志或收入日志,应添加此值并发送到游戏,允许 Hive IAP 作为中介发送到分析服务器。在收据验证阶段,无法知道物品是否已发送 (itemsendok),因此此部分必须单独实现并提供作为附加信息。 |
⠀⠀server_uid | bigint | O | 游戏服务器发放的用户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¶
生产 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) |
Bearer令牌对应于在Hive控制台中找到的Hive身份验证密钥,路径为_App Center > 项目管理 > 选择游戏公司 > 游戏详情 > 基本信息_。
请求参数¶
名称 | 类型 | 必需 (必需: 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
值,就像获取购买结果 API一样,允许游戏使用此值验证收据,然后将产品授予用户。只有在支付结果传输信息中的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 | 购买用户的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) |
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..."
}