银行卡四要素核验接口设计(精简版)

更新于 2026-06-15

银行卡四要素核验接口设计(精简版)

本文只讲**"怎么设计"**——状态码体系、两层契约、前置校验、响应结构、翻译模式与迭代纪律。

不含供应商映射、银联校准/差距、本期启用范围等内容,详见完整版《银行卡四要素-自研接口设计》。

一、设计约定与约束

完全复用项目现有骨架,只做最小且有规律的扩展:

既有资产 复用方式
SDTResponse {result, message, data, traceId} 对外响应结构不变
@Api("bank4") + AbstractApi / Bank4Api 入口不变
@Provider("xxx") + BaseRequestClient.processBank4() 每家供应商实现 processBank4
BaseClientResponse.convert() + setCharging() 上游码 → 我方码的翻译点;计费用内部标记
SDTCode(跨业务通用枚举) 通用结论复用,不重复定义
SDTBankCategory / SDTBankDetailCode 本设计主体:大类补充 + 细分语义

关键约束:result 是单一整数命名空间。 同一字段同时承载 SDTCode 与银行码的值,因此银行细分码必须与 SDTCode 已占用值错开(1,2,100,101,777,888,997,998,999)。规律:卡账户维度细分 → 2xx 段、入参维度细分 → 11x 段,互不冲突。

二、两层契约(核心)

各供应商返回粒度粗细不一。若把大类与细分塞进同一个 result,调用方 switch(result) 会漏码;若把细分写进契约,粗粒度上游下又成"死码"。因此拆成两个字段、两种承诺。

大类码 result(必返)

调用方据此编程;再粗的上游都能归到某个大类。

1 一致 2 不一致 210 不支持验证 100 格式有误 200 不确定 998 数据源异常

细分码 data.detailCode(选返)

仅作展示 / 客户引导 / 风控,缺失不影响主流程。

201/202/204/207 不一致细化 203/205/206/208/209 不支持细化 110~113 格式细化

为何必须拆两个字段:调用方只读 result 做逻辑、读 data.detailCode 做展示,无需自己上卷。把细分塞进 result 会让 switch(result){case 2:} 漏掉 result=201。

落码铁律:result 落大类;data.detailCode 落"该上游码能支撑的最细、且仍为真的码"——分不清子因时 detailCode 留空,绝不硬塞。

三、状态码体系

3.1 大类码(result,必返)

复用通用 SDTCode + 两个银行专属大类:

result 枚举 含义
1 SDTCode.核验一致 四要素一致
2 SDTCode.核验不一致 要素不符(含卡维度不一致)
100 SDTCode.参数异常 入参不合法(网关前置产出为主)
101 SDTCode.同一请求参数超限 平台侧同一参数请求超限
200 SDTBankCategory.核验不确定 银行已响应但无法定论,建议重试/换卡
210 SDTBankCategory.不支持验证 该卡/该组合无法核验的大类兜底
997 SDTCode.调用配额耗尽 套餐/余额耗尽
998 SDTCode.数据源异常 上游不可用/繁忙/超时/限流;可重试
999 SDTCode.系统异常 我方内部异常
public enum SDTBankCategory {   // 银行专属补充的两个大类
    核验不确定(200),   // 银行已响应但确无法定论,建议更换银行卡核验
    不支持验证(210),   // 该卡/该组合无法核验;上游分不清具体子因时落此
    ;
    private final int code; public int code(){return code;}
    SDTBankCategory(int code){this.code=code;}
}

上游"繁忙/超时/限流/稍后重试"类一律直接落 998,对客户统一答复"数据源暂时繁忙,请稍后重试"。bank4 不使用内部重试码 777:对客户无意义,限流类即时重试也只会再次撞限流。

3.2 细分码(data.detailCode,选返补充)

public enum SDTBankDetailCode {
    // —— 父类 100 参数/格式(不计费)——
    姓名格式不正确(110), 证件号格式不正确(111), 手机号格式不正确(112), 银行卡号格式不正确(113),
    // —— 父类 2 核验不一致(银行已响应)——
    卡号无效(201), 卡状态异常(202), 卡已销户(204), 未预留手机号(207),
    // —— 父类 210 不支持验证 ——
    无卡支付未开通(203), 发卡行不支持(205), 卡风控次数超限(206), 核验组合不支持(208), 风控拒绝(209),
    ;
    private final int code; public int code(){return code;}
    SDTBankDetailCode(int code){this.code=code;}
}

3.3 大类 ↔ 细分 归属

result(大类,必返) data.detailCode(细分,选返)
1 核验一致 —(无需细化)
2 核验不一致 201 卡号无效 / 202 卡状态异常 / 204 卡已销户 / 207 未预留手机号
210 不支持验证 203 无卡支付未开通 / 205 发卡行不支持 / 206 卡风控次数超限 / 208 核验组合不支持 / 209 风控拒绝
100 参数/格式有误 110 姓名 / 111 证件号 / 112 手机号 / 113 银行卡号
200 核验不确定 —(自身即终态)
998 数据源异常 —(系统侧)

