手机分期商户放款流水号门店识别优化 — 迭代需求
本文为 Nigeria、Ghana 手机分期商户放款流水号的增量需求。目标是在不破坏当地支付通道受理、唯一性、幂等、查单、回调和对账能力的前提下，使门店可以从交机页展示的流水号中识别本门店。除本文明确调整的内容外，沿用现有商户放款、交机放行和资金终态规则。
1. 现状结论
当前交机页 Merchant payout 卡片中的 Reference No. 来源于我司支付链路：支付中台生成支付流水号并提交给实际支付通道，放款结果回到资金系统和手机分期业务系统后，交机页再展示该号码。
上述现状已在 Nigeria 现有链路中确认。Ghana 现有方案将 EP（InterPayAfrica）作为 Cashout 候选通道，但当前资料不足以证明商户放款已经生产启用；因此本文将相同流水号归属规则同步纳入 Ghana，并把 EP 接入、生产商户确认和 UAT 通过作为上线前置条件，不把候选方案表述为现网能力。
因此，该号码的生成规则可以由我司调整，但不能只修改页面展示文案。新规则必须作用于实际商户放款流水，并保证后续仍可使用同一号码完成通道查单、结果回调关联、异常补偿和财务对账。
当前流水号只包含业务线、唯一序列和系统路由所需信息，不包含门店可识别信息。门店收到多笔货款时，难以仅凭流水号判断款项属于哪一家门店。
2. 背景与目标
手机分期订单在商户放款最终成功后进入交机环节。SA 可在交机页看到放款状态、流水号、金额和付款时间，但现有流水号对门店没有直接识别价值，尤其在同一商户主体管理多家门店、同一收款账户承接多店货款时，门店需要依赖金额、时间或人工询问确认归属。
本期目标如下：
- 商户放款流水号包含稳定、可辨认的门店标识，门店人员能够判断该流水属于本店。
- 流水号满足当前启用支付通道的字符、长度、唯一性和幂等要求。
- 同一笔放款在首次提交、超时查单、结果回调和非终态重试期间始终使用同一流水号，避免重复出款。
- 门店名称修改后不反向改变历史流水号，历史款项仍可准确追溯。
- 交机页同时展示门店名称和完整流水号，避免仅靠缩写猜测门店归属。
- 存量放款流水保持不变，新规则只应用于生效后首次创建的商户放款流水。
3. 范围与边界
| 范围 | 是否纳入 | 说明 |
|---|---|---|
| Nigeria 手机分期商户放款 | 是 | 覆盖 Paystack、Monnify 及上线前确认的实际启用通道 |
| Ghana 手机分期商户放款 | 是 | 覆盖 EP（InterPayAfrica）Cashout 的 MMT、GIP 放款；须完成接入和 UAT 门禁 |
SA App 交机页 Merchant payout 卡片 | 是 | 展示门店名称和新流水号 |
| 门店流水标识生成与固化 | 是 | 从正式门店名称生成稳定标识，并处理重名与非法字符 |
| 支付通道提交、查单、回调和对账 | 是 | 全链路使用同一实际流水号 |
| 管理后台门店详情 | 是 | 查看门店名称和已固化的门店流水标识 |
| 历史已生成商户放款流水 | 否 | 不改号、不迁移、不重新提交 |
| 首付款、客户还款、绑卡流水号 | 否 | 本期只调整商户放款流水 |
| 商户收款账户、放款路由和通道优先级 | 否 | 沿用现有规则 |
| 支付通道返回的自有交易号 | 否 | 保留原样，不能用门店流水号覆盖 |
| 其他国家手机分期 | 否 | 后续复用前须重新确认当地通道限制 |
Nigeria 与 Ghana 均属于本期交付范围，不能仅完成 Nigeria 验收即关闭需求。两个国家可使用独立开关灰度，但正式验收必须分别通过各自支付通道的真实请求、查单、回调和重复流水号验证。
4. 角色与系统责任
| 角色/系统 | 责任 |
|---|---|
| 门店人员 | 根据交机页、到账记录或对账材料中的门店流水标识确认款项归属 |
| SA | 在交机页核对订单门店、商户放款状态、金额、流水号和付款时间，不自行修改流水号 |
| 渠道/门店管理 | 维护正式门店名称；查看门店流水标识及其状态 |
| 手机分期业务 | 以订单已固化的交机门店为准提供门店归属，不接受客户端临时传入门店名决定流水号 |
| 支付中台 | 按统一规则生成唯一流水号，并在提交、查单、回调、补偿和对账中保持一致 |
| 支付通道 | 按其约束受理流水号并返回通道交易结果及通道自有交易号 |
| 财务/运营 | 可按完整流水号、门店流水标识、订单和通道交易号查询与对账 |
5. 名词与业务口径
| 名词 | 业务含义 |
|---|---|
| 商户放款流水号 | 我司为一次商户放款生成并提交支付通道的唯一 reference；交机页展示该号码 |
| 门店流水标识 | 从正式门店名称生成并固化的短标识，用于嵌入商户放款流水号，例如 slot-ikeja |
| 门店通道码 | 门店流水标识按通道长度和字符集压缩后的稳定短码，例如 slotik、slotac；同一门店在同一国家内保持不变 |
| 通道交易号 | 支付通道受理后生成的自有号码；与我司商户放款流水号分别保存和使用 |
| EP | 本文特指 Ghana 的 InterPayAfrica/EPA Cashout 通道，不是资金系统内代表多余还款的同名交易类型 |
| 首次创建 | 一笔商户放款第一次形成唯一流水号的时点；非终态查单或安全重试不属于重新创建 |
6. 门店流水标识规则
6.1 生成来源
- 门店流水标识必须来源于订单已固化的正式门店名称及门店唯一身份，不能使用 SA 手工输入、页面缓存、收款账户名或商户主体名称代替。
- 同一商户下的不同门店必须拥有不同的门店流水标识；不同商户的同名门店也不得产生冲突。
- 门店流水标识在首次用于商户放款前固化。固化后，普通门店改名不自动改变该标识，防止历史与新流水口径割裂。
- 门店尚未产生任何放款流水时，具备门店维护权限的人员可基于正式名称重新生成；一旦已有放款流水，只允许保留原标识。确需变更时应走受控迁移并保留前后值、操作人、时间和原因，不得覆盖历史记录。
6.2 规范化规则
门店流水标识按以下顺序生成：
- 使用正式门店名称，统一转为小写。
- 连续空格或分隔符统一为单个短横线。
- 移除支付通道不支持的符号、重音和不可见字符；可可靠转换的字符先转为拉丁字母。
- 保留小写英文字母、数字和短横线，不保留客户信息、手机号、银行账号、地址或人员姓名。
- 优先保留最能识别门店的品牌/商户简称和地点词，默认长度为 3–12 个字符。
- 规范化后不足 3 个字符、与其他门店冲突或截断后冲突时，在可识别词后增加稳定的门店区分码；区分码来自门店唯一身份，不由人工随意填写。
- 为适配 Ghana EP 的 20 位端到端限制，每个门店还须生成 6 位门店通道码：优先使用品牌和地点的可识别缩写；不足 6 位时补充稳定区分码，超过 6 位时按可识别词优先级缩写，不得直接截断导致重名。
示例：
| 正式门店名称 | 门店流水标识示例 | 说明 |
|---|---|---|
Slot Ikeja City Mall | slot-ikeja | 保留品牌与地点 |
3C Hub Abuja | 3c-hub-abuja | 数字可保留 |
Best Phone Shop! | best-phone | 移除不支持符号和通用尾词 |
两家均名为 Prime Mobile | prime-a7k2、prime-f4m8 | 使用稳定区分码消除冲突 |
例如 Slot Ikeja City Mall 的门店通道码可为 slotik，Slot Accra Mall 可为 slotac。页面仍展示完整门店名称；6 位通道码只承担流水号内的快速识别和通道兼容职责。
6.3 异常处理
| 场景 | 处理 |
|---|---|
| 门店名称为空、只有特殊符号或无法生成有效标识 | 阻止创建新的商户放款流水，提示先完善门店资料；不得使用 unknown、收款账户名或随机门店名继续放款 |
| 门店流水标识重复 | 自动加入稳定区分码后再次校验；仍冲突则阻止创建并进入人工处理 |
| 门店已改名 | 历史和后续流水默认继续使用已固化标识；页面展示当前门店名称并可查看历史名称 |
| 订单门店与收款账户归属不一致 | 阻止放款并进入现有收款账户异常处理，不得通过改流水号掩盖归属错误 |
| 门店已停用但订单仍在履约 | 沿用现有订单和门店状态规则；若允许继续履约，仍使用订单固化的门店流水标识 |
7. 商户放款流水号规则
7.1 格式
新流水号使用以下业务结构，具体大小写和分隔方式按国家通道规则输出：
国家标识 + 业务标识 + 门店通道码 + 唯一序列 + 系统路由标识为同时满足 Nigeria Paystack 的最小长度和 Ghana EP 的端到端最大长度，新格式固定为 20 位：
| 分段 | 长度 | 规则 |
|---|---|---|
| 国家标识 | 2 | Nigeria 为 ng/NG，Ghana 为 gh/GH |
| 业务标识 | 1 | 商户放款固定为 p/P |
| 门店通道码 | 6 | 来源于已固化门店，不足或冲突时使用稳定区分码 |
| 唯一序列 | 9 | 全局唯一，不得只使用日期或门店内自增号 |
| 系统路由标识 | 2 | 沿用支付中台所需路由能力；不得包含敏感信息 |
国家示例：
| 国家/通道 | 流水号示例 | 门店识别 |
|---|---|---|
| Nigeria / Paystack、Monnify | ngpslotik2609k7m4w01 | slotik 对应 Slot Ikeja |
| Ghana / EP Cashout | GHPSLOTAC2609K7M4W01 | SLOTAC 对应 Slot Accra |
其中：
p/P表示 PocketBuy merchant payout，避免与首付、客户还款等其他流水混淆。slotik/SLOTAC是已固化的门店通道码。- 唯一序列必须具备跨门店、跨并发的全局唯一性，不能从客户信息、完整订单号或账号派生。
- 同一业务流水在数据库、通道请求、查单、回调匹配、交机页和对账材料中保持同值；不得由各系统分别拼接。
7.2 通道兼容要求
各国家按实际支付通道采用以下规则：
| 国家/通道 | 提交字段 | 已核规则 | 本期采用规则 |
|---|---|---|---|
| Nigeria / Paystack | transfer reference | 16–50 位；只允许小写字母、数字、短横线和下划线；唯一 | 固定 20 位、小写字母数字，不使用分隔符 |
| Nigeria / Monnify | transfer reference | 每笔转账 reference 唯一；重复 reference 会被拒绝 | 固定 20 位、小写字母数字；同一笔重试复用原号 |
| Ghana / EP MMT | merch_trans_ref_no | Create 文档写 String(100)，但后续查单与回调只支持 20 位 | 按端到端最严限制固定 20 位、大写字母数字 |
| Ghana / EP GIP | merch_trans_ref_no | Create、GetTransStatus 均为 String(20)；回调 merchant_trans_ref_no 为 String(20) | 固定 20 位、大写字母数字 |
EP 文档未明确 merch_trans_ref_no 的字符集、大小写和重复号响应，只给出大写字母数字样例。因此“大写字母数字”是本期的保守候选格式，必须在 EP UAT 中完成创建、查单、回调原值返回和重复号验证；验证不通过不得上线 Ghana 新格式，也不得在生产环境试错。
所有通道共同要求：
- 在同一支付通道商户主体下全局唯一，不得只保证单门店内唯一。
- 同一笔非终态放款的重复提交、查单和补偿必须复用原流水号；只有原放款已明确终态且业务规则允许创建新放款时，才生成新流水号。
- 支付通道新增、切换或升级前，必须先验证该通道的字符、长度、大小写、唯一性和幂等要求；若通道限制更严格，以更严格规则为准，不能在线截断或静默改写已生成流水号。
- 提交支付通道前必须完成本地格式和唯一性校验。校验失败时不得调用通道。
EP 还须遵循以下关联规则：
- MMT 和 GIP 创建、
GetTransStatus均使用原merch_trans_ref_no；回调虽命名为merchant_trans_ref_no，其值必须与原号一致后才能关联业务。 - EP 返回的
trans_ref_no是通道自有交易号，与我司门店可识别流水号分别保存，不能互相覆盖。 - Create 返回 HTTP 200 且
status_code=1仅代表 EP 已受理；必须继续查单并完成账务确认后，才可作为交机放行依据。
7.3 唯一性与幂等
- 一笔商户放款只能有一个当前有效的我司流水号。
- 通道请求超时、网络中断或结果未知时，先使用原流水号查单；未确认原交易终态前不得生成新流水号再次出款。
- 通道返回“流水号已存在”时，应按原流水号查询既有交易，不能直接换号重试。
- 回调、主动查询和人工补偿必须同时核对流水号、业务订单、金额、币种、收款账户和通道，不能只凭流水号推进放款成功。
- 通道自有交易号与我司流水号分别留存；任一号码均可定位到同一笔商户放款及其订单、门店和收款账户。
8. 主流程
- 手机分期订单满足现有商户放款前置条件。
- 系统读取订单已固化的门店身份、正式门店名称和收款账户归属。
- 系统取得该门店已固化的门店流水标识和门店通道码；尚未固化时按本文规则生成、查重并固化。
- 支付中台按订单国家和实际通道生成包含门店通道码的唯一商户放款流水号，并完成对应通道的格式校验。
- 系统使用该流水号向选定支付通道提交放款。
- 放款处理中、查单、回调和补偿均继续使用原流水号。
- 放款最终成功后，交机页展示订单门店名称、流水号、金额和付款时间。
- 财务和运营可按流水号或门店流水标识查询该笔放款及其通道交易号。
9. 交机页展示
Merchant payout 卡片调整为：
| 页面字段 | 展示规则 |
|---|---|
| Status | 沿用现有放款状态映射 |
| Store | 展示订单固化的正式门店名称；为空视为异常，不显示猜测值 |
| Reference No. | 展示实际提交支付通道的完整商户放款流水号，不显示临时前端拼接值 |
| Amount | 沿用现有币种和金额格式 |
| Paid at | 沿用现有业务时区展示规则 |
页面规则：
- 门店通道码应在
Reference No.中完整可见，不得以省略号隐藏门店部分；空间不足时允许换行或提供完整值查看能力。 - 页面显示的
Store、流水号中的门店标识和订单门店必须属于同一门店。 - 放款结果未知或页面查询失败时，不得展示客户端缓存的旧流水号作为已完成凭证。
- 不展示完整收款账号、BVN/NIN、客户手机号、IMEI、支付密钥或通道原始报文。
- 本期不改变“商户放款最终成功后才允许完成交机”的既有规则。
10. 存量与生效边界
| 对象 | 处理 |
|---|---|
| 上线前已生成流水号的放款 | 保持原号；后续查单、回调、补偿和页面展示继续使用原号 |
| 上线前已有订单但尚未创建商户放款流水 | 上线后首次创建时使用新规则 |
| 上线时处于处理中或结果未知的放款 | 视为存量，必须继续使用原号查单，不得为了增加门店标识重新生成 |
| 上线后新建放款 | 使用新规则 |
| 存量门店 | 在首次适用新规则时生成并固化门店流水标识；生成失败则阻止新放款并提示处理 |
11. 异常与边界场景
| 场景 | 处理 |
|---|---|
| 流水号超过通道长度 | 阻止提交并记录格式版本异常；不得在线截断唯一序列、门店通道码或系统路由信息 |
| 流水号包含非法字符 | 创建前拦截并重新规范化；仍不合法则不调用通道 |
| 支付通道返回 reference 重复 | 使用原 reference 查单并核对业务归属；不得直接换号出款 |
| 请求超时或返回未知 | 保持处理中，使用原 reference 主动查询或补偿 |
| 回调 reference 与原流水号不一致 | 不推进成功，记录异常并进入人工核对 |
| 回调金额、币种或收款账户不一致 | 不推进成功，按资金异常处理 |
| 页面门店名称与流水号标识不匹配 | 不将该号码作为可确认的门店付款凭证，页面提示数据异常并阻断完成交机 |
| 支付通道不支持新格式 | 上线前验证失败则该通道不得启用新规则；不得生产试错 |
| EP 创建字段允许 100 位但查单/回调只允许 20 位 | 一律按 20 位生成和传递，不得按创建接口的宽松值生成长号 |
| EP 回调字段名与请求字段名不同 | 适配为同一内部商户放款流水号；原值不一致时不推进成功 |
12. 前端埋点要求
本期仅补充交机页可见结果的产品埋点；支付流水生成、通道受理和对账属于服务端业务证据，不由前端事件代替。
| event_name | 事件类型 | event_page / owner | 唯一触发时机 | 业务含义 | 属性及来源 | 指标/漏斗 |
|---|---|---|---|---|---|---|
merchant_payout_reference_view | view | device_delivery / SA App | 交机页成功渲染一笔商户放款卡片且服务端返回流水号时，每次页面会话最多一次 | SA 已看到可用于门店识别的放款凭证 | country_code、currency、payout_status、reference_format_version、store_reference_status、payment_provider 均来自服务端标准结果；不上传完整流水号、门店名、订单号、账号或错误文本 | 按国家/通道的新格式覆盖率、门店标识有效率、放款凭证可见率 |
merchant_payout_reference_mismatch_view | result | device_delivery / SA App | 服务端明确返回门店与流水号标识不匹配，页面展示异常且阻断交机时一次 | 监控门店归属异常对交机的影响 | country_code、payment_provider、mismatch_reason_code、reference_format_version 来自服务端稳定枚举；不上传原始 reference 或门店名 | 按国家/通道的门店归属异常率、异常订单数 |
埋点要求：
event_name和event_page固定，不拼接门店名、流水号、订单号、支付通道返回文本或错误详情。- 页面事实可由当前渲染状态提供；门店匹配结果、格式版本和支付通道必须使用服务端可信结果。
- 埋点上报成功与否不得影响支付结果、交机页展示或交机放行。
13. 验收标准
- 新规则生效后创建的 Nigeria、Ghana 手机分期商户放款，实际提交支付通道的 reference 均包含对应门店的稳定可识别门店通道码。
- Nigeria 示例门店
Slot Ikeja City Mall可形成ngpslotik2609k7m4w01；Ghana 示例门店Slot Accra Mall可形成GHPSLOTAC2609K7M4W01。门店人员结合页面完整门店名，无需查询客户信息即可识别本店流水。 - Nigeria 流水号固定 20 位小写字母数字，并通过已启用 Paystack、Monnify 放款通道验证；Ghana EP 流水号固定 20 位大写字母数字，并通过 MMT、GIP 创建、查单、回调和对账验证。
- 同一支付通道商户主体下批量生成至少 100 万个测试流水号，无重复；并验证并发创建时不会产生重复有效流水。
- 同名门店、超长门店名、数字开头、含标点、重音或无法直接转换的名称均能生成合法且不冲突的门店流水标识。
- 门店改名后，历史流水号不变；已有放款流水的门店不会因普通改名自动更换门店流水标识。
- 同一笔放款首次提交、超时查单、非终态重试、回调和补偿使用同一 reference；模拟请求超时后不会生成第二个 reference 或重复出款。
- Paystack、Monnify 或 EP 返回 reference 已存在或结果不明确时，系统使用原 reference 查询并核对订单、金额、币种和收款账户，不直接换号重试。
- 交机页同时展示正确的
Store、完整Reference No.、金额和付款时间；流水号中的门店标识与订单门店一致。 - 页面门店与流水标识不匹配、流水号缺失或结果未知时，不得把该信息作为商户付款成功凭证，也不得完成交机。
- 上线前已生成流水号的成功、失败、处理中和未知放款均保持原号，历史查单、回调和对账不受影响。
- 财务或运营使用完整流水号、门店流水标识或通道交易号，均可定位到同一笔商户放款、订单和门店。
- 前端埋点能统计新格式覆盖和门店归属异常，且数据中不包含完整流水号、门店名称、客户信息或收款账户信息。
- EP MMT 创建接口即使接受超过 20 位的值，系统仍只生成和提交 20 位；
GetTransStatus与回调可原值关联，且 EPtrans_ref_no与我司流水号分开保存。 - Nigeria 与 Ghana 分别通过验收，按国家、通道、格式版本可监控和回滚；不得以 Nigeria 验收结果替代 Ghana EP 验收。
14. 发布与验证要求
- 上线前分别在 Paystack、Monnify、EP 测试环境或经通道认可的验证方式中完成发起、查单、回调和重复 reference 验证，不能只做本地格式校验。
- EP 必须分别验证 MMT 与 GIP；重点确认 20 位大写字母数字、大小写原样返回、重复号响应，以及请求
merch_trans_ref_no与回调merchant_trans_ref_no的一致映射。 - Nigeria、Ghana 分别从受控门店灰度，核对通道受理结果、到账描述、交机页展示和财务对账，再逐步扩大范围。本需求只有两个国家均达到验收标准后才算完成。
- 灰度期间同时监控通道参数拒绝、reference 重复、查单未命中、页面门店不匹配和异常补偿数量。
- 回滚时只停止为新放款生成新格式，不修改已提交的新格式流水号；已提交交易继续按原 reference 查单和处理。
15. 待确认事项
| 待确认项 | 说明 |
|---|---|
| 银行到账摘要展示 | 支付通道和收款银行是否完整展示我司 reference，需用真实或等效通道环境验证；即使银行短信截断，SA App 和对账材料仍须展示完整值 |
| 门店流水标识维护权限 | 建议由渠道运营或门店资料管理员负责，具体角色与审批流程待确认 |
| 现网启用放款通道 | 上线前确认 Nigeria 手机分期实际启用的 Paystack、Monnify 或其他通道及其最新 reference 限制 |
| Ghana EP 生产条件 | 确认 Ghana Cashout 生产商户、MMT/GIP 权限、凭证、限额、费率、结算和 SLA；未确认不得生产启用 |
| EP 字符与幂等合同 | 供应商文档未明确 merch_trans_ref_no 字符集、大小写和重复号行为，须取得书面确认并完成 UAT |
| 门店改名后的新标识申请 | 默认不自动变更；如业务确需调整，需补充受控迁移审批和历史查询方式 |