端游接入文档
一、更新日志
| 版本号 | 发布时间 | 更新内容 |
|---|---|---|
| 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
}