{"id":"075fdc19-87d1-439f-a151-889835a0d37a","entityType":"agent","slug":"clawhub-huifu-huifu-pay-integration","name":"汇付支付集成","canonicalUrl":"https://www.xpersona.co/agent/clawhub-huifu-huifu-pay-integration","canonicalPath":"/agent/clawhub-huifu-huifu-pay-integration","generatedAt":"2026-10-10T10:45:02.400Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T06:04:52.994Z","emptyReason":null},"description":"汇付支付/斗拱支付（Huifu Payment）交易接入与开发排障。用于支付 API/SDK、聚合支付、托管支付、收银台组件checkout-js、统一/H5/PC 收银台，以及微信、支付宝、银联、抖音、小程序、JSAPI、公众号、扫码、付款码、B2B/B2C 网银和快捷支付等场景；覆盖预下单/下单、查单、关单、退款、合单、拆单/分账交易、对账账单，以及异步通知和支付终态处理。支持 Java/PHP/Python SDK、完整请求与响应 签名验签、请求头、幂等去重、重复回调/重复发货、查单补偿、错误码与通道排查、存量系统改造、沙箱联调、上线检查和生产问题脱敏升级等开发集成。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.6K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17c2c78kmqx2n99rr99gg5qt584zrbn:huifu-pay-integration","sourceUrl":"https://clawhub.ai/huifu/huifu-pay-integration","homepage":"https://clawhub.ai/huifu/skills/huifu-pay-integration","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/huifu/huifu-pay-integration","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/huifu/skills/huifu-pay-integration","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"汇付支付集成 technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T06:04:52.994Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T06:04:52.994Z","emptyReason":null},"stars":null,"forks":null,"downloads":1632,"packageName":null,"latestVersion":"1.3.5","tractionLabel":"1.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T06:04:52.993Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T06:04:52.994Z","lastCrawledAt":"2026-10-10T06:04:52.993Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T06:04:52.993Z","lastVerifiedAt":null,"highlights":[{"version":"1.3.5","createdAt":"2026-08-31T08:52:48.148Z","changelog":"- 新增对交易分账明细（trade/trans/split/query）接口的完整 reference 路由 (`references/trade-split-detail-query.md`) - 删除老版 skill 卡片文档（skill-card.md），以精确化 reference 路由与文档结构 - 路由表增加“交易分账明细”场景，明确代码任务的适配器要求 - `skill_source` 策略及当前版本号按 1.3.5 规范更新","fileCount":106,"zipByteSize":423065},{"version":"1.3.4","createdAt":"2026-08-17T13:23:19.283Z","changelog":"huifu-pay-integration 1.3.4 - 移除 skill-card.md 文件。 - 更新 Skill 版本描述与兼容的 huifu-merchant-onboarding 版本号。 - 明确官方 SDK-only 传输与校验规则，不再因历史 TLS 猜测对 Java/PHP 触发硬停。 - 精简硬停条件，去除针对 Java/PHP TLS 测试的相关项。 - 其余执行流程与精确路由、输出要求保持不变。","fileCount":105,"zipByteSize":419199},{"version":"1.3.3","createdAt":"2026-07-31T13:05:43.171Z","changelog":"**1.3.3 is a major change, moving merchant onboarding to a separate skill and focusing this skill on transaction integration only.** - 进件相关文档（包括商户进件、图片上传、业务开通、详情、申请状态等）已完全移除；上述任务统一交由 huifu-merchant-onboarding skill 负责。 - 新增聚合及托管支付、交易、退款、通知、签名验签、本地沙箱等支付集成 reference 文档。 - SKILL.md 全面重写：明确声明本 skill 仅处理“支付交易”；精简路由、能力描述和执行流程，给出严格的边界和路由表，移除进件相关介绍。 - 精确路由和硬检查点当前仅覆盖支付相关场景，具体进件、开通、审核路径改为提示交由 merchant-onboarding。 - 清晰标注 references 用法与合并原则、请求/安全/验签/幂等边界及升级规范。","fileCount":105,"zipByteSize":419672},{"version":"1.3.2","createdAt":"2026-07-17T12:58:54.800Z","changelog":"huifu-pay-integration v1.3.2 - 新增商户进件相关 reference，包括企业、个体无执照、图片上传、业务开通、状态查询、详细信息等文档。 - 路由表与精确场景分流支持商户进件链路，覆盖基础资料、业务开通、进件状态、字段合同、三语言 SDK 差异、日志安全等多场景。 - 进件字段及业务开通请求参数严格按字段合同核对类型、长度、必填与约束，并新增进件自检规则。 - 精简 skill-card.md，全面移除，替换为结构化路由和指引。 - 本轮只读取当前场景涉及的3-5份 reference，其余按路由裁剪“暂不读取”。","fileCount":113,"zipByteSize":415391},{"version":"1.3.1","createdAt":"2026-07-04T01:45:03.992Z","changelog":"huifu-pay-integration 1.3.1 - 新增本地沙箱（local-sandbox）支持及文档入口，便于本地协议模拟、闭环演练和自检报告。 - 更新“什么时候使用”与快速路由，支持本地沙箱演练、报告校验和故障注入场景。 - 路由表、决策流程中增加本地沙箱相关文档筛选和优先级处理逻辑。 - 移除 skill-card.md；新增 references/shared-local-sandbox.md。 - 其他功能、既有接口和主流程不变。","fileCount":105,"zipByteSize":314039},{"version":"1.3.0","createdAt":"2026-06-12T09:48:56.936Z","changelog":"**huifu-pay-integration v1.2.3** - 提升为“汇付支付接入副驾驶”，支持首次接入、存量改造、调试、排查、上线全阶段。 - 新增 13 个 reference 文档，包括回归 prompts、现有系统集成、上线校验、参数/方案卡、常见问题、FAQ、官方参考、版本升级策略等。 - 加强存量系统判断、FAQ 路由、排查与升级场景。 - 移除旧 skill-card.md。 - 默认只推荐场景必需的 3-5 本地 references，细化快速路由表与硬/软检查点机制。","fileCount":104,"zipByteSize":304718},{"version":"1.2.2","createdAt":"2026-05-29T12:51:09.821Z","changelog":"- 新增 Python 技术栈支持，覆盖聚合支付与托管支付接入说明与场景案例：aggregation-python-adapter.md、aggregation-python-scenarios.md、hostingpay-python-adapter.md、hostingpay-python-scenarios.md - 增加 Python 环境变量示例文件：python.env.prod.example - 新增服务端请求字段保留原则说明：shared-request-field-preservation.md - SKILL.md 主描述补充 Python 相关的产品接入、SDK、落地裁决规则与能力边界 - 用户路由树与决策流程明确纳入 Python 场景与模板规则 - 升级硬检查点机制，置 Go、Rust、Node、.NET、Ruby、Kotlin、Scala、Swift、C++ 为当前未覆盖技术栈","fileCount":91,"zipByteSize":255873},{"version":"1.2.1","createdAt":"2026-05-08T07:39:43.296Z","changelog":"huifu-pay-integration 1.2.1 Changelog - 项目英文名从 huifu-payment-integration 标准化为 huifu-pay-integration，统一命名风格。 - 其他内容结构与描述保持不变，无功能或文档更新，仅为名称校正。","fileCount":86,"zipByteSize":233528}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17c2c78kmqx2n99rr99gg5qt584zrbn:huifu-pay-integration","setupComplexity":"low","setupSteps":["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":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huifu-huifu-pay-integration/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huifu-huifu-pay-integration/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huifu-huifu-pay-integration/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-huifu-huifu-pay-integration/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-huifu-huifu-pay-integration/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-huifu-huifu-pay-integration/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T10:45:02.396Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huifu-huifu-pay-integration/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huifu-huifu-pay-integration/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huifu-huifu-pay-integration/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huifu-huifu-pay-integration/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T06:04:52.994Z","emptyReason":null},"readme":"Skill: 汇付支付集成\n\nOwner: huifu\n\nSummary: 汇付支付/斗拱支付（Huifu Payment）交易接入与开发排障。用于支付 API/SDK、聚合支付、托管支付、收银台组件checkout-js、统一/H5/PC 收银台，以及微信、支付宝、银联、抖音、小程序、JSAPI、公众号、扫码、付款码、B2B/B2C 网银和快捷支付等场景；覆盖预下单/下单、查单、关单、退款、合单、拆单/分账交易、对账账单，以及异步通知和支付终态处理。支持 Java/PHP/Python SDK、完整请求与响应 签名验签、请求头、幂等去重、重复回调/重复发货、查单补偿、错误码与通道排查、存量系统改造、沙箱联调、上线检查和生产问题脱敏升级等开发集成。\n\nTags: latest:1.3.5\n\nVersion history:\n\nv1.3.5 | 2026-08-31T08:52:48.148Z | user\n\n- 新增对交易分账明细（trade/trans/split/query）接口的完整 reference 路由 (`references/trade-split-detail-query.md`)\n- 删除老版 skill 卡片文档（skill-card.md），以精确化 reference 路由与文档结构\n- 路由表增加“交易分账明细”场景，明确代码任务的适配器要求\n- `skill_source` 策略及当前版本号按 1.3.5 规范更新\n\nv1.3.4 | 2026-08-17T13:23:19.283Z | user\n\nhuifu-pay-integration 1.3.4\n\n- 移除 skill-card.md 文件。\n- 更新 Skill 版本描述与兼容的 huifu-merchant-onboarding 版本号。\n- 明确官方 SDK-only 传输与校验规则，不再因历史 TLS 猜测对 Java/PHP 触发硬停。\n- 精简硬停条件，去除针对 Java/PHP TLS 测试的相关项。\n- 其余执行流程与精确路由、输出要求保持不变。\n\nv1.3.3 | 2026-07-31T13:05:43.171Z | user\n\n**1.3.3 is a major change, moving merchant onboarding to a separate skill and focusing this skill on transaction integration only.**\n\n- 进件相关文档（包括商户进件、图片上传、业务开通、详情、申请状态等）已完全移除；上述任务统一交由 huifu-merchant-onboarding skill 负责。\n- 新增聚合及托管支付、交易、退款、通知、签名验签、本地沙箱等支付集成 reference 文档。\n- SKILL.md 全面重写：明确声明本 skill 仅处理“支付交易”；精简路由、能力描述和执行流程，给出严格的边界和路由表，移除进件相关介绍。\n- 精确路由和硬检查点当前仅覆盖支付相关场景，具体进件、开通、审核路径改为提示交由 merchant-onboarding。\n- 清晰标注 references 用法与合并原则、请求/安全/验签/幂等边界及升级规范。\n\nv1.3.2 | 2026-07-17T12:58:54.800Z | user\n\nhuifu-pay-integration v1.3.2\n\n- 新增商户进件相关 reference，包括企业、个体无执照、图片上传、业务开通、状态查询、详细信息等文档。\n- 路由表与精确场景分流支持商户进件链路，覆盖基础资料、业务开通、进件状态、字段合同、三语言 SDK 差异、日志安全等多场景。\n- 进件字段及业务开通请求参数严格按字段合同核对类型、长度、必填与约束，并新增进件自检规则。\n- 精简 skill-card.md，全面移除，替换为结构化路由和指引。\n- 本轮只读取当前场景涉及的3-5份 reference，其余按路由裁剪“暂不读取”。\n\nv1.3.1 | 2026-07-04T01:45:03.992Z | user\n\nhuifu-pay-integration 1.3.1\n\n- 新增本地沙箱（local-sandbox）支持及文档入口，便于本地协议模拟、闭环演练和自检报告。\n- 更新“什么时候使用”与快速路由，支持本地沙箱演练、报告校验和故障注入场景。\n- 路由表、决策流程中增加本地沙箱相关文档筛选和优先级处理逻辑。\n- 移除 skill-card.md；新增 references/shared-local-sandbox.md。\n- 其他功能、既有接口和主流程不变。\n\nv1.3.0 | 2026-06-12T09:48:56.936Z | user\n\n**huifu-pay-integration v1.2.3**\n\n- 提升为“汇付支付接入副驾驶”，支持首次接入、存量改造、调试、排查、上线全阶段。\n- 新增 13 个 reference 文档，包括回归 prompts、现有系统集成、上线校验、参数/方案卡、常见问题、FAQ、官方参考、版本升级策略等。\n- 加强存量系统判断、FAQ 路由、排查与升级场景。\n- 移除旧 skill-card.md。\n- 默认只推荐场景必需的 3-5 本地 references，细化快速路由表与硬/软检查点机制。\n\nv1.2.2 | 2026-05-29T12:51:09.821Z | user\n\n- 新增 Python 技术栈支持，覆盖聚合支付与托管支付接入说明与场景案例：aggregation-python-adapter.md、aggregation-python-scenarios.md、hostingpay-python-adapter.md、hostingpay-python-scenarios.md\n- 增加 Python 环境变量示例文件：python.env.prod.example\n- 新增服务端请求字段保留原则说明：shared-request-field-preservation.md\n- SKILL.md 主描述补充 Python 相关的产品接入、SDK、落地裁决规则与能力边界\n- 用户路由树与决策流程明确纳入 Python 场景与模板规则\n- 升级硬检查点机制，置 Go、Rust、Node、.NET、Ruby、Kotlin、Scala、Swift、C++ 为当前未覆盖技术栈\n\nv1.2.1 | 2026-05-08T07:39:43.296Z | user\n\nhuifu-pay-integration 1.2.1 Changelog\n\n- 项目英文名从 huifu-payment-integration 标准化为 huifu-pay-integration，统一命名风格。\n- 其他内容结构与描述保持不变，无功能或文档更新，仅为名称校正。\n\nv1.2.0 | 2026-05-08T06:39:58.462Z | user\n\n**1.2.0 版本重点：新增可读路由树，提升汇付支付集成路径清晰度**\n\n- 新增“用户可读路由树”板块，图示各主线（聚合/托管/checkout-js）接入路径及文档定位，便于初学者快速明晰选型与跳转。\n- 其余主流程说明、工作流、澄清规则等无本质调整，仅结构前移路由内容。\n- 文件未变动，仅 SKILL.md 文档内容结构优化，核心判决与能力边界无变化。\n- 技能描述及决策优先级等主体逻辑保持一致。\n\nv1.0.0 | 2026-05-08T06:34:44.389Z | user\n\nhuifu-payment-integration 1.0.0\n\n- 首次发布，提供汇付支付斗拱产品接入的最佳实践、文档路由与能力边界指引。\n- 覆盖场景包括聚合支付、托管支付、H5/PC收银台、checkout-js接入、查单/关单、退款、对账等。\n- 明确决策与检查点机制，细化不同产品线与技术栈的处理优先级、澄清话术和能力边界。\n- 针对PHP、Java、前端等主流技术栈，指定官方SDK集成方案与受支持主链路。\n- 提供常见场景快速路由、必需参数校验逻辑和不支持组合的固定应答规范。\n\nArchive index:\n\nArchive v1.3.5: 106 files, 423065 bytes\n\nFiles: agents/openai.yaml (404b), references/aggregation-async-webhook.md (7041b), references/aggregation-base.md (3287b), references/aggregation-common-params.md (7171b), references/aggregation-customer-preparation.md (10271b), references/aggregation-error-codes.md (5180b), references/aggregation-faq.md (5044b), references/aggregation-java-adapter.md (2502b), references/aggregation-java-sdk-quickstart.md (9469b), references/aggregation-java-tech-spec.md (5478b), references/aggregation-order-errors.md (7063b), references/aggregation-order-method-alipay.md (7765b), references/aggregation-order-method-unionpay.md (4190b), references/aggregation-order-method-wechat.md (7071b), references/aggregation-order-quickstart.md (2826b), references/aggregation-order-request.md (11876b), references/aggregation-order-response.md (10548b), references/aggregation-order-tx-metadata.md (11529b), references/aggregation-order.md (3912b), references/aggregation-payload-construction.md (10005b), references/aggregation-php-adapter.md (10872b), references/aggregation-python-adapter.md (7071b), references/aggregation-python-scenarios.md (7929b), references/aggregation-query-close-query.md (7479b), references/aggregation-query-payment-query.md (21795b), references/aggregation-query-php-scenarios.md (9123b), references/aggregation-query-quickstart.md (1509b), references/aggregation-query-reconciliation.md (9371b), references/aggregation-query-trade-close.md (7889b), references/aggregation-query.md (3522b), references/aggregation-quickstart.md (3616b), references/aggregation-refund-query.md (9071b), references/aggregation-refund-quickstart.md (1362b), references/aggregation-refund.md (15213b), references/canonical-regression-prompts.md (3222b), references/checkout-js-callback-and-confirmation.md (2350b), references/checkout-js-component-modes.md (2664b), references/checkout-js-create-preorder-contract.md (3381b), references/checkout-js-framework-integration-notes.md (1806b), references/checkout-js-integration-flow.md (3260b), references/checkout-js-readme.md (1549b), references/checkout-js.md (2364b), references/copilot-existing-system.md (4883b), references/copilot-go-live-checklist.md (3136b), references/copilot-onboarding.md (5174b), references/copilot-parameter-review.md (2960b), references/copilot-solution-cards.md (8682b), references/copilot-solution-selection.md (3370b), references/copilot-troubleshooting-playbooks.md (7672b), references/hostingpay-async-webhook.md (11437b), references/hostingpay-base.md (2218b), references/hostingpay-common-params.md (6572b), references/hostingpay-customer-preparation.md (9974b), references/hostingpay-error-codes.md (4399b), references/hostingpay-faq.md (4983b), references/hostingpay-java-adapter.md (2201b), references/hostingpay-java-sdk-quickstart.md (6639b), references/hostingpay-java-tech-spec.md (11425b), references/hostingpay-payload-construction.md (7898b), references/hostingpay-php-adapter.md (11872b), references/hostingpay-preorder-alipay-mini.md (23087b), references/hostingpay-preorder-douyin-direct.md (14269b), references/hostingpay-preorder-h5-pc-channel.md (9875b), references/hostingpay-preorder-h5-pc-errors.md (1284b), references/hostingpay-preorder-h5-pc-request.md (10144b), references/hostingpay-preorder-h5-pc-response-channel.md (11665b), references/hostingpay-preorder-h5-pc-response.md (6402b), references/hostingpay-preorder-h5-pc.md (9489b), references/hostingpay-preorder-php-scenarios.md (10210b), references/hostingpay-preorder-quickstart.md (7869b), references/hostingpay-preorder-wechat-mini.md (27034b), references/hostingpay-preorder.md (3817b), references/hostingpay-python-adapter.md (7092b), references/hostingpay-python-scenarios.md (9321b), references/hostingpay-query-payment-status-query.md (24116b), references/hostingpay-query-php-scenarios.md (6657b), references/hostingpay-query-quickstart.md (5206b), references/hostingpay-query-reconciliation.md (12588b), references/hostingpay-query-splitpay.md (9081b), references/hostingpay-query-trade-close.md (7713b)\n\nFile v1.3.5:SKILL.md\n\n---\nname: huifu-pay-integration\ndescription: \"汇付支付交易集成：用于聚合支付、托管支付、checkout-js、下单、查单、关单、退款、对账、支付通知、签名验签、请求头、幂等、交易终态、本地沙箱和支付上线；不用于企业/个人商户进件、图片上传、商户业务开通、商户详情或申请状态查询，这些任务使用 huifu-merchant-onboarding。\"\n---\n\n# 汇付支付集成\n\n## 版权声明\n\n本 Skill 中的汇付支付资料整理自上海汇付支付有限公司官方开放平台与官方产品文档；原始文档及其更新维护权归汇付支付官方所有。仅作技术学习交流与接口集成辅助使用，详见 `references/shared-copyright-notice.md`。\n\n## 执行流程\n\n1. 识别产品线、Endpoint、接入阶段、技术栈、端形态、当前目标和是否存量系统。完成标准：这些维度均已唯一确定，极速版产品场景与 V4 API 枚举已分开。\n2. 检查下方硬检查点；命中时停止生成可运行实现，只问一个最高优先级问题。完成标准：已记录命中或未命中的具体理由，SDK 传输安全和调试日志均已检查。\n3. 从精确路由中选择 3–5 份 reference。只有用户同时提出两个独立目标时才合并；完整 DTO、响应或嵌套字段任务必须包含完整字段目录。完成标准：每个目标均有一跳可达的原子接口页、合同定位路径、实际 JSON/解码路径（分别记录 wire 字段路径与 String(JSON) 解码后路径）和明确语言 adapter，不使用“对应文档”占位，也不把官网展示分组当成 wire key；只有官网明确标注“方便文档展示”时才从 wire 路径移除该分组。\n4. 首次接入输出产品线判断和方案卡；存量接入输出新增、保留、人工确认和回归检查。完成标准：请求、前端交接、通知、终态和补偿查询责任均已落到具体组件。\n5. 最后应用签名、验签、幂等、终态确认、请求字段保留和凭据安全规则。完成标准：每项均已检查，未知合同明确标记并停止生成相应实现。\n\n字段说明中的链接按其用途处理：完整字段目录已将官网 `#锚点` / 相对链接解析到各自接口原始页，并保留相对地址原文；绝对地址保持官网值。已确认的坏锚点使用显式映射：`#业务返回码` 补公共返回码全集，聚合下单 `notify_url` 的“异步返回参数”同时映射正扫、反扫通知参数和通用异步消息规范。只有命中本次字段的规范文档、编码表或渠道指引才作为外部资料提示。`notify_url`、`jump_url`、下载地址、二维码等裸 URL 示例是运行时值或格式示例，不是默认值、推荐地址或外部资料。\n\n本 Skill 只处理支付交易。企业、个人商户进件、图片资料、业务开通、商户详情和申请状态使用 `$huifu-merchant-onboarding`；不要从本 Skill 读取进件实现文档。\n\n## 精确路由\n\n| 场景 | 最小 reference 集 |\n| --- | --- |\n| 首次接入、产品线不明 | `references/shared-overview.md`、`references/copilot-onboarding.md`、`references/copilot-solution-selection.md` |\n| 存量系统接入 | `references/copilot-existing-system.md`、`references/copilot-solution-selection.md` |\n| 聚合支付快速接入 | `references/aggregation-quickstart.md`、`references/aggregation-customer-preparation.md` |\n| 聚合下单参数或代码 | `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` 补微信/支付宝/银联分册 |\n| 聚合交易查询 | `references/aggregation-query-payment-query.md` |\n| 返回码、公共编码或术语 | `aggregation-error-codes.md`、`aggregation-common-params.md`；具体字段仍补对应原子接口页 |\n| 聚合关单 | `references/aggregation-query-trade-close.md` |\n| 聚合对账 | `references/aggregation-query-reconciliation.md` |\n| 聚合退款或退款查询 | `references/aggregation-refund.md`、`references/payment-complete-field-catalog.md`，查询时补 `references/aggregation-refund-query.md` |\n| 托管支付快速接入 | `references/hostingpay-quickstart.md`、`references/hostingpay-customer-preparation.md` |\n| 托管预下单 | `references/hostingpay-preorder.md`、`references/payment-complete-field-catalog.md`，再按端形态补一个原子文档 |\n| 抖音直连、`pre_order_type=4` | `references/hostingpay-preorder.md`、`references/hostingpay-preorder-douyin-direct.md` |\n| 拆单支付查询、`splitpay/query` | `references/hostingpay-query.md`、`references/hostingpay-query-splitpay.md`；完整 DTO 同时执行下方完整字段目录路由 |\n| 交易分账明细、`trade/trans/split/query` | `references/trade-split-detail-query.md`、`references/payment-complete-field-catalog.md`；代码任务再补对应 Java/PHP/Python adapter |\n| 托管退款 | `references/hostingpay-refund.md`；完整 DTO 同时执行下方完整字段目录路由，Java setter 问题补 `references/hostingpay-faq.md` |\n| 托管普通交易查询 | `references/hostingpay-query.md`、`references/hostingpay-query-payment-status-query.md` |\n| 托管交易关单 | `references/hostingpay-query.md`、`references/hostingpay-query-trade-close.md` |\n| 托管退款查询 | `references/hostingpay-refund.md`、`references/hostingpay-refund-query.md`；完整 DTO 同时执行下方完整字段目录路由 |\n| 托管对账 | `references/hostingpay-query.md`、`references/hostingpay-query-reconciliation.md` |\n| checkout-js 已完成服务端前置 | `references/checkout-js.md`、`references/checkout-js-callback-and-confirmation.md`、`references/hostingpay-async-webhook.md` |\n| checkout-js 前置未确认 | `references/checkout-js-create-preorder-contract.md`，触发硬检查点 |\n| 支付通知、重复通知、幂等 | `references/shared-async-notify.md`、`references/copilot-troubleshooting-playbooks.md` |\n| 控台 Webhook 验签 | `references/shared-webhook-signing.md` |\n| Java / PHP / Python SDK | 先读 `references/shared-server-sdk-matrix.md`；再按语言与产品线精确选择 `references/aggregation-java-adapter.md`、`references/hostingpay-java-adapter.md`、`references/aggregation-php-adapter.md`、`references/hostingpay-php-adapter.md`、`references/aggregation-python-adapter.md` 或 `references/hostingpay-python-adapter.md` |\n| 请求头和 `skill_source` | `references/shared-request-header-policy.md` |\n| DTO/Controller 字段保留 | `references/shared-request-field-preservation.md` |\n| 完整 DTO、完整响应、嵌套字段或同名字段核对 | 对应原子接口页、`references/payment-complete-field-catalog.md`；代码任务再补语言 adapter |\n| appid/openid、支付路由、对账或资金运营 FAQ | `references/payment-operations-faq.md`、`references/copilot-troubleshooting-playbooks.md` |\n| 本地沙箱 | `references/shared-local-sandbox.md`，再补通知、查询或上线检查 |\n| 上线前检查 | `references/copilot-go-live-checklist.md`、`references/copilot-existing-system.md` |\n| 版本与升级 | `references/skill-version-policy.md` |\n\n按语言选择 reference：\n\n- Java：公共矩阵 + 产品线 Java adapter；先核对项目中的实际 SDK 版本和 Request 类。\n- PHP：公共矩阵 + 产品线 PHP adapter；保留安全初始化顺序，但不得使用会启用 `DEBUG=true` 的官方 Demo/Composer loader。\n- Python：公共矩阵 + 产品线 Python adapter；不要把 SDK 网络重试解释成业务重试。\n- 前端：checkout-js 只负责展示与前端事件，支付终态仍由服务端确认。\n\n## 🔴 CHECKPOINT · HARD STOP\n\n命中以下任一情况时，首行输出 `🔴 CHECKPOINT · HARD STOP：硬检查点。`，列出当前判断和本轮 references，只问一个最高优先级问题：\n\n1. 无法区分聚合支付、托管支付和 checkout-js。\n2. 无法区分服务端接入、前端页面接入和最终状态确认。\n3. 用户要求现成可运行代码，但当前接口、端形态或回退路径不唯一。\n4. checkout-js 的托管预下单、支付通知验签/幂等和查单补偿未确认。\n5. 用户要求联调或生产代码，但缺少环境、系统号、产品号、商户号、RSA 密钥安全来源、通知地址或必要渠道标识。未显式配置 `skill_source` 时使用下述确定性默认值，不因此硬停。\n6. 本地 SDK 源码与文档在请求头、签名、版本或能力覆盖上冲突。\n7. 用户要求 PHP 联调或生产可运行代码，但不能证明在加载 SDK、Demo/Composer 配置和调用 `BsPay::init` 之前已将全局 `DEBUG` 固定为 `false`，或仍使用会定义 `DEBUG=true` 的官方 Demo/Composer 入口。\n\nSDK 安装、初始化和安全 loader 骨架不因产品线不明而硬停，但不得猜具体业务 Request 或字段；PHP 骨架必须在加载任何 SDK 文件前拒绝 `DEBUG=true`。\n\n## 支付终态与通知\n\n- 同步受理成功、`jump_url`、浏览器回跳和前端 callback 都不是支付终态。\n- 对支付通知先验签，再校验金额、商户号、订单号和状态，最后做幂等更新。\n- 通知缺失时使用官方查单补偿；不要伪造通知、跳过验签或直接改成功。\n- 控台 Webhook 和接口 `notify_url` 是不同协议，不能混用签名位置或 ACK。\n- 聚合下单的同一个 `notify_url` 同时承接正扫和反扫两套通知参数；按 `trade_type` 分场景解析，不得只实现一套。\n\n## 请求和凭据\n\n- 保留 Controller/DTO 已接收的 `req_date`、`req_seq_id`、金额、商户号和原交易定位键；缺失或非法时报错，不自行重写。\n- 私钥、系统号和生产商户号只能从服务端安全配置读取，不能写入前端、日志、仓库或回答示例。\n- PHP `2.0.30` 默认 `DEBUG=false`，但官方 `BsPayDemo/loader.php` 与 `Composer/BsPayConfig.php` 会在初始化前启用调试；调试日志会包含带 RSA 私钥的 `MerConfig`、完整请求和响应。联调/生产必须拒绝这些入口，并在加载任何 SDK 文件前固定 `DEBUG=false`。\n- 未显式配置 `skill_source` 时，按当前请求实际加载并参与生成的 Skill 集合取值：仅本 Skill 使用 `hfps/1.3.5`；支付与进件两个 Skill 都参与当前请求时使用 `hfps/1.3.5;hfms/1.0.2`。仅安装在仓库但未参与当前请求不计入；顺序固定为支付、进件，使用一个英文分号且不加空格。\n- 调用方显式提供经确认的 `skill_source` 合同值时原样透传；不得再追加 `sys_id`。\n- 不因方便绕过 SDK 的签名、验签、证书或请求头路径。\n\n## 官方 SDK-only 传输规则\n\n- 接入方已确认官方 Lightning Java `1.0.5`、通用 Java `3.0.40`、PHP `2.0.30` 和 Python `2.0.24` SDK 不存在本 Skill 曾从历史源码快照推断的 TLS 问题；不得再据此触发 Java/PHP TLS 硬停。\n- Java、PHP、Python 的真实请求都必须使用对应官方 SDK 的 Request/facade/client；不得为了“规避 TLS”或补齐语言示例而改写 `HttpClient`、OkHttp、Guzzle、curl 或自实现 HTTP+签名/验签客户端。\n- SDK 缺少专属 Request 时先核对官方通用调用入口；仍无官方能力证据则明确报告能力缺口，不得用手写 HTTP 静默补位。\n- TLS 证书链和主机名校验属于部署环境的常规上线检查。不得关闭校验或安装信任所有证书的自定义实现，但该检查不构成针对当前官方 Java/PHP SDK 的预设硬停。\n\n## 本地沙箱边界\n\n本地沙箱仅验证本地协议闭环、状态机、幂等、故障注入和报告，不验证真实商户权限、通道、费率、风控、资金结果或生产准入。冻结的 `r1–r4` 合同和样例包属于历史支付证据，不得因本次 Skill 拆分改名或重算。\n\n## 输出要求\n\n回答至少包含：\n\n1. 当前产品线、阶段、技术栈和存量判断。\n2. 本轮实际使用的 3–5 份 references。\n3. 请求、通知、终态和安全边界。\n4. 缺失信息、人工确认项和下一步。\n\n不要输出费率、合规、通道准入或生产失败责任结论；只整理脱敏升级材料并转人工确认。\n\n## 当前版本\n\n| 项目 | 口径 |\n| --- | --- |\n| Skill 版本 | `1.3.5` |\n| 能力范围 | 聚合支付、托管支付、checkout-js、支付通知、SDK、本地沙箱和支付上线 |\n| 进件能力 | 已迁移至独立 `$huifu-merchant-onboarding` |\n| 聚合支付 Java SDK | `dg-lightning-sdk 1.0.5` |\n| 托管支付 Java SDK | `dg-java-sdk 3.0.40` |\n| PHP SDK | `huifurepo/dg-php-sdk 2.0.30` |\n| Python SDK | `dg-sdk 2.0.24`，import 为 `dg_sdk` |\n\nFile v1.3.5:_meta.json\n\n{\n  \"ownerId\": \"kn7as5mtmp7qjv21jr9n15qth182kat3\",\n  \"slug\": \"huifu-pay-integration\",\n  \"version\": \"1.3.5\",\n  \"publishedAt\": 1788166368148\n}\n\nFile v1.3.5:references/aggregation-async-webhook.md\n\n# 异步通知与 Webhook\r\n\r\n> 本文面向 `references/aggregation-base.md` 依赖的聚合支付 Skill，重点把交易通知的真实报文形态、验签方式、幂等和终态判断说明清楚。\r\n\r\n\r\n## 目录\r\n\r\n- 两种异步机制\r\n- `notify_url` 使用规范\r\n- 聚合交易通知报文形态\r\n- Spring Boot 接收、验签与查单示例\r\n- 终态判断原则\r\n- 签名差异\r\n- Webhook 使用场景\r\n- Webhook 落地步骤\r\n- Webhook 重发规则\r\n- 使用建议\r\n- 参考\r\n\r\n## 两种异步机制\r\n\r\n| 机制 | 入口 | 用途 | 签名方式 |\r\n|------|------|------|----------|\r\n| `notify_url` | 下单、退款等接口请求参数 | 交易结果回调 | 汇付 RSA 公钥验签 |\r\n| Webhook | 汇付控台端点订阅 | 平台事件通知 | 终端密钥 + MD5 原始事件体 |\r\n\r\n## `notify_url` 使用规范\r\n\r\n- 汇付以 HTTP `POST` 发送交易结果。\r\n- 响应必须在 5 秒内返回。\r\n- 正确应答格式为：HTTP `200` + `RECV_ORD_ID_` + `req_seq_id`。\r\n- 未及时应答或应答格式不正确时，汇付会自动重试，最多 3 次。\r\n- 自定义端口需落在 `8000-9005`。\r\n- URL 不要带查询参数。\r\n- 同一笔交易可能会重复通知，必须用 `hf_seq_id` 做幂等。\r\n\r\n## 聚合交易通知报文形态\r\n\r\n聚合支付的交易类异步通知，外层通常包含以下 4 个网关字段：\r\n\r\n| 字段 | 说明 |\r\n|------|------|\r\n| `resp_code` | 网关返回码 |\r\n| `resp_desc` | 网关返回信息 |\r\n| `sign` | 对整个业务数据的签名 |\r\n| `resp_data` | 业务数据 JSON 字符串 |\r\n\r\n其中真正要驱动业务的字段在 `resp_data` 里，而不是直接平铺在最外层。\r\n\r\n```json\r\n{\r\n  \"resp_code\": \"10000\",\r\n  \"resp_desc\": \"成功调用\",\r\n  \"sign\": \"返回签名串\",\r\n  \"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\\\"}\"\r\n}\r\n```\r\n\r\n## Spring Boot 接收、验签与查单示例\r\n\r\n```java\r\nimport com.alibaba.fastjson.JSON;\r\nimport com.alibaba.fastjson.JSONObject;\r\n// Spring Boot 2.x: import javax.servlet.http.HttpServletRequest;\r\n// Spring Boot 3.x: import jakarta.servlet.http.HttpServletRequest;\r\nimport java.util.Objects;\r\nimport org.springframework.beans.factory.annotation.Value;\r\nimport org.springframework.util.StringUtils;\r\nimport org.springframework.web.bind.annotation.PostMapping;\r\nimport org.springframework.web.bind.annotation.RequestMapping;\r\nimport org.springframework.web.bind.annotation.RestController;\r\n\r\n@RestController\r\n@RequestMapping(\"/notify\")\r\npublic class AggregateNotifyController {\r\n\r\n    private final String huifuPublicKey;\r\n    private final AggregateQueryService queryService;\r\n    private final NotifyIdempotentService idempotentService;\r\n\r\n    public AggregateNotifyController(\r\n            @Value(\"${huifu.rsa-public-key}\") String huifuPublicKey,\r\n            AggregateQueryService queryService,\r\n            NotifyIdempotentService idempotentService) {\r\n        this.huifuPublicKey = huifuPublicKey;\r\n        this.queryService = queryService;\r\n        this.idempotentService = idempotentService;\r\n    }\r\n\r\n    @PostMapping(\"/payment\")\r\n    public String onNotify(HttpServletRequest request) {\r\n        String respData = request.getParameter(\"resp_data\");\r\n        String sign = request.getParameter(\"sign\");\r\n        if (!StringUtils.hasText(respData) || !StringUtils.hasText(sign)) {\r\n            throw new IllegalArgumentException(\"汇付回调缺少 resp_data 或 sign\");\r\n        }\r\n        if (!RsaUtils.verify(respData, huifuPublicKey, sign)) {\r\n            throw new IllegalArgumentException(\"汇付回调验签失败\");\r\n        }\r\n\r\n        JSONObject dataObj = JSON.parseObject(respData);\r\n        String reqSeqId = dataObj.getString(\"req_seq_id\");\r\n        String reqDate = dataObj.getString(\"req_date\");\r\n        String hfSeqId = dataObj.getString(\"hf_seq_id\");\r\n        String transStat = dataObj.getString(\"trans_stat\");\r\n        String transType = dataObj.getString(\"trans_type\");\r\n\r\n        if (idempotentService.isProcessed(hfSeqId)) {\r\n            return \"RECV_ORD_ID_\" + reqSeqId;\r\n        }\r\n\r\n        AggregateQueryResult queryResult = queryService.query(reqDate, reqSeqId);\r\n        if (!Objects.equals(queryResult.getTransStat(), transStat)) {\r\n            throw new IllegalStateException(\"异步通知与查单状态不一致\");\r\n        }\r\n\r\n        if (\"S\".equals(transStat)) {\r\n            // 支付成功：更新订单并执行后续业务\r\n        } else if (\"F\".equals(transStat)) {\r\n            // 支付失败：记录失败原因\r\n        } else if (\"P\".equals(transStat)) {\r\n            // 处理中：继续等待通知或轮询\r\n        } else {\r\n            throw new IllegalStateException(\"未知 trans_stat=\" + transStat);\r\n        }\r\n\r\n        // 同步返回常见字段名是 trade_type，异步回调字段名是 trans_type，不要混用\r\n        // 例如：log.info(\"notify reqSeqId={}, hfSeqId={}, transType={}, transStat={}\", ...);\r\n        return \"RECV_ORD_ID_\" + reqSeqId;\r\n    }\r\n}\r\n```\r\n\r\n## 终态判断原则\r\n\r\n- `trans_stat`、查单结果、幂等键可以驱动订单状态流转。\r\n- `resp_code`、`resp_desc`、HTTP 返回码主要用于排查，不直接驱动订单终态。\r\n- 不要写“`resp_code=00000000` 就直接支付成功”这种逻辑。\r\n\r\n## 签名差异\r\n\r\n| 场景 | 密钥 | 说明 |\r\n|------|------|------|\r\n| API 请求与 `notify_url` | 商户 RSA 私钥签名，汇付 RSA 公钥验签 | `SHA256WithRSA` |\r\n| Webhook | Webhook 终端密钥 | `MD5(raw_body + endpoint_key)`，与 API RSA 密钥无关 |\r\n\r\nWebhook 必须先对原始请求体验签，再 JSON 解析事件体。不要先反序列化后重新序列化，也不要用 `sign` 长度自动猜 MD5 / RSA。完整共享规则见 `shared-webhook-signing.md`。\r\n\r\n## Webhook 使用场景\r\n\r\nWebhook 更适合做平台级事件通知，例如：\r\n\r\n| 事件类型编号 | 说明 |\r\n|--------------|------|\r\n| `trans.close` | 关单事件 |\r\n| `refund.standard` | 退款事件 |\r\n| `statement.day` | 日结算通知 |\r\n| `statement.auto` | 自动结算通知 |\r\n| `settlement.encashment` | 取现通知 |\r\n\r\n## Webhook 落地步骤\r\n\r\n1. 在服务端创建 HTTPS 端点。\r\n2. 在汇付控台注册端点并选择订阅事件。\r\n3. 使用测试事件验证联通性。\r\n4. 处理正式事件，并监控失败重试。\r\n\r\n## Webhook 重发规则\r\n\r\n- 首次发送失败后会快速重试 3 次。\r\n- 之后按小时级补发，直到成功。\r\n- 控台支持手工重新推送。\r\n\r\n## 使用建议\r\n\r\n- 支付交易主状态仍优先依赖 `notify_url` 和主动查询。\r\n- Webhook 更适合对账、结算、告警和平台事件同步。\r\n- API 回调验签和 Webhook 验签必须分开实现，不要共用密钥。\r\n\r\n## 参考\r\n\r\n- 平台 Webhook 工具介绍：<https://paas.huifu.com/open/doc/devtools/#/webhook/webhook_jieshao>\n\nFile v1.3.5:references/aggregation-base.md\n\n# 聚合支付基础\r\n\r\n这份文档负责聚合支付的初始化、公共参数、语言边界和接入前置判断。\r\n\r\n## 什么时候读这里\r\n\r\n- 第一次接聚合支付\r\n- 需要确认 `trade_type`、公共环境变量、初始化顺序\r\n- 需要判断当前应该走 Java、PHP 还是 Python\r\n\r\n## 推荐阅读顺序\r\n\r\n```text\r\nshared-overview\r\n  -> shared-signing-v2\r\n  -> shared-request-header-policy\r\n  -> aggregation-base\r\n  -> aggregation-order / aggregation-query / aggregation-refund\r\n```\r\n\r\n## 当前版本口径\r\n\r\n| 项目 | 当前值 |\r\n| --- | --- |\r\n| Java SDK | `dg-lightning-sdk 1.0.5` |\r\n| PHP 覆盖范围 | 下单、扫码交易查询、关单、关单查询、退款、退款查询、对账 |\r\n| `HUIFU_SKILL_SOURCE` 最终值 | `<skill_source>` |\r\n\r\n## 必备环境变量\r\n\r\n| 环境变量 | 用途 |\r\n| --- | --- |\r\n| `HUIFU_PRODUCT_ID` | 汇付分配的产品号 |\r\n| `HUIFU_SYS_ID` | 渠道商 / 商户 `huifu_id` |\r\n| `HUIFU_RSA_PRIVATE_KEY` | 请求签名私钥 |\r\n| `HUIFU_RSA_PUBLIC_KEY` | 响应验签公钥 |\r\n| `HUIFU_SKILL_SOURCE` | 可选来源覆盖项，请求头层按 `<skill_source>` 原样透传 |\r\n\r\n## 初始化前确认事项\r\n\r\n1. 先读 `references/shared-signing-v2.md`\r\n2. 先读 `references/shared-async-notify.md`\r\n3. 如果不是 Java，必须额外核对 `references/shared-request-header-policy.md`\r\n4. 不要猜测 `sub_openid`、`buyer_id`、`auth_code`、`devs_id`、`fee_sign` 等运行时值\r\n\r\n## 聚合支付主流程\r\n\r\n```text\r\n准备产品号和密钥\r\n  -> 初始化 SDK 或 HTTP 客户端\r\n  -> 选择 trade_type\r\n  -> aggregation-order 下单\r\n  -> aggregation-query 查单 / 关单 / 对账\r\n  -> aggregation-refund 退款\r\n```\r\n\r\n## trade_type 速查\r\n\r\n| trade_type | 说明 |\r\n| --- | --- |\r\n| `T_JSAPI` | 微信公众号支付 |\r\n| `T_MINIAPP` | 微信小程序支付 |\r\n| `T_APP` | 微信 APP 支付 |\r\n| `T_MICROPAY` | 微信付款码反扫 |\r\n| `A_JSAPI` | 支付宝 JS 支付 |\r\n| `A_NATIVE` | 支付宝正扫 |\r\n| `A_MICROPAY` | 支付宝付款码反扫 |\r\n| `U_JSAPI` | 银联 JS 支付 |\r\n| `U_NATIVE` | 银联正扫 |\r\n| `U_MICROPAY` | 银联付款码反扫 |\r\n\r\n## 语言边界\r\n\r\n- Java 是聚合支付完整基线\r\n- PHP 已覆盖聚合支付核心主链路与对账；默认入口先读 `references/aggregation-php-adapter.md` 与 `references/aggregation-query-php-scenarios.md`\r\n- Python 已覆盖聚合支付核心主链路与对账；默认入口先读 `references/aggregation-python-adapter.md` 与 `references/aggregation-python-scenarios.md`\r\n- 当前 Skill 包不再内置 PHP 模板资产；PHP 默认走官方 `huifurepo/dg-php-sdk`\r\n- C#、Go 当前只保留统一入口说明，不提供现成业务模板\r\n\r\n## 公共字段提醒\r\n\r\n- `req_seq_id` 必须保证当日唯一\r\n- `req_date` 建议始终保存，后续查询、关单、退款都要回用\r\n- `method_expand`、`acct_split_bunch`、`terminal_device_data`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info` 应先建模再序列化；`tx_metadata` 本身不作为请求字段上送\r\n\r\n## 下一步怎么走\r\n\r\n- 要创建订单：读 `references/aggregation-order.md`\r\n- 要查单 / 关单 / 对账：读 `references/aggregation-query.md`\r\n- 要退款：读 `references/aggregation-refund.md`\n\nFile v1.3.5:references/aggregation-common-params.md\n\n# 公共参数说明\n\n官方公共资料入口：\n\n- [基础参数汇总](https://paas.huifu.com/partners/api/doc/csfl/api_csfl.md)：地区、银行、支行、MCC、交易类型、文件类型等公共编码/枚举的入口。\n- [名词解释](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_mcjs.md)：ATU、H5、结算周期、手续费等术语口径。\n- [返回码](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_ywm.md)：网关与业务返回码全集。\n\n这些页面是公共字典和术语来源，不覆盖具体接口页对字段必填、条件、类型和层级的定义；发生差异时保留两边证据并按具体接口合同处理。\n\n\n## 目录\n\r\n- 公共请求参数\r\n- 公共返回参数\r\n- 业务数据通用字段\r\n- 交易状态枚举（trans_stat）\r\n- 金额格式\r\n- 日期时间格式\r\n- 流水号规则\r\n- 支付类型详解\r\n- 标准字段与格式约束\r\n- 结算术语\r\n- 手续费术语\r\n\r\n## 公共请求参数\r\n\r\n所有聚合支付 API 请求的外层参数：\r\n\r\n| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |\r\n|------|-------|------|------|------|------|\r\n| sys_id | 系统号 | String | 32 | Y | 渠道商/代理商/商户的 huifu_id |\r\n| product_id | 产品号 | String | 32 | Y | 汇付分配的产品号，如 `MYPAY`、`YYZY` |\r\n| sign | 加签结果 | String | 512 | Y | SDK 自动生成，无需手动处理 |\r\n| data | 请求数据 | JSON | - | Y | 业务请求参数 |\r\n\r\n> 强制请求头约束：\r\n> - 必须带 `jpt-x-skill-source: <skill_source>`\r\n> - 如果当前按 PHP 接入，且接口业务报文里存在 `huifu_id`，还必须带 `jpt-x-skill-huifu_id: <data.huifu_id>`\r\n> - 当前 Skill 包对齐的官方 PHP SDK 主链路在 `MerConfig.skill_source` 已配置时，会自动带 `jpt-x-skill-source`，并在当前请求 `huifu_id` 存在且非空时自动带 `jpt-x-skill-huifu_id`\r\n> - 当前 Java SDK 基线也会在接口业务报文里 `huifu_id` 存在且非空时自动带 `jpt-x-skill-huifu_id: <data.huifu_id>`\r\n> - 这两项属于 HTTP 请求头，不属于 `data` 字段本身；完整口径见 `references/shared-request-header-policy.md`\r\n\r\n### sys_id 说明\r\n\r\n| 主体类型 | sys_id 填写 |\r\n|---------|-----------|\r\n| 渠道商/代理商 | 渠道商/代理商的 huifu_id |\r\n| 直连商户 | 商户自身的 huifu_id |\r\n\r\n> **sys_id vs huifu_id**：`sys_id` 是外层公共参数，标识调用方身份；`huifu_id` 是 `data` 内业务参数，标识交易商户。渠道商模式下两者不同，直连商户模式下两者相同。\r\n\r\n## 公共返回参数\r\n\r\n| 参数 | 中文名 | 类型 | 长度 | 说明 |\r\n|------|-------|------|------|------|\r\n| sign | 签名 | String | 512 | SDK 自动验证 |\r\n| data | 响应内容体 | JSON | - | 业务返回参数 |\r\n\r\n## 业务数据通用字段\r\n\r\n以下字段在多数业务接口的 `data` 中出现：\r\n\r\n| 参数 | 中文名 | 类型 | 说明 |\r\n|------|-------|------|------|\r\n| resp_code | 业务响应码 | String(8) | 接口受理返回码，用于排查；订单终态仍看 `trans_stat` 和查单结果 |\r\n| resp_desc | 业务响应信息 | String(512) | 响应描述 |\r\n| huifu_id | 商户号 | String(32) | 商户 huifu_id |\r\n| req_date | 请求日期 | String(8) | 格式 yyyyMMdd |\r\n| req_seq_id | 请求流水号 | String(128) | 同一 huifu_id 下当天唯一 |\r\n| hf_seq_id | 汇付全局流水号 | String(128) | 汇付生成的全局唯一标识 |\r\n\r\n## 交易状态枚举（trans_stat）\r\n\r\n| 值 | 含义 | 处理方式 |\r\n|---|------|---------|\r\n| I | 初始 | 罕见状态，联系汇付技术人员 |\r\n| P | 处理中 | 等待异步通知或轮询查询接口 |\r\n| S | 成功 | 交易完成 |\r\n| F | 失败 | 交易失败，可重新发起 |\r\n\r\n## 金额格式\r\n\r\n- **单位**：元（CNY）\r\n- **精度**：保留两位小数\r\n- **最小值**：0.01\r\n- **示例**：`\"1.00\"`、`\"100.50\"`、`\"0.01\"`\r\n\r\n## 日期时间格式\r\n\r\n| 格式 | 说明 | 示例 |\r\n|------|------|------|\r\n| yyyyMMdd | 日期 | `20250320` |\r\n| yyyyMMddHHmmss | 日期时间（14位） | `20250320143000` |\r\n| HHmmss | 时间（6位） | `143000` |\r\n\r\n## 流水号规则\r\n\r\n| 字段 | 规则 | 说明 |\r\n|------|------|------|\r\n| req_seq_id | 同一 huifu_id 下当天唯一 | 商户自行生成 |\r\n| hf_seq_id | 全局唯一 | 汇付返回，用于查询/退款 |\r\n| org_req_seq_id | 原交易的 req_seq_id | 用于关联原交易 |\r\n| org_hf_seq_id | 原交易的 hf_seq_id | 可替代 org_req_seq_id |\r\n\r\n## 支付类型详解\r\n\r\n### 正扫 vs 反扫\r\n\r\n| 类型 | 说明 | 适用 trade_type |\r\n|------|------|----------------|\r\n| 正扫 (NATIVE) | 商户生成二维码，用户扫码支付 | A_NATIVE、U_NATIVE |\r\n| 反扫 (MICROPAY) | 用户出示付款码，商户扫码收款 | T_MICROPAY、A_MICROPAY、U_MICROPAY |\r\n| JS 支付 (JSAPI) | 在对应 APP 内通过 JS 调起支付 | T_JSAPI、A_JSAPI、U_JSAPI |\r\n| 小程序 (MINIAPP) | 微信小程序内支付 | T_MINIAPP |\r\n| APP 支付 | 原生 APP 内支付 | T_APP |\r\n\r\n### method_expand 参数\n\n本节只描述**聚合下单请求侧**的 `request.data.method_expand`，不得外推到查询响应。不同 `trade_type` 需要传入不同的 `method_expand` 扩展参数。请求侧的 `trade_type` 是场景选择器，这 10 个枚举值本身不是 `request.data.method_expand` 的 key；该 JSON 内容直接是当前请求场景对象本身。查询响应 `response.data.method_expand` 同样只解码一次且字段单层平铺，具体字段与勘误必须改读 `aggregation-query-payment-query.md`。\n\r\n| trade_type | method_expand 必填字段 | 说明 |\r\n|-----------|----------------------|------|\r\n| T_JSAPI | sub_appid, sub_openid | 微信公众号 AppID 和用户 OpenID |\r\n| T_MINIAPP | sub_appid, sub_openid | 微信小程序 AppID 和用户 OpenID |\r\n| T_APP | sub_appid | 微信开放平台 AppID |\r\n| T_MICROPAY | auth_code | 用户付款码 |\r\n| A_JSAPI | buyer_id 或 buyer_logon_id | 支付宝买家 ID / 账号，二选一 |\r\n| A_NATIVE | - | 无需额外参数 |\r\n| A_MICROPAY | auth_code | 用户付款码 |\r\n| U_JSAPI | user_id, qr_code, customer_ip | 银联 JS 常见关键字段 |\r\n| U_NATIVE | - | 无需额外参数 |\r\n| U_MICROPAY | auth_code | 用户付款码 |\r\n\r\n## 标准字段与格式约束\r\n\r\n- 请求和返回统一使用 JSON，字符编码统一为 `UTF-8`。\r\n- 参数命名统一采用下划线命名法，如 `req_seq_id`、`trade_type`。\r\n- 金额单位统一为元，保留两位小数。\r\n- 时间统一按北京时间（东八区）处理。\r\n- 数值字段在 API 层尽量使用字符串承载，避免精度损失。\r\n\r\n## 结算术语\r\n\r\n| 术语 | 说明 |\r\n|------|------|\r\n| T1 自动结算 | 前一工作日周期内余额结算到银行卡 |\r\n| D1 自动结算 | 前一自然日周期内余额结算到银行卡 |\r\n| D0 取现 | 发起后通常 2 小时内到账 |\r\n| DM 取现 | 不包含在途资金的快速取现方式 |\r\n\r\n## 手续费术语\r\n\r\n| 术语 | 说明 |\r\n|------|------|\r\n| 实时收取 | 默认模式，按交易费率实时计算并收取 |\r\n| 手续费内扣 | 从交易金额中扣收手续费 |\r\n| 手续费外扣 | 从指定主体或账户额外扣收手续费 |\n\nFile v1.3.5:references/aggregation-customer-preparation.md\n\n# 聚合支付客户前置准备清单\r\n\r\n> 这份文档用于约束聚合支付 skill 在编码前先确认“参数从哪里来”。这里的前置准备不只是收集字段值，还包括官方产品介绍和开发指引里明确要求的业务开通、应用配置、授权绑定和终端采集动作。如果来源不明确，模型不应自行推断或伪造参数值。\r\n\r\n\r\n## 目录\r\n\r\n- 参数来源分类\r\n- 全局必备配置\r\n- 官方开发指引确认的通用前置动作\r\n- 聚合下单前要准备什么\r\n- 渠道级前置准备矩阵\r\n- 扩展字段相关准备项\r\n- 查询 / 关单 / 退款前要沉淀什么\r\n- 权限 / 开通项检查\r\n- 向客户索取材料的最小清单\r\n- 给模型的硬约束\r\n\r\n## 参数来源分类\r\n\r\n| 来源类型 | 典型字段 | 说明 |\r\n|---------|---------|------|\r\n| 汇付平台固定配置 | `sys_id`、`product_id`、`huifu_id`、RSA 密钥 | 由汇付开放平台 / 控台提供 |\r\n| 客户业务配置 | `notify_url`、`fee_flag`、`acct_id`、`channel_no` | 由客户业务侧或控台确认 |\r\n| 前端 / 用户授权结果 | `sub_openid`、`buyer_id`、`buyer_logon_id` | 运行时值，模型不能猜 |\r\n| 终端 / 设备采集 | `auth_code`、`device_ip`、`devs_id`、`customer_ip` | 反扫、终端报备、银联场景常见 |\r\n| 上游订单沉淀 | `req_date`、`req_seq_id`、`hf_seq_id`、`party_order_id` | 查询 / 关单 / 退款必须复用 |\r\n\r\n## 全局必备配置\r\n\r\n| 配置项 | 用途 | 没有会怎样 |\r\n|-------|------|-----------|\r\n| `sys_id` | 公共请求参数 | 请求无法落地 |\r\n| `product_id` | 公共请求参数 | 汇付会直接报产品号错误 |\r\n| `huifu_id` | 商户主体标识 | 业务请求无法定位商户 |\r\n| RSA 私钥 / 公钥 | 请求签名、响应验签 | 请求或验签失败 |\r\n| `notify_url` / `refund_notify_url` | 异步结果通知 | 只能依赖轮询，不稳定 |\r\n| 对应渠道业务开通状态 | 微信 / 支付宝 / 银联交易前提 | 交易前必须确认账户和对应渠道已开通；进件实施交给 `$huifu-merchant-onboarding` |\n\r\n## 官方开发指引确认的通用前置动作\r\n\r\n- `Lightning_intro.md` 和《快速开始》都明确要求：开发新业务或变更旧业务前，先按产品文档中的“开通功能和准备材料”在合作伙伴控台或商户控台完成业务新增 / 变更。\r\n- 多个渠道开发指引都明确写了：用户前端页面收到支付完成回调，不等于后端可以直接认定交易成功；后端仍需调用查询订单 API 确认最终状态。\r\n- 运行时授权值、扫码值、终端采集值、渠道绑定关系，都是“业务前置准备”的一部分，不是接口层补字段时临时猜出来的。\r\n\r\n## 聚合下单前要准备什么\r\n\r\n### 所有 trade_type 通用\r\n\r\n| 字段 / 配置 | 来源 | 说明 |\r\n|------------|------|------|\r\n| `trade_type` | 业务场景确认 | 决定 `method_expand` 结构 |\r\n| `goods_desc` | 业务订单 | 不是示例值，应该来自真实商品 / 订单语义 |\r\n| `req_seq_id` | 平台流水号生成规则 | 必须当天唯一 |\r\n| `time_expire` | 业务超时策略 | 如不明确可不传，不要乱填过期时间 |\r\n| `acct_split_bunch` | 分账业务配置 | 只有要做分账时才准备 |\r\n| `terminal_device_data` | 终端 / 设备采集链路 | 反扫、终端报备、银联场景常见 |\r\n| `combinedpay_data` / `combinedpay_data_fee_info` / `trans_fee_allowance_info` | 补贴与手续费补贴能力配置 | 按能力名直接作为请求顶层扩展字段传；不要包进 `tx_metadata` |\r\n\r\n### 微信类场景\r\n\r\n| `trade_type` | 必须提前明确的值 | 来源 |\r\n|-------------|------------------|------|\r\n| `T_JSAPI` | `sub_appid`、`sub_openid` | 官方要求先准备微信公众号、开通微信业务、绑定 `sub_appid`、配置支付授权目录；`sub_openid` 必须通过当前公众号 `sub_appid` 的网页授权流程获取 |\n| `T_MINIAPP` | `sub_appid`、`sub_openid` | 官方要求先准备微信小程序、开通微信业务、完成微信配置和 appid 绑定；`sub_openid` 必须通过当前小程序 `sub_appid` 获取，且二者不能错配 |\n| `T_APP` | `sub_appid` | 应用配置 |\r\n| `T_MICROPAY` | `auth_code` | 官方要求通过扫码设备实时采集用户付款码；值本身来自用户当次付款码，不应预置到配置中 |\r\n\r\n### 支付宝类场景\r\n\r\n| `trade_type` | 必须提前明确的值 | 来源 |\r\n|-------------|------------------|------|\r\n| `A_JSAPI` | `buyer_id` 或 `buyer_logon_id` | 官方要求先开通支付宝业务；`buyer_id` 必须通过支付宝 `user_id` 获取流程拿到，不能猜 |\r\n| `A_NATIVE` | 视业务决定是否传门店、商品、营销扩展 | 客户业务配置 |\r\n| `A_MICROPAY` | `auth_code` | 官方要求通过扫码设备实时采集用户支付宝付款码 |\r\n\r\n### 银联类场景\r\n\r\n| `trade_type` | 必须提前明确的值 | 来源 |\r\n|-------------|------------------|------|\r\n| `U_JSAPI` | `user_id`、`customer_ip`，官方说明 `qr_code` 也要明确 | 官方要求先开通银联业务；`user_id` 需先经“网页授权获取 `auth_code` -> 调获取银联用户标识接口”获得，`customer_ip` 必须来自真实客户端 |\r\n| `U_NATIVE` | 是否需要 `front_url`、`payee_info` | 客户业务配置 |\r\n| `U_MICROPAY` | `auth_code`，以及是否需要 `pid_info` | 官方要求通过扫码设备实时采集用户云闪付付款码；`pid_info` 来自服务商配置 |\r\n\r\n## 渠道级前置准备矩阵\r\n\r\n| 场景 | 客户开发前必须完成什么 | 关键运行时值 |\r\n|------|----------------------|-------------|\r\n| 微信公众号支付 | 准备公众号、确认账户和微信业务已开通、绑定 `sub_appid`、配置公众号支付授权目录；授权目录通常以 `/` 结尾，配置后可能延迟生效 | `sub_openid` |\n| 微信小程序支付 | 准备小程序、确认账户和微信业务已开通、完成微信配置、确认 `sub_appid` 绑定关系，清理 appid 配置首尾空格 | `sub_openid` |\n| 支付宝 JS 支付 | 确认账户和支付宝业务已开通 | `buyer_id` / `buyer_logon_id` |\n| 银联 JS 支付 | 确认账户和银联业务已开通、准备银联网页授权回调链路 | `user_id`、`customer_ip` |\n| 各类付款码反扫 | 准备扫码枪或终端采集链路 | `auth_code` |\r\n\r\n## 扩展字段相关准备项\r\n\r\n| 对象 | 需要客户先准备什么 | 说明 |\r\n|------|------------------|------|\r\n| `acct_split_bunch` | 分账接收方 `huifu_id`、账户号、比例 / 金额规则 | 未准备好不要让模型硬拼分账串 |\r\n| `terminal_device_data` | `device_ip`、`devs_id`、定位 / 设备指纹 | 反扫和报备终端场景很关键 |\r\n| `combinedpay_data` | 补贴方 `huifu_id`、`acct_id`、金额 | 请求顶层字段，属于补贴业务配置，不可猜 |\r\n| `combinedpay_data_fee_info` | 手续费承担方 `huifu_id`、`acct_id` | 请求顶层字段，需要真实承担方信息 |\r\n| `trans_fee_allowance_info` | 补贴手续费金额和活动来源 | 请求顶层字段，需要明确的活动或配置支持 |\r\n\r\n## 查询 / 关单 / 退款前要沉淀什么\r\n\r\n| 接口 | 开发前必须保证已保存 | 说明 |\r\n|------|------------------|------|\r\n| 交易查询 | `req_date`、`req_seq_id`、`hf_seq_id`、`party_order_id` 中至少一组 | 不能等到查询时再猜 |\r\n| 交易关单 | 原交易 `org_req_date` + `org_req_seq_id` 或 `org_hf_seq_id` | 依赖原交易标识 |\r\n| 关单查询 | 关单请求自身标识 + 原交易标识 | 两层流水都要可追溯 |\r\n| 退款 | `org_hf_seq_id`、`org_party_order_id`、`org_req_seq_id` 三选一 | 原交易定位键来自上游沉淀 |\r\n| 退款查询 | 原退款请求标识、原交易标识 | 便于轮询确认 |\r\n| 对账单查询 | 对账功能开通状态、`file_date` 语义 | 功能未开通时接口也不可用 |\r\n\r\n## 权限 / 开通项检查\r\n\r\n| 能力 | 影响点 |\r\n|------|--------|\r\n| 分账权限 | `acct_split_bunch` |\r\n| 延迟入账权限 | `delay_acct_flag` |\r\n| 退款权限 | 退款接口 |\r\n| 终端报备 | `terminal_device_data.devs_id` |\r\n| 手续费 / 贴息 / 补贴配置 | `fee_flag`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info` |\r\n| 对账单功能 | `file_date`、`bill_type` |\n| 微信小程序 `sub_appid` 绑定 | `T_MINIAPP` 下单成功率 | 官方 QA 明确要求 `sub_appid` 与商户建立绑定关系 |\n| 微信 `sub_appid` / `sub_openid` 一致性 | `T_MINIAPP` / `T_JSAPI` | 官方 QA 明确要求 `sub_openid` 必须从对应 `sub_appid` 获取 |\n| 接口权限 | 当前接口是否能调用 | `接口权限认证失败` 或 `20003` 时先核对 `sys_id` 是否开通当前接口权限 |\n| 数据权限 | `product_id`、`sys_id`、`huifu_id`、`upper_huifu_id` | `数据权限认证失败` 时核对产品号、服务商/子商户层级和请求头来源 |\n| 渠道路由 | `pay_channel`、`pay_scene`、`channel_no`、线上/线下 `fee_type` | 多渠道或线上/线下混用时要明确场景；不指定通道时不要传空字符串 `channel_no` |\n\r\n## 向客户索取材料的最小清单\r\n\r\n### 必需\r\n\r\n- `sys_id`、`product_id`、`huifu_id`\r\n- RSA 私钥、公钥\r\n- 支付 / 退款异步通知地址\r\n- 实际要接的 `trade_type` 列表\r\n\r\n### 按场景补充\r\n\r\n- 微信：公众号 / 小程序应用信息、`sub_appid`、`sub_openid` 获取链路\r\n- 支付宝：`buyer_id` / `buyer_logon_id` 的真实获取链路\r\n- 银联 JS：网页授权回调地址、`auth_code -> user_id` 获取链路、`customer_ip`\r\n- 反扫：`auth_code` 获取方式、终端采集能力\r\n- 银联扩展：`front_url`、`payee_info`、`pid_info`\r\n- 分账 / 设备 / 补贴：`acct_split_bunch`、`devs_id`、补贴账户配置\r\n\r\n## 给模型的硬约束\r\n\r\n- 运行时授权值、扫码值、报备值、控台配置值，都不能靠模型猜。\r\n- 前端页面回调、支付完成页、客户端 success 回调，都不能直接当作交易成功终态；按官方开发指引，后端必须再查单确认。\r\n- 如果客户没有提供场景必需值，应该先暴露缺口，而不是直接给出“看起来完整”的代码。\r\n- 查询、关单、退款代码必须复用上游订单沉淀的标识，不要在下游重新假设。\n\nFile v1.3.5:references/aggregation-error-codes.md\n\n# 聚合支付错误码\r\n\r\n> 本页返回码主要用于排查和联调定位，不建议把 `resp_code` 直接写成订单终态逻辑；订单终态仍以 `trans_stat`、异步通知和主动查询结果为准。\n\n## 官方来源与合并规则\n\n- 公共全集：[返回码](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_ywm.md)，包含网关返回码以及扫码类、线上交易、商户进件等业务返回码。\n- 公共字典入口：[基础参数汇总](https://paas.huifu.com/partners/api/doc/csfl/api_csfl.md)。\n- 业务术语：[名词解释](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_mcjs.md)。\n- 本页下方只保留高频码和接口专项码，不是全集。排查时必须把“当前接口页业务返回码”与公共返回码全集合并查看；同一码可能按接口或 `resp_desc` 表示不同原因，不能只按码值做唯一映射。\n- 网关返回码用于判断请求是否到达业务处理层；业务返回码用于接口处理诊断；交易终态仍由交易状态、异步通知和主动查询共同确认。\n\r\n## 通用错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 00000000 | 本次接口处理完成，实际交易结果仍以 `trans_stat` / 查询结果为准 | 继续结合交易状态字段确认终态 |\r\n| 00000100 | 交易正在处理中 | 等待异步通知或轮询查询 |\r\n| 10000000 | 无效参数 | 检查必填字段、格式、长度 |\r\n| 98888888 | 未知系统错误 | 联系汇付技术支持 |\r\n| 99999999 | 系统异常，请稍后重试 | 稍后重试或联系技术支持 |\r\n\r\n## 参数校验类 (10000000)\r\n\r\n| 返回描述 | 处理建议 |\r\n|---------|---------|\r\n| 请求内容体不能为空 | 检查请求 body |\r\n| %s不能为空 | 检查对应必填字段 |\r\n| %s长度固定%d位 | 检查字段长度 |\r\n| %s最大长度为%d位 | 缩短字段值 |\r\n| %s的传入枚举[%s]不存在 | 检查枚举值是否合法 |\r\n| %s不符合%s格式 | 检查日期/金额等格式 |\r\n\r\n## 下单类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 20000000 | 重复交易 | 使用新的 req_seq_id |\r\n| 20000001 | 操作过于频繁 | 稍后重试 |\r\n| 22000000 | 产品配置信息异常 | 检查 product_id 配置 |\r\n| 22000002 | 商户配置信息异常 | 检查 huifu_id |\r\n| 90000000 | 交易受限 / 单笔金额超限 / 交易存在风险 | 查看 resp_desc 详情 |\r\n\r\n## 查询类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 20000004 | 交易不存在 | 检查流水号是否正确 |\r\n| 21000000 | 参数逻辑校验不合法（流水号、全局流水号不能同时为空） | 至少传入一个查询条件 |\r\n\r\n## 关单类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 20000001 | 不允许关闭一分钟以内的订单；官网同码也用于并发冲突 | 结合 `resp_desc` 区分，未满一分钟时等待边界后再查询/关单 |\n| 10000016 | 原订单已为终态,请发起查询交易获取 | 订单已完成，无需关单 |\r\n| 10000018 | 关单失败 | 查看 resp_desc 详情 |\r\n| 23000000 | 原交易订单已失败不允许关单 / 关单状态为终态 | 订单已完成或已关单 |\r\n| 23000004 | 不支持的交易（银联二维码不支持关单） | 银联不支持关单 |\r\n\r\n## 退款类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 10000001 | 原交易没有处理完成 | 等待原交易完成 |\r\n| 10000002 | 退款金额大于可退金额 | 检查退款金额 |\r\n| 10000009 | 该交易不支持部分退款 | 只能全额退款 |\r\n| 21000000 | 原交易请求流水号、商户单号、全局流水号不能同时为空 | 至少传入一个原交易标识 |\r\n| 22000004 | 暂未开通退款权限/分账退款权限 | 联系汇付开通权限 |\r\n| 23000002 | 数据权限不足 / 退款手续费承担方不一致 | 检查手续费配置 |\r\n| 23000003 | 金额校验异常（退款额>可退额 / 余额不足） | 检查退款金额和账户余额 |\r\n| 23000004 | 不支持的交易（预授权撤销/优惠交易部分退款） | 使用其他方式处理 |\r\n| 30000000 | 调用收银台退款接口失败 | 稍后重试 |\r\n| 90000000 | 交易受限 / 可用余额不足 / 交易存在风险 | 查看 resp_desc 详情 |\r\n\r\n## 对账单查询错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 00000000 | 查询成功 | 正常返回 |\r\n| — | 当前huifuId请求过于频繁 | 每天不要超过 3 次查询 |\r\n\r\n## 使用边界\r\n\r\n- `resp_code`、`resp_desc` 主要用于排查，不直接驱动订单成功/失败终态。\r\n- `00000000` 不等于“交易最终成功”，仍要结合 `trans_stat`、异步通知和查单结果判断。\r\n- `00000100` 表示当前接口仍在处理中，应该继续等待异步通知或轮询查询。\r\n- 其他返回码优先结合 `resp_desc`、请求参数、渠道场景和原交易标识排查。\n- 本页未列出的返回码不得直接判为“未知系统错误”；先查公共返回码全集，再结合接口专属码和 `resp_desc` 分类。\n\nFile v1.3.5:references/aggregation-faq.md\n\n# 各渠道常见问题汇总\r\n\r\n\r\n## 目录\r\n\r\n- 微信支付通用问题\r\n- 微信付款码特有问题\r\n- 支付宝支付通用问题\r\n- 银联支付问题\r\n- 对账单问题\r\n\r\n## 微信支付通用问题\r\n\r\n### 业务常见问题\r\n\r\n**Q：支付时显示的商家简称可以修改吗？**\r\nA：可以。登录合作伙伴控台修改，或调用【微信支付宝入驻信息修改】接口。\r\n\r\n**Q：消费者账单侧显示的商品字段如何修改？**\r\nA：对应下单时传入的 `goods_desc`（商品描述）字段，可笔笔指定。\r\n\r\n**Q：支付时如何限制信用卡支付？**\r\nA：发起交易时传入禁用支付方式字段。它属于请求顶层字段，不属于 `method_expand`。\r\n\r\n**Q：支付时是否可以指定入账账户？**\r\nA：支持，传入需入账的账户号，仅支持基本户、现金户。\r\n\r\n**Q：已开通多个微信商户号，支付时如何指定？**\r\nA：通过接口或控台修改微信交易通道配置，预配置默认通道。下单时可通过\"渠道号\"和\"场景类型\"单独指定。\r\n\r\n**Q：支付失败，风控拦截交易（非微信拦截）如何处理？**\r\nA：提供报错描述联系客服，若为可申诉场景按流程提交材料。\r\n\r\n### 微信技术问题\r\n\r\n**Q：报错 \"当前商户需补齐相关资料后，才可进行相应的支付交易\"**\r\n原因：商户未完成微信实名认证。\r\n处理：登录控台完成实名认证，或调用【微信实名认证】接口。\r\n\r\n**Q：报错 \"sub_mch_id与sub_appid不匹配\"**\r\n原因：商户 appid 配置有误。\r\n处理：确认公众号/小程序的 sub_appid 已与商户绑定，可调用【微信商户配置】接口或控台配置。\r\n\r\n**Q：报错 \"sub_appid与sub_openid不匹配\"**\r\n原因：sub_appid 和 sub_openid 获取对应关系有误。\r\n处理：sub_openid 必须从对应的 sub_appid 下获取，不能混用不同公众号/小程序。\r\n\r\n**Q：报错 \"特约子商户该产品权限已被冻结\"**\r\n原因：微信风控关闭商户号支付权限。\r\n处理：处理商户风险问题，申诉通过后恢复支付权限。\r\n\r\n## 微信付款码特有问题\r\n\r\n**Q：付款码支付是否需要输入密码？**\r\nA：一般情况下免密扣款。以下情况需验密：\r\n- 支付金额 > 1000元\r\n- 当天已有10笔免密交易\r\n- 用户查看了付款码数字\r\n- 微信风控判断异常\r\n\r\n## 支付宝支付通用问题\r\n\r\n### 业务常见问题\r\n\r\n**Q：支付时显示的商家简称可以修改吗？**\r\nA：可以。登录控台修改，或调用【微信支付宝入驻信息修改】接口。\r\n\r\n**Q：支付时如何限制信用卡支付？**\r\nA：发起交易时传入禁用支付方式字段。\r\n\r\n### 支付宝技术问题\r\n\r\n**Q：报错 \"当前商户未认证，请通知商户在支付宝搜索'支付宝商家认证助手'小程序，完成认证后开通交易\"**\r\n原因：商户未完成支付宝实名认证。\r\n处理：登录控台完成认证，或调用【支付宝实名申请提交】接口。\r\n\r\n### 支付宝付款码特有问题\r\n\r\n**Q：付款码支付什么时候需要输入密码？**\r\nA：以下场景会唤起支付宝收银台：\r\n- 消费者付款码安全校验未通过\r\n- 支付额度超过代扣额度\r\n- 代扣失败（所有渠道余额不足）\r\n\r\n## 银联支付问题\r\n\r\n**Q：H5页面无法打开？**\r\nA：确认页面地址是否已在银联通过备案，未备案页面无法正常打开。\r\n\r\n**Q：支付时是否可以指定入账账户？**\r\nA：支持，传入需入账的账户号，仅支持基本户、现金户。\r\n\r\n**Q：支付失败，风控拦截交易如何处理？**\r\nA：提供报错描述联系客服，若为可申诉场景按流程提交材料。\r\n\r\n### 银联付款码特有问题\r\n\r\n**Q：付款码支付是否需要输入密码？**\r\nA：一般情况下免密扣款，仅触发验证密码规则后需验密。\r\n\r\n## 对账单问题\r\n\r\n**Q：对账单查询接口返回的文件格式？**\r\nA：常规账单一个链接通常对应一个压缩文件，压缩包内多为 csv。`SETTLE_FUND_BILL` 模板为 `.xlsx`，不要把所有账单都按 csv 解析。单个文件超过 400,000 条时会拆分为多个 csv。\r\n\r\n**Q：对账单什么时候适合下载？**\r\nA：最新产品介绍口径建议按跑批节奏取数：交易/分账文件 03:00 跑批后建议 12:00 再取，出金对账单 10:30 跑批后一小时，结算对账单 17:00 跑批后一小时。\r\n\r\n**Q：对账单能查多久以前的数据？**\r\nA：接口当前支持 1 年内账单下载；控台下载暂未见时间限制说明。\r\n\r\n**Q：交易账单实收金额与结算金额不一致？**\r\nA：计算公式：交易金额 - 交易手续费 - 退款金额 + 退款手续费。还需排除结算周期 > D+1 的交易和资金冻结。\r\n\r\n**Q：报错 \"当前huifuId请求过于频繁\"？**\r\nA：生成对账单有次数限制，每天不超过3次。\r\n\r\n**Q：对账单查询 file_details 为空？**\r\nA：查看 task_details，如果 task_stat 为成功且文件为空，代表前一日无记录。\n\nFile v1.3.5:references/aggregation-java-adapter.md\n\n# Java 适配层\r\n\r\n这份文件只讲 Java 接入。  \r\n协议规则不在这里重复写。\r\n\r\n## 适配范围\r\n\r\n| 项目 | 内容 |\r\n| --- | --- |\r\n| 当前适配 SDK | `dg-lightning-sdk` `1.0.5` |\r\n| 最低运行时 | JDK 1.8+ |\r\n| 初始化入口 | `MerConfig` + `BasePay.initWithMerConfig()` |\n| 主要调用方式 | `Factory.Payment.Common()` |\n\n`dg-lightning-sdk 1.0.5` 的 `BasePay.debug` 默认是 `true`，底层会输出私钥、签名和请求数据。所有初始化必须在任何 `initWithMerConfig(s)` 或业务请求前执行一次 `BasePay.debug = false;`，不得在并发请求中临时切换。\n\r\n## 先看哪些文件\r\n\r\n- `references/aggregation-java-sdk-quickstart.md`\r\n- `references/aggregation-java-tech-spec.md`\r\n- `references/aggregation-async-webhook.md`\r\n\r\n## Java 特有说明\r\n\r\n1. Lightning SDK 的产品号方法名是 `setProductId()`，这里拼写正常。\r\n2. Spring Boot 2.x 和 3.x 的 import 不一样。\r\n   2.x 常见是 `javax.annotation.PostConstruct`\r\n   3.x 常见是 `jakarta.annotation.PostConstruct`\r\n3. 当前仓库的异步通知示例使用了 `fastjson`。\r\n   这是 Java 示例选型，不是协议层要求。\r\n4. `method_expand`、`acct_split_bunch`、`terminal_device_data`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info` 这类字段，仍然建议先在业务层建对象，再在 SDK 边界统一序列化。\r\n5. `T_JSAPI`、`T_MINIAPP`、`T_APP`、`T_MICROPAY`、`A_JSAPI`、`A_NATIVE`、`A_MICROPAY`、`U_JSAPI`、`U_NATIVE`、`U_MICROPAY` 这些值不是 `method_expand` 的 key；`method_expand` 的 JSON 内容直接是当前场景对象本身。\r\n6. `tx_metadata` 本身不作为请求字段上送；交易能力扩展按能力名直接传 `acct_split_bunch`、`terminal_device_data`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info`。\r\n7. `MerConfig.setSkillSource(...)` 直接传 `<skill_source>` 即可；聚合支付要求的 `sys_id` 仍通过独立请求头 `sys_id` / `jpt-sys_id` 传递，`jpt-x-skill-source` 只透传来源值。\r\n8. 当前 Java SDK 基线如果请求参数里的 `huifu_id` 存在且非空，还会自动补 `jpt-x-skill-huifu_id`；该值必须与本次请求的 `huifu_id` 一致，不要手工写成固定常量。\r\n\r\n## 不属于这里的内容\r\n\r\n- 签名规则：看 `references/shared-signing-v2.md`\r\n- 异步通知规则：看 `references/shared-async-notify.md`\r\n- 其他语言入口：看 `references/shared-server-sdk-matrix.md`\n\nFile v1.3.5:references/aggregation-java-sdk-quickstart.md\n\n## 目录\n\n- [SDK 信息](#sdk-信息)\n- [步骤 1：添加 Maven 依赖](#步骤-1添加-maven-依赖)\n- [步骤 2：SDK 初始化](#步骤-2sdk-初始化spring-boot-配置类)\n- [步骤 3：验证核心类导入](#步骤-3验证核心类导入)\n- [Factory 调用模式](#factory-调用模式)\n- [与 dg-java-sdk 的关键差异](#与-dg-java-sdk-的关键差异)\n\n# SDK 安装与初始化\n\n## SDK 信息\n\n| 属性 | 值 |\n|-----|-----|\n| SDK 名称 | dg-lightning-sdk |\n| 当前版本 | 1.0.5 |\n| GroupId | com.huifu.dg.lightning.sdk |\n| ArtifactId | dg-lightning-sdk |\n\n> **说明**：如果项目中同时需要托管支付（dg-java-sdk）和聚合支付（dg-lightning-sdk），两个 SDK 可以共存，各自独立初始化。\n\n## 步骤 1：添加 Maven 依赖\n\n在 `pom.xml` 中添加：\n\n```xml\n<dependency>\n    <groupId>com.huifu.dg.lightning.sdk</groupId>\n    <artifactId>dg-lightning-sdk</artifactId>\n    <version>1.0.5</version>\n</dependency>\n```\n\n如果同时需要托管支付，也添加：\n\n```xml\n<dependency>\n    <groupId>com.huifu.bspay.sdk</groupId>\n    <artifactId>dg-java-sdk</artifactId>\n    <version>3.0.40</version>\n</dependency>\n```\n\n执行安装：\n\n```bash\nmvn clean install\n```\n\n## 步骤 2：SDK 初始化（Spring Boot 配置类）\n\n> **[Spring Boot 3.x 用户必读]** 如果你使用 Spring Boot 3.x（JDK 17/21），`javax.*` 命名空间已迁移至 `jakarta.*`，初始化代码中的 import 需替换。\n\n| Spring Boot 版本 | PostConstruct |\n|-----------------|---------------|\n| 2.x | `javax.annotation.PostConstruct` |\n| 3.x (JDK 17/21) | `jakarta.annotation.PostConstruct` |\n\n> **[产品号方法名]** Lightning SDK 和当前 `dg-java-sdk 3.0.40` 的 `MerConfig` 产品号方法名都使用 `setProductId(...)`。\n\n> **官方 SDK-only**：接入方已确认当前官方 Lightning SDK 不存在本 Skill 曾推断的 TLS 问题。下方初始化可用于官方 SDK 调用；不得改写 `HttpClient`、OkHttp 或自实现 HTTP+签名客户端。\n\n```java\npackage com.yourcompany.huifu.config;\n\nimport com.huifu.dg.lightning.biz.config.MerConfig;\nimport com.huifu.dg.lightning.utils.BasePay;\nimport lombok.extern.slf4j.Slf4j;\nimport org.springframework.beans.factory.annotation.Value;\nimport org.springframework.context.annotation.Configuration;\n\nimport javax.annotation.PostConstruct;\n\n@Configuration\n@Slf4j\npublic class HuifuLightningConfig {\n\n    @Value(\"${huifu.product-id}\")\n    private String productId;\n\n    @Value(\"${huifu.sys-id}\")\n    private String sysId;\n\n    @Value(\"${huifu.rsa-private-key}\")\n    private String rsaPrivateKey;\n\n    @Value(\"${huifu.rsa-public-key}\")\n    private String rsaPublicKey;\n\n    @Value(\"${huifu.skill-source:hfps/1.3.5}\")\n    private String skillSource;\n\n    @Value(\"${huifu.mode:prod}\")\n    private String mode;\n\n    @PostConstruct\n    public void initSdk() throws Exception {\n        // SDK 1.0.5 默认 debug=true，会输出私钥、签名和请求数据。\n        // 必须在任何初始化或请求之前全局关闭，且不得按请求临时切换。\n        BasePay.debug = false;\n\n        // 设置环境模式\n        if (\"test\".equals(mode)) {\n            BasePay.prodMode = BasePay.MODE_TEST;\n            log.info(\"汇付聚合支付SDK: 联调环境\");\n        } else {\n            BasePay.prodMode = BasePay.MODE_PROD;\n            log.info(\"汇付聚合支付SDK: 生产环境\");\n        }\n\n        // 初始化商户配置\n        MerConfig merConfig = new MerConfig();\n        merConfig.setProductId(productId);   // 注意：Lightning SDK 拼写正常\n        merConfig.setSysId(sysId);\n        merConfig.setRsaPrivateKey(rsaPrivateKey);\n        merConfig.setRsaPublicKey(rsaPublicKey);\n        merConfig.setSkillSource(skillSource);\n\n        BasePay.initWithMerConfig(merConfig);  // 注意：throws Exception\n        log.info(\"汇付聚合支付SDK初始化完成\");\n    }\n}\n```\n\n### 多商户配置（可选）\n\n如果需要支持多个商户，使用 `initWithMerConfigs`：\n\n```java\nMap<String, MerConfig> configs = new HashMap<>();\n\n// 多商户初始化同样必须先全局关闭调试输出。\nBasePay.debug = false;\n\nMerConfig config1 = new MerConfig();\nconfig1.setProductId(\"MYPAY\");\nconfig1.setSysId(\"6666000123120001\");\nconfig1.setRsaPrivateKey(\"...\");\nconfig1.setRsaPublicKey(\"...\");\nconfig1.setSkillSource(\"hfps/1.3.5\");\nconfigs.put(\"merchant1\", config1);\n\nMerConfig config2 = new MerConfig();\nconfig2.setSysId(\"6666000123120002\");\nconfig2.setSkillSource(\"hfps/1.3.5\");\n// ... 配置第二个商户\nconfigs.put(\"merchant2\", config2);\n\nBasePay.initWithMerConfigs(configs);\n```\n\n### 自定义超时时间（可选）\n\n```java\nMerConfig merConfig = new MerConfig();\n// ... 基本配置\nmerConfig.setCustomConnectTimeout(\"30000\");              // 连接超时 30s（默认 20s），注意是 String 类型\nmerConfig.setCustomSocketTimeout(\"30000\");               // 读取超时 30s（默认 20s）\nmerConfig.setCustomConnectionRequestTimeout(\"40000\");    // 请求超时 40s（默认 30s）\nmerConfig.setSkillSource(\"hfps/1.3.5\");\n```\n\n## 步骤 3：验证核心类导入\n\n确认以下类可正常导入：\n\n| 类 | 包路径 | 用途 |\n|---|-------|------|\n| BasePay | `com.huifu.dg.lightning.utils.BasePay` | SDK 入口，初始化配置、环境模式 |\n| MerConfig | `com.huifu.dg.lightning.biz.config.MerConfig` | 商户配置对象 |\n| Factory | `com.huifu.dg.lightning.factory.Factory` | 工厂类，获取业务客户端 |\n| CommonPayClient | `com.huifu.dg.lightning.biz.client.CommonPayClient` | 聚合支付客户端 |\n| BasePayException | `com.huifu.dg.lightning.biz.exception.BasePayException` | SDK 异常类 |\n| DateTools | `com.huifu.dg.lightning.utils.DateTools` | 日期工具（`getCurrentDateYYYYMMDD()`） |\n| SequenceTools | `com.huifu.dg.lightning.utils.SequenceTools` | 流水号工具（`getReqSeqId32()`） |\n\n`MerConfig.setSkillSource(...)` 按 `<skill_source>` 原样透传；聚合支付要求的 `sys_id` 仍通过独立请求头 `sys_id` / `jpt-sys_id` 传递，`jpt-x-skill-source` 只承载来源值本身。\n\n## Factory 调用模式\n\nLightning SDK 使用 Factory 模式创建业务客户端，与 dg-java-sdk 的 `BasePayClient.request()` 不同：\n\n```java\nimport com.huifu.dg.lightning.factory.Factory;\nimport com.huifu.dg.lightning.biz.client.CommonPayClient;\nimport com.huifu.dg.lightning.models.payment.*;\n\n// 1. 获取聚合支付客户端\nCommonPayClient client = Factory.Payment.Common();\n\n// 2. 下单\nTradePaymentCreateRequest createReq = new TradePaymentCreateRequest();\n// ... 设置参数\nMap<String, Object> createResp = client.create(createReq);\n\n// 3. 查询\nTradePaymentScanpayQueryRequest queryReq = new TradePaymentScanpayQueryRequest();\n// ... 设置参数\nMap<String, Object> queryResp = client.query(queryReq);\n\n// 4. 关单\nTradePaymentScanpayCloseRequest closeReq = new TradePaymentScanpayCloseRequest();\nMap<String, Object> closeResp = client.close(closeReq);\n\n// 5. 关单查询\nTradePaymentScanpayClosequeryRequest closeQueryReq = new TradePaymentScanpayClosequeryRequest();\nMap<String, Object> closeQueryResp = client.closeQuery(closeQueryReq);\n\n// 6. 退款\nTradePaymentScanpayRefundRequest refundReq = new TradePaymentScanpayRefundRequest();\nMap<String, Object> refundResp = client.refund(refundReq);\n\n// 7. 退款查询\nTradePaymentScanpayRefundQueryRequest refundQueryReq = new TradePaymentScanpayRefundQueryRequest();\nMap<String, Object> refundQueryResp = client.refundQuery(refundQueryReq);\n```\n\n### 添加可选业务参数\n\nCommonPayClient 支持通过 `optional()` 方法添加额外参数：\n\n```java\nCommonPayClient client = Factory.Payment.Common();\nclient.optional(\"notify_url\", \"https://your-domain.com/notify\");\nclient.optional(\"remark\", \"备注信息\");\nMap<String, Object> response = client.create(request);\n```\n\n### 延迟交易客户端\n\n```java\nimport com.huifu.dg.lightning.biz.client.DelayTransClient;\n\nDelayTransClient delayClient = Factory.Solution.DelayTrans();\n// delayClient.confirm()      - 延迟交易确认\n// delayClient.confirmQuery() - 确认查询\n// delayClient.refund()       - 延迟交易退款\n// delayClient.refundQuery()  - 退款查询\n// delayClient.splitQuery()   - 分账查询\n```\n\n## SDK Request 类速查表\n\n| 场景 | Request 类 | 包路径 |\n|------|-----------|-------|\n| 聚合支付下单 | `TradePaymentCreateRequest` | `com.huifu.dg.lightning.models.payment` |\n| 聚合交易查询 | `TradePaymentScanpayQueryRequest` | 同上 |\n| 聚合交易关单 | `TradePaymentScanpayCloseRequest` | 同上 |\n| 聚合交易关单查询 | `TradePaymentScanpayClosequeryRequest` | 同上 |\n| 交易退款 | `TradePaymentScanpayRefundRequest` | 同上 |\n| 交易退款查询 | `TradePaymentScanpayRefundQueryRequest` | 同上 |\n\n## 与 dg-java-sdk 的关键差异\n\n| 对比项 | dg-lightning-sdk | dg-java-sdk |\n|-------|-----------------|------------|\n| 初始化 import | `com.huifu.dg.lightning.*` | `com.huifu.bspay.sdk.opps.*` |\n| MerConfig 包路径 | `com.huifu.dg.lightning.biz.config.MerConfig` | `com.huifu.bspay.sdk.opps.core.config.MerConfig` |\n| BasePay 包路径 | `com.huifu.dg.lightning.utils.BasePay` | `com.huifu.bspay.sdk.opps.core.BasePay` |\n| 设置产品号 | `setProductId()` | `setProductId()` |\n| 调用方式 | `Factory.Payment.Common().create(req)` | `BasePayClient.request(req, false)` |\n| 扩展参数 | `client.optional(key, value)` | `request.setExtendInfo(map)` |\n| HTTP 客户端 | Apache HttpClient 4.5.2 | OkHttp |\n\nFile v1.3.5:references/aggregation-java-tech-spec.md\n\n# 技术规范\r\n\r\n\r\n## 目录\r\n\r\n- 请求协议与报文模型\r\n- 签名规则\r\n- 异步通知\r\n- HTTP 连接池配置\r\n- 重试策略\r\n- API 版本\r\n\r\n## 请求协议与报文模型\r\n\r\n| 项目 | 说明 |\r\n|------|------|\r\n| 通信协议 | HTTPS |\r\n| 请求方式 | POST |\r\n| 数据格式 | JSON |\r\n| 字符编码 | UTF-8 |\r\n| 建议头 | `Content-Type: application/json;charset=UTF-8` |\r\n\r\n请求模型：\r\n\r\n```json\r\n{\r\n  \"sys_id\": \"调用方 huifu_id\",\r\n  \"product_id\": \"产品号\",\r\n  \"sign\": \"请求签名\",\r\n  \"data\": {\r\n    \"业务字段\": \"值\"\r\n  }\r\n}\r\n```\r\n\r\n响应模型：\r\n\r\n```json\r\n{\r\n  \"sign\": \"返回签名\",\r\n  \"data\": {\r\n    \"resp_code\": \"00000000\",\r\n    \"resp_desc\": \"处理成功\"\r\n  }\r\n}\r\n```\r\n\r\n## 签名规则\r\n\r\n### 请求签名\r\n\r\n1. 将请求 `data` 对象序列化为 JSON\r\n2. 对 JSON 中所有对象的 key 按 ASCII 值排序（数组不排序）\r\n3. 使用商户 RSA 私钥对排序后的 JSON 字符串进行 SHA256WithRSA 签名\r\n4. 将签名结果 Base64 编码后填入 `sign` 字段\r\n\r\n> SDK 自动完成以上步骤，开发者无需手动处理。\r\n\r\n### 响应验签\r\n\r\nSDK 自动使用汇付 RSA 公钥验证响应签名，验签失败时抛出 `BasePayException`。\r\n\r\n### RSA 密钥格式\r\n\r\n- 私钥格式：PKCS#8（Base64 编码）\r\n- 公钥格式：X.509（Base64 编码）\r\n\r\n## 异步通知\r\n\r\n### 通知机制\r\n\r\n聚合支付支持两种异步通知方式：\r\n\r\n1. **notify_url 回调**：下单时传入 `notify_url`，交易完成后汇付 POST 通知到该地址\r\n2. **Webhook 事件**：通过汇付控台配置 Webhook 接收端，支持以下事件：\r\n   - `trans.close` — 关单事件\r\n\r\n### notify_url 接收规范\r\n\r\n- **请求方式**：POST\r\n- **报文形态**：交易类回调通常提交 `sign` 和 `resp_data` 字段，业务字段位于 `resp_data`\r\n- **响应要求**：HTTP 200，body 返回 `RECV_ORD_ID_` + req_seq_id（5 秒内）\r\n- **重试策略**：超时未响应最多重试 3 次\r\n- **幂等键**：以 `hf_seq_id` 为最简幂等键，防止重复处理（完整口径见 `references/shared-async-notify.md`，建议复合键）\r\n\r\n以下示例为流程片段。`HttpServletRequest` 在 Spring Boot 2.x 使用 `javax.servlet.*`，在 3.x 使用 `jakarta.servlet.*`；`huifuPublicKey` 的注入方式可直接参考 `references/aggregation-async-webhook.md` 中的完整类示例。\r\n\r\n```java\r\n@PostMapping(\"/notify\")\r\npublic String handleNotify(HttpServletRequest request) {\r\n    String respData = request.getParameter(\"resp_data\");\r\n    String sign = request.getParameter(\"sign\");\r\n    if (!RsaUtils.verify(respData, huifuPublicKey, sign)) {\r\n        throw new IllegalArgumentException(\"汇付回调验签失败\");\r\n    }\r\n\r\n    JSONObject notification = JSON.parseObject(respData);\r\n    String reqSeqId = notification.getString(\"req_seq_id\");\r\n    String hfSeqId = notification.getString(\"hf_seq_id\");\r\n    String transStat = notification.getString(\"trans_stat\");\r\n\r\n    if (isProcessed(hfSeqId)) {\r\n        return \"RECV_ORD_ID_\" + reqSeqId;\r\n    }\r\n\r\n    // 先查单确认，再按 trans_stat 驱动订单状态\r\n    if (\"S\".equals(transStat)) {\r\n        // 交易成功\r\n    } else if (\"F\".equals(transStat)) {\r\n        // 交易失败\r\n    }\r\n\r\n    return \"RECV_ORD_ID_\" + reqSeqId;\r\n}\r\n```\r\n\r\n### Webhook 使用\r\n\r\nWebhook 是汇付提供的事件通知机制，与 notify_url 独立，可在汇付控台灵活配置接收端。\r\n\r\n配置方式参见汇付文档：[Webhook 使用说明](https://paas.huifu.com/open/doc/devtools/#/webhook/webhook_jieshao)\r\n\r\nWebhook 与 API 的签名密钥不是一套：\r\n\r\n- API 请求和 `notify_url` 回调使用 RSA 密钥体系。\r\n- Webhook 使用控台配置的终端密钥，对原始事件体计算 MD5。\r\n- Webhook 不使用汇付 RSA 公钥验签，也不要靠 `sign` 长度自动猜算法。\r\n- 详细说明见 `references/aggregation-async-webhook.md`。\r\n\r\n## HTTP 连接池配置\r\n\r\nSDK 内置 Apache HttpClient 连接池，默认配置：\r\n\r\n| 参数 | 默认值 |\r\n|------|-------|\r\n| 最大连接数 | 500 |\r\n| 每路由最大连接数 | 40 |\r\n| 每主机最大连接数 | 100 |\r\n| Socket 超时 | 20 秒 |\r\n| 连接超时 | 20 秒 |\r\n| 连接请求超时 | 30 秒 |\r\n\r\n可通过 MerConfig 自定义超时：\r\n\r\n```java\r\nmerConfig.setCustomConnectTimeout(\"30000\");\nmerConfig.setCustomSocketTimeout(\"30000\");\nmerConfig.setCustomConnectionRequestTimeout(\"40000\");\n```\r\n\r\n## 重试策略\r\n\r\nSDK 内置 HTTP 处理器最多形成 3 次总尝试，即至多 2 次重试；带实体的支付 POST 请求不自动重试。`NoHttpResponseException` 等条件只适用于处理器允许的非实体请求，不能解释成支付业务自动重试。SSL 错误、Socket 超时和 SSL 握手失败不重试；任何网络不确定结果都先按原请求标识查单，不得另造流水重提。\n\r\n## API 版本\r\n\r\n聚合支付接口涉及不同的 API 版本：\r\n\r\n| 接口 | API 路径 | 版本 |\r\n|------|---------|------|\r\n| 聚合支付下单 | /v4/trade/payment/create | v4 |\r\n| 聚合交易查询 | /v4/trade/payment/scanpay/query | v4 |\r\n| 交易退款 | /v4/trade/payment/scanpay/refund | v4 |\r\n| 交易退款查询 | /v4/trade/payment/scanpay/refundquery | v4 |\r\n| 聚合交易关单 | /v2/trade/payment/scanpay/close | v2 |\r\n| 聚合交易关单查询 | /v2/trade/payment/scanpay/closequery | v2 |\r\n| 对账单查询 | /v2/trade/check/filequery | v2 |\r\n\r\n> SDK 自动处理 API 路径路由，开发者无需关心版本差异。\n\nFile v1.3.5:references/aggregation-order-errors.md\n\n# 聚合下单返回码与勘误\r\n\r\n\r\n## 目录\r\n\r\n- 聚合正扫 / JS / APP 业务返回码\r\n- 聚合反扫业务返回码\r\n- 文档勘误与实现备注\r\n\r\n## 聚合正扫 / JS / APP 业务返回码\r\n\r\n| 返回码 | 返回描述 |\r\n|--------|----------|\r\n| `00000000` | 交易受理成功；交易状态以 `trans_stat` 为准 |\r\n| `00000100` | 下单成功 |\r\n| `10000000` | 产品号不能为空 |\r\n| `10000000` | 交易类型不能为空 |\r\n| `10000000` | `%s` 不能为空 |\r\n| `10000000` | `%s` 长度固定 `%d` 位 |\r\n| `10000000` | `%s` 最大长度为 `%d` 位 |\r\n| `10000000` | `%s` 的传入枚举 `[%s]` 不存在 |\r\n| `10000000` | `%s` 不符合 `%s` 格式，例如交易金额格式错误 |\r\n| `10000000` | 订单已超时 |\r\n| `20000000` | 重复交易 |\r\n| `21000000` | 手续费金额、手续费收取方式、手续费扣款标识、手续费子客户号、手续费账户号必须同时为空或同时必填 |\r\n| `22000000` | 产品号不存在 |\r\n| `22000000` | 产品号状态异常 |\r\n| `22000002` | 商户信息不存在 |\r\n| `22000002` | 商户状态异常 |\r\n| `22000003` | 延迟账户不存在 |\r\n| `22000003` | 商户账户信息不存在 |\r\n| `22000004` | 暂未开通分账权限 |\r\n| `22000004` | 暂未开通 `%s` 权限 |\r\n| `22000004` | 暂未开通延迟入账权限 |\r\n| `22000005` | 手续费承担方必须参与分账 |\r\n| `22000005` | 分账列表必须包含主交易账户 |\r\n| `22000005` | 其他商户分账比例过高 |\r\n| `22000005` | 商户入驻信息配置有误(多通道) |\r\n| `22000005` | 商户分期贴息未激活 |\r\n| `22000005` | 分期交易不能重复激活 |\r\n| `22000005` | 手续费配置有误 |\r\n| `22000005` | 商户贴息信息未配置 |\r\n| `22000005` | 花呗分期费率配置有误 |\r\n| `22000005` | 分账配置有误 |\r\n| `22000005` | 分账配置未包含手续费承担方 |\r\n| `22000005` | 商户入驻配置信息有误 |\r\n| `22000005` | 商户支付宝 / 微信入驻信息配置有误 |\r\n| `22000005` | 商户银联入驻信息配置有误 |\r\n| `22000005` | 商户贴息分期费率未配置渠道号 |\r\n| `22000005` | 商户贴息分期费率未配置费率类型 |\r\n| `22000005` | 商户贴息分期费率配置有误 |\r\n| `22000005` | 手续费费率未配置 |\r\n| `22000005` | 手续费计算错误 |\r\n| `22000005` | 商户贴息信息配置有误 |\r\n| `22000005` | 商户未报名活动或活动已过期 |\r\n| `22000005` | 数字货币手续费费率未配置 |\r\n| `22000005` | 数字货币手续费配置有误 |\r\n| `22000005` | 商户未配置默认入驻信息（多通道） |\r\n| `23000003` | 交易金额不足以支付内扣手续费 |\r\n| `23000003` | 优惠金额大于交易金额 |\r\n| `23000004` | 交易类型不支持 |\r\n| `23000004` | 当前交易类型不支持商户贴息 |\r\n| `90000000` | 业务执行失败，例如账户可用余额不足 |\r\n| `90000000` | 该功能已关闭，请联系客服 |\r\n| `90000000` | 交易失败，单日金额超限，请联系额服提额 |\r\n| `90000000` | 交易存在风险 |\r\n| `91111119` | 通道异常，请稍后重试 |\r\n| `98888888` | 系统错误 |\r\n\r\n## 聚合反扫业务返回码\r\n\r\n| 返回码 | 返回描述 |\r\n|--------|----------|\r\n| `10000000` | 不支持交易类型 |\r\n| `10000000` | 订单时间错误 |\r\n| `10000000` | 付款码格式异常 |\r\n| `10000000` | 请求日期必须是当前日期 |\r\n| `10000000` | `%s` 不能为空 |\r\n| `10000000` | `%s` 不符合 `%s` 格式 |\r\n| `10000000` | `%s` 长度固定 `%d` 位 |\r\n| `10000000` | `%s` 最大长度为 `%d` 位 |\r\n| `10000000` | `%s` 的传入枚举 `[%s]` 不存在 |\r\n| `10000000` | 产品号、原预授权交易请求流水、请求日期都不能为空 |\r\n| `21000000` | 手续费金额、手续费收取方式、手续费扣款标识、手续费子客户号、手续费账户号必须同时为空或同时必填 |\r\n| `22000002` | 商户信息不存在 |\r\n| `22000002` | 商户状态异常 |\r\n| `22000002` | 商户和产品的关联信息有误 |\r\n| `22000003` | 账户信息配置有误 / 账户信息不存在 |\r\n| `22000003` | 默认账户配置有误 |\r\n| `22000004` | 商户支付交易业务配置错误 / 细化指定需要的功能 |\r\n| `22000004` | 暂未开通分账权限 |\r\n| `22000004` | 暂未开通延时入账权限 |\r\n| `22000005` | 分账串配置未包含手续费承担方 |\r\n| `22000005` | 其他成员分账比例过高 |\r\n| `22000005` | 分账列表必须包含主交易账户 |\r\n| `22000005` | 内扣交易，手续费承担方必须参与分账 |\r\n| `22000005` | 商户未配置默认入驻信息(多通道) |\r\n| `22000005` | 商户贴息分期费率有误 |\r\n| `22000005` | 商户贴息分期费率未配置费率类型 |\r\n| `22000005` | 商户贴息分期费率未配置渠道号 |\r\n| `22000005` | 商户多通道配置有误 |\r\n| `22000005` | 商户入驻信息配置有误(多通道) |\r\n| `22000005` | 分账配置有误 |\r\n| `22000005` | 分账比例配置有误 |\r\n| `22000005` | 该交易暂未配置支付费率 |\r\n| `22000005` | 商户支付宝微信入驻信息配置有误 |\r\n| `22000005` | 多通道入驻信息配置有误 |\r\n| `22000005` | 商户银联入驻信息配置有误 |\r\n| `23000001` | 原预授权交易不存在 |\r\n| `23000003` | 交易金额不足以支付手续费 |\r\n| `23000003` | 优惠金额大于交易金额 |\r\n| `23000003` | 分账金额总和必须等于交易金额 |\r\n| `23000004` | 交易类型不支持 |\r\n| `90000000` | 业务执行失败，付款码无效，请重新扫码 |\r\n| `90000000` | 业务执行失败，每个二维码仅限使用一次，请刷新再试 |\r\n| `90000000` | 业务执行失败，付款码已过期，请退出重试 |\r\n| `90000000` | 业务执行失败，当前商户需补齐相关资料后才可进行支付交易，请商户联系服务商 |\r\n| `90000000` | 交易存在风险 |\r\n| `98888888` | 系统错误 |\r\n| `91111119` | 通道异常，请稍后重试 |\r\n| `99999999` | 系统异常，请重试 |\r\n| `00000000` | 交易受理成功；交易状态以 `trans_stat` 为准 |\r\n| `00000100` | 交易正在处理中 |\r\n\r\n## 文档勘误与实现备注\r\n\r\n- 官方顶部“支持的支付方式”列表漏写了 `T_APP`，但请求参数 `trade_type` 枚举明确包含 `T_APP`；当前按参数表收录。\r\n- 官方请求参数把 `req_date` 标成 `N`，但 SDK 示例和回调字段都依赖它；实现时仍建议始终传入。\r\n- 官方请求参数把 `method_expand` 标成 `Y`，但是否真正必填取决于 `trade_type`；例如 `A_NATIVE`、`U_NATIVE` 并不是每次都有强制子字段。\r\n- 官方 `A_JSAPI` / `A_NATIVE` 表中 `body` 与重复的 `ali_promo_params` 行被拼到了同一行；当前按两个独立字段理解。\r\n- 同步返回里字段名是 `trade_type`，异步回调里字段名是 `trans_type`；不要混用。\r\n- 同步返回 `trade_type` 的官方枚举含 `D_NATIVE`、`T_H5`、`T_NATIVE`，但当前请求参数页并未把这些值列入下单枚举；不要据此自行扩展请求值。\r\n- 官方另有 Webhook 能力说明，但它属于事件分发机制，不是本接口固定响应体结构。\n\nArchive v1.3.4: 105 files, 419199 bytes\n\nFiles: agents/openai.yaml (404b), references/aggregation-async-webhook.md (7041b), references/aggregation-base.md (3287b), references/aggregation-common-params.md (7171b), references/aggregation-customer-preparation.md (10271b), references/aggregation-error-codes.md (5180b), references/aggregation-faq.md (5044b), references/aggregation-java-adapter.md (2502b), references/aggregation-java-sdk-quickstart.md (9469b), references/aggregation-java-tech-spec.md (5478b), references/aggregation-order-errors.md (7063b), references/aggregation-order-method-alipay.md (7765b), references/aggregation-order-method-unionpay.md (4190b), references/aggregation-order-method-wechat.md (7071b), references/aggregation-order-quickstart.md (2826b), references/aggregation-order-request.md (11876b), references/aggregation-order-response.md (10548b), references/aggregation-order-tx-metadata.md (11529b), references/aggregation-order.md (3912b), references/aggregation-payload-construction.md (10005b), references/aggregation-php-adapter.md (10872b), references/aggregation-python-adapter.md (7071b), references/aggregation-python-scenarios.md (7929b), references/aggregation-query-close-query.md (7479b), references/aggregation-query-payment-query.md (21752b), references/aggregation-query-php-scenarios.md (9123b), references/aggregation-query-quickstart.md (1509b), references/aggregation-query-reconciliation.md (9371b), references/aggregation-query-trade-close.md (7889b), references/aggregation-query.md (3522b), references/aggregation-quickstart.md (3616b), references/aggregation-refund-query.md (9071b), references/aggregation-refund-quickstart.md (1362b), references/aggregation-refund.md (15213b), references/canonical-regression-prompts.md (2612b), references/checkout-js-callback-and-confirmation.md (2350b), references/checkout-js-component-modes.md (2664b), references/checkout-js-create-preorder-contract.md (3381b), references/checkout-js-framework-integration-notes.md (1806b), references/checkout-js-integration-flow.md (3260b), references/checkout-js-readme.md (1549b), references/checkout-js.md (2364b), references/copilot-existing-system.md (4883b), references/copilot-go-live-checklist.md (3136b), references/copilot-onboarding.md (5174b), references/copilot-parameter-review.md (2960b), references/copilot-solution-cards.md (8682b), references/copilot-solution-selection.md (3370b), references/copilot-troubleshooting-playbooks.md (7672b), references/hostingpay-async-webhook.md (11437b), references/hostingpay-base.md (2218b), references/hostingpay-common-params.md (6572b), references/hostingpay-customer-preparation.md (9974b), references/hostingpay-error-codes.md (4399b), references/hostingpay-faq.md (4983b), references/hostingpay-java-adapter.md (2201b), references/hostingpay-java-sdk-quickstart.md (6639b), references/hostingpay-java-tech-spec.md (11425b), references/hostingpay-payload-construction.md (7898b), references/hostingpay-php-adapter.md (11872b), references/hostingpay-preorder-alipay-mini.md (23087b), references/hostingpay-preorder-douyin-direct.md (14269b), references/hostingpay-preorder-h5-pc-channel.md (9875b), references/hostingpay-preorder-h5-pc-errors.md (1284b), references/hostingpay-preorder-h5-pc-request.md (10144b), references/hostingpay-preorder-h5-pc-response-channel.md (11665b), references/hostingpay-preorder-h5-pc-response.md (6402b), references/hostingpay-preorder-h5-pc.md (9489b), references/hostingpay-preorder-php-scenarios.md (10210b), references/hostingpay-preorder-quickstart.md (7869b), references/hostingpay-preorder-wechat-mini.md (27034b), references/hostingpay-preorder.md (3817b), references/hostingpay-python-adapter.md (7092b), references/hostingpay-python-scenarios.md (9321b), references/hostingpay-query-payment-status-query.md (24116b), references/hostingpay-query-php-scenarios.md (6657b), references/hostingpay-query-quickstart.md (5206b), references/hostingpay-query-reconciliation.md (12588b), references/hostingpay-query-splitpay.md (9081b), references/hostingpay-query-trade-close.md (7713b)\n\nFile v1.3.4:SKILL.md\n\n---\nname: huifu-pay-integration\ndescription: \"汇付支付交易集成：用于聚合支付、托管支付、checkout-js、下单、查单、关单、退款、对账、支付通知、签名验签、请求头、幂等、交易终态、本地沙箱和支付上线；不用于企业/个人商户进件、图片上传、商户业务开通、商户详情或申请状态查询，这些任务使用 huifu-merchant-onboarding。\"\n---\n\n# 汇付支付集成\n\n## 版权声明\n\n本 Skill 中的汇付支付资料整理自上海汇付支付有限公司官方开放平台与官方产品文档；原始文档及其更新维护权归汇付支付官方所有。仅作技术学习交流与接口集成辅助使用，详见 `references/shared-copyright-notice.md`。\n\n## 执行流程\n\n1. 识别产品线、Endpoint、接入阶段、技术栈、端形态、当前目标和是否存量系统。完成标准：这些维度均已唯一确定，极速版产品场景与 V4 API 枚举已分开。\n2. 检查下方硬检查点；命中时停止生成可运行实现，只问一个最高优先级问题。完成标准：已记录命中或未命中的具体理由，SDK 传输安全和调试日志均已检查。\n3. 从精确路由中选择 3–5 份 reference。只有用户同时提出两个独立目标时才合并；完整 DTO、响应或嵌套字段任务必须包含完整字段目录。完成标准：每个目标均有一跳可达的原子接口页、合同定位路径、实际 JSON/解码路径（分别记录 wire 字段路径与 String(JSON) 解码后路径）和明确语言 adapter，不使用“对应文档”占位，也不把官网展示分组当成 wire key；只有官网明确标注“方便文档展示”时才从 wire 路径移除该分组。\n4. 首次接入输出产品线判断和方案卡；存量接入输出新增、保留、人工确认和回归检查。完成标准：请求、前端交接、通知、终态和补偿查询责任均已落到具体组件。\n5. 最后应用签名、验签、幂等、终态确认、请求字段保留和凭据安全规则。完成标准：每项均已检查，未知合同明确标记并停止生成相应实现。\n\n字段说明中的链接按其用途处理：完整字段目录已将官网 `#锚点` / 相对链接解析到各自接口原始页，并保留相对地址原文；绝对地址保持官网值。已确认的坏锚点使用显式映射：`#业务返回码` 补公共返回码全集，聚合下单 `notify_url` 的“异步返回参数”同时映射正扫、反扫通知参数和通用异步消息规范。只有命中本次字段的规范文档、编码表或渠道指引才作为外部资料提示。`notify_url`、`jump_url`、下载地址、二维码等裸 URL 示例是运行时值或格式示例，不是默认值、推荐地址或外部资料。\n\n本 Skill 只处理支付交易。企业、个人商户进件、图片资料、业务开通、商户详情和申请状态使用 `$huifu-merchant-onboarding`；不要从本 Skill 读取进件实现文档。\n\n## 精确路由\n\n| 场景 | 最小 reference 集 |\n| --- | --- |\n| 首次接入、产品线不明 | `references/shared-overview.md`、`references/copilot-onboarding.md`、`references/copilot-solution-selection.md` |\n| 存量系统接入 | `references/copilot-existing-system.md`、`references/copilot-solution-selection.md` |\n| 聚合支付快速接入 | `references/aggregation-quickstart.md`、`references/aggregation-customer-preparation.md` |\n| 聚合下单参数或代码 | `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` 补微信/支付宝/银联分册 |\n| 聚合交易查询 | `references/aggregation-query-payment-query.md` |\n| 返回码、公共编码或术语 | `aggregation-error-codes.md`、`aggregation-common-params.md`；具体字段仍补对应原子接口页 |\n| 聚合关单 | `references/aggregation-query-trade-close.md` |\n| 聚合对账 | `references/aggregation-query-reconciliation.md` |\n| 聚合退款或退款查询 | `references/aggregation-refund.md`、`references/payment-complete-field-catalog.md`，查询时补 `references/aggregation-refund-query.md` |\n| 托管支付快速接入 | `references/hostingpay-quickstart.md`、`references/hostingpay-customer-preparation.md` |\n| 托管预下单 | `references/hostingpay-preorder.md`、`references/payment-complete-field-catalog.md`，再按端形态补一个原子文档 |\n| 抖音直连、`pre_order_type=4` | `references/hostingpay-preorder.md`、`references/hostingpay-preorder-douyin-direct.md` |\n| 拆单支付查询、`splitpay/query` | `references/hostingpay-query.md`、`references/hostingpay-query-splitpay.md`；完整 DTO 同时执行下方完整字段目录路由 |\n| 托管退款 | `references/hostingpay-refund.md`；完整 DTO 同时执行下方完整字段目录路由，Java setter 问题补 `references/hostingpay-faq.md` |\n| 托管普通交易查询 | `references/hostingpay-query.md`、`references/hostingpay-query-payment-status-query.md` |\n| 托管交易关单 | `references/hostingpay-query.md`、`references/hostingpay-query-trade-close.md` |\n| 托管退款查询 | `references/hostingpay-refund.md`、`references/hostingpay-refund-query.md`；完整 DTO 同时执行下方完整字段目录路由 |\n| 托管对账 | `references/hostingpay-query.md`、`references/hostingpay-query-reconciliation.md` |\n| checkout-js 已完成服务端前置 | `references/checkout-js.md`、`references/checkout-js-callback-and-confirmation.md`、`references/hostingpay-async-webhook.md` |\n| checkout-js 前置未确认 | `references/checkout-js-create-preorder-contract.md`，触发硬检查点 |\n| 支付通知、重复通知、幂等 | `references/shared-async-notify.md`、`references/copilot-troubleshooting-playbooks.md` |\n| 控台 Webhook 验签 | `references/shared-webhook-signing.md` |\n| Java / PHP / Python SDK | 先读 `references/shared-server-sdk-matrix.md`；再按语言与产品线精确选择 `references/aggregation-java-adapter.md`、`references/hostingpay-java-adapter.md`、`references/aggregation-php-adapter.md`、`references/hostingpay-php-adapter.md`、`references/aggregation-python-adapter.md` 或 `references/hostingpay-python-adapter.md` |\n| 请求头和 `skill_source` | `references/shared-request-header-policy.md` |\n| DTO/Controller 字段保留 | `references/shared-request-field-preservation.md` |\n| 完整 DTO、完整响应、嵌套字段或同名字段核对 | 对应原子接口页、`references/payment-complete-field-catalog.md`；代码任务再补语言 adapter |\n| appid/openid、支付路由、对账或资金运营 FAQ | `references/payment-operations-faq.md`、`references/copilot-troubleshooting-playbooks.md` |\n| 本地沙箱 | `references/shared-local-sandbox.md`，再补通知、查询或上线检查 |\n| 上线前检查 | `references/copilot-go-live-checklist.md`、`references/copilot-existing-system.md` |\n| 版本与升级 | `references/skill-version-policy.md` |\n\n按语言选择 reference：\n\n- Java：公共矩阵 + 产品线 Java adapter；先核对项目中的实际 SDK 版本和 Request 类。\n- PHP：公共矩阵 + 产品线 PHP adapter；保留安全初始化顺序，但不得使用会启用 `DEBUG=true` 的官方 Demo/Composer loader。\n- Python：公共矩阵 + 产品线 Python adapter；不要把 SDK 网络重试解释成业务重试。\n- 前端：checkout-js 只负责展示与前端事件，支付终态仍由服务端确认。\n\n## 🔴 CHECKPOINT · HARD STOP\n\n命中以下任一情况时，首行输出 `🔴 CHECKPOINT · HARD STOP：硬检查点。`，列出当前判断和本轮 references，只问一个最高优先级问题：\n\n1. 无法区分聚合支付、托管支付和 checkout-js。\n2. 无法区分服务端接入、前端页面接入和最终状态确认。\n3. 用户要求现成可运行代码，但当前接口、端形态或回退路径不唯一。\n4. checkout-js 的托管预下单、支付通知验签/幂等和查单补偿未确认。\n5. 用户要求联调或生产代码，但缺少环境、系统号、产品号、商户号、RSA 密钥安全来源、通知地址或必要渠道标识。未显式配置 `skill_source` 时使用下述确定性默认值，不因此硬停。\n6. 本地 SDK 源码与文档在请求头、签名、版本或能力覆盖上冲突。\n7. 用户要求 PHP 联调或生产可运行代码，但不能证明在加载 SDK、Demo/Composer 配置和调用 `BsPay::init` 之前已将全局 `DEBUG` 固定为 `false`，或仍使用会定义 `DEBUG=true` 的官方 Demo/Composer 入口。\n\nSDK 安装、初始化和安全 loader 骨架不因产品线不明而硬停，但不得猜具体业务 Request 或字段；PHP 骨架必须在加载任何 SDK 文件前拒绝 `DEBUG=true`。\n\n## 支付终态与通知\n\n- 同步受理成功、`jump_url`、浏览器回跳和前端 callback 都不是支付终态。\n- 对支付通知先验签，再校验金额、商户号、订单号和状态，最后做幂等更新。\n- 通知缺失时使用官方查单补偿；不要伪造通知、跳过验签或直接改成功。\n- 控台 Webhook 和接口 `notify_url` 是不同协议，不能混用签名位置或 ACK。\n- 聚合下单的同一个 `notify_url` 同时承接正扫和反扫两套通知参数；按 `trade_type` 分场景解析，不得只实现一套。\n\n## 请求和凭据\n\n- 保留 Controller/DTO 已接收的 `req_date`、`req_seq_id`、金额、商户号和原交易定位键；缺失或非法时报错，不自行重写。\n- 私钥、系统号和生产商户号只能从服务端安全配置读取，不能写入前端、日志、仓库或回答示例。\n- PHP `2.0.30` 默认 `DEBUG=false`，但官方 `BsPayDemo/loader.php` 与 `Composer/BsPayConfig.php` 会在初始化前启用调试；调试日志会包含带 RSA 私钥的 `MerConfig`、完整请求和响应。联调/生产必须拒绝这些入口，并在加载任何 SDK 文件前固定 `DEBUG=false`。\n- 未显式配置 `skill_source` 时，按当前请求实际加载并参与生成的 Skill 集合取值：仅本 Skill 使用 `hfps/1.3.4`；支付与进件两个 Skill 都参与当前请求时使用 `hfps/1.3.4;hfms/1.0.1`。仅安装在仓库但未参与当前请求不计入；顺序固定为支付、进件，使用一个英文分号且不加空格。\n- 调用方显式提供经确认的 `skill_source` 合同值时原样透传；不得再追加 `sys_id`。\n- 不因方便绕过 SDK 的签名、验签、证书或请求头路径。\n\n## 官方 SDK-only 传输规则\n\n- 接入方已确认官方 Lightning Java `1.0.5`、通用 Java `3.0.40`、PHP `2.0.30` 和 Python `2.0.24` SDK 不存在本 Skill 曾从历史源码快照推断的 TLS 问题；不得再据此触发 Java/PHP TLS 硬停。\n- Java、PHP、Python 的真实请求都必须使用对应官方 SDK 的 Request/facade/client；不得为了“规避 TLS”或补齐语言示例而改写 `HttpClient`、OkHttp、Guzzle、curl 或自实现 HTTP+签名/验签客户端。\n- SDK 缺少专属 Request 时先核对官方通用调用入口；仍无官方能力证据则明确报告能力缺口，不得用手写 HTTP 静默补位。\n- TLS 证书链和主机名校验属于部署环境的常规上线检查。不得关闭校验或安装信任所有证书的自定义实现，但该检查不构成针对当前官方 Java/PHP SDK 的预设硬停。\n\n## 本地沙箱边界\n\n本地沙箱仅验证本地协议闭环、状态机、幂等、故障注入和报告，不验证真实商户权限、通道、费率、风控、资金结果或生产准入。冻结的 `r1–r4` 合同和样例包属于历史支付证据，不得因本次 Skill 拆分改名或重算。\n\n## 输出要求\n\n回答至少包含：\n\n1. 当前产品线、阶段、技术栈和存量判断。\n2. 本轮实际使用的 3–5 份 references。\n3. 请求、通知、终态和安全边界。\n4. 缺失信息、人工确认项和下一步。\n\n不要输出费率、合规、通道准入或生产失败责任结论；只整理脱敏升级材料并转人工确认。\n\n## 当前版本\n\n| 项目 | 口径 |\n| --- | --- |\n| Skill 版本 | `1.3.4` |\n| 能力范围 | 聚合支付、托管支付、checkout-js、支付通知、SDK、本地沙箱和支付上线 |\n| 进件能力 | 已迁移至独立 `$huifu-merchant-onboarding` |\n| 聚合支付 Java SDK | `dg-lightning-sdk 1.0.5` |\n| 托管支付 Java SDK | `dg-java-sdk 3.0.40` |\n| PHP SDK | `huifurepo/dg-php-sdk 2.0.30` |\n| Python SDK | `dg-sdk 2.0.24`，import 为 `dg_sdk` |\n\nFile v1.3.4:_meta.json\n\n{\n  \"ownerId\": \"kn7as5mtmp7qjv21jr9n15qth182kat3\",\n  \"slug\": \"huifu-pay-integration\",\n  \"version\": \"1.3.4\",\n  \"publishedAt\": 1786972999283\n}\n\nFile v1.3.4:references/aggregation-async-webhook.md\n\n# 异步通知与 Webhook\r\n\r\n> 本文面向 `references/aggregation-base.md` 依赖的聚合支付 Skill，重点把交易通知的真实报文形态、验签方式、幂等和终态判断说明清楚。\r\n\r\n\r\n## 目录\r\n\r\n- 两种异步机制\r\n- `notify_url` 使用规范\r\n- 聚合交易通知报文形态\r\n- Spring Boot 接收、验签与查单示例\r\n- 终态判断原则\r\n- 签名差异\r\n- Webhook 使用场景\r\n- Webhook 落地步骤\r\n- Webhook 重发规则\r\n- 使用建议\r\n- 参考\r\n\r\n## 两种异步机制\r\n\r\n| 机制 | 入口 | 用途 | 签名方式 |\r\n|------|------|------|----------|\r\n| `notify_url` | 下单、退款等接口请求参数 | 交易结果回调 | 汇付 RSA 公钥验签 |\r\n| Webhook | 汇付控台端点订阅 | 平台事件通知 | 终端密钥 + MD5 原始事件体 |\r\n\r\n## `notify_url` 使用规范\r\n\r\n- 汇付以 HTTP `POST` 发送交易结果。\r\n- 响应必须在 5 秒内返回。\r\n- 正确应答格式为：HTTP `200` + `RECV_ORD_ID_` + `req_seq_id`。\r\n- 未及时应答或应答格式不正确时，汇付会自动重试，最多 3 次。\r\n- 自定义端口需落在 `8000-9005`。\r\n- URL 不要带查询参数。\r\n- 同一笔交易可能会重复通知，必须用 `hf_seq_id` 做幂等。\r\n\r\n## 聚合交易通知报文形态\r\n\r\n聚合支付的交易类异步通知，外层通常包含以下 4 个网关字段：\r\n\r\n| 字段 | 说明 |\r\n|------|------|\r\n| `resp_code` | 网关返回码 |\r\n| `resp_desc` | 网关返回信息 |\r\n| `sign` | 对整个业务数据的签名 |\r\n| `resp_data` | 业务数据 JSON 字符串 |\r\n\r\n其中真正要驱动业务的字段在 `resp_data` 里，而不是直接平铺在最外层。\r\n\r\n```json\r\n{\r\n  \"resp_code\": \"10000\",\r\n  \"resp_desc\": \"成功调用\",\r\n  \"sign\": \"返回签名串\",\r\n  \"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\\\"}\"\r\n}\r\n```\r\n\r\n## Spring Boot 接收、验签与查单示例\r\n\r\n```java\r\nimport com.alibaba.fastjson.JSON;\r\nimport com.alibaba.fastjson.JSONObject;\r\n// Spring Boot 2.x: import javax.servlet.http.HttpServletRequest;\r\n// Spring Boot 3.x: import jakarta.servlet.http.HttpServletRequest;\r\nimport java.util.Objects;\r\nimport org.springframework.beans.factory.annotation.Value;\r\nimport org.springframework.util.StringUtils;\r\nimport org.springframework.web.bind.annotation.PostMapping;\r\nimport org.springframework.web.bind.annotation.RequestMapping;\r\nimport org.springframework.web.bind.annotation.RestController;\r\n\r\n@RestController\r\n@RequestMapping(\"/notify\")\r\npublic class AggregateNotifyController {\r\n\r\n    private final String huifuPublicKey;\r\n    private final AggregateQueryService queryService;\r\n    private final NotifyIdempotentService idempotentService;\r\n\r\n    public AggregateNotifyController(\r\n            @Value(\"${huifu.rsa-public-key}\") String huifuPublicKey,\r\n            AggregateQueryService queryService,\r\n            NotifyIdempotentService idempotentService) {\r\n        this.huifuPublicKey = huifuPublicKey;\r\n        this.queryService = queryService;\r\n        this.idempotentService = idempotentService;\r\n    }\r\n\r\n    @PostMapping(\"/payment\")\r\n    public String onNotify(HttpServletRequest request) {\r\n        String respData = request.getParameter(\"resp_data\");\r\n        String sign = request.getParameter(\"sign\");\r\n        if (!StringUtils.hasText(respData) || !StringUtils.hasText(sign)) {\r\n            throw new IllegalArgumentException(\"汇付回调缺少 resp_data 或 sign\");\r\n        }\r\n        if (!RsaUtils.verify(respData, huifuPublicKey, sign)) {\r\n            throw new IllegalArgumentException(\"汇付回调验签失败\");\r\n        }\r\n\r\n        JSONObject dataObj = JSON.parseObject(respData);\r\n        String reqSeqId = dataObj.getString(\"req_seq_id\");\r\n        String reqDate = dataObj.getString(\"req_date\");\r\n        String hfSeqId = dataObj.getString(\"hf_seq_id\");\r\n        String transStat = dataObj.getString(\"trans_stat\");\r\n        String transType = dataObj.getString(\"trans_type\");\r\n\r\n        if (idempotentService.isProcessed(hfSeqId)) {\r\n            return \"RECV_ORD_ID_\" + reqSeqId;\r\n        }\r\n\r\n        AggregateQueryResult queryResult = queryService.query(reqDate, reqSeqId);\r\n        if (!Objects.equals(queryResult.getTransStat(), transStat)) {\r\n            throw new IllegalStateException(\"异步通知与查单状态不一致\");\r\n        }\r\n\r\n        if (\"S\".equals(transStat)) {\r\n            // 支付成功：更新订单并执行后续业务\r\n        } else if (\"F\".equals(transStat)) {\r\n            // 支付失败：记录失败原因\r\n        } else if (\"P\".equals(transStat)) {\r\n            // 处理中：继续等待通知或轮询\r\n        } else {\r\n            throw new IllegalStateException(\"未知 trans_stat=\" + transStat);\r\n        }\r\n\r\n        // 同步返回常见字段名是 trade_type，异步回调字段名是 trans_type，不要混用\r\n        // 例如：log.info(\"notify reqSeqId={}, hfSeqId={}, transType={}, transStat={}\", ...);\r\n        return \"RECV_ORD_ID_\" + reqSeqId;\r\n    }\r\n}\r\n```\r\n\r\n## 终态判断原则\r\n\r\n- `trans_stat`、查单结果、幂等键可以驱动订单状态流转。\r\n- `resp_code`、`resp_desc`、HTTP 返回码主要用于排查，不直接驱动订单终态。\r\n- 不要写“`resp_code=00000000` 就直接支付成功”这种逻辑。\r\n\r\n## 签名差异\r\n\r\n| 场景 | 密钥 | 说明 |\r\n|------|------|------|\r\n| API 请求与 `notify_url` | 商户 RSA 私钥签名，汇付 RSA 公钥验签 | `SHA256WithRSA` |\r\n| Webhook | Webhook 终端密钥 | `MD5(raw_body + endpoint_key)`，与 API RSA 密钥无关 |\r\n\r\nWebhook 必须先对原始请求体验签，再 JSON 解析事件体。不要先反序列化后重新序列化，也不要用 `sign` 长度自动猜 MD5 / RSA。完整共享规则见 `shared-webhook-signing.md`。\r\n\r\n## Webhook 使用场景\r\n\r\nWebhook 更适合做平台级事件通知，例如：\r\n\r\n| 事件类型编号 | 说明 |\r\n|--------------|------|\r\n| `trans.close` | 关单事件 |\r\n| `refund.standard` | 退款事件 |\r\n| `statement.day` | 日结算通知 |\r\n| `statement.auto` | 自动结算通知 |\r\n| `settlement.encashment` | 取现通知 |\r\n\r\n## Webhook 落地步骤\r\n\r\n1. 在服务端创建 HTTPS 端点。\r\n2. 在汇付控台注册端点并选择订阅事件。\r\n3. 使用测试事件验证联通性。\r\n4. 处理正式事件，并监控失败重试。\r\n\r\n## Webhook 重发规则\r\n\r\n- 首次发送失败后会快速重试 3 次。\r\n- 之后按小时级补发，直到成功。\r\n- 控台支持手工重新推送。\r\n\r\n## 使用建议\r\n\r\n- 支付交易主状态仍优先依赖 `notify_url` 和主动查询。\r\n- Webhook 更适合对账、结算、告警和平台事件同步。\r\n- API 回调验签和 Webhook 验签必须分开实现，不要共用密钥。\r\n\r\n## 参考\r\n\r\n- 平台 Webhook 工具介绍：<https://paas.huifu.com/open/doc/devtools/#/webhook/webhook_jieshao>\n\nFile v1.3.4:references/aggregation-base.md\n\n# 聚合支付基础\r\n\r\n这份文档负责聚合支付的初始化、公共参数、语言边界和接入前置判断。\r\n\r\n## 什么时候读这里\r\n\r\n- 第一次接聚合支付\r\n- 需要确认 `trade_type`、公共环境变量、初始化顺序\r\n- 需要判断当前应该走 Java、PHP 还是 Python\r\n\r\n## 推荐阅读顺序\r\n\r\n```text\r\nshared-overview\r\n  -> shared-signing-v2\r\n  -> shared-request-header-policy\r\n  -> aggregation-base\r\n  -> aggregation-order / aggregation-query / aggregation-refund\r\n```\r\n\r\n## 当前版本口径\r\n\r\n| 项目 | 当前值 |\r\n| --- | --- |\r\n| Java SDK | `dg-lightning-sdk 1.0.5` |\r\n| PHP 覆盖范围 | 下单、扫码交易查询、关单、关单查询、退款、退款查询、对账 |\r\n| `HUIFU_SKILL_SOURCE` 最终值 | `<skill_source>` |\r\n\r\n## 必备环境变量\r\n\r\n| 环境变量 | 用途 |\r\n| --- | --- |\r\n| `HUIFU_PRODUCT_ID` | 汇付分配的产品号 |\r\n| `HUIFU_SYS_ID` | 渠道商 / 商户 `huifu_id` |\r\n| `HUIFU_RSA_PRIVATE_KEY` | 请求签名私钥 |\r\n| `HUIFU_RSA_PUBLIC_KEY` | 响应验签公钥 |\r\n| `HUIFU_SKILL_SOURCE` | 可选来源覆盖项，请求头层按 `<skill_source>` 原样透传 |\r\n\r\n## 初始化前确认事项\r\n\r\n1. 先读 `references/shared-signing-v2.md`\r\n2. 先读 `references/shared-async-notify.md`\r\n3. 如果不是 Java，必须额外核对 `references/shared-request-header-policy.md`\r\n4. 不要猜测 `sub_openid`、`buyer_id`、`auth_code`、`devs_id`、`fee_sign` 等运行时值\r\n\r\n## 聚合支付主流程\r\n\r\n```text\r\n准备产品号和密钥\r\n  -> 初始化 SDK 或 HTTP 客户端\r\n  -> 选择 trade_type\r\n  -> aggregation-order 下单\r\n  -> aggregation-query 查单 / 关单 / 对账\r\n  -> aggregation-refund 退款\r\n```\r\n\r\n## trade_type 速查\r\n\r\n| trade_type | 说明 |\r\n| --- | --- |\r\n| `T_JSAPI` | 微信公众号支付 |\r\n| `T_MINIAPP` | 微信小程序支付 |\r\n| `T_APP` | 微信 APP 支付 |\r\n| `T_MICROPAY` | 微信付款码反扫 |\r\n| `A_JSAPI` | 支付宝 JS 支付 |\r\n| `A_NATIVE` | 支付宝正扫 |\r\n| `A_MICROPAY` | 支付宝付款码反扫 |\r\n| `U_JSAPI` | 银联 JS 支付 |\r\n| `U_NATIVE` | 银联正扫 |\r\n| `U_MICROPAY` | 银联付款码反扫 |\r\n\r\n## 语言边界\r\n\r\n- Java 是聚合支付完整基线\r\n- PHP 已覆盖聚合支付核心主链路与对账；默认入口先读 `references/aggregation-php-adapter.md` 与 `references/aggregation-query-php-scenarios.md`\r\n- Python 已覆盖聚合支付核心主链路与对账；默认入口先读 `references/aggregation-python-adapter.md` 与 `references/aggregation-python-scenarios.md`\r\n- 当前 Skill 包不再内置 PHP 模板资产；PHP 默认走官方 `huifurepo/dg-php-sdk`\r\n- C#、Go 当前只保留统一入口说明，不提供现成业务模板\r\n\r\n## 公共字段提醒\r\n\r\n- `req_seq_id` 必须保证当日唯一\r\n- `req_date` 建议始终保存，后续查询、关单、退款都要回用\r\n- `method_expand`、`acct_split_bunch`、`terminal_device_data`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info` 应先建模再序列化；`tx_metadata` 本身不作为请求字段上送\r\n\r\n## 下一步怎么走\r\n\r\n- 要创建订单：读 `references/aggregation-order.md`\r\n- 要查单 / 关单 / 对账：读 `references/aggregation-query.md`\r\n- 要退款：读 `references/aggregation-refund.md`\n\nFile v1.3.4:references/aggregation-common-params.md\n\n# 公共参数说明\n\n官方公共资料入口：\n\n- [基础参数汇总](https://paas.huifu.com/partners/api/doc/csfl/api_csfl.md)：地区、银行、支行、MCC、交易类型、文件类型等公共编码/枚举的入口。\n- [名词解释](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_mcjs.md)：ATU、H5、结算周期、手续费等术语口径。\n- [返回码](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_ywm.md)：网关与业务返回码全集。\n\n这些页面是公共字典和术语来源，不覆盖具体接口页对字段必填、条件、类型和层级的定义；发生差异时保留两边证据并按具体接口合同处理。\n\n\n## 目录\n\r\n- 公共请求参数\r\n- 公共返回参数\r\n- 业务数据通用字段\r\n- 交易状态枚举（trans_stat）\r\n- 金额格式\r\n- 日期时间格式\r\n- 流水号规则\r\n- 支付类型详解\r\n- 标准字段与格式约束\r\n- 结算术语\r\n- 手续费术语\r\n\r\n## 公共请求参数\r\n\r\n所有聚合支付 API 请求的外层参数：\r\n\r\n| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |\r\n|------|-------|------|------|------|------|\r\n| sys_id | 系统号 | String | 32 | Y | 渠道商/代理商/商户的 huifu_id |\r\n| product_id | 产品号 | String | 32 | Y | 汇付分配的产品号，如 `MYPAY`、`YYZY` |\r\n| sign | 加签结果 | String | 512 | Y | SDK 自动生成，无需手动处理 |\r\n| data | 请求数据 | JSON | - | Y | 业务请求参数 |\r\n\r\n> 强制请求头约束：\r\n> - 必须带 `jpt-x-skill-source: <skill_source>`\r\n> - 如果当前按 PHP 接入，且接口业务报文里存在 `huifu_id`，还必须带 `jpt-x-skill-huifu_id: <data.huifu_id>`\r\n> - 当前 Skill 包对齐的官方 PHP SDK 主链路在 `MerConfig.skill_source` 已配置时，会自动带 `jpt-x-skill-source`，并在当前请求 `huifu_id` 存在且非空时自动带 `jpt-x-skill-huifu_id`\r\n> - 当前 Java SDK 基线也会在接口业务报文里 `huifu_id` 存在且非空时自动带 `jpt-x-skill-huifu_id: <data.huifu_id>`\r\n> - 这两项属于 HTTP 请求头，不属于 `data` 字段本身；完整口径见 `references/shared-request-header-policy.md`\r\n\r\n### sys_id 说明\r\n\r\n| 主体类型 | sys_id 填写 |\r\n|---------|-----------|\r\n| 渠道商/代理商 | 渠道商/代理商的 huifu_id |\r\n| 直连商户 | 商户自身的 huifu_id |\r\n\r\n> **sys_id vs huifu_id**：`sys_id` 是外层公共参数，标识调用方身份；`huifu_id` 是 `data` 内业务参数，标识交易商户。渠道商模式下两者不同，直连商户模式下两者相同。\r\n\r\n## 公共返回参数\r\n\r\n| 参数 | 中文名 | 类型 | 长度 | 说明 |\r\n|------|-------|------|------|------|\r\n| sign | 签名 | String | 512 | SDK 自动验证 |\r\n| data | 响应内容体 | JSON | - | 业务返回参数 |\r\n\r\n## 业务数据通用字段\r\n\r\n以下字段在多数业务接口的 `data` 中出现：\r\n\r\n| 参数 | 中文名 | 类型 | 说明 |\r\n|------|-------|------|------|\r\n| resp_code | 业务响应码 | String(8) | 接口受理返回码，用于排查；订单终态仍看 `trans_stat` 和查单结果 |\r\n| resp_desc | 业务响应信息 | String(512) | 响应描述 |\r\n| huifu_id | 商户号 | String(32) | 商户 huifu_id |\r\n| req_date | 请求日期 | String(8) | 格式 yyyyMMdd |\r\n| req_seq_id | 请求流水号 | String(128) | 同一 huifu_id 下当天唯一 |\r\n| hf_seq_id | 汇付全局流水号 | String(128) | 汇付生成的全局唯一标识 |\r\n\r\n## 交易状态枚举（trans_stat）\r\n\r\n| 值 | 含义 | 处理方式 |\r\n|---|------|---------|\r\n| I | 初始 | 罕见状态，联系汇付技术人员 |\r\n| P | 处理中 | 等待异步通知或轮询查询接口 |\r\n| S | 成功 | 交易完成 |\r\n| F | 失败 | 交易失败，可重新发起 |\r\n\r\n## 金额格式\r\n\r\n- **单位**：元（CNY）\r\n- **精度**：保留两位小数\r\n- **最小值**：0.01\r\n- **示例**：`\"1.00\"`、`\"100.50\"`、`\"0.01\"`\r\n\r\n## 日期时间格式\r\n\r\n| 格式 | 说明 | 示例 |\r\n|------|------|------|\r\n| yyyyMMdd | 日期 | `20250320` |\r\n| yyyyMMddHHmmss | 日期时间（14位） | `20250320143000` |\r\n| HHmmss | 时间（6位） | `143000` |\r\n\r\n## 流水号规则\r\n\r\n| 字段 | 规则 | 说明 |\r\n|------|------|------|\r\n| req_seq_id | 同一 huifu_id 下当天唯一 | 商户自行生成 |\r\n| hf_seq_id | 全局唯一 | 汇付返回，用于查询/退款 |\r\n| org_req_seq_id | 原交易的 req_seq_id | 用于关联原交易 |\r\n| org_hf_seq_id | 原交易的 hf_seq_id | 可替代 org_req_seq_id |\r\n\r\n## 支付类型详解\r\n\r\n### 正扫 vs 反扫\r\n\r\n| 类型 | 说明 | 适用 trade_type |\r\n|------|------|----------------|\r\n| 正扫 (NATIVE) | 商户生成二维码，用户扫码支付 | A_NATIVE、U_NATIVE |\r\n| 反扫 (MICROPAY) | 用户出示付款码，商户扫码收款 | T_MICROPAY、A_MICROPAY、U_MICROPAY |\r\n| JS 支付 (JSAPI) | 在对应 APP 内通过 JS 调起支付 | T_JSAPI、A_JSAPI、U_JSAPI |\r\n| 小程序 (MINIAPP) | 微信小程序内支付 | T_MINIAPP |\r\n| APP 支付 | 原生 APP 内支付 | T_APP |\r\n\r\n### method_expand 参数\n\n本节只描述**聚合下单请求侧**的 `request.data.method_expand`，不得外推到查询响应。不同 `trade_type` 需要传入不同的 `method_expand` 扩展参数。请求侧的 `trade_type` 是场景选择器，这 10 个枚举值本身不是 `request.data.method_expand` 的 key；该 JSON 内容直接是当前请求场景对象本身。查询响应 `response.data.method_expand` 同样只解码一次且字段单层平铺，具体字段与勘误必须改读 `aggregation-query-payment-query.md`。\n\r\n| trade_type | method_expand 必填字段 | 说明 |\r\n|-----------|----------------------|------|\r\n| T_JSAPI | sub_appid, sub_openid | 微信公众号 AppID 和用户 OpenID |\r\n| T_MINIAPP | sub_appid, sub_openid | 微信小程序 AppID 和用户 OpenID |\r\n| T_APP | sub_appid | 微信开放平台 AppID |\r\n| T_MICROPAY | auth_code | 用户付款码 |\r\n| A_JSAPI | buyer_id 或 buyer_logon_id | 支付宝买家 ID / 账号，二选一 |\r\n| A_NATIVE | - | 无需额外参数 |\r\n| A_MICROPAY | auth_code | 用户付款码 |\r\n| U_JSAPI | user_id, qr_code, customer_ip | 银联 JS 常见关键字段 |\r\n| U_NATIVE | - | 无需额外参数 |\r\n| U_MICROPAY | auth_code | 用户付款码 |\r\n\r\n## 标准字段与格式约束\r\n\r\n- 请求和返回统一使用 JSON，字符编码统一为 `UTF-8`。\r\n- 参数命名统一采用下划线命名法，如 `req_seq_id`、`trade_type`。\r\n- 金额单位统一为元，保留两位小数。\r\n- 时间统一按北京时间（东八区）处理。\r\n- 数值字段在 API 层尽量使用字符串承载，避免精度损失。\r\n\r\n## 结算术语\r\n\r\n| 术语 | 说明 |\r\n|------|------|\r\n| T1 自动结算 | 前一工作日周期内余额结算到银行卡 |\r\n| D1 自动结算 | 前一自然日周期内余额结算到银行卡 |\r\n| D0 取现 | 发起后通常 2 小时内到账 |\r\n| DM 取现 | 不包含在途资金的快速取现方式 |\r\n\r\n## 手续费术语\r\n\r\n| 术语 | 说明 |\r\n|------|------|\r\n| 实时收取 | 默认模式，按交易费率实时计算并收取 |\r\n| 手续费内扣 | 从交易金额中扣收手续费 |\r\n| 手续费外扣 | 从指定主体或账户额外扣收手续费 |\n\nFile v1.3.4:references/aggregation-customer-preparation.md\n\n# 聚合支付客户前置准备清单\r\n\r\n> 这份文档用于约束聚合支付 skill 在编码前先确认“参数从哪里来”。这里的前置准备不只是收集字段值，还包括官方产品介绍和开发指引里明确要求的业务开通、应用配置、授权绑定和终端采集动作。如果来源不明确，模型不应自行推断或伪造参数值。\r\n\r\n\r\n## 目录\r\n\r\n- 参数来源分类\r\n- 全局必备配置\r\n- 官方开发指引确认的通用前置动作\r\n- 聚合下单前要准备什么\r\n- 渠道级前置准备矩阵\r\n- 扩展字段相关准备项\r\n- 查询 / 关单 / 退款前要沉淀什么\r\n- 权限 / 开通项检查\r\n- 向客户索取材料的最小清单\r\n- 给模型的硬约束\r\n\r\n## 参数来源分类\r\n\r\n| 来源类型 | 典型字段 | 说明 |\r\n|---------|---------|------|\r\n| 汇付平台固定配置 | `sys_id`、`product_id`、`huifu_id`、RSA 密钥 | 由汇付开放平台 / 控台提供 |\r\n| 客户业务配置 | `notify_url`、`fee_flag`、`acct_id`、`channel_no` | 由客户业务侧或控台确认 |\r\n| 前端 / 用户授权结果 | `sub_openid`、`buyer_id`、`buyer_logon_id` | 运行时值，模型不能猜 |\r\n| 终端 / 设备采集 | `auth_code`、`device_ip`、`devs_id`、`customer_ip` | 反扫、终端报备、银联场景常见 |\r\n| 上游订单沉淀 | `req_date`、`req_seq_id`、`hf_seq_id`、`party_order_id` | 查询 / 关单 / 退款必须复用 |\r\n\r\n## 全局必备配置\r\n\r\n| 配置项 | 用途 | 没有会怎样 |\r\n|-------|------|-----------|\r\n| `sys_id` | 公共请求参数 | 请求无法落地 |\r\n| `product_id` | 公共请求参数 | 汇付会直接报产品号错误 |\r\n| `huifu_id` | 商户主体标识 | 业务请求无法定位商户 |\r\n| RSA 私钥 / 公钥 | 请求签名、响应验签 | 请求或验签失败 |\r\n| `notify_url` / `refund_notify_url` | 异步结果通知 | 只能依赖轮询，不稳定 |\r\n| 对应渠道业务开通状态 | 微信 / 支付宝 / 银联交易前提 | 交易前必须确认账户和对应渠道已开通；进件实施交给 `$huifu-merchant-onboarding` |\n\r\n## 官方开发指引确认的通用前置动作\r\n\r\n- `Lightning_intro.md` 和《快速开始》都明确要求：开发新业务或变更旧业务前，先按产品文档中的“开通功能和准备材料”在合作伙伴控台或商户控台完成业务新增 / 变更。\r\n- 多个渠道开发指引都明确写了：用户前端页面收到支付完成回调，不等于后端可以直接认定交易成功；后端仍需调用查询订单 API 确认最终状态。\r\n- 运行时授权值、扫码值、终端采集值、渠道绑定关系，都是“业务前置准备”的一部分，不是接口层补字段时临时猜出来的。\r\n\r\n## 聚合下单前要准备什么\r\n\r\n### 所有 trade_type 通用\r\n\r\n| 字段 / 配置 | 来源 | 说明 |\r\n|------------|------|------|\r\n| `trade_type` | 业务场景确认 | 决定 `method_expand` 结构 |\r\n| `goods_desc` | 业务订单 | 不是示例值，应该来自真实商品 / 订单语义 |\r\n| `req_seq_id` | 平台流水号生成规则 | 必须当天唯一 |\r\n| `time_expire` | 业务超时策略 | 如不明确可不传，不要乱填过期时间 |\r\n| `acct_split_bunch` | 分账业务配置 | 只有要做分账时才准备 |\r\n| `terminal_device_data` | 终端 / 设备采集链路 | 反扫、终端报备、银联场景常见 |\r\n| `combinedpay_data` / `combinedpay_data_fee_info` / `trans_fee_allowance_info` | 补贴与手续费补贴能力配置 | 按能力名直接作为请求顶层扩展字段传；不要包进 `tx_metadata` |\r\n\r\n### 微信类场景\r\n\r\n| `trade_type` | 必须提前明确的值 | 来源 |\r\n|-------------|------------------|------|\r\n| `T_JSAPI` | `sub_appid`、`sub_openid` | 官方要求先准备微信公众号、开通微信业务、绑定 `sub_appid`、配置支付授权目录；`sub_openid` 必须通过当前公众号 `sub_appid` 的网页授权流程获取 |\n| `T_MINIAPP` | `sub_appid`、`sub_openid` | 官方要求先准备微信小程序、开通微信业务、完成微信配置和 appid 绑定；`sub_openid` 必须通过当前小程序 `sub_appid` 获取，且二者不能错配 |\n| `T_APP` | `sub_appid` | 应用配置 |\r\n| `T_MICROPAY` | `auth_code` | 官方要求通过扫码设备实时采集用户付款码；值本身来自用户当次付款码，不应预置到配置中 |\r\n\r\n### 支付宝类场景\r\n\r\n| `trade_type` | 必须提前明确的值 | 来源 |\r\n|-------------|------------------|------|\r\n| `A_JSAPI` | `buyer_id` 或 `buyer_logon_id` | 官方要求先开通支付宝业务；`buyer_id` 必须通过支付宝 `user_id` 获取流程拿到，不能猜 |\r\n| `A_NATIVE` | 视业务决定是否传门店、商品、营销扩展 | 客户业务配置 |\r\n| `A_MICROPAY` | `auth_code` | 官方要求通过扫码设备实时采集用户支付宝付款码 |\r\n\r\n### 银联类场景\r\n\r\n| `trade_type` | 必须提前明确的值 | 来源 |\r\n|-------------|------------------|------|\r\n| `U_JSAPI` | `user_id`、`customer_ip`，官方说明 `qr_code` 也要明确 | 官方要求先开通银联业务；`user_id` 需先经“网页授权获取 `auth_code` -> 调获取银联用户标识接口”获得，`customer_ip` 必须来自真实客户端 |\r\n| `U_NATIVE` | 是否需要 `front_url`、`payee_info` | 客户业务配置 |\r\n| `U_MICROPAY` | `auth_code`，以及是否需要 `pid_info` | 官方要求通过扫码设备实时采集用户云闪付付款码；`pid_info` 来自服务商配置 |\r\n\r\n## 渠道级前置准备矩阵\r\n\r\n| 场景 | 客户开发前必须完成什么 | 关键运行时值 |\r\n|------|----------------------|-------------|\r\n| 微信公众号支付 | 准备公众号、确认账户和微信业务已开通、绑定 `sub_appid`、配置公众号支付授权目录；授权目录通常以 `/` 结尾，配置后可能延迟生效 | `sub_openid` |\n| 微信小程序支付 | 准备小程序、确认账户和微信业务已开通、完成微信配置、确认 `sub_appid` 绑定关系，清理 appid 配置首尾空格 | `sub_openid` |\n| 支付宝 JS 支付 | 确认账户和支付宝业务已开通 | `buyer_id` / `buyer_logon_id` |\n| 银联 JS 支付 | 确认账户和银联业务已开通、准备银联网页授权回调链路 | `user_id`、`customer_ip` |\n| 各类付款码反扫 | 准备扫码枪或终端采集链路 | `auth_code` |\r\n\r\n## 扩展字段相关准备项\r\n\r\n| 对象 | 需要客户先准备什么 | 说明 |\r\n|------|------------------|------|\r\n| `acct_split_bunch` | 分账接收方 `huifu_id`、账户号、比例 / 金额规则 | 未准备好不要让模型硬拼分账串 |\r\n| `terminal_device_data` | `device_ip`、`devs_id`、定位 / 设备指纹 | 反扫和报备终端场景很关键 |\r\n| `combinedpay_data` | 补贴方 `huifu_id`、`acct_id`、金额 | 请求顶层字段，属于补贴业务配置，不可猜 |\r\n| `combinedpay_data_fee_info` | 手续费承担方 `huifu_id`、`acct_id` | 请求顶层字段，需要真实承担方信息 |\r\n| `trans_fee_allowance_info` | 补贴手续费金额和活动来源 | 请求顶层字段，需要明确的活动或配置支持 |\r\n\r\n## 查询 / 关单 / 退款前要沉淀什么\r\n\r\n| 接口 | 开发前必须保证已保存 | 说明 |\r\n|------|------------------|------|\r\n| 交易查询 | `req_date`、`req_seq_id`、`hf_seq_id`、`party_order_id` 中至少一组 | 不能等到查询时再猜 |\r\n| 交易关单 | 原交易 `org_req_date` + `org_req_seq_id` 或 `org_hf_seq_id` | 依赖原交易标识 |\r\n| 关单查询 | 关单请求自身标识 + 原交易标识 | 两层流水都要可追溯 |\r\n| 退款 | `org_hf_seq_id`、`org_party_order_id`、`org_req_seq_id` 三选一 | 原交易定位键来自上游沉淀 |\r\n| 退款查询 | 原退款请求标识、原交易标识 | 便于轮询确认 |\r\n| 对账单查询 | 对账功能开通状态、`file_date` 语义 | 功能未开通时接口也不可用 |\r\n\r\n## 权限 / 开通项检查\r\n\r\n| 能力 | 影响点 |\r\n|------|--------|\r\n| 分账权限 | `acct_split_bunch` |\r\n| 延迟入账权限 | `delay_acct_flag` |\r\n| 退款权限 | 退款接口 |\r\n| 终端报备 | `terminal_device_data.devs_id` |\r\n| 手续费 / 贴息 / 补贴配置 | `fee_flag`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info` |\r\n| 对账单功能 | `file_date`、`bill_type` |\n| 微信小程序 `sub_appid` 绑定 | `T_MINIAPP` 下单成功率 | 官方 QA 明确要求 `sub_appid` 与商户建立绑定关系 |\n| 微信 `sub_appid` / `sub_openid` 一致性 | `T_MINIAPP` / `T_JSAPI` | 官方 QA 明确要求 `sub_openid` 必须从对应 `sub_appid` 获取 |\n| 接口权限 | 当前接口是否能调用 | `接口权限认证失败` 或 `20003` 时先核对 `sys_id` 是否开通当前接口权限 |\n| 数据权限 | `product_id`、`sys_id`、`huifu_id`、`upper_huifu_id` | `数据权限认证失败` 时核对产品号、服务商/子商户层级和请求头来源 |\n| 渠道路由 | `pay_channel`、`pay_scene`、`channel_no`、线上/线下 `fee_type` | 多渠道或线上/线下混用时要明确场景；不指定通道时不要传空字符串 `channel_no` |\n\r\n## 向客户索取材料的最小清单\r\n\r\n### 必需\r\n\r\n- `sys_id`、`product_id`、`huifu_id`\r\n- RSA 私钥、公钥\r\n- 支付 / 退款异步通知地址\r\n- 实际要接的 `trade_type` 列表\r\n\r\n### 按场景补充\r\n\r\n- 微信：公众号 / 小程序应用信息、`sub_appid`、`sub_openid` 获取链路\r\n- 支付宝：`buyer_id` / `buyer_logon_id` 的真实获取链路\r\n- 银联 JS：网页授权回调地址、`auth_code -> user_id` 获取链路、`customer_ip`\r\n- 反扫：`auth_code` 获取方式、终端采集能力\r\n- 银联扩展：`front_url`、`payee_info`、`pid_info`\r\n- 分账 / 设备 / 补贴：`acct_split_bunch`、`devs_id`、补贴账户配置\r\n\r\n## 给模型的硬约束\r\n\r\n- 运行时授权值、扫码值、报备值、控台配置值，都不能靠模型猜。\r\n- 前端页面回调、支付完成页、客户端 success 回调，都不能直接当作交易成功终态；按官方开发指引，后端必须再查单确认。\r\n- 如果客户没有提供场景必需值，应该先暴露缺口，而不是直接给出“看起来完整”的代码。\r\n- 查询、关单、退款代码必须复用上游订单沉淀的标识，不要在下游重新假设。\n\nFile v1.3.4:references/aggregation-error-codes.md\n\n# 聚合支付错误码\r\n\r\n> 本页返回码主要用于排查和联调定位，不建议把 `resp_code` 直接写成订单终态逻辑；订单终态仍以 `trans_stat`、异步通知和主动查询结果为准。\n\n## 官方来源与合并规则\n\n- 公共全集：[返回码](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_ywm.md)，包含网关返回码以及扫码类、线上交易、商户进件等业务返回码。\n- 公共字典入口：[基础参数汇总](https://paas.huifu.com/partners/api/doc/csfl/api_csfl.md)。\n- 业务术语：[名词解释](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_mcjs.md)。\n- 本页下方只保留高频码和接口专项码，不是全集。排查时必须把“当前接口页业务返回码”与公共返回码全集合并查看；同一码可能按接口或 `resp_desc` 表示不同原因，不能只按码值做唯一映射。\n- 网关返回码用于判断请求是否到达业务处理层；业务返回码用于接口处理诊断；交易终态仍由交易状态、异步通知和主动查询共同确认。\n\r\n## 通用错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 00000000 | 本次接口处理完成，实际交易结果仍以 `trans_stat` / 查询结果为准 | 继续结合交易状态字段确认终态 |\r\n| 00000100 | 交易正在处理中 | 等待异步通知或轮询查询 |\r\n| 10000000 | 无效参数 | 检查必填字段、格式、长度 |\r\n| 98888888 | 未知系统错误 | 联系汇付技术支持 |\r\n| 99999999 | 系统异常，请稍后重试 | 稍后重试或联系技术支持 |\r\n\r\n## 参数校验类 (10000000)\r\n\r\n| 返回描述 | 处理建议 |\r\n|---------|---------|\r\n| 请求内容体不能为空 | 检查请求 body |\r\n| %s不能为空 | 检查对应必填字段 |\r\n| %s长度固定%d位 | 检查字段长度 |\r\n| %s最大长度为%d位 | 缩短字段值 |\r\n| %s的传入枚举[%s]不存在 | 检查枚举值是否合法 |\r\n| %s不符合%s格式 | 检查日期/金额等格式 |\r\n\r\n## 下单类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 20000000 | 重复交易 | 使用新的 req_seq_id |\r\n| 20000001 | 操作过于频繁 | 稍后重试 |\r\n| 22000000 | 产品配置信息异常 | 检查 product_id 配置 |\r\n| 22000002 | 商户配置信息异常 | 检查 huifu_id |\r\n| 90000000 | 交易受限 / 单笔金额超限 / 交易存在风险 | 查看 resp_desc 详情 |\r\n\r\n## 查询类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 20000004 | 交易不存在 | 检查流水号是否正确 |\r\n| 21000000 | 参数逻辑校验不合法（流水号、全局流水号不能同时为空） | 至少传入一个查询条件 |\r\n\r\n## 关单类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 20000001 | 不允许关闭一分钟以内的订单；官网同码也用于并发冲突 | 结合 `resp_desc` 区分，未满一分钟时等待边界后再查询/关单 |\n| 10000016 | 原订单已为终态,请发起查询交易获取 | 订单已完成，无需关单 |\r\n| 10000018 | 关单失败 | 查看 resp_desc 详情 |\r\n| 23000000 | 原交易订单已失败不允许关单 / 关单状态为终态 | 订单已完成或已关单 |\r\n| 23000004 | 不支持的交易（银联二维码不支持关单） | 银联不支持关单 |\r\n\r\n## 退款类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 10000001 | 原交易没有处理完成 | 等待原交易完成 |\r\n| 10000002 | 退款金额大于可退金额 | 检查退款金额 |\r\n| 10000009 | 该交易不支持部分退款 | 只能全额退款 |\r\n| 21000000 | 原交易请求流水号、商户单号、全局流水号不能同时为空 | 至少传入一个原交易标识 |\r\n| 22000004 | 暂未开通退款权限/分账退款权限 | 联系汇付开通权限 |\r\n| 23000002 | 数据权限不足 / 退款手续费承担方不一致 | 检查手续费配置 |\r\n| 23000003 | 金额校验异常（退款额>可退额 / 余额不足） | 检查退款金额和账户余额 |\r\n| 23000004 | 不支持的交易（预授权撤销/优惠交易部分退款） | 使用其他方式处理 |\r\n| 30000000 | 调用收银台退款接口失败 | 稍后重试 |\r\n| 90000000 | 交易受限 / 可用余额不足 / 交易存在风险 | 查看 resp_desc 详情 |\r\n\r\n## 对账单查询错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 00000000 | 查询成功 | 正常返回 |\r\n| — | 当前huifuId请求过于频繁 | 每天不要超过 3 次查询 |\r\n\r\n## 使用边界\r\n\r\n- `resp_code`、`resp_desc` 主要用于排查，不直接驱动订单成功/失败终态。\r\n- `00000000` 不等于“交易最终成功”，仍要结合 `trans_stat`、异步通知和查单结果判断。\r\n- `00000100` 表示当前接口仍在处理中，应该继续等待异步通知或轮询查询。\r\n- 其他返回码优先结合 `resp_desc`、请求参数、渠道场景和原交易标识排查。\n- 本页未列出的返回码不得直接判为“未知系统错误”；先查公共返回码全集，再结合接口专属码和 `resp_desc` 分类。\n\nFile v1.3.4:references/aggregation-faq.md\n\n# 各渠道常见问题汇总\r\n\r\n\r\n## 目录\r\n\r\n- 微信支付通用问题\r\n- 微信付款码特有问题\r\n- 支付宝支付通用问题\r\n- 银联支付问题\r\n- 对账单问题\r\n\r\n## 微信支付通用问题\r\n\r\n### 业务常见问题\r\n\r\n**Q：支付时显示的商家简称可以修改吗？**\r\nA：可以。登录合作伙伴控台修改，或调用【微信支付宝入驻信息修改】接口。\r\n\r\n**Q：消费者账单侧显示的商品字段如何修改？**\r\nA：对应下单时传入的 `goods_desc`（商品描述）字段，可笔笔指定。\r\n\r\n**Q：支付时如何限制信用卡支付？**\r\nA：发起交易时传入禁用支付方式字段。它属于请求顶层字段，不属于 `method_expand`。\r\n\r\n**Q：支付时是否可以指定入账账户？**\r\nA：支持，传入需入账的账户号，仅支持基本户、现金户。\r\n\r\n**Q：已开通多个微信商户号，支付时如何指定？**\r\nA：通过接口或控台修改微信交易通道配置，预配置默认通道。下单时可通过\"渠道号\"和\"场景类型\"单独指定。\r\n\r\n**Q：支付失败，风控拦截交易（非微信拦截）如何处理？**\r\nA：提供报错描述联系客服，若为可申诉场景按流程提交材料。\r\n\r\n### 微信技术问题\r\n\r\n**Q：报错 \"当前商户需补齐相关资料后，才可进行相应的支付交易\"**\r\n原因：商户未完成微信实名认证。\r\n处理：登录控台完成实名认证，或调用【微信实名认证】接口。\r\n\r\n**Q：报错 \"sub_mch_id与sub_appid不匹配\"**\r\n原因：商户 appid 配置有误。\r\n处理：确认公众号/小程序的 sub_appid 已与商户绑定，可调用【微信商户配置】接口或控台配置。\r\n\r\n**Q：报错 \"sub_appid与sub_openid不匹配\"**\r\n原因：sub_appid 和 sub_openid 获取对应关系有误。\r\n处理：sub_openid 必须从对应的 sub_appid 下获取，不能混用不同公众号/小程序。\r\n\r\n**Q：报错 \"特约子商户该产品权限已被冻结\"**\r\n原因：微信风控关闭商户号支付权限。\r\n处理：处理商户风险问题，申诉通过后恢复支付权限。\r\n\r\n## 微信付款码特有问题\r\n\r\n**Q：付款码支付是否需要输入密码？**\r\nA：一般情况下免密扣款。以下情况需验密：\r\n- 支付金额 > 1000元\r\n- 当天已有10笔免密交易\r\n- 用户查看了付款码数字\r\n- 微信风控判断异常\r\n\r\n## 支付宝支付通用问题\r\n\r\n### 业务常见问题\r\n\r\n**Q：支付时显示的商家简称可以修改吗？**\r\nA：可以。登录控台修改，或调用【微信支付宝入驻信息修改】接口。\r\n\r\n**Q：支付时如何限制信用卡支付？**\r\nA：发起交易时传入禁用支付方式字段。\r\n\r\n### 支付宝技术问题\r\n\r\n**Q：报错 \"当前商户未认证，请通知商户在支付宝搜索'支付宝商家认证助手'小程序，完成认证后开通交易\"**\r\n原因：商户未完成支付宝实名认证。\r\n处理：登录控台完成认证，或调用【支付宝实名申请提交】接口。\r\n\r\n### 支付宝付款码特有问题\r\n\r\n**Q：付款码支付什么时候需要输入密码？**\r\nA：以下场景会唤起支付宝收银台：\r\n- 消费者付款码安全校验未通过\r\n- 支付额度超过代扣额度\r\n- 代扣失败（所有渠道余额不足）\r\n\r\n## 银联支付问题\r\n\r\n**Q：H5页面无法打开？**\r\nA：确认页面地址是否已在银联通过备案，未备案页面无法正常打开。\r\n\r\n**Q：支付时是否可以指定入账账户？**\r\nA：支持，传入需入账的账户号，仅支持基本户、现金户。\r\n\r\n**Q：支付失败，风控拦截交易如何处理？**\r\nA：提供报错描述联系客服，若为可申诉场景按流程提交材料。\r\n\r\n### 银联付款码特有问题\r\n\r\n**Q：付款码支付是否需要输入密码？**\r\nA：一般情况下免密扣款，仅触发验证密码规则后需验密。\r\n\r\n## 对账单问题\r\n\r\n**Q：对账单查询接口返回的文件格式？**\r\nA：常规账单一个链接通常对应一个压缩文件，压缩包内多为 csv。`SETTLE_FUND_BILL` 模板为 `.xlsx`，不要把所有账单都按 csv 解析。单个文件超过 400,000 条时会拆分为多个 csv。\r\n\r\n**Q：对账单什么时候适合下载？**\r\nA：最新产品介绍口径建议按跑批节奏取数：交易/分账文件 03:00 跑批后建议 12:00 再取，出金对账单 10:30 跑批后一小时，结算对账单 17:00 跑批后一小时。\r\n\r\n**Q：对账单能查多久以前的数据？**\r\nA：接口当前支持 1 年内账单下载；控台下载暂未见时间限制说明。\r\n\r\n**Q：交易账单实收金额与结算金额不一致？**\r\nA：计算公式：交易金额 - 交易手续费 - 退款金额 + 退款手续费。还需排除结算周期 > D+1 的交易和资金冻结。\r\n\r\n**Q：报错 \"当前huifuId请求过于频繁\"？**\r\nA：生成对账单有次数限制，每天不超过3次。\r\n\r\n**Q：对账单查询 file_details 为空？**\r\nA：查看 task_details，如果 task_stat 为成功且文件为空，代表前一日无记录。\n\nFile v1.3.4:references/aggregation-java-adapter.md\n\n# Java 适配层\r\n\r\n这份文件只讲 Java 接入。  \r\n协议规则不在这里重复写。\r\n\r\n## 适配范围\r\n\r\n| 项目 | 内容 |\r\n| --- | --- |\r\n| 当前适配 SDK | `dg-lightning-sdk` `1.0.5` |\r\n| 最低运行时 | JDK 1.8+ |\r\n| 初始化入口 | `MerConfig` + `BasePay.initWithMerConfig()` |\n| 主要调用方式 | `Factory.Payment.Common()` |\n\n`dg-lightning-sdk 1.0.5` 的 `BasePay.debug` 默认是 `true`，底层会输出私钥、签名和请求数据。所有初始化必须在任何 `initWithMerConfig(s)` 或业务请求前执行一次 `BasePay.debug = false;`，不得在并发请求中临时切换。\n\r\n## 先看哪些文件\r\n\r\n- `references/aggregation-java-sdk-quickstart.md`\r\n- `references/aggregation-java-tech-spec.md`\r\n- `references/aggregation-async-webhook.md`\r\n\r\n## Java 特有说明\r\n\r\n1. Lightning SDK 的产品号方法名是 `setProductId()`，这里拼写正常。\r\n2. Spring Boot 2.x 和 3.x 的 import 不一样。\r\n   2.x 常见是 `javax.annotation.PostConstruct`\r\n   3.x 常见是 `jakarta.annotation.PostConstruct`\r\n3. 当前仓库的异步通知示例使用了 `fastjson`。\r\n   这是 Java 示例选型，不是协议层要求。\r\n4. `method_expand`、`acct_split_bunch`、`terminal_device_data`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info` 这类字段，仍然建议先在业务层建对象，再在 SDK 边界统一序列化。\r\n5. `T_JSAPI`、`T_MINIAPP`、`T_APP`、`T_MICROPAY`、`A_JSAPI`、`A_NATIVE`、`A_MICROPAY`、`U_JSAPI`、`U_NATIVE`、`U_MICROPAY` 这些值不是 `method_expand` 的 key；`method_expand` 的 JSON 内容直接是当前场景对象本身。\r\n6. `tx_metadata` 本身不作为请求字段上送；交易能力扩展按能力名直接传 `acct_split_bunch`、`terminal_device_data`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info`。\r\n7. `MerConfig.setSkillSource(...)` 直接传 `<skill_source>` 即可；聚合支付要求的 `sys_id` 仍通过独立请求头 `sys_id` / `jpt-sys_id` 传递，`jpt-x-skill-source` 只透传来源值。\r\n8. 当前 Java SDK 基线如果请求参数里的 `huifu_id` 存在且非空，还会自动补 `jpt-x-skill-huifu_id`；该值必须与本次请求的 `huifu_id` 一致，不要手工写成固定常量。\r\n\r\n## 不属于这里的内容\r\n\r\n- 签名规则：看 `references/shared-signing-v2.md`\r\n- 异步通知规则：看 `references/shared-async-notify.md`\r\n- 其他语言入口：看 `references/shared-server-sdk-matrix.md`\n\nFile v1.3.4:references/aggregation-java-sdk-quickstart.md\n\n## 目录\n\n- [SDK 信息](#sdk-信息)\n- [步骤 1：添加 Maven 依赖](#步骤-1添加-maven-依赖)\n- [步骤 2：SDK 初始化](#步骤-2sdk-初始化spring-boot-配置类)\n- [步骤 3：验证核心类导入](#步骤-3验证核心类导入)\n- [Factory 调用模式](#factory-调用模式)\n- [与 dg-java-sdk 的关键差异](#与-dg-java-sdk-的关键差异)\n\n# SDK 安装与初始化\n\n## SDK 信息\n\n| 属性 | 值 |\n|-----|-----|\n| SDK 名称 | dg-lightning-sdk |\n| 当前版本 | 1.0.5 |\n| GroupId | com.huifu.dg.lightning.sdk |\n| ArtifactId | dg-lightning-sdk |\n\n> **说明**：如果项目中同时需要托管支付（dg-java-sdk）和聚合支付（dg-lightning-sdk），两个 SDK 可以共存，各自独立初始化。\n\n## 步骤 1：添加 Maven 依赖\n\n在 `pom.xml` 中添加：\n\n```xml\n<dependency>\n    <groupId>com.huifu.dg.lightning.sdk</groupId>\n    <artifactId>dg-lightning-sdk</artifactId>\n    <version>1.0.5</version>\n</dependency>\n```\n\n如果同时需要托管支付，也添加：\n\n```xml\n<dependency>\n    <groupId>com.huifu.bspay.sdk</groupId>\n    <artifactId>dg-java-sdk</artifactId>\n    <version>3.0.40</version>\n</dependency>\n```\n\n执行安装：\n\n```bash\nmvn clean install\n```\n\n## 步骤 2：SDK 初始化（Spring Boot 配置类）\n\n> **[Spring Boot 3.x 用户必读]** 如果你使用 Spring Boot 3.x（JDK 17/21），`javax.*` 命名空间已迁移至 `jakarta.*`，初始化代码中的 import 需替换。\n\n| Spring Boot 版本 | PostConstruct |\n|-----------------|---------------|\n| 2.x | `javax.annotation.PostConstruct` |\n| 3.x (JDK 17/21) | `jakarta.annotation.PostConstruct` |\n\n> **[产品号方法名]** Lightning SDK 和当前 `dg-java-sdk 3.0.40` 的 `MerConfig` 产品号方法名都使用 `setProductId(...)`。\n\n> **官方 SDK-only**：接入方已确认当前官方 Lightning SDK 不存在本 Skill 曾推断的 TLS 问题。下方初始化可用于官方 SDK 调用；不得改写 `HttpClient`、OkHttp 或自实现 HTTP+签名客户端。\n\n```java\npackage com.yourcompany.huifu.config;\n\nimport com.huifu.dg.lightning.biz.config.MerConfig;\nimport com.huifu.dg.lightning.utils.BasePay;\nimport lombok.extern.slf4j.Slf4j;\nimport org.springframework.beans.factory.annotation.Value;\nimport org.springframework.context.annotation.Configuration;\n\nimport javax.annotation.PostConstruct;\n\n@Configuration\n@Slf4j\npublic class HuifuLightningConfig {\n\n    @Value(\"${huifu.product-id}\")\n    private String productId;\n\n    @Value(\"${huifu.sys-id}\")\n    private String sysId;\n\n    @Value(\"${huifu.rsa-private-key}\")\n    private String rsaPrivateKey;\n\n    @Value(\"${huifu.rsa-public-key}\")\n    private String rsaPublicKey;\n\n    @Value(\"${huifu.skill-source:hfps/1.3.4}\")\n    private String skillSource;\n\n    @Value(\"${huifu.mode:prod}\")\n    private String mode;\n\n    @PostConstruct\n    public void initSdk() throws Exception {\n        // SDK 1.0.5 默认 debug=true，会输出私钥、签名和请求数据。\n        // 必须在任何初始化或请求之前全局关闭，且不得按请求临时切换。\n        BasePay.debug = false;\n\n        // 设置环境模式\n        if (\"test\".equals(mode)) {\n            BasePay.prodMode = BasePay.MODE_TEST;\n            log.info(\"汇付聚合支付SDK: 联调环境\");\n        } else {\n            BasePay.prodMode = BasePay.MODE_PROD;\n            log.info(\"汇付聚合支付SDK: 生产环境\");\n        }\n\n        // 初始化商户配置\n        MerConfig merConfig = new MerConfig();\n        merConfig.setProductId(productId);   // 注意：Lightning SDK 拼写正常\n        merConfig.setSysId(sysId);\n        merConfig.setRsaPrivateKey(rsaPrivateKey);\n        merConfig.setRsaPublicKey(rsaPublicKey);\n        merConfig.setSkillSource(skillSource);\n\n        BasePay.initWithMerConfig(merConfig);  // 注意：throws Exception\n        log.info(\"汇付聚合支付SDK初始化完成\");\n    }\n}\n```\n\n### 多商户配置（可选）\n\n如果需要支持多个商户，使用 `initWithMerConfigs`：\n\n```java\nMap<String, MerConfig> configs = new HashMap<>();\n\n// 多商户初始化同样必须先全局关闭调试输出。\nBasePay.debug = false;\n\nMerConfig config1 = new MerConfig();\nconfig1.setProductId(\"MYPAY\");\nconfig1.setSysId(\"6666000123120001\");\nconfig1.setRsaPrivateKey(\"...\");\nconfig1.setRsaPublicKey(\"...\");\nconfig1.setSkillSource(\"hfps/1.3.4\");\nconfigs.put(\"merchant1\", config1);\n\nMerConfig config2 = new MerConfig();\nconfig2.setSysId(\"6666000123120002\");\nconfig2.setSkillSource(\"hfps/1.3.4\");\n// ... 配置第二个商户\nconfigs.put(\"merchant2\", config2);\n\nBasePay.initWithMerConfigs(configs);\n```\n\n### 自定义超时时间（可选）\n\n```java\nMerConfig merConfig = new MerConfig();\n// ... 基本配置\nmerConfig.setCustomConnectTimeout(\"30000\");              // 连接超时 30s（默认 20s），注意是 String 类型\nmerConfig.setCustomSocketTimeout(\"30000\");               // 读取超时 30s（默认 20s）\nmerConfig.setCustomConnectionRequestTimeout(\"40000\");    // 请求超时 40s（默认 30s）\nmerConfig.setSkillSource(\"hfps/1.3.4\");\n```\n\n## 步骤 3：验证核心类导入\n\n确认以下类可正常导入：\n\n| 类 | 包路径 | 用途 |\n|---|-------|------|\n| BasePay | `com.huifu.dg.lightning.utils.BasePay` | SDK 入口，初始化配置、环境模式 |\n| MerConfig | `com.huifu.dg.lightning.biz.config.MerConfig` | 商户配置对象 |\n| Factory | `com.huifu.dg.lightning.factory.Factory` | 工厂类，获取业务客户端 |\n| CommonPayClient | `com.huifu.dg.lightning.biz.client.CommonPayClient` | 聚合支付客户端 |\n| BasePayException | `com.huifu.dg.lightning.biz.exception.BasePayException` | SDK 异常类 |\n| DateTools | `com.huifu.dg.lightning.utils.DateTools` | 日期工具（`getCurrentDateYYYYMMDD()`） |\n| SequenceTools | `com.huifu.dg.lightning.utils.SequenceTools` | 流水号工具（`getReqSeqId32()`） |\n\n`MerConfig.setSkillSource(...)` 按 `<skill_source>` 原样透传；聚合支付要求的 `sys_id` 仍通过独立请求头 `sys_id` / `jpt-sys_id` 传递，`jpt-x-skill-source` 只承载来源值本身。\n\n## Factory 调用模式\n\nLightning SDK 使用 Factory 模式创建业务客户端，与 dg-java-sdk 的 `BasePayClient.request()` 不同：\n\n```java\nimport com.huifu.dg.lightning.factory.Factory;\nimport com.huifu.dg.lightning.biz.client.CommonPayClient;\nimport com.huifu.dg.lightning.models.payment.*;\n\n// 1. 获取聚合支付客户端\nCommonPayClient client = Factory.Payment.Common();\n\n// 2. 下单\nTradePaymentCreateRequest createReq = new TradePaymentCreateRequest();\n// ... 设置参数\nMap<String, Object> createResp = client.create(createReq);\n\n// 3. 查询\nTradePaymentScanpayQueryRequest queryReq = new TradePaymentScanpayQueryRequest();\n// ... 设置参数\nMap<String, Object> queryResp = client.query(queryReq);\n\n// 4. 关单\nTradePaymentScanpayCloseRequest closeReq = new TradePaymentScanpayCloseRequest();\nMap<String, Object> closeResp = client.close(closeReq);\n\n// 5. 关单查询\nTradePaymentScanpayClosequeryRequest closeQueryReq = new TradePaymentScanpayClosequeryRequest();\nMap<String, Object> closeQueryResp = client.closeQuery(closeQueryReq);\n\n// 6. 退款\nTradePaymentScanpayRefundRequest refundReq = new TradePaymentScanpayRefundRequest();\nMap<String, Object> refundResp = client.refund(refundReq);\n\n// 7. 退款查询\nTradePaymentScanpayRefundQueryRequest refundQueryReq = new TradePaymentScanpayRefundQueryRequest();\nMap<String, Object> refundQueryResp = client.refundQuery(refundQueryReq);\n```\n\n### 添加可选业务参数\n\nCommonPayClient 支持通过 `optional()` 方法添加额外参数：\n\n```java\nCommonPayClient client = Factory.Payment.Common();\nclient.optional(\"notify_url\", \"https://your-domain.com/notify\");\nclient.optional(\"remark\", \"备注信息\");\nMap<String, Object> response = client.create(request);\n```\n\n### 延迟交易客户端\n\n```java\nimport com.huifu.dg.lightning.biz.client.DelayTransClient;\n\nDelayTransClient delayClient = Factory.Solution.DelayTrans();\n// delayClient.confirm()      - 延迟交易确认\n// delayClient.confirmQuery() - 确认查询\n// delayClient.refund()       - 延迟交易退款\n// delayClient.refundQuery()  - 退款查询\n// delayClient.splitQuery()   - 分账查询\n```\n\n## SDK Request 类速查表\n\n| 场景 | Request 类 | 包路径 |\n|------|-----------|-------|\n| 聚合支付下单 | `TradePaymentCreateRequest` | `com.huifu.dg.lightning.models.payment` |\n| 聚合交易查询 | `TradePaymentScanpayQueryRequest` | 同上 |\n| 聚合交易关单 | `TradePaymentScanpayCloseRequest` | 同上 |\n| 聚合交易关单查询 | `TradePaymentScanpayClosequeryRequest` | 同上 |\n| 交易退款 | `TradePaymentScanpayRefundRequest` | 同上 |\n| 交易退款查询 | `TradePaymentScanpayRefundQueryRequest` | 同上 |\n\n## 与 dg-java-sdk 的关键差异\n\n| 对比项 | dg-lightning-sdk | dg-java-sdk |\n|-------|-----------------|------------|\n| 初始化 import | `com.huifu.dg.lightning.*` | `com.huifu.bspay.sdk.opps.*` |\n| MerConfig 包路径 | `com.huifu.dg.lightning.biz.config.MerConfig` | `com.huifu.bspay.sdk.opps.core.config.MerConfig` |\n| BasePay 包路径 | `com.huifu.dg.lightning.utils.BasePay` | `com.huifu.bspay.sdk.opps.core.BasePay` |\n| 设置产品号 | `setProductId()` | `setProductId()` |\n| 调用方式 | `Factory.Payment.Common().create(req)` | `BasePayClient.request(req, false)` |\n| 扩展参数 | `client.optional(key, value)` | `request.setExtendInfo(map)` |\n| HTTP 客户端 | Apache HttpClient 4.5.2 | OkHttp |\n\nFile v1.3.4:references/aggregation-java-tech-spec.md\n\n# 技术规范\r\n\r\n\r\n## 目录\r\n\r\n- 请求协议与报文模型\r\n- 签名规则\r\n- 异步通知\r\n- HTTP 连接池配置\r\n- 重试策略\r\n- API 版本\r\n\r\n## 请求协议与报文模型\r\n\r\n| 项目 | 说明 |\r\n|------|------|\r\n| 通信协议 | HTTPS |\r\n| 请求方式 | POST |\r\n| 数据格式 | JSON |\r\n| 字符编码 | UTF-8 |\r\n| 建议头 | `Content-Type: application/json;charset=UTF-8` |\r\n\r\n请求模型：\r\n\r\n```json\r\n{\r\n  \"sys_id\": \"调用方 huifu_id\",\r\n  \"product_id\": \"产品号\",\r\n  \"sign\": \"请求签名\",\r\n  \"data\": {\r\n    \"业务字段\": \"值\"\r\n  }\r\n}\r\n```\r\n\r\n响应模型：\r\n\r\n```json\r\n{\r\n  \"sign\": \"返回签名\",\r\n  \"data\": {\r\n    \"resp_code\": \"00000000\",\r\n    \"resp_desc\": \"处理成功\"\r\n  }\r\n}\r\n```\r\n\r\n## 签名规则\r\n\r\n### 请求签名\r\n\r\n1. 将请求 `data` 对象序列化为 JSON\r\n2. 对 JSON 中所有对象的 key 按 ASCII 值排序（数组不排序）\r\n3. 使用商户 RSA 私钥对排序后的 JSON 字符串进行 SHA256WithRSA 签名\r\n4. 将签名结果 Base64 编码后填入 `sign` 字段\r\n\r\n> SDK 自动完成以上步骤，开发者无需手动处理。\r\n\r\n### 响应验签\r\n\r\nSDK 自动使用汇付 RSA 公钥验证响应签名，验签失败时抛出 `BasePayException`。\r\n\r\n### RSA 密钥格式\r\n\r\n- 私钥格式：PKCS#8（Base64 编码）\r\n- 公钥格式：X.509（Base64 编码）\r\n\r\n## 异步通知\r\n\r\n### 通知机制\r\n\r\n聚合支付支持两种异步通知方式：\r\n\r\n1. **notify_url 回调**：下单时传入 `notify_url`，交易完成后汇付 POST 通知到该地址\r\n2. **Webhook 事件**：通过汇付控台配置 Webhook 接收端，支持以下事件：\r\n   - `trans.close` — 关单事件\r\n\r\n### notify_url 接收规范\r\n\r\n- **请求方式**：POST\r\n- **报文形态**：交易类回调通常提交 `sign` 和 `resp_data` 字段，业务字段位于 `resp_data`\r\n- **响应要求**：HTTP 200，body 返回 `RECV_ORD_ID_` + req_seq_id（5 秒内）\r\n- **重试策略**：超时未响应最多重试 3 次\r\n- **幂等键**：以 `hf_seq_id` 为最简幂等键，防止重复处理（完整口径见 `references/shared-async-notify.md`，建议复合键）\r\n\r\n以下示例为流程片段。`HttpServletRequest` 在 Spring Boot 2.x 使用 `javax.servlet.*`，在 3.x 使用 `jakarta.servlet.*`；`huifuPublicKey` 的注入方式可直接参考 `references/aggregation-async-webhook.md` 中的完整类示例。\r\n\r\n```java\r\n@PostMapping(\"/notify\")\r\npublic String handleNotify(HttpServletRequest request) {\r\n    String respData = request.getParameter(\"resp_data\");\r\n    String sign = request.getParameter(\"sign\");\r\n    if (!RsaUtils.verify(respData, huifuPublicKey, sign)) {\r\n        throw new IllegalArgumentException(\"汇付回调验签失败\");\r\n    }\r\n\r\n    JSONObject notification = JSON.parseObject(respData);\r\n    String reqSeqId = notification.getString(\"req_seq_id\");\r\n    String hfSeqId = notification.getString(\"hf_seq_id\");\r\n    String transStat = notification.getString(\"trans_stat\");\r\n\r\n    if (isProcessed(hfSeqId)) {\r\n        return \"RECV_ORD_ID_\" + reqSeqId;\r\n    }\r\n\r\n    // 先查单确认，再按 trans_stat 驱动订单状态\r\n    if (\"S\".equals(transStat)) {\r\n        // 交易成功\r\n    } else if (\"F\".equals(transStat)) {\r\n        // 交易失败\r\n    }\r\n\r\n    return \"RECV_ORD_ID_\" + reqSeqId;\r\n}\r\n```\r\n\r\n### Webhook 使用\r\n\r\nWebhook 是汇付提供的事件通知机制，与 notify_url 独立，可在汇付控台灵活配置接收端。\r\n\r\n配置方式参见汇付文档：[Webhook 使用说明](https://paas.huifu.com/open/doc/devtools/#/webhook/webhook_jieshao)\r\n\r\nWebhook 与 API 的签名密钥不是一套：\r\n\r\n- API 请求和 `notify_url` 回调使用 RSA 密钥体系。\r\n- Webhook 使用控台配置的终端密钥，对原始事件体计算 MD5。\r\n- Webhook 不使用汇付 RSA 公钥验签，也不要靠 `sign` 长度自动猜算法。\r\n- 详细说明见 `references/aggregation-async-webhook.md`。\r\n\r\n## HTTP 连接池配置\r\n\r\nSDK 内置 Apache HttpClient 连接池，默认配置：\r\n\r\n| 参数 | 默认值 |\r\n|------|-------|\r\n| 最大连接数 | 500 |\r\n| 每路由最大连接数 | 40 |\r\n| 每主机最大连接数 | 100 |\r\n| Socket 超时 | 20 秒 |\r\n| 连接超时 | 20 秒 |\r\n| 连接请求超时 | 30 秒 |\r\n\r\n可通过 MerConfig 自定义超时：\r\n\r\n```java\r\nmerConfig.setCustomConnectTimeout(\"30000\");\nmerConfig.setCustomSocketTimeout(\"30000\");\nmerConfig.setCustomConnectionRequestTimeout(\"40000\");\n```\r\n\r\n## 重试策略\r\n\r\nSDK 内置 HTTP 处理器最多形成 3 次总尝试，即至多 2 次重试；带实体的支付 POST 请求不自动重试。`NoHttpResponseException` 等条件只适用于处理器允许的非实体请求，不能解释成支付业务自动重试。SSL 错误、Socket 超时和 SSL 握手失败不重试；任何网络不确定结果都先按原请求标识查单，不得另造流水重提。\n\r\n## API 版本\r\n\r\n聚合支付接口涉及不同的 API 版本：\r\n\r\n| 接口 | API 路径 | 版本 |\r\n|------|---------|------|\r\n| 聚合支付下单 | /v4/trade/payment/create | v4 |\r\n| 聚合交易查询 | /v4/trade/payment/scanpay/query | v4 |\r\n| 交易退款 | /v4/trade/payment/scanpay/refund | v4 |\r\n| 交易退款查询 | /v4/trade/payment/scanpay/refundquery | v4 |\r\n| 聚合交易关单 | /v2/trade/payment/scanpay/close | v2 |\r\n| 聚合交易关单查询 | /v2/trade/payment/scanpay/closequery | v2 |\r\n| 对账单查询 | /v2/trade/check/filequery | v2 |\r\n\r\n> SDK 自动处理 API 路径路由，开发者无需关心版本差异。\n\nFile v1.3.4:references/aggregation-order-errors.md\n\n# 聚合下单返回码与勘误\r\n\r\n\r\n## 目录\r\n\r\n- 聚合正扫 / JS / APP 业务返回码\r\n- 聚合反扫业务返回码\r\n- 文档勘误与实现备注\r\n\r\n## 聚合正扫 / JS / APP 业务返回码\r\n\r\n| 返回码 | 返回描述 |\r\n|--------|----------|\r\n| `00000000` | 交易受理成功；交易状态以 `trans_stat` 为准 |\r\n| `00000100` | 下单成功 |\r\n| `10000000` | 产品号不能为空 |\r\n| `10000000` | 交易类型不能为空 |\r\n| `10000000` | `%s` 不能为空 |\r\n| `10000000` | `%s` 长度固定 `%d` 位 |\r\n| `10000000` | `%s` 最大长度为 `%d` 位 |\r\n| `10000000` | `%s` 的传入枚举 `[%s]` 不存在 |\r\n| `10000000` | `%s` 不符合 `%s` 格式，例如交易金额格式错误 |\r\n| `10000000` | 订单已超时 |\r\n| `20000000` | 重复交易 |\r\n| `21000000` | 手续费金额、手续费收取方式、手续费扣款标识、手续费子客户号、手续费账户号必须同时为空或同时必填 |\r\n| `22000000` | 产品号不存在 |\r\n| `22000000` | 产品号状态异常 |\r\n| `22000002` | 商户信息不存在 |\r\n| `22000002` | 商户状态异常 |\r\n| `22000003` | 延迟账户不存在 |\r\n| `22000003` | 商户账户信息不存在 |\r\n| `22000004` | 暂未开通分账权限 |\r\n| `22000004` | 暂未开通 `%s` 权限 |\r\n| `22000004` | 暂未开通延迟入账权限 |\r\n| `22000005` | 手续费承担方必须参与分账 |\r\n| `22000005` | 分账列表必须包含主交易账户 |\r\n| `22000005` | 其他商户分账比例过高 |\r\n| `22000005` | 商户入驻信息配置有误(多通道) |\r\n| `22000005` | 商户分期贴息未激活 |\r\n| `22000005` | 分期交易不能重复激活 |\r\n| `22000005` | 手续费配置有误 |\r\n| `22000005` | 商户贴息信息未配置 |\r\n| `22000005` | 花呗分期费率配置有误 |\r\n| `22000005` | 分账配置有误 |\r\n| `22000005` | 分账配置未包含手续费承担方 |\r\n| `22000005` | 商户入驻配置信息有误 |\r\n| `22000005` | 商户支付宝 / 微信入驻信息配置有误 |\r\n| `22000005` | 商户银联入驻信息配置有误 |\r\n| `22000005` | 商户贴息分期费率未配置渠道号 |\r\n| `22000005` | 商户贴息分期费率未配置费率类型 |\r\n| `22000005` | 商户贴息分期费率配置有误 |\r\n| `22000005` | 手续费费率未配置 |\r\n| `22000005` | 手续费计算错误 |\r\n| `22000005` | 商户贴息信息配置有误 |\r\n| `22000005` | 商户未报名活动或活动已过期 |\r\n| `22000005` | 数字货币手续费费率未配置 |\r\n| `22000005` | 数字货币手续费配置有误 |\r\n| `22000005` | 商户未配置默认入驻信息（多通道） |\r\n| `23000003` | 交易金额不足以支付内扣手续费 |\r\n| `23000003` | 优惠金额大于交易金额 |\r\n| `23000004` | 交易类型不支持 |\r\n| `23000004` | 当前交易类型不支持商户贴息 |\r\n| `90000000` | 业务执行失败，例如账户可用余额不足 |\r\n| `90000000` | 该功能已关闭，请联系客服 |\r\n| `90000000` | 交易失败，单日金额超限，请联系额服提额 |\r\n| `90000000` | 交易存在风险 |\r\n| `91111119` | 通道异常，请稍后重试 |\r\n| `98888888` | 系统错误 |\r\n\r\n## 聚合反扫业务返回码\r\n\r\n| 返回码 | 返回描述 |\r\n|--------|----------|\r\n| `10000000` | 不支持交易类型 |\r\n| `10000000` | 订单时间错误 |\r\n| `10000000` | 付款码格式异常 |\r\n| `10000000` | 请求日期必须是当前日期 |\r\n| `10000000` | `%s` 不能为空 |\r\n| `10000000` | `%s` 不符合 `%s` 格式 |\r\n| `10000000` | `%s` 长度固定 `%d` 位 |\r\n| `10000000` | `%s` 最大长度为 `%d` 位 |\r\n| `10000000` | `%s` 的传入枚举 `[%s]` 不存在 |\r\n| `10000000` | 产品号、原预授权交易请求流水、请求日期都不能为空 |\r\n| `21000000` | 手续费金额、手续费收取方式、手续费扣款标识、手续费子客户号、手续费账户号必须同时为空或同时必填 |\r\n| `22000002` | 商户信息不存在 |\r\n| `22000002` | 商户状态异常 |\r\n| `22000002` | 商户和产品的关联信息有误 |\r\n| `22000003` | 账户信息配置有误 / 账户信息不存在 |\r\n| `22000003` | 默认账户配置有误 |\r\n| `22000004` | 商户支付交易业务配置错误 / 细化指定需要的功能 |\r\n| `22000004` | 暂未开通分账权限 |\r\n| `22000004` | 暂未开通延时入账权限 |\r\n| `22000005` | 分账串配置未包含手续费承担方 |\r\n| `22000005` | 其他成员分账比例过高 |\r\n| `22000005` | 分账列表必须包含主交易账户 |\r\n| `22000005` | 内扣交易，手续费承担方必须参与分账 |\r\n| `22000005` | 商户未配置默认入驻信息(多通道) |\r\n| `22000005` | 商户贴息分期费率有误 |\r\n| `22000005` | 商户贴息分期费率未配置费率类型 |\r\n| `22000005` | 商户贴息分期费率未配置渠道号 |\r\n| `22000005` | 商户多通道配置有误 |\r\n| `22000005` | 商户入驻信息配置有误(多通道) |\r\n| `22000005` | 分账配置有误 |\r\n| `22000005` | 分账比例配置有误 |\r\n| `22000005` | 该交易暂未配置支付费率 |\r\n| `22000005` | 商户支付宝微信入驻信息配置有误 |\r\n| `22000005` | 多通道入驻信息配置有误 |\r\n| `22000005` | 商户银联入驻信息配置有误 |\r\n| `23000001` | 原预授权交易不存在 |\r\n| `23000003` | 交易金额不足以支付手续费 |\r\n| `23000003` | 优惠金额大于交易金额 |\r\n| `23000003` | 分账金额总和必须等于交易金额 |\r\n| `23000004` | 交易类型不支持 |\r\n| `90000000` | 业务执行失败，付款码无效，请重新扫码 |\r\n| `90000000` | 业务执行失败，每个二维码仅限使用一次，请刷新再试 |\r\n| `90000000` | 业务执行失败，付款码已过期，请退出重试 |\r\n| `90000000` | 业务执行失败，当前商户需补齐相关资料后才可进行支付交易，请商户联系服务商 |\r\n| `90000000` | 交易存在风险 |\r\n| `98888888` | 系统错误 |\r\n| `91111119` | 通道异常，请稍后重试 |\r\n| `99999999` | 系统异常，请重试 |\r\n| `00000000` | 交易受理成功；交易状态以 `trans_stat` 为准 |\r\n| `00000100` | 交易正在处理中 |\r\n\r\n## 文档勘误与实现备注\r\n\r\n- 官方顶部“支持的支付方式”列表漏写了 `T_APP`，但请求参数 `trade_type` 枚举明确包含 `T_APP`；当前按参数表收录。\r\n- 官方请求参数把 `req_date` 标成 `N`，但 SDK 示例和回调字段都依赖它；实现时仍建议始终传入。\r\n- 官方请求参数把 `method_expand` 标成 `Y`，但是否真正必填取决于 `trade_type`；例如 `A_NATIVE`、`U_NATIVE` 并不是每次都有强制子字段。\r\n- 官方 `A_JSAPI` / `A_NATIVE` 表中 `body` 与重复的 `ali_promo_params` 行被拼到了同一行；当前按两个独立字段理解。\r\n- 同步返回里字段名是 `trade_type`，异步回调里字段名是 `trans_type`；不要混用。\r\n- 同步返回 `trade_type` 的官方枚举含 `D_NATIVE`、`T_H5`、`T_NATIVE`，但当前请求参数页并未把这些值列入下单枚举；不要据此自行扩展请求值。\r\n- 官方另有 Webhook 能力说明，但它属于事件分发机制，不是本接口固定响应体结构。\n\nArchive v1.3.3: 105 files, 419672 bytes\n\nFiles: agents/openai.yaml (404b), references/aggregation-async-webhook.md (7041b), references/aggregation-base.md (3287b), references/aggregation-common-params.md (7171b), references/aggregation-customer-preparation.md (10271b), references/aggregation-error-codes.md (5180b), references/aggregation-faq.md (5044b), references/aggregation-java-adapter.md (2502b), references/aggregation-java-sdk-quickstart.md (9511b), references/aggregation-java-tech-spec.md (5478b), references/aggregation-order-errors.md (7063b), references/aggregation-order-method-alipay.md (7765b), references/aggregation-order-method-unionpay.md (4190b), references/aggregation-order-method-wechat.md (7071b), references/aggregation-order-quickstart.md (2826b), references/aggregation-order-request.md (11876b), references/aggregation-order-response.md (10548b), references/aggregation-order-tx-metadata.md (11529b), references/aggregation-order.md (3912b), references/aggregation-payload-construction.md (10005b), references/aggregation-php-adapter.md (11309b), references/aggregation-python-adapter.md (7071b), references/aggregation-python-scenarios.md (7929b), references/aggregation-query-close-query.md (7479b), references/aggregation-query-payment-query.md (21752b), references/aggregation-query-php-scenarios.md (9210b), references/aggregation-query-quickstart.md (1509b), references/aggregation-query-reconciliation.md (9371b), references/aggregation-query-trade-close.md (7889b), references/aggregation-query.md (3522b), references/aggregation-quickstart.md (3616b), references/aggregation-refund-query.md (9071b), references/aggregation-refund-quickstart.md (1362b), references/aggregation-refund.md (15213b), references/canonical-regression-prompts.md (2612b), references/checkout-js-callback-and-confirmation.md (2350b), references/checkout-js-component-modes.md (2664b), references/checkout-js-create-preorder-contract.md (3381b), references/checkout-js-framework-integration-notes.md (1806b), references/checkout-js-integration-flow.md (3260b), references/checkout-js-readme.md (1549b), references/checkout-js.md (2364b), references/copilot-existing-system.md (4883b), references/copilot-go-live-checklist.md (3136b), references/copilot-onboarding.md (5174b), references/copilot-parameter-review.md (2960b), references/copilot-solution-cards.md (8682b), references/copilot-solution-selection.md (3370b), references/copilot-troubleshooting-playbooks.md (7672b), references/hostingpay-async-webhook.md (11437b), references/hostingpay-base.md (2218b), references/hostingpay-common-params.md (6572b), references/hostingpay-customer-preparation.md (9974b), references/hostingpay-error-codes.md (4399b), references/hostingpay-faq.md (4983b), references/hostingpay-java-adapter.md (2191b), references/hostingpay-java-sdk-quickstart.md (6641b), references/hostingpay-java-tech-spec.md (11425b), references/hostingpay-payload-construction.md (7898b), references/hostingpay-php-adapter.md (12216b), references/hostingpay-preorder-alipay-mini.md (23087b), references/hostingpay-preorder-douyin-direct.md (14269b), references/hostingpay-preorder-h5-pc-channel.md (9875b), references/hostingpay-preorder-h5-pc-errors.md (1284b), references/hostingpay-preorder-h5-pc-request.md (10144b), references/hostingpay-preorder-h5-pc-response-channel.md (11665b), references/hostingpay-preorder-h5-pc-response.md (6402b), references/hostingpay-preorder-h5-pc.md (9489b), references/hostingpay-preorder-php-scenarios.md (9988b), references/hostingpay-preorder-quickstart.md (7869b), references/hostingpay-preorder-wechat-mini.md (27034b), references/hostingpay-preorder.md (3817b), references/hostingpay-python-adapter.md (7092b), references/hostingpay-python-scenarios.md (9321b), references/hostingpay-query-payment-status-query.md (24116b), references/hostingpay-query-php-scenarios.md (6573b), references/hostingpay-query-quickstart.md (5206b), references/hostingpay-query-reconciliation.md (12588b), references/hostingpay-query-splitpay.md (9081b), references/hostingpay-query-trade-close.md (7713b)\n\nFile v1.3.3:SKILL.md\n\n---\nname: huifu-pay-integration\ndescription: \"汇付支付交易集成：用于聚合支付、托管支付、checkout-js、下单、查单、关单、退款、对账、支付通知、签名验签、请求头、幂等、交易终态、本地沙箱和支付上线；不用于企业/个人商户进件、图片上传、商户业务开通、商户详情或申请状态查询，这些任务使用 huifu-merchant-onboarding。\"\n---\n\n# 汇付支付集成\n\n## 版权声明\n\n本 Skill 中的汇付支付资料整理自上海汇付支付有限公司官方开放平台与官方产品文档；原始文档及其更新维护权归汇付支付官方所有。仅作技术学习交流与接口集成辅助使用，详见 `references/shared-copyright-notice.md`。\n\n## 执行流程\n\n1. 识别产品线、Endpoint、接入阶段、技术栈、端形态、当前目标和是否存量系统。完成标准：这些维度均已唯一确定，极速版产品场景与 V4 API 枚举已分开。\n2. 检查下方硬检查点；命中时停止生成可运行实现，只问一个最高优先级问题。完成标准：已记录命中或未命中的具体理由，SDK 传输安全和调试日志均已检查。\n3. 从精确路由中选择 3–5 份 reference。只有用户同时提出两个独立目标时才合并；完整 DTO、响应或嵌套字段任务必须包含完整字段目录。完成标准：每个目标均有一跳可达的原子接口页、合同定位路径、实际 JSON/解码路径（分别记录 wire 字段路径与 String(JSON) 解码后路径）和明确语言 adapter，不使用“对应文档”占位，也不把官网展示分组当成 wire key；只有官网明确标注“方便文档展示”时才从 wire 路径移除该分组。\n4. 首次接入输出产品线判断和方案卡；存量接入输出新增、保留、人工确认和回归检查。完成标准：请求、前端交接、通知、终态和补偿查询责任均已落到具体组件。\n5. 最后应用签名、验签、幂等、终态确认、请求字段保留和凭据安全规则。完成标准：每项均已检查，未知合同明确标记并停止生成相应实现。\n\n字段说明中的链接按其用途处理：完整字段目录已将官网 `#锚点` / 相对链接解析到各自接口原始页，并保留相对地址原文；绝对地址保持官网值。已确认的坏锚点使用显式映射：`#业务返回码` 补公共返回码全集，聚合下单 `notify_url` 的“异步返回参数”同时映射正扫、反扫通知参数和通用异步消息规范。只有命中本次字段的规范文档、编码表或渠道指引才作为外部资料提示。`notify_url`、`jump_url`、下载地址、二维码等裸 URL 示例是运行时值或格式示例，不是默认值、推荐地址或外部资料。\n\n本 Skill 只处理支付交易。企业、个人商户进件、图片资料、业务开通、商户详情和申请状态使用 `$huifu-merchant-onboarding`；不要从本 Skill 读取进件实现文档。\n\n## 精确路由\n\n| 场景 | 最小 reference 集 |\n| --- | --- |\n| 首次接入、产品线不明 | `references/shared-overview.md`、`references/copilot-onboarding.md`、`references/copilot-solution-selection.md` |\n| 存量系统接入 | `references/copilot-existing-system.md`、`references/copilot-solution-selection.md` |\n| 聚合支付快速接入 | `references/aggregation-quickstart.md`、`references/aggregation-customer-preparation.md` |\n| 聚合下单参数或代码 | `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` 补微信/支付宝/银联分册 |\n| 聚合交易查询 | `references/aggregation-query-payment-query.md` |\n| 返回码、公共编码或术语 | `aggregation-error-codes.md`、`aggregation-common-params.md`；具体字段仍补对应原子接口页 |\n| 聚合关单 | `references/aggregation-query-trade-close.md` |\n| 聚合对账 | `references/aggregation-query-reconciliation.md` |\n| 聚合退款或退款查询 | `references/aggregation-refund.md`、`references/payment-complete-field-catalog.md`，查询时补 `references/aggregation-refund-query.md` |\n| 托管支付快速接入 | `references/hostingpay-quickstart.md`、`references/hostingpay-customer-preparation.md` |\n| 托管预下单 | `references/hostingpay-preorder.md`、`references/payment-complete-field-catalog.md`，再按端形态补一个原子文档 |\n| 抖音直连、`pre_order_type=4` | `references/hostingpay-preorder.md`、`references/hostingpay-preorder-douyin-direct.md` |\n| 拆单支付查询、`splitpay/query` | `references/hostingpay-query.md`、`references/hostingpay-query-splitpay.md`；完整 DTO 同时执行下方完整字段目录路由 |\n| 托管退款 | `references/hostingpay-refund.md`；完整 DTO 同时执行下方完整字段目录路由，Java setter 问题补 `references/hostingpay-faq.md` |\n| 托管普通交易查询 | `references/hostingpay-query.md`、`references/hostingpay-query-payment-status-query.md` |\n| 托管交易关单 | `references/hostingpay-query.md`、`references/hostingpay-query-trade-close.md` |\n| 托管退款查询 | `references/hostingpay-refund.md`、`references/hostingpay-refund-query.md`；完整 DTO 同时执行下方完整字段目录路由 |\n| 托管对账 | `references/hostingpay-query.md`、`references/hostingpay-query-reconciliation.md` |\n| checkout-js 已完成服务端前置 | `references/checkout-js.md`、`references/checkout-js-callback-and-confirmation.md`、`references/hostingpay-async-webhook.md` |\n| checkout-js 前置未确认 | `references/checkout-js-create-preorder-contract.md`，触发硬检查点 |\n| 支付通知、重复通知、幂等 | `references/shared-async-notify.md`、`references/copilot-troubleshooting-playbooks.md` |\n| 控台 Webhook 验签 | `references/shared-webhook-signing.md` |\n| Java / PHP / Python SDK | 先读 `references/shared-server-sdk-matrix.md`；再按语言与产品线精确选择 `references/aggregation-java-adapter.md`、`references/hostingpay-java-adapter.md`、`references/aggregation-php-adapter.md`、`references/hostingpay-php-adapter.md`、`references/aggregation-python-adapter.md` 或 `references/hostingpay-python-adapter.md` |\n| 请求头和 `skill_source` | `references/shared-request-header-policy.md` |\n| DTO/Controller 字段保留 | `references/shared-request-field-preservation.md` |\n| 完整 DTO、完整响应、嵌套字段或同名字段核对 | 对应原子接口页、`references/payment-complete-field-catalog.md`；代码任务再补语言 adapter |\n| appid/openid、支付路由、对账或资金运营 FAQ | `references/payment-operations-faq.md`、`references/copilot-troubleshooting-playbooks.md` |\n| 本地沙箱 | `references/shared-local-sandbox.md`，再补通知、查询或上线检查 |\n| 上线前检查 | `references/copilot-go-live-checklist.md`、`references/copilot-existing-system.md` |\n| 版本与升级 | `references/skill-version-policy.md` |\n\n按语言选择 reference：\n\n- Java：公共矩阵 + 产品线 Java adapter；先核对项目中的实际 SDK 版本和 Request 类。\n- PHP：公共矩阵 + 产品线 PHP adapter；保留安全初始化顺序，但不得使用会启用 `DEBUG=true` 的官方 Demo/Composer loader。\n- Python：公共矩阵 + 产品线 Python adapter；不要把 SDK 网络重试解释成业务重试。\n- 前端：checkout-js 只负责展示与前端事件，支付终态仍由服务端确认。\n\n## 🔴 CHECKPOINT · HARD STOP\n\n命中以下任一情况时，首行输出 `🔴 CHECKPOINT · HARD STOP：硬检查点。`，列出当前判断和本轮 references，只问一个最高优先级问题：\n\n1. 无法区分聚合支付、托管支付和 checkout-js。\n2. 无法区分服务端接入、前端页面接入和最终状态确认。\n3. 用户要求现成可运行代码，但当前接口、端形态或回退路径不唯一。\n4. checkout-js 的托管预下单、支付通知验签/幂等和查单补偿未确认。\n5. 用户要求联调或生产代码，但缺少环境、系统号、产品号、商户号、RSA 密钥安全来源、通知地址或必要渠道标识。未显式配置 `skill_source` 时使用下述确定性默认值，不因此硬停。\n6. 本地 SDK 源码与文档在请求头、签名、版本或能力覆盖上冲突。\n7. 用户要求 Java 或 PHP 联调/生产可运行代码，但锁定的 Lightning Java `1.0.5`、通用 Java `3.0.40` 或 PHP `2.0.30` 仍关闭 TLS 证书链、对端或主机名校验；在经批准的安全制品通过源码和错证书/错域名测试前不得输出可上线实现。\n8. 用户要求 PHP 联调或生产可运行代码，但不能证明在加载 SDK、Demo/Composer 配置和调用 `BsPay::init` 之前已将全局 `DEBUG` 固定为 `false`，或仍使用会定义 `DEBUG=true` 的官方 Demo/Composer 入口。\n\nSDK 安装、初始化和安全 loader 骨架不因产品线不明而硬停，但不得猜具体业务 Request 或字段；PHP 骨架必须在加载任何 SDK 文件前拒绝 `DEBUG=true`。\n\n## 支付终态与通知\n\n- 同步受理成功、`jump_url`、浏览器回跳和前端 callback 都不是支付终态。\n- 对支付通知先验签，再校验金额、商户号、订单号和状态，最后做幂等更新。\n- 通知缺失时使用官方查单补偿；不要伪造通知、跳过验签或直接改成功。\n- 控台 Webhook 和接口 `notify_url` 是不同协议，不能混用签名位置或 ACK。\n- 聚合下单的同一个 `notify_url` 同时承接正扫和反扫两套通知参数；按 `trade_type` 分场景解析，不得只实现一套。\n\n## 请求和凭据\n\n- 保留 Controller/DTO 已接收的 `req_date`、`req_seq_id`、金额、商户号和原交易定位键；缺失或非法时报错，不自行重写。\n- 私钥、系统号和生产商户号只能从服务端安全配置读取，不能写入前端、日志、仓库或回答示例。\n- PHP `2.0.30` 默认 `DEBUG=false`，但官方 `BsPayDemo/loader.php` 与 `Composer/BsPayConfig.php` 会在初始化前启用调试；调试日志会包含带 RSA 私钥的 `MerConfig`、完整请求和响应。联调/生产必须拒绝这些入口，并在加载任何 SDK 文件前固定 `DEBUG=false`。\n- 未显式配置 `skill_source` 时，按当前请求实际加载并参与生成的 Skill 集合取值：仅本 Skill 使用 `hfps/1.3.3`；支付与进件两个 Skill 都参与当前请求时使用 `hfps/1.3.3;hfms/1.0.0`。仅安装在仓库但未参与当前请求不计入；顺序固定为支付、进件，使用一个英文分号且不加空格。\n- 调用方显式提供经确认的 `skill_source` 合同值时原样透传；不得再追加 `sys_id`。\n- 不因方便绕过 SDK 的签名、验签、证书或请求头路径。\n\n## 本地沙箱边界\n\n本地沙箱仅验证本地协议闭环、状态机、幂等、故障注入和报告，不验证真实商户权限、通道、费率、风控、资金结果或生产准入。冻结的 `r1–r4` 合同和样例包属于历史支付证据，不得因本次 Skill 拆分改名或重算。\n\n## 输出要求\n\n回答至少包含：\n\n1. 当前产品线、阶段、技术栈和存量判断。\n2. 本轮实际使用的 3–5 份 references。\n3. 请求、通知、终态和安全边界。\n4. 缺失信息、人工确认项和下一步。\n\n不要输出费率、合规、通道准入或生产失败责任结论；只整理脱敏升级材料并转人工确认。\n\n## 当前版本\n\n| 项目 | 口径 |\n| --- | --- |\n| Skill 版本 | `1.3.3` |\n| 能力范围 | 聚合支付、托管支付、checkout-js、支付通知、SDK、本地沙箱和支付上线 |\n| 进件能力 | 已迁移至独立 `$huifu-merchant-onboarding` |\n| 聚合支付 Java SDK | `dg-lightning-sdk 1.0.5` |\n| 托管支付 Java SDK | `dg-java-sdk 3.0.40` |\n| PHP SDK | `huifurepo/dg-php-sdk 2.0.30` |\n| Python SDK | `dg-sdk 2.0.24`，import 为 `dg_sdk` |\n\nFile v1.3.3:_meta.json\n\n{\n  \"ownerId\": \"kn7as5mtmp7qjv21jr9n15qth182kat3\",\n  \"slug\": \"huifu-pay-integration\",\n  \"version\": \"1.3.3\",\n  \"publishedAt\": 1785503143171\n}\n\nFile v1.3.3:references/aggregation-async-webhook.md\n\n# 异步通知与 Webhook\r\n\r\n> 本文面向 `references/aggregation-base.md` 依赖的聚合支付 Skill，重点把交易通知的真实报文形态、验签方式、幂等和终态判断说明清楚。\r\n\r\n\r\n## 目录\r\n\r\n- 两种异步机制\r\n- `notify_url` 使用规范\r\n- 聚合交易通知报文形态\r\n- Spring Boot 接收、验签与查单示例\r\n- 终态判断原则\r\n- 签名差异\r\n- Webhook 使用场景\r\n- Webhook 落地步骤\r\n- Webhook 重发规则\r\n- 使用建议\r\n- 参考\r\n\r\n## 两种异步机制\r\n\r\n| 机制 | 入口 | 用途 | 签名方式 |\r\n|------|------|------|----------|\r\n| `notify_url` | 下单、退款等接口请求参数 | 交易结果回调 | 汇付 RSA 公钥验签 |\r\n| Webhook | 汇付控台端点订阅 | 平台事件通知 | 终端密钥 + MD5 原始事件体 |\r\n\r\n## `notify_url` 使用规范\r\n\r\n- 汇付以 HTTP `POST` 发送交易结果。\r\n- 响应必须在 5 秒内返回。\r\n- 正确应答格式为：HTTP `200` + `RECV_ORD_ID_` + `req_seq_id`。\r\n- 未及时应答或应答格式不正确时，汇付会自动重试，最多 3 次。\r\n- 自定义端口需落在 `8000-9005`。\r\n- URL 不要带查询参数。\r\n- 同一笔交易可能会重复通知，必须用 `hf_seq_id` 做幂等。\r\n\r\n## 聚合交易通知报文形态\r\n\r\n聚合支付的交易类异步通知，外层通常包含以下 4 个网关字段：\r\n\r\n| 字段 | 说明 |\r\n|------|------|\r\n| `resp_code` | 网关返回码 |\r\n| `resp_desc` | 网关返回信息 |\r\n| `sign` | 对整个业务数据的签名 |\r\n| `resp_data` | 业务数据 JSON 字符串 |\r\n\r\n其中真正要驱动业务的字段在 `resp_data` 里，而不是直接平铺在最外层。\r\n\r\n```json\r\n{\r\n  \"resp_code\": \"10000\",\r\n  \"resp_desc\": \"成功调用\",\r\n  \"sign\": \"返回签名串\",\r\n  \"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\\\"}\"\r\n}\r\n```\r\n\r\n## Spring Boot 接收、验签与查单示例\r\n\r\n```java\r\nimport com.alibaba.fastjson.JSON;\r\nimport com.alibaba.fastjson.JSONObject;\r\n// Spring Boot 2.x: import javax.servlet.http.HttpServletRequest;\r\n// Spring Boot 3.x: import jakarta.servlet.http.HttpServletRequest;\r\nimport java.util.Objects;\r\nimport org.springframework.beans.factory.annotation.Value;\r\nimport org.springframework.util.StringUtils;\r\nimport org.springframework.web.bind.annotation.PostMapping;\r\nimport org.springframework.web.bind.annotation.RequestMapping;\r\nimport org.springframework.web.bind.annotation.RestController;\r\n\r\n@RestController\r\n@RequestMapping(\"/notify\")\r\npublic class AggregateNotifyController {\r\n\r\n    private final String huifuPublicKey;\r\n    private final AggregateQueryService queryService;\r\n    private final NotifyIdempotentService idempotentService;\r\n\r\n    public AggregateNotifyController(\r\n            @Value(\"${huifu.rsa-public-key}\") String huifuPublicKey,\r\n            AggregateQueryService queryService,\r\n            NotifyIdempotentService idempotentService) {\r\n        this.huifuPublicKey = huifuPublicKey;\r\n        this.queryService = queryService;\r\n        this.idempotentService = idempotentService;\r\n    }\r\n\r\n    @PostMapping(\"/payment\")\r\n    public String onNotify(HttpServletRequest request) {\r\n        String respData = request.getParameter(\"resp_data\");\r\n        String sign = request.getParameter(\"sign\");\r\n        if (!StringUtils.hasText(respData) || !StringUtils.hasText(sign)) {\r\n            throw new IllegalArgumentException(\"汇付回调缺少 resp_data 或 sign\");\r\n        }\r\n        if (!RsaUtils.verify(respData, huifuPublicKey, sign)) {\r\n            throw new IllegalArgumentException(\"汇付回调验签失败\");\r\n        }\r\n\r\n        JSONObject dataObj = JSON.parseObject(respData);\r\n        String reqSeqId = dataObj.getString(\"req_seq_id\");\r\n        String reqDate = dataObj.getString(\"req_date\");\r\n        String hfSeqId = dataObj.getString(\"hf_seq_id\");\r\n        String transStat = dataObj.getString(\"trans_stat\");\r\n        String transType = dataObj.getString(\"trans_type\");\r\n\r\n        if (idempotentService.isProcessed(hfSeqId)) {\r\n            return \"RECV_ORD_ID_\" + reqSeqId;\r\n        }\r\n\r\n        AggregateQueryResult queryResult = queryService.query(reqDate, reqSeqId);\r\n        if (!Objects.equals(queryResult.getTransStat(), transStat)) {\r\n            throw new IllegalStateException(\"异步通知与查单状态不一致\");\r\n        }\r\n\r\n        if (\"S\".equals(transStat)) {\r\n            // 支付成功：更新订单并执行后续业务\r\n        } else if (\"F\".equals(transStat)) {\r\n            // 支付失败：记录失败原因\r\n        } else if (\"P\".equals(transStat)) {\r\n            // 处理中：继续等待通知或轮询\r\n        } else {\r\n            throw new IllegalStateException(\"未知 trans_stat=\" + transStat);\r\n        }\r\n\r\n        // 同步返回常见字段名是 trade_type，异步回调字段名是 trans_type，不要混用\r\n        // 例如：log.info(\"notify reqSeqId={}, hfSeqId={}, transType={}, transStat={}\", ...);\r\n        return \"RECV_ORD_ID_\" + reqSeqId;\r\n    }\r\n}\r\n```\r\n\r\n## 终态判断原则\r\n\r\n- `trans_stat`、查单结果、幂等键可以驱动订单状态流转。\r\n- `resp_code`、`resp_desc`、HTTP 返回码主要用于排查，不直接驱动订单终态。\r\n- 不要写“`resp_code=00000000` 就直接支付成功”这种逻辑。\r\n\r\n## 签名差异\r\n\r\n| 场景 | 密钥 | 说明 |\r\n|------|------|------|\r\n| API 请求与 `notify_url` | 商户 RSA 私钥签名，汇付 RSA 公钥验签 | `SHA256WithRSA` |\r\n| Webhook | Webhook 终端密钥 | `MD5(raw_body + endpoint_key)`，与 API RSA 密钥无关 |\r\n\r\nWebhook 必须先对原始请求体验签，再 JSON 解析事件体。不要先反序列化后重新序列化，也不要用 `sign` 长度自动猜 MD5 / RSA。完整共享规则见 `shared-webhook-signing.md`。\r\n\r\n## Webhook 使用场景\r\n\r\nWebhook 更适合做平台级事件通知，例如：\r\n\r\n| 事件类型编号 | 说明 |\r\n|--------------|------|\r\n| `trans.close` | 关单事件 |\r\n| `refund.standard` | 退款事件 |\r\n| `statement.day` | 日结算通知 |\r\n| `statement.auto` | 自动结算通知 |\r\n| `settlement.encashment` | 取现通知 |\r\n\r\n## Webhook 落地步骤\r\n\r\n1. 在服务端创建 HTTPS 端点。\r\n2. 在汇付控台注册端点并选择订阅事件。\r\n3. 使用测试事件验证联通性。\r\n4. 处理正式事件，并监控失败重试。\r\n\r\n## Webhook 重发规则\r\n\r\n- 首次发送失败后会快速重试 3 次。\r\n- 之后按小时级补发，直到成功。\r\n- 控台支持手工重新推送。\r\n\r\n## 使用建议\r\n\r\n- 支付交易主状态仍优先依赖 `notify_url` 和主动查询。\r\n- Webhook 更适合对账、结算、告警和平台事件同步。\r\n- API 回调验签和 Webhook 验签必须分开实现，不要共用密钥。\r\n\r\n## 参考\r\n\r\n- 平台 Webhook 工具介绍：<https://paas.huifu.com/open/doc/devtools/#/webhook/webhook_jieshao>\n\nFile v1.3.3:references/aggregation-base.md\n\n# 聚合支付基础\r\n\r\n这份文档负责聚合支付的初始化、公共参数、语言边界和接入前置判断。\r\n\r\n## 什么时候读这里\r\n\r\n- 第一次接聚合支付\r\n- 需要确认 `trade_type`、公共环境变量、初始化顺序\r\n- 需要判断当前应该走 Java、PHP 还是 Python\r\n\r\n## 推荐阅读顺序\r\n\r\n```text\r\nshared-overview\r\n  -> shared-signing-v2\r\n  -> shared-request-header-policy\r\n  -> aggregation-base\r\n  -> aggregation-order / aggregation-query / aggregation-refund\r\n```\r\n\r\n## 当前版本口径\r\n\r\n| 项目 | 当前值 |\r\n| --- | --- |\r\n| Java SDK | `dg-lightning-sdk 1.0.5` |\r\n| PHP 覆盖范围 | 下单、扫码交易查询、关单、关单查询、退款、退款查询、对账 |\r\n| `HUIFU_SKILL_SOURCE` 最终值 | `<skill_source>` |\r\n\r\n## 必备环境变量\r\n\r\n| 环境变量 | 用途 |\r\n| --- | --- |\r\n| `HUIFU_PRODUCT_ID` | 汇付分配的产品号 |\r\n| `HUIFU_SYS_ID` | 渠道商 / 商户 `huifu_id` |\r\n| `HUIFU_RSA_PRIVATE_KEY` | 请求签名私钥 |\r\n| `HUIFU_RSA_PUBLIC_KEY` | 响应验签公钥 |\r\n| `HUIFU_SKILL_SOURCE` | 可选来源覆盖项，请求头层按 `<skill_source>` 原样透传 |\r\n\r\n## 初始化前确认事项\r\n\r\n1. 先读 `references/shared-signing-v2.md`\r\n2. 先读 `references/shared-async-notify.md`\r\n3. 如果不是 Java，必须额外核对 `references/shared-request-header-policy.md`\r\n4. 不要猜测 `sub_openid`、`buyer_id`、`auth_code`、`devs_id`、`fee_sign` 等运行时值\r\n\r\n## 聚合支付主流程\r\n\r\n```text\r\n准备产品号和密钥\r\n  -> 初始化 SDK 或 HTTP 客户端\r\n  -> 选择 trade_type\r\n  -> aggregation-order 下单\r\n  -> aggregation-query 查单 / 关单 / 对账\r\n  -> aggregation-refund 退款\r\n```\r\n\r\n## trade_type 速查\r\n\r\n| trade_type | 说明 |\r\n| --- | --- |\r\n| `T_JSAPI` | 微信公众号支付 |\r\n| `T_MINIAPP` | 微信小程序支付 |\r\n| `T_APP` | 微信 APP 支付 |\r\n| `T_MICROPAY` | 微信付款码反扫 |\r\n| `A_JSAPI` | 支付宝 JS 支付 |\r\n| `A_NATIVE` | 支付宝正扫 |\r\n| `A_MICROPAY` | 支付宝付款码反扫 |\r\n| `U_JSAPI` | 银联 JS 支付 |\r\n| `U_NATIVE` | 银联正扫 |\r\n| `U_MICROPAY` | 银联付款码反扫 |\r\n\r\n## 语言边界\r\n\r\n- Java 是聚合支付完整基线\r\n- PHP 已覆盖聚合支付核心主链路与对账；默认入口先读 `references/aggregation-php-adapter.md` 与 `references/aggregation-query-php-scenarios.md`\r\n- Python 已覆盖聚合支付核心主链路与对账；默认入口先读 `references/aggregation-python-adapter.md` 与 `references/aggregation-python-scenarios.md`\r\n- 当前 Skill 包不再内置 PHP 模板资产；PHP 默认走官方 `huifurepo/dg-php-sdk`\r\n- C#、Go 当前只保留统一入口说明，不提供现成业务模板\r\n\r\n## 公共字段提醒\r\n\r\n- `req_seq_id` 必须保证当日唯一\r\n- `req_date` 建议始终保存，后续查询、关单、退款都要回用\r\n- `method_expand`、`acct_split_bunch`、`terminal_device_data`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info` 应先建模再序列化；`tx_metadata` 本身不作为请求字段上送\r\n\r\n## 下一步怎么走\r\n\r\n- 要创建订单：读 `references/aggregation-order.md`\r\n- 要查单 / 关单 / 对账：读 `references/aggregation-query.md`\r\n- 要退款：读 `references/aggregation-refund.md`\n\nFile v1.3.3:references/aggregation-common-params.md\n\n# 公共参数说明\n\n官方公共资料入口：\n\n- [基础参数汇总](https://paas.huifu.com/partners/api/doc/csfl/api_csfl.md)：地区、银行、支行、MCC、交易类型、文件类型等公共编码/枚举的入口。\n- [名词解释](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_mcjs.md)：ATU、H5、结算周期、手续费等术语口径。\n- [返回码](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_ywm.md)：网关与业务返回码全集。\n\n这些页面是公共字典和术语来源，不覆盖具体接口页对字段必填、条件、类型和层级的定义；发生差异时保留两边证据并按具体接口合同处理。\n\n\n## 目录\n\r\n- 公共请求参数\r\n- 公共返回参数\r\n- 业务数据通用字段\r\n- 交易状态枚举（trans_stat）\r\n- 金额格式\r\n- 日期时间格式\r\n- 流水号规则\r\n- 支付类型详解\r\n- 标准字段与格式约束\r\n- 结算术语\r\n- 手续费术语\r\n\r\n## 公共请求参数\r\n\r\n所有聚合支付 API 请求的外层参数：\r\n\r\n| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |\r\n|------|-------|------|------|------|------|\r\n| sys_id | 系统号 | String | 32 | Y | 渠道商/代理商/商户的 huifu_id |\r\n| product_id | 产品号 | String | 32 | Y | 汇付分配的产品号，如 `MYPAY`、`YYZY` |\r\n| sign | 加签结果 | String | 512 | Y | SDK 自动生成，无需手动处理 |\r\n| data | 请求数据 | JSON | - | Y | 业务请求参数 |\r\n\r\n> 强制请求头约束：\r\n> - 必须带 `jpt-x-skill-source: <skill_source>`\r\n> - 如果当前按 PHP 接入，且接口业务报文里存在 `huifu_id`，还必须带 `jpt-x-skill-huifu_id: <data.huifu_id>`\r\n> - 当前 Skill 包对齐的官方 PHP SDK 主链路在 `MerConfig.skill_source` 已配置时，会自动带 `jpt-x-skill-source`，并在当前请求 `huifu_id` 存在且非空时自动带 `jpt-x-skill-huifu_id`\r\n> - 当前 Java SDK 基线也会在接口业务报文里 `huifu_id` 存在且非空时自动带 `jpt-x-skill-huifu_id: <data.huifu_id>`\r\n> - 这两项属于 HTTP 请求头，不属于 `data` 字段本身；完整口径见 `references/shared-request-header-policy.md`\r\n\r\n### sys_id 说明\r\n\r\n| 主体类型 | sys_id 填写 |\r\n|---------|-----------|\r\n| 渠道商/代理商 | 渠道商/代理商的 huifu_id |\r\n| 直连商户 | 商户自身的 huifu_id |\r\n\r\n> **sys_id vs huifu_id**：`sys_id` 是外层公共参数，标识调用方身份；`huifu_id` 是 `data` 内业务参数，标识交易商户。渠道商模式下两者不同，直连商户模式下两者相同。\r\n\r\n## 公共返回参数\r\n\r\n| 参数 | 中文名 | 类型 | 长度 | 说明 |\r\n|------|-------|------|------|------|\r\n| sign | 签名 | String | 512 | SDK 自动验证 |\r\n| data | 响应内容体 | JSON | - | 业务返回参数 |\r\n\r\n## 业务数据通用字段\r\n\r\n以下字段在多数业务接口的 `data` 中出现：\r\n\r\n| 参数 | 中文名 | 类型 | 说明 |\r\n|------|-------|------|------|\r\n| resp_code | 业务响应码 | String(8) | 接口受理返回码，用于排查；订单终态仍看 `trans_stat` 和查单结果 |\r\n| resp_desc | 业务响应信息 | String(512) | 响应描述 |\r\n| huifu_id | 商户号 | String(32) | 商户 huifu_id |\r\n| req_date | 请求日期 | String(8) | 格式 yyyyMMdd |\r\n| req_seq_id | 请求流水号 | String(128) | 同一 huifu_id 下当天唯一 |\r\n| hf_seq_id | 汇付全局流水号 | String(128) | 汇付生成的全局唯一标识 |\r\n\r\n## 交易状态枚举（trans_stat）\r\n\r\n| 值 | 含义 | 处理方式 |\r\n|---|------|---------|\r\n| I | 初始 | 罕见状态，联系汇付技术人员 |\r\n| P | 处理中 | 等待异步通知或轮询查询接口 |\r\n| S | 成功 | 交易完成 |\r\n| F | 失败 | 交易失败，可重新发起 |\r\n\r\n## 金额格式\r\n\r\n- **单位**：元（CNY）\r\n- **精度**：保留两位小数\r\n- **最小值**：0.01\r\n- **示例**：`\"1.00\"`、`\"100.50\"`、`\"0.01\"`\r\n\r\n## 日期时间格式\r\n\r\n| 格式 | 说明 | 示例 |\r\n|------|------|------|\r\n| yyyyMMdd | 日期 | `20250320` |\r\n| yyyyMMddHHmmss | 日期时间（14位） | `20250320143000` |\r\n| HHmmss | 时间（6位） | `143000` |\r\n\r\n## 流水号规则\r\n\r\n| 字段 | 规则 | 说明 |\r\n|------|------|------|\r\n| req_seq_id | 同一 huifu_id 下当天唯一 | 商户自行生成 |\r\n| hf_seq_id | 全局唯一 | 汇付返回，用于查询/退款 |\r\n| org_req_seq_id | 原交易的 req_seq_id | 用于关联原交易 |\r\n| org_hf_seq_id | 原交易的 hf_seq_id | 可替代 org_req_seq_id |\r\n\r\n## 支付类型详解\r\n\r\n### 正扫 vs 反扫\r\n\r\n| 类型 | 说明 | 适用 trade_type |\r\n|------|------|----------------|\r\n| 正扫 (NATIVE) | 商户生成二维码，用户扫码支付 | A_NATIVE、U_NATIVE |\r\n| 反扫 (MICROPAY) | 用户出示付款码，商户扫码收款 | T_MICROPAY、A_MICROPAY、U_MICROPAY |\r\n| JS 支付 (JSAPI) | 在对应 APP 内通过 JS 调起支付 | T_JSAPI、A_JSAPI、U_JSAPI |\r\n| 小程序 (MINIAPP) | 微信小程序内支付 | T_MINIAPP |\r\n| APP 支付 | 原生 APP 内支付 | T_APP |\r\n\r\n### method_expand 参数\n\n本节只描述**聚合下单请求侧**的 `request.data.method_expand`，不得外推到查询响应。不同 `trade_type` 需要传入不同的 `method_expand` 扩展参数。请求侧的 `trade_type` 是场景选择器，这 10 个枚举值本身不是 `request.data.method_expand` 的 key；该 JSON 内容直接是当前请求场景对象本身。查询响应 `response.data.method_expand` 同样只解码一次且字段单层平铺，具体字段与勘误必须改读 `aggregation-query-payment-query.md`。\n\r\n| trade_type | method_expand 必填字段 | 说明 |\r\n|-----------|----------------------|------|\r\n| T_JSAPI | sub_appid, sub_openid | 微信公众号 AppID 和用户 OpenID |\r\n| T_MINIAPP | sub_appid, sub_openid | 微信小程序 AppID 和用户 OpenID |\r\n| T_APP | sub_appid | 微信开放平台 AppID |\r\n| T_MICROPAY | auth_code | 用户付款码 |\r\n| A_JSAPI | buyer_id 或 buyer_logon_id | 支付宝买家 ID / 账号，二选一 |\r\n| A_NATIVE | - | 无需额外参数 |\r\n| A_MICROPAY | auth_code | 用户付款码 |\r\n| U_JSAPI | user_id, qr_code, customer_ip | 银联 JS 常见关键字段 |\r\n| U_NATIVE | - | 无需额外参数 |\r\n| U_MICROPAY | auth_code | 用户付款码 |\r\n\r\n## 标准字段与格式约束\r\n\r\n- 请求和返回统一使用 JSON，字符编码统一为 `UTF-8`。\r\n- 参数命名统一采用下划线命名法，如 `req_seq_id`、`trade_type`。\r\n- 金额单位统一为元，保留两位小数。\r\n- 时间统一按北京时间（东八区）处理。\r\n- 数值字段在 API 层尽量使用字符串承载，避免精度损失。\r\n\r\n## 结算术语\r\n\r\n| 术语 | 说明 |\r\n|------|------|\r\n| T1 自动结算 | 前一工作日周期内余额结算到银行卡 |\r\n| D1 自动结算 | 前一自然日周期内余额结算到银行卡 |\r\n| D0 取现 | 发起后通常 2 小时内到账 |\r\n| DM 取现 | 不包含在途资金的快速取现方式 |\r\n\r\n## 手续费术语\r\n\r\n| 术语 | 说明 |\r\n|------|------|\r\n| 实时收取 | 默认模式，按交易费率实时计算并收取 |\r\n| 手续费内扣 | 从交易金额中扣收手续费 |\r\n| 手续费外扣 | 从指定主体或账户额外扣收手续费 |\n\nFile v1.3.3:references/aggregation-customer-preparation.md\n\n# 聚合支付客户前置准备清单\r\n\r\n> 这份文档用于约束聚合支付 skill 在编码前先确认“参数从哪里来”。这里的前置准备不只是收集字段值，还包括官方产品介绍和开发指引里明确要求的业务开通、应用配置、授权绑定和终端采集动作。如果来源不明确，模型不应自行推断或伪造参数值。\r\n\r\n\r\n## 目录\r\n\r\n- 参数来源分类\r\n- 全局必备配置\r\n- 官方开发指引确认的通用前置动作\r\n- 聚合下单前要准备什么\r\n- 渠道级前置准备矩阵\r\n- 扩展字段相关准备项\r\n- 查询 / 关单 / 退款前要沉淀什么\r\n- 权限 / 开通项检查\r\n- 向客户索取材料的最小清单\r\n- 给模型的硬约束\r\n\r\n## 参数来源分类\r\n\r\n| 来源类型 | 典型字段 | 说明 |\r\n|---------|---------|------|\r\n| 汇付平台固定配置 | `sys_id`、`product_id`、`huifu_id`、RSA 密钥 | 由汇付开放平台 / 控台提供 |\r\n| 客户业务配置 | `notify_url`、`fee_flag`、`acct_id`、`channel_no` | 由客户业务侧或控台确认 |\r\n| 前端 / 用户授权结果 | `sub_openid`、`buyer_id`、`buyer_logon_id` | 运行时值，模型不能猜 |\r\n| 终端 / 设备采集 | `auth_code`、`device_ip`、`devs_id`、`customer_ip` | 反扫、终端报备、银联场景常见 |\r\n| 上游订单沉淀 | `req_date`、`req_seq_id`、`hf_seq_id`、`party_order_id` | 查询 / 关单 / 退款必须复用 |\r\n\r\n## 全局必备配置\r\n\r\n| 配置项 | 用途 | 没有会怎样 |\r\n|-------|------|-----------|\r\n| `sys_id` | 公共请求参数 | 请求无法落地 |\r\n| `product_id` | 公共请求参数 | 汇付会直接报产品号错误 |\r\n| `huifu_id` | 商户主体标识 | 业务请求无法定位商户 |\r\n| RSA 私钥 / 公钥 | 请求签名、响应验签 | 请求或验签失败 |\r\n| `notify_url` / `refund_notify_url` | 异步结果通知 | 只能依赖轮询，不稳定 |\r\n| 对应渠道业务开通状态 | 微信 / 支付宝 / 银联交易前提 | 交易前必须确认账户和对应渠道已开通；进件实施交给 `$huifu-merchant-onboarding` |\n\r\n## 官方开发指引确认的通用前置动作\r\n\r\n- `Lightning_intro.md` 和《快速开始》都明确要求：开发新业务或变更旧业务前，先按产品文档中的“开通功能和准备材料”在合作伙伴控台或商户控台完成业务新增 / 变更。\r\n- 多个渠道开发指引都明确写了：用户前端页面收到支付完成回调，不等于后端可以直接认定交易成功；后端仍需调用查询订单 API 确认最终状态。\r\n- 运行时授权值、扫码值、终端采集值、渠道绑定关系，都是“业务前置准备”的一部分，不是接口层补字段时临时猜出来的。\r\n\r\n## 聚合下单前要准备什么\r\n\r\n### 所有 trade_type 通用\r\n\r\n| 字段 / 配置 | 来源 | 说明 |\r\n|------------|------|------|\r\n| `trade_type` | 业务场景确认 | 决定 `method_expand` 结构 |\r\n| `goods_desc` | 业务订单 | 不是示例值，应该来自真实商品 / 订单语义 |\r\n| `req_seq_id` | 平台流水号生成规则 | 必须当天唯一 |\r\n| `time_expire` | 业务超时策略 | 如不明确可不传，不要乱填过期时间 |\r\n| `acct_split_bunch` | 分账业务配置 | 只有要做分账时才准备 |\r\n| `terminal_device_data` | 终端 / 设备采集链路 | 反扫、终端报备、银联场景常见 |\r\n| `combinedpay_data` / `combinedpay_data_fee_info` / `trans_fee_allowance_info` | 补贴与手续费补贴能力配置 | 按能力名直接作为请求顶层扩展字段传；不要包进 `tx_metadata` |\r\n\r\n### 微信类场景\r\n\r\n| `trade_type` | 必须提前明确的值 | 来源 |\r\n|-------------|------------------|------|\r\n| `T_JSAPI` | `sub_appid`、`sub_openid` | 官方要求先准备微信公众号、开通微信业务、绑定 `sub_appid`、配置支付授权目录；`sub_openid` 必须通过当前公众号 `sub_appid` 的网页授权流程获取 |\n| `T_MINIAPP` | `sub_appid`、`sub_openid` | 官方要求先准备微信小程序、开通微信业务、完成微信配置和 appid 绑定；`sub_openid` 必须通过当前小程序 `sub_appid` 获取，且二者不能错配 |\n| `T_APP` | `sub_appid` | 应用配置 |\r\n| `T_MICROPAY` | `auth_code` | 官方要求通过扫码设备实时采集用户付款码；值本身来自用户当次付款码，不应预置到配置中 |\r\n\r\n### 支付宝类场景\r\n\r\n| `trade_type` | 必须提前明确的值 | 来源 |\r\n|-------------|------------------|------|\r\n| `A_JSAPI` | `buyer_id` 或 `buyer_logon_id` | 官方要求先开通支付宝业务；`buyer_id` 必须通过支付宝 `user_id` 获取流程拿到，不能猜 |\r\n| `A_NATIVE` | 视业务决定是否传门店、商品、营销扩展 | 客户业务配置 |\r\n| `A_MICROPAY` | `auth_code` | 官方要求通过扫码设备实时采集用户支付宝付款码 |\r\n\r\n### 银联类场景\r\n\r\n| `trade_type` | 必须提前明确的值 | 来源 |\r\n|-------------|------------------|------|\r\n| `U_JSAPI` | `user_id`、`customer_ip`，官方说明 `qr_code` 也要明确 | 官方要求先开通银联业务；`user_id` 需先经“网页授权获取 `auth_code` -> 调获取银联用户标识接口”获得，`customer_ip` 必须来自真实客户端 |\r\n| `U_NATIVE` | 是否需要 `front_url`、`payee_info` | 客户业务配置 |\r\n| `U_MICROPAY` | `auth_code`，以及是否需要 `pid_info` | 官方要求通过扫码设备实时采集用户云闪付付款码；`pid_info` 来自服务商配置 |\r\n\r\n## 渠道级前置准备矩阵\r\n\r\n| 场景 | 客户开发前必须完成什么 | 关键运行时值 |\r\n|------|----------------------|-------------|\r\n| 微信公众号支付 | 准备公众号、确认账户和微信业务已开通、绑定 `sub_appid`、配置公众号支付授权目录；授权目录通常以 `/` 结尾，配置后可能延迟生效 | `sub_openid` |\n| 微信小程序支付 | 准备小程序、确认账户和微信业务已开通、完成微信配置、确认 `sub_appid` 绑定关系，清理 appid 配置首尾空格 | `sub_openid` |\n| 支付宝 JS 支付 | 确认账户和支付宝业务已开通 | `buyer_id` / `buyer_logon_id` |\n| 银联 JS 支付 | 确认账户和银联业务已开通、准备银联网页授权回调链路 | `user_id`、`customer_ip` |\n| 各类付款码反扫 | 准备扫码枪或终端采集链路 | `auth_code` |\r\n\r\n## 扩展字段相关准备项\r\n\r\n| 对象 | 需要客户先准备什么 | 说明 |\r\n|------|------------------|------|\r\n| `acct_split_bunch` | 分账接收方 `huifu_id`、账户号、比例 / 金额规则 | 未准备好不要让模型硬拼分账串 |\r\n| `terminal_device_data` | `device_ip`、`devs_id`、定位 / 设备指纹 | 反扫和报备终端场景很关键 |\r\n| `combinedpay_data` | 补贴方 `huifu_id`、`acct_id`、金额 | 请求顶层字段，属于补贴业务配置，不可猜 |\r\n| `combinedpay_data_fee_info` | 手续费承担方 `huifu_id`、`acct_id` | 请求顶层字段，需要真实承担方信息 |\r\n| `trans_fee_allowance_info` | 补贴手续费金额和活动来源 | 请求顶层字段，需要明确的活动或配置支持 |\r\n\r\n## 查询 / 关单 / 退款前要沉淀什么\r\n\r\n| 接口 | 开发前必须保证已保存 | 说明 |\r\n|------|------------------|------|\r\n| 交易查询 | `req_date`、`req_seq_id`、`hf_seq_id`、`party_order_id` 中至少一组 | 不能等到查询时再猜 |\r\n| 交易关单 | 原交易 `org_req_date` + `org_req_seq_id` 或 `org_hf_seq_id` | 依赖原交易标识 |\r\n| 关单查询 | 关单请求自身标识 + 原交易标识 | 两层流水都要可追溯 |\r\n| 退款 | `org_hf_seq_id`、`org_party_order_id`、`org_req_seq_id` 三选一 | 原交易定位键来自上游沉淀 |\r\n| 退款查询 | 原退款请求标识、原交易标识 | 便于轮询确认 |\r\n| 对账单查询 | 对账功能开通状态、`file_date` 语义 | 功能未开通时接口也不可用 |\r\n\r\n## 权限 / 开通项检查\r\n\r\n| 能力 | 影响点 |\r\n|------|--------|\r\n| 分账权限 | `acct_split_bunch` |\r\n| 延迟入账权限 | `delay_acct_flag` |\r\n| 退款权限 | 退款接口 |\r\n| 终端报备 | `terminal_device_data.devs_id` |\r\n| 手续费 / 贴息 / 补贴配置 | `fee_flag`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info` |\r\n| 对账单功能 | `file_date`、`bill_type` |\n| 微信小程序 `sub_appid` 绑定 | `T_MINIAPP` 下单成功率 | 官方 QA 明确要求 `sub_appid` 与商户建立绑定关系 |\n| 微信 `sub_appid` / `sub_openid` 一致性 | `T_MINIAPP` / `T_JSAPI` | 官方 QA 明确要求 `sub_openid` 必须从对应 `sub_appid` 获取 |\n| 接口权限 | 当前接口是否能调用 | `接口权限认证失败` 或 `20003` 时先核对 `sys_id` 是否开通当前接口权限 |\n| 数据权限 | `product_id`、`sys_id`、`huifu_id`、`upper_huifu_id` | `数据权限认证失败` 时核对产品号、服务商/子商户层级和请求头来源 |\n| 渠道路由 | `pay_channel`、`pay_scene`、`channel_no`、线上/线下 `fee_type` | 多渠道或线上/线下混用时要明确场景；不指定通道时不要传空字符串 `channel_no` |\n\r\n## 向客户索取材料的最小清单\r\n\r\n### 必需\r\n\r\n- `sys_id`、`product_id`、`huifu_id`\r\n- RSA 私钥、公钥\r\n- 支付 / 退款异步通知地址\r\n- 实际要接的 `trade_type` 列表\r\n\r\n### 按场景补充\r\n\r\n- 微信：公众号 / 小程序应用信息、`sub_appid`、`sub_openid` 获取链路\r\n- 支付宝：`buyer_id` / `buyer_logon_id` 的真实获取链路\r\n- 银联 JS：网页授权回调地址、`auth_code -> user_id` 获取链路、`customer_ip`\r\n- 反扫：`auth_code` 获取方式、终端采集能力\r\n- 银联扩展：`front_url`、`payee_info`、`pid_info`\r\n- 分账 / 设备 / 补贴：`acct_split_bunch`、`devs_id`、补贴账户配置\r\n\r\n## 给模型的硬约束\r\n\r\n- 运行时授权值、扫码值、报备值、控台配置值，都不能靠模型猜。\r\n- 前端页面回调、支付完成页、客户端 success 回调，都不能直接当作交易成功终态；按官方开发指引，后端必须再查单确认。\r\n- 如果客户没有提供场景必需值，应该先暴露缺口，而不是直接给出“看起来完整”的代码。\r\n- 查询、关单、退款代码必须复用上游订单沉淀的标识，不要在下游重新假设。\n\nFile v1.3.3:references/aggregation-error-codes.md\n\n# 聚合支付错误码\r\n\r\n> 本页返回码主要用于排查和联调定位，不建议把 `resp_code` 直接写成订单终态逻辑；订单终态仍以 `trans_stat`、异步通知和主动查询结果为准。\n\n## 官方来源与合并规则\n\n- 公共全集：[返回码](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_ywm.md)，包含网关返回码以及扫码类、线上交易、商户进件等业务返回码。\n- 公共字典入口：[基础参数汇总](https://paas.huifu.com/partners/api/doc/csfl/api_csfl.md)。\n- 业务术语：[名词解释](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_mcjs.md)。\n- 本页下方只保留高频码和接口专项码，不是全集。排查时必须把“当前接口页业务返回码”与公共返回码全集合并查看；同一码可能按接口或 `resp_desc` 表示不同原因，不能只按码值做唯一映射。\n- 网关返回码用于判断请求是否到达业务处理层；业务返回码用于接口处理诊断；交易终态仍由交易状态、异步通知和主动查询共同确认。\n\r\n## 通用错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 00000000 | 本次接口处理完成，实际交易结果仍以 `trans_stat` / 查询结果为准 | 继续结合交易状态字段确认终态 |\r\n| 00000100 | 交易正在处理中 | 等待异步通知或轮询查询 |\r\n| 10000000 | 无效参数 | 检查必填字段、格式、长度 |\r\n| 98888888 | 未知系统错误 | 联系汇付技术支持 |\r\n| 99999999 | 系统异常，请稍后重试 | 稍后重试或联系技术支持 |\r\n\r\n## 参数校验类 (10000000)\r\n\r\n| 返回描述 | 处理建议 |\r\n|---------|---------|\r\n| 请求内容体不能为空 | 检查请求 body |\r\n| %s不能为空 | 检查对应必填字段 |\r\n| %s长度固定%d位 | 检查字段长度 |\r\n| %s最大长度为%d位 | 缩短字段值 |\r\n| %s的传入枚举[%s]不存在 | 检查枚举值是否合法 |\r\n| %s不符合%s格式 | 检查日期/金额等格式 |\r\n\r\n## 下单类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 20000000 | 重复交易 | 使用新的 req_seq_id |\r\n| 20000001 | 操作过于频繁 | 稍后重试 |\r\n| 22000000 | 产品配置信息异常 | 检查 product_id 配置 |\r\n| 22000002 | 商户配置信息异常 | 检查 huifu_id |\r\n| 90000000 | 交易受限 / 单笔金额超限 / 交易存在风险 | 查看 resp_desc 详情 |\r\n\r\n## 查询类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 20000004 | 交易不存在 | 检查流水号是否正确 |\r\n| 21000000 | 参数逻辑校验不合法（流水号、全局流水号不能同时为空） | 至少传入一个查询条件 |\r\n\r\n## 关单类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 20000001 | 不允许关闭一分钟以内的订单；官网同码也用于并发冲突 | 结合 `resp_desc` 区分，未满一分钟时等待边界后再查询/关单 |\n| 10000016 | 原订单已为终态,请发起查询交易获取 | 订单已完成，无需关单 |\r\n| 10000018 | 关单失败 | 查看 resp_desc 详情 |\r\n| 23000000 | 原交易订单已失败不允许关单 / 关单状态为终态 | 订单已完成或已关单 |\r\n| 23000004 | 不支持的交易（银联二维码不支持关单） | 银联不支持关单 |\r\n\r\n## 退款类错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 10000001 | 原交易没有处理完成 | 等待原交易完成 |\r\n| 10000002 | 退款金额大于可退金额 | 检查退款金额 |\r\n| 10000009 | 该交易不支持部分退款 | 只能全额退款 |\r\n| 21000000 | 原交易请求流水号、商户单号、全局流水号不能同时为空 | 至少传入一个原交易标识 |\r\n| 22000004 | 暂未开通退款权限/分账退款权限 | 联系汇付开通权限 |\r\n| 23000002 | 数据权限不足 / 退款手续费承担方不一致 | 检查手续费配置 |\r\n| 23000003 | 金额校验异常（退款额>可退额 / 余额不足） | 检查退款金额和账户余额 |\r\n| 23000004 | 不支持的交易（预授权撤销/优惠交易部分退款） | 使用其他方式处理 |\r\n| 30000000 | 调用收银台退款接口失败 | 稍后重试 |\r\n| 90000000 | 交易受限 / 可用余额不足 / 交易存在风险 | 查看 resp_desc 详情 |\r\n\r\n## 对账单查询错误码\r\n\r\n| 返回码 | 返回描述 | 处理建议 |\r\n|-------|---------|---------|\r\n| 00000000 | 查询成功 | 正常返回 |\r\n| — | 当前huifuId请求过于频繁 | 每天不要超过 3 次查询 |\r\n\r\n## 使用边界\r\n\r\n- `resp_code`、`resp_desc` 主要用于排查，不直接驱动订单成功/失败终态。\r\n- `00000000` 不等于“交易最终成功”，仍要结合 `trans_stat`、异步通知和查单结果判断。\r\n- `00000100` 表示当前接口仍在处理中，应该继续等待异步通知或轮询查询。\r\n- 其他返回码优先结合 `resp_desc`、请求参数、渠道场景和原交易标识排查。\n- 本页未列出的返回码不得直接判为“未知系统错误”；先查公共返回码全集，再结合接口专属码和 `resp_desc` 分类。\n\nFile v1.3.3:references/aggregation-faq.md\n\n# 各渠道常见问题汇总\r\n\r\n\r\n## 目录\r\n\r\n- 微信支付通用问题\r\n- 微信付款码特有问题\r\n- 支付宝支付通用问题\r\n- 银联支付问题\r\n- 对账单问题\r\n\r\n## 微信支付通用问题\r\n\r\n### 业务常见问题\r\n\r\n**Q：支付时显示的商家简称可以修改吗？**\r\nA：可以。登录合作伙伴控台修改，或调用【微信支付宝入驻信息修改】接口。\r\n\r\n**Q：消费者账单侧显示的商品字段如何修改？**\r\nA：对应下单时传入的 `goods_desc`（商品描述）字段，可笔笔指定。\r\n\r\n**Q：支付时如何限制信用卡支付？**\r\nA：发起交易时传入禁用支付方式字段。它属于请求顶层字段，不属于 `method_expand`。\r\n\r\n**Q：支付时是否可以指定入账账户？**\r\nA：支持，传入需入账的账户号，仅支持基本户、现金户。\r\n\r\n**Q：已开通多个微信商户号，支付时如何指定？**\r\nA：通过接口或控台修改微信交易通道配置，预配置默认通道。下单时可通过\"渠道号\"和\"场景类型\"单独指定。\r\n\r\n**Q：支付失败，风控拦截交易（非微信拦截）如何处理？**\r\nA：提供报错描述联系客服，若为可申诉场景按流程提交材料。\r\n\r\n### 微信技术问题\r\n\r\n**Q：报错 \"当前商户需补齐相关资料后，才可进行相应的支付交易\"**\r\n原因：商户未完成微信实名认证。\r\n处理：登录控台完成实名认证，或调用【微信实名认证】接口。\r\n\r\n**Q：报错 \"sub_mch_id与sub_appid不匹配\"**\r\n原因：商户 appid 配置有误。\r\n处理：确认公众号/小程序的 sub_appid 已与商户绑定，可调用【微信商户配置】接口或控台配置。\r\n\r\n**Q：报错 \"sub_appid与sub_openid不匹配\"**\r\n原因：sub_appid 和 sub_openid 获取对应关系有误。\r\n处理：sub_openid 必须从对应的 sub_appid 下获取，不能混用不同公众号/小程序。\r\n\r\n**Q：报错 \"特约子商户该产品权限已被冻结\"**\r\n原因：微信风控关闭商户号支付权限。\r\n处理：处理商户风险问题，申诉通过后恢复支付权限。\r\n\r\n## 微信付款码特有问题\r\n\r\n**Q：付款码支付是否需要输入密码？**\r\nA：一般情况下免密扣款。以下情况需验密：\r\n- 支付金额 > 1000元\r\n- 当天已有10笔免密交易\r\n- 用户查看了付款码数字\r\n- 微信风控判断异常\r\n\r\n## 支付宝支付通用问题\r\n\r\n### 业务常见问题\r\n\r\n**Q：支付时显示的商家简称可以修改吗？**\r\nA：可以。登录控台修改，或调用【微信支付宝入驻信息修改】接口。\r\n\r\n**Q：支付时如何限制信用卡支付？**\r\nA：发起交易时传入禁用支付方式字段。\r\n\r\n### 支付宝技术问题\r\n\r\n**Q：报错 \"当前商户未认证，请通知商户在支付宝搜索'支付宝商家认证助手'小程序，完成认证后开通交易\"**\r\n原因：商户未完成支付宝实名认证。\r\n处理：登录控台完成认证，或调用【支付宝实名申请提交】接口。\r\n\r\n### 支付宝付款码特有问题\r\n\r\n**Q：付款码支付什么时候需要输入密码？**\r\nA：以下场景会唤起支付宝收银台：\r\n- 消费者付款码安全校验未通过\r\n- 支付额度超过代扣额度\r\n- 代扣失败（所有渠道余额不足）\r\n\r\n## 银联支付问题\r\n\r\n**Q：H5页面无法打开？**\r\nA：确认页面地址是否已在银联通过备案，未备案页面无法正常打开。\r\n\r\n**Q：支付时是否可以指定入账账户？**\r\nA：支持，传入需入账的账户号，仅支持基本户、现金户。\r\n\r\n**Q：支付失败，风控拦截交易如何处理？**\r\nA：提供报错描述联系客服，若为可申诉场景按流程提交材料。\r\n\r\n### 银联付款码特有问题\r\n\r\n**Q：付款码支付是否需要输入密码？**\r\nA：一般情况下免密扣款，仅触发验证密码规则后需验密。\r\n\r\n## 对账单问题\r\n\r\n**Q：对账单查询接口返回的文件格式？**\r\nA：常规账单一个链接通常对应一个压缩文件，压缩包内多为 csv。`SETTLE_FUND_BILL` 模板为 `.xlsx`，不要把所有账单都按 csv 解析。单个文件超过 400,000 条时会拆分为多个 csv。\r\n\r\n**Q：对账单什么时候适合下载？**\r\nA：最新产品介绍口径建议按跑批节奏取数：交易/分账文件 03:00 跑批后建议 12:00 再取，出金对账单 10:30 跑批后一小时，结算对账单 17:00 跑批后一小时。\r\n\r\n**Q：对账单能查多久以前的数据？**\r\nA：接口当前支持 1 年内账单下载；控台下载暂未见时间限制说明。\r\n\r\n**Q：交易账单实收金额与结算金额不一致？**\r\nA：计算公式：交易金额 - 交易手续费 - 退款金额 + 退款手续费。还需排除结算周期 > D+1 的交易和资金冻结。\r\n\r\n**Q：报错 \"当前huifuId请求过于频繁\"？**\r\nA：生成对账单有次数限制，每天不超过3次。\r\n\r\n**Q：对账单查询 file_details 为空？**\r\nA：查看 task_details，如果 task_stat 为成功且文件为空，代表前一日无记录。\n\nFile v1.3.3:references/aggregation-java-adapter.md\n\n# Java 适配层\r\n\r\n这份文件只讲 Java 接入。  \r\n协议规则不在这里重复写。\r\n\r\n## 适配范围\r\n\r\n| 项目 | 内容 |\r\n| --- | --- |\r\n| 当前适配 SDK | `dg-lightning-sdk` `1.0.5` |\r\n| 最低运行时 | JDK 1.8+ |\r\n| 初始化入口 | `MerConfig` + `BasePay.initWithMerConfig()` |\n| 主要调用方式 | `Factory.Payment.Common()` |\n\n`dg-lightning-sdk 1.0.5` 的 `BasePay.debug` 默认是 `true`，底层会输出私钥、签名和请求数据。所有初始化必须在任何 `initWithMerConfig(s)` 或业务请求前执行一次 `BasePay.debug = false;`，不得在并发请求中临时切换。\n\r\n## 先看哪些文件\r\n\r\n- `references/aggregation-java-sdk-quickstart.md`\r\n- `references/aggregation-java-tech-spec.md`\r\n- `references/aggregation-async-webhook.md`\r\n\r\n## Java 特有说明\r\n\r\n1. Lightning SDK 的产品号方法名是 `setProductId()`，这里拼写正常。\r\n2. Spring Boot 2.x 和 3.x 的 import 不一样。\r\n   2.x 常见是 `javax.annotation.PostConstruct`\r\n   3.x 常见是 `jakarta.annotation.PostConstruct`\r\n3. 当前仓库的异步通知示例使用了 `fastjson`。\r\n   这是 Java 示例选型，不是协议层要求。\r\n4. `method_expand`、`acct_split_bunch`、`terminal_device_data`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info` 这类字段，仍然建议先在业务层建对象，再在 SDK 边界统一序列化。\r\n5. `T_JSAPI`、`T_MINIAPP`、`T_APP`、`T_MICROPAY`、`A_JSAPI`、`A_NATIVE`、`A_MICROPAY`、`U_JSAPI`、`U_NATIVE`、`U_MICROPAY` 这些值不是 `method_expand` 的 key；`method_expand` 的 JSON 内容直接是当前场景对象本身。\r\n6. `tx_metadata` 本身不作为请求字段上送；交易能力扩展按能力名直接传 `acct_split_bunch`、`terminal_device_data`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info`。\r\n7. `MerConfig.setSkillSource(...)` 直接传 `<skill_source>` 即可；聚合支付要求的 `sys_id` 仍通过独立请求头 `sys_id` / `jpt-sys_id` 传递，`jpt-x-skill-source` 只透传来源值。\r\n8. 当前 Java SDK 基线如果请求参数里的 `huifu_id` 存在且非空，还会自动补 `jpt-x-skill-huifu_id`；该值必须与本次请求的 `huifu_id` 一致，不要手工写成固定常量。\r\n\r\n## 不属于这里的内容\r\n\r\n- 签名规则：看 `references/shared-signing-v2.md`\r\n- 异步通知规则：看 `references/shared-async-notify.md`\r\n- 其他语言入口：看 `references/shared-server-sdk-matrix.md`\n\nFile v1.3.3:references/aggregation-java-sdk-quickstart.md\n\n## 目录\n\n- [SDK 信息](#sdk-信息)\n- [步骤 1：添加 Maven 依赖](#步骤-1添加-maven-依赖)\n- [步骤 2：SDK 初始化](#步骤-2sdk-初始化spring-boot-配置类)\n- [步骤 3：验证核心类导入](#步骤-3验证核心类导入)\n- [Factory 调用模式](#factory-调用模式)\n- [与 dg-java-sdk 的关键差异](#与-dg-java-sdk-的关键差异)\n\n# SDK 安装与初始化\n\n## SDK 信息\n\n| 属性 | 值 |\n|-----|-----|\n| SDK 名称 | dg-lightning-sdk |\n| 当前版本 | 1.0.5 |\n| GroupId | com.huifu.dg.lightning.sdk |\n| ArtifactId | dg-lightning-sdk |\n\n> **说明**：如果项目中同时需要托管支付（dg-java-sdk）和聚合支付（dg-lightning-sdk），两个 SDK 可以共存，各自独立初始化。\n\n## 步骤 1：添加 Maven 依赖\n\n在 `pom.xml` 中添加：\n\n```xml\n<dependency>\n    <groupId>com.huifu.dg.lightning.sdk</groupId>\n    <artifactId>dg-lightning-sdk</artifactId>\n    <version>1.0.5</version>\n</dependency>\n```\n\n如果同时需要托管支付，也添加：\n\n```xml\n<dependency>\n    <groupId>com.huifu.bspay.sdk</groupId>\n    <artifactId>dg-java-sdk</artifactId>\n    <version>3.0.40</version>\n</dependency>\n```\n\n执行安装：\n\n```bash\nmvn clean install\n```\n\n## 步骤 2：SDK 初始化（Spring Boot 配置类）\n\n> **[Spring Boot 3.x 用户必读]** 如果你使用 Spring Boot 3.x（JDK 17/21），`javax.*` 命名空间已迁移至 `jakarta.*`，初始化代码中的 import 需替换。\n\n| Spring Boot 版本 | PostConstruct |\n|-----------------|---------------|\n| 2.x | `javax.annotation.PostConstruct` |\n| 3.x (JDK 17/21) | `jakarta.annotation.PostConstruct` |\n\n> **[产品号方法名]** Lightning SDK 和当前 `dg-java-sdk 3.0.40` 的 `MerConfig` 产品号方法名都使用 `setProductId(...)`。\n\n> **🔴 传输安全硬停**：下方仅展示初始化形态。锁定的 Lightning Java `1.0.5` 信任所有证书并接受任意主机名；在安全制品通过证书链、主机名以及错证书/过期证书/错域名拒绝测试前，不得用于联调或生产。\n\n```java\npackage com.yourcompany.huifu.config;\n\nimport com.huifu.dg.lightning.biz.config.MerConfig;\nimport com.huifu.dg.lightning.utils.BasePay;\nimport lombok.extern.slf4j.Slf4j;\nimport org.springframework.beans.factory.annotation.Value;\nimport org.springframework.context.annotation.Configuration;\n\nimport javax.annotation.PostConstruct;\n\n@Configuration\n@Slf4j\npublic class HuifuLightningConfig {\n\n    @Value(\"${huifu.product-id}\")\n    private String productId;\n\n    @Value(\"${huifu.sys-id}\")\n    private String sysId;\n\n    @Value(\"${huifu.rsa-private-key}\")\n    private String rsaPrivateKey;\n\n    @Value(\"${huifu.rsa-public-key}\")\n    private String rsaPublicKey;\n\n    @Value(\"${huifu.skill-source:hfps/1.3.3}\")\n    private String skillSource;\n\n    @Value(\"${huifu.mode:prod}\")\n    private String mode;\n\n    @PostConstruct\n    public void initSdk() throws Exception {\n        // SDK 1.0.5 默认 debug=true，会输出私钥、签名和请求数据。\n        // 必须在任何初始化或请求之前全局关闭，且不得按请求临时切换。\n        BasePay.debug = false;\n\n        // 设置环境模式\n        if (\"test\".equals(mode)) {\n            BasePay.prodMode = BasePay.MODE_TEST;\n            log.info(\"汇付聚合支付SDK: 联调环境\");\n        } else {\n            BasePay.prodMode = BasePay.MODE_PROD;\n            log.info(\"汇付聚合支付SDK: 生产环境\");\n        }\n\n        // 初始化商户配置\n        MerConfig merConfig = new MerConfig();\n        merConfig.setProductId(productId);   // 注意：Lightning SDK 拼写正常\n        merConfig.setSysId(sysId);\n        merConfig.setRsaPrivateKey(rsaPrivateKey);\n        merConfig.setRsaPublicKey(rsaPublicKey);\n        merConfig.setSkillSource(skillSource);\n\n        BasePay.initWithMerConfig(merConfig);  // 注意：throws Exception\n        log.info(\"汇付聚合支付SDK初始化完成\");\n    }\n}\n```\n\n### 多商户配置（可选）\n\n如果需要支持多个商户，使用 `initWithMerConfigs`：\n\n```java\nMap<String, MerConfig> configs = new HashMap<>();\n\n// 多商户初始化同样必须先全局关闭调试输出。\nBasePay.debug = false;\n\nMerConfig config1 = new MerConfig();\nconfig1.setProductId(\"MYPAY\");\nconfig1.setSysId(\"6666000123120001\");\nconfig1.setRsaPrivateKey(\"...\");\nconfig1.setRsaPublicKey(\"...\");\nconfig1.setSkillSource(\"hfps/1.3.3\");\nconfigs.put(\"merchant1\", config1);\n\nMerConfig config2 = new MerConfig();\nconfig2.setSysId(\"6666000123120002\");\nconfig2.setSkillSource(\"hfps/1.3.3\");\n// ... 配置第二个商户\nconfigs.put(\"merchant2\", config2);\n\nBasePay.initWithMerConfigs(configs);\n```\n\n### 自定义超时时间（可选）\n\n```java\nMerConfig merConfig = new MerConfig();\n// ... 基本配置\nmerConfig.setCustomConnectTimeout(\"30000\");              // 连接超时 30s（默认 20s），注意是 String 类型\nmerConfig.setCustomSocketTimeout(\"30000\");               // 读取超时 30s（默认 20s）\nmerConfig.setCustomConnectionRequestTimeout(\"40000\");    // 请求超时 40s（默认 30s）\nmerConfig.setSkillSource(\"hfps/1.3.3\");\n```\n\n## 步骤 3：验证核心类导入\n\n确认以下类可正常导入：\n\n| 类 | 包路径 | 用途 |\n|---|-------|------|\n| BasePay | `com.huifu.dg.lightning.utils.BasePay` | SDK 入口，初始化配置、环境模式 |\n| MerConfig | `com.huifu.dg.lightning.biz.config.MerConfig` | 商户配置对象 |\n| Factory | `com.huifu.dg.lightning.factory.Factory` | 工厂类，获取业务客户端 |\n| CommonPayClient | `com.huifu.dg.lightning.biz.client.CommonPayClient` | 聚合支付客户端 |\n| BasePayException | `com.huifu.dg.lightning.biz.exception.BasePayException` | SDK 异常类 |\n| DateTools | `com.huifu.dg.lightning.utils.DateTools` | 日期工具（`getCurrentDateYYYYMMDD()`） |\n| SequenceTools | `com.huifu.dg.lightning.utils.SequenceTools` | 流水号工具（`getReqSeqId32()`） |\n\n`MerConfig.setSkillSource(...)` 按 `<skill_source>` 原样透传；聚合支付要求的 `sys_id` 仍通过独立请求头 `sys_id` / `jpt-sys_id` 传递，`jpt-x-skill-source` 只承载来源值本身。\n\n## Factory 调用模式\n\nLightning SDK 使用 Factory 模式创建业务客户端，与 dg-java-sdk 的 `BasePayClient.request()` 不同：\n\n```java\nimport com.huifu.dg.lightning.factory.Factory;\nimport com.huifu.dg.lightning.biz.client.CommonPayClient;\nimport com.huifu.dg.lightning.models.payment.*;\n\n// 1. 获取聚合支付客户端\nCommonPayClient client = Factory.Payment.Common();\n\n// 2. 下单\nTradePaymentCreateRequest createReq = new TradePaymentCreateRequest();\n// ... 设置参数\nMap<String, Object> createResp = client.create(createReq);\n\n// 3. 查询\nTradePaymentScanpayQueryRequest queryReq = new TradePaymentScanpayQueryRequest();\n// ... 设置参数\nMap<String, Object> queryResp = client.query(queryReq);\n\n// 4. 关单\nTradePaymentScanpayCloseRequest closeReq = new TradePaymentScanpayCloseRequest();\nMap<String, Object> closeResp = client.close(closeReq);\n\n// 5. 关单查询\nTradePaymentScanpayClosequeryRequest closeQueryReq = new TradePaymentScanpayClosequeryRequest();\nMap<String, Object> closeQueryResp = client.closeQuery(closeQueryReq);\n\n// 6. 退款\nTradePaymentScanpayRefundRequest refundReq = new TradePaymentScanpayRefundRequest();\nMap<String, Object> refundResp = client.refund(refundReq);\n\n// 7. 退款查询\nTradePaymentScanpayRefundQueryRequest refundQueryReq = new TradePaymentScanpayRefundQueryRequest();\nMap<String, Object> refundQueryResp = client.refundQuery(refundQueryReq);\n```\n\n### 添加可选业务参数\n\nCommonPayClient 支持通过 `optional()` 方法添加额外参数：\n\n```java\nCommonPayClient client = Factory.Payment.Common();\nclient.optional(\"notify_url\", \"https://your-domain.com/notify\");\nclient.optional(\"remark\", \"备注信息\");\nMap<String, Object> response = client.create(request);\n```\n\n### 延迟交易客户端\n\n```java\nimport com.huifu.dg.lightning.biz.client.DelayTransClient;\n\nDelayTransClient delayClient = Factory.Solution.DelayTrans();\n// delayClient.confirm()      - 延迟交易确认\n// delayClient.confirmQuery() - 确认查询\n// delayClient.refund()       - 延迟交易退款\n// delayClient.refundQuery()  - 退款查询\n// delayClient.splitQuery()   - 分账查询\n```\n\n## SDK Request 类速查表\n\n| 场景 | Request 类 | 包路径 |\n|------|-----------|-------|\n| 聚合支付下单 | `TradePaymentCreateRequest` | `com.huifu.dg.lightning.models.payment` |\n| 聚合交易查询 | `TradePaymentScanpayQueryRequest` | 同上 |\n| 聚合交易关单 | `TradePaymentScanpayCloseRequest` | 同上 |\n| 聚合交易关单查询 | `TradePaymentScanpayClosequeryRequest` | 同上 |\n| 交易退款 | `TradePaymentScanpayRefundRequest` | 同上 |\n| 交易退款查询 | `TradePaymentScanpayRefundQueryRequest` | 同上 |\n\n## 与 dg-java-sdk 的关键差异\n\n| 对比项 | dg-lightning-sdk | dg-java-sdk |\n|-------|-----------------|------------|\n| 初始化 import | `com.huifu.dg.lightning.*` | `com.huifu.bspay.sdk.opps.*` |\n| MerConfig 包路径 | `com.huifu.dg.lightning.biz.config.MerConfig` | `com.huifu.bspay.sdk.opps.core.config.MerConfig` |\n| BasePay 包路径 | `com.huifu.dg.lightning.utils.BasePay` | `com.huifu.bspay.sdk.opps.core.BasePay` |\n| 设置产品号 | `setProductId()` | `setProductId()` |\n| 调用方式 | `Factory.Payment.Common().create(req)` | `BasePayClient.request(req, false)` |\n| 扩展参数 | `client.optional(key, value)` | `request.setExtendInfo(map)` |\n| HTTP 客户端 | Apache HttpClient 4.5.2 | OkHttp |\n\nFile v1.3.3:references/aggregation-java-tech-spec.md\n\n# 技术规范\r\n\r\n\r\n## 目录\r\n\r\n- 请求协议与报文模型\r\n- 签名规则\r\n- 异步通知\r\n- HTTP 连接池配置\r\n- 重试策略\r\n- API 版本\r\n\r\n## 请求协议与报文模型\r\n\r\n| 项目 | 说明 |\r\n|------|------|\r\n| 通信协议 | HTTPS |\r\n| 请求方式 | POST |\r\n| 数据格式 | JSON |\r\n| 字符编码 | UTF-8 |\r\n| 建议头 | `Content-Type: application/json;charset=UTF-8` |\r\n\r\n请求模型：\r\n\r\n```json\r\n{\r\n  \"sys_id\": \"调用方 huifu_id\",\r\n  \"product_id\": \"产品号\",\r\n  \"sign\": \"请求签名\",\r\n  \"data\": {\r\n    \"业务字段\": \"值\"\r\n  }\r\n}\r\n```\r\n\r\n响应模型：\r\n\r\n```json\r\n{\r\n  \"sign\": \"返回签名\",\r\n  \"data\": {\r\n    \"resp_code\": \"00000000\",\r\n    \"resp_desc\": \"处理成功\"\r\n  }\r\n}\r\n```\r\n\r\n## 签名规则\r\n\r\n### 请求签名\r\n\r\n1. 将请求 `data` 对象序列化为 JSON\r\n2. 对 JSON 中所有对象的 key 按 ASCII 值排序（数组不排序）\r\n3. 使用商户 RSA 私钥对排序后的 JSON 字符串进行 SHA256WithRSA 签名\r\n4. 将签名结果 Base64 编码后填入 `sign` 字段\r\n\r\n> SDK 自动完成以上步骤，开发者无需手动处理。\r\n\r\n### 响应验签\r\n\r\nSDK 自动使用汇付 RSA 公钥验证响应签名，验签失败时抛出 `BasePayException`。\r\n\r\n### RSA 密钥格式\r\n\r\n- 私钥格式：PKCS#8（Base64 编码）\r\n- 公钥格式：X.509（Base64 编码）\r\n\r\n## 异步通知\r\n\r\n### 通知机制\r\n\r\n聚合支付支持两种异步通知方式：\r\n\r\n1. **notify_url 回调**：下单时传入 `notify_url`，交易完成后汇付 POST 通知到该地址\r\n2. **Webhook 事件**：通过汇付控台配置 Webhook 接收端，支持以下事件：\r\n   - `trans.close` — 关单事件\r\n\r\n### notify_url 接收规范\r\n\r\n- **请求方式**：POST\r\n- **报文形态**：交易类回调通常提交 `sign` 和 `resp_data` 字段，业务字段位于 `resp_data`\r\n- **响应要求**：HTTP 200，body 返回 `RECV_ORD_ID_` + req_seq_id（5 秒内）\r\n- **重试策略**：超时未响应最多重试 3 次\r\n- **幂等键**：以 `hf_seq_id` 为最简幂等键，防止重复处理（完整口径见 `references/shared-async-notify.md`，建议复合键）\r\n\r\n以下示例为流程片段。`HttpServletRequest` 在 Spring Boot 2.x 使用 `javax.servlet.*`，在 3.x 使用 `jakarta.servlet.*`；`huifuPublicKey` 的注入方式可直接参考 `references/aggregation-async-webhook.md` 中的完整类示例。\r\n\r\n```java\r\n@PostMapping(\"/notify\")\r\npublic String handleNotify(HttpServletRequest request) {\r\n    String respData = request.getParameter(\"resp_data\");\r\n    String sign = request.getParameter(\"sign\");\r\n    if (!RsaUtils.verify(respData, huifuPublicKey, sign)) {\r\n        throw new IllegalArgumentException(\"汇付回调验签失败\");\r\n    }\r\n\r\n    JSONObject notification = JSON.parseObject(respData);\r\n    String reqSeqId = notification.getString(\"req_seq_id\");\r\n    String hfSeqId = notification.getString(\"hf_seq_id\");\r\n    String transStat = notification.getString(\"trans_stat\");\r\n\r\n    if (isProcessed(hfSeqId)) {\r\n        return \"RECV_ORD_ID_\" + reqSeqId;\r\n    }\r\n\r\n    // 先查单确认，再按 trans_stat 驱动订单状态\r\n    if (\"S\".equals(transStat)) {\r\n        // 交易成功\r\n    } else if (\"F\".equals(transStat)) {\r\n        // 交易失败\r\n    }\r\n\r\n    return \"RECV_ORD_ID_\" + reqSeqId;\r\n}\r\n```\r\n\r\n### Webhook 使用\r\n\r\nWebhook 是汇付提供的事件通知机制，与 notify_url 独立，可在汇付控台灵活配置接收端。\r\n\r\n配置方式参见汇付文档：[Webhook 使用说明](https://paas.huifu.com/open/doc/devtools/#/webhook/webhook_jieshao)\r\n\r\nWebhook 与 API 的签名密钥不是一套：\r\n\r\n- API 请求和 `notify_url` 回调使用 RSA 密钥体系。\r\n- Webhook 使用控台配置的终端密钥，对原始事件体计算 MD5。\r\n- Webhook 不使用汇付 RSA 公钥验签，也不要靠 `sign` 长度自动猜算法。\r\n- 详细说明见 `references/aggregation-async-webhook.md`。\r\n\r\n## HTTP 连接池配置\r\n\r\nSDK 内置 Apache HttpClient 连接池，默认配置：\r\n\r\n| 参数 | 默认值 |\r\n|------|-------|\r\n| 最大连接数 | 500 |\r\n| 每路由最大连接数 | 40 |\r\n| 每主机最大连接数 | 100 |\r\n| Socket 超时 | 20 秒 |\r\n| 连接超时 | 20 秒 |\r\n| 连接请求超时 | 30 秒 |\r\n\r\n可通过 MerConfig 自定义超时：\r\n\r\n```java\r\nmerConfig.setCustomConnectTimeout(\"30000\");\nmerConfig.setCustomSocketTimeout(\"30000\");\nmerConfig.setCustomConnectionRequestTimeout(\"40000\");\n```\r\n\r\n## 重试策略\r\n\r\nSDK 内置 HTTP 处理器最多形成 3 次总尝试，即至多 2 次重试；带实体的支付 POST 请求不自动重试。`NoHttpResponseException` 等条件只适用于处理器允许的非实体请求，不能解释成支付业务自动重试。SSL 错误、Socket 超时和 SSL 握手失败不重试；任何网络不确定结果都先按原请求标识查单，不得另造流水重提。\n\r\n## API 版本\r\n\r\n聚合支付接口涉及不同的 API 版本：\r\n\r\n| 接口 | API 路径 | 版本 |\r\n|------|---------|------|\r\n| 聚合支付下单 | /v4/trade/payment/create | v4 |\r\n| 聚合交易查询 | /v4/trade/payment/scanpay/query | v4 |\r\n| 交易退款 | /v4/trade/payment/scanpay/refund | v4 |\r\n| 交易退款查询 | /v4/trade/payment/scanpay/refundquery | v4 |\r\n| 聚合交易关单 | /v2/trade/payment/scanpay/close | v2 |\r\n| 聚合交易关单查询 | /v2/trade/payment/scanpay/closequery | v2 |\r\n| 对账单查询 | /v2/trade/check/filequery | v2 |\r\n\r\n> SDK 自动处理 API 路径路由，开发者无需关心版本差异。\n\nFile v1.3.3:references/aggregation-order-errors.md\n\n# 聚合下单返回码与勘误\r\n\r\n\r\n## 目录\r\n\r\n- 聚合正扫 / JS / APP 业务返回码\r\n- 聚合反扫业务返回码\r\n- 文档勘误与实现备注\r\n\r\n## 聚合正扫 / JS / APP 业务返回码\r\n\r\n| 返回码 | 返回描述 |\r\n|--------|----------|\r\n| `00000000` | 交易受理成功；交易状态以 `trans_stat` 为准 |\r\n| `00000100` | 下单成功 |\r\n| `10000000` | 产品号不能为空 |\r\n| `10000000` | 交易类型不能为空 |\r\n| `10000000` | `%s` 不能为空 |\r\n| `10000000` | `%s` 长度固定 `%d` 位 |\r\n| `10000000` | `%s` 最大长度为 `%d` 位 |\r\n| `10000000` | `%s` 的传入枚举 `[%s]` 不存在 |\r\n| `10000000` | `%s` 不符合 `%s` 格式，例如交易金额格式错误 |\r\n| `10000000` | 订单已超时 |\r\n| `20000000` | 重复交易 |\r\n| `21000000` | 手续费金额、手续费收取方式、手续费扣款标识、手续费子客户号、手续费账户号必须同时为空或同时必填 |\r\n| `22000000` | 产品号不存在 |\r\n| `22000000` | 产品号状态异常 |\r\n| `22000002` | 商户信息不存在 |\r\n| `22000002` | 商户状态异常 |\r\n| `22000003` | 延迟账户不存在 |\r\n| `22000003` | 商户账户信息不存在 |\r\n| `22000004` | 暂未开通分账权限 |\r\n| `22000004` | 暂未开通 `%s` 权限 |\r\n| `22000004` | 暂未开通延迟入账权限 |\r\n| `22000005` | 手续费承担方必须参与分账 |\r\n| `22000005` | 分账列表必须包含主交易账户 |\r\n| `22000005` | 其他商户分账比例过高 |\r\n| `\n\nArchive v1.3.2: 113 files, 415391 bytes\n\nFiles: agents/openai.yaml (398b), references/aggregation-async-webhook.md (7041b), references/aggregation-base.md (3287b), references/aggregation-common-params.md (6256b), references/aggregation-customer-preparation.md (10257b), references/aggregation-error-codes.md (4081b), references/aggregation-faq.md (5044b), references/aggregation-java-adapter.md (2239b), references/aggregation-java-sdk-quickstart.md (8935b), references/aggregation-java-tech-spec.md (5258b), references/aggregation-order-errors.md (7063b), references/aggregation-order-method-alipay.md (7507b), references/aggregation-order-method-unionpay.md (3935b), references/aggregation-order-method-wechat.md (7001b), references/aggregation-order-quickstart.md (2701b), references/aggregation-order-request.md (10907b), references/aggregation-order-response.md (10548b), references/aggregation-order-tx-metadata.md (11529b), references/aggregation-order.md (3407b), references/aggregation-payload-construction.md (10005b), references/aggregation-php-adapter.md (10209b), references/aggregation-python-adapter.md (7071b), references/aggregation-python-scenarios.md (7929b), references/aggregation-query-close-query.md (7479b), references/aggregation-query-payment-query.md (19426b), references/aggregation-query-php-scenarios.md (8630b), references/aggregation-query-quickstart.md (1509b), references/aggregation-query-reconciliation.md (9027b), references/aggregation-query-trade-close.md (7889b), references/aggregation-query.md (3522b), references/aggregation-quickstart.md (3419b), references/aggregation-refund-query.md (8877b), references/aggregation-refund-quickstart.md (1362b), references/aggregation-refund.md (11808b), references/canonical-regression-prompts.md (3395b), references/checkout-js-callback-and-confirmation.md (2350b), references/checkout-js-component-modes.md (2664b), references/checkout-js-create-preorder-contract.md (3381b), references/checkout-js-framework-integration-notes.md (1806b), references/checkout-js-integration-flow.md (3260b), references/checkout-js-readme.md (1549b), references/checkout-js.md (2364b), references/copilot-existing-system.md (4883b), references/copilot-go-live-checklist.md (3136b), references/copilot-onboarding.md (5174b), references/copilot-parameter-review.md (2960b), references/copilot-solution-cards.md (8714b), references/copilot-solution-selection....","readmeExcerpt":"Skill: 汇付支付集成 Owner: huifu Summary: 汇付支付/斗拱支付（Huifu Payment）交易接入与开发排障。用于支付 API/SDK、聚合支付、托管支付、收银台组件checkout-js、统一/H5/PC 收银台，以及微信、支付宝、银联、抖音、小程序、JSAPI、公众号、扫码、付款码、B2B/B2C 网银和快捷支付等场景；覆盖预下单/下单、查单、关单、退款、合单、拆单/分账交易、对账账单，以及异步通知和支付终态处理。支持 Java/PHP/Python SDK、完整请求与响应 签名验签、请求头、幂等去重、重复回调/重复发货、查单补偿、错误码与通道排查、存量系统改造、沙箱联调、上线检查和生产问题脱敏升级等开发集成。 Tags: latest:1.3.5 Version history: v1.3.5 | 2026-08-31T08:52:48.148Z | user - 新增对交易分账明细（trad","codeSnippets":[],"executableExamples":[{"language":"xml","snippet":"<dependency>\n    <groupId>com.huifu.dg.lightning.sdk</groupId>\n    <artifactId>dg-lightning-sdk</artifactId>\n    <version>1.0.5</version>\n</dependency>"},{"language":"xml","snippet":"<dependency>\n    <groupId>com.huifu.bspay.sdk</groupId>\n    <artifactId>dg-java-sdk</artifactId>\n    <version>3.0.40</version>\n</dependency>"},{"language":"bash","snippet":"mvn clean install"},{"language":"java","snippet":"package com.yourcompany.huifu.config;\n\nimport com.huifu.dg.lightning.biz.config.MerConfig;\nimport com.huifu.dg.lightning.utils.BasePay;\nimport lombok.extern.slf4j.Slf4j;\nimport org.springframework.beans.factory.annotation.Value;\nimport org.springframework.context.annotation.Configuration;\n\nimport javax.annotation.PostConstruct;\n\n@Configuration\n@Slf4j\npublic class HuifuLightningConfig {\n\n    @Value(\"${huifu.product-id}\")\n    private String productId;\n\n    @Value(\"${huifu.sys-id}\")\n    private String sysId;\n\n    @Value(\"${huifu.rsa-private-key}\")\n    private String rsaPrivateKey;\n\n    @Value(\"${huifu.rsa-public-key}\")\n    private String rsaPublicKey;\n\n    @Value(\"${huifu.skill-source:hfps/1.3.5}\")\n    private String skillSource;\n\n    @Value(\"${huifu.mode:prod}\")\n    private String mode;\n\n    @PostConstruct\n    public void initSdk() throws Exception {\n        // SDK 1.0.5 默认 debug=true，会输出私钥、签名和请求数据。\n        // 必须在任何初始化或请求之前全局关闭，且不得按请求临时切换。\n        BasePay.debug = false;\n\n        // 设置环境模式\n        if (\"test\".equals(mode)) {\n            BasePay.prodMode = BasePay.MODE_TEST;\n            log.info(\"汇付聚合支付SDK: 联调环境\");\n        } else {\n            BasePay.prodMode = BasePay.MODE_PROD;\n            log.info(\"汇付聚合支付SDK: 生产环境\");\n        }\n\n        // 初始化商户配置\n        MerConfig merConfig = new MerConfig();\n        merConfig.setProductId(productId);   // 注意：Lightning SDK 拼写正常\n        merConfig.setSysId(sysId);\n        merConfig.setRsaPrivateKey(rsaPrivateKey);\n        merConfig.setRsaPublicKey(rsaPublicKey);\n        merConfig.setSkillSource(skillSource);\n\n        BasePay.initWithMerConfig(merConfig);  // 注意：throws Exception\n        log.info(\"汇付聚合支付SDK初始化完成\");\n    }\n}"},{"language":"java","snippet":"Map<String, MerConfig> configs = new HashMap<>();\n\n// 多商户初始化同样必须先全局关闭调试输出。\nBasePay.debug = false;\n\nMerConfig config1 = new MerConfig();\nconfig1.setProductId(\"MYPAY\");\nconfig1.setSysId(\"6666000123120001\");\nconfig1.setRsaPrivateKey(\"...\");\nconfig1.setRsaPublicKey(\"...\");\nconfig1.setSkillSource(\"hfps/1.3.5\");\nconfigs.put(\"merchant1\", config1);\n\nMerConfig config2 = new MerConfig();\nconfig2.setSysId(\"6666000123120002\");\nconfig2.setSkillSource(\"hfps/1.3.5\");\n// ... 配置第二个商户\nconfigs.put(\"merchant2\", config2);\n\nBasePay.initWithMerConfigs(configs);"},{"language":"java","snippet":"MerConfig merConfig = new MerConfig();\n// ... 基本配置\nmerConfig.setCustomConnectTimeout(\"30000\");              // 连接超时 30s（默认 20s），注意是 String 类型\nmerConfig.setCustomSocketTimeout(\"30000\");               // 读取超时 30s（默认 20s）\nmerConfig.setCustomConnectionRequestTimeout(\"40000\");    // 请求超时 40s（默认 30s）\nmerConfig.setSkillSource(\"hfps/1.3.5\");"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: huifu-pay-integration\ndescription: \"汇付支付交易集成：用于聚合支付、托管支付、checkout-js、下单、查单、关单、退款、对账、支付通知、签名验签、请求头、幂等、交易终态、本地沙箱和支付上线；不用于企业/个人商户进件、图片上传、商户业务开通、商户详情或申请状态查询，这些任务使用 huifu-merchant-onboarding。\"\n---\n\n# 汇付支付集成\n\n## 版权声明\n\n本 Skill 中的汇付支付资料整理自上海汇付支付有限公司官方开放平台与官方产品文档；原始文档及其更新维护权归汇付支付官方所有。仅作技术学习交流与接口集成辅助使用，详见 `references/shared-copyright-notice.md`。\n\n## 执行流程\n\n1. 识别产品线、Endpoint、接入阶段、技术栈、端形态、当前目标和是否存量系统。完成标准：这些维度均已唯一确定，极速版产品场景与 V4 API 枚举已分开。\n2. 检查下方硬检查点；命中时停止生成可运行实现，只问一个最高优先级问题。完成标准：已记录命中或未命中的具体理由，SDK 传输安全和调试日志均已检查。\n3. 从精确路由中选择 3–5 份 reference。只有用户同时提出两个独立目标时才合并；完整 DTO、响应或嵌套字段任务必须包含完整字段目录。完成标准：每个目标均有一跳可达的原子接口页、合同定位路径、实际 JSON/解码路径（分别记录 wire 字段路径与 String(JSON) 解码后路径）和明确语言 adapter，不使用“对应文档”占位，也不把官网展示分组当成 wire key；只有官网明确标注“方便文档展示”时才从 wire 路径移除该分组。\n4. 首次接入输出产品线判断和方案卡；存量接入输出新增、保留、人工确认和回归检查。完成标准：请求、前端交接、通知、终态和补偿查询责任均已落到具体组件。\n5. 最后应用签名、验签、幂等、终态确认、请求字段保留和凭据安全规则。完成标准：每项均已检查，未知合同明确标记并停止生成相应实现。\n\n字段说明中的链接按其用途处理：完整字段目录已将官网 `#锚点` / 相对链接解析到各自接口原始页，并保留相对地址原文；绝对地址保持官网值。已确认的坏锚点使用显式映射：`#业务返回码` 补公共返回码全集，聚合下单 `notify_url` 的“异步返回参数”同时映射正扫、反扫通知参数和通用异步消息规范。只有命中本次字段的规范文档、编码表或渠道指引才作为外部资料提示。`notify_url`、`jump_url`、下载地址、二维码等裸 URL 示例是运行时值或格式示例，不是默认值、推荐地址或外部资料。\n\n本 Skill 只处理支付交易。企业、个人商户进件、图片资料、业务开通、商户详情和申请状态使用 `$huifu-merchant-onboarding`；不要从本 Skill 读取进件实现文档。\n\n## 精确路由\n\n| 场景 | 最小 reference 集 |\n| --- | --- |\n| 首次接入、产品线不明 | `references/shared-overview.md`、`references/copilot-onboarding.md`、`references/copilot-solution-selection.md` |\n| 存量系统接入 | `references/copilot-existing-system.md`、`references/copilot-solution-selection.md` |\n| 聚合支付快速接入 | `references/aggregation-quickstart.md`、`references/aggregation-customer-preparation.md` |\n| 聚合下单参数或代码 | `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` 补微信/支付宝/银联分册 |\n| 聚合交易查询 | `references/aggregation-query-payment-query.md` |\n| 返回码、公共编码或术语 | `aggregation-error-codes.md`、`aggregation-common-params.md`；具体字段仍补对应原子接口页 |\n| 聚合关单 | `references/aggregation-query-trade-close.md` |\n| 聚合对账 | `references/aggregation-query-reconciliation.md` |\n| 聚合退款或退款查询 | `references/aggregation-refund.md`、`references/payment-complete-field-catalog.md`，查询时补 `references/aggregation-refund-query.md` |\n| 托管支付快速接入 | `references/hostingpay-quickstart.md`、`references/hostingpay-customer-preparation.md` |\n| 托管预下单 | `references/hostingpay-preorder.md`、`references/payment-complete-field-catalog.md`，再按端形态补一个原子文档 |\n| 抖音直连、`pre_order_type=4` | `references/hostingpay-preorder.md`、`references/hostingpay-preorder-douyin-direct.md` |\n| 拆单支付查询、`splitpay/query` | `references/hostingpay-query.md`、`references/hostingpay-query-splitpay.md`；完整 DTO 同时执行下方完整字段目录路由 |\n| 交易分账明细、`trade/trans/split/query` | `references/trade-split-detail-query.md`、`references/payment-complete-field-catalog.md`；代码任务再补对应 Java/PHP/Python adapter |\n| 托管退款 | `references/hostingpay-refund.md`；完整 DTO 同时执行下方完整字段目录路由，Java setter 问题补 `references/hosting"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7as5mtmp7qjv21jr9n15qth182kat3\",\n  \"slug\": \"huifu-pay-integration\",\n  \"version\": \"1.3.5\",\n  \"publishedAt\": 1788166368148\n}"},{"path":"references/aggregation-async-webhook.md","content":"# 异步通知与 Webhook\r\n\r\n> 本文面向 `references/aggregation-base.md` 依赖的聚合支付 Skill，重点把交易通知的真实报文形态、验签方式、幂等和终态判断说明清楚。\r\n\r\n\r\n## 目录\r\n\r\n- 两种异步机制\r\n- `notify_url` 使用规范\r\n- 聚合交易通知报文形态\r\n- Spring Boot 接收、验签与查单示例\r\n- 终态判断原则\r\n- 签名差异\r\n- Webhook 使用场景\r\n- Webhook 落地步骤\r\n- Webhook 重发规则\r\n- 使用建议\r\n- 参考\r\n\r\n## 两种异步机制\r\n\r\n| 机制 | 入口 | 用途 | 签名方式 |\r\n|------|------|------|----------|\r\n| `notify_url` | 下单、退款等接口请求参数 | 交易结果回调 | 汇付 RSA 公钥验签 |\r\n| Webhook | 汇付控台端点订阅 | 平台事件通知 | 终端密钥 + MD5 原始事件体 |\r\n\r\n## `notify_url` 使用规范\r\n\r\n- 汇付以 HTTP `POST` 发送交易结果。\r\n- 响应必须在 5 秒内返回。\r\n- 正确应答格式为：HTTP `200` + `RECV_ORD_ID_` + `req_seq_id`。\r\n- 未及时应答或应答格式不正确时，汇付会自动重试，最多 3 次。\r\n- 自定义端口需落在 `8000-9005`。\r\n- URL 不要带查询参数。\r\n- 同一笔交易可能会重复通知，必须用 `hf_seq_id` 做幂等。\r\n\r\n## 聚合交易通知报文形态\r\n\r\n聚合支付的交易类异步通知，外层通常包含以下 4 个网关字段：\r\n\r\n| 字段 | 说明 |\r\n|------|------|\r\n| `resp_code` | 网关返回码 |\r\n| `resp_desc` | 网关返回信息 |\r\n| `sign` | 对整个业务数据的签名 |\r\n| `resp_data` | 业务数据 JSON 字符串 |\r\n\r\n其中真正要驱动业务的字段在 `resp_data` 里，而不是直接平铺在最外层。\r\n\r\n```json\r\n{\r\n  \"resp_code\": \"10000\",\r\n  \"resp_desc\": \"成功调用\",\r\n  \"sign\": \"返回签名串\",\r\n  \"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\\\"}\"\r\n}\r\n```\r\n\r\n## Spring Boot 接收、验签与查单示例\r\n\r\n```java\r\nimport com.alibaba.fastjson.JSON;\r\nimport com.alibaba.fastjson.JSONObject;\r\n// Spring Boot 2.x: import javax.servlet.http.HttpServletRequest;\r\n// Spring Boot 3.x: import jakarta.servlet.http.HttpServletRequest;\r\nimport java.util.Objects;\r\nimport org.springframework.beans.factory.annotation.Value;\r\nimport org.springframework.util.StringUtils;\r\nimport org.springframework.web.bind.annotation.PostMapping;\r\nimport org.springframework.web.bind.annotation.RequestMapping;\r\nimport org.springframework.web.bind.annotation.RestController;\r\n\r\n@RestController\r\n@RequestMapping(\"/notify\")\r\npublic class AggregateNotifyController {\r\n\r\n    private final String huifuPublicKey;\r\n    private final AggregateQueryService queryService;\r\n    private final NotifyIdempotentService idempotentService;\r\n\r\n    public AggregateNotifyController(\r\n            @Value(\"${huifu.rsa-public-key}\") String huifuPublicKey,\r\n            AggregateQueryService queryService,\r\n            NotifyIdempotentService idempotentService) {\r\n        this.huifuPublicKey = huifuPublicKey;\r\n        this.queryService = queryService;\r\n        this.idempotentService = idempotentService;\r\n    }\r\n\r\n    @PostMapping(\"/payment\")\r\n    public String onNotify(HttpServletRequest request) {\r\n        String respData = request.getParameter(\"resp_data\");\r\n        String sign = request.getParameter(\"sign\");\r\n        if (!StringUtils.hasText(respData) || !StringUtils.hasText(sign)) {\r\n            throw new IllegalArgumentException(\"汇付回调缺少 resp_data 或 sign\");\r\n        }\r\n        if (!RsaUtils.verify(respData, huifuPublicKey, sign)) {\r\n            throw new IllegalArgumentException(\"汇付回调验签失败\");\r\n        }\r\n\r\n      "},{"path":"references/aggregation-base.md","content":"# 聚合支付基础\r\n\r\n这份文档负责聚合支付的初始化、公共参数、语言边界和接入前置判断。\r\n\r\n## 什么时候读这里\r\n\r\n- 第一次接聚合支付\r\n- 需要确认 `trade_type`、公共环境变量、初始化顺序\r\n- 需要判断当前应该走 Java、PHP 还是 Python\r\n\r\n## 推荐阅读顺序\r\n\r\n```text\r\nshared-overview\r\n  -> shared-signing-v2\r\n  -> shared-request-header-policy\r\n  -> aggregation-base\r\n  -> aggregation-order / aggregation-query / aggregation-refund\r\n```\r\n\r\n## 当前版本口径\r\n\r\n| 项目 | 当前值 |\r\n| --- | --- |\r\n| Java SDK | `dg-lightning-sdk 1.0.5` |\r\n| PHP 覆盖范围 | 下单、扫码交易查询、关单、关单查询、退款、退款查询、对账 |\r\n| `HUIFU_SKILL_SOURCE` 最终值 | `<skill_source>` |\r\n\r\n## 必备环境变量\r\n\r\n| 环境变量 | 用途 |\r\n| --- | --- |\r\n| `HUIFU_PRODUCT_ID` | 汇付分配的产品号 |\r\n| `HUIFU_SYS_ID` | 渠道商 / 商户 `huifu_id` |\r\n| `HUIFU_RSA_PRIVATE_KEY` | 请求签名私钥 |\r\n| `HUIFU_RSA_PUBLIC_KEY` | 响应验签公钥 |\r\n| `HUIFU_SKILL_SOURCE` | 可选来源覆盖项，请求头层按 `<skill_source>` 原样透传 |\r\n\r\n## 初始化前确认事项\r\n\r\n1. 先读 `references/shared-signing-v2.md`\r\n2. 先读 `references/shared-async-notify.md`\r\n3. 如果不是 Java，必须额外核对 `references/shared-request-header-policy.md`\r\n4. 不要猜测 `sub_openid`、`buyer_id`、`auth_code`、`devs_id`、`fee_sign` 等运行时值\r\n\r\n## 聚合支付主流程\r\n\r\n```text\r\n准备产品号和密钥\r\n  -> 初始化 SDK 或 HTTP 客户端\r\n  -> 选择 trade_type\r\n  -> aggregation-order 下单\r\n  -> aggregation-query 查单 / 关单 / 对账\r\n  -> aggregation-refund 退款\r\n```\r\n\r\n## trade_type 速查\r\n\r\n| trade_type | 说明 |\r\n| --- | --- |\r\n| `T_JSAPI` | 微信公众号支付 |\r\n| `T_MINIAPP` | 微信小程序支付 |\r\n| `T_APP` | 微信 APP 支付 |\r\n| `T_MICROPAY` | 微信付款码反扫 |\r\n| `A_JSAPI` | 支付宝 JS 支付 |\r\n| `A_NATIVE` | 支付宝正扫 |\r\n| `A_MICROPAY` | 支付宝付款码反扫 |\r\n| `U_JSAPI` | 银联 JS 支付 |\r\n| `U_NATIVE` | 银联正扫 |\r\n| `U_MICROPAY` | 银联付款码反扫 |\r\n\r\n## 语言边界\r\n\r\n- Java 是聚合支付完整基线\r\n- PHP 已覆盖聚合支付核心主链路与对账；默认入口先读 `references/aggregation-php-adapter.md` 与 `references/aggregation-query-php-scenarios.md`\r\n- Python 已覆盖聚合支付核心主链路与对账；默认入口先读 `references/aggregation-python-adapter.md` 与 `references/aggregation-python-scenarios.md`\r\n- 当前 Skill 包不再内置 PHP 模板资产；PHP 默认走官方 `huifurepo/dg-php-sdk`\r\n- C#、Go 当前只保留统一入口说明，不提供现成业务模板\r\n\r\n## 公共字段提醒\r\n\r\n- `req_seq_id` 必须保证当日唯一\r\n- `req_date` 建议始终保存，后续查询、关单、退款都要回用\r\n- `method_expand`、`acct_split_bunch`、`terminal_device_data`、`combinedpay_data`、`combinedpay_data_fee_info`、`trans_fee_allowance_info` 应先建模再序列化；`tx_metadata` 本身不作为请求字段上送\r\n\r\n## 下一步怎么走\r\n\r\n- 要创建订单：读 `references/aggregation-order.md`\r\n- 要查单 / 关单 / 对账：读 `references/aggregation-query.md`\r\n- 要退款：读 `references/aggregation-refund.md`"},{"path":"references/aggregation-common-params.md","content":"# 公共参数说明\n\n官方公共资料入口：\n\n- [基础参数汇总](https://paas.huifu.com/partners/api/doc/csfl/api_csfl.md)：地区、银行、支行、MCC、交易类型、文件类型等公共编码/枚举的入口。\n- [名词解释](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_mcjs.md)：ATU、H5、结算周期、手续费等术语口径。\n- [返回码](https://paas.huifu.com/partners/api/doc/csfl/api_csfl_ywm.md)：网关与业务返回码全集。\n\n这些页面是公共字典和术语来源，不覆盖具体接口页对字段必填、条件、类型和层级的定义；发生差异时保留两边证据并按具体接口合同处理。\n\n\n## 目录\n\r\n- 公共请求参数\r\n- 公共返回参数\r\n- 业务数据通用字段\r\n- 交易状态枚举（trans_stat）\r\n- 金额格式\r\n- 日期时间格式\r\n- 流水号规则\r\n- 支付类型详解\r\n- 标准字段与格式约束\r\n- 结算术语\r\n- 手续费术语\r\n\r\n## 公共请求参数\r\n\r\n所有聚合支付 API 请求的外层参数：\r\n\r\n| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |\r\n|------|-------|------|------|------|------|\r\n| sys_id | 系统号 | String | 32 | Y | 渠道商/代理商/商户的 huifu_id |\r\n| product_id | 产品号 | String | 32 | Y | 汇付分配的产品号，如 `MYPAY`、`YYZY` |\r\n| sign | 加签结果 | String | 512 | Y | SDK 自动生成，无需手动处理 |\r\n| data | 请求数据 | JSON | - | Y | 业务请求参数 |\r\n\r\n> 强制请求头约束：\r\n> - 必须带 `jpt-x-skill-source: <skill_source>`\r\n> - 如果当前按 PHP 接入，且接口业务报文里存在 `huifu_id`，还必须带 `jpt-x-skill-huifu_id: <data.huifu_id>`\r\n> - 当前 Skill 包对齐的官方 PHP SDK 主链路在 `MerConfig.skill_source` 已配置时，会自动带 `jpt-x-skill-source`，并在当前请求 `huifu_id` 存在且非空时自动带 `jpt-x-skill-huifu_id`\r\n> - 当前 Java SDK 基线也会在接口业务报文里 `huifu_id` 存在且非空时自动带 `jpt-x-skill-huifu_id: <data.huifu_id>`\r\n> - 这两项属于 HTTP 请求头，不属于 `data` 字段本身；完整口径见 `references/shared-request-header-policy.md`\r\n\r\n### sys_id 说明\r\n\r\n| 主体类型 | sys_id 填写 |\r\n|---------|-----------|\r\n| 渠道商/代理商 | 渠道商/代理商的 huifu_id |\r\n| 直连商户 | 商户自身的 huifu_id |\r\n\r\n> **sys_id vs huifu_id**：`sys_id` 是外层公共参数，标识调用方身份；`huifu_id` 是 `data` 内业务参数，标识交易商户。渠道商模式下两者不同，直连商户模式下两者相同。\r\n\r\n## 公共返回参数\r\n\r\n| 参数 | 中文名 | 类型 | 长度 | 说明 |\r\n|------|-------|------|------|------|\r\n| sign | 签名 | String | 512 | SDK 自动验证 |\r\n| data | 响应内容体 | JSON | - | 业务返回参数 |\r\n\r\n## 业务数据通用字段\r\n\r\n以下字段在多数业务接口的 `data` 中出现：\r\n\r\n| 参数 | 中文名 | 类型 | 说明 |\r\n|------|-------|------|------|\r\n| resp_code | 业务响应码 | String(8) | 接口受理返回码，用于排查；订单终态仍看 `trans_stat` 和查单结果 |\r\n| resp_desc | 业务响应信息 | String(512) | 响应描述 |\r\n| huifu_id | 商户号 | String(32) | 商户 huifu_id |\r\n| req_date | 请求日期 | String(8) | 格式 yyyyMMdd |\r\n| req_seq_id | 请求流水号 | String(128) | 同一 huifu_id 下当天唯一 |\r\n| hf_seq_id | 汇付全局流水号 | String(128) | 汇付生成的全局唯一标识 |\r\n\r\n## 交易状态枚举（trans_stat）\r\n\r\n| 值 | 含义 | 处理方式 |\r\n|---|------|---------|\r\n| I | 初始 | 罕见状态，联系汇付技术人员 |\r\n| P | 处理中 | 等待异步通知或轮询查询接口 |\r\n| S | 成功 | 交易完成 |\r\n| F | 失败 | 交易失败，可重新发起 |\r\n\r\n## 金额格式\r\n\r\n- **单位**：元（CNY）\r\n- **精度**：保留两位小数\r\n- **最小值**：0.01\r\n- **示例**：`\"1.00\"`、`\"100.50\"`、`\"0.01\"`\r\n\r\n## 日期时间格式\r\n\r\n| 格式 | 说明 | 示例 |\r\n|------|------|------|\r\n| yyyyMMdd | 日期 | `20250320` |\r\n| yyyyMMddHHmmss | 日期时间（14位） | `20250320143000` |\r\n| HHmmss | 时间（6位） | `143000` |\r\n\r\n## 流水号规则\r\n\r\n| 字段 | 规则 | 说明 |\r\n|------|------|------|\r\n| req_seq_id | 同一 huifu_id 下当天唯一 | 商户自行生成 |\r\n| hf_seq_id | 全局唯一 | 汇付返回，用于查询/退款 |\r\n| org_req_seq_id | 原交易的 req_seq_id | 用于关联原交易 |\r\n| org_hf_seq_id | 原交易的 hf_seq_id | 可替代 org_req_seq_id |\r\n\r\n## 支付类型详解\r\n\r\n### 正扫 vs 反扫\r\n\r\n| 类型 | 说明 | 适用 trade_type |\r\n|------|------|----------------|\r\n| 正扫 (NATIVE) | 商户生成二维码，用户扫码支付 | A_NATIVE、U_NATIVE |\r\n| 反扫 (MICROPAY) | 用户出示付款码，商户扫码收款 | T_M"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1051,"uniquenessScore":41,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T06:04:52.994Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T06:04:52.994Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T10:45:02.400Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"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!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"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","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}