# 银行卡四要素核验接口设计(精简版) > 本文只讲**"怎么设计"**——状态码体系、两层契约、前置校验、响应结构、翻译模式与迭代纪律。 > 不含供应商映射、银联校准/差距、本期启用范围等内容,详见完整版《银行卡四要素-自研接口设计.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.系统异常` | 我方内部异常 | ```java 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`,选返补充) ```java 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. **码值不同名,只对齐结构、不等同码值**:我方 `1/2/100/200/210 + 2xx` 与银联 `00/01/02/03/04 + 2xxx/4xxx/5xxx` 数值不同。对外口径是"**对齐**银联应答码体系",非"就是银联码"。 2. **多出平台级码 `101/997`**:银联把"商户频控 / 备付金不足"放报文头级、非业务应答码;我方显式建为平台级大类。 3. **归类纠偏(比银联更收敛/更准)**: - 请求漏字段 / 风险要素缺失(银联 5107/5109/5110)→ 我方归 `100 参数异常`(属集成 bug、内部修复),**不当卡结果返客户**; - 未知商户 / 备付金不足(银联 5000/20001010)→ 我方 `997`,不误判为"不支持验证"; - "格式非法的无效卡"(银联 4001)→ `113`、"银行侧查无卡号"(银联 2314)→ `201`:**我方把"格式错"与"银行侧查无"拆两层**,比笼统"无效卡"更严格。 4. **`200 核验不确定` 独立成大类**:对齐银联 `04 系统异常` 里"稍后重试"子集,但银联无独立"不确定"大类,我方显式拆出,便于客户区分"重试可能成功"。 5. **发卡行级风控不单列细分**:银联 `5110`(发卡行风险拒绝)归 02 不支持,我方原拟以 `209` 对齐,但无供应商透传该粒度 → **已删除**;发卡行级风控落大类 `210 不支持验证`(不产细分),平台层风控归 `998`。 6. **不使用内部重试码 `777`**:所有繁忙 / 限流直接落 `998`,不向客户暴露重试语义(银联码表本无此类)。 7. **细分粒度差异**:银联精鉴码能给"要素级不匹配"(姓名 / 证件 / 手机到底哪个不符)、卡状态子类等更细的码;我方当前按选返结构合并到大类 `2` / `202`,**缺失时大类结论仍正确**,属选返层、不动契约。 8. **计费维度银联码表没有**:计费是商业层叠加,与银联应答码正交。 > 一句话:**相同的是骨架(大类同构、细分选返结构忠实复刻),不同的是有意的归类纠偏 + 平台扩展 + 码值独立。** ### 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` | 当前不开(无供应商透传) | **交付边界(交付前必读)**: 1. **对照 ≠ 透传**:本表是"语义对照表",**不代表每笔都会返回银联原始码**。架构上上游不一定给到该粒度,**商务不得承诺"透传银联原始 `detailRespCode`"**,只承诺"平台结果码 + 可提供对照表"。 2. **码值不同名**:只声明"**对齐**银联应答码体系",不声明"等同/就是银联码"。 3. **关系非纯 1:1**:存在多对一(如多个银联系统码 → `998`)与我方合并(如 `202` ← `2316/2320`);逐码对表以"关系"列为准。 4. **平台级无业务码对应**:`101/997/999` 对应银联报文头级 / 账户级或我方内部,无"业务应答码"等价物。 5. **以银联最新规范为准**:本表银联码值为设计期整理,**交付前须与银联银杏盾官方最新规范校对**。 --- ## 五、计费规则(不进响应体,由 `setCharging()` 内部标记) 判据不是"段位",而是**上游是否对该卡给出了实质核验结论**: | 是否计费 | 对应结果(默认) | |----------|----------| | 计费 | `核验一致(1)`、`核验不一致(2)`、`卡号无效(201)`、`卡状态异常(202)`、`未预留手机号(207)` | | 不计费 | `参数异常(100)`、`11x`、`同一请求参数超限(101)`、`核验不确定(200)`、`不支持验证(210)`、`发卡行不支持(205)`、`卡风控次数超限(206)`、`核验组合不支持(208)`、`997/998/999` | > 原则:**核验实际发生且有定论才计费**;不支持/被超限拦下/格式错/系统错不计费。 --- ## 六、「核验不确定」的边界与可回溯 `核验不确定(200)` 是必要兜底,但必须**收紧到最小**并配套回溯: 1. **收紧范围**:能解释的子集一律拆走——繁忙/超时归 `998`、组合不支持归 `208`、格式问题归 `11x`。`200` 只保留"银行确实响应了、但给不出一致/不一致结论"。 2. **message 自带行动建议**:对外写成 **"核验未确定,建议稍后重试或更换银行卡核验"**,让客户能下一步。 3. **原始上游码落库可回溯**:对外码可粗,但每笔按 `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、卡状态 | 宽松取舍(均偏放行): 1. **校验位 / Luhn 不本地硬拦**——宽松优先,误杀代价 > 放过;可留作可选灰度开关、默认关。 2. **手机号不做号段白名单**——号段年年新增,只判 `1 开头 + 11 位`。 3. **一代证(15 位)不处理**——依《居民身份证法》2013-01-01 全面停用,15 位一律按失效格式拦为 `111`。 4. **港澳台/外籍证件不拦**——格式合法即放行,由供应商判定。 --- ## 八、响应数据体(`SDTBankResponseData`) `data` 只承载**选返补充**:本期即细分码。无补充信息时整个 `data` 为 `null`(如核验一致、或粗粒度不一致)。 ```java @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→发卡行细粒度数据来自第三方、可能滞后,**仅作展示、不进核验判断**。 --- ## 九、对外响应示例 ```json // 核验一致(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()` 中把上游码翻译到统一码,模式一致: ```java @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` 追加细分码(细分缺失永远有大类兜底)。 --- ## 十一、可持续迭代约束(落地纪律) 1. **段位封闭**:1xx=入参/请求侧、2xx=卡账户维度、9xx=系统侧;新增码只在对应段内追加,不跨段。 2. **先归类后建码**:新供应商每个返回码必须先尝试落到现有码;确无法归类才提案新增,并说明它为何不是已有码的子集。 3. **不开特例分支**:禁止在 `convert()` 里写"某家某码"的临时 if;一切走映射表。 4. **映射表全覆盖**:接入新供应商以"上游码 100% 落表"为合并前置条件,未列/未知码统一兜底 `998` 并告警。 5. **对外契约只增不改**:已发布的 `result` 数值语义永不改写,只新增。 --- ## 十二、对外契约原则 > 两层契约决定了两种承诺,发布口径据此区分。 | 层 | 对外定位 | 客户用法 | |---|---|---| | `result` 大类表 | **正式契约**:每码都会出现、语义永远成立,零脚注 | 业务逻辑、验收测试只对这张表 | | `data.detailCode` 细分表 | **诊断增强字段**:只列实际会出现的取值,附一句"是否返回取决于发卡行粒度,**请勿用于业务分支判断、请勿穷举校验**" | 展示 / 客服 / 日志排查 | - **枚举只保留有供应商支持的码、不养死码**:当前无任何供应商点亮的细分码不进枚举(如曾经的 `203/204/209` 已删除)——列客户观察不到的码 = 邀请其造场景去测,测不出反损信任。将来有供应商透传新语义时按"只增不改"补码、文档"新增一行取值",因有扩充声明而**不构成破坏性变更**。 - **验收按大类**:场景类用例(销户卡/无效卡等)断言一律写大类结论(如"该卡不能通过核验:`result=2` 或 `210`"),不绑定原因码。 - **可回溯**:客户追问具体原因 → 由 `traceId` 落库的上游原始码回溯答复。 - **信任来源 = 文档承诺的每条都 100% 成立**,而非码的数量。