Web PG 支付

Web PG支付 API 是在开发 Windows 应用程序时不使用 Hive SDK 计费，而在网站上实现 PG 支付时使用的 API。Web PG支付 API 与在应用程序中实现 PG 支付的 API 不同。

Note

要在应用中实现 PG 支付，您需要使用 Hive SDK 计费 和 通用 PG 支付 API。

产品列表检索

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

请求 URL

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

持有者令牌对应于在Hive控制台的应用中心 > 项目管理 > 选择游戏公司 > 游戏详情 > 基本信息中找到的Hive身份验证密钥。

请求参数

字段	类型	必需	描述
api	字符串	是	API标识符值（使用固定值`product`）
market_id	字符串	是	Hive 市场ID（PG支付：使用固定值`15`）
appid	字符串	是	Hive 应用ID
hive_country	字符串	是	国家代码（ISO 3166-1 两个字母）
game_language	字符串	是	语言（ISO 639-1 两个字母）
vid	字符串	是	Hive 账户信息（玩家ID）
vid_type	字符串	是	账户类型（v4）
market_pid_type	字符串	是	产品类型（消耗品）

响应元素

字段	类型	必需	描述
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	字符串	是	产品分类（消耗品）
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: application/json" \
    -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 信息请求产品订单。

自定义金额支付

自定义金额支付是一个功能，允许您请求支付由游戏服务器指定的金额（custom_price），而不是产品PID中设置的金额。

如果您想在游戏中对产品应用优惠券、积分、活动折扣等，游戏服务器必须在应用所有折扣后计算最终支付金额，并使用该金额作为 custom_price 值调用 API。如果未提供 custom_price 值，则支付将按产品 PID 中设置的金额进行。

请求 URL

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

持有者令牌对应于在应用中心 > 项目管理 > 选择游戏公司 > 游戏详情 > 基本信息中找到的Hive身份验证密钥，该密钥位于Hive控制台中。

请求参数

字段	类型	必需	描述
market_id	字符串	O	Hive 市场 ID
appid	字符串	O	Hive Appid
hive_country	字符串	O	国家代码（ISO 3166-1 两个字母）
game_language	字符串	O	语言（ISO 639-1 两个字母）
vid	字符串	O	Hive 账户信息（玩家 ID）
vid_type	字符串	O	账户类型（v4）
market_pid	字符串	O	产品 PID
server_id	字符串	O	服务器 ID
os	字符串	O	Windows: W, MAC: M, Android: A
quantity	整数	X	购买数量（如果未发送，默认值为 1）
iap_payload	字符串	X	由应用开发者定义的[购买元信息](../../../dev/billing/iapv4-purchase.md#iap-payload)
fixed_currency	字符串	X	支付方式曝光的货币（ISO 4217 三个字母） * 如果未提供 fixed_currency 参数，则根据 hive_country 曝光支付方式，但如果添加 fixed_currency 参数，则根据 fixed_currency 货币曝光支付方式。
refund_idx	整数	X	退款用户重新支付列表 IDX * 仅在退款用户重新支付请求时必需
is_repayment	整数	X	是否为退款用户重新支付（0：正常支付，1：退款用户重新支付） * 仅在退款用户重新支付请求时必需
expiration_time	整数	X	这是支付窗口的过期时间。它以 Unix 时间戳毫秒格式表示（例如，1745395211）。如果 Hive 计费服务器的当前时间（Unix 时间戳毫秒）超过此值，则将返回不同的指导页面，而不是响应中的支付窗口 HTML 页面。
from_url	字符串	X	网络商店域名 URL
close_redirect_url	字符串	X	当 PG 支付完成弹出窗口关闭按钮被点击时的重定向 URL
fixed_currency	字符串	X	支付方式曝光的货币（ISO 4217 三个字母） * 对于常规支付不是必需的。如果 `fixed_currency` 参数不存在，则根据 `hive_country` 曝光支付方式。如果添加 `fixed_currency` 参数，则根据 `fixed_currency` 货币曝光支付方式。 * 在使用自定义金额支付功能时必需，因为价格信息是固定的。
gameserver_price_verify_key	字符串	X	游戏服务器支付金额验证密钥 * 游戏服务器生成验证密钥，存储与生成的验证密钥匹配的货币和价格信息，并需要实现，如果从收据验证 API 响应的支付价格和货币信息不同，则不授予该物品。 * 在使用自定义金额支付功能时必需。
custom_price	字符串	X	自定义金额 * 当请求的金额由游戏服务器指定而不是PID中设置的金额时使用。
折扣券	字符串	X	百分比折扣券代码 * 使用百分比折扣券时必需。 * 仅可使用从Hive控制台发放的百分比折扣券。支付完成后，优惠券状态变为已使用。

Note

使用百分比折扣优惠券时，您必须在请求支付前，通过百分比折扣优惠券验证 API验证 Hive 控制台发放的百分比折扣优惠券是否有效。

要使“关闭 PG 支付完成弹出窗口”按钮正常工作，您需要将以下脚本添加到 PG 支付调用页面。

window.addEventListener('message', function(event) {
    const data = event.data;

    if (data?.type === 'REFRESH_PARENT') {
        if (typeof data.url === 'string' && data.url.trim() !== '') {
            window.location.href = data.url;
        } else {
            window.location.reload();
        }
    }
});

请求示例

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\"}", "expiration_time": 1745395211}' \
    -H "Content-Type: application/json" \
    -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 (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
