意玩云数 实人认证

确认是本人 三个接口

接入支付宝实人认证:签名换凭证,提交姓名与身份证号,用户在支付宝里刷脸,回来查一次结果。

看接入流程

姓名、身份证号、 一张脸。 我们只回答一个问题: 这个人, 是不是证件上的 那个人。

{ "passed": true }

查询接口最后只回这一个布尔值。订单、流水、状态,都是为它服务的。

从签名到结果

  1. 签名 本机计算 你的服务器 · 不到 1 毫秒

    在你的服务器上算出 Sign,这一步不发请求。

  2. 换凭证 /api/v1/credential 你的服务器 · 约 100 毫秒

    一个 HTTPS 请求,换回一个只能用一次的 token。

  3. 建单 /api/v1/certify/create 你的服务器 · 不到 1 秒

    冻结余额,拿到支付宝的跳转地址。

  4. 用户刷脸 支付宝客户端 用户的手机 · 1~3 分钟

    用户跳去支付宝,这一步不经过你,也最慢。

  5. 查结果 /api/v1/certify/query 你的服务器 · 约 200 毫秒

    回来查一次,只看 passed 是真还是假。

签名

在你的服务器上算出 Sign。这一步不发请求,也不该出现在浏览器里。

明文是三个字段,用 Secret 的 SHA-256 摘要当密钥,AES-256-ECB 加密后转成 Base64URL。 服务端要能解回时间戳,所以它是可逆加密,不是哈希。

  1. 拼明文:Appid|Secret|时间戳,用竖线分隔。
  2. 算密钥:SHA-256(Secret) 的 32 字节二进制摘要,不是十六进制字符串。
  3. 用 AES-256-ECB 加 PKCS#7 填充加密。
  4. Base64 后把 + 换成 -、/ 换成 _,去掉末尾的 =。

Appid 与 Secret 在控制台的应用详情页;Secret 泄露或丢失就在那里重置,旧的立即失效。

控制台 · 应用凭证
Appid
YWV10001
Secret
e3b0••••••••1f24
可用余额
¥1,286.00
冻结金额
¥2.00
认证单价
¥1.00 / 次
状态
正常
生成 Sign · PHP
$appid  = 'YWV10001';
$secret = 'e3b0c44298fc1c149afbf4c8996fb924';
$time   = time();   // 10 位秒级时间戳

$key    = hash('sha256', $secret, true);   // 32 字节二进制摘要
$plain  = $appid . '|' . $secret . '|' . $time;
$cipher = openssl_encrypt($plain, 'AES-256-ECB', $key, OPENSSL_RAW_DATA);

$sign = rtrim(strtr(base64_encode($cipher), '+/', '-_'), '=');
生成 Sign · Node.js
import crypto from 'node:crypto';

const appid  = 'YWV10001';
const secret = 'e3b0c44298fc1c149afbf4c8996fb924';
const time   = Math.floor(Date.now() / 1000);

const key    = crypto.createHash('sha256').update(secret, 'utf8').digest();
const cipher = crypto.createCipheriv('aes-256-ecb', key, null);
const buf    = Buffer.concat([
  cipher.update(`${appid}|${secret}|${time}`, 'utf8'),
  cipher.final(),
]);

const sign = buf.toString('base64')
  .replace(/\+/g, '-')
  .replace(/\//g, '_')
  .replace(/=+$/, '');

服务器时间,东八区

签名里的时间戳和它相差超过 300 秒,会直接返回 10003。

换凭证

拿 Appid 和 Sign 换一个一次性 token。

参数 必填 说明
appid 是 应用标识,必须与签名里的一致
sign 是 第 1 步算出的 Sign,Base64URL 编码、不带 = 填充

token 是 64 位十六进制字符串,有效期 2 小时,未使用也会过期。 它只能被消费一次,每次调业务接口前都重新换。

请求 · POST /api/v1/credential
curl -s https://face.1wnt.cn/api/v1/credential \
  -H 'Content-Type: application/json' \
  -d '{"appid":"YWV10001","sign":"<第 1 步算出的 Sign>"}'
响应 · 200
{
  "code": 0,
  "msg": "ok",
  "data": {
    "token": "8f3c1b0a6d2e4f5a9b7c8d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a",
    "expires_in": 7200,
    "expires_at": "2026-11-14 23:50:36"
  }
}

建单

提交姓名与身份证号,换一个只能在支付宝里打开的地址。

参数 必填 说明
appid 是 应用标识,必须与凭证所属 Appid 一致
name 是 姓名,2~50 字,支持中文、字母和 ·
id_card 是 身份证号,18 位(含校验码)或 15 位老号码
return_url 否 认证完成后的回跳地址,必须 http/https,不超过 2048 字符;不传则用服务端默认值

这一步按应用单价冻结余额,余额不够直接返回 402,订单不会产生。 代价只有认证通过时才真正扣掉。

控制台 · 余额流水(同一个订单)
时间 类型 金额 可用 冻结
21:50 冻结 −¥1.00 ¥1,286.00 ¥3.00
21:51 退回 +¥1.00 ¥1,287.00 ¥2.00
21:54 冻结 −¥1.00 ¥1,286.00 ¥3.00
21:56 结算 −¥1.00 ¥1,286.00 ¥2.00

退回的那笔是第一次认证未通过;结算只扣冻结,可用余额不变。

请求 · POST /api/v1/certify/create
curl -s https://face.1wnt.cn/api/v1/certify/create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "appid": "YWV10001",
    "name": "张三",
    "id_card": "11010519491231002X",
    "return_url": "https://example.com/certify/return"
  }'
