数据合作 / 接口产品 / 银行卡ocr查询

银行卡ocr查询 2 BBN/次 （最终定价以商务协议为准）

接口描述：输入银行卡图片Base64编码后的字符串，返回银行卡ocr信息。

适用于：信息采集

申请试用
产品说明 接入指南 接口规范 通用返回码

1. 产品说明

参数输入要求

以下接口文档内，将对请求参数是否必填作出说明。

输入要求 英文名称 简写名称
必填 Must M
条件必填 Conditional C
选填 Optional O

1.1 产品介绍

输入银行卡图片Base64编码后的字符串，返回银行卡ocr信息。

1.2 请求参数示例

{
"productId":"C0901",
"customerId":"1522*****8140",
"cardPic":"/9j/4AAQSkZJRgABAQA***********"
}

1.3 请求参数说明

参数 类型 输入要求 参数名
productId String M 产品唯一编号
customerId String M 客户请求流水号，确保唯一
cardPic String M 银行卡图片Base64编码后的字符串

1.4 返回示例

以下仅为简单示例

查询成功

{

"result:{
"ocrResult":{
"bankCode":"03***000",
"cardName":"广发VISA信用卡",
"cardType":"贷记卡",
"bankName":"广发银行股份有限公司",
"cardNo":"62257****5319***"
},
"code":"1",
"message":"查询成功"
},
"code":"200",
"gid":"5ad***13****800",
"customerId":"1531*****4615",
"message":"查询成功",
"status":"2000"
}

参数为空或格式错误

{
"code":"400",
"gid":"5729acce280d800",
"customerId":"1529995168073",
"message":"参数为空或格式错误",
"status":"9804"
}

失败

{
"code":"500",
"gid":"5729acce280d800",
"customerId":"1529995168073",
"message":"渠道异常",
"status":"9902"
}

1.5 返回字段说明

节点名称 字段名 描述
code 返回码 参见2.附录
status 状态码 参见2.附录
message 状态信息 参见2.附录
gid 流水号 我方返回唯一id
customerId 客户请求流水号 原样返回
result 查询结果 见result节点说明

result节点说明

节点名称 字段名
code 银行卡卡号
cardName 银行卡名称
cardType 银行卡类型
bankCode 发卡行代号
bankName 发卡行名称

2. 附录

2.1 响应吗和状态码

响应码 状态码 状态信息 计费说明（Y/N）
200 2000 查询成功 Y
200 2004 查询失败 N
200 2005 不支持该笔查询 Y
200 9804 参数为空或格式错误 Y

2.2 通用响应码和状态码

响应码 状态码 状态信息
400 9800 账户不存在或被禁用
400 9801 访问资源不存在
400 9802 请求IP没有访问权限
400 9803 没有此产品访问权限
400 9804 参数为空或格式错误
400 9805 该帐号余额不足
400 9806 此接口请求次数达到上限
400 9807 报文解析错误
400 9808 验签失败
400 9809 查询时间区间不正确
400 9810 访问产品不存在
400 9811 标签没有权限访问
400 9812 密钥未配置或过期
400 9813 产品后台配置异常
500 9900 系统异常
500 9901 服务异常
500 9902 渠道异常
500 9903 请求超时

2.3 二级返回码

result.code result.message
1 查询成功
2 校验信息错误

接口接入指南，意在指导客户从完成账号申请，到接口接入主要步骤的说明。

1. 试用账号接入流程

1.1. 客户申请测试账号

客户需发送邮件，告知我方如下必备的信息，包含：公司名称、联系人姓名、联系人邮箱、联系人电话、报备公司访问 IP。

1.2. 运营人员审核

业务运营人员对客户资质做初步的审核。

1.3. 开通测试账号

客户资质审核通过后，由运营人员为客户开通账号，设置访问权限和访问次数等。并将测试账号的登录信息，以及接口对接需要的相关文档发送给客户。

2. 正式账号接入流程

2.1. 双方签署合作协议

双方商务对接人员，签署合作协议，明确接口可用的时间，调用的价格。

2.2. 合作款项到账通知

我方财务人员确认合作款项到账，并通知到业务部门。

2.3. 开通正式账号

业务运营人员为客户开通正式账号，配置接口可用时间和收费价格。并将正式账号的登录信息，以及接口对接需要的相关文档发送给客户。

