银行卡归属地查询接口接入指南|输入卡号识别发卡行与卡类型,获取归属地、卡品牌与银行简码

简介: 银行卡归属地查询接口通过卡号返回发卡行名称、规范化行名、银行简码、卡种、卡产品、归属地、服务热线及脱敏回显卡号。接口为 GET /bankcard,Query 仅一个必填参数 kahao,请求头用 Authorization: APPCODE <appcode> 鉴权,返回 JSON。本文给出返回结构、字段含义表、失败响应、Python / Java / PHP / Node.js 四语言示例、在线调试判读顺序与错误码排查表,并整理卡号清洗、结果缓存、限流重试、日志脱敏等工程实践。能力边界:不返回开户支行名称与 12 位联行号。适用于转账打钱表单、绑卡自动填充、财务批量对账等场景。

一、技术简介:为什么转账前要先问一句「哪个银行」

企业发工资、对公转账、用户绑卡提现时,表单里几乎总要问一句:这张卡是哪个银行的?

为什么要问?

因为只拿到卡号和姓名,收单侧并不知道这张卡属于哪家银行、是借记卡还是贷记卡、卡段登记在哪个地区。表单里的银行选错了,后续的转账路由、卡种判断、分区统计都会跟着错。

银行卡归属地查询接口做的就是这件事:传入一个卡号,返回发卡行、卡种、卡产品名称、归属地、银行简码与服务热线等字段。它是一个 GET 接口,Query 里只有 kahao 一个必填参数,请求头用 Authorization: APPCODE <appcode> 鉴权,返回 JSON。

返回体是两层结构:外层 showapi_res_code / showapi_res_error 表示「请求有没有被受理」,内层 showapi_res_body.ret_code 表示「这次有没有查到这张卡的信息」。两层都判断,才算把一次调用读完整。

图 1 卡号到返回字段的数据流

二、能力概览:一次调用能拿到哪些字段

沿用「先看能查什么、再看怎么查」的顺序,把返回信息拆成三组来看。

能力 返回字段 说明 适用情形
发卡行识别 bankName、formatBankName、simpleCode 银行名称、规范化行名、银行简码 表单带出银行、按行分组
卡种与卡产品 cardType、brand 借记卡/贷记卡等卡种,银行卡产品名称 区分扣款与限额逻辑
归属地 area 「省 - 市」粒度的卡片归属地 地域分布统计
联系方式与官网 tel、url、logo 银行服务热线、官网、标志图片地址 信息展示与核对
入参回显 cardNum 脱敏后回显的卡号 核对本次请求入参
状态与失败说明 showapi_res_code、showapi_res_error、showapi_res_id、ret_code、remark 外层受理状态、内层查询状态、请求标识、失败原因 日志、排查、监控

2.1 卡号识别发卡行与卡类型:bankName 是接口返回的原始行名,formatBankName 是规范化后的简称,simpleCode 是简码。三者不一定同时有值,做字段映射时要按「有值才用、为空降级」处理。

2.2 归属地与联系方式:area 给到「省 - 市」粒度,tel 给服务热线。这两个字段适合在表单里做自动带出,但不能当作开户网点信息使用(见第八章)。

2.3 状态字段怎么读:showapi_res_code = 0 只说明请求被受理;还要继续看 showapi_res_body.ret_code,0 才是查到结果,-1 表示这张卡号没有对应信息,此时 area 通常为空或不存在。

三、适用场景:从转账打钱到批量对账

转账打钱。企业财务在对公转账、发薪、退款时,表单需要填银行信息。用卡号先查一次,把 bankName 与 area 带出来,再和用户填写的内容做一致性核对。

自动填充。商户、结算平台、小程序提现页要让用户选银行。接口可以在卡号输入完成后带出发卡行,前端把下拉框的默认值填上,用户只需确认。

财务批量对账。一批供应商、员工卡号需要归并到不同银行和地区时,逐条调用后按 bankName / area 分组,再与流水记录比对。

