📖 概述

MiniPay 是一套基于微信小程序的支付解决方案,通过 URL Link + 半屏小程序技术,实现微信外浏览器直接拉起微信支付,无需申请 H5 支付权限。

💡 核心优势 无需H5支付审核 · 商家自有商户号资金直达 · 标准RESTful API · 3步完成对接

🌐 网关信息

API网关https://minipay.1.taolianwl.cn
签名方式MD5
通信格式JSON(Content-Type: application/json)
字符编码UTF-8

1️⃣ 统一下单

创建支付订单,生成支付链接。用户点击链接后拉起微信小程序完成支付。

请求

POST /api/pay/unified-order
Content-Type: application/json

请求参数

字段类型必填说明
app_idstring必填平台分配的应用ID
timestampstring必填当前Unix时间戳(秒)
signstring必填签名,见第3节
mch_idstring选填微信支付商户号,不传则自动轮询已开启的商户号
amountnumber必填支付金额(元),最小0.01
out_order_nostring必填商户订单号,需保证唯一
user_ipstring必填付款用户真实IP
notify_urlstring必填异步通知地址(支付成功后回调)
sync_notify_urlstring必填同步回调地址(支付完成后跳转)
descriptionstring选填商品描述,默认"支付"

请求示例

{
  "app_id": "Mmp6k026k3956",
  "timestamp": "1715827200",
  "sign": "a1b2c3d4e5f6...",
  "mch_id": "16888888",            // 可选,不传则自动轮询
  "amount": 0.01,
  "out_order_no": "ORDER20260516001",
  "user_ip": "192.168.1.1",
  "notify_url": "https://yoursite.com/pay/notify",
  "sync_notify_url": "https://yoursite.com/pay/sync",
  "description": "商品描述"
}

成功响应

{
  "code": 0,
  "data": {
    "out_order_no": "ORDER20260516001",    // 商户订单号
    "order_no": "WPMP7D18YL19B5F6",    // 平台订单号
    "transaction_id": "",                 // 微信订单号(支付成功后填充)
    "url_link": "https://wxaurl.cn/xxx",  // 支付链接(发给用户点击)
    "amount": 0.01,
    "fee": 0.01
  }
}
⚠️ 三单号说明 每笔交易产生三个订单号:
out_order_no — 商户订单号,你传入的,用于关联你的业务系统
order_no — 平台订单号,MiniPay生成,用于查询和对账
transaction_id — 微信订单号,42000开头,支付成功后才有

2️⃣ 订单查询

通过平台订单号查询订单状态和详细信息。

GET /api/pay/query/{order_no}?app_id=你的AppID&sign=签名&timestamp=时间戳

3️⃣ 签名算法

所有API请求必须携带签名,确保请求来源可信。

签名公式

sign = MD5( app_id + app_secret + timestamp )

代码示例

const crypto = require('crypto');

const sign = crypto.createHash('md5')
  .update(app_id + app_secret + timestamp)
  .digest('hex');
🔑 密钥获取 app_idapp_secret 在商家后台「密钥管理」页面获取。

4️⃣ 异步通知(支付回调)

用户支付成功后,MiniPay 会向你的 notify_url 发送 POST 请求,通知内容为 JSON 格式:

通知内容

{
  "out_order_no": "ORDER20260516001",
  "order_no": "WPMP7D18YL19B5F6",
  "transaction_id": "420000xxxx",
  "amount": 0.01,
  "fee": 0.01,
  "description": "商品描述",
  "status": "paid",
  "paid_at": "2026-05-16T04:00:00.000Z",
  "user_ip": "192.168.1.1",
  "app_id": "你的AppID",
  "timestamp": "1715827200",
  "nonce_str": "abc123",
  "sign": "md5签名"
}
⚠️ 必须返回 SUCCESS 你的接口收到通知后,必须返回字符串 SUCCESS 或 JSON {"code":0}
否则系统将自动重试通知:15s → 30s → 60s → 120s → 300s,最多5次。

你的服务器正确响应

// 方式1:直接返回纯文本
SUCCESS

// 方式2:返回JSON
{"code": 0, "msg": "ok"}

通知签名验证

// 1. 取所有非sign字段,按key升序排列
// 2. 拼接为 key1=value1&key2=value2...
// 3. 末尾追加 &key=你的app_secret
// 4. 对整个字符串取MD5

const keys = Object.keys(data).filter(k => k !== 'sign').sort();
const str = keys.map(k => k + '=' + data[k]).join('&') + '&key=' + app_secret;
const expected = crypto.createHash('md5').update(str).digest('hex');
// expected === data.sign 则验签通过

