# 托管支付客户前置准备清单

> 这份文档解决的问题不是“接口有哪些字段”，而是“这些字段的值从哪里来、客户在开发前必须先准备什么”。这里的“准备”不仅包括参数，还包括官方托管产品文档里明确写出的控台创建项目、授权绑定、费率开通、对账配置和回调地址约束。如果来源不明确，模型不应自行猜测参数值。

## 参数来源分类

| 来源类型 | 典型字段 | 说明 |
|---------|---------|------|
| 汇付平台固定配置 | `sys_id`、`product_id`、`huifu_id`、RSA 密钥 | 由汇付开放平台 / 控台分配 |
| 客户业务配置 | `project_id`、`project_title`、`fee_sign`、`acct_id` | 由客户业务或控台预先创建 |
| 前端 / 用户运行时数据 | `sub_openid`、`buyer_id`、`buyer_logon_id`、`callback_url` | 需要前端授权、页面上下文或用户侧输入 |
| 终端 / 设备采集数据 | `devs_id`、`payer_client_ip`、`front_url` | 需要设备报备、终端采集或外网地址 |
| 上游订单沉淀数据 | `req_date`、`req_seq_id`、`hf_seq_id`、`org_req_date`、`org_req_seq_id` | 下单成功后必须落库，供查询 / 关单 / 退款复用 |

## 全局必备配置

所有托管支付 skill 在开发前都要先确认以下配置已经拿到：

| 配置项 | 用途 | 没有会怎样 |
|-------|------|-----------|
| `sys_id` | 公共请求参数 | 请求无法签名落地 |
| `product_id` | 公共请求参数 | 汇付会直接报产品号相关错误 |
| `huifu_id` | 商户业务主体标识 | 业务请求无法定位商户 |
| RSA 私钥 / 公钥 | 请求签名、响应验签 | 请求或验签直接失败 |
| `notify_url` / `refund_notify_url` | 支付、退款异步回调 | 无法可靠接收最终结果 |
| 托管支付权限 / 对应费率 | 业务开通前提 | 官方产品文档明确要求先开通权限并配置费率，否则无法完成交易 |

## 官方产品文档确认的全局前置动作

- H5 / PC 收银台接入前，需在合作伙伴控台创建支付托管项目，并记录留存托管项目号；下单时 `hosting_data.project_id` 必须上送这个真实项目号。
- 收银台展示的支付方式必须先在项目里勾选，且商户已开通对应支付方式；未开通时控台里就无法选中。
- 多份托管产品文档都明确规定了 `notify_url` 的约束：
  - 必须是 `http` / `https` 地址
  - 不支持 HTTP 重定向
  - 自定义端口需在 `8000-9005`
  - URL 不要带查询参数
  - 商户收到回调后应返回状态码 `200`
- `callback_url` 只负责支付完成后的页面跳转，不代表支付成功；最终结果仍要依赖异步通知或主动查询。

## 统一收银台预下单前要准备什么

### H5 / PC 场景

| 字段 / 配置 | 来源 | 说明 |
|------------|------|------|
| `hosting_data.project_id` | 客户在合作伙伴控台项目管理里创建的半支付托管项目 | 必填，项目创建成功后需留存；模型无法猜测 |
| `hosting_data.project_title` | 客户业务侧定义 | 必填，用于账单展示 |
| `notify_url` | 客户服务端回调地址 | 需满足官方 URL 约束：公网可达、无重定向、无查询参数、端口合规 |
| `hosting_data.callback_url` | 客户前端页面地址 | 只负责支付后跳转，不代表交易成功 |
| `trans_type` | 客户确认要开放的支付方式 | 单值直达支付页，多值进入收银台；前提是该支付方式已在项目里启用 |
| `hosting_data.request_type` | 客户页面场景 | 指定 `trans_type` 时要同步确认是 `P` 还是 `M` |
| `fee_sign` | 客户已开通的手续费场景配置 | 未准备时不要伪造，直接走默认费率 |
| `acct_id` | 客户指定的收款账户号 | 只在特定账户收款场景使用 |
| 微信授权域名配置 | 微信支付场景的控台 / 微信侧配置 | 官方 H5 / PC 产品文档要求微信支付使用前先配置 `api.huifu.com/hostingH5/` |

### 微信小程序场景

