银行卡四要素核验 · 自研接口设计

更新于 2026-06-14

银行卡四要素核验 · 自研接口设计

两层契约状态码体系 + 三家供应商映射(蚂蚁 mykj / 365 hl365 / 创蓝253 zhi)。对齐 cs-proxy 工程,对齐银联应答码体系。

本文是设计稿的浓缩展示版。对外只暴露一个 result 整数 + message,靠分段语义自解释;各供应商粗细不一的返回码全部收敛到同一契约。

一、两层契约

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

result — 大类码(必返 · 稳定契约)

任何数据源下语义恒成立。调用方只对这一层写业务逻辑与验收用例,对应银联必返的 respCode 五大类。

1 核验一致 2 核验不一致 210 不支持验证 100 参数异常 200 核验不确定 998 数据源异常 997 配额耗尽

data.detailCode — 细分码(选返 · 诊断增强)

上游支持才给,缺失不影响主流程。仅用于展示、客服、日志排查,勿做业务分支。对应银联选返的 detailRespCode,返回粒度由发卡行决定。

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

落码铁律:result 落大类;data.detailCode 只落"该上游码能支撑的最细、且仍为真"的码——上游分不清子因时 detailCode 留空,绝不硬塞。 例:智 0206(无卡支付或发卡行不支持,分不清)→ result=210、detailCode 留空;蚂蚁 CARD_NOT_SUPPORT(明确非银联卡)→ result=210、detailCode=205。

二、大类码表

通用 SDTCode + 银行专属 SDTBankCategory(200/210),对齐银联 respCode 五大类。result 是单一整数命名空间,所有码互不冲突。

result 枚举 含义 对齐银联 计费
1 SDTCode.核验一致 四要素一致 00 验证一致 是
2 SDTCode.核验不一致 要素与银行留存不符 01 验证不一致 是
210 SDTBankCategory.不支持验证 该卡/组合无法核验的大类兜底 02 不支持验证 否
100 SDTCode.参数异常 入参格式不合法(网关前置为主) 03 要素格式有误 否
200 SDTBankCategory.核验不确定 银行已响应但无法定论,建议重试/换卡 04 系统异常(部分) 否
998 SDTCode.数据源异常 上游不可用/繁忙/超时/限流,一律直接落 04 系统异常 否
997 SDTCode.调用配额耗尽 套餐/余额/产品未开通 平台级 否
101 SDTCode.同一请求参数超限 平台侧同参数频控 平台级 否

bank4 不使用 系统重试(777):777 是内部重试信号、对客户无意义;限流类即时重试也只会再撞限流。所有繁忙/超时一律直接落 998。

三、细分码表

SDTBankDetailCode,按归属大类分组。「本期」指蚂蚁 + 365 + 创蓝三家接入下是否实际会出现;预留码保留在枚举中、对外契约不删,接入更细供应商后自动点亮。

detailCode 含义 归属大类 来源 本期
110 姓名格式不正确 100 网关前置(供应商作二次安全网) 启用
111 证件号格式不正确 100 网关前置 启用
112 手机号格式不正确 100 网关前置 启用
113 银行卡号格式不正确 100 网关前置 启用
201 卡号无效(银行侧无此卡号) 2 365 detailCode=5(独家干净 201) 启用
202 卡状态异常(挂失/冻结/过期) 2 蚂蚁 detail=2、智 0207、365 2/6/11 启用
204 卡已销户 2 当前候选供应商均无独立码 预留
207 未预留手机号 2 365 detailCode=13(独家) 启用
203 无卡支付未开通 210 当前候选供应商均无独立码 预留
205 发卡行不支持 / 非银联卡 210 蚂蚁 CARD_NOT_SUPPORT、365 3/4 启用
206 卡风控次数超限 210 蚂蚁 HIGH_RISK、智 0402、365 14 启用
208 核验组合不支持 210 365 detailCode=15(独家) 启用
209 风控拒绝(发卡行级·非次数) 210 无供应商点亮(365 10040 属平台层→998) 预留

四、请求处理链路

参数格式校验由我方网关前置完成(fail-fast、不下发、行为与路由无关);供应商只负责真实性核验。

① 前置校验

validateBank4:只拦结构上绝无可能正确的。命中 → 100 + 11x,不下发供应商、不计费

② 路由

负载均衡 / client.hard 定向 → 蚂蚁 / 365 / 创蓝,按权重与配置

③ 供应商核验

各 client.processBank4:蚂蚁 AntChain 网关 / 365 明文 HTTP / 创蓝 wsauth.253.com

④ convert 两层映射

各 Bank4Response:上游码 → 大类 + 细分 + 计费标记(路由切换对调用方无感)

⑤ 响应 / 落库

SDTResponse {result, message, data, traceId};上游原始码按 traceId 落库可回溯

五、供应商映射

三家映射均收敛到同一两层契约,路由切到任意一家对调用方无感。粗细不同:365 最细(独家产 201/207/208),蚂蚁、创蓝偏粗。未列/未知上游码统一兜底 998 + 告警。

蚂蚁 mykj · AntChain

接口 fourmeta.check。不一致细分藏在 extern_info(转义 JSON,二次解析取 checkResultDetail)。仅 OK/FOURMETA_MATCH_FAIL 计费。

  • OK → 1
  • MATCH_FAIL + detail=2 → 2 202
  • CARD_NOT_SUPPORT → 210 205
  • HIGH_RISK_ERROR → 210 206
  • OVER_RATE_LIMIT → 998
365 hl365 · 三层码

判定优先级:error_code≠0 → 系统层;否则键于 detailCode(主键);缺失 → 998(不用 respCode 兜底)。

  • detailCode=0 → 1
  • detailCode=5 → 2 201(独家)
  • detailCode=13 → 2 207(独家)
  • detailCode=15 → 210 208(独家)
  • error_code=10035 → 101
创蓝253 zhi · CL

接口 wsauth.253.com/...。键于 innerresult,计费采信 chargeStatus。0202/0205/0206 为合并语义 → 只落大类、不产细分。

  • 0101 → 1
  • 0207 → 2 202
  • 0206 → 210(合并,不硬塞)
  • 0301/0401 → 200
  • 0403 → 998(限流直落)

六、响应示例

下列示例对所有数据源一致(路由无感)。data 在无补充信息时为 null。

核验一致(data 为 null)
{
  "result": 1,
  "message": "核验一致",
  "data": null,
  "traceId": "a1b2c3d4..."
}
不一致 · 带细分(智 0202 → 201)
{
  "result": 2,
  "message": "核验不一致",
  "data": { "detailCode": 201, "detailMsg": "卡号无效" },
  "traceId": "a1b2c3d4..."
}
参数异常 · 手机号格式(100 + 112)
{
  "result": 100,
  "message": "参数异常",
  "data": { "detailCode": 112, "detailMsg": "手机号格式不正确" },
  "traceId": "a1b2c3d4..."
}
不支持验证 · 非银联卡(210 + 205)
{
  "result": 210,
  "message": "不支持验证",
  "data": { "detailCode": 205, "detailMsg": "发卡行不支持" },
  "traceId": "a1b2c3d4..."
}

convert() 翻译模式(每家供应商一张映射表,公共接口零改动):

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());

对外发布口径:result 大类表为正式契约(零脚注、永远成立),调用方只对它写业务逻辑与验收用例;data.detailCode 为诊断增强字段——"对应银联 detailRespCode(选返),返回粒度由发卡行决定,请勿用于业务分支判断"。覆盖度矩阵与供应商映射为内部资料,不外发。