# 公共参数说明

## 公共请求参数

所有汇付 API 请求都包含以下公共参数（位于请求 JSON 的顶层）：

| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |
|------|-------|------|------|------|------|
| sys_id | 系统号 | String | 32 | Y | 渠道商/商户的 huifu_id。当主体为渠道商时填写渠道商 huifu_id；当主体为直连商户时填写商户 huifu_id。示例值：`6666000108854952` |
| product_id | 产品号 | String | 32 | Y | 汇付分配的产品号。示例值：`YYZY` |
| sign | 加签结果 | String | 512 | Y | 对报文整体签名，SDK 自动处理 |
| data | 请求数据 | JSON | - | Y | 业务请求参数，具体内容参见各接口文档 |

## 公共返回参数

所有汇付 API 返回都包含以下公共参数（位于返回 JSON 的顶层）：

| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |
|------|-------|------|------|------|------|
| sign | 签名 | String | 512 | Y | 对报文整体签名，SDK 自动验签 |
| data | 响应内容体 | JSON | - | N | 业务返回参数 |

## data 中的通用业务字段

| 参数 | 中文名 | 类型 | 说明 |
|------|-------|------|------|
| resp_code | 业务响应码 | String | 接口受理返回码，用于排查；订单终态仍看 `trans_stat`、`order_stat` 或查单结果 |
| resp_desc | 业务响应信息 | String | 响应描述文本 |
| req_date | 请求日期 | String | 格式 yyyyMMdd |
| req_seq_id | 请求流水号 | String | 同一 huifu_id 下当天唯一 |
| huifu_id | 商户号 | String | 开户自动生成 |

## 交易状态枚举

| 状态码 | 含义 | 建议处理方式 |
|-------|------|------------|
| P | 处理中 | **不可当作失败处理！** 应启动轮询（建议间隔 5 秒，最多 30 次 / 150 秒）调用查询接口，同时等待异步通知，以先到者为准 |
| S | 交易成功 | 执行业务成功逻辑（更新订单状态、发货等） |
| F | 交易失败 | 提示用户重新发起或联系客服，记录失败原因用于排查 |

> **trans_stat=P 处理要点**：
> 1. 前端展示"支付处理中"，**切勿提示"支付失败"**
> 2. 后端启动定时轮询：`GET /queryorderinfo`，间隔 5 秒，最多查询 30 次
> 3. 若 150 秒后仍为 P，记录异常日志并人工介入，**不要自动关单**
> 4. 异步通知到达后以通知结果为准，终止轮询

## 名词解释

> **sys_id 与 huifu_id 的区别**
>
> | 场景 | sys_id 填什么 | huifu_id 填什么 |
> |------|-------------|----------------|
> | 直连商户（自己发起交易） | 商户自己的 huifu_id | 商户自己的 huifu_id（两者**相同**） |
> | 渠道商代商户发起交易 | 渠道商的 huifu_id | 子商户的 huifu_id（两者**不同**） |
>
> 简记：`sys_id` = "谁在调 API"，`huifu_id` = "这笔交易属于谁"。直连商户场景下二者一致。

| 术语 | 说明 |
|------|------|
| huifu_id | 商户在汇付开户后获得的唯一标识 |
| sys_id | 系统号，即发起请求的主体标识（直连商户 = huifu_id，渠道商 = 渠道商自己的 huifu_id） |
| product_id | 产品号，汇付分配给商户的产品标识 |
| req_seq_id | 请求流水号，同一 huifu_id 下当天唯一，用于幂等和对账 |
| req_date | 请求日期，格式 yyyyMMdd |
| org_req_seq_id | 原交易请求流水号，查询/退款/关单时需要引用原始交易的流水号 |
| org_req_date | 原交易请求日期，查询/退款/关单时需要引用原始交易的日期 |
| hf_seq_id | 汇付全局流水号，汇付系统内部生成的唯一标识 |
| trans_stat | 交易状态，P=处理中、S=成功、F=失败 |
| notify_url | 异步通知地址，交易结果通过 HTTP POST 回调此地址 |
| hosting_data | 半支付托管扩展参数，JSON 字符串，包含项目信息和回调地址 |
| delay_acct_flag | 延迟入账标志，Y=延迟、N=不延迟 |
| terminal_device_data | 设备信息，JSON 字符串，退款时必填 |

## 标准字段与格式约束

- 参数命名统一使用下划线命名法，如 `trade_type`、`req_seq_id`。
- 枚举值优先使用数字或大写字母下划线风格，如 `T_JSAPI`、`ONLINE_PAY_B2B`。
- 交易金额单位统一为“元”，保留两位小数。
- 时间统一按北京时间（东八区）传递；如业务系统不在东八区，需先换算。
- 数值型字段在接口层尽量按字符串传输，避免精度和序列化歧义。

## 结算术语

| 术语 | 说明 |
|------|------|
| T1 自动结算 | 默认结算方式，前一工作日周期内余额结算到银行卡 |
| T1 主动取现 | 工作日发起取现，通常下一个工作日到账 |
| D1 自动结算 | 前一自然日余额结算到银行卡 |
| D1 主动取现 | 自然日发起取现，通常下一个自然日到账 |
| D0 取现 | 发起后通常 2 小时内到账 |
| DM 取现 | 不包含在途资金的快速取现方式 |

## 手续费术语

| 术语 | 说明 |
|------|------|
| 实时收取 | 默认模式，交易过程中按费率实时计算并收取 |
| 手续费内扣 | 从交易金额中扣收手续费，收款方实收金额会减少 |
| 手续费外扣 | 从指定主体及斗拱账户中额外扣收手续费，收款方保持全额收款 |

手续费规则补充：

- 交易手续费默认按四舍五入保留两位小数。
- 全额退款通常全额退还交易手续费。
- 部分退款时，退款手续费通常按“退款金额 × 原订单手续费 ÷ 原订单金额”向下取整计算，多次退款差额会并入最后一笔。