简介与协议规则

感谢使用 柯达集团。本页是开发者对接文档（V1 / MD5 签名），覆盖以下内容：

• 页面跳转支付 submit.php —— 适合网站，用户浏览器跳转到收银台付款
• API 接口支付 mapi.php —— 适合 App / 服务端，返回支付链接或二维码
• 支付结果异步通知 —— 付款成功后平台回调你的服务器
• 查询与退款 api.php?act=... —— 商户信息、订单、结算记录查询与退款

对接地址与接口路径

对接需要两个凭证，均可在商户后台「API 凭证」页获取：pid（商户 ID）和 key（MD5 密钥）。key 泄露等于资金风险，请只保存在服务器端，绝不要写进网页或 App 前端。

5 分钟对接流程

1. 在商户后台「API 凭证」页拿到 pid 和 key。
2. 选择接入方式：网站用 submit.php（页面跳转）；App / 后端用 mapi.php（返回支付链接）。
3. 按 MD5 签名算法 生成 sign，提交下单参数（金额、订单号、回调地址等）。
4. 用户完成支付后，平台以 GET 方式请求你的 notify_url；你验签后处理订单，并返回纯文本 success。
5. 建议：再用 单个订单查询 做主动查单兜底，避免因网络问题漏单。

MD5 签名算法

签名的作用是用密钥给参数"盖章"，防止请求被伪造或篡改。生成步骤：

1. 取出所有值非空的请求参数；剔除 sign 和 sign_type。
2. 按参数名 ASCII 从小到大排序（a → z）。
3. 拼接成 a=1&b=2&c=3 形式（值不要做 URL 编码）。
4. sign = md5(拼接字符串 + 商户密钥key)，结果取小写。密钥直接拼在末尾，中间没有 & 或 &key=。

PHP 参考实现（可直接复制使用）：

function make_sign(array $params, $key) {
    unset($params['sign'], $params['sign_type']);
    ksort($params);
    $parts = array();
    foreach ($params as $k => $v) {
        if ($v === '' || $v === null) continue;
        $parts[] = $k . '=' . $v;
    }
    return md5(implode('&', $parts) . $key);
}

示例：假设密钥为 KEY123，参与签名的参数拼接后为：

money=1.00&name=test¬ify_url=https://xx/notify.php&out_trade_no=20260817001&pid=1001&type=alipay

sign = md5("money=1.00&name=...&type=alipayKEY123")

收到异步通知时，用同样的规则对通知参数重新计算 sign，与通知中携带的 sign 比对，一致才可信。

支付方式与设备类型

支付方式列表 (type)

下单时 type 参数填「调用值」。实际可用范围以你商户后台开通的为准。

设备类型列表 (device)

可选参数，帮助平台返回更合适的支付形式（如微信内直接唤起支付）。

USDT 支付说明

支付方式调用值：type=usdt（需商户后台已开通）。

• money 仍然填人民币金额（元），系统按实时汇率自动换算应付 USDT 数量。
• 通过 mapi.php 下单会返回 payurl：用户打开后先选择链（BSC 或 TRON），再显示收款地址与应付 USDT。
• BSC（推荐）：不额外加收链上手续费。
• TRON：用户需额外承担 1.5 USDT 链上手续费，已自动计入应付总额。
• 到账后与普通订单一样走异步通知；链上交易哈希可通过 订单查询 的 api_trade_no 字段获取。

USDT 下单返回示例：

{
  "code": 1,
  "trade_no": "2026081715300012345",
  "payurl": "<对接地址>/pay/usdt/2026081715300012345/"
}

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

适用场景：网站收银台。用户点击"去支付"后，浏览器跳转到本平台页面完成付款，付完自动跳回你的 return_url。

接口地址： <对接地址>/submit.php

请求方式： POST（推荐）或 GET

PHP 生成支付表单示例：

$params = array(
    'pid'          => 1001,
    'type'         => 'alipay',
    'out_trade_no' => date('YmdHis') . rand(100, 999),
    'notify_url'   => 'https://你的域名/notify.php',
    'return_url'   => 'https://你的域名/return.php',
    'name'         => 'VIP会员',
    'money'        => '100.00',
);
$params['sign'] = make_sign($params, $KEY);   // 见「MD5 签名算法」
$params['sign_type'] = 'MD5';

// 输出自动提交的表单，浏览器即跳转到收银台
echo '<form id="pay" action="<对接地址>/submit.php" method="post">';
foreach ($params as $k => $v) {
    echo '<input type="hidden" name="' . $k . '" value="' . htmlspecialchars($v) . '">';
}
echo '</form><script>document.getElementById("pay").submit()</script>';

2. API 接口支付（mapi.php）

适用场景：App / 服务端对接。你的后端发起请求，拿到 payurl（支付链接）或 qrcode（二维码内容），再展示给用户。

接口地址： <对接地址>/mapi.php

请求方式： POST

