# 1、Return_url 和 Notify_url 回调

说明：客户在GetToken方法中传入的 return_url 和 notify_url 会在完成 FinAuth Lite 人脸核身后被系统回调。其中

return_url：可通过设置action_http_method选择Post方法或者Get方法回调，直接通过页面跳转实现；

notify_url：会通过Post方法回调，由FinAuth后台发起调用。出于安全性考虑，FinAuth验证服务对服务器端回调端口有白名单要求，支持的端口有：443，5000，16003，8883，8028（如果回调地址不是HTTPS的，则推荐进行签名校验）。

1.1、采用Post回调的内容为一个form格式数据，具体的内容如下表所示：

字段	类型	说明	示例
data	String	人脸核身返回值（json格式），具体见返回值说明
sign	String	数据段的签名签名方法为 sign = sha1(API_SECRET + json_data)，其中sha1返回的字符均为小写签名方法为hmac_sha256，sign = sha256(API_SECRET + json_data)，其中sha256返回的字符均为小写	ac041f49940c5afb2640a251633a8029ae69c1d5

# 返回值说明

参数	类型	说明	示例
request_id	String	API 调用的流水号	"1462259763, e2d2f8d6-204b-4c43 -92ea-1d62b071f83c"
biz_info	Json	包含：biz_id, biz_no, biz_extra_data biz_id：业务流串号，可以用于反查比对结果 biz_no：客户业务流水号，会在notify和return时原封不动的返回给客户 biz_extra_data：在调用 notify_url 和 return_url 时会返回的额外数据用户可以用此接口来传递一些额外信息。	{ "biz_extra_data": "...", "biz_id": "1462259748, 52b13fb5-8dfb-4537 -a62b-a641d5e929f1", "biz_no": "cc47190f-5502-44a2 -ab74-ea4f0f649f61" }
time_used	Int	整个请求所花费的时间，单位为毫秒，此字段必定返回	100
result_code	Int	表示本次验证的结果状态码；可结合result_code和result_message字段知晓具体的结果及原因： 1000系列状态码表示比对完成，活体验证通过，比对通过 2000系列状态码表示比对完成，活体验证通过，比对不通过 3000系列状态码表示在比对的时候，数据源调用情况 4000系列状态码表示活体验证不通过 6000系列状态码表示流程状态相关错误其他结果，请预留处理方案，对于未来可能的错误，我们可能持续增加错误码	1000
result_message	String	可通过此字段信息知晓具体的原因。具体见：result_code & result_message 对照表	SUCCESS
idcard_info	Json	身份证识别的结果，此字段在idcard_mode = 0时不返回；如果用户中途中断了活体流程，则此字段也不返回内容包括： idcard_number：表示最终经过用户确认的身份证号（根据idcard_uneditable_field可能被修改过） idcard_name：表示最终经过用户确认的姓名（根据idcard_uneditable_field可能被修改过） idcard_valid_date：表示最终经过用户确认的身份证有效期（根据idcard_uneditable_field可能被修改过，如果不用拍摄身份证国徽面则不返回此字段） idcard_issued_by：表示最终经过用户确认的身份证签发机关（根据idcard_uneditable_field可能被修改过，如果不用拍摄身份证国徽面则不返回此字段） front_side：身份证人像面的识别结果（如果不用拍摄身份证人像面则不返回此字段） ocr_result：文字识别结果，详见【FinAuth Ocridcard API】 back_side：身份证国徽面的识别结果（如果不用拍摄身份证国徽面则不返回此字段） ocr_result：文字识别结果，详见【FinAuth Ocridcard API】 ocr_front_quality：身份证人像面各字段质量判断及逻辑判断结果 ocr_back_quality：身份证国徽面各字段质量判断及逻辑判断结果	{ "idcard_number": "xxxxxx19910602xxxx", "idcard_name": "陈AB", "idcard_valid_date": "2010.11.13-2020.11.13", "idcard_issued_by": "北京市公安局", "front_side": { "ocr_result": { "address": "北京市海淀区XXXX", "birthday": { "day": "2", "month": "6", "year": "1991" }, "gender": "男", "id_card_number": "xxxxxx19910602xxxx", "name": "陈XX", "race": "汉", "legality": { "ID Photo": 0.855, "Temporary ID Photo ":0, "Photocopy": 0.049, "Screen": 0.096, "Edited": 0 } }, "upload_times": 1 }, "back_side": { "ocr_result": { "issued_by": " 北京市公安局海淀分局", "valid_date": "2010.11.13-2020.11.13", "legality": { "ID Photo": 0.855, "Temporary ID Photo ": 0, "Photocopy": 0.049, "Screen": 0.096, "Edited": 0 } }, "upload_times": 2 }, "ocr_front_quality": { "gender": { "quality": 0.925, "logic": 0, "result": "男" }, "address": { "quality": 0.958, "logic": 0, "result": "xxx" }, "idcard_number": { "quality": 0.995, "logic": 0, "result": "xxxx" }, "name": { "quality": 0.996, "logic": 0, "result": "张三" }, "birth_month": { "quality": 0.971, "logic": 0, "result": "8" }, "birth_day": { "quality": 0.975, "logic": 0, "result": "31" }, "nationality": { "quality": 0.959, "logic": 0, "result": "汉" }, "birth_year": { "quality": 0.942, "logic": 0, "result": "1996" } }, "ocr_back_quality": { "issued_by": { "quality": 0.994, "logic": 0, "result": "xxxxx" }, "valid_date_end": { "quality": 0.995, "logic": 0, "result": "xxxx" }, "valid_date_start": { "quality": 0.995, "logic": 0, "result": "20140515" } } }
liveness_result	Json	活体检测结果；如果用户中途中断了活体流程，则此字段不返回 procedure_type：返回本次活体所使用的活体验证方式： flash：通过炫彩活体方式进行活体验证 active_flash：通过灵动活体方式进行活体验证 distance：通过距离活体方式进行活体验证 still：通过实时静默活体方式进行活体验证 video：通过自拍有声视频方式进行活体验证 still_record：通过自拍一段人脸视频进行活体认证 "result"：Bool类型，取值True或者False。代表云端攻击判断的结果，False代表不是攻击，True代表是攻击 "score"：Float类型，取值［0,1]。代表攻击的分数，分数越高表明攻击的可能性越大 "threshold"：Float类型，取值［0,1]。代表攻击的阈值注：云端采用默认策略是判断score >= threshold时，代表此次可能是攻击	"liveness_result":{ "procedure_type": "flash", "result": false, "score": 0, "threshold": 0.5 }
verify_result	Json	人脸比对结果；如果用户中途中断了活体流程或comparison_type为-1（仅活体不比对）等情况，则此字段不返回 result_kyc：人脸核身的综合分数 "confidence"：综合分数的置信度，Float类型，取值［0，100］，数字越大表示风险越小 “thresholds”：一组用于参考的置信度阈值，Object类型，包含四个字段，均为Float类型、取值［0，100］： “1e-3”：风险为千分之一的置信度阈值 “1e-4”：风险为万分之一的置信度阈值 “1e-5”：风险为十万分之一的置信度阈值 “1e-6”：风险为百万分之一的置信度阈值 result_ref[x]：活体采集人像与上传的image_ref[x]的比对结果（同result_kyc） result_idcard_photo：活体采集人像与身份证照片上的人脸比对的结果（同result_kyc） result_idcard_datasource：身份证照片上的人脸和参考比对数据照片比对的结果（同result_kyc） verify_time：验证发生的时间戳（单位：秒），仅当return_verify_time=1时返回该字段	{ "verify_time": 1462259763, "result_kyc": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } }, "result_ref1": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } }, "result_idcard_photo": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } }, "result_idcard _datasource": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } } }
verify_risk_info	Json	visual_attributes：性别年龄预估结果： “age”：预估核验人活体图年龄 “gender”：预估核验人活体图性别 “age_image_ref1”：预估比对参照人脸图年龄（仅comparison_type=0时返回） “gender_image_ref1”：预估比对参照人脸图性别（仅comparison_type=0时返回）比对风险提示结果： "verify_info_tags"：Json类型；表示活体图与比对图的比对风险 "is_gender_risk"：String类型，0：表示活体图与比对图性别一致；1：表示活体图与比对图性别不一致（comparison_type=1，则活体图与身份证性别比对；comparison_type=0，则活体图与ref1图性别比对，comparison_type=-1，则返回为空）； "is_age_risk"：String类型，0：表示活体图与比对图年龄差异不大（10岁以内）；1：表示活体图与比对图年龄差异较大（一般指的是年龄差距在10岁及以上，具体根据阈值设定。comparison_type=1，则活体图与身份证年龄比对；comparison_type=0，则活体图与ref1图年龄比对，comparison_type=-1，则返回为空）； “multifaces_tag”：String类型，表示是否检测到多人脸 0：单人脸 1：多人脸	"visual_attributes": { "gender": 0, "age": 31, "age_image_ref1": 22, "gender_image_ref1": 0 }， "verify_risk_info": { "verify_info_tags": { "is_gender_risk": 0, "is_age_risk": 0 } }
device_risk_info	Json	设备风险检测结果： device_info_level：string类型 none：表示未检测到风险 middle:表示中风险需要人工复核 high：表示高风险直接拦截 device_info_tags: is_cookies_disabled COOKIES 被禁用 is_code_tampered 代码被篡改 is_virtual_browser 虚拟浏览器 is_debug_mode 调试模式 is_higher_device_risk_threshold 高于设备风险阈值	"device_risk_info": { "device_info_level": "none", "device_info_tags": { "is_cookies_disabled": "0", "is_higher_device_risk_threshold": "0", "is_debug_mode": "0", "is_virtual_browser": "0", "is_code_tampered": "0" } }

