客户收款接口：手动 channel_id 版

更新日期：2026-10-30。适用于已升级“手动channel_id统一下单版”的平台；本文档补丁不升级支付逻辑。

1. 下单流程与通道编号

客户携带签名请求本站 → 本站检查商户独立配置权限与金额 → 指定通道向上游下单 → 返回支付地址 → 用户付款 → 上游通知本站 → 本站验签处理 → 本站通知客户。

channel_id 必填，为平台后台手动设置的字符串。它不是内部自增ID，也不是上游通道编号。长度1至64位，以字母或数字开头，仅允许字母、数字、下划线和短横线；区分大小写，保留前导零。示例：客户传 00101，后台将其绑定到天下微信通道，上游编号为101。请向平台取得你被授权的实际编号，不能自行猜测。

type可省略，由通道确定；传入时必须匹配且参与签名。通道不存在、关闭、暂停或商户独立配置未授权时直接拒绝，不随机选用其他通道。未配置商户权限也拒绝。旧的仅type下单、自动收银台入口不再适用。

2. 请求接口与参数

页面支付：POST https://你的平台域名/submit.php；服务端API：POST https://你的平台域名/mapi.php。Content-Type为 application/x-www-form-urlencoded，UTF-8，不能直接提交JSON请求体。密钥只保存在客户服务端。

参数必填说明
pid是本站分配给客户的商户号，不是上游商户号
channel_id是手动对外编号，例如字符串00101；参与签名
type否如alipay、wxpay；省略由通道决定，传入必须匹配
out_trade_no是商户订单号；同一商户不可换通道、金额或其他支付参数复用原订单号
name是商品名称，原接口超过127字节截取
money是元，正数，最多2位小数；例如100.00
notify_url是客户服务器接收本站异步通知的URL
return_url页面接口必填用户支付后返回页面，mapi可省略
clientipmapi必填付款用户IP
device否mapi原设备参数；pc、mobile、qq、wechat、alipay、app或jump。jump只返回本站跳转URL，不代表已完成上游下单
param否业务扩展参数，非空参与签名
sign_type建议传MD5不参与签名
sign是32位小写MD5，不参与自身计算

3. 签名

  1. 除sign、sign_type、空字符串参数外，所有实际发送的参数按参数名ASCII升序排序，channel_id必须包括在内；数字0不能误当空值过滤。
  2. 用原始参数值拼接 key1=value1&key2=value2，这一步不做URL编码。
  3. 在末尾直接追加本站商户密钥，计算MD5小写：md5(拼接串 + 本站商户密钥)。不添加 &key=；不要套用上游签名算法。
  4. 加入sign后，再把完整参数编码成表单请求。不能在签名之后改变金额、编号或其他参数。不要把00101转换成101。

不含密钥的参数示例：

pid=1001
channel_id=00101
out_trade_no=TEST202610300001
money=100.00
name=test
notify_url=https://merchant.example/notify
return_url=https://merchant.example/return
clientip=127.0.0.1
sign_type=MD5
sign=由服务端计算

4. 金额限制

金额需要同时满足全站配置、本站通道范围及上游实际支持范围。全站最大1000、通道最大10000时，提交2000仍会被全站拦截，提示“最大支付金额是1000元”。管理员在“系统设置 → 支付相关配置”设置全站限额，在“支付接口 → 支付通道 → 编辑”设置通道范围；修改本地限额不会提高上游限额。加费或金额调整后实际支付金额也会校验通道范围。

5. 返回结果与错误处理

mapi返回JSON。成功 code=1 表示取得支付输出，不表示已付款。根据返回内容使用payurl跳转、qrcode生成二维码或urlscheme拉起客户端；部分插件返回html表单，须与平台确认支持方式。submit.php返回支付跳转/页面，不能当JSON解析。

{"code":1,"trade_no":"平台订单号","payurl":"https://支付地址示例"}

当前失败可能返回code=-1（校验或下单异常）、-2（插件错误结果）、-4（未传pid参数）；客户应统一把所有非1结果视为失败并记录msg，不依赖文字作为固定错误码。

典型提示处理
channel_id必填/格式错误按字符串发送授权编号
签名校验失败检查编号是否参与签名、前导零、参数编码和本站商户密钥
商户未授权此channel_id由管理员勾选授权，客户不能绕过
指定通道不存在、已关闭或不可用确认编号和通道状态
type与channel_id绑定的支付方式不一致省略type或传入正确值并重新签名
最大支付金额是…元/金额超过指定通道单笔最大限额分别核对全站/通道及上游限额
同一商户订单号不能更换channel_id核实原单状态；新业务使用新订单号
TX-*、上游业务错误、超时或下单未完成保留平台订单号及完整脱敏提示，先查原单；可能上游已建单，不能盲目重新创建订单或切换通道

6. 回调与查单

通知仍沿用现有本站协议，GET到notify_url，包含pid、trade_no、out_trade_no、type、name、money、trade_status=TRADE_SUCCESS、sign、sign_type及可选param。本次没有给回调新增channel_id字段。客户按自己的out_trade_no关联下单时保存的编号，不要因缺少channel_id拒绝合法通知。

客户必须验签，核对商户、订单、金额、成功状态，在本地事务中幂等处理，成功后返回纯文本 success。重复通知不能重复发货或入账。浏览器return_url和取得支付链接都不能代替服务端付款确认。查单、退款接口沿用站内下方文档，本次没有给它们新增channel_id参数，也不能把新下单签名规则强套到旧查询接口。

7. 联调清单

  1. 正确授权、签名及金额下单，核对绑定通道和返回链接。
  2. 缺少编号、签名后修改编号、未授权编号、type不匹配均拒绝。
  3. 分别验证全站和通道金额边界。
  4. 同一订单号换编号/金额拒绝，原单重试不能重复建单。
  5. 完成实际测试付款，验证上游→本站→客户通知，验签与重复通知幂等。

示例只生成请求，不会自动发起收款。请使用测试商户和已确认的通道。此前本地检查不能替代真实通道收款回调验收。