What makes 汇付支付集成 notable?

1.6K downloads. Trust evidence available

How should 汇付支付集成 be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

agentCLAWHUBUnverified

汇付支付集成

汇付支付/斗拱支付（Huifu Payment）交易接入与开发排障。用于支付 API/SDK、聚合支付、托管支付、收银台组件checkout-js、统一/H5/PC 收银台，以及微信、支付宝、银联、抖音、小程序、JSAPI、公众号、扫码、付款码、B2B/B2C 网银和快捷支付等场景；覆盖预下单/下单、查单、关单、退款、合单、拆单/分账交易、对账账单，以及异步通知和支付终态处理。支持 Java/PHP/Python SDK、完整请求与响应签名验签、请求头、幂等去重、重复回调/重复发货、查单补偿、错误码与通道排查、存量系统改造、沙箱联调、上线检查和生产问题脱敏升级等开发集成。

OpenClaw

View on ClawHub Homepage

Rank

Safety

Downloads

1.6k

Updated

Oct 10, 2026

Version

1.3.5

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 1.6K downloads reported by the source. Last updated 10/10/2026.

Avoid when

Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor: Clawhubvendor · observed Oct 10, 2026
Protocol compatibility: OpenClawcompatibility · observed Oct 10, 2026
Adoption signal: 1.6K downloadsadoption · observed Oct 10, 2026
Latest release: 1.3.5release · observed Aug 31, 2026
Handshake status: UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s17c2c78kmqx2n99rr99gg5qt584zrbn:huifu-pay-integration

Install using `clawhub skill install s17c2c78kmqx2n99rr99gg5qt584zrbn:huifu-pay-integration` in an isolated environment before connecting it to live workloads.
No published capability contract is available yet, so validate auth and request/response behavior manually.
Review the upstream CLAWHUB listing at https://clawhub.ai/huifu/huifu-pay-integration before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-huifu-huifu-pay-integration/snapshot"

Documentation

CLAWHUB

160,000 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: huifu-pay-integration
description: "汇付支付交易集成：用于聚合支付、托管支付、checkout-js、下单、查单、关单、退款、对账、支付通知、签名验签、请求头、幂等、交易终态、本地沙箱和支付上线；不用于企业/个人商户进件、图片上传、商户业务开通、商户详情或申请状态查询，这些任务使用 huifu-merchant-onboarding。"
---

# 汇付支付集成

## 版权声明

本 Skill 中的汇付支付资料整理自上海汇付支付有限公司官方开放平台与官方产品文档；原始文档及其更新维护权归汇付支付官方所有。仅作技术学习交流与接口集成辅助使用，详见 `references/shared-copyright-notice.md`。

## 执行流程

1. 识别产品线、Endpoint、接入阶段、技术栈、端形态、当前目标和是否存量系统。完成标准：这些维度均已唯一确定，极速版产品场景与 V4 API 枚举已分开。
2. 检查下方硬检查点；命中时停止生成可运行实现，只问一个最高优先级问题。完成标准：已记录命中或未命中的具体理由，SDK 传输安全和调试日志均已检查。
3. 从精确路由中选择 3–5 份 reference。只有用户同时提出两个独立目标时才合并；完整 DTO、响应或嵌套字段任务必须包含完整字段目录。完成标准：每个目标均有一跳可达的原子接口页、合同定位路径、实际 JSON/解码路径（分别记录 wire 字段路径与 String(JSON) 解码后路径）和明确语言 adapter，不使用“对应文档”占位，也不把官网展示分组当成 wire key；只有官网明确标注“方便文档展示”时才从 wire 路径移除该分组。
4. 首次接入输出产品线判断和方案卡；存量接入输出新增、保留、人工确认和回归检查。完成标准：请求、前端交接、通知、终态和补偿查询责任均已落到具体组件。
5. 最后应用签名、验签、幂等、终态确认、请求字段保留和凭据安全规则。完成标准：每项均已检查，未知合同明确标记并停止生成相应实现。

