尊戎商城

Appearance

YML配置说明 ​

平台端 / 财务管理 / 自动分账

微信收付通分账 YAML 配置说明 ​

1. 配置范围 ​

微信收付通配置统一使用以下前缀：

:
  profit-sharing:

配置需要同时写入：

  • -front/src/main/resources/application.yml：负责用户支付、退款、微信回调、进件轮询和分账重试。

  • -admin/src/main/resources/application.yml：负责进件、平台补贴、提现、账单、分账订单和结算账户等后台操作。

生产环境可以在对应的 application-prod.yml 中覆盖配置。Spring Profile 会合并基础配置和生产配置，因此只在生产文件中填写敏感值即可。

front 和 admin 必须使用同一个收付通平台商户号、APIv3 密钥、证书和业务参数。两者不在同一台服务器时，需要分别部署证书文件，并填写各自服务器上的路径。

2. 推荐配置方式 ​

不要把商户号、APIv3 密钥或证书内容提交到 Git。推荐通过环境变量注入，YAML 只保留变量名和非敏感默认值。

2.1 -front ​

:
  profit-sharing:
    # 总开关：启用后会在启动阶段强校验必填项
    enabled: ${WX_ECOMMERCE_ENABLED:false}

    # 收付通平台商户身份，不是原直连支付 wx.pay 的商户号
    mch-id: ${WX_ECOMMERCE_MCH_ID:}
    api-v3-key: ${WX_ECOMMERCE_API_V3_KEY:}
    cert-serial-no: ${WX_ECOMMERCE_CERT_SERIAL_NO:}

    # 当前服务器上的证书绝对路径
    private-cert-path: ${WX_ECOMMERCE_PRIVATE_CERT_PATH:}
    private-key-path: ${WX_ECOMMERCE_PRIVATE_KEY_PATH:}
    public-key-path: ${WX_ECOMMERCE_PUBLIC_KEY_PATH:}
    public-key-id: ${WX_ECOMMERCE_PUBLIC_KEY_ID:}

    # ma=小程序，mp=公众号，app=APP
    pay-source: ${WX_ECOMMERCE_PAY_SOURCE:ma}
    mini-app-id: ${WX_ECOMMERCE_MINI_APP_ID:}
    mp-app-id: ${WX_ECOMMERCE_MP_APP_ID:}
    app-app-id: ${WX_ECOMMERCE_APP_APP_ID:}

    # 必须是公网可访问的 HTTPS 地址，路径不要修改
    pay-notify-url: ${WX_ECOMMERCE_PAY_NOTIFY_URL:}
    combine-notify-url: ${WX_ECOMMERCE_COMBINE_NOTIFY_URL:}
    notify-url: ${WX_ECOMMERCE_SHARING_NOTIFY_URL:}
    refund-notify-url: ${WX_ECOMMERCE_REFUND_NOTIFY_URL:}

    max-sharing-ratio: ${WX_ECOMMERCE_MAX_SHARING_RATIO:30}
    auto-sharing: ${WX_ECOMMERCE_AUTO_SHARING:true}
    max-retry-count: ${WX_ECOMMERCE_MAX_RETRY_COUNT:3}
    sharing-retry-interval-ms: ${WX_ECOMMERCE_RETRY_INTERVAL_MS:600000}

    # 定时任务统一由 front 承担
    applyment-poll-enabled: true
    sharing-retry-enabled: true

    # 推广员佣金默认仍由平台代收后按原体系结算
    promoter-sharing-enabled: false
    promoter-relation-type: DISTRIBUTOR

回调环境变量应设置为：

WX_ECOMMERCE_PAY_NOTIFY_URL=
WX_ECOMMERCE_COMBINE_NOTIFY_URL=
WX_ECOMMERCE_SHARING_NOTIFY_URL=
WX_ECOMMERCE_REFUND_NOTIFY_URL=

2.2 -admin ​

