【银行卡认证】银行卡4要素核身

接口描述

对个人银行卡四要素信息进行核验，成功后向手机号发送验证码，需要调用【银行卡认证】预留手机号校验接口进行验证码回填，回填成功才算完成了核身认证。

【注】核身认证无需提前为用户创建账号；

接口

/v2/identity/auth/api/individual/bankCard4Factors

请求方式

POST

请求头

提供两种安全接入方式，对应参数如何获取，参考文档【请点击】。

方式一：请求签名鉴权（优先推荐）

参数名称	类型	必选	参数说明
X-Tsign-Open-App-Id	string	是	应用ID
Content-Type	string	是	application/json;charset=UTF-8
X-Tsign-Open-Ca-Timestamp	string	是	API 调用者传递时间戳，值为当前时间的毫秒数，也就是从1970年1月1日起至今的时间转换为毫秒，时间戳有效时间为15分钟，为了防重放攻击
Accept	string	是	建议统一填写 /
X-Tsign-Open-Ca-Signature	string	是	签名字符串
Content-MD5	string	否	当请求 Body 非 Form 表单时，可以计算 Body 的 MD5 值传递给云网关进行 Body MD5 校验。建议当请求 Body 非 Form 表单时，加上此请求头。
X-Tsign-Open-Auth-Mode	string	是	选择请求方式进行鉴权，固定值：Signature

方式二：OAuth2.0鉴权（不推荐使用）

当安全接入选择OAuth2.0鉴权方式，请点击查阅详情。

请求参数

参数名称	参数类型	必选	参数位置	参数说明
name	string	是	body	姓名
certType	string	否	body	个人证件类型 INDIVIDUAL_CH_IDCARD - 中国大陆身份证（默认值） INDIVIDUAL_CH_TWCARD - 台湾来往大陆通行证（台胞证） INDIVIDUAL_CH_HONGKONG_MACAO - 港澳来往大陆通行证（回乡证） INDIVIDUAL_PASSPORT - 护照 INDIVIDUAL_CH_RESIDENCE_PERMIT_HK_MO_TW - 港澳台居民居住证（18位810开头） INDIVIDUAL_CH_OFFICER - 军官证（单个汉字/大写字母+字第+4-8位数字+号，例如：军字第2001998号） INDIVIDUAL_CH_POLICE - 警官证（开头是数字/字母，总共位数为6-7位） INDIVIDUAL_CH_PRIVATES - 士兵证（”士“/大写字母Z+字第+4-8位数字+号，例如：Z字第1004853号）
idNo	string	是	body	个人证件号
mobileNo	string	是	body	手机号（仅限中国大陆11位手机号）
bankCardNo	string	是	body	银行卡号（仅限印有“银联”字样的银行卡）
contextId	string	否	body	自定义业务标识，将在异步通知及跳转时携带返回对接方
notifyUrl	string	否	body	认证结束后异步通知地址,具体见"异步通知"章节说明
grade	string	否	body	指定银行卡4要素信息比对结果详情 ADVANCED - 详情版（核验失败时会返回具体不匹配信息） STANDARD - 普通版（默认值）【注】详情版：需要单独购买，具体购买方式请咨询e签宝工作人员；普通版：信息比对核验失败，不会返回具体的不匹配信息。
source	int	否	body	指定银行卡4要素信息比对来源，默认0
				0 - 权威库比对；对用户4要素进行权威数据源的比对，收取银行卡4要素信息比对费用
				1 - 可信数据比对；可信核身数据有效期内，直接发送短信验证码，仅收取短信费用，若无可信数据，接口会报错（限在当前appId下做过银行卡4要素核身认证，一年内可以免除信息比对，直接发送验证码场景使用，并且需保证姓名、身份证号、银行卡号和手机号四者与之前的认证数据完全一致）
				2 - 优先策略比对；优先进行可信数据源比对，若无可信数据，则进行权威库比对（为了避免直接使用 “1- 可信数据比对”造成接口报错，建议传2，由e签宝自动判断）

响应参数

