GHOME SDK 文档 - 支付中心

# GHOME SDK 服务端 API （国际）

# 1. 【认证】

# 1.1 账号体系说明

  • 注册&登录原理

    1. 在游戏登录界面打开SDK注册&登录界面；
    2. 用户完成注册&登录之后，SDK把用户id和ticket票据返回游戏；
    3. 游戏如果有服务器，需要把客户端获取到ticket票据发送到“登录票据验证接口”（参考5.4节）进行验证，然后把返回的用户信息（用户id和账号）保存到游戏服务器；

  • 注册&登录时序图

    Android3

# 1.2. 服务器登录票据验证接口

  • 用法说明

    为了保证游戏服务器的安全性，游戏服务器在登记用户登录信息之前需要到国际版服务器做一个验证

  • 接口地址

    https://abroad-sin.shengqugames-corp.com/fh/open/ticket

  • 传值方式

    GET

  • 参数列表

    appid: 游戏对应的APPID

    timestamp: 精确到秒的unix时间戳

    sequence: 不重复的请求序列号（全局唯一）

    ticket_id: 从客户端登录接口返回的ticket字符串；

    sign: 签名串（参考：“附录A：服务器端签名算法”，签名原始串示例：appid=xxx&sequence=xxx&ticket_id=xxx & timestamp=xxxappsecretkey）

  • 返回结果

    返回结果按json编码，数据格式为：

    {
  "code":0, #返回状态，0为成功，1为失败,2  签名错误7 osap商户不存在,3001 票据不存在或超过有效期或被反复验证,1003 票据申请的appId和验证的APPID不一致
  "msg":"ok", #错误信息
  "data":{
    "userid":123456, #平台用户id，纯数字，无类型。
    "token":"40E00263-16A7-8CFA-D0E8-C951D683EA24", #平台TOKEN，36位字符串，暂时不用
    "phone":"+86-139****6893", #手机帐号，带国际区号，可用于显示帐号
    "invitation_code":"34343",  #邀请码，国际版无用
  	"companyId":"502", #当前用户登录第三方平台id，对应关系详见下表。若用户为游客登录返回：“companyId:""”
  	"thirdId":"1234567890qwerty"#当前用户登录第三方账号标识。若用户为游客登录返回：“thirdId:""”
  }
}
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12

​

第三方平台名称 第三方平台id
Gamecenter（已废弃） 501
google 502
Facebook 503
appleId 504
Twitter or X 505
Line 506
邮箱登录 588

# 1.3. 服务器WEB登录票据验证接口

  • 用法说明

    为了保证游戏服务器的安全性，游戏活动或商城后端服务器在确认用户登录信息之前需要到国际版服务器做一个验证

  • 接口地址

    https://service-sin.shengqugames-corp.com/fh/open/verifyWebTicket

  • 传值方式

    GET

  • 参数列表

    appid: 游戏对应的APPID

    timestamp: 精确到秒的unix时间戳

    sequence: 不重复的请求序列号（全局唯一）

    ticket_id: 从客户端登录接口返回的ticket字符串

    merchant_name: 商户号，由盛趣支付中心分配

    signature_method: 固定传入"MD5"

    signature: 签名串（参考：“附录B：WEB服务器端签名算法”，签名原始串示例：appid=xxxmerchant_name=xxxsequence=xxxsignature_method=MD5ticket_id=xxxtimestamp=xxxappsecretkey，其中appsecretkey为盛趣支付中心分配，且与商户号一一对应 ）

  • 返回结果

    返回结果按json编码，数据格式为：

    {
 "return_code":0, #返回状态，0为成功，1为失败,2  签名错误7 osap商户不存在,3001 票据不存在或超过有效期或被反复验证,1003 票据申请的appId和验证的APPID不一致
 "return_message":"ok", #错误信息
  "data":{
    "userid":123456, #平台用户id，纯数字，无类型。
    "token":"40E00263-16A7-8CFA-D0E8-C951D683EA24", #平台TOKEN，36位字符串，暂时不用
    "companyId":"34343",  #登录第三方 id，用于确认登录来源
  	"userIdCreateTime":"2023-11-15 23:59:59"
  }
}
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

# 2. 【支付】

# 2.1. 支付原理说明

  • 支付原理

    1. 游戏客户端发起支付请求；
    2. SDK服务器收到请求，并发送至第三方支付；
    3. 第三方支付成功收费以后通知SDK服务器，再由SDK服务器通知游戏服务器发货至游戏，需要游戏提供“订单通知接口”进行接收（参考2.2节）；

  • 支付时线图

    pay

