云步互娱-YunbuPi(π)

# PI 服务器接口文档_Server(v1.0.x)

此文档接口只针对网游或者需要服务器发货的单机游戏。包括：登录认证，支付结果通知 和 支付结果查询

# 1. 登录认证(网游接入)

# 1.1 说明

客户端登录成功之后，PiServer返回userId和token等数据，客户端需要将该参数告诉游戏服务器，游戏服务器拿着这些参数，去PiServer进行一次登录认证。

# 1.2 请求

方向：游戏开发服务器 -> PI平台

协议： HTTP

方法： POST

URL： 正式环境：https://bi.yunbugame.com/api/cp/v1/account/verify

测试环境：https://bi.yunbugame.com/api/cp/v1/account/verify 请务必先在测试环境上测试通过

Body格式:

{
	"userId":64,
	"appKey":"bf89045b2c32de383800",
	"token":"09147469BA928CB67B99B8A99338DF7966A2B00D6D1A582537545B7710AB25F8DFA1026118EC3B4CF0100A683ED57016f7cdad53ce3773494a11d1b131395f6a",
	"sign":"8bf89045b2c32de383800cf5a64afbe7"
}

参数说明：

参数名 类型 说明
userId String 用户ID
appKey String 游戏的AppKey,请跟运营联系获取
token String Token
sign String md5("userId="+userId+"token="+token+appSecret);游戏服务器按照格式生成一个md5串(32位小写)，appSecret是控制台创建游戏时，生成的AppSecret，请联系运营人员获取

# 1.3 响应

Json格式：

{ 
	"code": 1,
	"msg":"成功",
	"data": 
	{
		"userId":1324,
		"userName":""
	}
}
参数名 类型 说明
code Integer 处理结果, 1 为成功，其它均为失败
msg String 失败的原因
data Object 返回的数据对象
userId Integer 用户在ZeusID
userName String 用户昵称，一般是渠道生成

# 2. 支付结果通知

# 2.1 说明

用于通知开发者服务器支付结果。首先需要在 控制台 添加好游戏的回调地址。

通知重发: 若开发者返回结果为非成功响应(返回的result值不为0)，将对同一笔订单的通知进行周期性重发。

重发机制: 共10次，前3次每20s尝试一次，4-10次每200s尝试一次。

注：为保证可靠性，系统具备补偿机制，所以可能出现通知比预期的多，因此需要开发者自行处理重复的通知。

# 2.2 请求

方向：PI平台 -> 开发者的游戏服务器

协议： HTTP

方法： POST

URL参数： 无

Body参数

参数名 类型 说明
notifyId String 回调通知ID
orderId String 游戏传入的订单ID（客户端上传）
<!-- sdkOrderId String 渠道支付产生的订单ID -->
channel String 渠道名称，如 oppo, huawei等
productId String 商品ID（客户端上传）
productName String 商品名称（客户端上传）
payAmount Integer 支付金额，单位为分
extra String 请求支付时上传的附加参数（客户端上传）
signType String 签名方式：目前仅支持MD5
sign String 签名（见签名和验签）

兼容性建议和原则

  1. 随业务发展，本接口可能增加新参数、删除已有参数或修改已有参数，可能引起兼容性问题。为避免该影响，特增加本建议和原则；

  2. 原则：在本接口有参数改变、增加、删除时，签名将以接口实际发送的全部（除 sign，signType 参数外）参数按如下 签名 章节描述的方式生成待签名串，之后完成签名；

  3. 开发者的回调通知接口实现时，建议取出请求中所有出现的参数， 除 sign，signType参数外， 按本文 签名 章节要求生产待签名串，之后完成验签。

  4. 签名的SecrectKey为创建游戏时的AppSecrect，请妥善保管，不要泄露。

# 2.3 响应

Json格式：{ "result":0, "message":"Success"}

参数名 类型 说明
result Integer 处理结果,0 为成功，其它均为失败
message String 失败的原因，成功时可以不填

# 3. 支付结果查询

# 3.1 说明

用于开发者服务器向PI平台查询支付结果, 签名的SecrectKey为创建游戏时的AppSecrect.

# 3.2 请求

方向：游戏开发服务器 -> Pi服务器

协议： HTTP

方法： GET

URL：http://bi.yunbugame.com/api/cp/v1/order/check (正式环境)

http://test.yunbugame.com/api/cp/v1/order/check (测试环境)

参数：

参数名 类型 说明
appKey String 应用的标识
orderId String 游戏的订单ID

# 3.3 响应

