开发文档 - 支付系统

快速开始

欢迎使用支付系统。以下是快速接入步骤：

1

注册商户账号

前往用户中心注册账号，获取你的商户ID和密钥。

2

选择支付方式

支持微信支付、支付宝、QQ钱包等多种支付方式。

3

调用API接口

参考下方接口文档，集成统一下单接口到你的应用中。

提示： 所有接口使用 POST 方式提交，数据格式为 application/x-www-form-urlencoded。

接口概览

接口	URL	请求方式	说明
统一下单	/submit.php	POST	创建支付订单，获取支付链接
查询订单	/mapi.php	POST	查询订单支付状态
支付网关	/gateway.php	GET	支付收银台页面

统一下单接口

创建支付订单，返回支付链接或跳转到收银台页面。

接口地址

POST /submit.php

请求参数

参数	类型	必填	说明
pid	int	是	商户ID，在用户中心获取
type	string	是	支付方式，如 wxpay / alipay / qqpay
out_trade_no	string	是	商户订单号，需保证唯一
notify_url	string	是	异步通知地址，支付结果通知
return_url	string	否	同步跳转地址，支付完成后跳转
name	string	是	商品名称
money	float	是	支付金额，单位元
sitename	string	否	网站名称
sign	string	是	签名，见签名算法说明
sign_type	string	否	签名类型，支持 MD5 / SHA256
clientip	string	否	客户端IP
device	string	否	设备类型：pc / mobile / auto
param	string	否	自定义参数，异步通知时原样返回

请求示例

POST /submit.php HTTP/1.1
Host: your-domain.com
Content-Type: application/x-www-form-urlencoded

pid=1001&type=wxpay&out_trade_no=ORDER20240101001¬ify_url=https%3A%2F%2Fyour-site.com%2Fnotify.php&return_url=https%3A%2F%2Fyour-site.com%2Freturn.php&name=%E5%95%86%E5%93%81%E5%90%8D%E7%A7%B0&money=1.00&sign=xxxxxxxxxxxxxxxxxxxxxxxxxx

PHP示例代码

<?php
$api_url = 'https://your-domain.com/submit.php';
$params = [
    'pid'          => '1001',
    'type'         => 'wxpay',
    'out_trade_no' => 'ORDER' . date('YmdHis') . rand(1000, 9999),
    'notify_url'   => 'https://your-site.com/notify.php',
    'return_url'   => 'https://your-site.com/return.php',
    'name'         => '测试商品',
    'money'        => '1.00',
];
$params['sign'] = getSign($params, 'your-secret-key');

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

echo $response;

返回结果

成功时返回JSON格式数据：

{
  "code": 1,
  "msg": "下单成功",
  "trade_no": "20240101000001",
  "out_trade_no": "ORDER20240101001",
  "payurl": "https://your-domain.com/gateway.php?trade_no=xxx",
  "qrcode": "https://your-domain.com/qrcode.php?trade_no=xxx"
}

失败时返回：

{
  "code": -1,
  "msg": "签名错误"
}

查询订单接口

查询订单的支付状态。

接口地址

POST /mapi.php?act=order

请求参数

参数	类型	必填	说明
pid	int	是	商户ID
key	string	是	商户密钥
out_trade_no	string	否	商户订单号（与trade_no二选一）
trade_no	string	否	系统订单号（与out_trade_no二选一）

返回结果

{
  "code": 1,
  "status": 1,
  "out_trade_no": "ORDER20240101001",
  "trade_no": "20240101000001",
  "money": "1.00",
  "buyer": "用户昵称",
  "paytime": "2024-01-01 12:00:00"
}

状态码说明：

status	含义
0	未支付
1	已支付
2	已退款

异步通知

支付成功后系统会向商户设置的 notify_url 发送POST请求通知支付结果。

通知参数

参数	类型	说明
pid	int	商户ID
trade_no	string	系统订单号
out_trade_no	string	商户订单号
type	string	支付方式
name	string	商品名称
money	string	支付金额
trade_status	string	TRADE_SUCCESS 表示支付成功
param	string	自定义参数（原样返回）
sign	string	签名
sign_type	string	签名类型

通知处理示例

<?php
// notify.php - 异步通知接收示例
$key = 'your-secret-key'; // 你的商户密钥

// 获取通知参数
$params = $_POST;

// 取出sign并验证签名
$sign = $params['sign'];
unset($params['sign']);
unset($params['sign_type']);

// 验证签名
if (getSign($params, $key) === $sign) {
    // 签名验证通过
    if ($params['trade_status'] === 'TRADE_SUCCESS') {
        // 处理支付成功逻辑
        $out_trade_no = $params['out_trade_no'];
        // 更新订单状态...
        
        echo 'success'; // 必须返回 success 告知系统已处理
        exit;
    }
}

echo 'fail';

重要： 异步通知处理成功后，必须返回字符串 success，系统会持续重发通知直到收到成功响应。最多重试5次，间隔递增。

签名算法

所有API请求必须包含签名（sign）参数以验证请求的合法性。

签名步骤

1

参数排序

将所有请求参数（不含sign）按参数名ASCII码从小到大排序。

2

拼接字符串

将排序后的参数用 & 连接，格式：key1=value1&key2=value2

3

拼接密钥

在字符串末尾拼接商户密钥 key。

4

生成签名

对拼接后的字符串进行MD5计算，取32位大写结果。

PHP签名函数

<?php
/**
 * 生成签名
 * @param array  $params 请求参数
 * @param string $key    商户密钥
 * @return string 签名结果
 */
function getSign($params, $key) {
    // 过滤空值及sign参数
    $params = array_filter($params, function($v) {
        return $v !== '' && $v !== null;
    });
    unset($params['sign']);
    unset($params['sign_type']);
    
    // 按参数名ASCII码排序
    ksort($params);
    
    // 拼接字符串
    $str = urldecode(http_build_query($params));
    
    // 拼接密钥并MD5
    return strtoupper(md5($str . $key));
}

// 使用示例
$params = [
    'pid'          => '1001',
    'type'         => 'wxpay',
    'out_trade_no' => 'ORDER20240101001',
    'notify_url'   => 'https://your-site.com/notify.php',
    'name'         => '测试商品',
    'money'        => '1.00',
];
$sign = getSign($params, 'your-secret-key');
echo $sign; // 输出32位大写的MD5结果

支付方式

type值	支付方式	适用场景
wxpay	微信支付	PC端扫码 / H5 / JSAPI
alipay	支付宝	PC端扫码 / H5 / 当面付
qqpay	QQ钱包	PC端扫码 / H5
jdpay	京东支付	PC端扫码
bank	网银支付	PC端网银
ylpay	云闪付	PC端扫码 / H5

常见问题

签名验证失败？

请检查：参数排序是否按ASCII码从小到大；是否过滤了sign参数；密钥是否正确；MD5是否转为大写。

支付金额限制？

单笔最低 0.01 元，最高请参考各支付渠道限制。建议大额支付分拆为多笔。

异步通知没收到？

检查 notify_url 是否可从外网访问；是否返回了 success；查看系统通知日志。

支持退款吗？

支持。可通过商户后台或退款接口发起退款，按原支付方式退回。

有SDK吗？

目前提供PHP示例代码，其他语言可参照签名算法自行封装。如有SDK需求请联系客服。

out_trade_no可以重复吗？

不可以。同一商户的 out_trade_no 需保证唯一，重复提交会返回错误。