发生了什么
房东管理后台负责登记房东的银行卡:运营在这里添加一张卡,系统把卡号等信息提交给支付平台,由支付平台找银行做校验。校验通过,后台这一行显示“绑定成功”;校验没过,显示“绑定失败”。两种结果都来自同一条绑卡记录里的状态字段。
绑卡分成两段。第一段是提交:后台程序组装绑卡请求,调用支付平台的“提交绑卡”接口;支付平台收下后只回一个“请求已受理”,表示它接下了这件事。第二段是验证:银行处理完,支付平台再把最终结果异步通知回来。只有第二段的结果到了,才知道这张卡到底绑没绑上。
这次是一张对公账户的卡。对公账户不用输验证码,走的是转账验证,验证在银行侧异步完成,所以提交接口返回的时候,最终结果必然还没出来。
后台程序拿到“已受理”之后没有等第二段,直接把本地绑卡记录写成了绑定成功,页面随即显示已绑定。过了一会儿,银行验证失败,支付平台把这笔绑定改成失败,在支付平台的商户管理平台里能看到失败;我们的系统没有接收和处理这类异步状态变更,本地那条记录就一直停在成功。同一张卡,两个后台一个显示成功、一个显示失败。
本质
一句话:程序把“请求已受理”当成了“绑卡已完成”,而真正的结论要等异步回调,此后没有代码再去改本地状态。
-
提交绑卡和银行验证是两个阶段,两个阶段返回的东西不同。提交接口的返回码 0 表达的是“这笔请求我收下了、开始处理”,不是“银行卡验证通过”,前者不能替代后者。
-
对公账户走免验证码的转账验证,银行侧不会当场给结论。提交接口返回时,这笔业务只能处于“验证中”,本地能写的正确状态也只有“处理中”。
-
addBankCard() 在判断返回码含义这一步出错:看到 0 就写入 SUCCESS 并回给页面成功。它用提交阶段的受理结果,代表了整个绑卡流程的终态。
-
支付平台之后把该笔绑定更新为失败,并发出状态变更通知;我们的系统没有订阅这个通知,也没有实现对应的处理逻辑,所以没有任何动作把本地记录改成失败。
-
本地记录停在 SUCCESS,房东管理后台就照 SUCCESS 渲染。页面不报错、接口不报错,只是展示的状态和支付平台的真实状态分叉了。这次是房东管理后台和支付平台两边对不上才被发现;处置是按这条记录的编号定位到单条数据做订正,软删除并置为失败,产品侧另提需求补齐状态同步。
修复方向是:同步返回只落“验证中”,新增异步回调处理把最终结果写回本地,并对长时间停在“验证中”的记录做主动回查。
错误代码
// 房东管理后台绑卡入口(脱敏教学示例)
public BindCardResult addBankCard(BindCardRequest req) {
// 提交绑卡:支付平台同步只回复“请求已受理”
SubmitBindingResp resp = paymentClient.submitBindingCard(req);
MerchantBankCard card = new MerchantBankCard();
card.setMerchantNo(req.getMerchantNo());
card.setAccountType(req.getAccountType());
card.setCardNoMask(req.getCardNoMask());
// 为什么错:resultStatus=0 只代表请求已受理,
// 对公账户的银行验证是异步的,这里却直接写成终态“绑定成功”
if (resp.getResultStatus() == 0) {
card.setBindStatus(BindStatus.SUCCESS);
} else {
card.setBindStatus(BindStatus.FAIL);
}
bankCardMapper.insert(card);
return BindCardResult.of(card.getBindStatus());
}
修复代码示例
public BindCardResult addBankCard(BindCardRequest req) {
SubmitBindingResp resp = paymentClient.submitBindingCard(req);
MerchantBankCard card = new MerchantBankCard();
card.setMerchantNo(req.getMerchantNo());
card.setAccountType(req.getAccountType());
card.setCardNoMask(req.getCardNoMask());
card.setBindNo(resp.getBindNo()); // 保存支付平台流水号,回调时用它定位本地记录
// 为什么改:受理成功只落“验证中”,终态等银行验证结果回来再写
card.setBindStatus(resp.getResultStatus() == 0
? BindStatus.VERIFYING : BindStatus.FAIL);
bankCardMapper.insert(card);
return BindCardResult.accepted(card.getBindNo());
}
// 支付平台的绑定状态变更回调
public void onBindingStatusChanged(BindingStatusNotify notify) {
BindStatus target = notify.getBindingStatus() == BINDING_FAILED
? BindStatus.FAIL : BindStatus.SUCCESS;
// 为什么改:按流水号只把“验证中”推进到终态,重复通知不会覆盖已定结果
bankCardMapper.updateFromVerifying(notify.getBindNo(), BindStatus.VERIFYING, target);
}
下次遇到这些场景要警惕
- 接入任何“先提交、后出结果”的外部接口:先确认同步返回码到底代表什么,再造一次必然失败的验证,观察本地状态会不会跟着变成失败;如果拿到受理回执就写终态,这条用例一定过不去。
- 同一段绑卡代码要给不同账户类型复用:个人账户和需要异步验证的账户各跑一遍,重点看提交之后本地是不是“验证中”,页面有没有提前显示“已绑定”。
- 只写了提交、没写回调的链路:列出这个接口所有可能的结果通知,确认每一种都有接收方和落库逻辑;再模拟通知丢失,看有没有回查能把长期“验证中”的记录纠正过来。
- 两个系统各存一份同一状态:用同一个业务流水号分别在两边查当前状态,做成日常核对项;只等人工发现页面不一致,通常已经晚了一段时间。