调用VerifyBankElement接口发起银行卡OCR或二三四要素认证请求-阿里云帮助中心

调用VerifyBankElement接口发起银行卡OCR或二三四要素认证请求。

传入图片格式要求

图片大小：图片大小建议不超过2 MB。图片过大可能会影响接口响应速度，甚至可能导致读取图片超时失败。
图片格式：PNG、JPG、JPEG。
图片分辨率：图片长宽需要大于64像素且小于8192像素。
图片质量要求：图片模糊、内容遮挡、光线或图片角度异常都可能会对识别结果产生影响；在识别身份证人像面时，需要确保人脸呈现正向。

接口说明

接口名称：VerifyBankElement。

服务地址：cloudauth.cn-shanghai.aliyuncs.com（上海地域）或cloudauth.cn-beijing.aliyuncs.com（北京地域）。

请求方法：POST和GET。

传输协议：HTTPS。

接口描述：该接口支持以下四种认证方式：

银行卡照片OCR识别：通过银行卡照片识别出银行卡号。
银行卡二要素认证：识别银行卡号和用户的真实姓名是否匹配。
银行卡三要素认证：识别银行卡号和用户的真实姓名、身份证号是否匹配。
银行卡四要素认证：识别银行卡号和用户的真实姓名、身份证号、手机号是否匹配。

关于以上四种认证方式的必选请求参数，如下表所示。

表 1. 四种方式的必选请求参数说明

认证方式	SceneId	OuterOrderNo	Mode	IdName	IdNo	Mobile	BankCardUrl和BankCardFile
银行卡照片OCR识别	是	是	是 Mode取值为OCR_BANK_CARD。	否	否	否	否
银行卡二要素认证	是	是	是 Mode取值为OCR_VERIFY_BANK_CARD。	是	否	否	是 BankCardUrl和BankCardFile二选一。
			是 Mode取值为VERIFY_BANK_CARD。	是	否	否	否
银行卡三要素认证	是	是	是 Mode取值为OCR_VERIFY_BANK_CARD。	是	是	否	是 BankCardUrl和BankCardFile二选一。
			是 Mode取值为VERIFY_BANK_CARD。	是	是	否	否
银行卡四要素认证	是	是	是 Mode取值为OCR_VERIFY_BANK_CARD。	是	是	是	是 BankCardUrl和BankCardFile二选一。
			是 Mode取值为VERIFY_BANK_CARD。	是	是	是	否

请求参数

名称	类型	是否必选	示例值	描述
SceneId	Long	是	100000xxxx	认证场景ID。您必须先在增强版实人认证控制台创建认证场景，才能获得认证场景ID。更多信息，请参见添加认证场景。
OuterOrderNo	String	是	e0c34a77f5ac40a5aa5e6ed20c35xxxx	商户服务端自定义的业务请求唯一标识，用于后续定位排查问题使用，由32位字母、数字组合而成。
Mode	String	是	OCR_BANK_CARD	银行卡卡证核身的模式。取值： OCR_BANK_CARD：银行卡照片OCR识别模式。表示通过传入的银行卡照片，识别出银行卡号。 OCR_VERIFY_BANK_CARD：银行卡OCR照片识别+认证模式。表示通过传入的银行卡照片识别出银行卡号，将银行卡号和用户的真实姓名、身份证号、手机号进行匹配。该模式用于银行卡二、三、四要素认证方式。 VERIFY_BANK_CARD：银行卡认证模式。表示将传入的银行卡号和用户的真实姓名、身份证号、手机号是否匹配。该模式用于银行卡二、三、四要素认证方式。
BankCardNo	String	否	54121234567xxxxx	银行卡号。当Mode取值为VERIFY_BANK_CARD时，BankCardNo为必选参数。
IdName	String	否	张三	用户的真实姓名。当Mode取值为OCR_VERIFY_BANK_CARD或VERIFY_BANK_CARD时，IdName为必选参数。
IdNo	String	否	330103xxxxxxxxxxxx	用户的身份证号码。当使用银行卡三、四要素认证方式时，IdNo为必选参数。
BankCardUrl	String	否	https://www.aliyun.com/cert.jpeg	证件地址，公网可访问的HTTP、HTTPS链接。当Mode取值为OCR_BANK_CARD或OCR_VERIFY_BANK_CARD时，BankCardUrl和BankCardFile二选一。
BankCardFile	InputStream	否	无	本地证件文件。当Mode取值为OCR_BANK_CARD或OCR_VERIFY_BANK_CARD时，BankCardUrl和BankCardFile二选一。
Mobile	String	否	1301234xxxxx	用户的手机号。当使用银行卡四要素认证方式时，Mobile为必选参数。

