开发者文档

01 概览

落雨支付是一个自托管的聚合支付网关。商户可使用平台分配的 pid 与 api_key，按易支付协议向本平台发起下单请求。平台根据后台配置的通道（微信商户直连 / 易支付上游 / 测试通道）完成收款，并把支付结果异步通知给商户服务端。

如果你原本已经对接易支付，只需要把接口域名替换为 https://xiaochengyizhifu.xiaochennb.cn，签名规则完全一致。

商户号 PID10001

商户密钥你的商户密钥

签名方式MD5

支付方式wxpay / alipay / qqpay

02 接口地址

用途	地址	方法
页面跳转支付	`https://xiaochengyizhifu.xiaochennb.cn/submit.php`	GET / POST
API 接口支付	`https://xiaochengyizhifu.xiaochennb.cn/mapi.php`	GET / POST
异步通知	由你传入的 `notify_url` 决定	POST
同步跳转	由你传入的 `return_url` 决定	GET

建议服务端使用 POST 请求 mapi.php，避免参数出现在访问日志中。

03 签名规则

除 sign、sign_type 外，把所有非空参数按参数名 ASCII 升序排列。
拼接成 a=b&c=d 形式（不要对值做 URL 编码）。
末尾直接拼接商户密钥（不需要 &key=）。
对整串做 MD5，转小写，即为 sign。

签名示例

// 待签名参数
money=1.00
name=test
notify_url=https://your.site/notify
out_trade_no=20261113001
pid=10001
type=wxpay

// 排序拼接后追加密钥 demo_key_1234567890abcdef
money=1.00&name=test&notify_url=https://your.site/notify&out_trade_no=20261113001&pid=10001&type=wxpaydemo_key_1234567890abcdef

// MD5 结果
db6e29e4c1e62acbf40a27f058a3ef7e

04 创建订单

参数	必填	说明
`pid`	是	商户号，在商户后台「API 接入」查看
`type`	是	支付方式：`wxpay` / `alipay` / `qqpay`
`out_trade_no`	是	商户订单号，64 位以内，需保证唯一
`name`	是	商品名称
`money`	是	金额，单位元，最多两位小数，最低 0.01
`notify_url`	否	异步通知地址，必须可公网访问
`return_url`	否	支付完成后同步跳转地址
`sign`	是	按上文规则计算的 MD5 签名
`sign_type`	否	固定 `MD5`
`openid`	否	微信 JSAPI 支付时必传
`clientip`	否	用户真实 IP，H5 支付建议传入

05 返回参数

mapi.php 返回 JSON：

200 OK · application/json

{
  "code": 1,
  "msg": "success",
  "trade_no": "202611131530001234",
  "out_trade_no": "20261113001",
  "payurl": "https://pay.example.com/pay/202611131530001234",
  "qrcode": "weixin://wxpay/bizpayurl?pr=xxxx",
  "urlscheme": "",
  "money": "1.00"
}

字段	说明
`code`	1 表示成功，-1 表示失败（失败时 msg 为原因）
`trade_no`	平台订单号
`payurl`	收银台地址或微信 H5 支付链接
`qrcode`	微信 Native 二维码内容，可自行渲染
`payinfo`	JSAPI 支付参数（appId / timeStamp / nonceStr / package / signType / paySign）。返回该字段时 `payurl` 与 `qrcode` 为空，直接用小程序的 `wx.requestPayment` 拉起支付。

06 小程序直连支付

小程序里点「支付」直接弹出微信支付面板，不需要扫码。平台使用微信支付 JSAPI 下单，把签名参数原样返回给小程序，前端调用 wx.requestPayment 即可。

后台「通道管理」把微信通道的支付场景设为 JSAPI，AppID 填小程序 AppID，并确保该 AppID 与商户号已完成绑定、已开通 JSAPI 支付。
小程序端 wx.login() 拿 code，由你的服务端调用微信 jscode2session 换取 openid。
服务端把 openid 一起放进下单参数，调用 mapi.php，type=wxpay。
接口返回 payinfo（appId / timeStamp / nonceStr / package / signType / paySign），小程序直接 wx.requestPayment(payinfo)。
支付结果仍以 notify_url 异步通知为准，前端 requestPayment 成功回调只用于跳转结果页。

服务端下单（PHP）

$params = [
    'pid'          => '你的商户号',
    'type'         => 'wxpay',
    'out_trade_no' => '订单号',
    'name'         => '商品名称',
    'money'        => '9.90',
    'openid'       => $openid, // 小程序用户 openid
    'notify_url'   => 'https://你的域名/notify.php',
];
// 按签名规则生成 sign 后 POST 到 mapi.php
$result = json_decode(http_post('https://xiaochengyizhifu.xiaochennb.cn/mapi.php', $params), true);
return $result['payinfo']; // 交给小程序

