适用场景银行卡BINBank 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-KeyHeaderstring是你的API密钥cardQuerystring是银行卡号前6位数字例如622848请求地址https://v1.apizero.cn/api/bank-card?card{bin}示例请求https://v1.apizero.cn/api/bank-card?card622848curl 示例一次完整的请求以下是一个可直接复制运行的curl命令注意将$APIZERO_API_KEY替换为你自己的密钥curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/bank-card?card622848如果密钥已设置环境变量上述命令可直接执行。返回结果是一个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, headersheaders, paramsparams, timeout10) 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 示例使用 OkHttpimport 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()); } } }返回字段解读正常响应示例以code200为例{ code: 200, message: success, data: { bank: 中国农业银行, card_type: 借记卡, card_brand: 银联, is_luhn_valid: true, card_number_length: 19 } }字段类型说明codeint业务状态码200表示成功messagestring状态描述成功时为successdata.bankstring发卡行名称如中国农业银行data.card_typestring卡类型借记卡、贷记卡或准贷记卡data.card_brandstring卡品牌银联、Visa、MasterCard等data.is_luhn_validbool该BIN所属卡号是否通过Luhn算法校验仅供参考data.card_number_lengthint该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位是否正确。40002BIN格式非法包含非数字字符。工程化注意事项缓存策略同一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