返回数据

名称	类型	示例值	描述
RequestId	String	130A2C10-B9EE-4D84-88E3-5384FF039795	请求ID。
Message	String	success	请求信息的响应消息。
Code	String	200	返回码。关于返回码的具体介绍，请参见Code和Message说明。
ResultObject	Object		认证主体信息。ResultObject是一个结构体，关于ResultObject的结构描述，请参见ResultObject。

表 2. ResultObject

名称	类型	示例值	描述
Passed	String	T	认证是否通过，取值： T：通过。 F：不通过。说明如果接口异常或接口是未认证状态，则不返回该参数。
SubCode	String	200	认证结果码。关于认证结果码的具体介绍，请参见SubCode。
CertifyId	String	08573be80f944d95ac812e019e3655a8	认证请求ID，认证请求的唯一标识。
MaterialInfo	String	{"BankCardNo": "54121234567xxxxx"}	认证主体的卡证信息识别结果。OcrBankCardInfo是一个结构体，关于OcrBankCardInfo的结构描述，请参见OcrBankCardInfo。

表 3. OcrBankCardInfo

名称	类型	示例值	描述
BankCardNo	String	54121234567xxxxx	银行卡号。

表 4. SubCode

SubCode	是否计费	描述
200	是	认证通过。
201	是	实名校验不通过。认证不通过。可能导致失败的原因：用户的身份信息不匹配、信息有误或查询不到身份信息。
202	是	查询不到身份信息。认证不通过。可能导致失败的原因：用户发生户口迁移、用户为军人等特殊状态。建议预留人工审核入口，用于人工审核。
203	是	认证信息不一致，银行卡未开通认证支付。
204	是	认证信息不一致，银行卡已过期。
205	是	认证信息不一致，银行卡为受限制的卡。
206	是	认证信息不一致，此卡被没收。
207	是	认证信息不一致，银行卡无效。
208	是	认证信息不一致，此卡无对应发卡行。
209	是	认证信息不一致，该卡未初始化或睡眠卡。
210	是	认证信息不一致，此卡为作弊卡、吞卡。
211	是	认证信息不一致，此卡已挂失。
212	是	认证信息不一致，密码错误次数超限。
213	是	认证信息不一致，发卡行不支持此交易。
214	是	认证信息不一致，卡状态不正常或卡无效。
215	是	认证信息不一致，未预留手机号。
216	是	认证信息不一致，输入的密码、有效期或CVN2有误。
217	是	认证信息不一致，其他卡异常情况。
218	是	无法验证，银行卡不支持该业务。
219	是	无法验证，验证失败或银行拒绝验证，请联系发卡行。
220	是	无法验证，银行卡暂不支持手机号验证。
221	是	无法验证，银行卡号有误。
222	是	无法验证，验证次数超限。

Code和Message说明

Code	Message	描述
200	success	接口响应成功。
400	参数不能为空	参数不能为空。
401	参数非法	传入的字段不符合取值范围或长度不符合要求。
403	异常重复调用	异常重复调用次数超限。
410	未开通服务	未开通OSS产品或未完成OSS读写授权，请登录增强版实人认证控制台完成授权。
411	RAM无权限	需要为RAM用户授予AliyunYundunCloudAuthFullAccess的操作权限。
412	欠费中	增强版实人认证服务或OSS对象存储服务存在欠费，请充值后再进行操作。
420	数据重复	请求参数中BankCardUrl和BankCardFile二选一。
428	格式校验错误	传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母或特殊字符。
500	系统错误	系统内部错误，请通过智能在线联系阿里云工程师协助排查。