小程序端拉起支付

wx.request({
  url: 'https://你的域名/api/create-order',
  method: 'POST',
  data: { goodsId: 1 },
  success(res) {
    wx.requestPayment({
      timeStamp: res.data.payinfo.timeStamp,
      nonceStr:  res.data.payinfo.nonceStr,
      package:   res.data.payinfo.package,
      signType:  res.data.payinfo.signType,
      paySign:   res.data.payinfo.paySign,
      success() { wx.navigateTo({ url: '/pages/result?trade_no=' + res.data.trade_no }); },
      fail()    { wx.showToast({ title: '支付已取消', icon: 'none' }); }
    });
  }
});

payinfo 由平台实时调用微信生成，约 2 小时内有效，请拿到后立即调用 wx.requestPayment，不要缓存复用。同一订单重复请求会复用未支付的订单与参数。

07 异步通知

支付成功后，平台会向 notify_url 发送 POST 表单，参数如下（均已签名）：

参数	说明
`pid`	商户号
`trade_no`	平台订单号
`out_trade_no`	你的商户订单号
`type`	支付方式
`name`	商品名称
`money`	订单金额
`trade_status`	固定为 `TRADE_SUCCESS`
`api_trade_no`	微信/上游渠道订单号
`sign`	MD5 签名

收到通知并验签通过、金额一致后，请返回纯文本 success（不区分大小写）。否则平台会按设置自动重试。

notify.php · 验签示例

<?php
$key = '你的商户密钥';
$params = $_POST;
$sign = $params['sign'];
unset($params['sign'], $params['sign_type']);
$params = array_filter($params, fn($v) => $v !== '');
ksort($params, SORT_STRING);
$local = md5(implode('&', array_map(
    fn($k, $v) => "$k=$v", array_keys($params), $params
)) . $key);

if (hash_equals($local, $sign) && $params['trade_status'] === 'TRADE_SUCCESS') {
    // TODO: 校验订单号与金额、更新业务订单
    echo 'success';
}

08 同步跳转

用户支付完成后，浏览器会跳转到 return_url，并附带与异步通知一致的签名参数。同步跳转仅用于展示结果，不能作为发货依据，请以异步通知为准。

09 微信商户配置

管理员进入 后台 → 通道管理 → 新增通道，选择「微信商户直连」，按下表填写：

字段	来源
AppID	微信支付商户平台 / 小程序 AppID
商户号 mchid	微信支付商户号（10 位数字）
证书序列号	商户 API 证书的序列号
APIv3 密钥	商户平台设置的 32 位 APIv3 密钥
商户私钥	`apiclient_key.pem` 完整内容
平台证书	可选，留空时平台会自动下载并缓存
支付方式	Native（扫码）/ H5（手机浏览器）/ JSAPI（微信内）

保存后点击「测试连接」，平台会调用微信证书接口验证密钥并缓存平台证书。测试通过即可收款。

10 测试通道

系统内置测试通道，无需任何微信配置即可跑通完整链路：下单后打开收银台，点击「模拟支付成功」，订单会立即变为已支付并触发异步通知。正式上线前把默认通道切换为微信或上游通道即可。

11 代码示例

PHP · 发起支付

<?php
$params = [
    'pid' => '10001',
    'type' => 'wxpay',
    'out_trade_no' => 'ORDER_' . time(),
    'name' => '电竞陪练订单',
    'money' => '9.90',
    'notify_url' => 'https://your.site/pay/notify.php',
    'return_url' => 'https://your.site/pay/return.php',
];
ksort($params, SORT_STRING);
$stringA = implode('&', array_map(
    fn($k, $v) => "$k=$v", array_keys($params), $params
));
$params['sign'] = md5($stringA . '你的商户密钥');
$params['sign_type'] = 'MD5';

$ch = curl_init('https://xiaochengyizhifu.xiaochennb.cn/mapi.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($params),
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
// 跳转到 $result['payurl'] 或渲染 $result['qrcode']

12 常见问题

签名一直校验失败？

检查是否排除了空值参数、是否按 ASCII 升序排序、是否在末尾直接拼接密钥（不要加 &key=），以及 MD5 是否转为小写。

收不到异步通知？

notify_url 必须公网可访问且返回 success。可在商户后台订单详情里查看通知日志，或点击「重发通知」手动补发。

微信 H5 支付提示域名未配置？

需要在微信商户平台配置 H5 支付域名，并在项目中把站点地址填写为正式 https 域名。

测试通道能直接上线吗？

不能。测试通道仅用于联调，不会产生真实扣款。正式收款请配置微信商户直连或易支付上游通道。

落雨支付 · 接入文档