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

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

Copyright: Shanghai Huifu Payment Co., Ltd.

聚合支付 - 下单

覆盖微信/支付宝/银联全场景聚合支付下单。

适配版本与复核信息

运行依赖与凭据边界

本 Skill 依赖 huifu-dougong-aggregation-base 提供公共运行时。凭据使用规则与存放边界见 credential-boundary.md。

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

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

官方开发指引补充约束：接入前还要完成渠道业务开通、应用配置或授权绑定。微信公众号 / 小程序场景的 sub_openid、支付宝 JS 的 buyer_id、银联 JS 的 user_id、各类反扫的 auth_code，都必须来自真实获取链路；前端支付完成回调也不等于最终交易成功。

协议规则入口

真正跨语言共用的协议规则，统一看共享资料：

• signing-v2.md
• async-notify.md

语言适配入口

这份 Skill 里的 trade_type、参数表、返回字段和状态说明，都是语言无关的。
具体语言怎么初始化和发请求，先看这里：

• huifu-dougong-aggregation-base/SKILL.md
• server-sdk-matrix.md

端到端支付流程

[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：用户支付

• 正扫：前端将 qr_code 生成二维码展示，用户扫码支付
• JS 支付：前端使用 pay_info 调起微信/支付宝/银联支付；pay_info 是语言无关的返回结果，Java SDK 只是其中一种接法
• 反扫：无需用户操作，商户扫描用户付款码后同步完成

步骤 3：接收异步通知

汇付将交易结果 POST 到 notify_url：

• 返回 RECV_ORD_ID_ + req_seq_id（5 秒内）
• 以 hf_seq_id 为幂等键
• 详见 tech-spec.md

步骤 4：二次查询确认

见 huifu-dougong-aggregation-query。官方微信 / 支付宝 / 银联开发指引都明确要求：用户前端页面收到支付完成回调后，后端仍需调用查询订单 API 确认最终状态。

步骤 5：退款（可选）

见 huifu-dougong-aggregation-refund

触发词

• "聚合支付下单"、"创建支付订单"、"发起支付"
• "微信支付下单"、"微信公众号支付"、"微信小程序支付"
• "支付宝下单"、"支付宝JS支付"、"支付宝正扫"
• "银联下单"、"银联JS"、"银联正扫"
• "付款码支付"、"反扫支付"、"扫码支付"
• "二维码支付"、"正扫支付"

场景路由

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

官方场景前置条件

汇付 API 端点

通用架构

接口层
  +- 接收业务系统的下单请求
  +- 校验交易金额、支付类型、通知地址和渠道特有参数

业务逻辑层
  +- 根据 trade_type 选择具体支付场景
  +- 组装聚合支付报文
  +- 调用对应语言 SDK 或 HTTP 客户端发起 `v4/trade/payment/create`
  +- 保存 req_seq_id / req_date / hf_seq_id 供查单和退款复用

请求对象
  |- huifu_id
  |- req_seq_id
  |- trade_type
  |- trans_amt
  |- goods_desc
  +- method_expand / acct_split_bunch / terminal_device_data / combinedpay_data / combinedpay_data_fee_info / trans_fee_allowance_info / tx_metadata 等扩展字段

下面出现的 SDK Request 类和包路径，是 Java 适配层的写法。
如果你不是 Java 项目，参数结构仍按本 Skill 的协议字段来实现。

通用请求参数

通用同步返回参数

重要：调用成功后务必保存 req_seq_id 和 req_date，后续查询、退款、关单均需使用。

method_expand 各场景必填字段

SDK Request 类

常见错误与排查

网络/系统错误：未收到响应或超时时，调用查询接口确认状态，切勿直接判定为失败。

Reference 地图

版权声明与联系方式见 copyright-notice.md