适用场景
银行卡BIN（Bank Identification Number）即银行卡号的前6位数字，用于唯一标识发卡行、卡产品类型和卡品牌。在实际业务中，银行卡BIN查询API可以用于以下场景：
- 支付风控：在用户绑卡或支付前，校验卡类型（借记卡/贷记卡）和发卡行，拦截高风险或不合规的卡片。
- 用户体验优化：根据卡BIN自动识别银行名称和品牌，在支付页面展示对应银行的Logo，减少用户输入错误。
- 对账与清算：在财务系统中根据BIN归属银行进行资金路由或手续费计算。
- 身份辅助验证：部分场景下通过BIN信息辅助判断卡片所属国家或地区。
接口能力边界
本接口通过GET方法接收银行卡号前6位（BIN），返回该BIN对应的发卡行名称、卡类型（借记卡/贷记卡/准贷记卡）、卡品牌（Visa、MasterCard、银联等）以及是否支持境外交易等元数据。
需要明确的限制：
- 仅支持中国境内主流银行发行的银行卡BIN（银联、Visa、MasterCard等品牌在华发行的卡片）。
- 单用户QPS上限为20次/秒，超出将被限流。
- 数据来源为公开的BIN表，更新频率以文档说明为准。
- 返回结果中的部分字段可能因卡片联合品牌或银行内部变更而存在延迟，建议作为辅助信息而非唯一决策依据。
鉴权方式与请求参数
鉴权方式
API采用密钥对鉴权（API Key），需要在HTTP请求头中携带X-API-Key字段。密钥获取途径请参阅官方文档（https://apizero.cn/aidocs/bank-card）。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
X-API-Key | Header | string | 是 | 你的API密钥 |
card | Query | string | 是 | 银行卡号前6位数字（例如622848） |
请求地址：https://v1.apizero.cn/api/bank-card?card={bin}
示例请求：
https://v1.apizero.cn/api/bank-card?card=622848curl 示例：一次完整的请求
以下是一个可直接复制运行的curl命令，注意将$APIZERO_API_KEY替换为你自己的密钥：
curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/bank-card?card=622848"如果密钥已设置环境变量，上述命令可直接执行。返回结果是一个JSON对象，包含code、message和data字段。
多语言代码接入
Python 示例
使用Python的requests库，代码简洁且可处理异常：
import requests def query_bank_bin(bin_code: str, api_key: str) -> dict: """ 查询银行卡BIN信息 :param bin_code: 银行卡号前6位 :param api_key: API密钥 :return: 解析后的JSON对象 """ url = "https://v1.apizero.cn/api/bank-card" headers = {"X-API-Key": api_key} params = {"card": bin_code} try: resp = requests.get(url, headers=headers, params=params, timeout=10) resp.raise_for_status() # 非200时抛出异常 return resp.json() except requests.exceptions.RequestException as e: print(f"请求失败: {e}") return None # 使用示例 if __name__ == "__main__": # 请替换为真实密钥 api_key = "your_api_key_here" result = query_bank_bin("622848", api_key) if result: print(result)Java 示例（使用 OkHttp）
import okhttp3.*; import java.io.IOException; public class BankBinQuery { public static void main(String[] args) throws IOException { String apiKey = "your_api_key_here"; String bin = "622848"; OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://v1.apizero.cn/api/bank-card?card=" + bin) .addHeader("X-API-Key", apiKey) .get() .build(); Response response = client.newCall(request).execute(); if (response.isSuccessful()) { System.out.println(response.body().string()); } else { System.err.println("请求失败，状态码: " + response.code()); } } }返回字段解读
正常响应示例（以code=200为例）：
{ "code": 200, "message": "success", "data": { "bank": "中国农业银行", "card_type": "借记卡", "card_brand": "银联", "is_luhn_valid": true, "card_number_length": 19 } }| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 业务状态码，200表示成功 |
message | string | 状态描述，成功时为"success" |
data.bank | string | 发卡行名称，如"中国农业银行" |
data.card_type | string | 卡类型："借记卡"、"贷记卡"或"准贷记卡" |
data.card_brand | string | 卡品牌："银联"、"Visa"、"MasterCard"等 |
data.is_luhn_valid | bool | 该BIN所属卡号是否通过Luhn算法校验（仅供参考） |
data.card_number_length | int | 该BIN对应的标准卡号长度（通常为16或19） |
注：实际返回字段可能根据文档版本调整，以上字段为常见示例。具体请以官方文档为准。
常见错误与排查
| HTTP状态码 | 错误场景 | 排查思路 |
|---|---|---|
| 400 | 请求参数缺失或格式错误 | 检查card参数是否为纯数字且长度是否至少为6位 |
| 401 | 未提供API Key或Key无效 | 检查X-API-Key头是否正确，密钥是否过期 |
| 403 | 密钥无权限（如未绑定IP白名单） | 登录控制台检查API调用权限与白名单配置 |
| 429 | 请求频率超过QPS限制（20/s） | 降低调用频率，增加本地缓存或指数退避重试 |
| 500 | 服务端内部错误 | 稍后重试，若持续出现请提交工单 |
业务错误示例（JSON中code非200）：
{ "code": 40001, "message": "BIN不存在或不支持", "data": null }常见业务错误码：
40001：输入的BIN未在数据库中收录，请确认卡号前6位是否正确。40002：BIN格式非法（包含非数字字符）。
工程化注意事项
- 缓存策略：同一BIN的查询结果通常不会频繁变更，可以在应用层缓存24小时。使用内存缓存（如Python的
functools.lru_cache）或Redis，减少API调用次数，降低被限流风险。 - 错误重试：对于网络抖动或服务器临时错误（HTTP 5xx），应采用指数退避重试（如第一次1秒，第二次2秒，第三次4秒），最多重试3次。
- 批量查询：如果需要同时查询多张卡，不要串行逐卡请求，应使用异步并发（如Python的
asyncio或concurrent.futures），但注意控制并发总数不超过QPS限制。 - 数据一致性：不要在关键业务（如支付强制路由）中完全依赖API返回的
bank和card_type字段；建议作为辅助参考，配合银行列表白名单使用。 - 日志记录：记录每次查询的BIN、请求时间、响应耗时和返回码，便于分析异常和性能监控。
- 密钥安全：切勿将API Key硬编码在客户端代码或前端页面中；应当从环境变量或配置中心读取，并定期轮换。
参考文档
- 官方文档页：https://apizero.cn/aidocs/bank-card
- 原始开放API文档：https://apizero.cn/aidocs/bank-card/raw.md
