API 接口文档

多用户版 · 兼容标准易支付协议 · 通过 pid 识别商户身份

创建支付订单

POST/GEThttps://zf.idc258.com/createOrder

商户服务端调用此接口创建一笔待支付订单。系统根据 pid 路由到对应商户，自动匹配该商户的收款二维码。

请求参数

参数名	类型	必填	说明
`pid`	Int	必填	商户ID，注册后在用户面板「API配置」中查看
`type`	String	必填	支付方式：`alipay` 支付宝 / `wxpay` 微信 / `qqpay` QQ钱包
`out_trade_no`	String	必填	商户系统内部订单号，同一商户下唯一
`money`	String	必填	订单金额，单位元，最小 0.01
`name`	String	必填	商品名称，如"VIP会员月卡"
`notify_url`	String	必填	服务器异步通知地址，支付成功后系统回调此URL
`return_url`	String	选填	页面同步跳转地址，支付完成后浏览器跳转。不传则使用 notify_url
`sitename`	String	选填	网站名称，显示在支付页
`sign`	String	必填	签名字符串，见下方签名算法
`sign_type`	String	必填	固定值 `MD5`
`isHtml`	Int	选填	默认 `1` 自动跳转支付页；传 `0` 返回JSON数据（含 payUrl）

响应（isHtml=0 时返回JSON）

JSON Response
{
  "code": 1,
  "msg": "成功",
  "data": {
    "payId": "20260731001",       // 商户订单号
    "orderId": "20260731143052xxxxx", // 平台订单号
    "payType": 2,                   // 1微信 2支付宝 3QQ
    "price": "88.00",              // 订单金额
    "reallyPrice": "88.01",        // 实际需付金额(可能含递增)
    "payUrl": "https://...",       // 收款二维码URL
    "isAuto": 0,                   // 0预设码 1自动码
    "state": 0,                    // 0待支付
    "timeOut": 5,                  // 超时分钟数
    "date": 1753945852             // 创建时间戳
  }
}

当 isHtml=1（默认）时，接口直接 302 跳转到支付页面 /payPage/pay.php?orderId=xxx，无需自行渲染二维码。

签名算法

签名用于验证请求合法性，防止参数篡改。所有接口使用相同的签名规则。

步骤

步骤	操作
1	将所有请求参数（不含 `sign`、`sign_type`）按参数名 ASCII 升序排列
2	拼接为 `key1=value1&key2=value2&...` 格式（值不做 URL 编码）
3	在拼接字符串末尾直接追加通信密钥（不加 & 符号）：`...&key3=value3`YOUR_KEY
4	对最终字符串取 MD5（32位小写）

签名示例
// 原始参数
pid=1001, type=alipay, out_trade_no=20260731001, money=88.00, name=VIP会员, notify_url=https://mysite.com/notify

// 按key排序后拼接
money=88.00&name=VIP会员¬ify_url=https://mysite.com/notify&out_trade_no=20260731001&pid=1001&type=alipay

// 末尾追加密钥
money=88.00&name=VIP会员&...&type=alipayabc123def456

// 取MD5
sign = md5("money=88.00&name=VIP会员&...&type=alipayabc123def456")

通信密钥在用户面板「API配置」中查看，请妥善保管，切勿泄露或在前端代码中暴露。

异步通知 (notify_url)

用户支付成功后，系统向商户的 notify_url 发送 GET 请求通知。商户处理完成后必须输出字符串 success，否则系统将在 5 分钟间隔内重试，最多 10 次。

通知参数

参数名	类型	说明
`pid`	Int	商户ID
`type`	String	支付方式：alipay / wxpay / qqpay
`out_trade_no`	String	商户订单号
`trade_no`	String	平台订单号
`name`	String	商品名称
`money`	String	订单金额（元）
`trade_status`	String	固定值 `TRADE_SUCCESS`
`sign`	String	签名字符串（验证方式同上）
`sign_type`	String	固定值 `MD5`

