RESTful银行卡归属地接口详解，附多语言调用代码与JSON返回示例

1. 技术简介

银行卡归属地查询接口是基于 RESTful 风格的 HTTP GET API，输入一个银行卡号（kahao），返回该卡的归属地区、银行名称、卡种（借记卡/信用卡/银联卡）、银行联系电话、银行官网等结构化信息。接口覆盖 500 余家银行的卡段数据，支持所有带银联标识的银行卡。

鉴权采用 APICODE 方式，请求头携带 Authorization: APPCODE <appcode> 即可调用。返回类型为 JSON，标准外层包裹 showapi_res_code / showapi_res_error / showapi_res_body，业务数据在 showapi_res_body 内部。

2. 能力概览

3. 适用场景

• 风控与反欺诈：在交易环节根据卡号归属地与卡种做风险初筛，辅助判断异地/异种交易。
• 客户信息管理：开户或绑卡时快速识别发卡行，减少用户手动填写，降低输入错误。
• 支付路由：根据卡种（借记/信用/银联）选择对应清算通道。
• 数据分析：按地区维度聚合用户分布，辅助市场策略。
• 小程序 / APP / ERP：作为轻量后端能力嵌入，一次调用获取卡属性。

4. 接入流程

1. 在云市场开通该接口服务，获取 APICODE。
2. 确认调用端点：控制台「接口信息」中的调用地址（GET /bankcard）。
3. 构造请求：请求头加入 Authorization: APPCODE YOUR_APPCODE，Query 参数加 kahao=<卡号>。
4. 发起 HTTP GET 请求，解析 JSON 响应。
5. 按 showapi_res_body.ret_code 判断业务结果（0 为成功，非 0 为失败）。

5. 调用示例与返回结构

5.1 请求

GET /bankcard?kahao=6215982582010042122
Authorization: APPCODE YOUR_APPCODE

5.2 成功响应 JSON

{
   
    "showapi_res_code": 0,
    "showapi_res_error": "",
    "showapi_res_body": {
   
        "ret_code": 0,
        "area": "福建省 - 漳州市",
        "tel": "95568",
        "brand": "民生借记卡(银联卡)",
        "bankName": "中国民生银行（03050000）",
        "cardType": "借记卡",
        "url": "www.cmbc.com.cn",
        "cardNum": "622622070288xxxx"
    }
}

5.3 返回字段说明

6. 在线调试实录

在云市场「API 调试」面板中，填入 kahao 参数点击发起请求。以示例卡号为例，调试面板直接返回如下 JSON：

{
   
    "ret_code": 0,
    "area": "福建省 - 漳州市",
    "tel": "95568",
    "brand": "民生借记卡(银联卡)",
    "bankName": "中国民生银行（03050000）",
    "cardType": "借记卡",
    "url": "www.cmbc.com.cn",
    "cardNum": "622622070288xxxx"
}

解读：该卡归属地为福建省漳州市，发卡行为中国民生银行，卡种为借记卡（银联卡），联系电话 95568。调试面板与正式调用返回结构一致，可直接用于联调验证。

若卡号不在覆盖卡段内或数据缺失，ret_code 会返回非 0，且 area 字段为空字符串或不存在该字段。

7. 调用限制与规范

• 仅当 HTTP 响应状态码为 200 时计入调用量，非 200 不计入。
• 请求需携带有效 APICODE，否则网关返回 401/403。
• kahao 参数必填，传入空值或非数字字符串可能导致业务层 ret_code 非 0。
• 建议对高并发调用做限流与重试，避免触发网关 403（Quota Exhausted / Quota Expired）。
• 敏感字段（完整卡号）在返回中已脱敏，业务侧应遵循最小化保存原则。
• QPS 上限、每日配额等以控制台实时配置为准。

8. 多语言调用示例

Python

import requests