接口地址URL https://<host> （见邮件）
参数编码 UTF-8 参数格式 JSON
请求方法 POST 协议类型 HTTPs
请求参数示例 { “account” : ”123456”, “data” : ”encrypted request data”, “sign” : ” 6C768121683C45ABD83546A73DBE3284” }
请求参数详情 account 账户号（我方分配给客户账户号）
data 密文数据主体（参数主体JSON数据(见4.1.2) RSA加密后字符串），加密流程见3.1.2
sign 签名（采用MD5加密account、data两个参数的值组成的字符串），签名规则见3.2
响应结果示例 { “encrypt” : true, “data” : ”encrypted response data”, “sign” : ” EE4D39671D825BA272D4D2540D095EF7” }
返回参数详情 encrypt 数据主体是否加密标识（当请求用户的账号无法获取时，数据主体不加密，该字段为false）
data 数据主体（数据主体原始响应内容由具体接口定义数据格式）,解密流程见3.1.3
sign 签名（采用MD5加密encrypt、data 两个参数的值组成的字符串），验签流程见3.2

1.数据加密/解密

接口传输的所有数据均使用RSA公钥对参数进行加密处理。

1.1. 生成秘钥（首次接入时）

# 生成私钥

openssl genrsa-out app_private_key.pem 2048

# Java开发者需要将私钥转换成PKCS8格式

openssl pkcs8-topk8 -inform PEM -in app_private_key.pem -outform PEM -nocrypt -outapp_private_key_pkcs8.pem

# 生成公钥

openssl rsa -in app_private_key.pem-pubout -out app_public_key.pem

上述三条命令执行完成后会生成开发者可以在当前文件夹中，看到app_private_key.pem（开发者RSA私钥）、app_private_key_pkcs8.pem（pkcs8格式开发者RSA私钥）和app_public_key.pem（开发者RSA公钥）3个文件。开发者将私钥保留，将公钥告知我方，用于加密返回参数。


* 注意：
* Java的开发者，将pkcs8文件中的私钥去除头尾、换行和空格，作为开发者私钥。

1.2. 请求参数加密

{
"name":"张三",
"mobile":"12345678910",
"cid":"421087000000000000",
"card":"622100000000",
"customerId":"201301011011290001"
}

使用我司对外公钥进行 RSA 加密，生产加密字符串作为请求参数作为data字段。

RSA_ENCRYPT_BY_PUBLIC_KEY("{\"name\":\"张三\",\"mobile\":\"12345678910\",\"cid\":\"421087000000000000\",\"card\":\"622100000000\",\"customerId\":\"201301011011290001\"}")

加密后data：

oSlffhJki585URCTnFagvhN2SfItSuzFG60NjQTQzWfB3BDMXg0/qqAaTLi0GWwpwRZrfWc1CxYgbL3AzCNcyn/2iyQVeQK0eWa50S9rMqIOUrX7jHYm3vXjqqX2LQQtRF2V8+S7K7JR0MBEO708HGsVDChERLetKJ9pRL3EfftFfl9zEFLhttfFQjLzeK9RNq+8bnf2PqJGBp4hwk0iNA9VajsH4vrNINuLNUiaJWmhklQbCMnU4WutIl+ttNhthOhOnsIYbQyFxVVmURlQwv7HniOjPouyi6OvRpZ2lHlFRo6N0DFqL8Biz71edDrG35LTzyX9w2XhKWicydfT2g==

请求报文：

{
"account":"123456",
"data":"
oSlffhJki585URCTnFagvhN2SfItSuzFG60NjQTQzWfB3BDMXg0/qqAaTLi0GWwpwRZrfWc1CxYgbL3AzCNcyn/2iyQVeQK0eWa50S9rMqIOUrX7jHYm3vXjqqX2LQQtRF2V8+S7K7JR0MBEO708HGsVDChERLetKJ9pRL3EfftFfl9zEFLhttfFQjLzeK9RNq+8bnf2PqJGBp4hwk0iNA9VajsH4vrNINuLNUiaJWmhklQbCMnU4WutIl+ttNhthOhOnsIYbQyFxVVmURlQwv7HniOjPouyi6OvRpZ2lHlFRo6N0DFqL8Biz71edDrG35LTzyX9w2XhKWicydfT2g==", "sign":"EE4D39671D825BA272D4D2540D095EF7"
}

说明：account 为我方分配给客户的账号。

1.3. 响应报文解密

返回报文：

{
"encrypt":true,
"data": "V1YIvvzEBufvnY1wcuEr4GB0YCrPbFiqm0lvQeBV9pXZairLit1aZBxUCYoC+mZ0y64tgY2hRX66JzrRLyWCohKWDfuevNhZOVmJRq+3sDoomEdzAz2WBsK2qvu+YjW43SyYrF1dXozbZn7OMAWSZC8rRc38vS++b+n3GoDsnQdOZ9ebTb/JdYz+Sq7h1GyUIgDmiuhLAvcs6k6+wG6Qvt7mNByZpOse49tlsfLzhusgesU1Y+wz0oDyKcEZfqR4rxR1++3MgB/x1viarSlow1ci71QU4a/uqgw3x5L1QqgrehLnANHH3Fx3XZG9Va2LSxr9oDnoc/cEylAHzqNaeA==",
"sign":"6BD20DF100F66C3D375A072CBF0DBC68"
}