绑卡前置校验。在正式绑卡前,先确认卡种与发卡行是否符合当前业务支持的卡类型。卡号长度、纯数字、Luhn 校验这类格式检查由业务侧先做,接口本身不做卡号合法性判断。

图 2 三类业务场景的数据流向

四、接入流程:开通、取凭证、组请求、解析结果

  1. 在云市场控制台开通该接口,拿到当前账号的 AppCode。
  2. 配置调用地址:以控制台「接口信息」里显示的地址为准,写入环境变量,不硬编码到代码里。
  3. 组装 GET 请求:Header 放 Authorization: APPCODE <appcode>,Query 放 kahao,无 Body。
  4. 发起调用,先看 HTTP 状态码,再解析 JSON 的两层状态码。
  5. 做字段映射与脱敏落库;查询失败分「可重试」和「需人工补录」两类处理。

请求参数

位置 名称 类型 必填 说明
Header Authorization string 是 APPCODE 加空格再加 AppCode,中间是英文空格
Query kahao string 是 银行卡号,示例 6215982582010042122;传入前去掉空格与横杠
Body — — — 无参数

请求方式为 GET,返回类型为 JSON。卡号属于敏感信息,建议先做长度(一般 15~19 位)与纯数字校验,再发起请求。

图 3 接入流程四步

五、调用示例与返回结构

5.1 完整返回结构

下面是从控制台「成功响应」摘出的结构,注释标了每个字段的含义;示例里的官网与标志图片字段用空字符串示意脱敏后的展示形态。

{
   
  "showapi_res_code": 0,                 // 外层:0 表示请求被受理
  "showapi_res_error": "",               // 外层:错误信息,成功时为空
  "showapi_res_id": "446253c56b1e49f0a1b48710863c4c0d",  // 本次请求标识
  "showapi_res_body": {
   
    "ret_code": 0,                      // 内层:0 为查到结果,其他为未查到
    "area": "福建省 - 漳州市",           // 归属地,省 - 市粒度
    "tel": "95568",                     // 银行服务热线
    "brand": "民生借记卡(银联卡)",       // 银行卡产品名称
    "bankName": "中国民生银行(03050000)", // 银行名称,可能带行号后缀
    "cardType": "借记卡",                // 银行卡种
    "url": "",                          // 银行官网,部分银行为空字符串
    "cardNum": "622622070288xxxx",      // 脱敏回显的卡号
    "simpleCode": "CMBC",               // 银行简码,不一定返回
    "formatBankName": "民生银行",        // 规范化行名,部分银行为空字符串
    "logo": ""                          // 标志图片地址,部分银行为空字符串
  }
}

字段含义表

字段 类型 含义 是否一定有值
showapi_res_code int 外层受理状态,0 为受理成功 是
showapi_res_error string 外层错误描述,成功时为空 是
showapi_res_id string 本次请求唯一标识,排查时带上 是
showapi_res_body.ret_code int 内层查询状态,0 为查到结果 是
area string 卡片归属地,格式「一级 - 二级」 查到时返回
tel string 银行服务热线 查到时返回
brand string 银行卡产品名称 查到时返回
bankName string 银行名称,可能包含行号后缀 查到时返回
cardType string 银行卡种,如借记卡、贷记卡 查到时返回
url string 银行官网 否,部分银行为空
cardNum string 脱敏回显的卡号 查到时返回
simpleCode string 银行简码 否,不一定返回
formatBankName string 规范化银行名称 否,部分银行为空
logo string 银行标志图片地址 否,部分银行为空
remark string 未查到时的文字说明 否,仅失败场景返回

失败响应:外层受理成功,但内层没查到这张卡。

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_id": "446253c56b1e49f0a1b48710863c4c0d",
  "showapi_res_body": {
   
    "ret_code": -1,
    "remark": "找不到此卡号信息"
  }
}

图 4 返回结构分层:外层状态码与内层业务字段

5.2 Python 调用示例

import os
import requests

host = os.environ["BANKCARD_ENDPOINT"]    # 调用地址,以控制台显示为准
appcode = os.environ["BANKCARD_APPCODE"]

