--- title: 银行卡四要素核验 · 自研接口设计 accent: blue toc: true nav: auto --- # 银行卡四要素核验 · 自研接口设计 > 两层契约状态码体系 + 三家供应商映射(蚂蚁 mykj / 365 hl365 / 创蓝253 zhi)。对齐 cs-proxy 工程,对齐银联应答码体系。 :::tip 本文是设计稿的浓缩展示版。对外只暴露一个 `result` 整数 + `message`,靠分段语义自解释;各供应商粗细不一的返回码全部收敛到同一契约。 ::: ## 一、两层契约 各供应商返回粒度粗细不一。若把大类与细分塞进同一个 `result`,调用方 `switch(result)` 会漏码;若把细分写进契约,粗供应商下就成"死码"。因此拆成两个字段、两种承诺。 :::grid {cols=2} :::card {accent=green title="result — 大类码(必返 · 稳定契约)"} 任何数据源下语义恒成立。调用方**只对这一层写业务逻辑与验收用例**,对应银联必返的 respCode 五大类。 :badge[1 核验一致]{color=green} :badge[2 核验不一致]{color=amber} :badge[210 不支持验证]{color=coral} :badge[100 参数异常]{color=blue} :badge[200 核验不确定]{color=gray} :badge[998 数据源异常]{color=gray} :badge[997 配额耗尽]{color=purple} ::: :::card {accent=gray title="data.detailCode — 细分码(选返 · 诊断增强)"} 上游支持才给,**缺失不影响主流程**。仅用于展示、客服、日志排查,勿做业务分支。对应银联选返的 detailRespCode,返回粒度由发卡行决定。 :badge[110~113 格式细化]{color=blue} :badge[201/202/204/207 不一致细化]{color=amber} :badge[203/205/206/208/209 不支持细化]{color=coral} ::: ::: :::warn **落码铁律**:`result` 落大类;`data.detailCode` 只落"该上游码能支撑的最细、且仍为真"的码——上游分不清子因时 detailCode **留空**,绝不硬塞。 例:智 `0206`(无卡支付**或**发卡行不支持,分不清)→ `result=210`、detailCode 留空;蚂蚁 `CARD_NOT_SUPPORT`(明确非银联卡)→ `result=210`、`detailCode=205`。 ::: ## 二、大类码表 通用 `SDTCode` + 银行专属 `SDTBankCategory`(200/210),对齐银联 respCode 五大类。`result` 是单一整数命名空间,所有码互不冲突。 | result | 枚举 | 含义 | 对齐银联 | 计费 | |--------|------|------|----------|------| | :badge[1]{color=green} | `SDTCode.核验一致` | 四要素一致 | 00 验证一致 | 是 | | :badge[2]{color=amber} | `SDTCode.核验不一致` | 要素与银行留存不符 | 01 验证不一致 | 是 | | :badge[210]{color=coral} | `SDTBankCategory.不支持验证` | 该卡/组合无法核验的大类兜底 | 02 不支持验证 | 否 | | :badge[100]{color=blue} | `SDTCode.参数异常` | 入参格式不合法(网关前置为主) | 03 要素格式有误 | 否 | | :badge[200]{color=gray} | `SDTBankCategory.核验不确定` | 银行已响应但无法定论,建议重试/换卡 | 04 系统异常(部分) | 否 | | :badge[998]{color=gray} | `SDTCode.数据源异常` | 上游不可用/繁忙/超时/限流,一律直接落 | 04 系统异常 | 否 | | :badge[997]{color=purple} | `SDTCode.调用配额耗尽` | 套餐/余额/产品未开通 | 平台级 | 否 | | :badge[101]{color=gray} | `SDTCode.同一请求参数超限` | 平台侧同参数频控 | 平台级 | 否 | :::note `bank4` 不使用 `系统重试(777)`:777 是内部重试信号、对客户无意义;限流类即时重试也只会再撞限流。所有繁忙/超时**一律直接落 998**。 ::: ## 三、细分码表 `SDTBankDetailCode`,按归属大类分组。「本期」指蚂蚁 + 365 + 创蓝三家接入下是否实际会出现;预留码保留在枚举中、对外契约不删,接入更细供应商后自动点亮。 | detailCode | 含义 | 归属大类 | 来源 | 本期 | |------------|------|----------|------|------| | `110` | 姓名格式不正确 | :badge[100]{color=blue} | 网关前置(供应商作二次安全网) | 启用 | | `111` | 证件号格式不正确 | :badge[100]{color=blue} | 网关前置 | 启用 | | `112` | 手机号格式不正确 | :badge[100]{color=blue} | 网关前置 | 启用 | | `113` | 银行卡号格式不正确 | :badge[100]{color=blue} | 网关前置 | 启用 | | `201` | 卡号无效(银行侧无此卡号) | :badge[2]{color=amber} | 365 `detailCode=5`(独家干净 201) | 启用 | | `202` | 卡状态异常(挂失/冻结/过期) | :badge[2]{color=amber} | 蚂蚁 `detail=2`、智 `0207`、365 `2/6/11` | 启用 | | `204` | 卡已销户 | :badge[2]{color=amber} | 当前候选供应商均无独立码 | 预留 | | `207` | 未预留手机号 | :badge[2]{color=amber} | 365 `detailCode=13`(独家) | 启用 | | `203` | 无卡支付未开通 | :badge[210]{color=coral} | 当前候选供应商均无独立码 | 预留 | | `205` | 发卡行不支持 / 非银联卡 | :badge[210]{color=coral} | 蚂蚁 `CARD_NOT_SUPPORT`、365 `3/4` | 启用 | | `206` | 卡风控次数超限 | :badge[210]{color=coral} | 蚂蚁 `HIGH_RISK`、智 `0402`、365 `14` | 启用 | | `208` | 核验组合不支持 | :badge[210]{color=coral} | 365 `detailCode=15`(独家) | 启用 | | `209` | 风控拒绝(发卡行级·非次数) | :badge[210]{color=coral} | 无供应商点亮(365 `10040` 属平台层→998) | 预留 | ## 四、请求处理链路 参数格式校验由我方网关前置完成(fail-fast、不下发、行为与路由无关);供应商只负责真实性核验。 :::steps :::step {title="① 前置校验"} `validateBank4`:只拦结构上绝无可能正确的。命中 → :badge[100]{color=blue} + 11x,不下发供应商、不计费 ::: :::step {title="② 路由"} 负载均衡 / `client.hard` 定向 → 蚂蚁 / 365 / 创蓝,按权重与配置 ::: :::step {title="③ 供应商核验"} 各 `client.processBank4`:蚂蚁 AntChain 网关 / 365 明文 HTTP / 创蓝 wsauth.253.com ::: :::step {title="④ convert 两层映射"} 各 `Bank4Response`:上游码 → 大类 + 细分 + 计费标记(路由切换对调用方无感) ::: :::step {title="⑤ 响应 / 落库"} `SDTResponse {result, message, data, traceId}`;上游原始码按 traceId 落库可回溯 ::: ::: ## 五、供应商映射 三家映射均收敛到同一两层契约,**路由切到任意一家对调用方无感**。粗细不同:365 最细(独家产 201/207/208),蚂蚁、创蓝偏粗。未列/未知上游码统一兜底 :badge[998]{color=gray} + 告警。 :::grid {cols=3} :::card {accent=blue title="蚂蚁 mykj · AntChain"} 接口 `fourmeta.check`。不一致细分藏在 `extern_info`(转义 JSON,二次解析取 `checkResultDetail`)。仅 `OK`/`FOURMETA_MATCH_FAIL` 计费。 - `OK` → :badge[1]{color=green} - `MATCH_FAIL + detail=2` → :badge[2]{color=amber} `202` - `CARD_NOT_SUPPORT` → :badge[210]{color=coral} `205` - `HIGH_RISK_ERROR` → :badge[210]{color=coral} `206` - `OVER_RATE_LIMIT` → :badge[998]{color=gray} ::: :::card {accent=green title="365 hl365 · 三层码"} 判定优先级:`error_code≠0` → 系统层;否则键于 `detailCode`(主键);缺失 → :badge[998]{color=gray}(不用 respCode 兜底)。 - `detailCode=0` → :badge[1]{color=green} - `detailCode=5` → :badge[2]{color=amber} `201`(独家) - `detailCode=13` → :badge[2]{color=amber} `207`(独家) - `detailCode=15` → :badge[210]{color=coral} `208`(独家) - `error_code=10035` → :badge[101]{color=gray} ::: :::card {accent=purple title="创蓝253 zhi · CL"} 接口 `wsauth.253.com/...`。键于 `innerresult`,**计费采信 chargeStatus**。`0202/0205/0206` 为合并语义 → 只落大类、不产细分。 - `0101` → :badge[1]{color=green} - `0207` → :badge[2]{color=amber} `202` - `0206` → :badge[210]{color=coral}(合并,不硬塞) - `0301/0401` → :badge[200]{color=gray} - `0403` → :badge[998]{color=gray}(限流直落) ::: ::: ## 六、响应示例 下列示例对所有数据源一致(路由无感)。`data` 在无补充信息时为 `null`。 :::grid {cols=2} :::card {accent=green title="核验一致(data 为 null)"} ```json { "result": 1, "message": "核验一致", "data": null, "traceId": "a1b2c3d4..." } ``` ::: :::card {accent=amber title="不一致 · 带细分(智 0202 → 201)"} ```json { "result": 2, "message": "核验不一致", "data": { "detailCode": 201, "detailMsg": "卡号无效" }, "traceId": "a1b2c3d4..." } ``` ::: :::card {accent=blue title="参数异常 · 手机号格式(100 + 112)"} ```json { "result": 100, "message": "参数异常", "data": { "detailCode": 112, "detailMsg": "手机号格式不正确" }, "traceId": "a1b2c3d4..." } ``` ::: :::card {accent=coral title="不支持验证 · 非银联卡(210 + 205)"} ```json { "result": 210, "message": "不支持验证", "data": { "detailCode": 205, "detailMsg": "发卡行不支持" }, "traceId": "a1b2c3d4..." } ``` ::: ::: `convert()` 翻译模式(每家供应商一张映射表,公共接口零改动): ```java BankCodeMapping m = BankCodeMapper.map(supplier(), rawCode, rawSubCode, message); resp.setResult(m.category()); // result 永远是大类码(必有) if (m.detailCode() != null) { // 细分码:供应商支持才给,挂到 data resp.setData(new SDTBankResponseData(m.detailCode(), m.detailMsg())); } setCharging(m.charged()); ``` :::note **对外发布口径**:`result` 大类表为正式契约(零脚注、永远成立),调用方只对它写业务逻辑与验收用例;`data.detailCode` 为诊断增强字段——"对应银联 detailRespCode(选返),返回粒度由发卡行决定,请勿用于业务分支判断"。覆盖度矩阵与供应商映射为内部资料,不外发。 :::