解密业务数据

使用客户私钥进行 RSA 解密 data字段，返回业务返回数据。

RSA_DECRYPT_BY_PRIVATE_KEY("V1YIvvzEBufvnY1wcuEr4GB0YCrPbFiqm0lvQeBV9pXZairLit1aZBxUCYoC+mZ0y64tgY2hRX66JzrRLyWCohKWDfuevNhZOVmJRq+3sDoomEdzAz2WBsK2qvu+YjW43SyYrF1dXozbZn7OMAWSZC8rRc38vS++b+n3GoDsnQdOZ9ebTb/JdYz+Sq7h1GyUIgDmiuhLAvcs6k6+wG6Qvt7mNByZpOse49tlsfLzhusgesU1Y+wz0oDyKcEZfqR4rxR1++3MgB/x1viarSlow1ci71QU4a/uqgw3x5L1QqgrehLnANHH3Fx3XZG9Va2LSxr9oDnoc/cEylAHzqNaeA==")

解密后data：

{
"code":"200",
"status":"2000",
"message":"查询成功",
"result":"****",
"customerId":"201301011011290001",
"gid":"40d7be07-f40e-4021-ae92-9f9ff7b58db7"
}

2. 签名/验签机制

调用接口(API)时，服务器对请求参数进行签名验证，并对请求参数的格式进行正则验证，验证报文合法后才可以正常调用接口。

- 签名算法

签名采用 MD5算法。

- 生成待签名的字符串

把报文中待签名的参数名放入数组里，根据参数名从 a 到 z 的顺序排序，若遇到相同首字母，则看第二个字母，以此类推。排序完成之后，参数名与参数值连接起来，生成待签名字符串。

例如：

请求参数

"account": "123456"
"data":"oSlffhJki585URCTnFagvhN2SfItSuzFG60NjQTQzWfB3BDMXg0/qqAaTLi0GWwpwRZrfWc1CxYgbL3AzCNcyn/2iyQVeQK0eWa50S9rMqIOUrX7jHYm3vXjqqX2LQQtRF2V8+S7K7JR0MBEO708HGsVDChERLetKJ9pRL3EfftFfl9zEFLhttfFQjLzeK9RNq+8bnf2PqJGBp4hwk0iNA9VajsH4vrNINuLNUiaJWmhklQbCMnU4WutIl+ttNhthOhOnsIYbQyFxVVmURlQwv7HniOjPouyi6OvRpZ2lHlFRo6N0DFqL8Biz71edDrG35LTzyX9w2XhKWicydfT2g=="

连接后待签名字符串

account123456dataoSlffhJki585URCTnFagvhN2SfItSuzFG60NjQTQzWfB3BDMXg0/qqAaTLi0GWwpwRZrfWc1CxYgbL3AzCNcyn/2iyQVeQK0eWa50S9rMqIOUrX7jHYm3vXjqqX2LQQtRF2V8+S7K7JR0MBEO708HGsVDChERLetKJ9pRL3EfftFfl9zEFLhttfFQjLzeK9RNq+8bnf2PqJGBp4hwk0iNA9VajsH4vrNINuLNUiaJWmhklQbCMnU4WutIl+ttNhthOhOnsIYbQyFxVVmURlQwv7HniOjPouyi6OvRpZ2lHlFRo6N0DFqL8Biz71edDrG35LTzyX9w2XhKWicydfT2g==

- MD5运算后的签名结果

EE4D39671D825BA272D4D2540D095EF7

- 响应报文验签

用户得到响应结果时，仍按照上文方法生成待签名字符串，然后对其做MD5加签，加签结果与响应中的sign做比较，如果两者相同则验签通过，否则验签失败。

* 注意：
* 1：签名时字符均采用UTF-8编码；
* 2：接口请求采用HTTPS POST方式提交数据，参数无需做URLEncoding转码；

3. 异常响应

{
"code":"400",
"status":"9804",
"customerId":"150165535561065",
"gid":"2734ec87-339a-492a-8864-a375c36ba186",
"message":"参数为空或格式错误"
}

完整的异常响应码、状态码和错误提示信息，请参考附录

响应码 状态码 状态信息
400 9800 账户不存在或被禁用
400 9801 访问资源不存在
400 9802 请求IP没有访问权限
400 9803 没有此产品访问权限
400 9804 参数为空或格式错误
400 9805 该帐号余额不足
400 9806 此接口请求次数达到上限
400 9807 报文解析错误
400 9808 验签失败
400 9809 查询时间区间不正确
400 9810 访问产品不存在
400 9811 标签没有权限访问
400 9812 密钥未配置或过期
400 9813 产品后台配置异常
500 9900 系统异常
500 9901 服务异常
500 9902 渠道异常
500 9903 请求超时