成功：

{
	"code": 1,
	"msg":"成功",
	"data": 
	{
		"channel": "vivo",
		"extra": null,
		"occurTime": "2018-03-26 18:41:07",
		"orderId": "C201709151018300003000124880",
		"payAmount": 300,
		"productId": "12",
		"productName": "魔法箭枝",
		"sign": "8644f1e0e52b1effe7dd5a35f79b55b1",
		"signType": "MD5"
	}
}

Body参数

参数名 类型 说明
code Integer 处理结果, 1 为成功，其它均为失败
msg String 失败的原因
data JSON Object 订单检查的内容
channel String 支付的渠道
extra String 支付时填入的扩展信息
occurTime String 使用时间
orderId String 订单ID
payAmount Integer 支付的金额，以分单位
productId String 商品ID，兑换码对应的商品ID
productName String 商品名称
<!-- sdkOrderId String 渠道支付的订单ID -->
signType String 签名方式：目前仅支持MD5
sign String 签名（见签名和验签）

失败

{ 
	"code": 10001,
	"msg":"参数无效",
	"data":null
}

# 4.兑换码服务器通知

# 4.1 说明

用于将通知开发者服务器兑换码兑换结果。请联系我方运营提交兑换码通知地址以及获取签名SecretKey

通知重发: 若开发者返回结果为非成功响应(返回的result值不为0)，将对同一笔订单的通知进行周期性重发。

重发机制: 共10次，前3次每20s尝试一次，4-10次每200s尝试一次。

注：为保证可靠性，系统具备补偿机制，所以可能出现通知比预期的多，因此需要开发者自行处理重复的通知。

# 4.2 请求

方向：Pi服务器 -> 游戏开发服务器

协议： HTTP

方法： POST

URL参数： 无

Body参数

参数名 类型 说明
notifyId String 回调通知ID
code String 使用的兑换码
occurTime String 使用时间
productId String 商品ID，兑换码对应的商品ID
signType String 签名方式：目前仅持MD5
sign String 签名（见签名和验签）
extra String 扩展信息(透传)

兼容性建议和原则

  1. 随业务发展，本接口可能增加新参数、删除已有参数或修改已有参数，可能引起兼容性问题。为避免该影响，特增加本建议和原则；

  2. 原则：在本接口有参数改变、增加、删除时，签名将以接口实际发送的全部（除 sign，signType 参数外）参数按如下 签名 章节描述的方式生成待签名串，之后完成签名；

  3. 开发者的回调通知接口实现时，建议取出请求中所有出现的参数， 除 sign，signType参数外， 按本文 签名 章节要求生产待签名串，之后完成验签。

# 4.3 响应

Json格式：{ "result":0, "message":"Success"}

参数名 类型 说明
result Integer 处理结果,0 为成功，其它均为失败
message String 失败的原因，成功时可以不填

# 5. 签名

# 5.1 签名算法

Pi服务器要求每次http请求都要对关键信息进行签名，通信对端接收到消息后，也必须对消息进行验签。目前Pi服务器仅支持MD5签名算法，交互过程中，该字段signType固定取值：MD5。

示例：对于如下的参数数组

payAmount=1&productId=&orderId=C2017032723192400100015280&extra=ExtraMessage:1490627964499&channel=oppo&sign=1a07070acc80eddf599dccb39947cee7&signType=MD5&notifyId=N201703311929460000117564&productName=100元宝

对数组里的每一个参数名称ASCII 码的增序排序，若遇到相同首字母，则看第二个字母，以此类推,排序完成之后，再把所有数组值以“&”字符连接起来signData:

channel=oppo&extra=ExtraMessage:1490627964499&notifyId=N201703311929460000117564&orderId=C2017032723192400100015280&payAmount=1&productName=100元宝

注：空值（NULL和""）不参与签名, sign 和 signType 也不参与签名

最后签名：

sign=to_lower_case(md5_hex(signData&to_lower_case(md5_hex(App-key))))

# 5.2 验签

获取签名时，直接调用Pi服务器提供的签名方法[下载Java签名文件 (opens new window)]  [下载PHP签名文件]即可：

ZeusSignUtils.getSign(Map<String,String>para, String key)

该方法返回值即为签名：sign

验证签名时，直接调用Zeus提供的验签方法即可：

ZeusSignUtils.verifySignature(Map<String, String>para, String key)

该方法返回值为boolean，验签成功时为true，失败时为false

# 6. 注意事项

请使用UTF-8编码

← 常见问题FQA →