API开发文档

版本：v2.0 | 最后更新：2026-06-20

欢迎使用 支付网关 支付服务。本文档面向商户技术开发人员，详细说明支付接口的调用方式、参数规范及签名机制。请在使用前仔细阅读，确保对接顺利。

一、接口概述

本系统提供标准HTTP API，商户可通过简单的请求快速发起支付。目前支持的支付方式：

支付宝当面付（扫码）聚合支付 - 微信（扫码）

1.1 接口一览

接口名称	请求方式	接口地址	说明
API支付接口	POST	`https://api.hofp.cn/api/pay.html`	发起支付，返回支付链接或二维码内容
订单查询接口	GET	`https://api.hofp.cn/api/query.html`	查询订单支付状态
异步通知回调	POST	`(商户提供 notify_url)`	支付成功后平台主动通知商户系统

1.2 基本流程

商户系统按签名规则构建请求参数，POST提交至API支付接口。
接口返回 pay_url（跳转链接）或 code_url（二维码内容）。
若为跳转链接，用户访问链接完成支付；若为二维码，展示二维码供用户扫码。
用户支付成功后，平台异步通知商户 notify_url（POST方式）。
商户收到通知后，更新订单状态，并返回 success 字符串（不返回其他内容）。
用户支付成功后同步跳转至商户 return_url（带查询参数）。

1.3 商户密钥获取

登录商户中心 → API安全，查看您的 AppID（商户ID） 和 AppSecret（商户密钥）。请妥善保管，切勿泄露。免费注册商户

二、鉴权方式

所有API请求均通过 MD5签名 进行身份验证。商户需使用 AppSecret 对请求参数计算签名，平台收到请求后会重新计算并比对，以确保请求的合法性和完整性。

三、签名算法

核心规则：所有请求参数（不包括 sign 本身）按照参数名 ASCII 码升序排序，拼接为 key=value&key2=value2 格式，然后在末尾直接拼接商户密钥（AppSecret），计算 32位小写MD5 作为签名。

3.1 签名步骤

将请求参数中除去 sign 以外的所有参数，按参数名 ASCII 码升序排序。
将排序后的参数拼接成 key=value&key2=value2 格式（不对 value 进行 URL 编码）。
在拼接后的字符串末尾直接拼接商户密钥 AppSecret（不需要加 & 或 key=）。
计算拼接后字符串的 MD5 哈希值（32位小写字母），即为签名。

3.2 签名示例

PHP

$params = [
    'app_id'       => '202604080001',
    'type'         => 'alipay_face',
    'out_trade_no' => 'ORDER20260408001',
    'money'        => '0.01',
    'name'         => '测试商品',
    'return_url'   => 'https://yourdomain.com/return',
    'notify_url'   => 'https://yourdomain.com/notify'
];

// 1. 按键名升序排序
ksort($params);

// 2. 拼接字符串
$str = '';
foreach ($params as $k => $v) {
    if ($v !== '' && $v !== null) {
        $str .= $k . '=' . $v . '&';
    }
}
$str = rtrim($str, '&');   // 去掉末尾多余的 &

// 3. 拼接商户密钥
$signStr = $str . $app_secret;

// 4. 计算MD5
$sign = md5($signStr);

四、API支付接口

POST https://api.hofp.cn/api/pay.html

发起支付请求，成功返回支付链接或二维码内容。

4.1 请求参数

参数名	必填	类型	示例值	说明
`app_id`	是	String	202604080001	商户AppID，在商户中心获取
`type`	是	String	`alipay_face` / `zpay_channel`	支付渠道类型。 • `alipay_face`：支付宝当面付（扫码支付） • `zpay_channel`：聚合支付（上游类型由平台配置，商户无需关心）
`out_trade_no`	是	String	ORDER20260408001	商户系统内部订单号，必须唯一
`money`	是	String	0.01	支付金额，单位：元，精确到小数点后两位
`name`	是	String	测试商品	商品名称/订单标题
`return_url`	是	String	https://yourdomain.com/return	支付成功后页面跳转地址（用户浏览器同步跳转）
`notify_url`	是	String	https://yourdomain.com/notify	异步通知地址（服务器后台接收支付结果）
`sign`	是	String	a1b2c3...	签名值，按签名算法生成

