实名认证接口怎么选：H5 刷脸 vs 支付宝核身

平台的实名认证提供两条通道，都是标准 RESTful 接口调用，但适用人群和体验不太一样。选错了会白白拉低通过率。

一、先看结论（对照表）

维度	H5 刷脸	支付宝核身
入口	/api/id/verify/h5	/api/id/verify/alipay
用户要准备什么	只有手机/电脑 + 摄像头	需要有实名一致的支付宝账号
体验	跳转到 H5 页做动作/眨眼刷脸	唤起支付宝 App 核身，通常更快
适合谁	大多数场景、PC 端、无支付宝用户	移动端为主、用户普遍有支付宝
典型卡点	光线差、遮挡、动作不到位	支付宝实名信息与填写的姓名/证件不一致

二、怎么调用

发起认证：POST /api/id/verify，返回一个实名页地址，把用户引导过去即可；也可以直接指定通道：

POST /api/id/verify/h5    // H5 刷脸
POST /api/id/verify/alipay  // 支付宝核身

Authorization: Bearer {API_KEY}
Content-Type: application/json

{"name":"张三","id_number":"110101199001011234","callback_url":"https://你的站点/id-notify"}

用户完成后，你可以：

• 用 POST /api/id/verify/query 按订单号查结果；
• 或者配置 callback_url，结果自动回调给你。

三、常见失败原因（按出现频率）

1. 姓名 / 证件号填错或不一致 —— 最常见的失败，先核对这两项；
2. 环境问题：光线太暗/太亮、戴帽子口罩、镜头脏；
3. 动作没做到位：眨眼/转头幅度不够，超时；
4. 支付宝通道：用户的支付宝实名信息与本次填写的姓名/证件不一致（比如帮别人认证）；
5. 证件本身状态异常：过期、注销。

四、计费与对账

• 按次计费，平台给每个账号有免费次数（用于自测），超出后按次扣额度；
• 每次认证都会生成订单号 + 调用流水，控制台「实名认证记录」和「调用日志」都能查；
• 对账时用订单号关联；有疑问把流水号发给客服查上游。

五、该选哪个？

• 网站 / PC 端为主 → 用 H5 刷脸（不依赖支付宝）；
• App / 移动端、用户普遍有支付宝 → 用 支付宝核身，体验更顺；
• 不确定 → 两个都开放给用户选，通过率最高。