headers = {
   "Authorization": "APPCODE " + appcode}
params = {
   "kahao": "6215982582010042122"}

resp = requests.get(host + "/bankcard", headers=headers, params=params, timeout=5)
resp.raise_for_status()
data = resp.json()

if data.get("showapi_res_code") != 0:
    raise RuntimeError("外层受理失败: " + data.get("showapi_res_error", ""))

body = data.get("showapi_res_body", {
   })
if body.get("ret_code") != 0:
    # 查不到结果不做重试,转人工补录
    print("未查到:", body.get("remark"))
else:
    print(body.get("bankName"), body.get("cardType"), body.get("area"))

5.3 Java 调用示例

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class BankcardDemo {
   
    public static void main(String[] args) throws Exception {
   
        String host = System.getenv("BANKCARD_ENDPOINT");  // 调用地址,以控制台显示为准
        String appcode = System.getenv("BANKCARD_APPCODE");
        String kahao = "6215982582010042122";

        String query = "kahao=" + URLEncoder.encode(kahao, StandardCharsets.UTF_8);
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(host + "/bankcard?" + query))
                .header("Authorization", "APPCODE " + appcode)
                .GET()
                .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());

        // 先判断 HTTP 状态码,再解析正文 JSON 的两层状态码
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

5.4 PHP 调用示例

<?php
$host = getenv('BANKCARD_ENDPOINT');     // 调用地址,以控制台显示为准
$appcode = getenv('BANKCARD_APPCODE');
$kahao = '6215982582010042122';

$url = $host . '/bankcard?' . http_build_query(['kahao' => $kahao]);
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: APPCODE ' . $appcode],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 5,
]);
$raw = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// 先判断 HTTP 状态码,再解析正文 JSON 的两层状态码
if ($httpCode === 200) {
   
    $data = json_decode($raw, true);
    $body = $data['showapi_res_body'] ?? [];
    echo ($body['bankName'] ?? '') . ' / ' . ($body['area'] ?? '') . PHP_EOL;
}

5.5 Node.js 调用示例

const host = process.env.BANKCARD_ENDPOINT;   // 调用地址,以控制台显示为准
const appcode = process.env.BANKCARD_APPCODE;

const url = new URL('/bankcard', host);
url.searchParams.set('kahao', '6215982582010042122');

const res = await fetch(url, {
   
  headers: {
    Authorization: 'APPCODE ' + appcode },
  signal: AbortSignal.timeout(5000),
});
if (!res.ok) throw new Error('HTTP ' + res.status);

const data = await res.json();
if (data.showapi_res_code !== 0) throw new Error(data.showapi_res_error);
const body = data.showapi_res_body || {
   };
if (body.ret_code !== 0) {
   
  // 查不到结果不做重试,转人工补录
  console.log('未查到:', body.remark);
} else {
   
  console.log(body.bankName, body.cardType, body.area);
}

四段示例都把调用地址与凭证放进环境变量,避免把地址散落在代码里;路径统一是 /bankcard,Query 统一是 kahao。

六、在线调试实录

控制台的「API 调试」模块可以直接走一遍,不用先写业务代码。

  1. 选中「银行卡归属地」接口,确认请求方式是 GET /bankcard。
  2. 在「请求参数(Query)」里填 kahao,用示例卡号 6215982582010042122。
  3. 点「发起请求」,先看返回的 HTTP 状态码,再看响应正文。
  4. 判断顺序:showapi_res_code → showapi_res_body.ret_code → 业务字段。

一次正常调用里,showapi_res_code = 0、ret_code = 0,area 返回「省 - 市」,bankName 与 cardType 有值。把卡号换成一段查不到信息的号码,外层仍是 0,但 ret_code = -1 且带 remark,此时 area 为空或不返回。

几个容易踩的点:

  • 只看了外层 showapi_res_code 就去读 bankName,遇到 ret_code = -1 会拿到空值。
  • APPCODE 与 AppCode 之间少了英文空格,或者凭证前后带了换行、空格,会直接被网关挡在 401。
  • 卡号从表单复制过来常带空格或横杠,Query 编码前先清洗。
  • 把 bankName 当成开户支行写进转账表单 —— 这两者不是一回事,见下一章之外的第八章。

