版权声明：本 Skill 内容来源于上海汇付支付有限公司官方开放平台文档，版权归属上海汇付支付有限公司。如有疑问可咨询汇付支付客服：400-820-2819 / cs@huifu.com

Source: Official Open Platform documentation of Shanghai Huifu Payment Co., Ltd.

Copyright: Shanghai Huifu Payment Co., Ltd.

聚合支付 - 下单（PHP 版）

覆盖微信/支付宝/银联全场景聚合支付下单，PHP SDK 适配。

适配版本与复核信息

PHP SDK 字段传参速查

SDK 初始化

⚠️ 必须使用官方 SDK，禁止裸 cURL 直接调用汇付 API。裸 cURL 会返回 HTTP 922（空响应），详见 aggregate-order-errors.md#http-922。

SDK 实际命名空间是 BsPaySdk，不是 Huifu\BsPay。SDK 需要手动 require_once init.php。

require_once 'vendor/autoload.php';
require_once 'vendor/huifurepo/dg-php-sdk/BsPaySdk/init.php';

use BsPaySdk\core\BsPay;
use BsPaySdk\core\BsPayClient;
use BsPaySdk\enums\FunctionCodeEnum;

// config.json 示例（注意键名是 rsa_merch_private_key / rsa_huifu_public_key）：
// {
//   "product_id": "YOUR_PRODUCT_ID",
//   "sys_id": "YOUR_SYS_ID",
//   "rsa_merch_private_key": "BASE64_PRIVATE_KEY",
//   "rsa_huifu_public_key": "BASE64_PUBLIC_KEY"
// }
BsPay::init('/path/to/huifu-config.json');

PHP SDK 调用基础模式

use BsPaySdk\core\BsPayClient;
use BsPaySdk\enums\FunctionCodeEnum;

$params = [
    "funcCode" => FunctionCodeEnum::$V4_TRADE_PAYMENT_CREATE,
    "params"   => [
        "req_date"      => date("Ymd"),
        "req_seq_id"    => date("YmdHis") . mt_rand(1000, 9999),
        "huifu_id"      => "YOUR_HUIFU_ID",
        "trade_type"    => "T_JSAPI",
        "trans_amt"     => "1.00",
        "goods_desc"    => "商品描述",
        "method_expand" => json_encode($methodExpand, JSON_UNESCAPED_UNICODE),
        "notify_url"    => "https://your-domain.com/notify",
    ]
];

$result = (new BsPayClient())->postRequest($params);

if (!$result || $result->isError()) {
    $errInfo = $result ? $result->getErrorInfo() : '网络异常';
    throw new \Exception("SDK error: " . print_r($errInfo, true));
}

$rspDatas = $result->getRspDatas();
$data = $rspDatas['data'] ?? [];
if ($data['resp_code'] !== '00000000' && $data['resp_code'] !== '00000100') {
    throw new \Exception("业务失败: [{$data['resp_code']}] " . $data['resp_desc']);
}

// 受理成功，以 trans_stat 为终态依据
$transStat = $data['trans_stat'] ?? 'P';  // P=处理中，S=成功，F=失败
$hfSeqId   = $data['hf_seq_id'] ?? '';

运行依赖与凭据边界

本 Skill 依赖 huifu-dougong-aggregation-base 提供公共运行时。凭据使用规则见基础 Skill。

前置依赖：首次接入请先阅读 huifu-dougong-aggregation-base/SKILL.md 完成 SDK 初始化。

开发前先补两步：先核对客户前置准备清单，再按参数校验与 JSON 构造规范建模。sub_openid、buyer_id、auth_code、devs_id、customer_ip 这些值都不能让模型自行猜测。

端到端支付流程

[1] 下单 (本 Skill)
  -> [2] 用户支付 (前端处理)
  -> [3] 异步通知 (回调 notify)
  -> [4] 查询确认 (二次校验)
  -> [5] 退款 (可选)

步骤 1：下单（本 Skill）

调用 v4/trade/payment/create 创建支付订单，根据 trade_type 返回不同结果：

• 正扫（NATIVE）：返回 qr_code（二维码 URL）
• JS 支付（JSAPI/MINIAPP）：返回 pay_info（JS 调起参数）
• 反扫（MICROPAY）：同步返回支付结果

同时保存 req_seq_id 和 req_date（后续所有操作都需要）。

步骤 2：用户支付

• 正扫：前端将 $data['qr_code'] 生成二维码展示，用户扫码支付
• JS 支付：前端使用 $data['pay_info'] 调起微信/支付宝/银联支付（pay_info 已是 JSON 字符串，直接传前端）
• 反扫：无需用户操作，商户扫描用户付款码后同步完成

步骤 3：接收异步通知

// notify.php
$rawBody = file_get_contents('php://input');
$notify  = json_decode($rawBody, true);
$respData = json_decode($notify['resp_data'] ?? '{}', true);

$hfSeqId  = $respData['hf_seq_id']  ?? '';
$transStat = $respData['trans_stat'] ?? '';
$transType = $respData['trans_type'] ?? ''; // 注意：异步字段名是 trans_type，不是 trade_type
$reqSeqId  = $respData['req_seq_id'] ?? '';

// 幂等处理
if (alreadyProcessed($hfSeqId)) {
    echo "RECV_ORD_ID_" . $reqSeqId;
    exit;
}

if ($transStat === 'S') {
    // 支付成功，更新订单状态
}

// 5 秒内必须返回
echo "RECV_ORD_ID_" . $reqSeqId;
exit;

场景路由

根据支付场景选择对应 trade_type：

汇付 API 端点

常见错误与排查

// PHP 错误处理示例
$respCode = $data['resp_code'] ?? '';
switch ($respCode) {
    case '00000000':
    case '00000100':
        // 受理成功，继续判断 trans_stat
        break;
    case '20000000':
        // 重复流水，换 req_seq_id 重试
        break;
    default:
        // 业务失败
        error_log("聚合下单失败: [{$respCode}] " . ($data['resp_desc'] ?? ''));
        break;
}

Reference 地图

版权声明：本 Skill 内容由开发者分享整理，基于上海汇付支付有限公司官方文档编写，版权归上海汇付支付有限公司所有。汇付天下斗拱校园交流群：https://paas.huifu.com/cms/details/m5SqYOn6n.html 欢迎加入！