银行卡识别接口接入教程：参数、请求示例与返回字段解读
在线开户、支付绑卡这类流程里，让用户手动输入一长串卡号既慢又容易出错。银行卡识别接口可以从图片中识别卡号与有效期，辅助录入和核对。本文从第一次调用写起：要准备什么、最小请求怎么发、返回值怎么看。
一、适用场景
- 在线开户：用户上传银行卡照片后自动填入卡号，减少手输错误。
- 支付绑卡辅助录入：识别后由用户确认，再进入后续流程。
- 卡号核对：用户提交的卡号与图片识别结果做一致性比对。
- 客服工单：用户上传卡面截图时，辅助提取关键信息。
注意：识别结果是“辅助录入”用的，最终仍应让用户确认，不要直接跳过人工确认环节。
二、接口能力边界
| 项目 | 说明 |
|---|---|
| 请求方法 | POST |
| 参数 | input_type、input_data |
| 识别内容 | 银行卡号、有效期 |
| 输入方式 | URL、Base64 两种 |
| 图片格式 | jpg、png |
| 文件大小 | 不超过 10MB |
| 识别效果 | 图片清晰、卡面完整时效果更好 |
需要明确：接口只识别卡号与有效期，不校验卡号真实性，也不做银行归属查询。识别成功不等于卡号有效，业务上仍需走各自的校验流程。
三、请求参数与鉴权
参数共两个：
| 参数 | 说明 |
|---|---|
input_type | 输入类型，区分 URL 与 Base64，具体取值以文档为准 |
input_data | 输入数据，与input_type对应 |
鉴权方式、请求头字段名与请求体编码，素材未给出，以文档为准。接入前请先在文档中确认 API Key 的传递位置。
调用前先做本地校验：文件格式是否为 jpg/png、大小是否在 10MB 以内、卡面是否完整。这三项能过滤掉大部分失败请求。
四、最小请求示例
下面是一个可复制的 curl 模板，YOUR_API_KEY、input_type取值与input_data内容均为占位，请按文档替换。
curl -X POST 'https://v1.apizero.cn/api/ocr-bank-card' \ -H 'Content-Type: application/json' \ -H 'Authorization: YOUR_API_KEY' \ -d '{ "input_type": "<按文档填写，区分 URL 与 Base64>", "input_data": "<图片 URL 或 Base64 字符串>" }'对应的 Python 调用示例，用本地图片转 Base64 后提交：
import base64 import requests def read_bank_card(image_path: str, input_type: str, api_key: str) -> dict: with open(image_path, "rb") as f: raw = f.read() if len(raw) > 10 * 1024 * 1024: raise ValueError("图片超过 10MB") input_data = base64.b64encode(raw).decode("utf-8") resp = requests.post( "https://v1.apizero.cn/api/ocr-bank-card", headers={"Authorization": api_key}, json={"input_type": input_type, "input_data": input_data}, timeout=15, ) resp.raise_for_status() return resp.json()如果使用 URL 方式，只需把input_data换成可公网访问的图片地址，input_type按文档对应取值。
五、返回值解读
素材说明返回“卡号与有效期”，具体字段名以文档为准。接入时建议按以下方式处理：
- 读取卡号字段，去掉识别结果中的空格，再做长度与数字格式校验。
- 读取有效期字段，格式（如 MM/YY 或 MM/YY 以外的形式）以文档为准，展示前统一格式化。
- 任一字段缺失时按“识别不完整”处理，引导用户重拍或手动输入。
一个防御式解析示例（字段名请替换为文档中的实际名称）：
def parse_card(payload: dict) -> dict: data = payload.get("data") or {} number = (data.get("number") or "").replace(" ", "") # 字段名以文档为准 expiry = data.get("expiry") or "" # 字段名以文档为准 ok = number.isdigit() and 12 <= len(number) <= 19 return {"number": number, "expiry": expiry, "complete": ok}卡号长度按行业常见范围做宽松校验即可，不要用固定 16 位硬卡，避免误杀其他卡种。
六、常见错误与排查
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 鉴权失败 | Key 缺失或位置错误 | 核对请求头，以文档为准 |
| 参数错误 | input_type与input_data不匹配 | 按文档确认取值与数据形式 |
| 文件过大 | 图片超过 10MB | 上传前压缩或裁剪 |
| 格式不支持 | 非 jpg/png | 转码后再提交 |
| 识别为空 | 卡面模糊、倾斜、遮挡 | 提示用户重拍，保证卡面完整 |
| 超时 | 图片过大或网络抖动 | 设置超时，压缩图片后重试 |
识别为空通常是图片质量问题，不是接口故障。把它映射为“请重试拍摄”的提示，比直接报错更友好。
七、工程化注意事项
- 前端预校验：在客户端就限制格式与大小，减少无效请求。
- 用户确认：识别结果填入表单后仍需用户确认，不要自动提交。
- 敏感数据：卡号属于敏感信息，日志中必须脱敏，Base64 图片不要落盘。
- 传输安全：Base64 会放大体积，大图优先用 URL 方式，避免请求体过大。
- 重试策略：只对超时和 5xx 做有限次重试，识别为空不重试。
- 有效期展示：统一格式化后再展示，避免不同来源格式不一致。
参考文档
- 接口文档