接入流程
创建接入账号管理员在云黑风险后台创建接入用户,启用账号后生成 API Key 和 API Secret。接入方也可以登录用户中心查看配置。
服务端保存密钥API Secret 只允许保存在后端服务,不要下发到浏览器、小程序、App 客户端或公开仓库。
生成签名并调用接口每次请求带上
api_key、timestamp 和 sign,服务端会校验签名和时间戳。按业务场景调用支付、注册、登录前可调用黑名单检测;产生交易投诉或欺诈证据时调用提交投诉接口;站点已有黑名单可调用同步接口。
推荐使用后端服务通过 HTTPS POST JSON 调用接口。接口也兼容表单参数和 URL Query 参数,但签名字段必须覆盖最终提交的所有业务参数。
签名认证
所有接口都必须携带认证字段。签名算法为 HMAC-SHA256,密钥为接入账号的 API Secret。
| 字段 | 必填 | 说明 |
|---|---|---|
api_key | 是 | 接入账号的 API Key。 |
timestamp | 是 | Unix 秒级时间戳,允许和服务器时间相差 300 秒以内。 |
sign | 是 | 签名结果。签名前需要排除 sign 字段。 |
action | 否 | 接口动作。不传时默认为 check。 |
签名步骤
组装参数把本次请求所有参数放入同一个一维数组,不包含
sign。按字段名升序排序等同 PHP 的
ksort($params)。生成查询字符串等同 PHP 的
http_build_query($params),例如 action=check&api_key=xxx&risk_type=account。计算 HMAC-SHA256使用 API Secret 作为密钥,计算十六进制小写字符串。
签名参数建议全部使用字符串或数字,不要直接提交嵌套数组。凭证图片、多条信息可以用逗号分隔 URL 或 JSON 字符串放入单个字段。
风险主体类型
| risk_type | 含义 | risk_value 示例 |
|---|---|---|
account | 账号、手机号、买家账号等通用主体 | 175******05 |
ip | IP 地址 | 203.0.113.10 |
openid | 微信、公众号、小程序 OpenID | oAbc123... |
alipay_uid | 支付宝 UID | 2088xxxxxxxxxxxx |
device_ua | 设备 UA 或设备标识 | Mozilla/5.0 ... |
browser_fingerprint | 浏览器指纹 | fp_9d8c... |
当前接口会校验 risk_value 非空且长度不超过 512 个字符。
响应格式
成功HTTP 200,返回
code=0,业务数据在 data 中。认证失败HTTP 403,API Key 无效、账号禁用、时间戳过期或签名错误。
参数错误HTTP 422,风险类型不支持或必填字段缺失。
成功响应
{
"code": 0,
"msg": "success",
"data": {}
}
失败响应
{
"code": 403,
"msg": "签名校验失败"
}
黑名单检测
用于实时查询风险主体是否命中云黑名单。该接口每次成功进入检测流程会扣 1 个调用点数。
| 字段 | 必填 | 说明 |
|---|---|---|
action | 否 | 固定为 check,不传也默认为检测。 |
risk_type | 是 | 风险主体类型,见上方类型表。 |
risk_value | 是 | 需要检测的主体值。 |
请求示例
POST https://risk.618n.com/openapi/index.php
Content-Type: application/json
{
"action": "check",
"api_key": "your_api_key",
"timestamp": 1781880000,
"risk_type": "alipay_uid",
"risk_value": "2088052919594350",
"sign": "签名结果"
}
响应示例
{
"code": 0,
"msg": "success",
"data": {
"client": "接入方名称",
"hit": true,
"has_record": true,
"record_status": "active",
"detail": {
"id": 12,
"black_uuid": "xxxx-xxxx",
"risk_type": "alipay_uid",
"risk_value": "2088052919594350",
"black_level": 3,
"black_reason": "complaint",
"start_time": "2026-06-20 10:00:00",
"end_time": null,
"create_time": "2026-06-20 10:00:00"
},
"point_balance": 99
}
}
record_status 可能为 active、expired 或 none。业务拦截建议以 hit=true 为准。
提交投诉
用于把站点、订单、支付渠道或人工审核产生的投诉信息提交到云黑风险数据库。投诉提交后默认进入待审核状态,审核通过后可沉淀为风险记录。
| 字段 | 必填 | 说明 |
|---|---|---|
action | 是 | 固定为 complaint。 |
risk_type | 否 | 默认 account。建议支付宝 UID 使用 alipay_uid。 |
risk_value | 是 | 被投诉主体。未传时接口会尝试使用 buyer_account。 |
complainant_info | 是 | 投诉人、业务来源、站点名称、订单来源等信息。 |
complain_reason | 是 | 投诉原因,最多建议 1000 字以内。 |
complain_proof | 否 | 证据地址、截图 URL、日志 URL、工单链接等。 |
source_ref | 否 | 源系统唯一引用,推荐传。用于幂等更新,避免重复投诉。 |
complaint_no | 否 | 投诉单号。不传时自动生成 CP 开头的单号。 |
complaint_status | 否 | 投诉状态,默认 待处理。 |
complaint_type | 否 | 投诉类型,默认 -。 |
complaint_amount | 否 | 投诉金额,支持数字或带货币符号的字符串。 |
complaint_time | 否 | 投诉时间,格式建议 YYYY-MM-DD HH:mm:ss。 |
merchant_order_no | 否 | 商户订单号。 |
trade_no | 否 | 渠道交易号或支付平台交易号。 |
buyer_account | 否 | 买家账号。不要用订单号代替。 |
buyer_user_id | 否 | 买家用户 ID。没有真实用户 ID 时建议不传或传 -,不要用订单号代替。 |
merchant_name | 否 | 商户名称。 |
merchant_no | 否 | 商户编号。 |
complaint_desc | 否 | 投诉说明。不传时默认使用 complain_reason。 |
请求示例
{
"action": "complaint",
"api_key": "your_api_key",
"timestamp": 1781880000,
"risk_type": "alipay_uid",
"risk_value": "2088052919594350",
"complainant_info": "支付系统 / 支付宝投诉同步",
"complain_reason": "付款后无法进入游戏,用户申请退款",
"complain_proof": "https://example.com/proof/CP20260620001.png",
"source_ref": "alipay_complaint:21088922582",
"complaint_no": "21088922582",
"complaint_amount": "1998.00",
"complaint_time": "2026-06-20 10:35:07",
"merchant_order_no": "ZH2026031516520973909",
"trade_no": "2026031522001465071442176739",
"buyer_account": "177******06",
"buyer_user_id": "2088622888772806",
"merchant_name": "海南优安丰网络科技有限公司",
"merchant_no": "2088960257614664",
"complaint_desc": "充值的游戏,现在游戏登录不上去",
"sign": "签名结果"
}
响应示例
{
"code": 0,
"msg": "success",
"data": {
"client": "接入方名称",
"complaint_id": 188,
"complaint_no": "21088922582",
"created": true,
"audit_status": 0,
"message": "投诉已提交,等待审核"
}
}
幂等规则:优先按
source_ref 查找已有投诉并更新;没有 source_ref 时按投诉单号和接入方匹配。批量同步投诉时强烈建议传入稳定的 source_ref。同步站点黑名单
用于把本站已确认的黑名单同步到云黑风险数据库。适合从业务系统批量上传已有风险账号、IP、设备或支付宝 UID。
| 字段 | 必填 | 说明 |
|---|---|---|
action | 是 | 固定为 blacklist_sync。 |
risk_type | 是 | 风险主体类型。 |
risk_value | 是 | 风险主体值。 |
black_level | 否 | 风险等级,允许 1、2、3,默认 2,数字越高风险越高。 |
black_reason | 否 | 拉黑原因,允许 complaint、warning、system、manual,默认 system。 |
end_time | 否 | 有效期截止时间。空值表示永久有效。 |
complainant_info | 否 | 来源说明或投诉人信息。 |
complain_proof | 否 | 关联凭证。传入后会写入黑名单关联日志,等待核验。 |
请求示例
{
"action": "blacklist_sync",
"api_key": "your_api_key",
"timestamp": 1781880000,
"risk_type": "account",
"risk_value": "175******05",
"black_level": 3,
"black_reason": "complaint",
"end_time": "",
"complainant_info": "本站投诉审核通过",
"complain_proof": "https://example.com/order/10001",
"sign": "签名结果"
}
响应示例
{
"code": 0,
"msg": "success",
"data": {
"client": "接入方名称",
"black_id": 52,
"created": false,
"message": "云黑记录已更新"
}
}
签名代码示例
PHP
PHP 调用示例
<?php
$apiKey = 'your_api_key';
$apiSecret = 'your_api_secret';
$params = [
'action' => 'check',
'api_key' => $apiKey,
'timestamp' => time(),
'risk_type' => 'alipay_uid',
'risk_value' => '2088052919594350',
];
ksort($params);
$params['sign'] = hash_hmac('sha256', http_build_query($params), $apiSecret);
$ch = curl_init('https://risk.618n.com/openapi/index.php');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($params, JSON_UNESCAPED_UNICODE),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Node.js
Node.js 签名示例
const crypto = require('crypto');
const querystring = require('querystring');
function sign(params, secret) {
const sorted = Object.keys(params).sort().reduce((acc, key) => {
if (key !== 'sign') acc[key] = params[key];
return acc;
}, {});
return crypto.createHmac('sha256', secret)
.update(querystring.stringify(sorted))
.digest('hex');
}
const payload = {
action: 'complaint',
api_key: 'your_api_key',
timestamp: Math.floor(Date.now() / 1000),
risk_type: 'account',
risk_value: '175******05',
complainant_info: '业务系统',
complain_reason: '恶意投诉或欺诈交易'
};
payload.sign = sign(payload, 'your_api_secret');
安全与重试建议
密钥只放服务端不要把 API Secret 写入前端代码、移动端包、小程序或公开配置。
保持服务器时间准确签名时间戳只允许 300 秒误差,建议服务器开启 NTP 时间同步。
使用 source_ref 幂等投诉同步失败后可以重试,同一个
source_ref 会更新已有记录。不要混淆账号字段
buyer_account 和 buyer_user_id 必须传真实值,不要用订单号或交易号代替。限制批量频率批量同步建议分批执行,单批控制数量,失败记录单独重试。
保存请求日志业务侧建议保存请求参数、响应 code、msg 和本地 request_id,方便排查。