四、与银联应答码体系的对齐

本码体系以银联银杏盾应答码为基准锚点。大类层与银联五大类严格同构(相同);差异都是有意为之的归类纠偏与平台扩展。 对外可直接引银联公开文档背书。

4.1 相同(一一对应、语义无损)

结构对齐
我方 银联(公开可查)
result 大类 respCode(00/01/02/03/04)·必返
data.detailCode detailRespCode·选返

大类结论与银联五大类一一对应,数据源再变语义恒成立。

细分

银联码表本就同时存在细分码(2314 发卡行无此卡号)与笼统码(2319 验证不一致),且 detailRespCode 标注选返——"原因粒度本就存在给不出、只返笼统不一致的情形"。我方正复刻这一结构。

4.2 差异(我方刻意与银联不同)

  1. 码值不同名,只对齐结构:我方 1/2/100/200/210 + 2xx 与银联 00/01/02/03/04 + 2xxx/4xxx/5xxx 数值不同。口径是"对齐"非"就是"。
  2. 多出平台级码 101/997:银联放报文头级,我方显式建为平台级大类。
  3. 归类纠偏(更收敛/更准):请求漏字段→100(集成 bug、不当卡结果返客户);未知商户/备付金不足→997;"格式非法"(113) 与"银行侧查无"(201) 拆两层。
  4. 200 核验不确定 独立成大类:从银联 04 拆出"稍后重试"子集,便于客户区分。
  5. 209 风控拒绝 语义收窄:限定"发卡行级",平台层风控不点亮。
  6. 不使用内部重试码 777:繁忙/限流直接落 998。
  7. 细分粒度差异:银联精鉴码能给"要素级不匹配",我方按选返结构合并到 2/202,缺失时大类仍正确。
  8. 计费维度银联码表没有:商业层叠加,与应答码正交。

4.3 我方码 ↔ 银联官方码 对照表

客户合同常要求"贵方结果码与官方源码对照"。本表即该场景的现成交付物——交付前务必先读「交付边界」。

大类码(result)→ 银联

我方 result 银联 respCode 大类 关系
1 00 验证一致 1:1
2 01 验证不一致 大类(含其下未细分情形)
100 03 要素格式有误 1:1(大类)
200 04 系统异常("稍后重试"子集) 从 04 拆出
210 02 不支持验证 1:1(大类)
998 04 系统异常 多对一
101 / 997 报文头/账户级(非业务码) 平台级

细分码(data.detailCode)→ 银联

我方 detailCode 银联 detailRespCode 关系
110/111/112/113 格式 4005/4003/4004/4001 1:1
201 卡号无效(银行侧查无) 2314 与 113 严格区分
202 卡状态异常 2316/2320 我方合并多个状态子码
207 未预留手机号 2344 1:1
205 发卡行不支持 2325/2347 近似
206 卡风控次数超限 2334/5103~5106 多对一
209 风控拒绝(发卡行级) 5110 1:1

交付边界(交付前必读)

  1. 对照 ≠ 透传:本表是语义对照,不代表每笔都返回银联原始码;商务不得承诺"透传 detailRespCode"。
  2. 码值不同名:只声明"对齐",不声明"等同"。
  3. 关系非纯 1:1:存在多对一与我方合并,逐码以"关系"列为准。
  4. 平台级无业务码对应:101/997/999 无银联业务应答码等价物。
  5. 以银联最新规范为准:交付前须与官方最新规范校对。

五、计费规则

判据不是"段位",而是上游是否对该卡给出了实质核验结论(由 setCharging() 内部标记,不进响应体)。

计费

核验实际发生且有定论:

1 一致 2 不一致 201 202 203 204 207

不计费

核验未真正发生:

100 11x 101 200 210 205 206 208 209 997/998/999

六、「核验不确定」的边界与可回溯

核验不确定(200) 是必要兜底,但必须收紧到最小并配套回溯:

① 收紧范围

能解释的子集一律拆走:繁忙/超时→998、组合不支持→208、格式问题→11x。200 只留"银行响应了、但给不出定论"。

② message 带行动建议

对外写成"核验未确定,建议稍后重试或更换银行卡核验",让客户能下一步。

③ 原始码落库可回溯

每笔按 traceId 持久化 {供应商, 上游原始码, 原文 message},客服一查即可答出具体原因。

一句话:粗码对外保稳定,细因落库保回溯。

七、前置参数校验:100/11x 由网关产出

类型 谁来做 产出码
格式/语法(本地可判) 我方网关前置(validateBank4,调供应商之前) 100 + 110~113
真实性/一致性(需查银行) 供应商 1/2/2xx
① 归一化

normalizeBank4 写回 request:trim、卡号/手机去空格横线、手机剥 +86、证件 x→X。

