云步互娱-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 SDK返回的用户ID
appKey String 游戏的AppKey,请跟运营联系获取
token String SDK返回的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": "魔法箭枝",
		"sdkOrderId": "150544191195093036879",
		"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。

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

sdkOrderId=GC201703272319263901692762304795668480&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元宝&sdkOrderId=GC201703272319263901692762304795668480

注：空值（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编码

← PI SDK集成母包测试用例（Android） →