Unknown

游戏服务端对接文档

游戏CP方与发行方服务端对接接口说明

功能说明

这是游戏 CP 方需要主动推送的 Web 接口,主要功能如下:

授权认证

游戏 CP 方获得发行 SDK 颁发的 token 二次验证是否已经完成登录

订单查询

用于查询充值订单状态信息,用于游戏服务端二次验证订单是否支付完成

订单通知

玩家支付完成之后需要游戏 CP 响应给游戏发行端,确认订单状态

实名认证

用于提供游戏防沉迷认证,确认是否为未成年玩家

响应状态码

状态码 说明
200 响应成功/操作成功
400 参数异常/参数错误
401 授权凭证失效,需要提示刷新页面重新登录
403 授权哈希验证签名失败,也就是加密生成 sign 异常
404 游戏应用不存在
500+ 发行服务器错误

通用响应数据格式

参数名 参数类型 参数说明
status number 响应状态,200 - 成功,其他 - 失败
message string 响应状态不为200时候的异常错误
data object 响应状为200时候的扩展数据
提示: 为了安全性考虑请尽量采用 POST 来做请求。

UTC 毫秒级时间戳获取方法

语言 获取方法
Java System.currentTimeMillis()
Python round(time.time() * 1000)
.Net DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
PHP intval(sprintf('%.0f', round(microtime(true) * 1000)))

权限验证

SDK 登录认证成功之后,YFSDK 返回生成的 token,客户端后续开始登录游戏之前需要携带 token 进行二次登录认证,从而确保整体账号正确存在发行后台当中。

请求信息
URL: https://{发行商提供的域名}/authority/verify
请求方式: POST

请求参数

参数名 参数类型 是否必须 参数说明
appid string 游戏在应用后台生成AppId
uid string 玩家在发行后台生成的唯一标识
token string 玩家在发行后台生成的会话凭证
time string 发起的毫秒级UTC时间戳
sign string 需要对以上参数名按照KEY正序排列,sign = md5(正序排列参数+后台生成appkey)

请求示例 (PHP)

<?php
$appid = 10001;// 应用AppID
$appKey = "345f83cea7fe4de056a6045a26645b2b"; // 后台配置的 AppKey
$uid = 100000001; // SDK获取的在发行账号唯一标识ID
$token = "82f69186f2c143f9ca4a1df8645baeb3"; // SDK获取的会话凭证

// 初始化数据结构如下
$params = [
    'appid' => $appid,
    'uid' => $uid,
    'token' => $token,
    'time' => round(microtime(true) * 1000), // 获取发起的毫秒级UTC时间戳
];

// 必须要对数组的 key 做正序排列
ksort($params);

// 最后进行签名生成哈希
$data = [];
foreach ($params as $k=>$v){
    $data []= "$k=$v";
}
$paramsString = implode('&',$data);

// 最后附加上 App Key 合并md5处理
$sign = md5("$paramsString$appKey");

// 最终提交的数据结构, 发起接口请求
$form = $params;
$form['sign'] = $sign;

响应结果

status 说明
200 成功
400 请求参数导致的失败,响应JSON内部 message 字段有具体错误
401 授权 token 失效
403 参数签名错误数据
404 找不到游戏应用
500 发行方服务器异常

订单查询

SDK 发起支付完成之后,YFSDK 返回生成的 order_id 等扩展参数;后续防止游戏 CP 方回调地址和密钥泄露导致被恶意回调,游戏 CP 方在收到回调的时候请求该接口,从而确认该订单在发行平台是否完成支付。

注: 该接口非必须,只是作为提高安全性措施来避免泄露回调地址和密钥被恶意攻击
请求信息
URL: https://{发行商提供的域名}/order/status
请求方式: POST

请求参数

参数名 参数类型 是否必须 参数说明
appid string 游戏在应用后台生成AppId
order_id string 玩家在发行后台生成订单ID
time string 发起的毫秒级UTC时间戳
sign string 需要对以上参数名按照KEY正序排列,sign = md5(正序排列参数+后台生成 app secure)
注意: appKey 和 appSecure 是两个不同的参数

请求示例 (PHP)

<?php
$appid = 10001;// 应用AppID
$appSecure = "27e4139bc838856648332bd0b5ee4cea"; // 后台配置的 App Secure
$orderId = '20250718112706471433'; // SDK获取的在发行平台生成的第三方订单号

// 初始化数据结构如下
$params = [
    'appid' => $appid,
    'order_id' => $orderId,
    'time' => round(microtime(true) * 1000), // 获取发起的毫秒级UTC时间戳
];

// 必须要对数组的 key 做正序排列
ksort($params);

// 准备进行签名生成哈希
$data = [];
foreach ($params as $k=>$v){
    $data []= "$k=$v";
}
$paramsString = implode('&',$data);

