端游接入文档

一、更新日志

版本号 发布时间 更新内容
v1.1.0 2021-09-29 1、登录 user/info 接口返回响应数据中的 uid 字段由 int 更改为 long 类型。

二、时序图

2.1 支付时序图

pc_server

三、接口列表

接口名 资源路径 请求方式 是否必接 描述 备注
服务单查单接口 /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
}