云黑风险开放文档 获取密钥
Risk Cloud Blacklist Open API

接入云黑名单检测,并提交投诉信息进入审核

本文档说明业务系统如何接入 618N 风险云黑中心,包括 API Key/Secret 签名认证、黑名单检测、投诉提交、站点黑名单同步,以及服务端调用示例。

接口地址
https://risk.618n.com/openapi/index.php

接入流程

创建接入账号管理员在云黑风险后台创建接入用户,启用账号后生成 API Key 和 API Secret。接入方也可以登录用户中心查看配置。
服务端保存密钥API Secret 只允许保存在后端服务,不要下发到浏览器、小程序、App 客户端或公开仓库。
生成签名并调用接口每次请求带上 api_keytimestampsign,服务端会校验签名和时间戳。
按业务场景调用支付、注册、登录前可调用黑名单检测;产生交易投诉或欺诈证据时调用提交投诉接口;站点已有黑名单可调用同步接口。
推荐使用后端服务通过 HTTPS POST JSON 调用接口。接口也兼容表单参数和 URL Query 参数,但签名字段必须覆盖最终提交的所有业务参数。

签名认证

所有接口都必须携带认证字段。签名算法为 HMAC-SHA256,密钥为接入账号的 API Secret。

字段必填说明
api_key接入账号的 API Key。
timestampUnix 秒级时间戳,允许和服务器时间相差 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
ipIP 地址203.0.113.10
openid微信、公众号、小程序 OpenIDoAbc123...
alipay_uid支付宝 UID2088xxxxxxxxxxxx
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 可能为 activeexpirednone。业务拦截建议以 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风险等级,允许 123,默认 2,数字越高风险越高。
black_reason拉黑原因,允许 complaintwarningsystemmanual,默认 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_accountbuyer_user_id 必须传真实值,不要用订单号或交易号代替。
限制批量频率批量同步建议分批执行,单批控制数量,失败记录单独重试。
保存请求日志业务侧建议保存请求参数、响应 code、msg 和本地 request_id,方便排查。