4.2 响应参数

参数名	类型	示例值	说明
`code`	Int	0	0=成功，1=失败（或错误码）
`msg`	String	success	返回信息
`pay_url`	String	https://...	支付链接（用于跳转支付），成功时可能返回此字段。
`code_url`	String	https://...	二维码内容（用于扫码支付），成功时可能返回此字段。

说明： 响应中最多只会返回 pay_url 或 code_url 之一，具体取决于渠道配置。商户可根据返回结果决定是跳转还是展示二维码。

4.3 请求示例（支付宝当面付）

PHP

$params = [
    'app_id'       => '202604080001',
    'type'         => 'alipay_face',
    'out_trade_no' => 'ORDER' . time(),
    'money'        => '0.01',
    'name'         => '测试商品',
    'return_url'   => 'https://yourdomain.com/return',
    'notify_url'   => 'https://yourdomain.com/notify',
];

ksort($params);
$str = '';
foreach ($params as $k => $v) {
    $str .= $k . '=' . $v . '&';
}
$str = rtrim($str, '&');
$params['sign'] = md5($str . '你的AppSecret');

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.hofp.cn/api/pay.html');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$response = curl_exec($ch);
$result = json_decode($response, true);
if ($result['code'] == 0) {
    if (!empty($result['code_url'])) {
        // 扫码支付：展示二维码
        echo '<img src="https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=' . urlencode($result['code_url']) . '">';
    } elseif (!empty($result['pay_url'])) {
        // 跳转支付：重定向
        header('Location: ' . $result['pay_url']);
    }
} else {
    echo '支付失败：' . $result['msg'];
}

五、订单查询接口

GET https://api.hofp.cn/api/query.html

根据商户订单号查询支付状态。

5.1 请求参数

参数名	必填	类型	示例值	说明
`app_id`	是	String	202604080001	商户AppID
`out_trade_no`	是	String	ORDER20260408001	商户订单号
`sign`	是	String	a1b2c3...	签名值（参数仅包含 app_id 和 out_trade_no）

5.2 响应参数

参数名	类型	示例值	说明
`code`	Int	0	0=成功，1=失败
`out_trade_no`	String	ORDER20260408001	商户订单号
`status`	Int	1	0=待支付，1=支付成功，2=支付失败
`status_text`	String	支付成功	状态文字描述
`amount`	Float	0.01	支付金额
`paid_at`	String	2026-04-23 10:30:00	支付完成时间（未支付时为空）

六、异步通知

重要：支付成功后，平台会以 POST 方式向商户 notify_url 发送支付结果通知。
商户收到通知后，应验证订单状态（可通过查询接口或本地数据库），确认金额与订单号无误后，返回纯文本 success（不要附带其他任何字符或HTML）。
若返回非 success 或超时，平台会重发通知（共5次，间隔递增）。
⚠️ 特别注意：请勿将 notify_url 设置为支付网关的地址（如 https://api.hofp.cn/api/notify.php），必须设置为商户自己的异步通知脚本地址。

6.1 通知参数

参数名	类型	说明
`out_trade_no`	String	商户订单号
`platform_trade_no`	String	平台交易流水号
`amount`	Float	支付金额
`status`	String	`success` 表示支付成功

6.2 验签说明

由于通知参数中不包含签名，商户无法直接验签。推荐以下安全措施：

根据 out_trade_no 查询本地订单或调用查询接口确认订单状态和金额。
仅当订单状态为待支付且金额匹配时，更新为已支付。
处理完成后务必返回字符串 success，否则平台会重复通知。

6.3 通知接收示例（PHP）

PHP

