跳转至

Web PG 支付

网页 PG 付款 API 在开发 Windows 应用时虽然不使用 Hive SDK 计费,但当希望在网站上实现 PG 付款时使用的 API。网页 PG 付款 API 与应用中实现 PG 付款的 API 不同。

Note

要在应用程序中实现PG支付,必须使用Hive SDK计费普通PG支付API

商品列表查询

获取商品信息。用于在应用中实现商品列表。

请求 URL

环境 URL
生产 URL https://store.withhive.com/external/api/product
沙盒 URL https://sandbox-store.withhive.com/external/api/product
HTTP 方法 POST
内容类型 text/html; charset=utf-8
数据格式 JSON
授权 Bearer (令牌)

Bearer令牌对应Hive控制台应用中心 > 项目管理 > 游戏公司选择 > 游戏详情 > 基本信息中的Hive认证密钥。

请求参数

字段 类型 必需 描述
api 字符串 api 区分值 (`product` 固定值使用)
market_id 字符串 Hive 市场 ID (PG 支付: `15` 固定值使用)
appid 字符串 Hive Appid
hive_country 字符串 国家代码(ISO 3166-1 两位)
game_language 字符串 语言(ISO 639-1 两位)
vid 字符串 Hive 账户信息(玩家 ID)
vid_type 字符串 账户类型(新游戏的情况下为 v4)
market_pid_type 字符串 商品类型(消耗品: consumable)

响应元素

字段 类型 必需 描述
result 整数 响应代码 (0表示成功,其他表示错误)
result_msg 字符串 响应消息
product_list 对象 商品信息列表
product_list > market_pid 字符串 商品PID
product_list > price 整数 商品价格 (数字值)
product_list > currency 字符串 商品价格货币
product_list > display_price 字符串 商品价格 (包含货币符号)
product_list > title 字符串 商品名称
product_list > description 字符串 商品描述
product_list > product_type 字符串 商品分类 (消耗品: consumable)
update_date 字符串 商品PID信息最后更新时间

请求示例

curl -L -v \
    -d '{"api": "product","market_id": 15,"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal","hive_country": "KR","game_language": "ko","vid": "100000000000","vid_type": "v4","market_pid_type": "consumable"}' \
    -H "Content-Type: text/html" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
    https://sandbox-store.withhive.com/external/api/product

响应示例

{
    "result": 0,
    "result_msg": "success",
    "product_list": [
        {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
            "price": 1200,
            "currency": "KRW",
            "display_price": "₩1,200",
            "title": "크리스탈 한 줌",
            "description": "크리스탈 한 줌",
            "product_type": "consumable"
        }, {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item02",
            "price": 2500,
            "currency": "KRW",
            "display_price": "₩2,500",
            "title": "크리스탈 묶음",
            "description": "크리스탈 묶음",
            "product_type": "consumable"
        }, {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item03",
            "price": 3900,
            "currency": "KRW",
            "display_price": "₩3,900",
            "title": "크리스탈 더미",
            "description": "크리스탈 더미",
            "product_type": "consumable"
        }
    ],
    "update_date": "2022-10-28 16:11:23"
}

商品订单请求

根据从商品列表中选择的 PID(商品 ID)信息请求商品订单。

请求 URL

环境 URL
生产 URL https://store.withhive.com/external/api/order
沙盒 URL https://sandbox-store.withhive.com/external/api/order
HTTP 方法 POST
内容类型 text/html; charset=utf-8
数据格式 JSON
授权 Bearer (令牌)

Bearer令牌对应于Hive控制台应用中心 > 项目管理 > 游戏公司选择 > 游戏详情 > 基本信息中的Hive认证密钥。

请求参数

字段 类型 必需 描述
market_id 字符串 Hive市场ID
appid 字符串 Hive Appid
hive_country 字符串 国家代码(ISO 3166-1 两位)
game_language 字符串 语言(ISO 639-1 两位)
vid 字符串 Hive账户信息(玩家ID)
vid_type 字符串 账户类型(新游戏的情况下为v4)
market_pid 字符串 商品PID
server_id 字符串 服务器ID
os 字符串 Windows: W, MAC: M, Android: A
quantity 整数 购买数量(未发送时默认值为1)
iap_payload 字符串 由应用开发者定义的 购买元信息

请求示例

curl -L -v \
    -d '{"market_id": 15,"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal","hive_country": "KR","game_language": "ko","vid": "100000000000","vid_type": "v4","market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01","server_id": "KR1","os": "A","quantity": 1,"iap_payload": "{\"character_id\":\"hivesdk01\"}"}' \
    -H "Content-Type: text/html" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
    https://sandbox-store.withhive.com/external/api/order

响应示例

当商品订单请求正常处理时,将返回一个选择支付方式的弹出窗口。返回构成以下弹出窗口的 HTML 页面。

查询支付完成记录

支付完成后,支付代理(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_infopurchase_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 String M 用于收据替代和分析传输的数据
    game_info Object Array 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 (令牌)

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

响应示例

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

付款结果通知服务

付款结果通知服务会在付款完成或付款取消发生时立即将该结果发送到游戏服务器。此 API 传递与 付款完成记录查询 相同的 purchase_bypass_info 值,因此游戏可以使用该值验证收据,然后向用户发放商品。只有在 付款结果传输信息type 为 paid 的情况下,才需要进行收据验证和商品发放。

Note

要使用此 API,您必须首先在Hive 控制台中设置 PG 公司。 为了进行收据验证和商品发放,建议仅使用此 API 或支付完成记录查询 API 之一。

付款结果发送基本事项

    HTTP 方法 POST
    内容类型 application/json
    数据格式 JSON

付款结果传送信息

    名称 类型 是否必需 (必需: M, 选项: O) 说明
    type String M 通知类型(paid: 付款完成, cancelled: 付款取消或退款)
    market_pid String M 商品唯一ID
    order_id String M 订单号
    server_id String M 购买用户连接的游戏服务器区分代码
    vid Number M 购买用户的PlayerID, v1认证的情况下为VID
    vid_type String O 根据SDK版本的vid类型值(默认v4)
    uid Number O 购买用户的uid
    amount String M 付款金额
    currency String M 付款货币
    quantity Number M 购买数量
    started_datetime Datetime M 开始付款的时间 (Y-m-d H:i:s)
    paid_datetime Datetime M 完成付款的时间 (Y-m-d H:i:s)
    cancelled_datetime Datetime O 付款取消或退款的时间 (Y-m-d H:i:s)
    cancelled_reason String O 付款取消或退款的原因
    hiveiap_receipt String M 付款信息加密HASH
    purchase_bypass_info String M 收据验证请求所需的必需信息
    additionalInfo String 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..."
}