admin 使用与 front 相同的平台商户身份和 AppID，但不接收支付回调，也不执行定时任务：

:
  profit-sharing:
    enabled: ${WX_ECOMMERCE_ENABLED:false}

    mch-id: ${WX_ECOMMERCE_MCH_ID:}
    api-v3-key: ${WX_ECOMMERCE_API_V3_KEY:}
    cert-serial-no: ${WX_ECOMMERCE_CERT_SERIAL_NO:}

    # 路径必须是 admin 所在服务器上的真实路径
    private-cert-path: ${WX_ECOMMERCE_PRIVATE_CERT_PATH:}
    private-key-path: ${WX_ECOMMERCE_PRIVATE_KEY_PATH:}
    public-key-path: ${WX_ECOMMERCE_PUBLIC_KEY_PATH:}
    public-key-id: ${WX_ECOMMERCE_PUBLIC_KEY_ID:}

    pay-source: ${WX_ECOMMERCE_PAY_SOURCE:ma}
    mini-app-id: ${WX_ECOMMERCE_MINI_APP_ID:}
    mp-app-id: ${WX_ECOMMERCE_MP_APP_ID:}
    app-app-id: ${WX_ECOMMERCE_APP_APP_ID:}

    # admin 不承担支付和退款回调，保持为空
    pay-notify-url:
    combine-notify-url:
    notify-url:
    refund-notify-url:

    max-sharing-ratio: ${WX_ECOMMERCE_MAX_SHARING_RATIO:30}
    auto-sharing: ${WX_ECOMMERCE_AUTO_SHARING:true}
    max-retry-count: ${WX_ECOMMERCE_MAX_RETRY_COUNT:3}
    sharing-retry-interval-ms: ${WX_ECOMMERCE_RETRY_INTERVAL_MS:600000}

    # 防止 front、admin 重复轮询和重复调用微信
    applyment-poll-enabled: false
    sharing-retry-enabled: false

    promoter-sharing-enabled: false
    promoter-relation-type: DISTRIBUTOR

3. 参数说明 ​

配置项 必填条件 默认值 说明

enabled 是 false 收付通总开关。关闭时不装配分账模块，继续走原直连支付流程。

mch-id 开启时必填 无 收付通平台商户号，即微信接口中的 sp_mchid，不要填写原直连商户号。

api-v3-key 开启时必填 无 32 位 APIv3 密钥，用于回调解密和敏感字段处理。

cert-serial-no 开启时必填 无 商户 API 证书序列号。

private-cert-path 开启时必填 无 apiclient_cert.pem 的可读文件路径。

private-key-path 开启时必填 无 apiclient_key.pem 的可读文件路径，必须严格限制文件权限。

public-key-path 开启时必填 无 微信支付公钥 pub_key.pem 的可读文件路径。

public-key-id 开启时必填 无 微信支付公钥 ID，格式类似 PUB_KEY_ID_xxx。

pay-source 开启时必填 ma 支付渠道，只允许 ma、mp、app。

mini-app-idpay-source=ma 无 平台小程序 AppID。

mp-app-idpay-source=mp 无 平台公众号 AppID。

app-app-idpay-source=app 无 平台 APP AppID。

pay-notify-urlfront 必填 无 服务商普通支付结果回调。

combine-notify-urlfront 必填 无 合单支付结果回调。

notify-urlfront 必填 无 分账结果回调。

refund-notify-urlfront 必填 无 退款结果回调。

max-sharing-ratio 开启时必填 30 最大分账比例，必须在 1 至 30 之间，并与微信后台上限一致。

auto-sharing 否 true 支付成功后是否自动发起分账。

max-retry-count 否 3 单个失败分账单的最大自动重试次数。

sharing-retry-interval-ms 否 600000 分账重试任务间隔，单位毫秒，默认 10 分钟。

applyment-poll-enabled 否 true 是否轮询进件状态；项目约定只在 front 开启。固定每 5 分钟执行。

