1. 接口说明

银行卡识别，通过全球领先的 OCR（光学字符识别 Optical Character Recognition）技术，自动对银行卡进行识别，返回银行卡原件上的银行卡卡号、有效日期、发卡行、卡片类型（借记卡&信用卡）、持卡人姓名（限信用卡）等信息，可以省去用户手动录入的过程，自动完成银行卡信息的结构化和图像数据的采集，可以很方便对接客户的后台数据系统，给用户带来极大的便利。采特有的图像处理技术，在识别银行卡图片过程中，还可以对银行卡图片上的卡号图像，方便用户保存。

2. 接口地址

POST http[s]://webapi.xfyun.cn/v1/service/v1/ocr/bankcard HTTP/1.1
Content-Type:application/x-www-form-urlencoded; charset=utf-8

3. 请求参数

在 Http Request Header 中配置授权认证参数，见【接口描述-授权认证】。其中 X-Param 为各配置参数组成的JSON串经BASE64编码之后的字符串，原始JSON串各字段说明如下：

参数	类型	必须	说明	示例
engine_type	string	是	引擎类型，固定为bankcard	bankcard
card_number_image	string	否	是否返回卡号区域截图，默认为0，如果设为 1，则返回base64编码的卡号区域截图。	0
imei	string	否	手机序列号	12345678
osid	string	否	操作系统版本	Android
ua	string	否	厂商\|全称\|机型信息\|操作系统版本\|分辨率	vivo\|vivoY67L\|PD1612\|ANDROID6.0\|720*1280

X-Param生成示例：

原始JSON串：
{
    "engine_type": "bankcard",
    "card_number_image": "0"
}
BASE64编码（即X-Param）：
eyJlbmdpbmVfdHlwZSI6ICJiYW5rY2FyZCIsImNhcmRfbnVtYmVyX2ltYWdlIjogIjAifQ==

在 Http Request Body 中配置以下参数：

参数	类型	必须	说明	示例
image	string	是	图像数据，base64编码后进行urlencode，要求base64编码和urlencode后大小不超过4M，仅支持jpg格式，推荐 jpg 文件设置为：尺寸 1024×768，图像质量 75 以上，位深度 24。	exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf…

_注：_base64编码后大小会增加约1/3

4. 返回值

返回值为json串，各字段如下：

参数	类型	说明
code	string	结果码(具体见错误码)
data	json	详见data说明
desc	string	描述
sid	string	会话ID

其中sid字段主要用于追查问题，如果出现问题，可以提供sid给讯飞技术人员帮助确认问题。

data各字段说明如下：

参数	说明	备注
type	银行卡类型	银行卡的类型判断（贷记卡，借记卡，准贷记卡）
card_number	银行卡号	银行卡上的银行卡号码识别结果
validate	有效期	信用卡上的有效期识别结果
holder_name	持卡人	银行卡信用卡上的持卡人姓名识别结果
issuer	发卡机构	银行卡发卡机构返回结果
card_number_image	卡号区域截图	银行卡卡号区域图片，base64编码
error_code	错误码	识别错误码
error_msg	错误信息	错误原因描述

其中的error_msg和error_code的取值范围及说明对照表：

error_code	error_msg	说明
0	ok	正常返回
40001	invalid parameter	参数不对
40002	missing parameter	缺少参数
40003	invalid user or password	账号或密码不对
40004	missing request body	没有HTTP body
40005	invalid image format	HTTP body不是图像或者不支持该格式
40006	invalid image size	图片太大或太小
40007	fail to recognize	识别失败
40008	invalid content type	通过HTTP form上传图片时，Content-Type无效
40009	corrupted request body	请求body损坏
40010	fail to extract image	提取图像裸数据失败
50001	backend down	后台服务器宕机
50004	timeout	识别超时
90099	unknown	未知错误

结果示例如下：

失败结果：

{
    "code": "10106",
    "desc": "invalid parameter|invalid X-Appid",
    "data": "",
    "sid": "wcr0000bb3f@ch3d5c059d83b3477200"
}

成功结果：

{
"code": "0",
"data": {
    "card_number": "6258 0001 0097 9974",
    "error_code": 0,
    "error_msg": "ok",
    "holder_name": "LI YUAN",
    "issuer": "招商银行信用卡中心",
    "issuer_id": "03080010",
    "type": "贷记卡",
    "validate": "04/22"
},
"desc": "success",
"sid": "wcr00000003@dx11730e797b8a000100"
}

4.1. 错误码

error_code	error_msg	说明
0	ok	正常返回
40001	invalid parameter	参数不对
40002	missing parameter	缺少参数
40003	invalid user or password	账号或密码不对
40004	missing request body	没有HTTP body
40005	invalid image format	HTTP body不是图像或者不支持该格式
40006	invalid image size	图片太大或太小
40007	fail to recognize	识别失败
40008	invalid content type	通过HTTP form上传图片时，Content-Type无效
40009	corrupted request body	请求body损坏
40010	fail to extract image	提取图像裸数据失败
50001	backend down	后台服务器宕机
50004	timeout	识别超时
90099	unknown	未知错误

5. 调用示例