端游接入文档
一、更新日志
版本号 | 发布时间 | 更新内容 |
---|---|---|
v1.1.0 | 2021-09-29 | 1、登录 user/info 接口返回响应数据中的 uid 字段由 int 更改为 long 类型。 |
二、时序图
2.1 支付时序图
三、接口列表
接口名 | 资源路径 | 请求方式 | 是否必接 | 描述 | 备注 |
---|---|---|---|---|---|
服务单查单接口 | /server/queryOrder | GET | 否 | 进行服务端查单以校验订单信息及状态正确性 | 建议接入 |
支付成功通知接口 | 无 | POST | 是 | 用户支付成功后,通知业务方发货 | |
登录user/info接口 | /api/pcg/user/info | POST | 是 | 通过临时令牌获取用户真实信息 |
四、签名方法
注:
1.sign字段不参与签名
2.拼接字符串通过utf-8编码
签名方式说明:
将参数通过key值的字典方式排序后,取对应value的值进行拼接,最后拼接secretKey进行md5,并转为小写,如下所示:
sign = md5(v1v2……secretKey).toLowerCase()
示例:
假设:secretKey = biliGameSecretTest
请求参数为:
{
"out_trade_no": "out_trade_no_test_100",
"username": "usernameTest",
"game_id": "biligame1",
"timestamp": "32145673"
}
进行签名字符串+密钥为:biligame1out_trade_no_test_10032145673usernameTestbiliGameSecretTest
签名后为:a73a9c7c449cb997729333ca323ea99e
五、 API 状态码
状态码 | 说明 |
---|---|
0 | 成功 |
-704 | 订单不存在 |
-500 | 订单不存在 |
-400 | 请求参数有误 |
-3 | 签名错误 |
六、接口文档
6.1 服务端查单
接口描述:用于业务方进行服务端查询订单信息及状态
接口版本:v1.0
HTTP请求方式:GET
请求地址:https://wpg.biligame.com/server/queryOrder
请求参数
参数 | 必填 | 类型 | 描述 | 备注 |
---|---|---|---|---|
order_no | Y | String | bili平台订单号 | |
uid | Y | String | bili平台用户id | |
game_id | Y | int | bili平台游戏id | |
zone_id | Y | int | bili平台游戏区服id | |
timestamp | Y | long | 请求时间戳 | |
sign | Y | String | 签名 |
响应数据说明
响应数据格式:json
参数 | 必填 | 类型 | 描述 | 备注 |
---|---|---|---|---|
code | Y | int | 状态码,详见错误码列表 | |
message | N | String | 响应描述 | |
timestamp | Y | long | 响应时间 | |
uid | Y | String | bili平台用户id | |
game_id | Y | String | bili平台游戏id | |
zone_id | Y | String | bili平台区服id | |
order_no | Y | String | bili平台订单号 | |
out_trade_no | Y | String | 游戏订单号 | |
product_name | Y | String | 商品名称 | |
product_desc | Y | String | 商品描述 | |
money | Y | String | 订单金额 | 单位:元 |
game_money | Y | String | 游戏内货币、道具数量 | |
uname | Y | String | 用户昵称 | |
role_name | Y | String | 游戏内角色名称 | |
pay_time | Y | long | 用户支付时间戳 | 单位:秒 |
client_ip | Y | String | 用户ip | |
order_status | Y | String | 订单状态 | 1:充值成功 2:充值失败 3:充值中 |
extension_info | N | String | 额外附加信息 | 下单时传入原样返回 |
响应示例
{
"timestamp": 1591783205,
"uid": "1111119274",
"uname": "",
"game_id": "13901",
"zone_id": "6565",
"role_name": "",
"money": "0.01",
"order_no": "2020061018293224215797",
"pay_time": 1591788030,
"client_ip": "127.0.0.1",
"product_name": "端游测试商品",
"product_desc": "",
"out_trade_no": "1591813757",
"game_money": "1000",
"order_status": "1",
"code": 0
}
6.2 支付成功通知(必接)
接口描述:用户支付成功后,通知业务方给用户发货
接口版本:v1.0
HTTP请求方式:POST
请求地址:游戏研发提供的支付回调地址
请求参数
参数 | 必填 | 类型 | 描述 | 备注 |
---|---|---|---|---|
data | Y | String | 支付回调内容,JSON格式 |
data内容
参数 | 必填 | 类型 | 描述 | 备注 |
---|---|---|---|---|
uid | Y | String | bili平台用户id | |
game_id | Y | String | bili平台游戏id | |
zone_id | Y | String | bili平台区服id | |
order_no | Y | String | bili平台订单号 | |
out_trade_no | Y | String | 游戏订单号 | |
product_name | Y | String | 商品名称 | |
product_desc | Y | String | 商品描述 | |
money | Y | String | 订单金额 | 单位:元 |
game_money | Y | String | 游戏内货币、道具数量 | |
uname | Y | String | 用户昵称 | |
role_name | Y | String | 游戏内角色名称 | |
pay_time | Y | String | 用户支付时间戳 | 单位:秒 |
client_ip | Y | String | 用户IP | |
order_status | Y | String | 订单状态 | 1:充值成功 2:充值失败 |
extension_info | N | String | 额外附加信息 | 如果下单时未传递, 则不会有此字段 |
sign | Y | String | 签名 | 校验规则见下面【验证签名】部分 |
返回规约
返回值 | 类型 | 大小写说明 | 返回值说明 |
---|---|---|---|
success | String | 小写 | 表示成功 |
fail | String | 小写 | 表示失败 |
请求示例
http://www.notifyUrl.com?data={
"client_ip": "127.0.0.1",
"game_id": "13901",
"game_money": "1000",
"money": "0.01",
"order_no": "2020061018293224215797",
"order_status": "1",
"out_trade_no": "1591813757",
"pay_time": "1591786995",
"product_desc": "",
"product_name": "端游测试商品",
"role_name": "",
"sign": "2cc0b8b2192b4fdb19adb5bb81f6727d",
"uid": "1111119274",
"uname": "",
"zone_id": "6565"
}
研发返回
success
验证签名
1.将data进行反序列化,获得一个key-value的Map,并按key进行字典排序。
2.遍历Map,并将value值(需要进行URL encode)进行拼接,最后拼接上secretKey,然后进行md5,并将结果转换为小写,如下所示:
sign = md5(v1v2……secretKey).toLowerCase()
注:
1.sign字段不参与签名
2.URL encode 结果必须遵照 RFC3986 规范;除字母 / 数字 / "-" / "." / "_" / "~"字符外,其它字符均需要进行百分号编码。
java实现参考:
URLEncoder.encode("待处理字符串", "UTF-8").replace("+", "%20").replace("*", "%2A").replace("%7E", "~")
注意事项说明
1.支付平台明确收到成功返回后(即返回success),才认为通知成功,否则会重试,注意返回值是小写字符串。
重试策略如下:1,3,10,30,60,60 * 2,60 * 4,60 * 6,60 * 8,60 * 9 将延迟上述时间(单位:分钟)进行重试通知。
2.业务方需校验签名(sign),订单支付金额(money),订单状态(order_status),游戏内货币、道具数量(game_money),游戏Id(game_id),用户id(uid)的正确性。
3.研发返回结果不能包含引号,不能加入换行符,缩进符等不可见字符。
6.3 登录user/info接口
接口描述:通过临时令牌获取用户真实信息,该方法需要签名校验
接口版本:v1.0
HTTP请求方式:POST
请求地址:http://wpg-api.biligame.com/api/pcg/user/info
请求头部信息
参数 | 必填 | 头部值 | 描述 |
---|---|---|---|
User-Agent | Y | Mozilla/5.0 PCGameSDK | 常量 |
请求参数
参数 | 必填 | 类型 | 描述 |
---|---|---|---|
game_id | Y | int | 游戏ID |
merchant_id | Y | int | 商户ID |
zone_id | Y | int | 区服ID |
access_key | Y | String | 临时令牌 |
timestamp | Y | long | 时间戳 |
sign | Y | String | 签名 |
签名方式说明
把接口所需所有参数,按参数名称排序,排除item_name以及item_desc字段,将其他参数值进行URLEncode编码后拼接,如utk=aa&time=bb,拼接后为aabb,最后再拼接上约定的密钥app-key,做md5加密
字段:拼接时需对字段名排序,排序方式是按字段名进行字符串升序排列.
字段值:取值只能为字符串/数字/true/false/null五类(注意true/false/null为小写,非True/False/Null等).字段值记得做URL编码
计算MD5签名时,取签名内容的字节时,应以UTF-8编码取字符串的字节值
响应数据说明
响应数据格式:json
参数 | 必填 | 类型 | 描述 |
---|---|---|---|
code | Y | int | 状态码,0表示成功 |
uid | Y | long | 用户uid |
uname | Y | String | 用户昵称 |
is_certify | Y | int | 是否需要防沉迷验证 |
响应示例
{
: "request-id":"c56062605d4b11ea901f4620548a6ae4",
: "code":0,
: "uid":39735053,
: "uname":"autotest29233",
: "is_certify":1
}