def query_bankcard_location(kahao: str, appcode: str) -> dict:
    url = "/bankcard"  # 完整调用地址见控制台「接口信息」
    params = {
   "kahao": kahao}
    headers = {
   "Authorization": f"APPCODE {appcode}"}
    r = requests.get(url, params=params, headers=headers, timeout=10)
    data = r.json()
    if data.get("showapi_res_code") != 0:
        raise RuntimeError(data.get("showapi_res_error"))
    return data["showapi_res_body"]

body = query_bankcard_location("6215982582010042122", "YOUR_APPCODE")
print(body["area"], body["bankName"], body["cardType"])

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class BankcardLocation {
   
    public static void main(String[] args) throws Exception {
   
        String base = ""; // 完整调用地址见控制台「接口信息」
        String kahao = "6215982582010042122";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(base + "/bankcard?kahao=" + kahao))
            .header("Authorization", "APPCODE YOUR_APPCODE")
            .GET()
            .build();
        HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(resp.body()); // 解析 JSON 后读取 showapi_res_body
    }
}

PHP

function query_bankcard_location(string $kahao, string $appcode): array {
   
    $base = ''; // 完整调用地址见控制台「接口信息」
    $url = $base . '/bankcard?kahao=' . urlencode($kahao);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: APPCODE $appcode"]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $body = curl_exec($ch);
    curl_close($ch);
    $json = json_decode($body, true);
    if (($json['showapi_res_code'] ?? -1) !== 0) {
   
        throw new RuntimeException($json['showapi_res_error'] ?? 'unknown');
    }
    return $json['showapi_res_body'];
}
print_r(query_bankcard_location('6215982582010042122', 'YOUR_APPCODE'));

JavaScript (Node.js)

async function queryBankcardLocation(kahao, appcode) {
   
  const base = ''; // 完整调用地址见控制台「接口信息」
  const url = `${
     base}/bankcard?kahao=${
     encodeURIComponent(kahao)}`;
  const res = await fetch(url, {
   
    headers: {
    Authorization: `APPCODE ${
     appcode}` }
  });
  const data = await res.json();
  if (data.showapi_res_code !== 0) {
   
    throw new Error(data.showapi_res_error);
  }
  return data.showapi_res_body;
}

queryBankcardLocation('6215982582010042122', 'YOUR_APPCODE')
  .then(body => console.log(body.area, body.bankName, body.cardType));

9. 错误码排查

10. 能力边界与免责声明

• 支持：带银联标识、在覆盖卡段内的银行卡号查询。
• 不支持：非银联卡段、境外卡、未在数据内的卡段（ret_code 非 0 或 area 缺失）。
• 边界：返回为结构化属性，不做身份核验；cardNum 为脱敏值，无法用于完整卡号还原。
• 免责：接口数据仅供参考，不作为业务决策或风控的唯一依据，具体以发卡行口径为准。

11. 技术 FAQ

Q：showapi_res_code 与 ret_code 有什么区别？
A：前者是网关层结果码（鉴权/限流/配额类），后者是业务层结果码（数据是否命中）。需先判外层为 0，再判业务层 ret_code 为 0。

Q：为什么 area 有时为空？
A：卡号不在覆盖卡段或数据缺失时，ret_code 非 0，area 为空字符串或该字段不存在。

Q：鉴权该用哪种？
A：该接口支持 APICODE 与 AppKey/AppSecret 签名两种方式，示例统一采用 APICODE，请求头携带 Authorization: APPCODE <appcode>。

Q：非 200 会不会计入调用量？
A：仅 HTTP 200 时计入，非 200 不计入。

12. 内容小结

本文以 RESTful 银行卡归属地接口为例，梳理了能力概览、适用场景、接入流程、调用示例与返回结构、在线调试、调用限制、多语言调用（Python / Java / PHP / JS）、错误码排查与能力边界。接入时以控制台实时配置为准，鉴权统一使用 APICODE，解析时先判网关层再判业务层 ret_code，即可稳定集成到风控、客户管理、支付路由等业务链路。