响应 · 200
{
  "code": 0,
  "msg": "ok",
  "data": {
    "out_order_no": "YW2026111421503612AB34CD56EF",
    "certify_id": "2109b5e671aa3ff2eb4851816c65828f",
    "url": "https://openapi.alipay.com/gateway.do?app_id=...&sign=..."
  }
}

url 是一次性的认证地址,只在支付宝客户端里有效;PC 站点请把它转成二维码。 两个单号都留着:out_order_no 对账用,certify_id 查结果用。

用户刷脸

用户带着那个地址去支付宝,剩下的不经过你。

页面跳到支付宝后,用户完成人脸核验。整个环节没有任何回调打到你这边—— 用户中途关掉页面,订单就停在待认证,两小时后自动过期并把冻结金额退回。

不要在客户端判断结果,也不要在这一跳里改自己的业务数据。等用户回来,再查一次。

回跳页面上的结果,一个都不算。

return_url 只是浏览器跳转,参数可以伪造,也可能根本不发生。 它唯一的作用是让用户回到你的页面;订单状态只由查询接口和定时任务推进。

查结果

查询这张单据在支付宝侧的最新状态。

参数 必填 说明
appid 是 应用标识,必须与凭证所属 Appid 一致
certify_id 是 建单返回的支付宝单据号,8~64 位字母或数字

单据必须是这个 Appid 建的,跨应用查询一律 404。 用户还没做完时返回 status=pending、passed=false、finished=false; 已经到终态的订单直接返回库里的结果,不会重复调用支付宝,也不会重复结算。

status 含义 说明
passed 已通过 支付宝返回 passed=T,冻结金额结算为收入
rejected 未通过 有明确失败原因,冻结金额退回可用余额
pending 待认证 用户还没完成,继续等或稍后再查
expired 已过期 超过本地有效期(默认 2 小时),冻结金额退回
failed 提交失败 建单阶段调用支付宝失败,冻结金额退回
请求 · POST /api/v1/certify/query
curl -s https://face.1wnt.cn/api/v1/certify/query \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{"appid":"YWV10001","certify_id":"2109b5e671aa3ff2eb4851816c65828f"}'
响应 · 已通过
{
  "code": 0,
  "msg": "ok",
  "data": {
    "out_order_no": "YW2026111421503612AB34CD56EF",
    "certify_id": "2109b5e671aa3ff2eb4851816c65828f",
    "status": "passed",
    "passed": true,
    "finished": true,
    "fail_reason": "",
    "finished_at": "2026-11-14 21:52:10",
    "queried_at": "2026-11-14 21:52:11"
  }
}
控制台 · 最近订单
时间 姓名 / 证件号 状态 金额
21:56 张* · 110105********002X 已通过 ¥1.00
21:51 李* · 310101********1234 未通过 ¥0.00
21:50 王* · 440301********5678 待认证 ¥1.00

未通过的那笔冻结金额已退回,金额显示为 0。

错误码

业务码在响应体的 code 里,HTTP 状态码同时按类目返回。先看 code,再看 msg。

通用

  • 10001 400 参数缺失、格式错误、身份证号校验失败
  • 10005 429 同一 IP 请求过于频繁
  • 10006 404 接口路径不存在
  • 10007 405 请求方式不对,接口只接受 POST
  • 10500 500 服务端异常,稍后重试

凭证

  • 10002 401 Sign 解密失败、明文不匹配或 Appid 不存在
  • 10003 401 时间戳超出 ±300 秒,先校准服务器时间
  • 10004 403 应用已停用或已到期
  • 10008 401 凭证缺失、已使用过,或与 Appid 不匹配
  • 10013 403 应用所属账号已停用

认证

  • 10009 402 可用余额不足,订单没有创建
  • 10010 502 支付宝调用失败:网络异常、返回码非 10000 或验签失败
  • 10011 404 单据不存在,或不属于这个 Appid
  • 10012 410 单据已失效,需要重新发起认证

常见问题

凭证能重复使用吗?

不能。每个 token 只能被消费一次,调用成功或失败之后立即作废。并发时只有一个请求能成功,其余返回 10008。所以每次调用业务接口前都重新换一个,不要缓存。

用户从支付宝跳回来,就算认证通过了吗?

不算。回跳是浏览器行为,参数可以伪造,也可能根本不发生(用户中途关页面)。唯一依据是查询接口的 passed = true,订单状态只由查询和定时任务推进。

签名一直返回 10003 是怎么回事?

时间戳必须是 10 位秒级 Unix 时间,而且与服务器相差不超过 300 秒。容器时钟漂移、误传了毫秒时间戳、服务器没开 NTP,都会命中这个错误。

身份证号会存明文吗?

不会。落库前就转成 张* 与 110105********002X,另存一份 HMAC 摘要用于对账和去重,明文只在内存里拼进支付宝请求,不写日志。

什么时候该去查结果?

用户回跳后立刻查一次;没有回跳的,从建单起 60 秒后开始轮询,间隔逐步拉长。超过 2 小时仍未完成的订单由定时任务关闭,冻结金额退回。

余额不足会建出半个订单吗?

不会。建单时先冻结,余额不够直接返回 402,订单不会产生。认证未通过、过期、提交失败,冻结金额都会退回可用余额。

接好之后,这些都在控制台里

应用、余额、订单结果、每一笔冻结与退回,都在同一个页面里,对得上账。

打开控制台
控制台 · 概览
应用 2
可用余额 ¥1,286.00
冻结金额 ¥2.00
今日认证 12

今日认证包含待认证的 1 笔。