┕ 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	收据验证请求所需的必填信息。 调用收据验证 API 时，必须将该值按原样作为输入值使用。建议不要用于其他用途。不建议在应用客户端或应用服务器中直接解析或修改该值。
┕ 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: application/json" \
 -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 传递的各类信息，并会发送到 Analytics。如需在收据验证请求中一并发送销售日志，请使用game_info。传递的game_info会由 IAP 代为将日志发送到分析服务器。

请求 URL

生产 URL	https://hiveiap-verify.qpyou.cn/api_v4/verify
沙盒 URL	https://sandbox-hiveiap-verify.qpyou.cn/api_v4/verify
HTTP 方法	POST
内容类型	application/json
数据格式	JSON
授权	Bearer (token)

Bearer令牌对应于在应用中心 > 项目管理 > 选择游戏公司 > 游戏详情 > 基本信息中找到的Hive身份验证密钥，该密钥位于Hive控制台中。

请求参数

名称	类型	必需 (必需: M, 可选: O)	描述
purchase_bypass_info	字符串	M	用于代替收据及发送分析日志的数据 该值必须按原样使用。不建议在应用客户端或应用服务器中直接解析或修改该值。
game_info	对象数组	O	当有需要传递给游戏的日志（如游戏日志、销售日志）时，将此值附加到游戏并传递后，IAP 会将日志发送到分析服务器。在收据验证阶段无法确认道具发放完成（itemsendok）与否，因此该部分需要另行实现并作为附加信息提供。
⠀⠀server_uid	bigint	O	游戏服务器发放的用户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	通过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: 正常支付)
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: application/json" \
 -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
内容类型	application/json
数据格式	JSON
授权	Bearer (token)

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 用户类型（使用固定值 `player_id`）
user_id	整数	M	Hive 用户ID（`player_id`）
asset	对象数组	O	关于授予物品的信息 仅在授予成功时提供值，授予失败时响应空数组 ([])
asset_id	字符串	O	物品ID
asset_name	字符串	O	物品名称
数量	整数	O	授予物品的数量

响应元素

名称	类型	必需 (必需: M, 可选: O)	描述
result	整数	M	响应代码 (0: 成功)
result_msg	字符串	M	根据响应代码的结果消息

请求示例

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: application/json" \
 -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	字符串	M	通知类型（paid: 支付完成，cancelled: 支付取消或退款）
market_id	字符串	M	Hive市场ID
order_id	字符串	M	订单号
market_pid	字符串	M	产品唯一ID
vid	字符串	M	购买用户的PlayerID
uid	字符串	O	购买用户的Hive会员UID
vid_type	字符串	O	SDK版本（默认v4）
server_id	字符串	M	区分购买用户访问的游戏服务器的代码
appid	字符串	M	Hive Appid
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	收据验证请求所需的必填信息。 调用收据验证 API 时，必须将该值按原样作为输入值使用。建议不要用于其他用途。不建议在应用客户端或应用服务器中直接解析或修改该值。
iap_payload	字符串	O	从客户端接收的附加信息，将发送到游戏服务器。它是JSON字符串格式，如果没有接收到信息，则返回null。
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": "테스트 결제 취소",
    "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
}

退款用户重新支付目标退款历史查询 API

此API用于检索已请求退款并需要重新付款的用户的退款历史。
如果您在自建的网上商店中为退款用户启用了重新付款功能，则应使用“退款用户重新付款目标退款历史查询”API的响应值，为退款用户实现重新付款通知弹出窗口UI。

在使用“退款用户重新支付目标退款历史查询”API时，请注意以下事项。

