还款入账查询监控 — 迭代需求
核心目标：解决客户已经完成还款，但我方系统未能及时、准确入账的问题。本文聚焦 Paystack、Monnify 等支付通道在主动还款、自动代扣、虚拟账户转账、还款链接等方式下的通知异常、主动查询、补偿入账、监控告警和运营排查能力。
1. 背景与目标
当前还款链路依赖支付通道回调、PMT 状态处理和 FCS 销账入账。只依赖通道异步通知存在静默失败风险：通道已收款但回调丢失、回调延迟、回调被我方拒绝、状态查询与回调不一致、重复通知、金额或订单匹配异常等，都会导致客户侧已扣款/已转账，我方借据仍未结清或仍被催收。
本次迭代目标：
- 为每一笔还款建立“发起、通道受理、通道终态、PMT 通知、FCS 入账、客户可见状态”的全链路可查口径。
- 对 Paystack、Monnify 等通道补齐主动查询、补偿处理和异常队列，避免只等待回调。
- 对不同还款方式分别识别异常情况，形成可告警、可查询、可人工处置的闭环。
- 优先保障客户已实际付款后的及时入账，减少误催收、重复扣款、客诉和人工对账成本。
2. 范围
2.1 本期包含
| 能力 | 范围 |
|---|---|
| 还款方式覆盖 | 主动还款、还款链接 / H5 WebPay、Paystack 卡授权代扣、Monnify 卡扣 / Direct Debit、虚拟账户 / Reserved Account 转账、批量代扣 |
| 通道覆盖 | Paystack、Monnify；其他已接入通道按同一抽象字段预留 |
| 通知异常识别 | 回调延迟、回调丢失、重复回调、签名失败、状态倒退、金额不一致、订单无法匹配、通道成功但我方入账失败 |
| 主动查询补偿 | 对处理中、未知、回调失败、客户投诉、金额不一致订单按规则查询通道结果并触发补偿 |
| 监控告警 | 还款回调成功率、回调延迟、通道成功未入账、处理中超时、补偿失败、虚拟账户未匹配等指标 |
| 运营查询 | 支持按客户、手机号、loanId、repaymentOrderId、paymentReference、transactionReference、虚拟账号、金额和时间查询 |
2.2 本期不包含
- 改造支付通道基础接入代码本身；本需求默认 PMT 已具备 Paystack / Monnify 还款、查询和回调能力。
- 设计完整财务对账平台；本期先完成 T+0 查询补偿、异常队列和关键告警。
- 变更 FCS 销账顺序、费用减免规则和还款计划计算逻辑。
- 面向客户展示复杂对账状态；客户侧仍只展示“处理中、成功、失败”等必要状态。
3. 还款方式与风险点
| 还款方式 | 典型通道 | 主要通知方式 | 可能异常 | 对客户影响 |
|---|---|---|---|---|
| App / H5 主动还款 | Paystack WebPay、Monnify One Time Payment | 支付完成回调 + 前端跳转后查询 | 前端成功但回调未到；客户关闭页面；回调晚于客户查询；支付初始化订单重复 | 客户看到扣款成功，但 App 仍显示未还 |
| 还款链接支付 | Paystack WebPay、Monnify Checkout | 通道回调 + 支付参考号查询 | 短链被多次打开；旧链接支付；金额过期后仍支付；链接来源丢失 | 入账归因不清，可能错配借据或重复生成订单 |
| 自动卡代扣 | Paystack Recurring Charge、Monnify Card Token | 通道扣款结果回调 / 查询 | 批量扣款部分成功；卡扣成功但回调失败；通道返回处理中后未再通知 | 到期代扣成功但系统继续催收或再次扣款 |
| 银行账户 Direct Debit | Monnify / NIBSS Mandate | 扣款状态查询 + 回调 | Mandate debit 长时间 pending；银行返回成功延迟；失败原因不明确 | 客户账户已扣但借据未销账，投诉成本高 |
| 虚拟账户 / Reserved Account 转账 | Monnify Reserved Account、独立 VP 服务 | 入账 webhook + 账户交易查询 | 转账备注缺失；金额不等于应还；客户用他人账户转账；虚拟账号未绑定当前借据 | 收款已到账但无法自动匹配，需人工处理 |
| 批量代扣 | Paystack Bulk Charge、批量 RP | 批次查询 + 单笔结果回调 | 批次成功率低；单笔结果缺失；批次回调与单笔状态不一致 | 大量客户状态停留处理中，催收策略误触发 |
4. 支付通道通知意外情况分析
4.1 通道已成功，我方未收到有效通知
| 异常 | 说明 | 系统要求 |
|---|---|---|
| 回调未送达 | 通道网络、DNS、防火墙、我方服务不可用导致 webhook 未到 | PMT 对处理中订单按 TTL 主动查询；回调入口不可用触发 P0 / P1 |
| 回调延迟 | 通道成功后数分钟到数小时才通知 | 订单状态允许保留处理中，但超过阈值必须进入查询补偿队列 |
| 回调被拒绝 | 签名校验失败、IP 白名单、JSON 解析、字段缺失导致拒绝处理 | 保存原始摘要和失败原因；签名失败不入账，但进入安全告警和人工复核 |
| 回调落库成功但异步处理失败 | PMT 已收到通知，但后续事件、MQ、任务处理失败 | 回调接收与业务处理分离；业务处理失败可重放且幂等 |
4.2 通道通知内容与我方订单不一致
| 异常 | 说明 | 系统要求 |
|---|---|---|
| 订单号无法匹配 | paymentReference、transactionReference、reference 与我方订单缺失或不一致 | 不允许自动入账；进入未匹配收款队列，支持人工按客户 / 金额 / 时间匹配 |
| 金额不一致 | 通道成功金额小于、等于或大于本次应还金额 | 小于应还按部分还款规则处理或挂起；大于应还进入超额还款 / 退款规则；必须保留原始金额 |
| 币种不一致 | 通道返回币种非业务币种或为空 | 不自动入账，触发 P1；人工确认前不得销账 |
| 客户身份不一致 | 通道返回 payer、email、account、BVN 与订单客户不一致 | 按支付方式策略处理：虚拟账户可进入人工匹配；代扣类需拦截并告警 |
4.3 状态变化异常
| 异常 | 说明 | 系统要求 |
|---|---|---|
| 重复成功通知 | 同一支付参考号多次收到成功回调 | 幂等处理，只入账一次；重复次数纳入监控 |
| 状态倒退 | 已成功后又收到 failed / reversed / abandoned | 不自动回退已入账；进入冲正 / 争议处理队列 |
| 先失败后成功 | 通道先返回 failed，后续查询或回调显示 success | 以通道最终查询结果和资金事实为准；若已通知客户失败，需补偿入账并记录状态纠偏 |
| 长期处理中 | 通道状态一直 pending / processing | 超过短 TTL 进入查询补偿；超过长 TTL 进入人工处理，避免无限占用在途订单 |
| 冲正 / 退款 / 拒付 | 通道后续发生 reversed、chargeback、refund | 不在普通还款成功流直接处理；进入冲正流程并联动 FCS 调账或人工审批 |
4.4 我方内部链路异常
| 异常 | 说明 | 系统要求 |
|---|---|---|
| PMT 已成功但未通知 FCS | PMT 订单终态成功，FCS 未收到 repayResult 或消费失败 | PMT-FCS 结果通知需可重试、可查、可重放 |
| FCS 收到通知但销账失败 | 借据状态、金额、锁、销账配置或账务异常导致入账失败 | 进入“通道成功未入账”队列，P0 / P1 告警 |
| FCS 已入账但客户侧仍显示未还 | 前端缓存、BNS 查询延迟、读库延迟 | 监控 FCS 入账时间到客户可见状态更新时间的延迟 |
| 重复扣款风险 | 前一笔处理中未确认，又发起新代扣或主动还款 | 还款发起前校验在途订单；查询补偿优先于再次扣款 |
5. 查询补偿需求
5.1 补偿触发条件
| 触发来源 | 条件 | 优先级 |
|---|---|---|
| 定时扫描 | 还款订单处于 pending / processing 超过 5 分钟 | P1 |
| 回调失败 | 回调签名失败、解析失败、业务处理失败 | P0 / P1 |
| 通道成功未入账 | PMT 已确认成功，但 FCS 未入账超过 3 分钟 | P0 |
| 客户投诉 | 客服输入交易参考号、截图金额、虚拟账号等发起查询 | P0 / P1 |
| 批量异常 | 同一通道 15 分钟内处理中订单突增或成功率下降 | P1 |
| 日终对账 | T+1 通道流水存在成功交易但我方未成功入账 | P0 |
5.2 通道查询字段
| 通道 | 查询键 | 说明 |
|---|---|---|
| Paystack | reference、authorization_code、bulk charge batch_code | 主动还款、卡授权代扣、批量扣款需可按单笔和批次查询 |
| Monnify | transactionReference、paymentReference、mandateReference、reserved account accountReference | 卡扣、Direct Debit、虚拟账户转账需分别保存查询键 |
| 虚拟账户服务 | accountNumber、accountReference、sessionId、交易时间、金额 | 用于客户转账后未自动匹配的人工查询 |
5.3 补偿处理规则
| 查询结果 | 处理 |
|---|---|
| 通道成功且订单匹配 | 更新 PMT 终态，重发 FCS 入账通知；FCS 幂等销账 |
| 通道成功但订单不匹配 | 放入未匹配收款队列，禁止自动销账 |
| 通道失败 | 更新失败原因，释放在途订单；按产品策略提醒客户重试 |
| 通道处理中 | 记录查询次数和最近查询时间；按退避策略继续查询 |
| 通道无记录 | 保留我方订单，进入人工核查或按 TTL 关闭 |
| 通道冲正 / 拒付 | 进入争议 / 冲正队列，不直接走普通失败 |
6. 监控告警需求
6.1 核心指标
| 指标 | 口径 | 告警建议 |
|---|---|---|
repayment_callback_success_rate | 成功处理回调数 / 收到回调数 | 5 分钟低于 95% 触发 P1，低于 80% 触发 P0 |
repayment_callback_delay_seconds | 通道交易成功时间到我方收到回调时间 | P95 超过 10 分钟 P1 |
repayment_success_not_posted_count | 通道成功但 FCS 未入账订单数 | 任一生产通道大于 0 且超过 3 分钟 P0 |
repayment_pending_timeout_count | 超过 TTL 仍处理中订单数 | 连续增长 P1 |
repayment_unmatched_fund_count | 收款成功但无法匹配订单数 | 大于 0 进入运营待办，超过阈值 P1 |
repayment_duplicate_callback_count | 重复回调次数 | 异常升高 P2；重复成功不应重复入账 |
repayment_compensation_failed_count | 查询补偿失败次数 | 连续失败 P1 |
repayment_posting_latency_seconds | PMT 确认成功到 FCS 入账完成耗时 | P95 超过 3 分钟 P1 |
6.2 看板分组
| 看板 | 展示内容 |
|---|---|
| 实时还款健康度 | 今日发起、通道成功、FCS 已入账、处理中、失败、未匹配、通道成功未入账 |
| 通道维度 | Paystack / Monnify 成功率、回调延迟、查询失败率、处理中积压 |
| 还款方式维度 | 主动还款、还款链接、卡代扣、Direct Debit、虚拟账户、批量代扣 |
| 异常队列 | 通道成功未入账、未匹配收款、回调失败、金额不一致、长期处理中、冲正 / 拒付 |
| 客服查询 | 输入客户 / loanId / 参考号后展示通道状态、PMT 状态、FCS 入账状态和下一步动作 |
7. 运营查询与处置
7.1 查询字段
| 字段 | 用途 |
|---|---|
custId / 手机号 | 客户投诉时定位客户 |
loanId / 借据号 | 定位应还计划和销账结果 |
repaymentOrderId | 我方还款订单 |
paymentReference / transactionReference / reference | 通道交易查询 |
虚拟账号 / accountReference | 转账还款查询 |
| 金额 + 付款时间 | 截图或银行流水辅助匹配 |
| 通道名称 / 还款方式 | 定位查询 API 和处理规则 |
7.2 处置动作
| 动作 | 权限 | 说明 |
|---|---|---|
| 查询通道状态 | 客服 / 运营 / 技术 | 只读查询，记录操作日志 |
| 触发补偿查询 | 客服主管 / 运营 / 技术 | 对指定订单立即查询通道并刷新状态 |
| 重发 FCS 入账通知 | 技术 / 财务运营 | 仅限通道已成功且订单匹配的订单 |
| 标记未匹配收款 | 财务运营 | 暂不入账，等待客户或财务补充信息 |
| 人工匹配入账 | 财务运营 + 审批 | 金额、客户、借据确认后入账，必须留痕 |
| 关闭异常 | 技术 / 财务运营 | 需填写原因，不删除原始记录 |
8. 数据留痕
每笔还款至少需保留以下状态节点：
| 节点 | 关键字段 |
|---|---|
| 我方发起 | repaymentOrderId、custId、loanId、金额、还款方式、通道、请求时间 |
| 通道受理 | 通道参考号、受理状态、原始响应摘要 |
| 回调接收 | 回调时间、签名校验结果、原始 payload 摘要、幂等键 |
| 主动查询 | 查询时间、查询参数、查询结果、查询次数 |
| PMT 终态 | 成功 / 失败 / 处理中 / 冲正、失败原因、终态时间 |
| FCS 入账 | 入账结果、销账分录号、入账时间、失败原因 |
| 客户可见 | App / H5 查询状态更新时间、通知发送时间 |
| 人工处置 | 操作人、动作、原因、审批记录、附件或备注 |
9. 验收标准
- 任一 Paystack / Monnify 还款订单都能从客户、借据、我方订单号或通道参考号查到完整链路状态。
- 通道成功但 FCS 未入账超过 3 分钟时，系统产生 P0 告警，并进入异常队列。
- 回调丢失或延迟时，处理中订单能被主动查询补偿任务发现并推进到正确终态。
- 重复回调、重复补偿、重复重发通知不会造成重复入账。
- 金额不一致、订单无法匹配、客户身份不一致的交易不会自动销账，能进入人工处理队列。
- 客服可基于客户提供的交易参考号或虚拟账号查询当前处理状态，并能触发受控的补偿查询。
- 所有人工匹配、重发入账通知、关闭异常动作均有权限控制和操作日志。
10. 待确认
- Paystack / Monnify 当前生产启用的还款方式、通道路由和 merchant key 命名。
- PMT 到 FCS 的还款结果通知是 HTTP、MQ 还是混合链路，以及当前是否支持按订单重放。
- 虚拟账户底层提供方和可用查询接口，以确认是否按 Monnify Reserved Account 或独立 VP 服务接入。
- FCS 对部分还款、超额还款、冲正 / 拒付的现有人工处理边界。
- 告警通知渠道、值班责任人和 P0 自动升级规则。