一、技术简介:为什么转账前要先问一句「哪个银行」
企业发工资、对公转账、用户绑卡提现时,表单里几乎总要问一句:这张卡是哪个银行的?
为什么要问?
因为只拿到卡号和姓名,收单侧并不知道这张卡属于哪家银行、是借记卡还是贷记卡、卡段登记在哪个地区。表单里的银行选错了,后续的转账路由、卡种判断、分区统计都会跟着错。
银行卡归属地查询接口做的就是这件事:传入一个卡号,返回发卡行、卡种、卡产品名称、归属地、银行简码与服务热线等字段。它是一个 GET 接口,Query 里只有 kahao 一个必填参数,请求头用 Authorization: APPCODE <appcode> 鉴权,返回 JSON。
返回体是两层结构:外层 showapi_res_code / showapi_res_error 表示「请求有没有被受理」,内层 showapi_res_body.ret_code 表示「这次有没有查到这张卡的信息」。两层都判断,才算把一次调用读完整。

二、能力概览:一次调用能拿到哪些字段
沿用「先看能查什么、再看怎么查」的顺序,把返回信息拆成三组来看。
| 能力 | 返回字段 | 说明 | 适用情形 |
|---|---|---|---|
| 发卡行识别 | 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 校验这类格式检查由业务侧先做,接口本身不做卡号合法性判断。

四、接入流程:开通、取凭证、组请求、解析结果
- 在云市场控制台开通该接口,拿到当前账号的 AppCode。
- 配置调用地址:以控制台「接口信息」里显示的地址为准,写入环境变量,不硬编码到代码里。
- 组装 GET 请求:Header 放
Authorization: APPCODE <appcode>,Query 放kahao,无 Body。 - 发起调用,先看 HTTP 状态码,再解析 JSON 的两层状态码。
- 做字段映射与脱敏落库;查询失败分「可重试」和「需人工补录」两类处理。
请求参数
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| Header | Authorization |
string | 是 | APPCODE 加空格再加 AppCode,中间是英文空格 |
| Query | kahao |
string | 是 | 银行卡号,示例 6215982582010042122;传入前去掉空格与横杠 |
| Body | — | — | — | 无参数 |
请求方式为 GET,返回类型为 JSON。卡号属于敏感信息,建议先做长度(一般 15~19 位)与纯数字校验,再发起请求。

五、调用示例与返回结构
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": "找不到此卡号信息"
}
}

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 调试」模块可以直接走一遍,不用先写业务代码。
- 选中「银行卡归属地」接口,确认请求方式是
GET /bankcard。 - 在「请求参数(Query)」里填
kahao,用示例卡号6215982582010042122。 - 点「发起请求」,先看返回的 HTTP 状态码,再看响应正文。
- 判断顺序:
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当成开户支行写进转账表单 —— 这两者不是一回事,见下一章之外的第八章。

七、调用限制与规范
- 必填约束:
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 直接填进「开户支行」字段,它只是发卡行名称。

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 传输、日志脱敏、结果缓存、限流与重试分类、失败率与耗时监控。
看懂返回结构、分清「发卡行」与「开户网点」,比多写几行调用代码更关键。