42bc7f6，核验日期为 2026 年 10 月 1 日。旧版本和分支的配置可能不同，请先确认已安装版本包含内置服务商及下列字段。
接入准备
- 启润商户已绑定所需支付服务商，相关凭据有效。仅启用该商户实际开通的支付方式。
- 获取商户账号 ID，作为
pid；获取当前完整的kyren_live_...API Key，作为商户密钥。使用包含前缀的原始值，不使用脱敏值或 Webhook Secret。仅在管理员配置中保存密钥。 - 为 sub2api 配置公网 HTTPS 域名，例如
https://ai.example.com，并将支付通知路径转发到后端。
配置支付服务商
进入 管理员 > 系统设置 > 支付设置，启用的服务商选择易支付。接着在服务商管理中，添加并启用 EasyPay 服务商实例。 启润商户账号ID(PID)，PKey，都可以在启润商户后台 > 开发者工具 > API Keys 页面中获取。
通知地址编辑器会追加固定路径。完整通知地址为
https://ai.example.com/api/v1/payment/webhook/easypay，返回地址为 https://ai.example.com/payment/result；基础地址输入框只填写域名，不重复填写路径。popup 拼接 /epay/submit.php，qrcode 请求 /epay/mapi.php，服务商会规范化 API 基础地址后追加端点。配置字段、通知地址编辑器、易支付客户端。
选择支付方式
按商户开通情况选择内置的alipay 和 / 或 wxpay。核验版本还提供自定义支付方式编辑器。需要其他已记录的启润支付方式时，添加以下本地类型与上游类型映射，并勾选新增的支持方式：
不要照搬其他网关的类型别名或渠道 ID。可用性仍取决于启润商户的服务商绑定。若已安装版本没有自定义方式编辑器，先核验或升级该版本，再向用户展示这些方式。自定义编辑器与序列化。
设置付款金额与入账余额
此易支付客户端不发送money_type，启润因此将 money 解释为 CNY。修改币种显示或商品名称后缀不会改变请求币种。
余额充值入账为 充值金额 × 余额充值倍率，四舍五入到两位小数。软件另设的充值附加费会增加 Epay 请求金额，附加费向上取整到分。首次验证可设 payment_balance_recharge_multiplier = 1、payment_recharge_fee_rate = 0：充值金额 10.00 时，发送 CNY 10.00 的 Epay 基础金额，增加 10.00 余额单位。公开充值前应确定自己的换算政策；美元余额显示不会自动换汇。订单计算、余额倍率、附加费取整。
Epay 基础金额不一定等于最终收银总额。启润可能按支付渠道的费用分担设置增加客户承担的费用；只有不增加此类费用时，示例的最终总额才是 CNY 10.00。Epay 通知和订单查询的 money 返回基础金额，sub2api 根据已保存的余额金额入账，不会把额外费用计入余额。应分别核对基础金额、收银台总额和预期入账余额。
验证付款和入账
- 保存配置，以测试用户创建一笔小额充值，记录商户订单号
out_trade_no、Epay 基础金额、收银台显示的 CNY 总额和充值前余额。 - 完成付款，在启润确认对应订单已付款，同时检查 sub2api 支付订单和预期余额增量。
- 确认后端在
/api/v1/payment/webhook/easypay收到签名 GET 通知，校验 Epay MD5 签名及TRADE_SUCCESS，并返回纯文本success。 - 确认同一订单的重复通知不会再次增加余额。浏览器返回页面或 HTTP
success本身不能证明已入账，需要同时核对订单与余额记录。
常见配置问题
- 地址错误： API 基础地址保留
/epay/，不填写商户控制台地址或完整的submit.php地址。 - 服务端创建被拒绝： 启润启用 API IP 白名单时，将 sub2api 服务器的出口 IP 加入白名单，以便调用
mapi.php。浏览器submit.php收银无需添加每位客户的 IP。 - 收不到通知： 确保 HTTPS 通知地址可从公网访问，保留 GET 查询参数，直接转发后端，不跳转登录页或触发浏览器验证。
- 更换密钥后验签失败： 重新生成启润 API Key 会使旧密钥失效。立即更新 PKey，并验证新付款和待处理通知。不要在支持工单中公开密钥。