支付接口对接文档

V1.0 · 适用于本平台商户接口对接

一、接入准备

接口网关 http://112.213.106.82:8201/api

商户号 mchId 开通后分配（数字）

商户私钥 mchKey 开通后分配（用于签名，请勿泄露，如需重置联系运营）

渠道编码 channelCode 开通后分配（如 2003），下单时用它指定通道

单笔限额 当前通道 10.00 ~ 90.00 元（按分传参即 1000 ~ 9000）

数据格式 请求 application/x-www-form-urlencoded；响应 JSON

二、签名规则（MD5）

1. 取所有非空请求参数（不含 sign 本身）；
2. 按参数名做字母升序排序；
3. 拼接成 k1=v1&k2=v2&... 形式；
4. 末尾直接拼接 key=商户私钥；
5. 整串做 MD5，转大写，作为 sign 参数发送。

// PHP 示例
function paramArraySign($paramArray, $mchKey) {
    ksort($paramArray);                       // 参数名升序
    $md5str = "";
    foreach ($paramArray as $key => $val) {
        if (strlen($key) && strlen($val)) {    // 空值不参与
            $md5str .= $key . "=" . $val . "&";
        }
    }
    return strtoupper(md5($md5str . "key=" . $mchKey));  // MD5 大写
}

// Java 示例
String raw = params.entrySet().stream()
    .filter(e -> e.getValue() != null && !"".equals(e.getValue()))
    .map(e -> e.getKey() + "=" + e.getValue())
    .sorted(String.CASE_INSENSITIVE_ORDER)
    .collect(Collectors.joining("&")) + "key=" + mchKey;
String sign = DigestUtils.md5Hex(raw).toUpperCase();

三、统一下单

POST/api/pay/create_order

参数	必填	说明
mchId	是	商户号
mchOrderNo	是	商户订单号，≤30 位，商户内唯一（重复单号会被拒绝）
amount	是	支付金额，单位：分（1000 = 10.00 元）
currency	是	币种，固定 `cny`
clientIp	是	付款用户公网 IP（勿传内网 IP）
notifyUrl	是	支付结果异步通知地址（见第五节）
subject	是	商品标题
body	是	商品描述
channelCode	二选一	渠道编码（开通时分配，如 2003）
productId	二选一	支付产品 ID（开通时分配）
returnUrl	否	支付完成后前端跳转地址
device	否	设备类型，如 web / ios / android
param1 / param2	否	扩展参数，回调时原样返回（可用于关联自身订单）
sign	是	签名（第二节）

成功响应

{
  "retCode": "0",
  "retMsg": "",
  "payOrderId": "P01202610090947271500000",
  "payMethod": "codeImg",
  "codeUrl": "https://qr.alipay.com/bax03880ye3mz4d7nwwn25d6",
  "codeImgUrl": "http://112.213.106.82:8201/api/qrcode_img_get?url=...&width=200&height=200",
  "sign": "A1B2C3..."
}

二维码怎么用：把 codeImgUrl 作为图片地址直接展示（用户扫码支付）；codeUrl 是收款码内容原文（自行渲染二维码时使用）。

失败响应

{
  "retCode": "9999",
  "retMsg": "aipay 金额超出限额[10-90元]: 100.00",
  "sign": "..."
}

注意：retCode 非 "0" 即下单失败（如金额超限、通道异常），此时未生成有效收款码，请更换新的 mchOrderNo 重试。

四、查询订单

POST/api/pay/query_order

参数	必填	说明
mchId	是	商户号
mchOrderNo	二选一	商户订单号
payOrderId	二选一	平台支付单号
executeNotify	否	true = 查询的同时重发一次回调（用于本地回调丢失时补发）
sign	是	签名

响应（status 为订单状态）

{
  "retCode": "0",
  "mchId": "1000",
  "productId": "2",
  "payOrderId": "P01202610090947271500000",
  "mchOrderNo": "TST179153924651944",
  "amount": "1000",
  "currency": "cny",
  "status": "2",
  "channelOrderNo": "920233",
  "paySuccTime": "1791539250000",
  "sign": "..."
}

status	含义
0	未出码/待处理（下单未完成）
1	支付中（已出码，等待用户支付）
2	支付成功
-1	支付失败（含未出码失败）
-2	订单超时关闭

五、支付结果通知（必接）

用户支付成功后，平台会向您下单时提供的 notifyUrl 发起 POST 请求（参数拼接在 URL 上，按 query 参数读取即可，PHP 用 $_REQUEST / Java 用 request.getParameter）。

参数	说明
payOrderId	平台支付单号
mchId / appId / productId	商户标识
mchOrderNo	商户订单号（关联您的业务单）
amount	订单金额（分）
income	商户入账金额（分）
status	订单状态，2 = 支付成功
channelOrderNo	渠道订单号
param1 / param2	下单时传入的扩展参数，原样返回
paySuccTime	支付成功时间（毫秒时间戳）
backType	通知类型
sign	签名（规则同第二节，用商户私钥验签）

商户侧处理要求

1. 验签：按第二节规则重算签名并与 sign 比对，不通过请勿处理业务；
2. 处理自身业务（订单加款等），按 mchOrderNo 做幂等（同一订单可能收到多次通知）；
3. 处理完成后输出纯文本 success（区分大小写不敏感）。

// PHP 回调处理骨架
$paramArray = $_REQUEST;
$sign = $paramArray["sign"]; unset($paramArray["sign"]);
if ($sign != paramArraySign($paramArray, $mchKey)) { echo "fail"; exit; }
if ($paramArray["status"] == 2) {
    // TODO: 按 mchOrderNo 幂等加款
}
echo "success";

未收到 success 应答时平台会按间隔重试（多次）；回调丢失也可随时用第四节「查询订单」主动对账（executeNotify=true 可补发回调）。

六、完整示例代码

随附 demo 压缩包（PHP / Java / ASP），内含：下单、查单、回调接收完整可运行代码（填入您的商户号与私钥即可使用）。

七、常见问题

Q：下单返回的二维码有效期多久？
A：二维码由上游渠道生成，有效期内完成支付即可；超时未支付的订单会被关闭（状态 -2 或 -1），需重新下单（换新 mchOrderNo）。

Q：mchOrderNo 可以重复使用吗？
A：不可以。同一商户内订单号必须唯一，失败/超时的订单请使用新的订单号重新发起。

Q：金额单位？
A：所有金额（下单、响应、通知）一律为分。

Q：收不到回调？
A：确认 notifyUrl 公网可达且返回 "success"；也可用查单接口主动对账；仍异常请联系运营排查。