② 宽松校验

validateBank4 只拦"结构上绝无可能正确"的。

③ 命中 → fail-fast

返 100 + 11x,不下发供应商,省一次(可能计费的)调用。

④ 通过 → 下发

交供应商做真实性核验,返 1/2/2xx。

7.1 宽松前置校验清单(零误杀优先)

字段 归一化 本地硬拦截(→ 落码) 放行给供应商判
name 姓名 trim 空 / 超长(>64) → 110 字符集、生僻字、是否真名
idNum 身份证 trim;x→X 非 18 位 / 字符非法 → 111(一代证 15 位已停用,一并拦截) 校验位、出生日期、港澳台/外籍
mobile 手机号 trim;去 +86 不匹配 ^1\d{10}$ → 112 号段是否在网(不做白名单)
cardNo 银行卡号 trim;去空格横线 非全数字 / 长度∉[12,19] → 113 Luhn、卡 BIN、卡状态

宽松取舍均偏放行:校验位/Luhn 不本地硬拦(可留灰度开关、默认关);手机号不做号段白名单;一代证 15 位依法停用、按 111 拦;港澳台/外籍证件格式合法即放行。

八、响应数据体(SDTBankResponseData)

data 只承载选返补充:本期即细分码。无补充信息时整个 data 为 null。

@Data
@JsonIgnoreProperties(ignoreUnknown = true)
public class SDTBankResponseData extends SDTResponseData {
    @JsonInclude(JsonInclude.Include.NON_NULL) private Integer detailCode; // 细分码(选返)
    @JsonInclude(JsonInclude.Include.NON_NULL) private String  detailMsg;  // 细分码描述
    // 卡信息(bankName/cardType…)本期不返回
}

本期不返回银行卡信息:写进契约会做出兑现不了的承诺。若后续需要,优先本地维护 BIN→银行映射表按卡号前 6~8 位补全,与供应商解耦(契约只增不改)。BIN 数据来自第三方、可能滞后,仅作展示、不进核验判断。

九、对外响应示例

核验一致(data 为空)
{ "result": 1, "message": "核验一致", "data": null, "traceId": "a1b2c3d4..." }
不一致 · 带细分(卡失效 → 201)
{ "result": 2, "message": "核验不一致",
  "data": { "detailCode": 201, "detailMsg": "卡号无效" },
  "traceId": "a1b2c3d4..." }
不支持验证 · 分不清子因
{ "result": 210, "message": "不支持验证", "data": null, "traceId": "a1b2c3d4..." }
手机号格式错(网关前置)
{ "result": 100, "message": "参数异常",
  "data": { "detailCode": 112, "detailMsg": "手机号格式不正确" },
  "traceId": "a1b2c3d4..." }

十、convert() 翻译模式

每家供应商在自己的 Bank4Response.convert() 中把上游码翻译到统一码,模式一致:

@Override
public SDTResponse convert(String traceId) {
    SDTResponse resp = new SDTResponse();
    resp.setTraceId(traceId);
    // 映射:上游码 → 大类码(必有) + 细分码(可空) + 是否计费
    resp.setResult(category);            // result 永远是大类码(必有)
    resp.setMessage(categoryMsg);
    if (detailCode != null) {            // 细分码:支持才给,挂到 data
        SDTBankResponseData data = new SDTBankResponseData();
        data.setDetailCode(detailCode);
        data.setDetailMsg(detailMsg);
        resp.setData(data);
    }                                    // 否则 data 留 null
    setCharging(charged);
    return resp;
}

沉淀为每家一张映射表(上游码 → 大类 + 细分 + 计费)。新增供应商 = 一个 @Provider 客户端 + 一张映射表,公共接口、大类码、响应结构零改动;仅在确有新语义时追加细分码(细分缺失永远有大类兜底)。

十一、可持续迭代约束(落地纪律)

  1. 段位封闭:1xx=入参/请求侧、2xx=卡账户维度、9xx=系统侧;新增码只在对应段内追加。
  2. 先归类后建码:新返回码必须先尝试落到现有码;确无法归类才提案新增并说明理由。
  3. 不开特例分支:禁止在 convert() 里写"某家某码"的临时 if;一切走映射表。
  4. 映射表全覆盖:接入新供应商以"上游码 100% 落表"为合并前置条件,未列/未知码统一兜底 998 并告警。
  5. 对外契约只增不改:已发布的 result 数值语义永不改写,只新增。

十二、对外契约原则

两层契约决定两种承诺,发布口径据此区分。

result 大类表 — 正式契约

每码都会出现、语义永远成立,零脚注。业务逻辑、验收测试只对这张表。

detailCode 细分表 — 诊断增强

只列实际会出现的取值,附一句"是否返回取决于发卡行粒度,勿用于业务分支判断、勿穷举校验"。

信任来源 = 文档承诺的每条都 100% 成立,而非码的数量。