字段说明中的链接按其用途处理：完整字段目录已将官网 `#锚点` / 相对链接解析到各自接口原始页，并保留相对地址原文；绝对地址保持官网值。已确认的坏锚点使用显式映射：`#业务返回码` 补公共返回码全集，聚合下单 `notify_url` 的“异步返回参数”同时映射正扫、反扫通知参数和通用异步消息规范。只有命中本次字段的规范文档、编码表或渠道指引才作为外部资料提示。`notify_url`、`jump_url`、下载地址、二维码等裸 URL 示例是运行时值或格式示例，不是默认值、推荐地址或外部资料。

本 Skill 只处理支付交易。企业、个人商户进件、图片资料、业务开通、商户详情和申请状态使用 `$huifu-merchant-onboarding`；不要从本 Skill 读取进件实现文档。

## 精确路由

| 场景 | 最小 reference 集 |
| --- | --- |
| 首次接入、产品线不明 | `references/shared-overview.md`、`references/copilot-onboarding.md`、`references/copilot-solution-selection.md` |
| 存量系统接入 | `references/copilot-existing-system.md`、`references/copilot-solution-selection.md` |
| 聚合支付快速接入 | `references/aggregation-quickstart.md`、`references/aggregation-customer-preparation.md` |
| 聚合下单参数或代码 | `references/aggregation-order.md`、`references/payment-complete-field-catalog.md`，按语言选择 `references/aggregation-java-adapter.md`、`references/aggregation-php-adapter.md` 或 `references/aggregation-python-adapter.md`，再按 `trade_type` 补微信/支付宝/银联分册 |
| 聚合交易查询 | `references/aggregation-query-payment-query.md` |
| 返回码、公共编码或术语 | `aggregation-error-codes.md`、`aggregation-common-params.md`；具体字段仍补对应原子接口页 |
| 聚合关单 | `references/aggregation-query-trade-close.md` |
| 聚合对账 | `references/aggregation-query-reconciliation.md` |
| 聚合退款或退款查询 | `references/aggregation-refund.md`、`references/payment-complete-field-catalog.md`，查询时补 `references/aggregation-refund-query.md` |
| 托管支付快速接入 | `references/hostingpay-quickstart.md`、`references/hostingpay-customer-preparation.md` |
| 托管预下单 | `references/hostingpay-preorder.md`、`references/payment-complete-field-catalog.md`，再按端形态补一个原子文档 |
| 抖音直连、`pre_order_type=4` | `references/hostingpay-preorder.md`、`references/hostingpay-preorder-douyin-direct.md` |
| 拆单支付查询、`splitpay/query` | `references/hostingpay-query.md`、`references/hostingpay-query-splitpay.md`；完整 DTO 同时执行下方完整字段目录路由 |
| 交易分账明细、`trade/trans/split/query` | `references/trade-split-detail-query.md`、`references/payment-complete-field-catalog.md`；代码任务再补对应 Java/PHP/Python adapter |
| 托管退款 | `references/hostingpay-refund.md`；完整 DTO 同时执行下方完整字段目录路由，Java setter 问题补 `references/hosting

_meta.json

{
  "ownerId": "kn7as5mtmp7qjv21jr9n15qth182kat3",
  "slug": "huifu-pay-integration",
  "version": "1.3.5",
  "publishedAt": 1788166368148
}

references/aggregation-async-webhook.md

# 异步通知与 Webhook

> 本文面向 `references/aggregation-base.md` 依赖的聚合支付 Skill，重点把交易通知的真实报文形态、验签方式、幂等和终态判断说明清楚。


## 目录

- 两种异步机制
- `notify_url` 使用规范
- 聚合交易通知报文形态
- Spring Boot 接收、验签与查单示例
- 终态判断原则
- 签名差异
- Webhook 使用场景
- Webhook 落地步骤
- Webhook 重发规则
- 使用建议
- 参考

## 两种异步机制

| 机制 | 入口 | 用途 | 签名方式 |
|------|------|------|----------|
| `notify_url` | 下单、退款等接口请求参数 | 交易结果回调 | 汇付 RSA 公钥验签 |
| Webhook | 汇付控台端点订阅 | 平台事件通知 | 终端密钥 + MD5 原始事件体 |

## `notify_url` 使用规范

- 汇付以 HTTP `POST` 发送交易结果。
- 响应必须在 5 秒内返回。
- 正确应答格式为：HTTP `200` + `RECV_ORD_ID_` + `req_seq_id`。
- 未及时应答或应答格式不正确时，汇付会自动重试，最多 3 次。
- 自定义端口需落在 `8000-9005`。
- URL 不要带查询参数。
- 同一笔交易可能会重复通知，必须用 `hf_seq_id` 做幂等。

## 聚合交易通知报文形态

聚合支付的交易类异步通知，外层通常包含以下 4 个网关字段：

| 字段 | 说明 |
|------|------|
| `resp_code` | 网关返回码 |
| `resp_desc` | 网关返回信息 |
| `sign` | 对整个业务数据的签名 |
| `resp_data` | 业务数据 JSON 字符串 |

其中真正要驱动业务的字段在 `resp_data` 里，而不是直接平铺在最外层。

```json
{
  "resp_code": "10000",
  "resp_desc": "成功调用",
  "sign": "返回签名串",
  "resp_data": "{\"resp_code\":\"00000000\",\"resp_desc\":\"处理成功\",\"req_seq_id\":\"20240514163256046l9da4ecgqugo7h\",\"req_date\":\"20240514\",\"hf_seq_id\":\"00290TOP1A240514165442P385ac131b5d00000\",\"trans_type\":\"T_JSAPI\",\"trans_amt\":\"1.00\",\"trans_stat\":\"S\"}"
}
```

## Spring Boot 接收、验签与查单示例

```java
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
// Spring Boot 2.x: import javax.servlet.http.HttpServletRequest;
// Spring Boot 3.x: import jakarta.servlet.http.HttpServletRequest;
import java.util.Objects;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/notify")
public class AggregateNotifyController {

