一、简要说明

本文档的阅读对象为接入并使用SDK用户和支付系统的游戏服务器开发者。

通信时SDK均采用UTF8编码。

双发通信时，若有sign字段则一定要验证签名。

二、接口列表

2.1.验证用户信息接口

2.1.1.接口目的

游戏客户端从SDK登录回调中获取到uid后，为防止用户篡改客户端而伪造用户uid标示从而登录他人账号，游戏客户端应将此信息传入给游戏服务器。游戏服务器调用此接口向SDK验证uid的真实性。若uid通过验证则允许此用户登录，若无法通过验证应拒绝此用户的登录授权。

2.1.2.接口地址

http://xxx.com/webapi/checkUserInfo    (xxx.com为域名，请联系贵方运营获取,获取之后替换即可)

2.1.3.请求方式

GET/POST

2.1.4.参数列表

参数	必要性	说明
uid	必传	从客户端登录回调中获取的uid
token	必传	从客户端登录回调中获取的token，请注意token的长度不要被截断

2.1.5.返回字段

接口会返回JSON格式字符串，如：

例1 {"status":false,"message":"tokenUidError"}

例2 {"status":true,"message":""}

参数	类型	必要性	说明
status	bool	必传	接口验证状态，若通过验证为true，否则为false
message	string	必传	Status为false时，message有值，为错误提示语
data	array	可为空	如果status为true时，data数组包含了用户账号绑定信息。
uid	string	可为空	如果status为true时，并且验证的用户存在，则返回用户uid

2.1.6.请求示例

http://xxx.com/webapi/checkUserInfo?token=@171@174@188@127@182@163@148@179@166@168@132@179@165@222@169@116@109@166@96@212@152@156@116@121@106@139@170@154@203@134@124@118@108@164@205@126@173@151@172@169@169@140@158@215@138@153@164@136@160@162@154@197@114@212@159@143@126@125@154@179@168@151@135@155@121@148@215@146@181@100@158@219@161@112@106@184@108@189@121@129@120@158@141@186@129@177@169@140@105@136@128@176@205@124@124@166@163@179@213@151@175@124@185@140@155@124@171@160&uid=523

2.2.发放道具接口

2.2.1.接口目的

玩家在完成充值后,SDK会按照此接口协议向游戏提供的发货地址POST数据（简称为发送通知），游戏在收到SDK POST的数据后应验证相关信息并向玩家发送道具。

游戏应按照第三章中的算法验证签名数据，确定请求是否合法。

游戏发货的金额应当以通知中的金额为准发放道具。

游戏应判断是否重复发放道具，若已发放则不能再次发放。

处理成功后返回SUCCESS这7个字母SDK将不再通知，否则SDK将在一段内持续通知

2.2.2.接口地址

发放道具地址由游戏提供，SDK会主动向此地址发起POST请求

2.2.3.请求方式

POST

2.2.4.POST参数列表

参数	必要性	说明
uid	必有	购买道具的用户uid
username	必有	购买道具的用户username
cpOrderNo	可为空	游戏下单时传递的游戏订单号，原样返回
orderNo	必有	SDK唯一订单号
payTime	必有	用户支付时间，如2017-02-06 14:22:32
payType	必有	订单支付方式，具体值对应支付渠道详见对照表
payAmount	必有	用户支付金额（单位：元） 注意：如果游戏商品有多个数量，那么金额就是单价*数量
payCurrency	必有	用户支付的币种，如RMB，USD等
usdAmount	必有	用户支付的游戏道具以美元计价的金额（单位：元） 注意：如果游戏商品有多个数量，那么金额就是单价*数量
payStatus	必有	支付状态，为0表示成功，为1时游戏不做处理
actRate	必有	充值折扣，取值范围0~1(不包含0），默认为1表示不折扣；如值为0.2表示多发20%的元宝
extrasParams	可为空	游戏下单时传递的扩展参数，将原样返回。
subscriptionStatus	非必有	内购订阅型商品订单使用，如果有此字段表示订单订阅状态。cp监测到有此字段时不需要发货。字段取值为：2：订阅取消
subReason	非必有	内购订阅型商品订单取消订阅原因。当有subscriptionStatus字段时此字段必有
sign	必有	签名值，游戏应根据签名约定，本地计算后与此值进行比对

注：如果是官网充值方式时，CP可以获取extrasParams参数的值来定位到角色信息。这里的值CP可与第三方官网约定一个规则，让第三方官网按照规则传值。

目前规则为:区服ID|@|角色ID|@|商品ID

2.2.5.请求示例

假设游戏在SDK后台配置的发货地址为http://xxx.com/notify

SDK会在玩家充值后向此地址POST如下参数：

uid=543&username=554230339%40qq.com&cpOrderNo=orderNo_xxx&orderNo=0020170210162721805701&payTime=2017-02-10+16%3A27%3A55&payAmount=6.00&payStatus=0&payCurrency=RMB&usdAmount=0.99&extrasParams=&sign=22abf0b204d19316d177baeec6a90fcd

CP接受到数据后应按第三章约定算法计算签名。

a)假设本地计算的签名与POST中传递的签名一致，则通过