5️⃣ 同步回调

用户支付完成后,MiniPay 会将用户重定向到你传入的 sync_notify_url

GET https://yoursite.com/pay/sync?order_no=WPxxx&out_order_no=ORDER001&status=paid
⚠️ 注意 同步回调仅用于页面跳转展示,不保证支付结果准确性。最终状态请以异步通知或主动查询为准。

6️⃣ 支付流程

  1. 你的系统调用 统一下单 API,传入订单信息和回调地址
  2. API返回 url_link(支付链接)
  3. 你的系统将链接展示给用户(二维码/超链接均可)
  4. 用户点击链接 → 拉起微信小程序 → 调起微信收银台 → 完成支付
  5. MiniPay 收到微信回调 → 更新订单状态 → POST通知你的 notify_url
  6. 你的接口返回 SUCCESS → 通知完成 ✅

7️⃣ SDK Demo

以下为各语言统一下单调用示例,app_id / app_secret 请在商家后台「密钥管理」页面获取。

<?php
// MiniPay 统一下单 - PHP Demo
$appId     = '你的AppID';
$appSecret = '你的AppSecret';
$timestamp = time();
$sign      = md5($appId . $appSecret . $timestamp);

$data = [
    'app_id'         => $appId,
    'timestamp'      => $timestamp,
    'sign'           => $sign,
    // 'mch_id'      => '16888888',  // 可选,不传则自动轮询
    'amount'         => 0.01,
    'out_order_no'   => 'ORDER' . date('YmdHis') . rand(1000,9999),
    'user_ip'        => $_SERVER['REMOTE_ADDR'] ?? '127.0.0.1',
    'notify_url'     => 'https://yoursite.com/pay/notify',
    'sync_notify_url'=> 'https://yoursite.com/pay/sync',
    'description'    => '商品描述',
];

$ch = curl_init('https://minipay.1.taolianwl.cn/api/pay/unified-order');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS    => json_encode($data),
    CURLOPT_HTTPHEADER    => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$result = curl_exec($ch);
curl_close($ch);

$resp = json_decode($result, true);
if ($resp['code'] === 0) {
    header('Location: ' . $resp['data']['url_link']);
} else {
    echo '下单失败: ' . $resp['msg'];
}

// === 异步通知验签 ===
$notify = json_decode(file_get_contents('php://input'), true);
$keys = array_filter(array_keys($notify), fn($k) => $k !== 'sign');
sort($keys);
$signStr = implode('&', array_map(fn($k) => $k.'='.$notify[$k], $keys)) . '&key=' . $appSecret;
if (md5($signStr) === $notify['sign'] && $notify['status'] === 'paid') {
    // 验签通过,处理订单
    echo json_encode(['code' => 0, 'msg' => 'ok']);
}

8️⃣ 错误码

错误码含义处理建议
1001缺少鉴权参数检查 app_id / sign / timestamp
1002无效的 app_id确认 app_id 是否正确
1003签名错误检查签名算法和 app_secret
2001参数错误检查必填参数是否完整
2002商户号不存在/无可用商户号确认 mch_id 是否正确且已激活,或在商户号管理中开启至少一个
2004未配置支付密钥在商户号管理中配置 API 密钥和证书
2005手续费余额不足联系管理员充值
2007支付链接生成失败检查小程序配置,稍后重试

三单号说明

字段名称来源格式示例
out_order_no商户订单号商家下单时传入ORDER20260516001
order_no平台订单号MiniPay自动生成WPMP7D18YL19B5F6
transaction_id微信订单号微信支付回调返回420000xxxx

三单号在异步通知中同时返回,商家通过 out_order_no 关联自己的业务系统。

常见问题

Q: 需要申请微信H5支付权限吗?

不需要。MiniPay 通过小程序能力实现支付,无需H5支付审核。

Q: 资金流向是怎样的?

资金直接到商家自有微信商户号,MiniPay平台不经手资金,仅收取技术服务费。

Q: 支持哪些支付方式?

目前支持微信支付(JSAPI小程序支付 + Native扫码支付),通过URL Link从微信外浏览器拉起。

Q: 异步通知失败怎么办?

系统自动重试5次(15s/30s/60s/120s/300s)。确保你的接口返回 SUCCESS,且服务可公网访问。

Q: 如何保证回调安全?

所有回调包含签名(sign字段),请按照签名验证流程验签后再处理业务逻辑。