银行卡四要素核验 · 自研接口设计
两层契约状态码体系 + 三家供应商映射(蚂蚁 mykj / 365 hl365 / 创蓝253 zhi)。对齐 cs-proxy 工程,对齐银联应答码体系。
本文是设计稿的浓缩展示版。对外只暴露一个 result 整数 + message,靠分段语义自解释;各供应商粗细不一的返回码全部收敛到同一契约。
一、两层契约
各供应商返回粒度粗细不一。若把大类与细分塞进同一个 result,调用方 switch(result) 会漏码;若把细分写进契约,粗供应商下就成"死码"。因此拆成两个字段、两种承诺。
任何数据源下语义恒成立。调用方只对这一层写业务逻辑与验收用例,对应银联必返的 respCode 五大类。
1 核验一致 2 核验不一致 210 不支持验证 100 参数异常 200 核验不确定 998 数据源异常 997 配额耗尽
上游支持才给,缺失不影响主流程。仅用于展示、客服、日志排查,勿做业务分支。对应银联选返的 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
各 Bank4Response:上游码 → 大类 + 细分 + 计费标记(路由切换对调用方无感)
SDTResponse {result, message, data, traceId};上游原始码按 traceId 落库可回溯
五、供应商映射
三家映射均收敛到同一两层契约,路由切到任意一家对调用方无感。粗细不同:365 最细(独家产 201/207/208),蚂蚁、创蓝偏粗。未列/未知上游码统一兜底 998 + 告警。
接口 fourmeta.check。不一致细分藏在 extern_info(转义 JSON,二次解析取 checkResultDetail)。仅 OK/FOURMETA_MATCH_FAIL 计费。
OK→ 1MATCH_FAIL + detail=2→ 2202CARD_NOT_SUPPORT→ 210205HIGH_RISK_ERROR→ 210206OVER_RATE_LIMIT→ 998
判定优先级:error_code≠0 → 系统层;否则键于 detailCode(主键);缺失 → 998(不用 respCode 兜底)。
detailCode=0→ 1detailCode=5→ 2201(独家)detailCode=13→ 2207(独家)detailCode=15→ 210208(独家)error_code=10035→ 101
接口 wsauth.253.com/...。键于 innerresult,计费采信 chargeStatus。0202/0205/0206 为合并语义 → 只落大类、不产细分。
0101→ 10207→ 22020206→ 210(合并,不硬塞)0301/0401→ 2000403→ 998(限流直落)
六、响应示例
下列示例对所有数据源一致(路由无感)。data 在无补充信息时为 null。
{
"result": 1,
"message": "核验一致",
"data": null,
"traceId": "a1b2c3d4..."
}
{
"result": 2,
"message": "核验不一致",
"data": { "detailCode": 201, "detailMsg": "卡号无效" },
"traceId": "a1b2c3d4..."
}
{
"result": 100,
"message": "参数异常",
"data": { "detailCode": 112, "detailMsg": "手机号格式不正确" },
"traceId": "a1b2c3d4..."
}
{
"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(选返),返回粒度由发卡行决定,请勿用于业务分支判断"。覆盖度矩阵与供应商映射为内部资料,不外发。