b)若签名不一致，则返回FAILED，中断处理。

CP应判断是否已发送道具。

CP其他判断逻辑。

处理完成后。

a)希望SDK继续通知则返回任何非SUCCESS的字符。

b)处理完毕，订单结束则返回SUCCESS，SDK不会再通知。

2.3.Facebook活动礼包发放（选接）

2.3.1.接口目的

玩家在领取礼包之后,SDK会按照此接口协议向游戏提供的发货地址POST数据，游戏在收到SDK POST的数据后应验证相关信息并向玩家发送礼包。

游戏应按照第三章中的算法验证签名数据，确定请求是否合法。

游戏应判断是否重复发放礼包，若已发放则不能再次发放。

处理成功后返回SUCCESS这7个字母表示领取成功，否则判定领取失败。

2.3.2.接口地址

礼包发放地址由游戏提供，SDK会主动向此地址发起POST请求

2.3.3.请求方式

POST

2.3.4.POST参数列表

参数	必要性	说明
uid	必有	领取礼包的用户uid
giftNo	必有	游戏礼包活动唯一值，表示用户要领取的哪个活动礼包
serverInfo	必有	游戏跳转活动页面是传递的游戏serverId，原样返回
roleInfo	必有	游戏跳转活动页面是传递的游戏roleId，原样返回
sign	必有	签名值，游戏应根据签名约定，本地计算后与此值进行比对

2.3.5.请求示例

假设游戏在SDK活动配置的礼包地址为http://xxx.com/notify

SDK会在玩家点击领取礼包时同步向此地址POST如下参数：

uid=543&giftNo=dwqu18921hud9&sign=22abf0b204d19316d177baeec6a90fcd

CP接受到数据后应按第三章约定算法计算签名。

a)假设本地计算的签名与POST中传递的签名一致，则通过

b)若签名不一致，则返回FAILED，中断处理。

CP应判断是否已发送礼包。

CP其他判断逻辑。

处理完成后，返回SUCCESS表示用户领取成功，否则为失败。

2.4. 获取玩家游戏角色列表（选接）

2.4.1.接口目的

在网页充值平台玩家登录账号选择游戏时获取游戏角色列表。玩家选择角色后向该角色充值。

2.4.2.接口地址

地址由游戏提供，SDK会主动向此地址发起POST请求

2.4.3.请求方式

POST

2.4.4.POST参数列表

参数	必要性	说明
frType	非必有	获取角色方式，取枚举值，如果没有此字段默认以第1种方式获取角色列表 1. 通过SDK账号UID获取，默认为此方式 2. 通过角色ID获取
roleId	非必有	用户角色ID，如果frType为2时，角色ID字段必有。游戏此时应该根据角色ID查询当前游戏的角色信息
uid	非必有	用户SDK账号uid，如果frType为1时，uid字段必有。游戏此时应该根据SDK账号ID查询当前游戏的所有角色列表
username	非必有	用户SDK账号名，如果frType为1时，username字段必有。游戏此时应该根据SDK账号ID查询当前游戏的所有角色列表
productCode	必有	SDK产品ProductCode
sign	必有	签名值，游戏应根据签名约定，本地计算后与此值进行比对