    private final String huifuPublicKey;
    private final AggregateQueryService queryService;
    private final NotifyIdempotentService idempotentService;

    public AggregateNotifyController(
            @Value("${huifu.rsa-public-key}") String huifuPublicKey,
            AggregateQueryService queryService,
            NotifyIdempotentService idempotentService) {
        this.huifuPublicKey = huifuPublicKey;
        this.queryService = queryService;
        this.idempotentService = idempotentService;
    }

    @PostMapping("/payment")
    public String onNotify(HttpServletRequest request) {
        String respData = request.getParameter("resp_data");
        String sign = request.getParameter("sign");
        if (!StringUtils.hasText(respData) || !StringUtils.hasText(sign)) {
            throw new IllegalArgumentException("汇付回调缺少 resp_data 或 sign");
        }
        if (!RsaUtils.verify(respData, huifuPublicKey, sign)) {
            throw new IllegalArgumentException("汇付回调验签失败");
        }

references/aggregation-base.md

# 聚合支付基础

这份文档负责聚合支付的初始化、公共参数、语言边界和接入前置判断。

## 什么时候读这里

- 第一次接聚合支付
- 需要确认 `trade_type`、公共环境变量、初始化顺序
- 需要判断当前应该走 Java、PHP 还是 Python

## 推荐阅读顺序

```text
shared-overview
  -> shared-signing-v2
  -> shared-request-header-policy
  -> aggregation-base
  -> aggregation-order / aggregation-query / aggregation-refund
```

## 当前版本口径

| 项目 | 当前值 |
| --- | --- |
| Java SDK | `dg-lightning-sdk 1.0.5` |
| PHP 覆盖范围 | 下单、扫码交易查询、关单、关单查询、退款、退款查询、对账 |
| `HUIFU_SKILL_SOURCE` 最终值 | `<skill_source>` |

## 必备环境变量

| 环境变量 | 用途 |
| --- | --- |
| `HUIFU_PRODUCT_ID` | 汇付分配的产品号 |
| `HUIFU_SYS_ID` | 渠道商 / 商户 `huifu_id` |
| `HUIFU_RSA_PRIVATE_KEY` | 请求签名私钥 |
| `HUIFU_RSA_PUBLIC_KEY` | 响应验签公钥 |
| `HUIFU_SKILL_SOURCE` | 可选来源覆盖项，请求头层按 `<skill_source>` 原样透传 |

## 初始化前确认事项

1. 先读 `references/shared-signing-v2.md`
2. 先读 `references/shared-async-notify.md`
3. 如果不是 Java，必须额外核对 `references/shared-request-header-policy.md`
4. 不要猜测 `sub_openid`、`buyer_id`、`auth_code`、`devs_id`、`fee_sign` 等运行时值

## 聚合支付主流程

```text
准备产品号和密钥
  -> 初始化 SDK 或 HTTP 客户端
  -> 选择 trade_type
  -> aggregation-order 下单
  -> aggregation-query 查单 / 关单 / 对账
  -> aggregation-refund 退款
```

## trade_type 速查

| trade_type | 说明 |
| --- | --- |
| `T_JSAPI` | 微信公众号支付 |
| `T_MINIAPP` | 微信小程序支付 |
| `T_APP` | 微信 APP 支付 |
| `T_MICROPAY` | 微信付款码反扫 |
| `A_JSAPI` | 支付宝 JS 支付 |
| `A_NATIVE` | 支付宝正扫 |
| `A_MICROPAY` | 支付宝付款码反扫 |
| `U_JSAPI` | 银联 JS 支付 |
| `U_NATIVE` | 银联正扫 |
| `U_MICROPAY` | 银联付款码反扫 |

## 语言边界

- Java 是聚合支付完整基线
- PHP 已覆盖聚合支付核心主链路与对账；默认入口先读 `references/aggregation-php-adapter.md` 与 `references/aggregation-query-php-scenarios.md`
- Python 已覆盖聚合支付核心主链路与对账；默认入口先读 `references/aggregation-python-adapter.md` 与 `references/aggregation-python-scenarios.md`
- 当前 Skill 包不再内置 PHP 模板资产；PHP 默认走官方 `huifurepo/dg-php-sdk`
- C#、Go 当前只保留统一入口说明，不提供现成业务模板

## 公共字段提醒

- `req_seq_id` 必须保证当日唯一
- `req_date` 建议始终保存，后续查询、关单、退款都要回用
- `method_expand`、`acct_split_bunch`、`terminal_device_data`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info` 应先建模再序列化；`tx_metadata` 本身不作为请求字段上送

## 下一步怎么走

- 要创建订单：读 `references/aggregation-order.md`
- 要查单 / 关单 / 对账：读 `references/aggregation-query.md`
- 要退款：读 `references/aggregation-refund.md`

references/aggregation-common-params.md

# 公共参数说明

官方公共资料入口：

- [基础参数汇总](https://paas.huifu.com/partners/api/doc/csfl/api_csfl.md)：地区、银行、支行、MCC、交易类型、文件类型等公共编码/枚举的入口。
- [名词解释](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_mcjs.md)：ATU、H5、结算周期、手续费等术语口径。
- [返回码](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_ywm.md)：网关与业务返回码全集。

这些页面是公共字典和术语来源，不覆盖具体接口页对字段必填、条件、类型和层级的定义；发生差异时保留两边证据并按具体接口合同处理。


## 目录

- 公共请求参数
- 公共返回参数
- 业务数据通用字段
- 交易状态枚举（trans_stat）
- 金额格式
- 日期时间格式
- 流水号规则
- 支付类型详解
- 标准字段与格式约束
- 结算术语
- 手续费术语

## 公共请求参数

所有聚合支付 API 请求的外层参数：

| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |
|------|-------|------|------|------|------|
| sys_id | 系统号 | String | 32 | Y | 渠道商/代理商/商户的 huifu_id |
| product_id | 产品号 | String | 32 | Y | 汇付分配的产品号，如 `MYPAY`、`YYZY` |
| sign | 加签结果 | String | 512 | Y | SDK 自动生成，无需手动处理 |
| data | 请求数据 | JSON | - | Y | 业务请求参数 |

> 强制请求头约束：
> - 必须带 `jpt-x-skill-source: <skill_source>`
> - 如果当前按 PHP 接入，且接口业务报文里存在 `huifu_id`，还必须带 `jpt-x-skill-huifu_id: <data.huifu_id>`
> - 当前 Skill 包对齐的官方 PHP SDK 主链路在 `MerConfig.skill_source` 已配置时，会自动带 `jpt-x-skill-source`，并在当前请求 `huifu_id` 存在且非空时自动带 `jpt-x-skill-huifu_id`
> - 当前 Java SDK 基线也会在接口业务报文里 `huifu_id` 存在且非空时自动带 `jpt-x-skill-huifu_id: <data.huifu_id>`
> - 这两项属于 HTTP 请求头，不属于 `data` 字段本身；完整口径见 `references/shared-request-header-policy.md`

### sys_id 说明

| 主体类型 | sys_id 填写 |
|---------|-----------|
| 渠道商/代理商 | 渠道商/代理商的 huifu_id |
| 直连商户 | 商户自身的 huifu_id |

> **sys_id vs huifu_id**：`sys_id` 是外层公共参数，标识调用方身份；`huifu_id` 是 `data` 内业务参数，标识交易商户。渠道商模式下两者不同，直连商户模式下两者相同。

## 公共返回参数

| 参数 | 中文名 | 类型 | 长度 | 说明 |
|------|-------|------|------|------|
| sign | 签名 | String | 512 | SDK 自动验证 |
| data | 响应内容体 | JSON | - | 业务返回参数 |

## 业务数据通用字段

以下字段在多数业务接口的 `data` 中出现：

| 参数 | 中文名 | 类型 | 说明 |
|------|-------|------|------|
| resp_code | 业务响应码 | String(8) | 接口受理返回码，用于排查；订单终态仍看 `trans_stat` 和查单结果 |
| resp_desc | 业务响应信息 | String(512) | 响应描述 |
| huifu_id | 商户号 | String(32) | 商户 huifu_id |
| req_date | 请求日期 | String(8) | 格式 yyyyMMdd |
| req_seq_id | 请求流水号 | String(128) | 同一 huifu_id 下当天唯一 |
| hf_seq_id | 汇付全局流水号 | String(128) | 汇付生成的全局唯一标识 |

## 交易状态枚举（trans_stat）

| 值 | 含义 | 处理方式 |
|---|------|---------|
| I | 初始 | 罕见状态，联系汇付技术人员 |
| P | 处理中 | 等待异步通知或轮询查询接口 |
| S | 成功 | 交易完成 |
| F | 失败 | 交易失败，可重新发起 |

## 金额格式

- **单位**：元（CNY）
- **精度**：保留两位小数
- **最小值**：0.01
- **示例**：`"1.00"`、`"100.50"`、`"0.01"`

## 日期时间格式

| 格式 | 说明 | 示例 |
|------|------|------|
| yyyyMMdd | 日期 | `20250320` |
| yyyyMMddHHmmss | 日期时间（14位） | `20250320143000` |
| HHmmss | 时间（6位） | `143000` |

## 流水号规则

| 字段 | 规则 | 说明 |
|------|------|------|
| req_seq_id | 同一 huifu_id 下当天唯一 | 商户自行生成 |
| hf_seq_id | 全局唯一 | 汇付返回，用于查询/退款 |
| org_req_seq_id | 原交易的 req_seq_id | 用于关联原交易 |
| org_hf_seq_id | 原交易的 hf_seq_id | 可替代 org_req_seq_id |

## 支付类型详解

### 正扫 vs 反扫

| 类型 | 说明 | 适用 trade_type |
|------|------|----------------|
| 正扫 (NATIVE) | 商户生成二维码，用户扫码支付 | A_NATIVE、U_NATIVE |
| 反扫 (MICROPAY) | 用户出示付款码，商户扫码收款 | T_M

Github ReposUpdated 15h agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW

Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.