签名规则页面支付 API 下单异步通知商户查询沙箱联调

开发者文档

易支付协议接入指南 · 兼容 submit.php、mapi.php、api.php 三种接入方式。已有易支付对接代码，仅需替换网关地址与商户密钥即可完成迁移。

接入概览

陌城网络聚合支付对外提供标准易支付协议。您可以使用页面跳转、API 下单两种方式发起支付，支付完成后平台会向您的 notify_url 发送异步通知，并向 return_url 跳转同步结果。

网关地址

https://ep.mcyvps.top/

商户号 PID

10001

商户密钥 Key

你的商户密钥

接口编码

UTF-8 / MD5

登录商户中心后可查看您的真实商户号与密钥。

1 签名规则

除 sign、sign_type 以及空值参数外，将全部参数按参数名 ASCII 升序排序，拼接为 k1=v1&k2=v2 形式，末尾直接拼接商户密钥，再进行 MD5（32 位小写）。

<?php
function epaySign(array $params, string $key): string
{
    unset($params['sign'], $params['sign_type']);
    $params = array_filter($params, fn ($v) => $v !== '' && $v !== null);
    ksort($params);
    $pairs = [];
    foreach ($params as $k => $v) {
        $pairs[] = $k . '=' . $v;
    }
    return md5(implode('&', $pairs) . $key);
}

签名必须使用原始参数值，不要对参数值进行 URL 编码。金额请统一保留两位小数。

2 页面跳转支付（submit.php）

适用于浏览器表单提交或直接跳转。若 type 为空，平台将展示收银台供用户选择支付方式。

参数	类型	必填	说明
pid	string	是	商户号
type	string	否	支付方式：wxpay / alipay / qqpay / bank / usdt
out_trade_no	string	是	商户订单号，最长 64 位，商户内唯一
notify_url	string	是	异步通知地址，必须为 http(s) 完整地址
return_url	string	否	支付完成后的同步跳转地址
name	string	是	商品名称，最长 120 字
money	decimal	是	订单金额，最低 0.01
param	string	否	业务扩展参数，通知时原样返回
sign	string	是	MD5 签名
sign_type	string	是	固定为 MD5

示例：https://ep.mcyvps.top/submit.php?pid=10001&type=wxpay&out_trade_no=ORDER001&name=测试商品&money=1.00¬ify_url=...&sign=...&sign_type=MD5

3 API 下单（mapi.php / api.php?act=order）

通过 POST 请求创建订单并直接获取支付地址。推荐接口：https://ep.mcyvps.top/mapi.php，也可使用 https://ep.mcyvps.top/api.php?act=order。

参数	类型	必填	说明
pid	string	是	商户号
type	string	是	支付方式
out_trade_no	string	是	商户订单号
notify_url	string	是	异步通知地址
return_url	string	否	同步跳转地址
name	string	是	商品名称
money	decimal	是	订单金额
clientip	string	否	用户客户端 IP
device	string	否	pc / mobile，默认 pc
param	string	否	业务扩展参数
sign	string	是	MD5 签名
sign_type	string	是	固定为 MD5

成功响应：

{
    "code": 1,
    "trade_no": "20241017120000123456",
    "payurl": "https://...",
    "qrcode": "https://...",
    "urlscheme": ""
}

失败响应：{"code":0,"msg":"签名验证失败"}

<?php
$params = [
    'pid'          => '10001',
    'type'         => 'wxpay',
    'out_trade_no' => 'ORDER' . date('YmdHis'),
    'notify_url'   => 'https://your.site/pay/notify.php',
    'return_url'   => 'https://your.site/pay/return.php',
    'name'         => '年度会员服务',
    'money'        => '128.00',
    'clientip'     => $_SERVER['REMOTE_ADDR'],
    'device'       => 'pc',
];
$params['sign'] = epaySign($params, '你的商户密钥');
$params['sign_type'] = 'MD5';

$ch = curl_init('https://pay.example.com/mapi.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($params),
    CURLOPT_TIMEOUT        => 15,
]);
$result = json_decode(curl_exec($ch), true);
if (($result['code'] ?? 0) === 1) {
    // $result['payurl'] 跳转支付，$result['qrcode'] 可用于展示二维码
    header('Location: ' . $result['payurl']);
}

4 异步通知

订单支付成功后，平台会以 GET 方式请求您的 notify_url。您必须验证签名并核对金额，处理完成后输出纯文本 success（不区分大小写）。若未返回 success，平台将按设置自动重试。

参数	说明
pid	商户号
trade_no	平台订单号
out_trade_no	您的商户订单号
type	支付方式
name	商品名称
money	订单金额（两位小数）
trade_status	固定为 TRADE_SUCCESS
param	下单时传入的扩展参数
sign	MD5 签名
sign_type	固定为 MD5

<?php
// 接收平台异步通知
$params = $_GET;
$key = '你的商户密钥';

if (!hash_equals(epaySign($params, $key), strtolower($params['sign'] ?? ''))) {
    exit('fail');
}

$orderNo = $params['out_trade_no'];
$money   = $params['money'];

// TODO: 校验订单金额、处理业务逻辑，必须保证幂等
// if (订单已处理) { echo 'success'; exit; }

if ($params['trade_status'] === 'TRADE_SUCCESS') {
    // 标记订单已支付
    echo 'success';
} else {
    echo 'fail';
}

5 同步跳转（return.php）

支付完成后用户浏览器会跳转至平台 return.php，平台校验订单后，再携带与异步通知相同的签名参数跳转至您的 return_url。同步跳转仅用于展示结果，订单状态请以异步通知或主动查单为准。

6 商户信息查询

请求：GET https://ep.mcyvps.top/api.php?act=query&pid=10001&key=你的商户密钥

{
    "code": 1,
    "pid": "10001",
    "active": 1,
    "money": "1000.00",
    "name": "商户名称",
    "email": "merchant@example.com"
}

可用于检查密钥是否正确以及查询账户余额。

7 沙箱与联调

平台安装后内置一个沙箱通道（通道地址填写 sandbox），无需真实上游账号即可体验下单、支付、回调、入账的完整流程。管理员可在后台关闭沙箱通道；正式上线前请配置真实上游易支付通道。

在管理后台「上游通道」中新增真实易支付上游，填写接口地址、上游商户号与密钥
支付方式需与上游支持的通道匹配，平台会按权重自动路由
回调地址无需手工配置，平台会自动向上游传递 https://ep.mcyvps.top/notify.php
建议配置计划任务定时访问 cron.php 完成补单与通知重试

8 常见问题

签名失败: 检查参数是否按 ASCII 排序、是否排除了 sign / sign_type 与空值、密钥是否与商户中心一致。
回调未收到: 确认 notify_url 为公网可访问的 http(s) 地址，且未做登录鉴权拦截；可在商户中心订单详情查看通知记录。
订单号重复: 同一商户下 out_trade_no 必须唯一。重复提交相同订单号时平台会返回原订单。
支付方式不可用: 管理员需在后台配置支持该支付方式的上游通道并启用。
金额不一致: 平台会校验上游回调金额与订单金额，异常回调将被拒绝并记录日志。