MMCCCPAY 商户支付接入文档

1. 文档说明

本文档描述商户如何通过 MMCCCPAY 开放接口完成收款接入。

• V1 协议：MD5 签名，兼容 submit.php、mapi.php、api.php 等传统入口。
• V2 协议：RSA 签名，推荐使用 /api/pay/* 标准 REST 风格接口，支持退款、关单、转账等扩展能力。

2. 快速开始（5 步接入）

1. 登录 商户后台，在「接口凭证」获取 商户 ID（pid） 与密钥。
2. 选择协议：新系统用 V2 + RSA；已有易支付 V1 代码可直接对接。
3. 实现签名：按本文档第 6 节规则生成 sign。
4. 调用下单接口：页面跳转用 submit，服务端 API 用 create（V2）或 mapi（V1）。
5. 实现 notify_url 异步通知：验签 → 校验金额与订单号 → 幂等更新订单 → 返回 success。

2.1 标准支付时序

3. 商户开通与凭证

3.1 需要准备的资料

3.2 回调地址要求

• notify_url 必须公网可访问，建议 HTTPS。
• 异步通知由平台服务器以 GET 方式发起，参数放在 URL Query 中（V1/V2 相同）。
• 收到通知后必须返回纯文本 success（小写），否则平台会按策略重试。
• return_url 仅用于浏览器同步跳转展示，不能作为到账依据，到账以 notify_url 为准。

4. V1 与 V2 如何选择

5. 接口地址总览

以下地址均以网关 https://pay.mmcccpay.com 为前缀。

5.1 V2 接口

5.2 V1 接口

6. 签名规则（必读）

6.1 公共规则

1. 取所有非空参数参与签名。
2. sign、sign_type 不参与签名。
3. 数组、对象、文件等非标量字段不参与签名。
4. 参数名按 ASCII 码升序排序。
5. 拼接格式：key1=value1&key2=value2（值不做 URL 编码）。

6.2 V1 MD5 签名

待签原文 = key1=value1&key2=value2 ...（按规则排序拼接）
sign = md5(待签原文 + API_KEY)   // 结果小写，+ 表示字符串直接拼接

示例参数：

{
  "pid": 1001,
  "type": "alipay",
  "out_trade_no": "ORDER20260530001",
  "notify_url": "https://merchant.example.com/notify",
  "return_url": "https://merchant.example.com/return",
  "name": "VIP会员",
  "money": "10.00"
}

排序后原文类似：

money=10.00&name=VIP会员&notify_url=https://merchant.example.com/notify&out_trade_no=ORDER20260530001&pid=1001&return_url=https://merchant.example.com/return&type=alipay

末尾直接拼接 API Key 后 MD5。

6.3 V2 RSA 签名

待签原文 = 同 6.1 规则拼接
sign = Base64( RSA-SHA256(待签原文, 商户私钥) )

请求需带 sign_type=RSA 与 timestamp（Unix 秒级时间戳，参与签名）。

验证平台响应或异步通知时，使用平台 RSA 公钥验签。

6.4 PHP 签名示例

<?php
function epay_build_sign_content(array $params): string {
    unset($params['sign'], $params['sign_type']);
    ksort($params);
    $parts = [];
    foreach ($params as $k => $v) {
        if ($v === '' || $v === null || is_array($v)) continue;
        $parts[] = $k . '=' . $v;
    }
    return implode('&', $parts);
}

function epay_sign_md5(array $params, string $apiKey): string {
    return md5(epay_build_sign_content($params) . $apiKey);
}

function epay_sign_rsa(array $params, string $privateKeyPem): string {
    $content = epay_build_sign_content($params);
    openssl_sign($content, $signature, $privateKeyPem, OPENSSL_ALGO_SHA256);
    return base64_encode($signature);
}

7. 支付方式与设备类型

7.1 支付方式 type

7.2 设备类型 device（V1 mapi / V2 create 可选）

8. 指定通道 channel_id（可选）

V1 的 submit、mapi 与 V2 的 submit、create 均支持可选参数 channel_id：

• 不传：平台按商户分组 → 轮询组 → 通道权重自动选路。
• 传入：强制使用指定通道 ID，且该通道必须在当前商户可用路由内。
• 参与签名：传入时与其他参数一样参与 MD5/RSA 签名。

9. V2 API 创建订单（推荐）

9.1 请求

• URL：POST https://pay.mmcccpay.com/api/pay/create
• Content-Type：application/x-www-form-urlencoded 或 application/json

9.2 成功响应

{
  "code": 0,
  "msg": "success",
  "trade_no": "PAY20260530164209956889",
  "pay_type": "jump",
  "pay_info": "https://pay.mmcccpay.com/payment/PAY20260530164209956889",
  "timestamp": "1779179000",
  "sign": "...",
  "sign_type": "RSA"
}

9.3 pay_type 含义

9.4 cURL 示例

curl -X POST "https://pay.mmcccpay.com/api/pay/create" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "pid=1001" \
  -d "method=jump" \
  -d "type=alipay" \
  -d "out_trade_no=ORDER20260530001" \
  -d "name=测试商品" \
  -d "money=10.00" \
  -d "notify_url=https://merchant.example.com/notify" \
  -d "return_url=https://merchant.example.com/return" \
  -d "clientip=127.0.0.1" \
  -d "timestamp=1779179000" \
  -d "sign_type=RSA" \
  -d "sign=YOUR_RSA_SIGN"

10. V2 页面跳转支付

适用于 PC/移动端表单提交，用户浏览器直接跳转到平台收银台或支付页。

• URL：POST https://pay.mmcccpay.com/api/pay/submit（兼容 GET）
• 参数与 create 类似，method 可不传；type 可不传（进入收银台选支付方式）

<form action="https://pay.mmcccpay.com/api/pay/submit" method="post">
  <input type="hidden" name="pid" value="1001">
  <input type="hidden" name="type" value="alipay">
  <input type="hidden" name="out_trade_no" value="ORDER20260530001">
  <input type="hidden" name="name" value="测试商品">
  <input type="hidden" name="money" value="10.00">
  <input type="hidden" name="notify_url" value="https://merchant.example.com/notify">
  <input type="hidden" name="return_url" value="https://merchant.example.com/return">
  <input type="hidden" name="timestamp" value="1779179000">
  <input type="hidden" name="sign_type" value="RSA">
  <input type="hidden" name="sign" value="YOUR_RSA_SIGN">
  <button type="submit">去支付</button>
</form>

11. V2 订单查询

• URL：POST https://pay.mmcccpay.com/api/pay/query
• trade_no（平台单号）与 out_trade_no（商户单号）二选一

12. 异步通知与同步跳转

12.1 异步通知 notify_url

用户支付成功后，平台会向商户 notify_url 发起通知。商户必须：

1. 验证签名（V1 用 API Key；V2 用平台公钥）。
2. 校验 pid 为本商户。
3. 校验 out_trade_no 存在且金额 money 一致。
4. 校验 trade_status == TRADE_SUCCESS（V2 同样使用该值表示成功）。
5. 幂等更新本地订单（重复通知不重复发货）。
6. 响应纯文本 success。

12.2 通知参数（V1 / V2 通用）

通知以 GET 请求送达，参数在 URL 中。V2 通知额外包含 timestamp、addtime、endtime，验签时使用平台 RSA 公钥。

12.3 PHP 通知处理示例

<?php
// 平台异步通知统一为 GET Query 参数（V1 / V2 相同）
$params = $_GET;

$apiKey = 'YOUR_V1_API_KEY';
$content = epay_build_sign_content($params);
$signOk = hash_equals(md5($content . $apiKey), strtolower($params['sign'] ?? ''));

if (!$signOk || ($params['trade_status'] ?? '') !== 'TRADE_SUCCESS') {
    http_response_code(400);
    exit('fail');
}

$outTradeNo = $params['out_trade_no'];
$money = $params['money'];
// TODO: 查库、校验金额、幂等更新为已支付

echo 'success';

12.4 同步跳转 return_url

用户支付完成后浏览器跳转至 return_url，参数与通知类似，仅用于展示。务必以异步通知或查单结果为准。

13. 身份授权（JSAPI / 小程序）

当路由到的支付产品需要用户 OpenID / buyer_id，而下单时未传入，平台返回身份承接地址：

{
  "code": 0,
  "msg": "identity_required",
  "pay_type": "identity",
  "pay_info": "https://pay.mmcccpay.com/cashier/identity/xxx",
  "identity_required": 1,
  "identity_url": "https://pay.mmcccpay.com/cashier/identity/xxx",
  "resume_token": "xxx"
}

处理流程：

1. 收到 identity_required=1 或 pay_type=identity。
2. 引导用户跳转 identity_url 完成授权。
3. 授权完成后平台继续支付流程，或携带 openid 等参数重新下单。

可选身份字段（V2 create）：openid、mini_openid、buyer_id、auth_code 等。

14. V1 API 支付 mapi

• URL：POST https://pay.mmcccpay.com/mapi.php（兼容 /mapi）
• 请求体：application/x-www-form-urlencoded（Form Data），参数以表单字段提交，不使用 JSON Body
• 签名：MD5，sign_type=MD5
• clientip 必填

14.0 cURL 示例

curl -X POST "https://pay.mmcccpay.com/mapi.php" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "pid=1001" \
  -d "type=wxpay" \
  -d "out_trade_no=ORDER20260530001" \
  -d "name=测试商品" \
  -d "money=10.00" \
  -d "notify_url=https://merchant.example.com/notify" \
  -d "return_url=https://merchant.example.com/return" \
  -d "clientip=127.0.0.1" \
  -d "device=pc" \
  -d "sign_type=MD5" \
  -d "sign=YOUR_MD5_SIGN"

sign 需按 MD5 规则计算；也可使用 V1 mapi 测试工具 在线调试。

14.1 返回字段（三选一）

{
  "code": 1,
  "msg": "success",
  "trade_no": "PAY20260530164209956889",
  "payurl": "https://pay.mmcccpay.com/payment/PAY20260530164209956889"
}

在线测试工具：submit.php 页面跳转测试 · mapi 接口测试

15. V1 页面跳转 submit

• URL：https://pay.mmcccpay.com/submit
• 支持 GET / POST
• type 可不传，进入收银台选择支付方式

16. V1 查询类 API（api.php）

16.1 查询订单 act=order

GET https://pay.mmcccpay.com/api?act=order&pid=1001&key=YOUR_API_KEY&out_trade_no=ORDER20260530001

status：1 已支付，0 未支付。

16.2 查询商户 act=query

GET https://pay.mmcccpay.com/api?act=query&pid=1001&key=YOUR_API_KEY

17. 退款（V2）

• URL：POST https://pay.mmcccpay.com/api/pay/refund
• trade_no 或 out_trade_no 二选一
• money 退款金额；out_refund_no 商户退款单号（建议传）

退款查询：/api/pay/refundquery

18. 订单号说明

19. 常见错误与排查

20. 安全规范

• API Key、RSA 私钥仅保存在商户服务器，禁止写入前端 JS 或移动端包体。
• 生产环境 notify_url 使用 HTTPS。
• 回调必须验签 + 校验金额 + 校验商户订单号。
• 勿以后台「同步跳转」作为到账依据。
• 商户订单号 out_trade_no 必须全局唯一，禁止重复使用。
• V2 请求校验 timestamp，防止重放（建议 ±300 秒窗口内有效）。

21. 上线检查清单

22. 常见问题 FAQ

22.1 金额单位是什么？

接口参数 money 单位均为元，字符串格式，最多两位小数，如 10.00。

22.2 out_trade_no 可以重复吗？

不可以。同一商户下 out_trade_no 必须唯一，重复提交会视为同一笔业务订单。

22.3 V1 和 V2 能否混用？

可以。同一商户可同时开通 V1 MD5 与 V2 RSA，按系统模块选择即可；通知验签方式与各自协议一致。

22.4 如何测试？

• V1：使用 在线测试页 或 SDK。
• V2：使用 V2 SDK 中的示例。
• 小额真实支付：建议 0.01 ~ 1.00 元验证完整链路。

22.5 支付页 URL 是什么？

API 返回的 payurl / pay_info 通常指向平台收银台，格式如：

https://pay.mmcccpay.com/payment/{平台支付单号}

23. 技术支持

• 商户后台：/mer
• API 速查文档：/docs
• V1 接口标准：/docs#v1
• V2 接口标准：/docs#v2