小游戏支付服务端接入文档

一、支付时序图

二、接口列表

接口名	资源路径	请求方式	是否必接	描述	备注
下单接口	/api/server/mini.game/create.order	POST	是	创建B站支付订单
查单接口	/api/server/mini.game/query.order	GET	否	查询订单状态信息	建议接入
支付成功通知接口	无	POST	是	用户支付成功后，通知业务方发货

三、接口文档

2.1 创建订单接口（必接）

接口描述：研发服务端提交支付订单信息，创建平台订单。
接口版本：1.0
HTTP请求方式：POST
Content-Type：application/x-www-form-urlencoded
请求地址：https://minigame-pay.biligame.net/api/server/mini.game/create.order
请求参数

参数	必填	类型	描述	备注
open_id	Y	String	小游戏用户id
game_id	Y	String	小游戏id
game_money	Y	String	小游戏订单金额，仅支持传入 [ 1 , 3 , 6 , 8 , 12 , 18 , 25 , 30 , 40 , 45 , 50 , 60 , 68 , 73 , 78 , 88 , 98 , 108 , 118 , 128 , 148 , 168 , 188 , 198 , 328 , 648 , 998 , 1498 , 1998 , 2498 , 2998 ]
out_trade_no	Y	String	小游戏订单号，[ 8 , 32 ] 个字符
username	Y	String	小游戏用户昵称，[ 1 , 128 ] 个字符
item_name	Y	String	小游戏商品名称，[ 1, 64 ] 个字符，如：金币（由于支付宝不支持特殊字符 % &，所以参数中不能包含 % &）	不参与签名
timestamp	Y	Long	时间戳
sign	Y	String	签名
extension_info	N	String	自定义参数，支付成功后通过回调原样返回， [ 1 , 255 ] 个字符
notify_url	N	String	自定义支付回调地址，[ 1 , 128 ] 个字符	不支持如下带参格式示例：http://host/notify?a=xxx&b=xxx
item_desc	N	String	自定义商品描述，[ 1 , 128 ] 个字符（参数中不能包含 % &）	不参与签名

响应数据说明
响应数据格式：json

参数	必填	类型	描述
code	Y	int	状态码，详见错误码列表
message	Y	String	响应描述
timestamp	Y	long	响应时间
data	N	Map	响应数据

data数据结构说明

参数	必填	类型	描述
customer_id	Y	String	B 站支付 SDK 支付 ID , 转换为customerId传入支付 SDK 即可
merchant_code	Y	String	B 站支付 SDK 支付码，转换为merchantCode传入支付 SDK 即可
coin_type	Y	String	B 站支付 SDK 货币类型，转换为coinType传入支付 SDK 即可
customer_user_type	Y	String	固定为 1 ，转换为customerUserType传入支付 SDK 即可
customer_user_id	Y	String	小游戏用户 id，转换为customerUserId传入支付 SDK 即可
platform_type	Y	String	固定为 2 ，转换为platformType传入支付 SDK 即可
trans_amount	Y	String	小游戏订单金额，转换为transAmount传入支付 SDK 即可
customer_seq	Y	String	B 站游戏平台订单号，转换为customerSeq传入支付 SDK 即可
small_game_name	Y	String	小游戏名，转换为smallGameName传入支付 SDK 即可
sign	Y	String	交易签名，原样传入支付 SDK 即可

响应示例

{
 "requestId": "2eaafac0ee3711e9ae3394b86da63d21",
 "timestamp": 1570870152962,
 "code": 0,
 "message": "success",
 "data": {
     "customer_seq": "5710256460693306",
     "merchant_code": "1",
     "customer_user_type": "1",
     "platform_type": "2",
     "coin_type": "1",
     "sign": "ad554e8484064f078a9518019c21816b",
     "customer_user_id": "d26bb523c3ffb877d33c8066c8a069bb",
     "customer_id": "10037",
     "trans_amount": "10",
     "small_game_name": "test"
 }
}

签名方式说明

注：item_name、item_desc、sign 字段不参与签名


签名方式说明：
将参数按照key的字典排列后连接appSecret，进行md5，如下：
sign = md5(v1v2……appSecret).toLowerCase()

示例：
假设：appSecret = miniGameSecretTest