$out_trade_no = $_POST['out_trade_no'] ?? '';
$platform_trade_no = $_POST['platform_trade_no'] ?? '';
$amount = $_POST['amount'] ?? 0;
$status = $_POST['status'] ?? '';

if ($status !== 'success') {
    echo 'fail'; exit;
}

// 根据订单号查询本地订单（示例）
$order = $db->query("SELECT * FROM orders WHERE out_trade_no = '$out_trade_no'")->fetch();
if (!$order || $order['status'] == 1) {
    echo 'success'; exit; // 已处理过
}
if (abs($order['amount'] - $amount) > 0.01) {
    echo 'fail'; exit; // 金额不匹配
}

// 更新订单状态为已支付
$db->exec("UPDATE orders SET status = 1, paid_at = NOW() WHERE out_trade_no = '$out_trade_no'");

echo 'success'; // 必须返回 success，不要有其他输出

七、同步跳转

用户支付成功后，浏览器会自动跳转到商户的 return_url，附带以下查询参数：

参数名	说明
`out_trade_no`	商户订单号
`status`	`success` 或 `fail`

同步跳转仅用于页面提示，不能作为支付成功的最终依据，请务必以异步通知为准。

PHP

$out_trade_no = $_GET['out_trade_no'] ?? '';
$status = $_GET['status'] ?? '';
if ($status === 'success') {
    echo '支付成功，订单号：' . $out_trade_no;
} else {
    echo '支付失败';
}

八、完整代码示例（PHP）

PHP

<?php
$app_id = '你的AppID';
$app_secret = '你的AppSecret';
$notify_url = 'https://yourdomain.com/notify.php';
$return_url = 'https://yourdomain.com/return.php';

$params = [
    'app_id'       => $app_id,
    'type'         => 'alipay_face',   // 或 zpay_channel
    'out_trade_no' => 'ORDER' . date('YmdHis') . rand(1000, 9999),
    'money'        => '0.01',
    'name'         => '测试商品',
    'return_url'   => $return_url,
    'notify_url'   => $notify_url,
];

ksort($params);
$str = '';
foreach ($params as $k => $v) {
    $str .= $k . '=' . $v . '&';
}
$str = rtrim($str, '&');
$params['sign'] = md5($str . $app_secret);

$ch = curl_init('https://api.hofp.cn/api/pay.html');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

if ($result['code'] == 0) {
    if (!empty($result['code_url'])) {
        // 生成并展示二维码
        echo '<img src="https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=' . urlencode($result['code_url']) . '">';
    } elseif (!empty($result['pay_url'])) {
        header('Location: ' . $result['pay_url']);
    }
} else {
    echo '支付失败：' . $result['msg'];
}
?>

九、常见问题

请按以下步骤排查：
1. 参数名是否按 ASCII 升序排列；
2. 签名时是否剔除了 sign 参数；
3. 拼接字符串末尾是否有多余的 &；
4. 拼接后是否直接追加 AppSecret（无任何符号）；
5. 计算出的 MD5 是否为32位小写；
6. 参数值是否包含不可见字符或空格。

type 参数填写 alipay_face（支付宝当面付）或 zpay_channel（聚合支付）。聚合支付的上游类型（支付宝/微信、扫码/跳转）由平台在后台配置，商户无需额外参数。

接口会返回 {"code":1,"msg":"订单号已存在"}。请确保每次请求的 out_trade_no 唯一。

支付宝当面付返回 code_url，您可以使用任何二维码生成库将其转为图片（如 https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=...）。聚合支付如果配置为扫码模式，同样返回 code_url。

请确保您的 notify_url 外网可访问（不能是 localhost 或内网IP），并且服务器未拦截 POST 请求。平台会自动重试最多5次，您也可以主动调用查询接口核实订单状态。

平台后台可配置聚合支付的上游为支付宝或微信，并选择支付模式（跳转或扫码）。您不需要在 API 请求中指定，直接使用 type=zpay_channel 即可。

免费获取商户密钥在线测试支付

文档目录