# result_code & result_message 对照表

result_code	result_message	含义解释	是否计费
1000	SUCCESS	验证成功	是，详细计费请咨询商务
2000	PASS_LIVING_NOT_THE_SAME	通过了活体检测，但是经过验证，待比对照片与其他照片中的至少一张，不是同一个人	是
3000	NO_ID_CARD_NUMBER	无此身份证号	是
3000	ID_NUMBER_NAME_NOT_MATCH	证件号码和姓名不匹配	是
3000	NO_FACE_FOUND	姓名和身份证号码正确，但照片没有检测到人脸	是
3000	NO_ID_PHOTO	找不到参考照片	是
3000	PHOTO_FORMAT_ERROR	参考照片格式错误	是
3000	DATA_SOURCE_ERROR	参考数据出现错误	否
3000	INTERNAL_ERROR	服务器内部错误	否
4000	FAIL_LIVING_FACE_ATTACK	活体验证失败	是
6000	NOT_STARTED	验证未开始	否
6000	PROCESSING	验证进行中	否
6000	FAILED	验证流程异常结束	否
6000	CANCELLED	用户主动取消	否
6000	TIMEOUT	验证超时	否
6100	SUPPORT_ERROR	浏览器不支持webRTC API	否
6100	PERMISSIONS_ERROR	用户拒绝摄像头权限或浏览器（APP）不支持唤起摄像头权限	否
6100	OTHER_ERROR	其他异常导致的webRTC连接错误	否

1.2、采用Get回调时会在return_url地址拼接biz_id参数，请提取地址中拼接的biz_id用于作为get_result的入参。

示例：

●https://yourdomainname/xxx?biz_id=xxx

●https://yourdomainname/xxx?xxx=xxx&biz_id=xxx

●https://yourdomainname/xxx?biz_id=xxx&xxx=xxx#xxx

参数	类型	说明	示例
biz_id	String	通过get_token返回的活体业务编号	146225974852b13fb5-8dfb-4537-a62b-a641d5e929f1