# 2.2. 服务器订单通知接口

  • 用法说明

    用于将用户支付结果通知给游戏。

  • 接口地址

    接口地址需要游戏提供，可以在开发商后台“我的游戏 > 区服管理”中配置。

  • 传值方式

    POST

  • 参数列表

    orderNo： 服务器的订单号

    userId：用户ID

    gameOrderNo： 游戏的订单号

    product： 产品ID（在开发商后台“我的游戏 > 充值管理”中配置）

    extend：游戏发送过来的扩展信息，原格式返回

    channel：支付渠道 google=谷歌 ios=苹果 onestore=OneStore mycard=MyCard unity-pc=pc统一支付收银台 coupon=抵扣券订单 union=移动端统一支付收银台

    platform：支付平台 0=安卓 1=IOS 2=PC

    mock：沙盒订单 1=沙盒 0=正式

    priceLocale：支付货币（客户端上报，三方渠道不会返回）

    priceAmount：支付货币金额（客户端上报，三方渠道不会返回）

    time：unix时间戳（精确到秒）

    sign：签名串

    payOrderNo: 抵扣券对应支付订单号（仅抵扣券订单）

  • 签名算法：

    1. 调用方首先需要将请求的参数根据参数的key(ASCII码值)进行升序排序，sign和为空参数不参与签名
    2. 将排序好的接口请求参数和参数值按key=val&key2=val2…这样得格式拼装成一个字符串，并在最后加上与APPID对应的APPKEY
    3. 对上述拼接好的字符串进行md5编码，获得最终的签名串

  • 参数示例

channel=ios&extend=testExt&gameOrderNo=p1234&mock=1&orderNo=MP010178040015230421170508000001&platform=1&priceAmount=6&priceLocale=CNY&product=com.snda.gameplus.test.3&sign=b6ab3a1a4b98e0710551a6093283730a&time=1682067939&userId=10529277
1

  • 返回结果

    返回结果按json编码，数据格式为：

{
  resultCode: "success", #响应状态 success = 成功 coupon = 自动发放抵扣券 其他 = 失败 重试
  resultMsg: "ok", #错误信息
  roleId: "roleId" #角色ID， 响应状态为coupon时返回， 用于发放等值抵扣券到对应角色
}
1
2
3
4
5

# 3. 附录A：服务器端签名算法

  • 参数说明：

    1. timestamp为调用接口时的unix时间戳（精确到秒）
    2. sequence为请求序列号（游戏服务器端需要保证两次调用接口生成的sequence不重复）

  • 签名算法：

    1. 调用方首先需要将请求的参数根据参数的key(ASCII码值)进行升序排序
    2. 将排序好的接口请求参数和参数值按key=val&key2=val2…这样得格式拼装成一个字符串，并在最后加上与APPID对应的APPKEY
    3. 对上述拼接好的字符串进行md5编码，获得最终的签名串

  • 代码示例（PHP）：

    public function sign ($params, $secret_key) { // $params数组必须包含timestamp
  $in = ksort($params);
  $pairs = array();
  foreach($in as $k => $v){
    $pair[] = $k. '=' .$v;
  }
  $str = implode('&', $pair); // 拼接字符串
  $str = $str.$secret_key; // 把APPKEY补充到最后
  return md5($str);
}
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

# 4. 附录B：WEB服务器端签名算法

  • 参数说明：

    1. timestamp为调用接口时的unix时间戳（精确到秒）
    2. sequence为请求序列号（游戏服务器端需要保证两次调用接口生成的sequence不重复）
    3. merchant_name 为盛趣支付中心分配商户号
    4. appsecretkey为盛趣支付中分配签名密钥
    5. signature_method固定为 "MD5"

  • 签名算法：

    1. 调用方首先需要将请求的参数根据参数的key(ASCII码值)进行升序排序
    2. 将排序好的接口请求参数和参数值按key1=val1key2=val2key3=val3…这样得格式拼装成一个字符串，并在最后加上与APPID对应的APPKEY
    3. 对上述拼接好的字符串进行md5编码获得signature参数，将 signature参数拼接到原链接串最后。获得最终的签名串，如：https://test.demo.com/key1=value1&key2=value2&merchant_name=TEST&signature_method=MD5&timestamp=1665561412&signature=5470BEA964810777B2984896703FC760

  • 须知： 此签名算法需主动向盛趣支付中心提供访问接口的服务器IP地址，由于接口控制

  • 代码示例（PHP）：

    public function sign ($params, $secret_key) { // $params数组必须包含timestamp
  $in = ksort($params);
  $pairs = array();
  foreach($in as $k => $v){
    $pair[] = $k. '=' .$v;
  }
  $str = implode('', $pair); // 拼接字符串
  $str = $str.$secret_key; // 把APPKEY补充到最后
  return md5($str);
}
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

# 5. 附录C：特殊说明

  • 订单重发机制：

    平台对所有发货状态非“success”的订单，采取统一的重发机制。具体的重发策略为：每60秒重发1次，最大重发次数为60次。

    对尝试重发后，最终失败的订单，我们会隔天通过报表机制发现，由平台方补发货，游戏方不需要参与。

  • 发货重复处理机制：

    基于订单重发机制，可能导致游戏方重复收到相同orderNo的发货通知，此时要求游戏检查orderNo实际到货情况，避免重复向玩家发放游戏币等虚拟货品。建议对一个月内的orderNo做唯一性检查。

    针对已发货成功的订单，要求游戏方收到重复通知时，请务必返回success，状态为“success”的订单，将不会继续触发重发机制。

Last Updated: 2024/5/15 11:49:23

← for 手游国外抵扣券功能 →