| 字段 / 配置 | 来源 | 说明 |
|------------|------|------|
| `miniapp_data.need_scheme` | 客户端拉起方案 | 必填，决定是否生成 `scheme_code` |
| `miniapp_data.seq_id` | 小程序托管授权并绑定 appid 后生成的应用 ID | 官方文档明确要求先完成小程序授权、代码发布和应用管理绑定，再拿到应用 ID |
| `wx_data.sub_appid` | 微信侧应用配置 | 子商户应用 ID，不是模型可推导值 |
| `wx_data.sub_openid` | 前端登录或授权结果 | 公众号 / 小程序支付场景是关键运行时值 |
| `terminal_device_data.devs_id` | 汇付终端报备结果 | 报备机具交易场景必传 |
| `split_pay_flag` 对应权限 | 客户控台能力开通 | 未开通拆单支付权限时不要让模型默认开启 |
| 微信支付产品和费率 | 商户控台业务配置 | 官方文档明确要求事先开通微信支付产品并配置相应费率 |

### 支付宝小程序场景

| 字段 / 配置 | 来源 | 说明 |
|------------|------|------|
| `app_data.appid` / 小程序应用标识 | 支付宝开放平台配置 | 场景专属，模型不能猜 |
| 托管支付权限和支付宝费率 | 商户控台业务配置 | 官方产品文档要求先开通托管支付权限并配置对应费率 |
| `seller_id`、`store_id`、`alipay_store_id` | 支付宝 / 商户控台配置 | 直连或门店场景常见 |
| `sys_service_provider_id` | 系统商签约 PID | 没有明确来源不要补 |
| `terminal_device_data.devs_id` | 汇付终端报备结果 | 报备机具交易场景必传 |
| `biz_info.person_payer.cert_no` | 用户实名信息 + 加密结果 | 先拿原文，再按汇付公钥加密 |

## 查询 / 关单 / 退款前要沉淀什么

这些接口最常见的问题不是“不会写请求”，而是上游订单没把关键标识保存下来。

| 后续接口 | 开发前必须保证已保存 | 说明 |
|---------|------------------|------|
| 交易查询 | `req_date`、`req_seq_id`，或 `party_order_id` | 建议下单成功就持久化 |
| 交易关单 | `org_req_date`、`org_req_seq_id` | 关单必须基于原交易定位 |
| 退款申请 | `org_req_date`、`org_req_seq_id`、`hf_seq_id`、原商户单号中的至少一组 | 退款 skill 会直接复用 |
| 退款查询 | 退款请求自身的 `req_date`、`req_seq_id`，以及原退款定位信息 | 便于轮询和幂等 |
| 对账单查询 | 对账单功能开通状态、`file_date` 语义 | 官方对账文档要求先在控台配置对账文件生成；`sys_id`、`product_id` 可从开发者信息获取 |

## 权限 / 开通项检查

以下能力如果客户没有预先开通，模型把参数写全也会失败：

| 能力 | 典型影响字段 | 说明 |
|------|-------------|------|
| 对账单功能 | `file_date`、`bill_type` | 未开通就无法拉取对账文件 |
| 分账权限 | `acct_split_bunch` | 分账对象写全也会被拒 |
| 延迟入账权限 | `delay_acct_flag` | 未开通不要默认传 `Y` |
| 拆单支付权限 | `split_pay_flag` | 微信小程序拆单场景需预开通 |
| 退款权限 | 退款接口本身 | 不是所有商户默认有退款能力 |
| 设备报备 | `terminal_device_data.devs_id` | 报备终端场景必须来自正式报备结果 |
| 小程序托管授权与应用绑定 | `miniapp_data.seq_id` | 未授权、未发布、未绑定 appid 时无法拿到真实应用 ID |

## 向客户索取材料的最小清单

### 必需

- 汇付平台分配的 `sys_id`、`product_id`、`huifu_id`
- RSA 私钥、公钥
- 支付 / 退款异步通知地址
- 托管项目 `project_id`、`project_title`
- 前端支付场景清单：H5 / PC / 微信小程序 / 支付宝小程序

### 按场景补充

- H5 / PC：托管项目配置、已启用的支付方式、微信授权域名是否已配置
- 微信：`sub_appid`、`sub_openid`、是否需要 `scheme_code`、`seq_id` 来源
- 支付宝：`buyer_id`、`seller_id`、`store_id`、`sys_service_provider_id`
- 设备：`devs_id`
- 分账 / 延迟入账 / 手续费场景：`acct_split_bunch`、`delay_acct_flag`、`fee_sign`
- 实名 / 大额支付：原始证件号、银行卡号，以及加密链路

## 给模型的硬约束

- 没有明确来源的值不要猜，不要填“示例值”或伪造默认值。
- 官方文档要求通过控台创建或授权生成的值，例如 `project_id`、`seq_id`、启用中的支付方式、终端报备号，都不能由模型直接臆造。
- 如果客户只说“要支持某场景”，但没有给关键参数来源，先把参数列出来要求业务方补齐，而不是直接生成完整请求。
- `callback_url` 不是支付成功回调，不能据此更新订单终态；支付完成后仍应走异步通知或主动查询确认。
- 任何查询、关单、退款代码都要优先复用上游订单已保存的标识，不要在下游重新拼接或假设。