图 5 在线调试:请求参数与响应判读

七、调用限制与规范

  • 必填约束:kahao 必填,仅支持 GET,无 Header 之外的额外参数,无 Body。
  • 配额与频率:单账号 QPS 上限、每日或总量额度以控制台实时配置为准;批量调用前先核对当前账号的额度与限流设置。
  • 批量规则:逐条调用,配合令牌桶或固定间隔限流;失败按类型分流,ret_code = -1 属确定性结果,不做重试。
  • 重试策略:仅对网络超时、500、502、503 做有限次重试,用指数退避加抖动;401、403 属配置问题,先修凭证与授权再发。
  • 结果缓存:同一卡号的发卡行、卡种与归属地取值在较长时间内不变,可按脱敏后的卡号做缓存并设置合理 TTL,减少重复调用;缓存 key 不要直接放明文卡号。
  • 幂等与降级:查询天然幂等,重复请求不会产生副作用;接口不可用时,表单降级为让用户手动选择银行,不要阻断主流程。
  • 合规与数据安全:传输走 HTTPS;日志只保留前 6 后 4 的脱敏卡号与 showapi_res_id;遵循最小必要原则,不长期存储卡号明文;用途限于用户已告知并同意的业务场景;展示层对回显卡号继续脱敏。
  • 监控:分别统计外层受理失败率、内层空结果率、HTTP 非 200 占比与 P95 耗时,避免把所有失败混成一个指标。

八、能力边界与免责声明

8.1 总行、分行、支行:哪些能查,哪些查不到

这是接入前最容易搞混的一层。接口返回的是发卡行与卡片归属信息,不是账户开户网点信息。

信息层级 本接口是否返回 对应字段或说明
发卡行(行名) 是 bankName、formatBankName、simpleCode
卡片归属地 是 area,省 - 市粒度
卡种与卡产品 是 cardType、brand
分行(省市分行) 否 不返回机构层级
开户支行名称 否 不返回基层网点名称
12 位联行号 否 不返回

场景上怎么区分:个人转账、快捷绑卡、提现这类流程,有发卡行名称加归属地通常就够;对公、电汇、代发、农商农信、大额划付这类流程,表单要的是开户支行名称与 12 位联行号,本接口不提供,需要业务侧另行采集并让用户确认。不要把 bankName 直接填进「开户支行」字段,它只是发卡行名称。

图 6 发卡行信息与开户支行、联行号的边界

8.2 能力边界

  • 支持带银联标识的银行卡,覆盖 500 余家银行的卡片信息;新发卡段、部分特殊卡种可能查不到。
  • area 只到「省 - 市」粒度,不返回区县、网点地址与经纬度。
  • formatBankName、simpleCode、logo、url 可能为空字符串或整个字段不返回,字段映射要做空值兼容。
  • 不返回 BIN 段、卡号长度与 Luhn 校验结果;需要这类校验时由业务侧自行实现。
  • 卡段数据会随发卡机构维护而更新,存在更新延迟,不保证与实时发卡记录同步。

8.3 免责声明

返回数据仅供参考,不作为转账、放款、身份核验、账户权属判定的唯一依据;因数据延迟、字段为空或业务侧字段误用产生的判断偏差,由业务系统自行承担。接口不存储查询明细,不用于任何违法违规用途。涉及金融数据的采集、传输与留存,按适用法规与内部数据安全制度执行。

九、错误码与排查

