聚合渠道服务端

文档修订记录

版本 更新日期 更新内容
3.0.6 2024.06.03 更新订单查询接口返回信息，新增channel_id字段
3.0.5 2024.05.14 新增账号登录和支付时序图
3.0.4 2022.03.30 登录校验接口verify新增type参数，可实时获取用户扩展信息，包含三方绑定信息
3.0.3 2021.01.21 更新支付回调接口返回信息，新增渠道ID标识，回调策略调整
3.0.2 2021.01.05 更新verify校验接口返回信息，新增用户详情信息
3.0.1 2020.10.27 新增verify会话校验接口,订单查询新增source参数
3.0.0 2020.05.25 新版本首发

1. 登录校验接口

1.1 登录流程

file

1、用户在游戏内点击登录，游戏客户端调用聚合SDK的登录接口
2、聚合SDK拉起渠道登录页面，用户在登录页面完成登录
3、聚合SDK携带渠道用户登录信息请求聚合服务端登录接口，聚合服务端进行渠道用户登录信息校验，完成聚合账号登录
4、游戏客户端携带聚合用户登录信息请求游戏服务端登录接口，游戏服务端进行聚合用户登录信息校验，完成游戏账号登录
1.2 说明
  • 场景一：登录成功后，游戏服务端需要携带token及聚合渠道用户OpenID等信息到平台服务端进行请求校验，确保本次登录是有效的，同时平台会返回对应当前用户的扩展信息，包含手机、生日、性别、名字、第三方信息（如qq、微信等昵称），部分个人信息会进行脱敏。
  • 场景二：如果玩家在个人中心进行了相关三方绑定操作，比如绑定了微信/QQ/Facebook等，游戏方需要实时获得玩家的绑定情况时，只需将type参数值设置为2来进行实时的渠道用户信息获取，通过用户三方信息的昵称是否有值来判断是否绑定成功。

备注：用户扩展信息，如三方绑定关系，手机号等，大部分渠道无法获取，目前仅保证能返回星云官方渠道的用户扩展信息。

1.3 Api地址

备注：由于目前通信网关有区分地域部署，所以请使用对应游戏发行区域的请求地址。

1.4 请求方式

GET

1.5 请求参数
参数名 必选 类型 说明
app_id 是 string 开放平台AppID
source 是 string 固定值：gateway_srv
open_id 是 string 聚合渠道用户OpenID（作为游戏内的唯一账号标识关联字段）
token 是 string 登录票据，有效期为7天
type 否 int 请求类型，默认值为1。1:登录校验，2:实时从渠道获取对应用户信息，包含三方信息
timestamp 是 int 时间戳
sign 是 string 签名值，请使用对接中心提供的AppSecret进行签名
sign_type 是 string 签名类型(默认：md5)
sign_nonce 是 string 签名随机数(随机数字+字符串共8位)
sign_version 是 string 签名版本,默认1.0
1.6 返回参数
通用参数
参数名 类型 说明
request_id string 请求唯一ID，可提供该ID到星云平台进行信息追踪定位
status int 状态码, 0代表成功，非0状态码可参考如下错误码表格确认信息
message string 返回结果描述
数据参数

(若status=0，则data数据参数会返回对应如下信息)

参数名 类型 说明
union_id string 聚合渠道用户UnionID
open_id string 聚合渠道用户OpenID（作为游戏内的唯一账号标识关联字段）
mobile string 手机号，已脱敏
birthday string 生日信息
gender int 性别，0 未知、1 男、2 女
name string 用户姓名，已脱敏
partner array 第三方信息，为空时返回array空数组，有值时返回json数组，有绑定才会有值，包括：qq_nickname、wechat_nickname、facebook_nickname、google_nickname、apple_nicknane
wechat_session_key string 微信小游戏登录会话
douyin_session_key string 抖音小游戏登录会话
1.7 返回结果

成功示例：

三方信息为空时：
{
    request_id:"db9777207c8824ed1f52e046a8c47b7a"
    status:0
    message:"成功"
    data:{
        union_id:"5e9b919ba18aafbc30337dd728247771"
        open_id:"285990c1ec3c488592657e33cfa61551"
        mobile:"198*****195"
        birthday:"2001-05-03"
        gender:1
        name:"李*"
        partner:[]
    }
}