在页面跳转支付参数基础上，增加 / 变化的参数：

返回字段（JSON）：

payurl / qrcode / urlscheme 每次只返回其中一个，按收到的字段处理即可。

PHP cURL 请求示例：

$params = array(
    'pid'          => 1001,
    'type'         => 'alipay',
    'out_trade_no' => '20260817151343001',
    'notify_url'   => 'https://你的域名/notify.php',
    'return_url'   => 'https://你的域名/return.php',
    'name'         => 'VIP会员',
    'money'        => '100.00',
    'clientip'     => $_SERVER['REMOTE_ADDR'],  // 用户真实 IP
    'device'       => 'mobile',
);
$params['sign'] = make_sign($params, $KEY);
$params['sign_type'] = 'MD5';

$ch = curl_init('<对接地址>/mapi.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($result['code'] == 1) {
    // 三选一：payurl / qrcode / urlscheme
}

3. 支付结果通知（异步 / 同步）

付款成功后，平台会以 GET 方式请求你在下单时传入的两个地址：

• notify_url —— 服务器异步通知，必须处理，是唯一可信的入账依据
• return_url —— 用户浏览器跳转，仅用于向用户展示结果，不能只靠它更新订单

通知参数：

失败重试机制：你的服务器没有返回 success 时，平台会自动重试，间隔依次约为 2 分钟、16 分钟、36 分钟、1 小时，最多重试 5 次后停止。也可以在商户后台「订单明细 → 详情」中查看每次回调的结果，或手动点击"补单"重新发送。

PHP 通知处理示例（notify.php）：

$KEY = '你的商户密钥';

// 1. 验签（用收到的原始参数值，不要重新格式化金额）
$sign = make_sign($_GET, $KEY);
if ($sign !== ($_GET['sign'] ?? '')) exit('sign error');

// 2. 校验支付状态
if (($_GET['trade_status'] ?? '') !== 'TRADE_SUCCESS') exit('fail');

// 3. 按 out_trade_no 找到本地订单，校验金额一致
//    if (bccomp($_GET['money'], $order['money'], 2) !== 0) exit('money error');

// 4. 幂等更新：未处理则标记为已支付并发货；已处理直接跳过

// 5. 必须输出纯文本 success
echo 'success';

4. 商户信息查询

用途：查询账户余额、商户状态、订单统计。

接口地址： <对接地址>/api.php?act=query&pid={商户ID}&key={商户密钥}

请求方式： GET

返回示例：

{
  "code": 1,
  "pid": 1001,
  "active": 1,            // 商户状态：1 正常 / 0 封禁
  "money": "1234.56",     // 账户余额（元）
  "type": 1,              // 结算方式
  "account": "结算账号",
  "username": "结算姓名",
  "orders": 2329,         // 累计订单数
  "orders_today": 6,      // 今日成功订单数
  "orders_lastday": 18    // 昨日成功订单数
}

5. 单个订单查询

用途：主动查询某笔订单是否已支付，与异步通知互补，防止漏单。

接口地址： <对接地址>/api.php?act=order&pid={商户ID}&key={商户密钥}&out_trade_no={商户订单号}

请求方式： GET

• trade_no（平台订单号）与 out_trade_no（商户订单号）二选一；都传时以 trade_no 为准。

返回示例：

{
  "code": 1,
  "msg": "succ",
  "trade_no": "2026081715300012345",   // 平台订单号
  "out_trade_no": "20260817151343001", // 商户订单号
  "api_trade_no": "...",               // 上游 / 链上交易号
  "type": "alipay",                    // 支付方式
  "pid": 1001,
  "addtime": "2026-08-17 15:13:43",    // 创建时间
  "endtime": "2026-08-17 15:14:02",    // 支付时间
  "name": "VIP会员",
  "money": "100.00",
  "param": "",
  "buyer": "",                         // 付款账号
  "status": 1                          // 1 已支付 / 0 未支付
}

6. 批量订单查询

接口地址： <对接地址>/api.php?act=orders&pid={商户ID}&key={商户密钥}&limit=20&offset=0

请求方式： GET

成功返回 count（本次条数）与 data（订单数组，字段同单个订单查询）。

7. 结算记录查询

接口地址： <对接地址>/api.php?act=settle&pid={商户ID}&key={商户密钥}&limit=10&offset=0

请求方式： GET

• limit：返回条数，默认 10，最大 50
• offset：偏移量，默认 0

成功时 code=1，data 为结算记录数组。

8. 订单退款

前提：需管理员为商户开启「订单退款 API」权限，未开启会返回 code=-2。

接口地址： <对接地址>/api.php?act=refund

请求方式： POST

返回示例（注意：此接口成功时 code=0，与其他接口不同）：

{
  "code": 0,
  "msg": "退款工单已创建，等待人工处理",
  "ticket_no": "TK202608170001",   // 退款工单号
  "status": "pending",
  "money": "100.00"
}

常见问题