展开全部参数参数名称（点击左侧“+”一键展开）			类型	必选	参数说明
code			int32	是	业务码，0表示成功，非0表示异常。
message			string	是	错误信息请根据 code 来判断错误情况，不应该依赖message匹配，因为 message 可能会调整。
data			object	否	业务信息
	flowId		string	否	认证流程ID
	behavior		object	否	本次核身认证流程行为数据【注】仅在请求参数source指定：1或2时返回该对象
	source	int	否	本次核身认证数据来源： 0 - 权威库比对：银行卡4要素信息比对 + 短信验证 1 - 可信数据比对：短信验证
	refFlowId	string	否	关联的权威库认证完成的核身流程（响应参数source为1时该参数返回值）
	refFlowTime	int64	否	关联的refFlowId核身认证完成时间，unix时间戳（毫秒）格式
	refFlowExpired	int64	否	关联的refFlowId核身认证流程的有效期截止时间，unix时间戳（毫秒）格式

请求示例

{
    "name": "**",
    "idNo": "320926xxxxxxxx5276",
    "mobileNo": "188xxxx8888",
    "bankCardNo": "622260026xxx1072444",
    "contextId": "f0a7927dxxxx1130d86c8fa8",
    "notifyUrl": "http://172.xx.xx.10:8080/notify/msgRecive",
    "grade": "ADVANCED",
    "source": 2
}

响应示例

信息比对来源source（请求参数）为1或者2场景：

{
    "code": 0,
    "message": "成功",
    "data": {
        "flowId": "3324******62174",
        "behavior": {
            "source": 1,
            "refFlowId": "3324*******4318",
            "refFlowTime": 1712890819000,
            "refFlowExpired": 1744426819000
        }
    }
}

信息比对来源source（请求参数）为0场景：

{
    "code": 0,
    "message": "成功",
    "data": {
        "flowId": "33244*******493"
    }
}

错误码

错误码	错误描述	解决方案
30500000	操作出错,请联系服务人员处理, ID:XXXX	请核实入参格式是否正确
30500101	参数错误：请输入正确长度的姓名（2-20位）	请输入真实有效的姓名
30500101	参数错误：姓名只支持中文/点符号·/半角逗号	请输入真实有效的姓名（与证件类型保持一致）
30500101	参数错误：请输入正确的身份证号码	请输入真实有效的证件号（与证件类型保持一致）
30500101	参数错误：请输入正确的证件类型!	请输入正确的证件类型枚举值（certType）
30500101	参数错误：证件号格式错误	请输入真实有效的证件号（与证件类型保持一致）
30500101	参数错误：请输入正确的手机号码	请输入真实有效的银行卡预留手机号
30500101	参数错误：请输入正确的银行卡号	请输入真实有效的银行卡号
30500101	参数错误：姓名不能为空	请输入真实有效的姓名
30500101	参数错误：手机号不能为空	请核实手机号是否为空
30500101	参数错误：身份证号码不能为空	请核实身份证号是否为空
30500101	参数错误：银行卡号不能为空	请核实银行卡号是否为空
30501001	银行卡四要素信息核验失败，请核实银行相关信息的准确性	银行卡号与个人信息不匹配
30501001	手机号与身份证号不⼀致	请检查手机号开户对应的身份信息是否与当前信息一致
30501001	姓名与⾝份证号不⼀致	请检查姓名和证件号是否匹配
30501001	银行卡号与身份证号不一致	请检查银行卡开户时的身份信息与当前信息是否一致
30500116	格式校验不通过，请检查填入信息是否有多余空格	请核实入参是否存在空格
30503107	很抱歉，订单余额不足	请核实是否有购买认证服务套餐，认证套餐是否生效，以及对应子服务是否开通。
30500056	无法核实身份，可信核身流程不存在，请将source切换到0或者2后重新发起	该用户信息在近一年内没有通过该接口做过银行卡4要素信息比对的核身认证，不能指定source为1
30500100	缺少参数：source类型不支持	请输入正确的信息比对来源枚举值（source）