sharing-retry-enabled 否 true 是否自动重试失败分账；项目约定只在 front 开启。

promoter-sharing-enabled 否 false 是否在确认收货后把佣金直接分给推广员微信零钱。

promoter-relation-type 否 DISTRIBUTOR 推广员个人分账接收方关系类型，一般不修改。

4. 参数获取位置 ​

参数 获取位置

平台商户号 微信支付服务商平台的收付通/平台商户资料

APIv3 密钥 微信商户平台 -> 账户中心 -> API 安全 -> APIv3 密钥

商户 API 证书及序列号 微信商户平台 -> 账户中心 -> API 安全 -> API 证书

微信支付公钥及公钥 ID 微信商户平台的微信支付公钥配置页面

AppID 对应小程序、公众号或 APP 的微信开放平台配置

最大分账比例 微信服务商后台的供应链分账配置

消费者付款所使用的小程序或公众号必须与收付通平台商户满足微信要求的主体及绑定关系。AppID 还必须与项目实际登录渠道一致，否则可能出现 sp_openid 与 sp_appid 不匹配而拒单。

5. 启动校验规则 ​

当 enabled=true 时，应用启动阶段会进行强校验。以下任一情况都会拒绝启动：

  • 平台商户号、APIv3 密钥或证书序列号为空。

  • APIv3 密钥不是 32 位。

  • 商户证书、商户私钥或微信支付公钥不存在、不是文件或不可读。

  • 微信支付公钥 ID 为空。

  • pay-source 不是 ma、mp、app，或对应渠道 AppID 为空。

  • max-sharing-ratio 不在 1 至 30 范围内。

回调地址为空或不是 HTTPS 当前只会记录告警，不会阻止启动。对 -front 来说仍应视为上线阻断项，否则可能出现微信已收款但本地订单未更新。

6. 部署与安全要求 ​

  • 私钥、APIv3 密钥不得进入代码仓库、镜像层、日志或工单截图。

  • Linux 上建议证书目录仅允许运行用户读取，例如目录权限 700、私钥权限 600。

  • 容器部署时通过 Secret 挂载 PEM 文件，并把配置路径指向容器内挂载点。

  • front 与 admin 分机部署时，不能直接复用另一台机器的绝对路径。

  • 回调域名必须使用公网 HTTPS，反向代理需要将四个回调路径转发到 -front。

  • front 和 admin 的 enabled 应同时开启或同时关闭，避免后台显示已启用但支付仍走旧流程。

  • 定时任务只能有一个执行方。本项目固定由 front 执行，admin 必须关闭两个任务开关。

7. 上线检查清单 ​

  • [ ] 微信侧已开通收付通、二级商户进件和供应链分账能力。

  • [ ] front、admin 使用同一套平台商户身份和相同业务参数。

  • [ ] 收付通商户号与原 wx.pay 直连商户号未混用。

  • [ ] APIv3 密钥为 32 位，证书序列号与当前商户 API 证书一致。

  • [ ] 三个 PEM 文件在两个服务的运行环境中均存在且可读。

  • [ ] pay-source 与实际支付渠道一致，对应 AppID 已填写。

  • [ ] 四个回调地址均为 -front 公网 HTTPS 地址，并能正确路由。

  • [ ] max-sharing-ratio 与微信后台配置一致且不超过 30。

  • [ ] 仅 front 开启进件轮询和分账重试任务。

  • [ ] 启动日志显示收付通配置校验通过，无回调地址告警。

  • [ ] 测试环境完成支付、支付回调、分账、退款及退款回退的完整联调。

8. 关闭与回退 ​

需要停用收付通时，同时在 front 和 admin 设置：

:
  profit-sharing:
    enabled: false

关闭后收付通模块 Bean 不再装配，新支付恢复原有直连流程。关闭前应先确认没有仍在支付、分账、退款或重试中的收付通订单，并完成资金和订单状态核对。

尊戎商城 · 商户与平台使用指南