2.4.5.返回字段说明

游戏地址在接收到SDK请求之后返回玩家的角色信息列表，数据格式为json，返回字段如下

参数	必要性	说明
code	必有	200：请求成功；其余值均为失败
data	必有	玩家角色列表集合，每个子集包含如下字段： serverId：区服ID serverName：区服名 roleId：角色ID roleName：角色名 roleLevel：角色等级 sdkUid：当获取方式frType=2时，游戏应必须返回SDK的uid，否则可能会无法调起支付

2.5. 消息推送（选接）

2.5.1.接口目的

开发者可通过该接口对玩家进行消息推送。接收推送的设备为玩家最后登录设备。
a.SDK海外后台->平台管理->开放平台生成开发者秘钥，获取openId和openKey。
b.其中openKey为用于生成签名KEY。
c.玩家设备可能是Android或IOS，开发者需在SDK后台推送配置配置 FireBase(Android) 和 推送证书(IOS)。
d.接口最终使用的推送参数，取决于玩家最后登录设备对应平台以及产品的配置，同一玩家也可能每次使用不同设备登录不同游戏！

2.5.2.接口地址

http://xxx.com/pushApi/send   (xxx.com为域名，请联系贵方运营获取,获取之后替换即可)

2.5.3.请求方式

POST

2.5.4.POST参数列表

参数	必要性	说明
openid	必有	SDK后台获取
users	必有	玩家ID集合，JSON串，如 ["123","124"]
title	必有	消息标题
message	必有	消息内容
andDebug	可选	Google推送环境，可选值：1沙盒模式，0正式环境；默认0，请注意对应环境参数。
iosDebug	可选	Apple推送环境，可选值：1沙盒模式，0正式环境；默认0，请注意对应环境参数。
sign	必有	参数签名，参考本接口所述签名算法

2.5.5.请求示例

POST

openId=0lEAhY&title=New%20message&message=The%20test%20message&users=%5B%22123%22%2C%22124%22%5D&sign=a2fd31d0d525857fb386298a509a3755

2.5.6.接口响应

失败

{
    "status": false,
    "data": [],
    "message": "SIGN ERROR"
}

成功，返回推送成功数。

{
            "data": {
                "success": 2
            },
            "status": true,
            "message": ""
        }

2.5.7.签名算法

请求参数中除sign外的所有参数(可选参数可不传)，按键首字母升序排序，键值对按照 key=val 封装，并使用 & 进行拼接，最后再拼接上openKey(注意openKey 前面也应该有个 &)得到待签名串。
待签名串示例：

message=The test message&openId=0lEAhY&title=You have a new message&users=["57524269","57524270"]&bkajTWxAT2TyU5vXuStD59smApTrMGso

将上一步得到的待签名串进行MD5，即得到32位签名sign。

三、签名算法描述

通信时，发起方会在请求中附带sign字段。

接收方收到消息后将收到的键值对POST参数，移除sign后，按首字母升序排序。

将所有键值对按 key1=val1&key2=val2&key3=val3& 格式进行拼接。

在第3步拼接的字符后拼接SDK约定的callbackKey则此时格式为：key1=val1&key2=val2&key3=val3&callbackKey

将第4步处理的字符串进行md5编码，得到32位md5值。

将第5步获取的md5值与第1步中发起方传递的sign值进行对比，一致则通过。

代码片段参见第四章。

四、代码片段

/**

* 本地计算MD5签名PHP示例代码

* @params $callbackey SDK后台分配的通信密钥

* @return本地计算的md5签名值

*/

public function getMd5Sign($callbackkey){

   $params = $_POST;

   unset($params['sign']);

   ksort($params);$signKey = '';

   foreach($params as $key => $val){

   $signKey .= $key.'='.$val.'&';

   }

   $signKey .= $callbackkey;

   return md5($signKey);

}