// 最后附加上 App Secure 合并md5处理
$sign = md5("$paramsString$appSecure");

// 最终提交的数据结构, 发起接口请求
$form = $params;
$form['sign'] = $sign;

响应结果

status 说明
200 支付成功
400 支付失败
401 游戏应用停止支付
403 参数签名错误数据
404 找不到游戏应用或者订单
500 发行方服务器异常

订单通知

这里只需要保证游戏应用在发行方的回调地址配置正确,或者客户端创建订单参数的时候配置 notify_url,作为我们发行方会负责在第三方支付完成后推送到游戏 CP 方的服务器并按照指定格式响应状态就能对订单进行标识完成。

发行方提交的POST表单数据

参数名 参数类型 参数说明
appid string 游戏在应用后台生成AppId
order_id string 发行方的订单号
uid string 发行方的用户唯一ID
time number 发行方响应的毫秒级UTC时间戳,仅仅作为数据噪音功能
channel string 玩家所属的渠道标识
cp_order_id string CP方生成的订单号
item_id string CP方的商品道具名
item_price number CP方的商品道具单价,注意这里采用分/美分为单位
item_count number CP方的商品道具购买数量,道具最终价格等于 price * count
extension string CP方生成订单时候的扩展字符(最大长度64字符)
currency string 货币结算单位: CNY/USD
region string 国家地区标识: CN/US
sign string 以上参数名按照KEY正序排列,sign = md5(正序排列参数+后台生成 app secure)

签名验证示例 (PHP)

<?php
$appSecure = '27e4139bc838856648332bd0b5ee4cea';// 后台记录的 App Secure

// 假设目前的回调数据架构如下
$request = [
    'appid' => "10001",
    'order_id' => '20250718112706471433',
    'uid' => '1003',
    'channel' => '0',
    'cp_order_id' => '8f8bfa08-6471-ab96-8107-252407b67c80',
    'time' => 1753174571860, // UTC毫秒时间戳
    'extension' => '8f8bfa08-6471-ab96-8107-252407b67c80',

    // 购买RMB等值货币, 相当于充值20元
    'item_id' => '2003',
    'item_price' => 1,
    'item_count' => 20,


    // 支付货币结算和地区
    'currency' => 'CNY',
    'region' => 'CN',
    'sign' => '451e484defcf069caf6a69f6d234893c',
];


// 首先请求参数的时候要把 sign 字段排除掉再参与哈希签名
$params = $request;
unset($params['sign']);

// 必须要对数组的 key 做正序排列
ksort($params);

// 准备进行签名生成哈希
$data = [];
foreach ($params as $k=>$v){
    $data []= "$k=$v";
}
$paramsString = implode('&',$data);

// 最后附加上 App Secure 合并md5处理
$sign = md5("$paramsString$appSecure");

// 最后验证参数签名是否完全匹配
if($sign === $request['sign']){
    // 验证成功, 通知游戏服务器发货
    echo 'success'; // 发货成功之后返回 'success' 字符串确认发货即可
}else{
    // 验证失败, 需要日志记录
    echo 'fail'; // 失败返回非 success 字符串即可
}
补充说明: 如果游戏 CP 方回调之后一直没有返回 'success' 字符串,默认会每分钟推送1次直到 30 次(30分钟),后续需要通知发行方验证订单从而去进行手动补发订单回调。

实名认证

注: 这个接口非必须,按照游戏需求来选择性接入

主要针对玩家未成年的验证,从而确定是否需要按照中国国内的防沉迷做特殊处理。

请求信息
URL: https://{发行商提供的域名}/authority/identity
请求方式: POST

请求参数

参数名 参数类型 是否必须 参数说明
appid string 游戏在应用后台生成AppId
uid string 玩家在发行后台生成的唯一标识
token string 玩家在发行后台生成的会话凭证
time string 发起的毫秒级UTC时间戳
sign string 需要对以上参数名按照KEY正序排列,sign = md5(正序排列参数+后台生成appkey)
提示: 这里的签名方法和二次验证授权机制一致,所以不做补充说明

响应结果 (data 字段)

data 参数类型 说明
uid string 玩家在发行后台生成的唯一标识
age number 玩家实名登记的年龄
overseas number 是否为海外用户,0 - 非海外玩家,1 - 海外玩家
identity_type number 证件类型,0 - 未知,1 - 身份证,2 - 中国护照,3 - 海外护照,4 - 其他
identity_id string 证件号码信息
identity_status int 是否验证实名,0 - 未提供,1 - 实名未权威验证,2 - 权威认证成功,3 - 权威认证失败
identity_code string 中宣部实名认证系统的用户身份唯一标识值
birthday string 用户出生日期,以 yyyyMMdd 格式保存,比如 20250718
注意: identity_id 身份信息并非原文信息,有的是加密过后的唯一身份证标识码