确认是本人 三个接口
接入支付宝实人认证:签名换凭证,提交姓名与身份证号,用户在支付宝里刷脸,回来查一次结果。
看接入流程姓名、身份证号、 一张脸。 我们只回答一个问题: 这个人, 是不是证件上的 那个人。
{ "passed": true }
查询接口最后只回这一个布尔值。订单、流水、状态,都是为它服务的。
从签名到结果
签名
在你的服务器上算出 Sign。这一步不发请求,也不该出现在浏览器里。
明文是三个字段,用 Secret 的 SHA-256 摘要当密钥,AES-256-ECB 加密后转成 Base64URL。 服务端要能解回时间戳,所以它是可逆加密,不是哈希。
- 拼明文:
Appid|Secret|时间戳,用竖线分隔。 - 算密钥:
SHA-256(Secret)的 32 字节二进制摘要,不是十六进制字符串。 - 用
AES-256-ECB加PKCS#7填充加密。 - Base64 后把
+换成-、/换成_,去掉末尾的=。
Appid 与 Secret 在控制台的应用详情页;Secret 泄露或丢失就在那里重置,旧的立即失效。
- Appid
YWV10001- Secret
e3b0••••••••1f24- 可用余额
¥1,286.00- 冻结金额
¥2.00- 认证单价
¥1.00 / 次- 状态
- 正常
$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), '+/', '-_'), '=');
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 小时,未使用也会过期。 它只能被消费一次,每次调业务接口前都重新换。
curl -s https://face.1wnt.cn/api/v1/credential \
-H 'Content-Type: application/json' \
-d '{"appid":"YWV10001","sign":"<第 1 步算出的 Sign>"}'
{
"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 |
退回的那笔是第一次认证未通过;结算只扣冻结,可用余额不变。
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"
}'
{
"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 |
提交失败 | 建单阶段调用支付宝失败,冻结金额退回 |
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,订单不会产生。认证未通过、过期、提交失败,冻结金额都会退回可用余额。
今日认证包含待认证的 1 笔。