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 身份信息并非原文信息,有的是加密过后的唯一身份证标识码