务必先验证 sign 再处理业务逻辑，防止伪造通知。同时做好订单去重，避免重复发货。

同步跳转 (return_url)

支付完成后，用户浏览器自动跳转到商户的 return_url，携带与异步通知相同的参数（GET 方式）。此跳转仅供前端展示"支付成功"页面，不可作为发货依据，发货必须以异步通知为准。

查询订单

获取订单详情

GEThttps://zf.idc258.com/getOrder?orderId={平台订单号}

返回订单完整信息，包含支付状态、金额、二维码等。

JSON Response
{
  "code": 1,
  "msg": "成功",
  "data": {
    "orderId": "20260731143052xxxxx",
    "payId": "20260731001",
    "payType": 2,
    "price": "88.00",
    "reallyPrice": "88.01",
    "state": 0,          // 0待支付 1已支付 -1已过期 2通知失败
    "date": 1753945852
  }
}

查询订单支付状态

GEThttps://zf.idc258.com/checkOrder?orderId={平台订单号}

若订单已支付，返回带签名的跳转URL（code=1）；未支付返回 code=-1。

code=1 已支付，data 为带签名的 return_url 完整链接

code=-1 订单未支付 / 已过期 / 不存在

关闭订单

GEThttps://zf.idc258.com/closeOrder?orderId={订单号}&sign={签名}

主动关闭一笔待支付订单，释放占用的金额位。仅 state=0 的订单可关闭。

参数名	说明
`orderId`	平台订单号
`sign`	签名 = `md5(orderId + KEY)`

错误码参考

code	msg	说明
1	成功	请求成功
-1	请传入商户ID	缺少 pid 参数
-1	商户ID错误	pid 不存在
-1	商户已被冻结	用户状态异常，联系管理员
-1	商户套餐已过期	需续费后使用
-1	请传入商户订单号	缺少 out_trade_no
-1	商户订单号已存在	out_trade_no 重复（已支付的不可复用）
-1	请传入支付方式...	type 值不合法
-1	订单金额不能小于0.01	money 过小
-1	签名错误	sign 验证不通过
-1	订单超出负荷，请稍后重试	金额递增50次仍冲突
-1	待支付订单不能超过N个	同IP未支付订单过多
-1	请在N秒后再发起支付	触发频率限制

PHP 对接示例

发起支付

pay.php
<?php
$pid = "1001";              // 您的商户ID
$key = "your_api_key";     // 您的通信密钥

$params = [
    'pid'          => $pid,
    'type'         => 'alipay',
    'out_trade_no' => date('YmdHis') . mt_rand(1000, 9999),
    'money'        => '88.00',
    'name'         => 'VIP会员月卡',
    'notify_url'   => 'https://yoursite.com/notify.php',
    'return_url'   => 'https://yoursite.com/return.php',
    'sitename'     => '我的商城',
];

// 签名
ksort($params);
$signStr = urldecode(http_build_query($params));
$params['sign'] = md5($signStr . $key);
$params['sign_type'] = 'MD5';

// 跳转支付页
$url = 'https://zf.idc258.com/createOrder?' . http_build_query($params);
header("Location: $url");

处理异步通知

notify.php
<?php
$key = "your_api_key";  // 您的通信密钥

$data = $_GET;
$sign = $data['sign'];
unset($data['sign'], $data['sign_type']);

// 验证签名
ksort($data);
$signStr = urldecode(http_build_query($data));
if (md5($signStr . $key) !== $sign) {
    exit('fail');  // 签名不合法
}

// 验证通过，处理业务
$out_trade_no = $data['out_trade_no'];  // 商户订单号
$trade_no     = $data['trade_no'];      // 平台订单号
$money        = $data['money'];         // 金额

// TODO: 查询本地订单，确认金额一致，发货/开通服务
// 注意去重：同一订单可能收到多次通知

exit('success');  // 必须输出 success

多用户说明：每位商户拥有独立的 pid 和通信密钥，在用户面板「API配置」页面查看。资金直达您自己的支付宝/微信账户，平台不经手。