三方信息有值时：
{
    request_id:"db9777207c8824ed1f52e046a8c47b7a"
    status:0
    message:"成功"
    data:{
        union_id:"5e9b919ba18aafbc30337dd728247771"
        open_id:"285990c1ec3c488592657e33cfa61551"
        mobile:"198*****195"
        birthday:"2001-05-03"
        gender:1
        name:"李*"
        partner:{
            qq_nickname: "ଘ南柯ଓ"
        }
    }
}

2. 支付回调

2.1 支付流程

file

1、用户在游戏内商城点击购买，游戏客户端调用聚合SDK的下单接口，传入用户信息、商品信息和游戏支付参数。
2、聚合SDK在聚合服务端创建订单，并从服务端获得拉起渠道支付页面所需的参数和签名。
3、聚合SDK拉起渠道支付页面，用户在支付页面完成支付。
4、聚合SDK回调游戏客户端支付结果；聚合服务端异步回调游戏服务端支付结果，并且仅回调支付成功的订单。
5、游戏服务端发放对应道具，并在游戏客户端展示获得道具。
2.2 说明
  • 支付成功后，平台将按一定策略异步回调通知游戏服务端。回调时间间隔策略为：0秒，2秒，5秒，10秒，1分钟，5分钟，10分钟，1小时，2小时，6小时，15小时 直到游戏方返回成功标识 SUCCESS 为止，若达到最大重试次数游戏服务端还是依然返回失败的话，则后续需人工介入进行补单操作（请务必在response header里设置content-type=text/plain）。
  • 唯一性校验：请务必进行订单的唯一性校验，防止重复下发商品给玩家造成不必要损失。
  • 沙箱充值：沙箱充值（sandbox=1）为未进行实质性充值，只提供联调测试，跑通整个支付流程。请严格区分沙箱状态的订单，正式服仅针对非沙箱订单进行道具下发，避免被非法人员恶意利用！！！
2.3 回调地址

file

  • 回调地址：需前往对接中心里面设置对应游戏回调地址。
  • IP白名单：请前往对接中心查看回调来源IP列表，必要的话请将对应IP添加为回调通知的合法白名单来源。（**非必须**）
2.4 请求方式

POST

2.5 参数列表
参数名 必传 类型 说明
trade_status 是 string TRADE_SUCCESS 成功, 其他值：TRADE_PROCESSING（业务执行中）, TRADE_FAIL（支付失败）
trade_no 是 string 星云订单号
trade_time 是 string 订单支付时间,日期时间格式
out_trade_no 是 string 游戏方订单号
total_amount 是 int 支付金额(单位分)
goods_id 是 string 游戏商品ID
app_id 是 string 开放平台AppID
player_id 是 string 游戏角色ID
open_id 是 string 聚合渠道用户OpenID
server_id 是 int 游戏区服ID
channel_id 是 string 聚合渠道ID
sandbox 是 int 是否沙箱充值，1为沙箱充值，0非沙箱（沙箱充值（sandbox=1）为未进行实质性充值，只提供联调测试，跑通整个支付流程。请严格区分沙箱状态的订单，正式服仅针对非沙箱订单进行道具下发，避免被非法人员恶意利用！！！）
timestamp 是 int 请求时间戳
notify_ext 是 string 回调扩展，游戏方在发起订单请求时传递过来的参数，平台将原封不动回传过去
sign 是 string 签名串，根据创建订单传递过来的pay_sign_type类型，使用不同的签名方式，md5则使用AppSecret进行签名，rsa的则使用PayPublicKey进行验证
2.6 返回结果

游戏服务端校验成功后需返回字符串SUCCESS，否则平台将会依据对应的回调策略持续请求。请务必在response header里设置content-type=text/plain

成功示例：

SUCCESS

3. 订单查询接口

3.1 说明
  • 提供通过星云订单号或游戏方订单号进行订单信息查询，若两种订单号都传，则以星云订单号为准。
3.2 Api地址
3.3 请求方式

GET

3.4 请求参数
参数名 必选 类型 说明
app_id 是 string 开放平台AppID
source 是 string 固定值：gateway_srv
trade_no 与out_trade_no二选一 string 星云订单号
out_trade_no 与trade_no二选一 string 游戏方订单号
timestamp 是 int 时间戳
sign 是 string 签名值，请使用对接中心提供的AppSecret进行签名
sign_type 否 string 签名类型(默认：md5)
sign_nonce 否 string 签名随机数(随机数字+字符串8位)
sign_version 否 string 签名版本,默认1.0
3.5 返回参数
通用参数
参数名 类型 说明
request_id string 请求唯一ID，可提供该ID到星云平台进行信息追踪定位
status int 状态码, 0代表成功，非0状态码可参考如下错误码表格确认信息
message string 返回结果描述
数据参数

