芝麻实名认证 API

基于支付宝芝麻信用人脸识别的实名认证服务 · 为其他网站提供 API 调用

管理后台

简介

本系统对接支付宝芝麻认证（人脸识别），为第三方网站提供统一的实名认证 API 服务。第三方网站通过分配的 app_key 和 app_secret 调用接口，实现姓名 + 身份证号 + 人脸识别的实名认证。

认证流程：
1. 调用方 POST /api/init.php 发起认证 → 获得 certify_url
2. 调用方将用户引导至 certify_url 完成人脸识别
3. 调用方 POST /api/query.php 查询认证结果（或等待异步通知）

鉴权说明

所有 API 请求需在 HTTP Header 中携带以下参数：

Header说明
X-App-Key应用 Key（管理后台分配）
X-Timestamp当前时间戳（秒），5分钟内有效
X-Sign签名，算法见下方

签名算法：

sign = md5( app_key + timestamp + body字符串 + app_secret )

示例：
app_key    = zm_xxxxxxxxxxxxxxxx
timestamp  = 1697000000
body       = {"out_order_no":"ORDER001","name":"张三","id_card":"110101199001011234"}
app_secret = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

待签名字符串 = "zm_xxxxxxxxxxxxxxxx1697000000{\"out_order_no\":\"ORDER001\",\"name\":\"张三\",\"id_card\":\"110101199001011234\"}xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
sign = md5(待签名字符串)

接口列表

POST /api/init.php — 发起实名认证

请求参数（JSON Body）：

参数必填说明
out_order_no是商户订单号，调用方唯一
name是真实姓名
id_card是身份证号
phone否手机号
return_url否认证完成回跳地址，不传用应用配置

响应示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "out_order_no": "ORDER001",
    "biz_no": "ZM202310101234567890",
    "certify_url": "https://zmopenapi.zmxy.com.cn/..."
  }
}
拿到 certify_url 后，将用户重定向到该 URL 完成人脸识别。
POST /api/query.php — 查询认证结果

请求参数（JSON Body）：

参数必填说明
out_order_no二选一商户订单号
biz_no二选一芝麻业务号

响应示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "out_order_no": "ORDER001",
    "biz_no": "ZM202310101234567890",
    "name": "张三",
    "id_card": "1101**********1234",
    "status": "success",
    "passed": true,
    "fail_reason": "",
    "certified_at": "2023-10-10 12:34:56"
  }
}

status 取值：pending 待认证 / success 成功 / fail 失败

PHP 调用示例

function apiSign($appKey, $timestamp, $body, $appSecret){
    return md5($appKey . $timestamp . $body . $appSecret);
}

$appKey    = 'zm_xxxxxxxxxxxxxxxx';
$appSecret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$timestamp = time();
$body = json_encode([
    'out_order_no' => 'ORDER' . time(),
    'name'         => '张三',
    'id_card'      => '110101199001011234',
], JSON_UNESCAPED_UNICODE);
$sign = apiSign($appKey, $timestamp, $body, $appSecret);

$ch = curl_init('https://your-domain.com/api/init.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-App-Key: ' . $appKey,
    'X-Timestamp: ' . $timestamp,
    'X-Sign: ' . $sign,
]);
$resp = curl_exec($ch);
curl_close($ch);

$result = json_decode($resp, true);
if ($result['code'] === 0) {
    // 重定向用户到刷脸页面
    header('Location: ' . $result['data']['certify_url']);
}

异步通知（回调）

支付宝在用户完成认证后，会异步通知 /api/notify.php，系统自动验签并更新认证状态。如需通知到接入方业务系统，可在应用配置中填写 callback_url。

© 芝麻实名认证 API 系统