请求参数为：
{
"game_money": "1",
"out_trade_no": "out_trade_no_test_632",
"item_desc": "test",
"open_id": "41dda1fb8be238456146b80bcgwdgbs",
"item_name": "test",
"merchant_id": "9999",
"server_id": "9999",
"username": "miniGameTest",
"game_id": "biligame11095b75ef5e07bd1",
"timestamp": "32145673"
}

进行签名字符串+密钥为：biligame11095b75ef5e07bd11999941dda1fb8be238456146b80bcgwdgbsout_trade_no_test_632999932145673miniGameTestminiGameSecretTest
签名后为：0a9555f1a7a24d8690c08cb122540129

注意事项说明

1.小游戏支付只支持如下金额档位（单位：元）：
  1,3,6,8,12,18,25,30,40,45,50,60,68,73,78,88,98,108,118,128,148,168,188,198,328,648,998,1498,1998,2498,2998
  若金额档位不匹配，将无法进行支付

2.平台支持支付成功回调地址的如下几种配置方式：
  2.1.正式回调地址 ：该地址由游戏接入平台时填写
  2.2.备用回调地址 ：该地址由游戏接入平台时填写
  2.3.自定义回调地址 ：该地址由游戏至平台下单时通过 notify_url 字段主动传入，该回调地址建议测试使用

  上述回调地址优先级：自定义回调地址 > 正式回调地址 > 备用回调地址

2.2 研发服务端查单接口（选接，建议接入）

接口描述：用于研发主动查询在游戏平台订单支付状态信息
接口版本：1.0
HTTP请求方式：GET
请求地址：https://minigame-pay.biligame.net/api/server/mini.game/query.order
请求参数

参数	必填	类型	描述
game_id	Y	String	小游戏 id
timestamp	Y	long	请求时间戳
sign	Y	String	请求签名
order_no	N	String	B 站游戏平台订单号
out_trade_no	N	String	小游戏订单号

order_no 与 out_trade_no两者必填其一，若都填写，则将order_no作为订单查询条件
data数据结构说明

参数	必填	类型	描述	备注
game_id	Y	String	游戏平台小游戏id
pay_time	Y	StringString	支付时间，时间戳
order_no	Y	String	游戏平台订单号
out_trade_no	Y	String	小游戏订单号
game_money	Y	String	需要充值的游戏内货币数量
item_name	Y	String	游戏内商品名称	不参与签名
notify_status	Y	int	支付成功通知状态 0：未完成，1：已经完成， 2：异步通知失败
order_status	Y	int	游戏平台订单状态 1：已完成，2：失败，3：处理中
extension_info	Y	String	下单时传入的信息
sign	Y	String	签名

响应示例

{
    "requestId": "fadb9510ee3611e9ae3394b86da63d21",
    "timestamp": 111111,
    "code": 0,
    "message": "success",
    "data": {
        "game_money": "12",
        "item_name": "test",
        "notify_status": "0",
        "order_no": "5705263873833534",
        "order_status": "3",
        "out_trade_no": "1111",
        "pay_money": "12",
        "pay_time": "0",
        "sign": "1db53dbf97d1b771db345d84574b7c3c",
        "username": "fengwei"
    }
}

签名方式说明

注：item_name、sign 字段不参与签名


接口请求签名方式说明：
  将参数按照key的字典排序后用value进行拼接，最后拼接appSecret，进行md5，如下：
  sign = md5(v1v2……appSecret).toLowerCase()
 
  示例：
  假设：appSecret = miniGameSecretTest
 
  请求参数为：
  {
   "order_no": "order_no_test_632",
   "game_id": "biligame11095b75ef5e07bd1",
   "timestamp": "1571995010322"
  }
 
  进行签名字符串+密钥为：biligame11095b75ef5e07bd1order_no_test_6321571995010322miniGameSecretTest
  签名后为：3c3bc1b39e64f70ec3ae90fe506782c5



