协议规则
请求数据格式:application/x-www-form-urlencoded
返回数据格式:JSON
签名算法:MD5
字符编码:UTF-8
请求协议:生产环境请务必使用 HTTPS
接入流程(5 步完成)
- 注册商户:在 七七支付平台 注册账号,登录商户后台。
- 获取凭据:在商户后台「密钥设置」中获取
商户ID(pid)与商户密钥(key)。密钥请勿泄露给他人,泄露后立即重置。 - 配置回调地址:在你的服务器上准备两个地址:
notify_url(异步通知):由服务器接收,必须以success响应,否则平台会重复通知。return_url(同步跳转):用户支付完成后浏览器跳回的页面,用于展示结果。
- 发起支付:按「页面跳转支付」或「API接口支付」文档构造参数并签名,提交到对应地址。
- 处理结果:收到通知后先验签,再校验金额与订单状态,最后执行业务逻辑并返回
success。
重要:不要仅依赖 return_url 判定支付成功,用户可能中途关闭页面。必须以 notify_url 的异步通知为准。
页面跳转支付
此接口可用于用户前台直接发起支付,使用form表单跳转或拼接成url跳转。
URL地址:https://qpay.xq688.com.cn/submit.php
请求方式:POST 或 GET(推荐POST,不容易被劫持或屏蔽)
请求参数说明:
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | pid | 是 | Int | 1001 | 商户后台获取 |
| 支付方式 | type | 否 | String | alipay | 支付方式列表;不传则跳转收银台 |
| 商户订单号 | out_trade_no | 是 | String | 20160806151343349 | 商户系统内唯一,建议 ≤32 位字母数字 |
| 异步通知地址 | notify_url | 是 | String | http://www.pay.com/notify_url.php | 服务器异步通知地址,需公网可访问 |
| 跳转通知地址 | return_url | 是 | String | http://www.pay.com/return_url.php | 页面跳转通知地址 |
| 商品名称 | name | 是 | String | VIP会员 | 如超过127个字节会自动截取 |
| 商品金额 | money | 是 | String | 1.00 | 单位:元,最大2位小数 |
| 业务扩展参数 | param | 否 | String | 没有请留空 | 支付后原样返回,可用于携带自定义数据 |
| 签名字符串 | sign | 是 | String | 202cb962ac59075b964b07152d234b70 | 签名算法点此查看 |
| 签名类型 | sign_type | 是 | String | MD5 | 固定为 MD5 |
支付方式(type)不传会跳转到收银台支付
API接口支付
此接口可用于服务器后端发起支付请求,会返回支付二维码链接或支付跳转url。适合扫码支付、小程序支付等场景。
URL地址:https://qpay.xq688.com.cn/mapi.php
请求方式:POST
请求参数说明:
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | pid | 是 | Int | 1001 | 商户后台获取 |
| 支付方式 | type | 是 | String | alipay | 支付方式列表 |
| 商户订单号 | out_trade_no | 是 | String | 20160806151343349 | 商户系统内唯一 |
| 异步通知地址 | notify_url | 是 | String | http://www.pay.com/notify_url.php | 服务器异步通知地址 |
| 跳转通知地址 | return_url | 否 | String | http://www.pay.com/return_url.php | 页面跳转通知地址 |
| 商品名称 | name | 是 | String | VIP会员 | 如超过127个字节会自动截取 |
| 商品金额 | money | 是 | String | 1.00 | 单位:元,最大2位小数 |
| 用户IP地址 | clientip | 是 | String | 192.168.1.100 | 用户发起支付的IP地址(传真实客户端IP) |
| 设备类型 | device | 否 | String | pc | 根据用户浏览器的UA判断, 传入用户所使用的浏览器 或设备类型,默认为pc 设备类型列表 |
| 业务扩展参数 | param | 否 | String | 没有请留空 | 支付后原样返回 |
| 签名字符串 | sign | 是 | String | 202cb962ac59075b964b07152d234b70 | 签名算法点此查看 |
| 签名类型 | sign_type | 是 | String | MD5 | 固定为 MD5 |
返回结果(json):
| 字段名 | 变量名 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|
| 返回状态码 | code | Int | 1 | 1为成功,其它值为失败 |
| 返回信息 | msg | String | 失败时返回原因 | |
| 订单号 | trade_no | String | 20160806151343349 | 平台订单号 |
| 支付跳转url | payurl | String | https://qpay.xq688.com.cn/pay/wxpay/202010903/ | 如果返回该字段,则直接跳转到该url支付 |
| 二维码链接 | qrcode | String | weixin://wxpay/bizpayurl?pr=04IPMKM | 如果返回该字段,则根据该url生成二维码 |
| 小程序跳转url | urlscheme | String | weixin://dl/business/?ticket=xxx | 如果返回该字段,则使用js跳转该url,可发起微信小程序支付 |
注:payurl、qrcode、urlscheme 三个参数只会返回其中一个,请按返回字段自行判断处理方式。
支付结果通知
通知类型:服务器异步通知(notify_url)、页面跳转通知(return_url)
请求方式:GET
请求参数说明:
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | pid | 是 | Int | 1001 | |
| 平台订单号 | trade_no | 是 | String | 20160806151343349021 | 七七支付平台订单号 |
| 商户订单号 | out_trade_no | 是 | String | 20160806151343349 | 商户系统内部的订单号 |
| 支付方式 | type | 是 | String | alipay | 支付方式列表 |
| 商品名称 | name | 是 | String | VIP会员 | |
| 商品金额 | money | 是 | String | 1.00 | 务必与本地订单金额比对 |
| 支付状态 | trade_status | 是 | String | TRADE_SUCCESS | 只有 TRADE_SUCCESS 是成功 |
| 业务扩展参数 | param | 否 | String | 发起支付时传入的原样返回 | |
| 签名字符串 | sign | 是 | String | 202cb962ac59075b964b07152d234b70 | 签名算法点此查看 |
| 签名类型 | sign_type | 是 | String | MD5 | 固定为 MD5 |
收到异步通知后,需返回 success(纯文本,不带任何 HTML/JSON)以表示服务器接收到了订单通知。返回其它内容平台会认为通知失败并重复推送。
notify_url 处理清单(缺一不可):
- 验签:用本文档的签名算法重新计算,与收到的
sign比对。不一致直接丢弃。 - 校验商户:确认
pid是自己的商户ID。 - 校验金额:
money必须与本地订单金额一致,防止篡改。 - 校验订单:
out_trade_no必须存在于本地订单表且状态为未支付。 - 幂等处理:同一
out_trade_no重复通知只处理一次(用数据库唯一索引或状态机保证)。 - 返回 success:业务处理完成后再输出
success。
安全提示:平台可能在极短时间内重复推送通知,请勿在通知处理中执行耗时操作;建议先落库标记、异步处理业务。
MD5签名算法
1、将发送或接收到的所有参数按照参数名ASCII码从小到大排序(a-z),sign、sign_type、和空值不参与签名!
2、将排序后的参数拼接成URL键值对的格式,例如 a=b&c=d&e=f,参数值不要进行url编码。
3、再将拼接好的字符串与商户密钥KEY进行MD5加密得出sign签名参数,sign = md5 ( a=b&c=d&e=f + KEY ) (注意:+ 为各语言的拼接符,不是字符!),md5结果为小写。
4、具体签名与发起支付的示例代码可下载SDK查看。
PHP 示例:
function makeSign($param, $key){
ksort($param); // 1. 按键名 ASCII 升序
reset($param);
$str = '';
foreach($param as $k => $v){
if($k != 'sign' && $k != 'sign_type' && $v !== '' && $v !== null){
$str .= $k . '=' . $v . '&';
}
}
$str = substr($str, 0, -1); // 去掉末尾 &
return md5($str . $key); // 2. 拼接密钥后 MD5
}
Python 示例:
import hashlib
def make_sign(param: dict, key: str) -> str:
items = [(k, v) for k, v in param.items()
if k not in ('sign', 'sign_type') and v not in ('', None)]
items.sort(key=lambda x: x[0]) # 按键名 ASCII 升序
s = '&'.join(f'{k}={v}' for k, v in items)
return hashlib.md5((s + key).encode('utf-8')).hexdigest()
Java 示例:
public static String makeSign(Map<String,String> param, String key) {
List<String> keys = new ArrayList<>(param.keySet());
Collections.sort(keys);
StringBuilder sb = new StringBuilder();
for (String k : keys) {
if ("sign".equals(k) || "sign_type".equals(k)) continue;
String v = param.get(k);
if (v == null || v.isEmpty()) continue;
if (sb.length() > 0) sb.append("&");
sb.append(k).append("=").append(v);
}
sb.append(key);
return md5Hex(sb.toString());
}
Go 示例:
func MakeSign(param map[string]string, key string) string {
keys := make([]string, 0, len(param))
for k, v := range param {
if k == "sign" || k == "sign_type" || v == "" { continue }
keys = append(keys, k)
}
sort.Strings(keys)
var sb strings.Builder
for i, k := range keys {
if i > 0 { sb.WriteString("&") }
sb.WriteString(k + "=" + param[k])
}
sb.WriteString(key)
sum := md5.Sum([]byte(sb.String()))
return hex.EncodeToString(sum[:])
}
常见签名错误排查:
| 现象 | 原因 | 解决 |
|---|---|---|
| 签名一直校验失败 | 参与了空值参数 | 空字符串 / null 的参数必须剔除,不能拼成 a= |
| 本地算的和平台不一致 | 排序用了字典序而非 ASCII 序 | 用 ASCII 升序(大写字母排在小写之前) |
| 通知验签失败但支付成功 | 对参数值做了 urlencode | 拼接时用原始值,不要编码 |
| 偶发失败 | 密钥尾部有空格 | 检查商户密钥是否复制完整、无多余空白 |
| MD5 结果大小写不一致 | 用了大写 | 必须小写 |
支付方式列表
| 调用值 | 描述 |
|---|---|
| alipay | 支付宝 |
| wxpay | 微信支付 |
实际可用的支付方式以商户后台「通道管理」中已开通的为准。
设备类型列表
| 调用值 | 描述 |
|---|---|
| pc | 电脑浏览器 |
| mobile | 手机浏览器 |
| 手机QQ内浏览器 | |
| 微信内浏览器 | |
| alipay | 支付宝客户端 |
| jump | 仅返回支付跳转url |
完整接入示例(PHP)
以下为可直接运行的完整示例,包含发起支付与异步通知处理两部分。
① 发起支付(pay.php)
<?php
// ===== 1. 商户配置 =====
$pid = '1001'; // 商户ID
$key = '你的商户密钥'; // 商户密钥
$api_url = 'https://qpay.xq688.com.cn/'; // 平台地址
$notify_url = 'https://你的域名/notify_url.php'; // 异步通知
$return_url = 'https://你的域名/return_url.php'; // 同步跳转
// ===== 2. 构造订单 =====
$out_trade_no = 'ORDER' . date('YmdHis') . mt_rand(1000, 9999);
$money = '1.00';
$name = 'VIP会员';
$type = 'alipay';
// ===== 3. 签名 =====
$param = [
'pid' => $pid,
'type' => $type,
'out_trade_no' => $out_trade_no,
'notify_url' => $notify_url,
'return_url' => $return_url,
'name' => $name,
'money' => $money,
];
ksort($param);
$str = '';
foreach ($param as $k => $v) {
if ($k != 'sign' && $k != 'sign_type' && $v !== '') {
$str .= $k . '=' . $v . '&';
}
}
$str = rtrim($str, '&');
$param['sign'] = md5($str . $key);
$param['sign_type'] = 'MD5';
// ===== 4. 本地落库(重要:先落库再跳转)=====
// INSERT INTO orders (out_trade_no, money, status) VALUES (?, ?, 0);
// ===== 5. 自动提交表单跳转 =====
echo '<form id="pay" action="' . $api_url . 'submit.php" method="post">';
foreach ($param as $k => $v) {
echo '<input type="hidden" name="' . $k . '" value="' . htmlspecialchars($v) . '">';
}
echo '</form><script>document.getElementById("pay").submit();</script>';
② 异步通知处理(notify_url.php)
<?php
$pid = '1001';
$key = '你的商户密钥';
// ===== 1. 验签 =====
$param = $_GET;
if (empty($param['sign'])) { exit('fail'); }
$sign = $param['sign'];
unset($param['sign'], $param['sign_type']);
ksort($param);
$str = '';
foreach ($param as $k => $v) {
if ($v !== '') { $str .= $k . '=' . $v . '&'; }
}
$str = rtrim($str, '&');
if (md5($str . $key) !== $sign) {
exit('fail'); // 验签失败
}
// ===== 2. 校验商户 =====
if ($param['pid'] != $pid) { exit('fail'); }
// ===== 3. 校验支付状态 =====
if ($param['trade_status'] != 'TRADE_SUCCESS') { exit('fail'); }
// ===== 4. 查本地订单并校验金额 =====
// $order = $db->query("SELECT * FROM orders WHERE out_trade_no=?",
// [$param['out_trade_no']]);
// if (!$order) exit('fail');
// if ($order['money'] != $param['money']) exit('fail');
// if ($order['status'] == 1) exit('success'); // 幂等:已处理过直接返回成功
// ===== 5. 执行业务逻辑 =====
// $db->update("UPDATE orders SET status=1, trade_no=? WHERE out_trade_no=? AND status=0",
// [$param['trade_no'], $param['out_trade_no']]);
// ===== 6. 必须返回 success =====
echo 'success';
常见返回码与错误说明
| code | 含义 | 排查方向 |
|---|---|---|
| 1 | 成功 | — |
| -1 | 业务错误(msg 中带原因) | 看 msg 具体内容 |
| -2 | 商户ID或密钥错误 | 核对 pid / key;确认密钥未被重置 |
| -3 | 商户ID或密钥错误 | 同上 |
| -4 | 功能未开启 | 如退款需在商户后台开启「自助退款」开关 |
| -5 | 订单不存在 | 核对 out_trade_no / trade_no 是否正确 |
不同版本返回码可能略有差异,请以实际返回的 msg 字段为准。
接入常见问题
Q:支付成功了但本地订单还是未支付状态?
A:99% 是 notify_url 没返回 success,或者 notify_url 不是公网可访问地址(内网地址、localhost、带 302 跳转都会导致通知失败)。用浏览器直接访问 notify_url 看是否能正常响应。
Q:notify_url 收到了多次通知?
A:正常现象。平台在未收到 success 前会重试。请在业务逻辑中做幂等处理(按 out_trade_no 唯一索引),重复通知直接返回 success。
Q:签名怎么算都不对?
A:按顺序检查:① 是否剔除了空值参数;② 是否按 ASCII 升序;③ 拼接时是否误做了 urlencode;④ 密钥是否有空格;⑤ MD5 是否小写。参考签名算法一节的排查表。
Q:mapi.php 返回 code=1 但没有 payurl?
A:payurl、qrcode、urlscheme 只会返回其中一个。扫码场景用 qrcode 生成二维码,H5 场景用 payurl 跳转,小程序场景用 urlscheme。
Q:能不能只靠 return_url 判断支付成功?
A:不能。return_url 是浏览器跳转,用户可以中途关闭、网络可以中断。必须以 notify_url 异步通知为准,return_url 只用于展示结果页。
Q:金额能用 0.001 这种三位小数吗?
A:不能,金额最大 2 位小数,单位元。传三位小数会被拒。
[API]查询商户信息
URL地址:https://qpay.xq688.com.cn/api.php?act=query&pid={商户ID}&key={商户密钥}
请求参数说明:
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 操作类型 | act | 是 | String | query | 此API固定值 |
| 商户ID | pid | 是 | Int | 1001 | |
| 商户密钥 | key | 是 | String | 89unJUB8HZ54Hj7x4nUj56HN4nUzUJ8i |
返回结果:
| 字段名 | 变量名 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|
| 返回状态码 | code | Int | 1 | 1为成功,其它值为失败 |
| 商户ID | pid | Int | 1001 | 商户ID |
| 商户密钥 | key | String(32) | 89unJUB8HZ54Hj7x4nUj56HN4nUzUJ8i | 商户密钥 |
| 商户状态 | active | Int | 1 | 1为正常,0为封禁 |
| 商户余额 | money | String | 0.00 | 商户所拥有的余额 |
| 结算方式 | type | Int | 1 | 1:支付宝,2:微信,3:QQ,4:银行卡 |
| 结算账号 | account | String | admin@pay.com | 结算的支付宝账号 |
| 结算姓名 | username | String | 张三 | 结算的支付宝姓名 |
| 订单总数 | orders | Int | 30 | 订单总数统计 |
| 今日订单 | order_today | Int | 15 | 今日订单数量 |
| 昨日订单 | order_lastday | Int | 15 | 昨日订单数量 |
[API]查询结算记录
URL地址:https://qpay.xq688.com.cn/api.php?act=settle&pid={商户ID}&key={商户密钥}
请求参数说明:
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 操作类型 | act | 是 | String | settle | 此API固定值 |
| 商户ID | pid | 是 | Int | 1001 | |
| 商户密钥 | key | 是 | String | 89unJUB8HZ54Hj7x4nUj56HN4nUzUJ8i |
返回结果:
| 字段名 | 变量名 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|
| 返回状态码 | code | Int | 1 | 1为成功,其它值为失败 |
| 返回信息 | msg | String | 查询结算记录成功! | |
| 结算记录 | data | Array | 结算记录列表 |
[API]查询单个订单
URL地址:https://qpay.xq688.com.cn/api.php?act=order&pid={商户ID}&key={商户密钥}&out_trade_no={商户订单号}
请求参数说明:
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 操作类型 | act | 是 | String | order | 此API固定值 |
| 商户ID | pid | 是 | Int | 1001 | |
| 商户密钥 | key | 是 | String | 89unJUB8HZ54Hj7x4nUj56HN4nUzUJ8i | |
| 系统订单号 | trade_no | 选择 | String | 20160806151343312 | |
| 商户订单号 | out_trade_no | 选择 | String | 20160806151343349 |
提示:系统订单号 和 商户订单号 二选一传入即可,如果都传入以系统订单号为准!
返回结果:
| 字段名 | 变量名 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|
| 返回状态码 | code | Int | 1 | 1为成功,其它值为失败 |
| 返回信息 | msg | String | 查询订单号成功! | |
| 平台订单号 | trade_no | String | 2016080622555342651 | 七七支付平台订单号 |
| 商户订单号 | out_trade_no | String | 20160806151343349 | 商户系统内部的订单号 |
| 第三方订单号 | api_trade_no | String | 20160806151343349 | 支付宝微信等接口方订单号 |
| 支付方式 | type | String | alipay | 支付方式列表 |
| 商户ID | pid | Int | 1001 | 发起支付的商户ID |
| 创建订单时间 | addtime | String | 2016-08-06 22:55:52 | |
| 完成交易时间 | endtime | String | 2016-08-06 22:55:52 | |
| 商品名称 | name | String | VIP会员 | |
| 商品金额 | money | String | 1.00 | |
| 支付状态 | status | Int | 0 | 1为支付成功,0为未支付 |
| 业务扩展参数 | param | String | 默认留空 | |
| 支付者账号 | buyer | String | 默认留空 |
[API]批量查询订单
URL地址:https://qpay.xq688.com.cn/api.php?act=orders&pid={商户ID}&key={商户密钥}
请求参数说明:
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 操作类型 | act | 是 | String | orders | 此API固定值 |
| 商户ID | pid | 是 | Int | 1001 | |
| 商户密钥 | key | 是 | String | 89unJUB8HZ54Hj7x4nUj56HN4nUzUJ8i | |
| 查询订单数量 | limit | 否 | Int | 20 | 返回的订单数量,最大50 |
| 页码 | page | 否 | Int | 1 | 当前查询的页码 |
返回结果:
| 字段名 | 变量名 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|
| 返回状态码 | code | Int | 1 | 1为成功,其它值为失败 |
| 返回信息 | msg | String | 查询结算记录成功! | |
| 订单列表 | data | Array | 订单列表 |
[API]提交订单退款
需要先在商户后台开启订单退款API接口开关,才能调用该接口发起订单退款
URL地址:https://qpay.xq688.com.cn/api.php?act=refund
请求方式:POST
请求参数说明:
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | pid | 是 | Int | 1001 | |
| 商户密钥 | key | 是 | String | 89unJUB8HZ54Hj7x4nUj56HN4nUzUJ8i | |
| 平台订单号 | trade_no | 特殊可选 | String | 20160806151343349021 | 平台订单号 |
| 商户订单号 | out_trade_no | 特殊可选 | String | 20160806151343349 | 订单支付时传入的商户订单号,商家自定义且保证商家系统中唯一 |
| 退款金额 | money | 是 | String | 1.50 | 少数通道需要与原订单金额一致 |
注:trade_no、out_trade_no 不能同时为空,如果都传了以trade_no为准
返回结果:
| 字段名 | 变量名 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|
| 返回状态码 | code | Int | 1 | 1为成功,其它值为失败 |
| 返回信息 | msg | String | 退款成功 |
SDK下载
SDK.zip
SDK版本:V1.4
包内含 PHP 示例(发起支付 / 异步通知 / 同步跳转 / 订单查询),下载后修改lib/epay.config.php中的域名、商户ID、商户密钥即可运行。
SDK 配置说明:
<?php //支付接口地址(请填写你的七七支付域名,以 / 结尾) $epay_config['apiurl'] = 'https://你的七七支付域名/'; //商户ID(请在七七支付商户后台获取) $epay_config['pid'] = '商户ID'; //商户密钥(请在七七支付商户后台获取) $epay_config['key'] = '商户密钥';