• 从PlayerID查找API返回的is_refund响应项只能在其为true时使用。
• 在请求重新付款的情况下，请求参数json必须包含refund_idx(Integer)和is_repayment(Integer)作为必填项。
• 在重新支付自定义金额的付款情况下，您必须在发起付款请求时为custom_price和gameserver_price_verify_key字段设置值。在这种情况下，将gameserver_price_verify_key字段设置为refund。
• 在发起重新付款请求时，将server_id字段设置为refund。

请求 URL

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

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

请求参数

字段	类型	必需	描述
appid	字符串	是	Hive Appid
vid_type	字符串	是	账户类型 ("v4")
vid	字符串	是	Hive 账户信息 (玩家ID)
game_language	字符串	是	语言 (ISO 639-1 两个字母)
device	字符串	否	PC、移动区分 (pc, mobile) * 如果设备项不存在，响应中将设置为移动

响应元素

字段	类型	必需	描述
result	整数	是	响应代码（0表示成功，其他任何值表示错误）
result_msg	字符串	是	响应消息
guide_title	字符串	是	指南标题
guide_content	字符串	是	指南内容
customer_site	对象	是	客服地址
customer_site > pc	字符串	是	PC客服地址
customer_site > mobile	字符串	是	移动客服地址
refund_list	数组 > 对象	是	退款重付款列表
refund_list > refund_idx	整数	否	重付款索引ID
refund_list > market_id	整数	否	Hive 市场ID
refund_list > market_pid	字符串	否	产品PID
refund_list > refund_time	字符串	否	退款日期和时间
refund_list > refund_time_ms	整数	否	退款日期和时间（Unix时间戳毫秒）
refund_list > quantity	整数	否	产品购买数量
refund_list > price	字符串	否	支付金额 * 用于自定义金额支付
refund_list > currency	字符串	否	支付货币 * 用于自定义金额支付
refund_list > display_price	字符串	否	显示的支付金额 * 用于自定义金额支付

请求示例

curl -L -v \
    -d '{"appid":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal","vid_type":"v4","vid":"20000015900","game_language":"ko","device":"pc"}' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
    https://sandbox-store.withhive.com/external/api/refund_info

响应示例

{
  "result": 0,
  "result_msg": "success",
  "guide_title": "환불 상품 재결제 안내",
  "guide_content": "고객님의 계정은 게임 서비스 약관 및 운영 정책 위반 행위(결제시스템 악용)가 확인되어, 
    게임 이용이 제한되었습니다.\n\n알 수없는 이유로 결제가 취소되었거나, 혹은 비정상적인 절차로 환불된 상품의 경우, 동일 상품 재결제 후 게임 이용이 가능합니다.\n\n 현재 접속한 단말OS의 마켓 상품만 재결제가 가능하오니, 다른 마켓은 해당 앱으로 접속하여 재결제 부탁드립니다. 
    스팀 환불 내역에 대한 재결제는 PC에서 진행하세요. 모든 마켓의 취소/환불 상품의 재결제가 완료되어야 게임 이용이 가능합니다.\n\n일부 마켓에서 한 상품을 여러 수량으로 한 번에 구매 후 환불한 경우, 
    동일한 수량으로 재결제 해야 합니다. 만약 환불한 수량과 재결제한 수량이 일치하지 않으면 해당 재결제 건은 자동 취소됩니다. 
    취소되는 시점은 마켓에 따라 상이하며 수일이 걸릴 수 있습니다.\n\n 재결제 도중 오류로 인하여 결제 실패한 경우, 현재 계정으로 다시 게임을 재실행해주세요. 디바이스를 변경하여 동일한 마켓계정이면서 다른 게임 계정으로 로그인하시면 결제가 정상적으로 완료되지 않을 수 있습니다.\n\n결제 불가상품을 비롯한 그밖의 문의사항은 고객센터로 접수 부탁드립니다.\n\n* 환불 시간은 UTC+9 기준입니다.",
  "customer_site": {
    "pc": "https://sandbox-customer.withhive.com/com2us/faq/game/539",
    "mobile": "https://sandbox-customer-m.withhive.com/com2us/faq/game/539"
  },
  "refund_list": [
    {
      "refund_idx": 20850,
      "market_id": 1,
      "market_pid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.cs01",
      "refund_time": "2023.02.02 15:47 (UTC+9)",
      "refund_time_ms": 1675320475000,
      "quantity": 1,
      "price": "1200",
      "currency": "KRW",
      "display_price": "₩1,200"
    }
  ]
}

退款用户重新支付通知弹窗示例

Warning

用户必须实现一个“刷新”按钮，以便在完成重新购买的付款后更新重新购买项目的列表。 完成重新购买的付款后，必须重新调用“退款用户重新购买目标退款历史查询”API，以继续进行身份验证释放流程。