(若status=0，则data数据参数会返回对应如下信息)

参数名 类型 说明
trade_status string TRADE_SUCCESS 成功, 其他值：TRADE_PROCESSING（业务执行中）, TRADE_FAIL（支付失败）
trade_no string 星云订单号
trade_time string 订单支付时间,日期时间格式
out_trade_no string 游戏方订单号
total_amount int 支付金额(单位分)
goods_id string 游戏商品ID
app_id string 开放平台AppID
channel_id string 开放平台ChannelID
player_id string 游戏角色ID
open_id string 聚合渠道用户OpenID
server_id int 游戏区服ID
sandbox int 是否沙箱充值，1为沙箱充值，0非沙箱（沙箱充值（sandbox=1）为未进行实质性充值，只提供联调测试，跑通整个支付流程。请严格区分沙箱状态的订单，正式服仅针对非沙箱订单进行道具下发，避免被非法人员恶意利用！！！）
3.6 返回结果

成功示例：

{
    request_id:"db9777207c8824ed1f52e046a8c47b7a"
    status:0
    message:"成功"
    data: {
        "trade_status": "TRADE_SUCCESS",
        "trade_no": "200012020042819533749873188",
        "trade_time": "2020-04-28 19:56:37",
        "out_trade_no": "61ede5abb8af65d87a036e5c48ebfb051",
        "total_amount": 100,
        "goods_id": "com.feiyu.sandbox.demo.1",
        "app_id": "20001",
        "player_id": "role_id_001",
        "open_id": "88f8d15ce0fa3325eb93241a8d06de44",
        "server_id": 1,
        "sandbox": 1
    }
}

4 签名规则

file

4.1 MD5步骤说明
1 待签名参数 ：除去 sign ，其他参数(包含空值的参数)都要参加验签。
2 对所有待签名参数按照字段名的ASCII码从小到大排序。
3 使用键值对的格式（key1=value1&key2=value2）拼接成字符串；进行urlencode编码（PHP使用rawurlencode），获得$source字符串。
4 将步骤3的$source字符与秘钥通过&符号进行拼接:$source&$key。
5 将步骤4的字符串进行md5哈希签名得到最终sign值。

签名样例（PHP版本）： 

1 秘钥获取：请前往对接中心获取对应"AppSecret"
2 验证案例：
ksort($data);//1 按照健值从小到大排序
$query_string = array();//2 键值对按照'='拼接,排除sign参数
foreach ($data as $key => $val) {
    if ($key == 'sign') continue;
    array_push($query_string, $key . '=' . $val);
}
$query_string = join('&', $query_string);//3 将上述数组按照&拼接
$source = rawurlencode($query_string);//4 将拼接结果用rawurlencode编码
$sign= md5($source.'&'. $app_secret);//md5 hash计算签名
4.2 RSA步骤说明
1 待签名参数 ：除去 sign ，其他参数(包含空值的参数)都要参加验签；
2 对所有待签名参数按照字段名的ASCII码从小到大排序；
3 使用键值对的格式（key1=value1&key2=value2）拼接成字符串；进行urlencode编码（PHP使用rawurlencode），获得$source字符串；
4 将请求传递过去的sign值进行base64Decode,后进行openssl校验 openssl_verify($source, base64_decode($sign), $res)

RSA-公钥验证签名样例（PHP版本）： 

1 秘钥获取：请前往对接中心获取对应"充值 Key"
2 验证案例：
ksort($data);// 按照健值从小到大排序
$query_string = array();// 键值对按照'='拼接
foreach ($data as $key => $val) {
    if ($key == 'sign') continue;
    array_push($query_string, $key . '=' . $val);
}
$query_string = join('&', $query_string);// 将上述项目按照&拼接
$source = rawurlencode($query_string);// 将拼接结果用rawurlencode编码
$res = openssl_get_publickey($rsapublickey);
$result = (bool)openssl_verify($source, base64_decode($sign), $res);//使用base64_decode进行解码验证签名
openssl_free_key($res);
文章目录