接口响应签名方式说明：
  将参数按照key的字典排序后用key=value进行拼接，最后拼接appSecret，进行md5，如下：
  sign = md5(key1=v1&key2=v2……appSecret).toLowerCase()
 
  示例：
  假设：appSecret = miniGameSecretTest
 
  返回参数为：
	{ 
	  "extension_info": "extension_info_test",
  	  "game_money": "1",
	  "item_name": "test",
	  "notify_status": "1",
	  "order_no": "57200481888521234",
      "order_status": "1",
      "out_trade_no": "out_trade_no_test",
      "pay_money": "1",
      "pay_time": "32145673",
      "username": "test"
    }
 
  进行签名字符串+密钥为：extension_info=extension_info_test&game_money=1&item_name=test&notify_status=1&order_no=57200481888521234&order_status=1&out_trade_no=out_trade_no_test&pay_money=1&pay_time=32145673&username=testminiGameSecretTest
  签名后为：1ff73e0521cfc3361d7dbe7b0d0b2789

2.3 支付成功通知（必接）

接口描述：用户支付成功后，通知业务方给用户发货
接口版本：1.0
HTTP请求方式：POST
Content-Type：application/x-www-form-urlencoded
请求参数

参数	必填	类型	描述	备注
order_no	Y	String	B 站游戏平台订单号
out_trade_no	Y	String	小游戏订单号
username	Y	String	B站用户昵称，与下单时传入一致
pay_time	Y	String	用户支付时间
money	Y	String	B 站游戏平台订单金额，单位：分	使用该值进行金额校验
pay_money	Y	String	用户实付金额，单位：分
game_money	Y	String	游戏内货币金额
game_id	Y	String	小游戏 id
product_name	Y	String	小游戏商品名，与下单传入时一致
extension_info	Y	String	自定义参数，下单时传入
order_status	Y	int	订单状态，1：成功；目前只有成功的订单会进行通知
sign	Y	String	签名

返回规约

返回值	类型	大小写说明	返回值说明
success	String	小写	表示成功
fail	String	小写	表示失败

请求示例

    http://www.notifyUrl.com?data={"extension_info": "",
        "game_id": "3826",
        "game_money": "1",
        "money": "100",
        "order_no": "5720043290152197",
        "order_status": 1,
        "out_trade_no": "out_trade_no_test_632",
        "pay_money": "100",
        "pay_time": "1572004480",
        "product_name": "test",
        "sign": "0e4fe7949f3b8bb5a1e10b4ece1c5b71",
        "username": "fengwei"
    }

小游戏返回

 success

签名方式说明

注：sign 字段不参与签名

签名方式说明：
  将参数按照key的字典排序后用value进行拼接，最后拼接appSecret，进行md5，如下：
  sign = md5(v1v2……appSecret).toLowerCase()

  示例：
  假设：appSecret = miniGameSecretTest

  请求参数为：
 {
   "extension_info": "ExtensionInfoTest",
   "game_id": "1",
   "game_money": "1",
   "money": "100",
   "order_no": "payOrderNoTest",
   "order_status": 1,
   "out_trade_no": "outTradeNoTest",
   "pay_money": "100",
   "pay_time": "1571995010322",
   "product_name": "productNameTest",
   "sign": "30bbcc37b868f73a1351ef52b2e36baf",
   "username": "userNameTest"
 }

  进行签名字符串+密钥为：ExtensionInfoTest11100payOrderNoTest1outTradeNoTest1001571995010322productNameTestuserNameTestminiGameSecretTest
  签名后为：30bbcc37b868f73a1351ef52b2e36baf

注意事项说明

1.支付平台明确收到成功返回后（即返回success），才认为通知成功，否则会重试，注意返回值是小写字符串。
  重试策略如下：1，3，10，30，60，60 * 2，60 * 4，60 * 6，60 * 8，60 * 9   将延迟上述时间（单位：分钟）进行重试通知。

2.业务方需校验sign，以及订单游戏内货币金额（game_money字段），订单支付金额（money字段），以及游戏内货币金额与订单支付金额的转换关系是否正确。
  转换关系如下：money = (game_money/rate)*100; (rate由业务方接入平台时配置，默认为：1.0，即游戏内货币为1，则实际支付金额为1元人名币)。

3.小游戏返回结果不能包含引号，不能加入换行符，缩进符等不可见字符。

四、 API 状态码

状态码	说明
0	成功
-1	接入参数错误
-3	订单签名错误
-14	游戏预下线，已关闭充值
-400	请求参数有误
-500	服务端内部错误
1001	小游戏用户不存在
1003	小游戏订单不存在
60007	调用频繁，请稍后重试