银行卡四要素核验

传姓名、身份证号、银行卡号、银行预留手机号四项，一次请求返回一致 / 不一致。不发短信、不跳页面、不需要用户做任何操作，适合放在绑卡、提现、收款人建档、散户入驻这些环节的提交动作里，把填错卡号、拿别人的卡收款的情况在入口就拦下来。鉴权与开灵其它接口完全一致，三个请求头。

🤖

给你的 AI 用 · 一键接入

把接入包复制给你的 AI（Claude / Cursor / 通义），它照着就能写出对接代码，含签名、错误处理和「不匹配」的提示文案。

打开 AI 接入包下载 .md

接口

POST  https://openapi.kailingteck.com/api/v1/bankcard4/verify

鉴权：X-App-Key ＋ X-Timestamp（Unix 秒）＋ X-Sign（＝ sha256(appKey ＋时间戳＋报文原文＋ appSecret) 小写十六进制）。签名用的是发出去的那串原文，先序列化成一个字符串变量，签名和发送都用它。

请求参数（四项全必填）

参数	必填	说明
`name`	必填	持卡人姓名,2～30 个汉字,须与开户时登记的完全一致(少数民族姓名的「·」也要带上)
`idCardNo`	必填	18 位居民身份证号。平台先做末位校验,不合法直接返回 400,不打核验源。港澳台及外籍证件不支持
`bankCardNo`	必填	银行卡号,12～19 位数字,借记卡、信用卡都可以。平台先做卡号校验,抄错一位会被拦在 400
`mobile`	必填	★这张卡在银行预留的手机号,不是用户当前在用的手机号。这是「不匹配」最常见的原因

{
  "name": "张三",
  "idCardNo": "110101199001011237",
  "bankCardNo": "6215340301448384262",
  "mobile": "13800138000"
}

平台在打核验源之前先做格式校验（身份证末位、卡号校验位、手机号段），格式不对直接 400 返回，不计费。这一层能拦掉大部分抄错一位的情况，省得为一个错字付一次核验费。

字段	说明
`matched`	true＝四要素与银行预留信息一致；false＝不一致；null＝核验源本次没给出结论（不计费，可重试一次）。业务判断只看这一个字段
`state`	核验源原始结论：1 匹配 / 2 不匹配 / 3 其他异常。与 matched 一一对应，给排障用
`reason`	一句话说明，可直接展示给操作人员
`isMock`	true＝沙箱密钥，结果是固定的「匹配」，不是真核验

{
  "code": "CYT_00000",
  "msg": "success",
  "requestId": "cyt_xxx",
  "data": {
    "matched": false,
    "state": 2,
    "reason": "四要素与银行预留信息不一致(姓名、身份证号、卡号、预留手机号至少有一项对不上)",
    "isMock": false
  }
}

matched=false 不是报错，HTTP 仍是 200、code 仍是 CYT_00000。它就是核验的结论：四项里至少有一项和银行留的不一样。核验源不会告诉你是哪一项对不上，所以给用户的提示要写成「请核对姓名、身份证号、卡号和银行预留手机号」，别猜。

接入之后发生什么（时序）

用户在你的页面提交四项 → 你的后端签名后调本接口 → 平台先做格式校验 → 打核验源 → 3～5 秒内返回结论。全程同步，没有回调、没有轮询。
matched=true：放行，把「已核验」记在你的业务单上。
matched=false：提示用户核对四项后重新提交。每次提交都计一次费，前端要做防重复提交，并且同一张卡 24 小时最多 10 次，第 11 次会被核验源拒绝。
matched=null（state=3）：核验源没给出结论，不计费，隔几秒自动重试一次即可，再不行让用户稍后再试。

计费口径

有结论就计一次：matched 为 true 或 false 各计一次（核验源对两种结果都收费）。
不计费：参数被平台或核验源拒绝（400）、超过单卡日上限（429）、核验源异常（502）、matched=null。
沙箱密钥不计费，结果固定为「匹配」，只用来跑通签名和报文。切生产由平台在后台操作，切完你的代码一行不用改。

排错表（按返回里的文案找）

看到这句话	含义与该做什么
缺少必填字段：…	400 · CYT_40001。四个字段少了哪个，hint 里点名
idCardNo 不是合法的 18 位居民身份证号	400 · CYT_40001。末位校验没过，多半是抄错一位或把 X 写成了 0；这条没打核验源、不计费
bankCardNo 须为 12～19 位数字且通过卡号校验	400 · CYT_40001。同上，卡号抄错一位；不计费
要素格式被核验源拒绝：…	400 · CYT_40001。本地校验过了但核验源仍拒收（如身份证号在公安库里对不上出生日期）。不计费
同一张银行卡 24 小时内最多核验 10 次	429 · CYT_42903。核验源的硬限制，重试无效，换卡或等 24 小时。不计费
核验源认证异常，请稍后重试一次	502 · CYT_50200。核验源那头临时抖动，隔几秒重试一次即可。不计费
核验服务暂不可用（平台侧额度或服务状态异常）	502 · CYT_50200。是平台这边的事（上游额度或服务状态），联系平台，客户侧不用改代码。不计费
matched=false	这不是错误，是结论。让用户核对四项，尤其是「银行预留手机号」；每次提交都计费

通用鉴权错误（401 · CYT_40100 / 40102 / 40103，403 · CYT_40301，429 · CYT_42901 每分钟 120 次限流）与全站一致。签名恒定失败时，先检查参与签名的报文和实际发送的是不是同一串。

接入承诺（必读）

本接口处理的是身份证号、银行卡号等个人敏感信息。接入即确认：你已取得被核验人的明示授权，核验仅用于该用户本人的业务办理（绑卡、提现、开票收款人建档等），不用于对他人信息的批量探测或其他非法用途。平台侧日志对姓名、身份证号、卡号、手机号一律脱敏存储，不保留明文，也不向任何第三方提供。