## 人脸核身 > 通过支付宝或微信扫码进行人脸实名认证。  >[danger]### 无论是网站、小程序还是APP客户端，在运营过程中，都会面临国内的互联网监管压力，这个时候对用户进行实名认证是必备功能，`ThinkAPI`最新推出的人脸核身接口可以最大程度的简化开发工作，通过优雅SDK一键对接支付宝和微信实人认证，而且比直接使用支付宝或微信官方的认证更具高性价比。 ## 功能介绍 1. 通过传递姓名+身份证号码返回认证地址，用户可以生成二维码进行扫码认证，认证结果可以异步回调或主动查询 2. 支持支付宝和微信 3. 支持网站、H5、App和小程序 4. 适用于社区、电商、游戏、直播、金融等需要用户实名认证的场景。 ## 认证流程 1. 传递用户姓名和身份证号码（这一环节可以通过身份证OCR识别或用户输入的方式获取） 2. 调用接口生成支付宝或微信认证地址 3. 根据认证地址生成二维码展示在页面或App客户端 4. 用户打开支付宝或微信扫码完成实人认证 5. 通过异步回调或主动查询接口查询认证接口 ## 接口1：认证地址生成 用户输入自己的身份证姓名和身份证号码，选择（支付宝/微信）模式后调用该接口，接口返回认证链接，用户通过该链接进行刷脸认证 ### 接口费用 （[点击购买](https://market.topthink.com/product/495)） > 最低 0.42元/次 > ### 请求地址 ``` GET https://api.topthink.com/face/detect ``` ### 请求参数 | 名称 | 必填 | 类型 | 说明 | | --- | --- | --- | --- | | appCode| 是 | string|用户授权码，参考[API调用](https://docs.topthink.com/think-api/1835086) | | idcard | 是 |string|身份证号（大陆二代身份证） | | name | 是 |string|姓名 | | callbackUrl | 是 |string|认证成功后重定向地址，网页端接入可以直接传入网页地址，app接入传入app schema地址 | | notifyUrl | 是 |string|认证结束后异步通知接口,具体见异步通知说明 | | faceauthMode | 是 |string|**ZHIMACREDIT** 支付宝认证 **WECHAT** 微信认证（生成只有微信客户端可以打开的链接） | >[danger] 支付宝里传了`callbackUrl`时，认证完成后会跳出支付宝，打开一个外部浏览器打开`callbackUrl`，如果希望避免跳出支付宝的话，可以传一个不存在的`schema`地址。 ### 返回`data`参数 | 请求参数 | 参数说明 | 示例 | | --- | --- | --- | | orderNumber | 认证业务订单号 | b2f526e4e60ee4c48e880a798e65e96a | | requestId | 请求记录ID | ER20221223113141254085 | | status | 初步认证状态 | true | | originalUrl | 获取个人刷脸实名认证长链接。可以自己生成短网址避免二维码生成数据太多 | [https://open.weixin.qq.com/connect/oauth2/authorize?appid=wx1f7125112b74db52&redirect\_uri=https%3A%2F%2Fopen.faceid.qq.com%2Fv1%2Fapi%2FCode%3FbizRedirect%3Dhttps%253A%252F%252Ffaceid.qq.com%252Fapi%252Fauth%252FgetOpenidAndSaveToken%253Ftoken%253D7FBAF4F7-4F1A-4561-9937-C852E623763A&response\_type=code&scope=snsapi\_base&state=&component\_appid=wx9802ee81e68d6dee#wechat\_redirect](https://open.weixin.qq.com/connect/oauth2/authorize?appid=wx1f7125112b74db52&redirect_uri=https%3A%2F%2Fopen.faceid.qq.com%2Fv1%2Fapi%2FCode%3FbizRedirect%3Dhttps%253A%252F%252Ffaceid.qq.com%252Fapi%252Fauth%252FgetOpenidAndSaveToken%253Ftoken%253D7FBAF4F7-4F1A-4561-9937-C852E623763A&response_type=code&scope=snsapi_base&state=&component_appid=wx9802ee81e68d6dee#wechat_redirect) | | expire | 链接失效时间,毫秒值 结果依据实际的刷脸方式为准：**支付宝 30分钟 微信 2小时** | 1671773501745 | >[danger] 建议保存返回的`orderNumber`数据，便于后期回调或查询处理认证结果。 ### SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->faceDetect() ->withIdcard('身份证号码') ->withName('真实姓名') ->withCallbackUrl('认证成功后重定向地址') ->withNotifyUrl('异步通知回调地址') ->withFaceauthMode('ZHIMACREDIT') ->request(); dump($result); ``` 返回数据示例： ``` { "code": 0, "data": { "orderNumber": "45d35c36e36dfe9938jh9115c32a387a", "requestId": "ER20221223113141254502", "status": true, "originalUrl": "https://open.weixin.qq.com/connect/oauth2/authorize?appid=wx1f7125112b74db52&redirect_uri=https%3A%2F%2Fopen.faceid.qq.com%2Fv1%2Fapi%2FgetCode%3FbizRedirect%3Dhttps%253A%252F%252Ffaceid.qq.com%252Fapi%252Fauth%252FgetOpenidAndSaveToken%253Ftoken%253D7FBAF4F7-4F1A-4561-9937-C852E6238523A&response_type=code&scope=snsapi_base&state=&component_appid=wx9802ee81e68d6dee#wechat_redirect", "expire": "1671773501745" }, "message": "Success" } ``` >[danger] 返回`code`为0时计费。 ### 异步通知说明 认证业务在认证流程成功结束或失败时（实名认证成功触发异步通知），会通过流程发起时指定的notifyUrl参数，向调用方发送异步通知。 目前通过HTTP协议，以POST方法进行通知调用； 开发者对于异步回调通知只需通过POST方式进行接收即可，认证结果以实际POST方式接收的异步通知为准。 **通知参数如下**： application/json;charset=UTF-8 | 请求参数 | 类型 | 参数说明 | | --- | --- | --- | | requestId | String | 请求业务ID | |orderNumber|String| 业务订单号| | isSuccess | Boolean | 认证结果：true、认证成功； false 、认证失败 | ## 接口2：查询认证结果 根据用户输入认证业务订单号查询认证结果 ### 请求地址 ``` GET https://api.topthink.com/face/query ``` ### 请求参数： | 请求参数 | 参数说明 | 示例 | 是否必填 | | --- | --- | --- | --- | | orderNumber | 认证业务订单号 | b2f526e4e60ee4c48e880a798e65e96a | 是 | ### 返回参数： | 请求参数 | 参数说明 | 示例 | | --- | --- | --- | | name | 姓名 | 张三 | | idcard | 身份证 | 331081158456138512 | | status | 认证状态 | 0：认证中；1：认证成功‘2：认证不匹配’ | ## SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->faceQuery() ->withOrderNumber('b2f526e4e60ee4c48e880a798e65e96a') ->request(); dump($result); ``` ### 返回示例： ``` {     "code": "0",     "data": {         "status": 1,         "name": "张三",         "idcard": "331081158456138512"     },     "message": "认证成功" } ```