还款结果同步与金额展示 — 迭代需求
本需求聚焦客户完成主动还款、还款链接支付、自动代扣或虚拟账户转账后，App / H5 如何及时、清楚地展示还款处理状态和已还金额。支付回调、补偿入账、监控告警的系统保障口径沿用 15-还款入账查询监控，本文补齐用户可见入口、金额展示、结果同步和客服查询闭环。
1. 背景
当前还款链路存在异步处理特征：客户完成支付后，支付通道、pmt、FCS 入账和前端展示之间存在时间差。若客户侧只展示“未还”或只能等待回调通知，容易产生以下问题：
- 客户已经付款，但 App / H5 仍显示全部应还，误以为还款失败。
- 还款处于处理中时，客户找不到查看进度的入口，可能重复还款或联系客服。
- 部分还款、分期多期还款、逾期还款时，客户不清楚“已还多少、还剩多少、还到哪一期”。
- 客服无法用客户看到的状态口径解释订单进度，导致客诉处理成本上升。
本次迭代需要在不改变 FCS 销账规则的前提下，补齐客户侧还款结果同步和金额展示能力。
2. 目标
- 用户还款中时，App / H5 必须有明确入口展示还款处理中信息。
- 用户已还金额必须清晰展示，区分累计已还、本次已还、当前仍需支付金额。
- 用户完成支付后可主动刷新还款结果，不只能等待 Push、短信或异步回调。
- 客户侧展示状态必须与后端状态口径一致，不因缓存或前端本地状态造成误导。
- 处理中订单不得引导用户无提示重复支付；若允许继续还款，必须说明原因和风险边界。
- 客服后台可查询与客户侧一致的还款结果、金额和下一步处理建议。
3. 范围
3.1 本期包含
| 能力 | 范围 |
|---|---|
| 客户入口 | 首页、还款页、还款结果页、还款记录页展示在途还款入口 |
| 状态同步 | App / H5 主动查询还款结果，后端聚合 FCS 入账状态和 PMT 支付状态 |
| 金额展示 | 应还、已还、处理中金额、剩余应还、逾期费用、销账明细摘要 |
| 还款中展示 | 处理中状态页、状态刷新、预计处理说明、防重复支付提示 |
| 成功展示 | 本次已还金额、累计已还金额、剩余应还、下一期还款信息、结清状态 |
| 失败展示 | 失败原因、是否已扣款说明、重试入口、联系客服信息 |
| 通知同步 | 支付结果变化后触发 App 查询刷新、Push / 短信通知可选联动 |
| 客服后台 | 支持按客户、借据、还款订单查询客户可见状态和金额口径 |
3.2 本期不包含
- 不调整 FCS 还款销账顺序、罚息计算、费用减免、超额还款和冲正规则。
- 不新增完整财务对账平台；通道补偿和告警继续归属 15-还款入账查询监控。
- 不承诺所有支付方式实时到账；客户侧展示需真实反映处理中状态。
- 不在客户端展示支付通道原始错误码、内部异常堆栈或敏感支付信息。
4. 术语
| 术语 | 说明 |
|---|---|
| 还款订单 | 客户一次主动支付、链接支付、代扣或虚拟账户入账对应的我方还款处理单 |
| 支付状态 | pmt 根据支付通道受理、回调、查询得到的交易状态 |
| 入账状态 | FCS 对还款金额执行销账后的账务状态 |
| 客户可见状态 | 后端聚合支付状态和入账状态后返回给 App / H5 的展示状态 |
| 本次已还金额 | 某一笔还款订单已经确认入账的金额 |
| 累计已还金额 | 当前借据所有已确认入账还款金额之和 |
| 处理中金额 | 支付已发起或通道已受理，但尚未完成 FCS 入账确认的金额 |
| 剩余应还金额 | 当前借据仍需客户偿还的金额，以 FCS 最新账务结果为准 |
5. 用户场景
5.1 用户主动还款后等待结果
- 用户在还款页选择金额并完成支付。
- App / H5 返回还款结果页，展示“Payment processing”。
- 页面展示本次支付金额、还款订单号后四位或短参考号、提交时间、预计处理说明。
- 页面提供“Refresh status”按钮，支持用户主动查询最新结果。
- 后端确认 FCS 入账成功后，页面变为成功状态，展示本次已还和剩余应还。
5.2 用户关闭页面后再次打开 App
- 用户有还款订单仍处于处理中。
- 首页或借据卡片展示还款中入口，例如“Repayment processing”。
- 用户点击入口进入还款进度页。
- 页面展示处理中金额、订单提交时间、当前处理阶段和刷新入口。
- 若订单超过处理 TTL，页面提示系统正在核实，不直接要求用户重复支付。
5.3 用户部分还款
- 用户支付金额小于当前总应还金额。
- 入账成功后，页面展示本次已还金额。
- 借据摘要展示累计已还金额和剩余应还金额。
- 还款计划中标识已部分还款，不得把该期展示为全额结清。
5.4 用户已还清当前借据
- FCS 确认当前借据已结清。
- App / H5 展示“Loan repaid”或“Fully paid”。
- 页面展示累计已还金额、最后还款时间、结清说明。
- 不再展示当前借据的立即还款按钮。
- 如存在复借引导，按 13-还款引导复借需求文档 的准入规则展示。
5.5 代扣或虚拟账户转账处理中
- 自动代扣发起后或客户转账后，系统生成或识别在途还款。
- 客户打开 App / H5 时看到还款处理中入口。
- 页面说明系统正在确认支付结果，不展示要求用户再次支付的主按钮。
- 若通道失败且未扣款，页面展示失败原因和重新还款入口。
- 若客户称已扣款但系统未入账，客服可触发查询补偿，客户侧展示“Under review”。
6. 客户可见状态
| 客户可见状态 | 触发条件 | 页面主信息 | 允许操作 |
|---|---|---|---|
NO_REPAYMENT | 无在途还款，仍有应还金额 | 当前应还、到期日、逾期信息 | 发起还款 |
PAYMENT_CREATED | 已创建还款订单，尚未确认通道受理 | Payment started | 查看详情、刷新 |
PAYMENT_PROCESSING | 通道处理中或 PMT 等待最终状态 | Payment processing | 刷新、查看记录、联系客服 |
POSTING_PROCESSING | 通道成功，FCS 正在入账 | Confirming your repayment | 刷新、查看记录、联系客服 |
PARTIALLY_REPAID | FCS 已入账，借据仍有剩余应还 | Payment received | 继续还款、查看计划 |
FULLY_REPAID | FCS 已入账，借据结清 | Loan fully paid | 查看记录、查看合同 / 结清信息 |
PAYMENT_FAILED | 通道明确失败且未入账 | Payment failed | 重新还款、换方式、联系客服 |
UNDER_REVIEW | 金额不一致、订单待匹配、通道成功未入账、客户投诉查询中 | We are checking your repayment | 刷新、联系客服 |
REVERSED_OR_REFUNDED | 已发生冲正、退款或拒付 | Payment reversed | 联系客服 |
状态聚合规则：
- 客户可见状态由后端返回，前端不得仅凭支付页跳转结果自行判定成功。
- FCS 已确认入账时，以 FCS 入账状态和金额为最高优先级。
- PMT 已成功但 FCS 未入账时，展示
POSTING_PROCESSING，不得展示为已还清。 - PMT 失败且 FCS 无入账时，展示
PAYMENT_FAILED。 - 金额不一致、订单无法匹配、冲正、退款、拒付进入
UNDER_REVIEW或REVERSED_OR_REFUNDED，不得自动合并为普通成功。
7. 页面需求
7.0 UI 稿总览
本 UI 稿覆盖本次改造的所有入口：
- 首页 / 借据卡片：存在处理中还款时展示
Repayment processing入口。 - 还款页：新增
Total due、Paid、Processing、Remaining金额摘要。 - 还款结果页：覆盖处理中、成功、失败 / 核实中三类结果。
- 还款记录页：已入账记录和在途订单同页展示。
- 还款计划页：每一期展示已还、处理中、剩余和期次状态。
- 客服 / 运营查询页：展示客户可见状态、金额摘要、在途订单、已入账记录和建议动作。
7.1 首页 / 借据卡片入口
当客户存在任一在途还款订单时，在首页借据卡片或还款入口附近展示状态入口。
展示字段：
| 字段 | 说明 |
|---|---|
| 状态标题 | Payment processing / Confirming your repayment / We are checking your repayment |
| 金额 | 处理中金额，例如 ₦20,000 |
| 提交时间 | 最近一笔在途还款提交时间 |
| 入口动作 | View status |
展示规则：
- 同一借据存在多笔在途还款时，按最新提交时间展示摘要，详情页展示全部在途订单。
- 有在途还款时，立即还款按钮可以保留，但点击前必须先展示在途提示。
- 若剩余应还金额为 0 且有入账延迟，只展示处理中，不再提示继续还款。
7.2 还款页金额摘要
还款页顶部必须展示金额结构，避免用户只看到总应还。
| 字段 | 必填 | 说明 |
|---|---|---|
| Total due | 是 | 当前应还总额，含本金、利息、费用、罚息 |
| Paid | 是 | 当前借据累计已入账金额 |
| Processing | 有在途时必填 | 已发起但未完成入账的金额 |
| Remaining | 是 | 当前仍需支付金额 |
| Due date | 是 | 当前应还日 |
| Overdue days | 逾期时必填 | 逾期天数 |
金额计算口径：
Remaining = FCS 当前应还总额 - 累计已入账金额展示说明：
Paid只统计 FCS 已入账金额。Processing单独展示，不计入Paid。- 如果需要展示“预计还款后剩余”，可用辅助文案展示，但不得替代 FCS 当前剩余应还金额。
- 金额统一展示 NGN，保留千分位；金额为 0 时展示
₦0。
7.3 还款结果页
支付返回后必须进入还款结果页，不能只跳回首页。
处理中
| 信息 | 要求 |
|---|---|
| 标题 | Payment processing |
| 关键金额 | 本次支付金额 |
| 说明 | We are confirming your repayment. This may take a few minutes. |
| 参考号 | 展示我方短参考号或脱敏参考号，不展示完整敏感支付信息 |
| 操作 | Refresh status、Back to home、Contact support |
成功
| 信息 | 要求 |
|---|---|
| 标题 | Payment received 或 Loan fully paid |
| 本次已还 | 本笔订单已入账金额 |
| 累计已还 | 当前借据累计已入账金额 |
| 剩余应还 | 当前借据剩余应还金额 |
| 下一期信息 | 多期产品未结清时展示下一期金额和到期日 |
| 操作 | View repayment record、Back to home |
失败
| 信息 | 要求 |
|---|---|
| 标题 | Payment failed |
| 失败原因 | 使用标准化客户可读原因 |
| 扣款说明 | 明确说明系统未确认收到该笔还款；如客户已被扣款，提示联系客服或等待核实 |
| 操作 | Try again、Choose another method、Contact support |
7.4 还款记录页
还款记录页需要同时展示已入账记录和在途记录。
| 字段 | 说明 |
|---|---|
| 还款订单号 | 我方订单号或短展示号 |
| 金额 | 本笔支付金额 / 入账金额 |
| 状态 | Processing / Posted / Failed / Under review / Reversed |
| 还款方式 | Card / Bank transfer / USSD / Repayment link / Auto debit |
| 支付通道 | Paystack / Monnify / 其他 |
| 提交时间 | 客户发起或系统代扣时间 |
| 入账时间 | FCS 入账成功时间，未入账则为空 |
| 失败原因 | 失败或复核状态展示客户可读原因 |
7.5 还款计划页
每一期展示：
- 应还金额。
- 已还金额。
- 剩余金额。
- 处理中金额。
- 状态：未还、部分已还、已还、逾期、处理中。
多期产品中，某笔还款跨期销账时，详情页需展示销账摘要，例如：
| 期次 | 本次入账分配 | 入账后状态 |
|---|---|---|
| 第 1 期 | ₦10,000 | 已还 |
| 第 2 期 | ₦5,000 | 部分已还 |
8. 后端需求
8.1 还款结果聚合查询
新增或改造客户侧查询接口，由业务后端聚合 FCS 和 PMT 状态。
输入建议：
| 字段 | 说明 |
|---|---|
custId | 从登录态获取 |
loanId | 借据编号，可选；为空时返回当前在贷借据摘要 |
repaymentOrderId | 还款订单号，可选；用于结果页刷新 |
scene | home / repayment_page / result_page / record_page |
输出建议：
| 字段 | 说明 |
|---|---|
loanId | 借据编号 |
visibleStatus | 客户可见状态 |
totalDueAmount | 当前应还总额 |
paidAmount | 累计已入账金额 |
processingAmount | 处理中金额 |
remainingAmount | 剩余应还金额 |
currentDueDate | 当前应还日 |
overdueDays | 逾期天数 |
latestRepaymentOrder | 最近一笔还款订单摘要 |
processingOrders | 在途订单列表 |
postedRecords | 已入账记录列表 |
nextInstallment | 下一期还款信息 |
actions | 前端可展示动作，如 repay / refresh / contact_support |
8.2 状态同步策略
| 场景 | 同步策略 |
|---|---|
| 支付返回结果页 | 立即查询一次聚合接口 |
| 结果页处理中 | 前 2 分钟每 10 秒自动刷新；之后停止自动轮询，仅保留手动刷新 |
| App 冷启动 / 回到前台 | 查询当前借据是否存在在途还款 |
| 收到 Push / 短信点击 | 打开结果页并查询最新聚合状态 |
| 客服触发补偿后 | 下一次客户刷新时展示最新状态 |
刷新限制：
- 手动刷新需做频控，例如 5 秒内不重复请求。
- 前端不得无限轮询。
- 后端需缓存短时间内重复查询结果，但不能缓存超过还款状态 TTL。
8.3 防重复还款
创建新还款订单前必须检查同一客户、同一借据是否存在在途还款。
| 条件 | 处理 |
|---|---|
| 在途金额大于等于剩余应还金额 | 阻止继续还款，展示还款处理中入口 |
| 在途金额小于剩余应还金额 | 可允许继续还差额，但需明确展示已在处理金额 |
| 在途订单超过短 TTL 但未终态 | 默认进入核实状态，优先触发查询补偿 |
| 客户强制继续还款 | 本期不建议开放；如开放需产品、财务、风控共同确认超额还款处理规则 |
8.4 金额口径
FCS 是应还、已还、剩余金额的唯一账务来源。
要求：
paidAmount仅来自 FCS 已入账记录。processingAmount来自 PMT / 业务还款订单中未终态或已成功未入账的金额。remainingAmount来自 FCS 当前账务结果，不由前端用本地金额自行扣减。- 若 PMT 成功金额与 FCS 入账金额不一致，客户侧展示
UNDER_REVIEW，金额明细中保留“已确认入账金额”和“核实中金额”。 - 金额字段后端统一返回最小货币单位或 decimal 字符串，前端不得使用浮点数自行计算。
8.5 通知
| 触发 | 通知要求 |
|---|---|
| 还款订单创建成功 | 可发送站内消息或 Push，提示正在处理 |
| FCS 入账成功 | 发送还款成功通知，包含本次已还金额和剩余应还摘要 |
| 借据结清 | 发送结清通知 |
| 还款失败 | 发送失败通知，包含标准化失败原因和重试入口 |
| 进入人工核实 | 可发送核实中通知，避免用户重复支付 |
通知内容不得包含完整卡号、完整通道 token、完整内部流水号或敏感身份信息。
9. 客服与后台需求
客服查询页需展示与客户侧一致的聚合口径。
| 区块 | 字段 |
|---|---|
| 客户可见摘要 | 客户当前看到的状态、入口文案、可操作按钮 |
| 金额摘要 | 当前应还、累计已还、处理中、剩余应还 |
| 在途订单 | 还款订单号、金额、方式、通道、PMT 状态、FCS 入账状态、提交时间 |
| 已入账记录 | 入账金额、入账时间、销账分配、借据状态 |
| 异常提示 | 通道成功未入账、金额不一致、未匹配、处理中超时 |
| 建议动作 | 等待、触发查询补偿、联系财务、引导客户重试 |
客服操作：
- 只读查看客户可见状态。
- 触发指定还款订单的状态刷新或补偿查询，权限沿用 15-还款入账查询监控。
- 复制脱敏参考号给客户。
- 添加客户反馈备注，例如客户称已扣款、提供截图、提供银行流水时间。
10. 异常展示文案
| 场景 | 英文标题 | 关键信息 | 主操作 | 次操作 | 是否可重试 |
|---|---|---|---|---|---|
| 支付处理中 | Payment processing | We are confirming your repayment. This may take a few minutes. | Refresh status | Back to home | 否 |
| 入账处理中 | Confirming your repayment | Your payment was received by the payment channel. We are updating your loan balance. | Refresh status | Contact support | 否 |
| 支付失败 | Payment failed | We could not complete this repayment. No repayment has been confirmed for this order. | Try again | Choose another method | 是 |
| 余额不足 | Insufficient funds | Your bank reported insufficient funds for this payment. | Try again | Choose another method | 是 |
| 银行拒绝 | Bank declined payment | Your bank declined this payment. Please try another card or payment method. | Choose another method | Contact support | 是 |
| OTP / 3DS 未完成 | Verification not completed | Bank verification was not completed, so this repayment was not confirmed. | Try again | Contact support | 是 |
| 客户称已扣款但未入账 | We are checking your repayment | If money was deducted, we will verify the payment and update your loan balance after confirmation. | Refresh status | Contact support | 否 |
| 金额不一致 | Repayment under review | The amount received does not match the expected repayment amount. We are reviewing it. | Contact support | Back to home | 否 |
| 已结清 | Loan fully paid | Your loan has been fully repaid. | View repayment record | Back to home | 否 |
11. 数据留痕
每次客户侧状态展示需能追溯以下信息：
| 数据 | 说明 |
|---|---|
| 查询时间 | 客户打开页面或刷新状态的时间 |
| 展示状态 | 返回给客户的 visibleStatus |
| 金额快照 | totalDue、paid、processing、remaining |
| 订单快照 | 在途订单和最新已入账记录 |
| 来源状态 | PMT 状态、FCS 入账状态、异常队列状态 |
| 前端场景 | home / repayment_page / result_page / record_page |
| 版本 | App / H5 版本，便于排查缓存和展示问题 |
12. 埋点与监控
| 指标 | 口径 |
|---|---|
repayment_status_entry_exposure | 还款中入口曝光次数 |
repayment_status_entry_click | 还款中入口点击次数 |
repayment_result_refresh_click | 用户手动刷新次数 |
repayment_processing_visible_count | 客户侧展示处理中订单数 |
repayment_processing_to_success_seconds | 客户侧处理中到成功展示耗时 |
repayment_paid_amount_mismatch_count | 客户侧金额快照与 FCS 最新金额不一致次数 |
duplicate_repayment_block_count | 因在途订单阻止重复还款次数 |
support_contact_from_repayment_count | 还款状态页联系客服次数 |
监控要求：
- 客户侧
PAYMENT_PROCESSING超过配置 TTL 的订单，应与后台异常队列打通。 - 客户侧
POSTING_PROCESSING超过 3 分钟，需进入通道成功未入账监控。 - 金额快照不一致需记录服务端日志，避免前端继续展示旧金额。
13. 验收标准
- 用户完成主动还款后，必须进入结果页，并能看到本次支付金额和处理状态。
- 用户存在处理中还款订单时，首页或借据卡片必须展示还款中入口，可进入状态详情页。
- 还款页必须展示
Total due、Paid、Remaining；有在途订单时必须展示Processing。 - FCS 入账成功后，客户刷新页面能看到本次已还金额、累计已还金额和最新剩余应还金额。
- 部分还款后，页面不得展示为已结清；必须展示剩余应还金额。
- 全额结清后，页面不得继续展示当前借据立即还款按钮。
- PMT 成功但 FCS 未入账时，客户侧展示入账处理中，不得展示还款成功或已结清。
- 支付失败且未入账时，客户侧展示标准化失败原因和重试入口。
- 同一借据存在在途还款且在途金额覆盖剩余应还时，系统阻止重复还款并引导查看状态。
- 客服后台能看到与客户侧一致的状态、金额、在途订单和已入账记录。
- 客户手动刷新、App 回前台、支付结果页刷新均不会造成重复入账或重复创建还款订单。
- 金额字段不包含浮点误差，前端展示金额与后端返回金额一致。
14. 待确认
- 当前 App / H5 首页、借据卡片和还款页的具体入口位置与 UI 稿。
- FCS 当前可返回的累计已还、分期已还、销账分配字段是否已满足展示要求。
- PMT 还款订单状态与 FCS 入账状态的现有关联键：
repaymentOrderId、loanId、paymentReference是否完整。 - 主动还款、还款链接、代扣、虚拟账户是否都能生成统一还款订单。
- 处理中短 TTL、长 TTL、自动刷新频率和客服触发补偿权限。
- 是否需要在还款结果页引导开启 Push 通知；如需要，按 AF / Firebase Push 通知权限需求统一处理。