银行卡四要素核验接口设计(精简版)
本文只讲**"怎么设计"**——状态码体系、两层契约、前置校验、响应结构、翻译模式与迭代纪律。 不含供应商映射、银联校准/差距、本期启用范围等内容,详见完整版《银行卡四要素-自研接口设计.md》。
一、设计约定与约束
完全复用项目现有骨架,只做最小且有规律的扩展:
| 既有资产 | 复用方式 |
|---|---|
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永远只放大类码,调用方据此编程;细分码作为data里的补充字段,"支持才给、允许缺失"。
| 层 | 字段 | 取值 | 必返? | 用途 |
|---|---|---|---|---|
| 大类码 | result |
1 一致 / 2 不一致 / 210 不支持验证 / 100 要素格式有误 / 200 核验不确定 / 998 数据源异常 |
是 | 调用方据此编程;再粗的上游都能归到某个大类 |
| 细分码 | data.detailCode (+detailMsg) |
201/202/207(不一致细化)、205/206/208(不支持细化)、110~113(格式细化) |
否 | 仅作展示 / 客户引导 / 风控;缺失不影响主流程 |
为何必须拆两个字段:上游粒度粗细不一。若把大类与细分塞进同一个 result,调用方 switch(result){case 2:} 会漏掉 result=201;若把细分写进契约,粗粒度上游下又成"死码"。拆开后:调用方只读 result 做逻辑、读 data.detailCode 做展示,无需自己上卷。
落码铁律: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), // 受限 / 挂失 / 冻结 / 没收 / 睡眠卡 / 已销户(销户归此,不单列)
未预留手机号(207),
// —— 父类 210 不支持验证 ——
发卡行不支持(205), 卡风控次数超限(206), 核验组合不支持(208),
;
private final int code; public int code(){return code;}
SDTBankDetailCode(int code){this.code=code;}
}
3.3 大类 ↔ 细分 归属
result(大类,必返) |
data.detailCode(细分,选返) |
|---|---|
1 核验一致 |
—(无需细化) |
2 核验不一致 |
201 卡号无效 / 202 卡状态异常(含已销户) / 207 未预留手机号 |
210 不支持验证 |
205 发卡行不支持 / 206 卡风控次数超限 / 208 核验组合不支持 |
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/2/100/200/210 + 2xx与银联00/01/02/03/04 + 2xxx/4xxx/5xxx数值不同。对外口径是"对齐银联应答码体系",非"就是银联码"。 - 多出平台级码
101/997:银联把"商户频控 / 备付金不足"放报文头级、非业务应答码;我方显式建为平台级大类。 - 归类纠偏(比银联更收敛/更准):
- 请求漏字段 / 风险要素缺失(银联 5107/5109/5110)→ 我方归
100 参数异常(属集成 bug、内部修复),不当卡结果返客户; - 未知商户 / 备付金不足(银联 5000/20001010)→ 我方
997,不误判为"不支持验证"; - "格式非法的无效卡"(银联 4001)→
113、"银行侧查无卡号"(银联 2314)→201:我方把"格式错"与"银行侧查无"拆两层,比笼统"无效卡"更严格。
- 请求漏字段 / 风险要素缺失(银联 5107/5109/5110)→ 我方归
200 核验不确定独立成大类:对齐银联04 系统异常里"稍后重试"子集,但银联无独立"不确定"大类,我方显式拆出,便于客户区分"重试可能成功"。- 发卡行级风控不单列细分:银联
5110(发卡行风险拒绝)归 02 不支持,我方原拟以209对齐,但无供应商透传该粒度 → 已删除;发卡行级风控落大类210 不支持验证(不产细分),平台层风控归998。 - 不使用内部重试码
777:所有繁忙 / 限流直接落998,不向客户暴露重试语义(银联码表本无此类)。 - 细分粒度差异:银联精鉴码能给"要素级不匹配"(姓名 / 证件 / 手机到底哪个不符)、卡状态子类等更细的码;我方当前按选返结构合并到大类
2/202,缺失时大类结论仍正确,属选返层、不动契约。 - 计费维度银联码表没有:计费是商业层叠加,与银联应答码正交。
一句话:相同的是骨架(大类同构、细分选返结构忠实复刻),不同的是有意的归类纠偏 + 平台扩展 + 码值独立。
4.3 我方码 ↔ 银联官方码 对照表(应客户索取官方源映射时直接交付)
用途:客户合同/对接常要求"贵方结果码与官方(银联)源码的对照"。本表即该场景的现成交付物。交付前务必先读表末「交付边界」。
大类码(result,必返)→ 银联
| 我方 result | 含义 | 银联 respCode 大类 |
对应银联 detailRespCode(示例) |
关系 |
|---|---|---|---|---|
1 |
核验一致 | 00 验证一致 |
0000 |
1:1 |
2 |
核验不一致 | 01 验证不一致 |
2319(笼统不一致)等 |
我方 2 = 银联 01 大类(含其下未细分情形) |
100 |
参数 / 要素格式有误 | 03 验证要素格式有误 |
4006/4007(字段级见细分 11x) |
1:1(大类) |
200 |
核验不确定 | 04 系统异常("稍后重试"子集) |
2329 等 |
我方从 04 拆出独立大类 |
210 |
不支持验证 | 02 不支持验证 |
2325/2347 等 |
1:1(大类) |
998 |
数据源异常 | 04 系统异常 |
1302/1399/2208/2329 |
多对一 |
999 |
系统异常(我方内部) | 04 系统异常(近似) |
—(无业务码) | 我方内部异常 |
101 |
同一请求参数超限 | 报文头级(非业务应答码) | ≈20001002 |
平台级 |
997 |
调用配额耗尽 | 账户/报文头级 | ≈5000 / 20001010 |
平台级 |
细分码(data.detailCode,选返)→ 银联
| 我方 detailCode | 含义 | 银联大类 | 对应银联 detailRespCode |
关系 |
|---|---|---|---|---|
110 |
姓名格式不正确 | 03 格式 |
4005 |
1:1 |
111 |
证件号格式不正确 | 03 格式 |
4003 |
1:1 |
112 |
手机号格式不正确 | 03 格式 |
4004 |
1:1 |
113 |
银行卡号格式不正确 | 03 格式 |
4001(无效卡·格式非法) |
1:1 |
201 |
卡号无效(银行侧查无) | 01 不一致 |
2314 发卡行无此卡号 |
1:1(与 113 严格区分:格式错 vs 银行侧查无) |
202 |
卡状态异常(含已销户) | 01 不一致 |
2316 / 2320(受限 / 状态异常) |
我方合并银联多个状态子码(销户亦归此) |
207 |
未预留手机号 | 01 不一致 |
2344 |
1:1 |
205 |
发卡行不支持 | 02 不支持 |
2325 / 2347 |
近似 |
206 |
卡风控次数超限 | 02 不支持 |
2334 / 5103~5106 |
多对一 |
208 |
核验组合不支持 | 02 不支持 |
2346 / 2347 |
近似 |
| (未来)要素级不匹配 | 姓名/证件/手机哪个不符 | 01 不一致 |
精鉴 2311/2312/2313 |
当前不开(无供应商透传) |
交付边界(交付前必读):
- 对照 ≠ 透传:本表是"语义对照表",不代表每笔都会返回银联原始码。架构上上游不一定给到该粒度,商务不得承诺"透传银联原始
detailRespCode",只承诺"平台结果码 + 可提供对照表"。 - 码值不同名:只声明"对齐银联应答码体系",不声明"等同/就是银联码"。
- 关系非纯 1:1:存在多对一(如多个银联系统码 →
998)与我方合并(如202←2316/2320);逐码对表以"关系"列为准。 - 平台级无业务码对应:
101/997/999对应银联报文头级 / 账户级或我方内部,无"业务应答码"等价物。 - 以银联最新规范为准:本表银联码值为设计期整理,交付前须与银联银杏盾官方最新规范校对。
五、计费规则(不进响应体,由 setCharging() 内部标记)
判据不是"段位",而是上游是否对该卡给出了实质核验结论:
| 是否计费 | 对应结果(默认) |
|---|---|
| 计费 | 核验一致(1)、核验不一致(2)、卡号无效(201)、卡状态异常(202)、未预留手机号(207) |
| 不计费 | 参数异常(100)、11x、同一请求参数超限(101)、核验不确定(200)、不支持验证(210)、发卡行不支持(205)、卡风控次数超限(206)、核验组合不支持(208)、997/998/999 |
原则:核验实际发生且有定论才计费;不支持/被超限拦下/格式错/系统错不计费。
六、「核验不确定」的边界与可回溯
核验不确定(200) 是必要兜底,但必须收紧到最小并配套回溯:
- 收紧范围:能解释的子集一律拆走——繁忙/超时归
998、组合不支持归208、格式问题归11x。200只保留"银行确实响应了、但给不出一致/不一致结论"。 - message 自带行动建议:对外写成 "核验未确定,建议稍后重试或更换银行卡核验",让客户能下一步。
- 原始上游码落库可回溯:对外码可粗,但每笔按
traceId持久化{供应商, 上游原始码, 原文 message}。客户拿 traceId 来问,客服一查即可答出具体原因。
一句话:粗码对外保稳定,细因落库保回溯。
七、前置参数校验:100/11x 由网关产出
参数校验分两类,边界清晰:
| 类型 | 谁来做 | 产出码 |
|---|---|---|
| 格式/语法(本地可判) | 我方网关前置(validateBank4,调供应商之前) |
100 + 110~113 |
| 真实性/一致性(需查银行) | 供应商 | 1/2/2xx |
100/11x一律网关前置产出——不管路由到哪家,手机号格式错都返100 + 112,行为恒一致、不随供应商变。- fail-fast 省成本:格式不合法的请求不下发供应商,省一次(可能计费的)调用。
- 实现:
validateBank4= 先normalizeBank4归一化(写回 request)再宽松校验;细分码经Bank4Api.validationDetail贯通到data.detailCode。
7.1 宽松前置校验清单
原则:本地只拦"结构上绝无可能正确"的(零误杀优先);有疑义、供应商可能处理得了的一律放行。
| 字段 | 归一化(本地做) | 本地硬拦截(→ 落码) | 放行给供应商判 |
|---|---|---|---|
| name 姓名 | trim | 空 / 超长(>64) → 110 |
字符集、生僻字、是否真名 |
| idNum 身份证 | trim;x→X |
空 / 非 18 位 / 字符非法 → 111(一代证 15 位已停用,一并拦截) |
校验位、出生日期、港澳台/外籍证件 |
| mobile 手机号 | trim;去空格横线;去 +86/86 |
空 / 不匹配 ^1\d{10}$ → 112 |
号段是否在网(不做白名单,避免误杀新号段) |
| cardNo 银行卡号 | trim;去空格横线 | 空 / 非全数字 / 长度∉[12,19] → 113 |
Luhn、卡 BIN、卡状态 |
宽松取舍(均偏放行):
- 校验位 / Luhn 不本地硬拦——宽松优先,误杀代价 > 放过;可留作可选灰度开关、默认关。
- 手机号不做号段白名单——号段年年新增,只判
1 开头 + 11 位。 - 一代证(15 位)不处理——依《居民身份证法》2013-01-01 全面停用,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..." }
// 核验不一致 · 带细分(卡失效 → 大类 2 + 细分 201)
{ "result": 2, "message": "核验不一致", "data": { "detailCode": 201, "detailMsg": "卡号无效" }, "traceId": "a1b2c3d4..." }
// 核验不一致 · 无细分(上游只给大类)
{ "result": 2, "message": "核验不一致", "data": null, "traceId": "a1b2c3d4..." }
// 不支持验证 · 分不清子因(只给大类 210)
{ "result": 210, "message": "不支持验证", "data": null, "traceId": "a1b2c3d4..." }
// 手机号格式错误(大类 100 + 细分 112,网关前置产出)
{ "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客户端 + 一张映射表,公共接口、大类码、响应结构零改动;仅在确有新语义时向SDTBankDetailCode追加细分码(细分缺失永远有大类兜底)。
十一、可持续迭代约束(落地纪律)
- 段位封闭:1xx=入参/请求侧、2xx=卡账户维度、9xx=系统侧;新增码只在对应段内追加,不跨段。
- 先归类后建码:新供应商每个返回码必须先尝试落到现有码;确无法归类才提案新增,并说明它为何不是已有码的子集。
- 不开特例分支:禁止在
convert()里写"某家某码"的临时 if;一切走映射表。 - 映射表全覆盖:接入新供应商以"上游码 100% 落表"为合并前置条件,未列/未知码统一兜底
998并告警。 - 对外契约只增不改:已发布的
result数值语义永不改写,只新增。
十二、对外契约原则
两层契约决定了两种承诺,发布口径据此区分。
| 层 | 对外定位 | 客户用法 |
|---|---|---|
result 大类表 |
正式契约:每码都会出现、语义永远成立,零脚注 | 业务逻辑、验收测试只对这张表 |
data.detailCode 细分表 |
诊断增强字段:只列实际会出现的取值,附一句"是否返回取决于发卡行粒度,请勿用于业务分支判断、请勿穷举校验" | 展示 / 客服 / 日志排查 |
- 枚举只保留有供应商支持的码、不养死码:当前无任何供应商点亮的细分码不进枚举(如曾经的
203/204/209已删除)——列客户观察不到的码 = 邀请其造场景去测,测不出反损信任。将来有供应商透传新语义时按"只增不改"补码、文档"新增一行取值",因有扩充声明而不构成破坏性变更。 - 验收按大类:场景类用例(销户卡/无效卡等)断言一律写大类结论(如"该卡不能通过核验:
result=2或210"),不绑定原因码。 - 可回溯:客户追问具体原因 → 由
traceId落库的上游原始码回溯答复。 - 信任来源 = 文档承诺的每条都 100% 成立,而非码的数量。