💰 码支付 · 接入文档

易支付（epay）协议完全兼容 —— 已对接易支付的发卡网、商城、CMS 可零成本切换，仅需修改网关地址与商户密钥。

MD5 签名统一下单 /api/pay/订单查询 /api/query在线退款 /api/refund异步回调 + 重试队列

📚 快速跳转：接入流程签名规则统一下单异步回调订单查询在线退款对账补单常见问题

🔌 接入流程

① 登录商户后台，获取 商户ID（pid） 与 商户密钥（key）
② 业务系统按下方「统一下单」参数，POST 到 /api/pay/，成功后携带签名跳转收银台（系统直接返回 302 到收银台）
③ 用户支付成功后，系统向 notify_url 发送异步回调；验证签名后完成发货，并原样输出 success
④ 回调失败的订单自动进入重试队列（最长间隔重试 3 次），也可在商户后台查看回调日志并手动重试

⚡ 快速上手：下载 PHP Demo（单文件、无依赖，含下单与回调参考实现），改 3 个配置项即可跑通。

⬇ 下载 PHP Demo（codepay-demo.php）

🔐 签名规则（MD5）

① 剔除 sign、sign_type 及空值参数
② 参数名按 ASCII 升序排序
③ 拼接为 a=1&b=2&c=3（不带转义、末尾无 &）
④ 末尾直接拼接商户密钥后做 MD5，转小写

PHP

function epaySign($params, $key) {
    unset($params['sign'], $params['sign_type']);
    foreach ($params as $k => $v) { if ($v === '' || $v === null) unset($params[$k]); }
    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) { $str .= ($str === '' ? '' : '&') . $k . '=' . $v; }
    return strtolower(md5($str . $key));
}

⚠️ 可选安全参数：timestamp（Unix秒，±300秒有效）与 nonce（一次性随机串，最长64位）可开启 API 防重放，两者均需参与签名。商户后台「API 安全」还可配置 IP 白名单。

📝 统一下单

POST https://你的域名/api/pay/（结尾必须带斜杠 /；表单或 JSON 均可）。签名验证通过后，浏览器请求将被 302 重定向到收银台；程序请求返回 JSON。

参数	必填	说明
pid	必填	商户ID
type	必填	wxpay / alipay（收款码通道）；wxpay_native / wxpay_jsapi / wxpay_h5 / alipay_qr / alipay_wap（官方通道）
out_trade_no	必填	商户订单号，需保证唯一；重复提交返回原订单号（幂等）
notify_url	必填	异步回调地址，支付成功后系统 POST/GET 通知
return_url	选填	支付完成后浏览器跳转地址（自动附加签名参数）
name	必填	商品名称（≤128字）
money	必填	金额（元），须在商户配置的金额范围内
sign / sign_type	必填	签名 / 固定 MD5
timestamp / nonce	选填	防重放参数（参与签名）

响应 JSON

{
  "code": 1,
  "msg": "success",
  "data": {
    "trade_no": "CP20250101120001",   // 平台订单号
    "out_trade_no": "M20250101001",  // 商户订单号
    "money": "10.05",                // 实际应付金额（开启金额浮动时与提交金额略有尾差）
    "type": "wxpay",
    "account_id": "ACCxxxx",
    "payurl": "https://域名/pay/CP20250101120001"  // 收银台地址
  }
}

💡 若商户开启「金额浮动」，money 会加 ±几分钱的随机尾数用于区分并发订单，返回值与回调中的金额均为实际支付金额；原始金额可在后台订单列表查看。

📩 异步回调（notify_url）

支付成功后，系统通过 GET 方式请求 notify_url 并附加以下参数（含签名）。业务方验证签名后处理订单，返回/输出 success 表示通知成功，否则系统将按队列重试。

参数	说明
pid	商户ID
trade_no	平台订单号
out_trade_no	商户订单号
type	支付通道
name	商品名称
money	实际支付金额
trade_status	固定 TRADE_SUCCESS
sign / sign_type	签名（同下单规则验签）/ MD5

PHP · notify.php

<?php
$key = '你的商户密钥';
// 复用上面的 epaySign()
if (epaySign($_GET, $key) !== $_GET['sign']) { exit('sign error'); }
if ($_GET['trade_status'] === 'TRADE_SUCCESS') {
    $outTradeNo = $_GET['out_trade_no'];
    $money = $_GET['money'];
    // 1. 按商户订单号查本地订单
    // 2. 校验金额一致（防伪造）
    // 3. 更新订单为已支付（务必做幂等，防止重复回调重复发货）
}
echo 'success';

🔍 订单查询

POST /api/query，参数 pid + trade_no（二选一，优先 trade_no）或 out_trade_no，附加签名。

响应 data

{
  "trade_no": "CP20250101120001",
  "out_trade_no": "M20250101001",
  "money": "10.05",
  "type": "wxpay",
  "status": "paid",        // pending / paid / expired
  "paid_at": "2025-01-01 18:00:00",
  "created_at": "2025-01-01 17:43:20"
}

↩️ 在线退款

POST /api/refund（易支付风格签名）。官方通道订单调用微信/支付宝 API 原路退回；收款码通道订单仅登记退款（资金在个人钱包，需线下退回）。money 不传 = 全额退款，支持多次部分退款。

参数	必填	说明
pid	必填	商户ID
trade_no / out_trade_no	必填	平台订单号 / 商户订单号（二选一）
money	选填	退款金额，缺省全额
note	选填	退款原因备注
sign / sign_type	必填	签名 / MD5

🧮 对账补单推送（平台管理员功能）

监控挂机意外掉线时，可用外部对账脚本把聚合码平台收款明细推送回来自动补单：

POST

curl -X POST "https://你的域名/api/reconcile/push?key=对账令牌" \
  -d "money=10.05" \
  -d "pid=100001" \
  -d "minutes=30"

# money   必填：实际收款金额
# pid     选填：限定商户（多笔同金额订单时必须指定）
# minutes 选填：匹配时间窗（分钟，默认 30）
# 匹配成功自动走支付成功全流程（回调 / 通知 / 统计）

对账令牌在总后台「⚙️ 系统设置」页查看；也可在总后台「对账补单」页人工查找候选订单并确认补单。

❓ 常见问题

回调收不到？ 检查 notify_url 是否外网可访问；商户后台「回调日志」查看每次通知的响应原文；失败订单自动进入重试队列。
提示签名错误？ 确认密钥无空格、参数按规则排序拼接、空值参数已剔除；timestamp 偏差超过 ±300 秒会提示过期。
提示 IP 不在白名单？ 商户后台「API 安全」中把服务器出口 IP 加入白名单，或清空白名单关闭限制。
金额浮动会影响到账核对吗？ 不会。浮动仅 ±几分，回调 money 即实际支付金额；发货校验建议按 out_trade_no 而非固定金额。
如何测试？ 用 Demo 发起 1 分钱~1 元测试单，在监控端（或后台「对账补单」）确认到账即走通全流程。

码支付 · 易支付兼容接入文档 · v17