芬达支付 - 供应商对接研判报告

一、通道对接基本要素

统一下单接口 (Pay)

接口网关: https://fenda-pay-api.yzmvp.com/api/pay/unifiedOrder
请求方式: POST JSON (Content-Type: application/json)
金额单位: amount (分，整型，避免浮点数精度受损)
加签规则: 参数 ASCII 排序拼接 &key=密钥 进行 MD5 加密，计算 32 位大写。

异步回调通知 (Notify)

请求方式: POST Form URL-Encoded
防刷白名单 IP: 34.87.131.26
商户侧响应: 回调处理成功后必须输出纯文本 success (小写)。
成功判定: state == 2 或 state == 5 均代表支付成功。

二、兼容性对比与模板评估

经过与 PMP 系统现有的 110+ 历史支付通道对比，发现芬达的报文协议、加签机制及回调处理与 xinhe2 (兴禾内部通道) 达到 100% 协议吻合。以下是核心接口比对数据：

比对维度	芬达 (Fenda Pay) 协议	兴禾 (xinhe2) 驱动	匹配度
下单参数	`mchNo`, `mchOrderNo`, `productId`, `amount`, `clientIp`, `notifyUrl`, `reqTime`	`mchNo`, `mchOrderNo`, `productId`, `amount`, `clientIp`, `notifyUrl`, `reqTime`	🟢 100% 一致
下单响应	`code=0`成功，跳转链接位于 `data.payData`，上游单号位于 `data.payOrderId`	`code=0`成功，跳转链接位于 `data.payData`，上游单号位于 `data.payOrderId`	🟢 100% 一致
加签规则	非空参数字典序 + `&key=密钥`，MD5 32位大写	使用 `utils.Sign(params, apiKey, "key", true)` 字典序计算，完全吻合	🟢 100% 一致
回调格式	表单接收，状态值 `state = 2/5` 为成功，成功返回 `success`	支持表单流转化为 JSON 校验，`state = 2/5` 为成功，输出 `success`	🟢 100% 一致

🚀 研判结论：本项目采用 可套模板 结论。根据项目规范，为了保证管理后台配置的隔离性以及方便日志排查、后续对各自 IP 白名单的安全审查，不建议共用 xinhe2 模板字典，而应该在本地新建独立驱动包 fenda 并在后台注册 FD 模板值。

三、系统集成与交叉注册方案 (Diff Draft)

为了让新通道 FD 运行上线，我们需要在系统的三处地方进行代码与字典的声明配置：

1. 分发器注册

修改文件：pmp/common/channels/handler.go

// 导入部分追加
import "pmp_backend/common/channels/fenda"

// SelectPay 模板 switch 结构追加
case "FD":
    res, params, err = fenda.Pay(ctx, order, channel, extra)
    return

2. 网关回调路由注册

修改文件：pmp/pmp_gateway/router/http.go

// 导入部分追加
import "pmp_backend/common/channels/fenda"

// notify 路由组追加
notify.POST("/fenda", fenda.NotifyHandler, middle.NotifyVerifySign("mchOrderNo", "key", true))

3. 管理后台模板字典追加

修改文件：pmp/pmp_admin/service/out/channel_template.go

// ChannelTemplates 列表追加
{"FD", "/notify/fenda"}, // 芬达 - PMP

四、本地 Mock 单元测试输出

本地测试文件 fenda_test.go 已经 Mock 了上游接口的出参并验证了加签逻辑，核心测试均已断言通过：

TestSignature: 确认芬达非空字典序加签无误，空值不参与签名；
TestPay: 模拟网关返回下单成功，确认 PayUrl 和 TradeNum（上游单号）获取正确。

一、 通道对接基本要素