现象 可能原因 处理建议
HTTP 401,X-Ca-Error-Message: Empty Signature 请求头没有带鉴权信息 补 Authorization: APPCODE <appcode>,注意中间是英文空格
HTTP 403,Unauthorized 凭证无效,或该接口未对当前账号授权 核对 AppCode 与接口授权状态,修正后重试
HTTP 403,Quota Exhausted 可用调用额度已用尽 检查额度余量,暂停调用并做限流,避免并发下重复发起
HTTP 403,Quota Expired 调用额度已过有效期 核对有效期配置后再发起
HTTP 500,Internal Error 网关内部错误 有限次退避重试,仍失败则记录 showapi_res_id 并降级
HTTP 502 请求报文格式异常 确认使用 GET、Query 已正确编码、无多余 Body
HTTP 503,Service Unavailable 接口可能处于维护状态 稍后重试,期间走表单手动填写的降级路径
HTTP 200 但 ret_code = -1 卡号无对应信息,remark 给出说明 不做重试,转人工补录或让用户核对卡号
showapi_res_code != 0 外层请求未被正常受理 读 showapi_res_error,并带 showapi_res_id 定位
area / simpleCode 为空 该卡段暂无对应数据,或字段本身可选 按空值兼容处理,不要写死字段必存在

排查顺序建议固定为:HTTP 状态码 → 外层 showapi_res_code → 内层 ret_code → 业务字段。这样能快速把「配置问题」「额度问题」「查无此卡」区分开。

十、技术 FAQ

Q1:支持哪些卡?
带银联标识的银行卡,覆盖 500 余家银行的卡片信息。新发卡段或部分特殊卡种可能查不到,此时返回 ret_code = -1。

Q2:为什么 cardNum 是脱敏的?
它是接口回显的入参,用于核对本次请求,不是可存储的原始卡号。业务侧仍应保留自己的脱敏策略。

Q3:area 精确到哪一级?
「省 - 市」粒度,格式形如「福建省 - 漳州市」。部分卡可能只到省级或返回空字符串。

Q4:能拿到开户支行名称和联行号吗?
不能。本接口返回发卡行名称与卡片归属地,不返回基层网点与 12 位联行号,详见 8.1。

Q5:bankName 和 formatBankName 该用哪个?
做展示可用 formatBankName(更短),做分组统计用 bankName(更完整);两者都可能带后缀或为空,建议同时保留原始值。

Q6:同一卡号的结果可以缓存吗?
可以。发卡行、卡种、归属地短时间内不变,按脱敏卡号做 key 并设置 TTL;不要用明文卡号当缓存 key。

Q7:批量几万条卡号怎么跑?
逐条调用 + 限流 + 失败分类。可重试错误走退避队列,ret_code = -1 直接落到人工补录清单,避免无效重试。

Q8:为什么外层成功却没拿到银行信息?
两层状态码含义不同:showapi_res_code = 0 只代表请求被受理,ret_code 才代表查询结果。两个都判断。

Q9:支持 POST 吗?
控制台给出的请求方式是 GET,Query 传 kahao,无 Body。

Q10:数据多久更新一次?
卡段数据随发卡机构维护更新,没有固定周期承诺;对时效敏感的业务应保留人工确认入口。

Q11:可以拿这个接口做身份核验吗?
不适合。接口不返回持卡人姓名、证件号等身份信息,也不校验账户权属,不能作为实名或身份核验依据。

十一、内容小结

把这次接入压缩成几句话:

  • 请求很轻:GET /bankcard,一个 Query 参数 kahao,一个请求头 Authorization: APPCODE <appcode>。
  • 判断要分两层:外层看受理,内层 ret_code 看有没有查到;ret_code = -1 是确定性结果,别重试。
  • 字段要按可选处理:formatBankName、simpleCode、url、logo 都可能为空,映射时留降级路径。
  • 边界要讲清:返回的是发卡行与卡片归属地,不是开户支行与联行号;对公、电汇、代发场景需要另行采集网点信息。
  • 工程上补齐:卡号前置清洗、HTTPS 传输、日志脱敏、结果缓存、限流与重试分类、失败率与耗时监控。

看懂返回结构、分清「发卡行」与「开户网点」,比多写几行调用代码更关键。

相关文章
|
4天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1799 4
|
6天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
6天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
4天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
3844 2
|
19天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
8897 58
|
14天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
3131 9
|
20天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5872 69
|
7天前
|
云安全 人工智能 安全
|
12天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1960 2