hmos-payment-kit-huawei-payment-integration
本技能面向 HarmonyOS Payment Kit 华为 / 鸿蒙支付接入排障,覆盖基础支付、签约代扣、平台合单、回调验签、沙盒联调、SpringBoot 服务端与 ArkTS 客户端适配,包含官方 Java‑SDK、Maven 构建、配置校验、常见报错排查,命中指定关键词即启用,输出接入指引与问题修复方案。
- License 许可
- GPL-3.0
- 最近更新
- 2026-10-08
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- hmos-payment-kit-huawei-payment-integration
- version
- 1.8.0
- description
- 本技能面向 HarmonyOS Payment Kit 华为 / 鸿蒙支付接入排障,覆盖基础支付、签约代扣、平台合单、回调验签、沙盒联调、SpringBoot 服务端与 ArkTS 客户端适配,包含官方 Java‑SDK、Maven 构建、配置校验、常见报错排查,命中指定关键词即启用,输出接入指引与问题修复方案。
02 资源文件 19
- 资产文件assets/examples.md1.8 KB
- 资产文件assets/基础支付/示例代码/ASCF-客户端支付示例.md711 B
- 资产文件assets/基础支付/示例代码/Java-快速请求调试示例.md509 B
- 资产文件assets/基础支付/示例代码/Java-支付回调示例.md684 B
- 资产文件assets/基础支付/示例代码/Java-服务端查单示例.md705 B
- 资产文件assets/基础支付/示例代码/Java-服务端配置示例.md1.0 KB
- 资产文件assets/基础支付/示例代码/Java-服务端预下单示例.md1.1 KB
- 资产文件assets/基础支付/示例代码/客户端配置示例.md2.2 KB
- 资产文件assets/基础支付/示例代码/接口索引.md2.5 KB
- 资产文件assets/基础支付/示例代码/标准App-客户端支付示例.md935 B
- 资产文件assets/平台类合单/示例代码/接口索引.md1.3 KB
- 资产文件assets/平台类合单/示例代码/服务端最小结构示例.md1.2 KB
- 资产文件assets/签约代扣/示例代码/ASCF-客户端签约示例.md510 B
- 资产文件assets/签约代扣/示例代码/Java-服务端预签约示例.md771 B
- 资产文件assets/签约代扣/示例代码/客户端配置检查项.md616 B
- 资产文件assets/签约代扣/示例代码/接口索引.md1.6 KB
- 资产文件assets/签约代扣/示例代码/服务端配置检查项.md588 B
- 资产文件assets/签约代扣/示例代码/标准App-客户端签约示例.md442 B
- 参考文档tests/evals.json5.5 KB
03 SKILL.md 正文
华为支付 / 鸿蒙支付服务接入指引
何时使用
本技能中,“华为支付”“鸿蒙支付服务”“HarmonyOS Payment Kit”默认视为同一类能力入口。
在下面这些场景优先使用本技能:
- 用户明确提到华为支付、鸿蒙支付服务、HarmonyOS Payment Kit、
orderStr、contractStr、预下单、预签约、回调验签、幂等、平台类合单。 - 用户在 HarmonyOS / ArkTS 客户端里排查鸿蒙支付服务 / Payment Kit 拉起失败、字段不对齐、
module.json5/oh-package.json5配置、arkts-no-any-unknown、API is supported since SDK version ...、UIAbilityContext获取方式等问题。 - 用户在 Java / Spring Boot 服务端里接入鸿蒙支付服务 / Payment Kit、排查 Maven 依赖、官方 SDK 可用性、预下单、回调验签、证书或构建问题。
- 用户提到现网典型错误码(如
CHECK_ACCOUNT_BALANCE、TRX100701、INVALID_MERCNO、INVALID_APPID、INVALID_SIGNATURE、INVALID_PARAMETER、200001)、退款失败、账单查询、子商户进件、证书准备、签约代扣失败、回调验签失败等排障场景,应优先检索references/5-问题排查/下的典型问题集,而非从零推导。
以下情况不要把它当作普通技能替代:
- 纯前端样式、通用 Java 后端、与华为支付 / 鸿蒙支付服务无关的编译或框架问题。
- 只涉及通用支付业务建模,但没有 Payment Kit / HarmonyOS / 华为支付 / 鸿蒙支付服务上下文。
使用顺序
- 先确认业务路径:基础支付、签约代扣,还是平台类合单。
- 再确认客户端类型与服务端形态:标准 App / ASCF、Java SDK / 自研 REST / 其他语言。
- 先读资源层,再给结论或代码,避免把
SKILL.md当成完整知识库。
常用入口:
- 场景与主题导航:reference.md
- 示例入口:examples.md
- 场景选择:场景选择说明
- 服务端官方 SDK 最小事实:官方 Java SDK 最小事实
全局高优先级规则
以下规则适用于本技能全部能力和全部对话轮次,优先级高于局部规则。
- 关键问题必须得到用户明确回答后才能继续。 对商户模型、业务场景、客户端类型、服务端语言等关键信息,严禁擅自猜测或补默认值。
- 场景前置确认:除简单知识问答外,优先确认当前属于基础支付、签约代扣还是平台类合单,再进入后续能力。
- 分步确认协议:需要帮用户分析、排障、改代码或执行操作时,必须遵循“先理解需求 -> 提议下一步 -> 征得同意 -> 收集信息 -> 执行前确认”。
- 线上风险提示:涉及生产环境、真实商户号、证书、公钥私钥、回调地址等内容时,必须先提示风险,再继续。
- 资源优先原则:优先从
references/检索现有指南和示例代码;资源缺失时,才可结合官方文档和本技能规则补充最小示例。 - 最小改动原则:处理
module.json5、oh-package.json5、客户端页面代码或服务端配置时,只给必要修改,不擅自扩大变更范围。 - 接口契约先行:凡是客户端要直接调用商户服务端预下单或预签约接口,改代码前必须明确接口 URL、请求字段、响应字段、回调地址和金额单位;缺任一关键项时,先向用户确认,严禁按页面字段名臆测服务端字段名。
- ArkTS 编译约束前置:在 HarmonyOS 客户端改代码前,先确认当前工程的兼容 SDK 和 ArkTS 语法约束;不要先写出高版本 API 或 TypeScript 宽泛类型,再等编译报错后回改。
- 只改源码,不改构建产物:
entry/build/、.hvigor/、缓存产物中的.ts文件只可用于只读比对或推断历史实现,不能当作正式源码编辑目标;最终改动必须回到src/main/ets等源码目录。 - 服务端商户模型先行:只要涉及 Java/Spring Boot 等服务端预下单、回调或签名验签实现,必须先确认商户模型(直连商户 / 服务商 / 平台类商户)与业务场景;未确认前,不得擅自决定接口路径、请求字段或
appId/mercNo/spAppId/spMercNo/subMercNo映射关系。 - SDK 可用性闸门:当用户要求“优先官方 SDK / 必须使用官方 SDK”时,必须先验证依赖是否可下载、关键类是否可见、关键 API 是否可确认;若三者任一无法验证,不得伪造 SDK 直连实现,应退回“SDK 适配层 + HTTP 网关兜底”的结构并明确告知用户。
- 用户已提供官方接入文档或官方样例工程时:优先以文档/样例中的 Maven 坐标、
pom.xml、MercApiController等真实源码为准完成验证;只有在“已按官方路径仍无法完成三者验证”时,才允许降级到 HTTP 网关兜底,并在回复中明确写出降级原因与恢复条件。 - 官方文档页为 SPA(抓取正文为空)时:不要仅凭 HTML 外壳判断“无 SDK”;应改用官方样例仓库、
mvn dependency:get、本地~/.m2产物、javap反查类签名等方式完成验证。
- 用户已提供官方接入文档或官方样例工程时:优先以文档/样例中的 Maven 坐标、
- 源码事实优先于文档:服务端工程改造时,优先以
src/main/java、src/main/resources等真实源码为准;README.md、target/、build/、metadata、历史产物只能作为线索,不能当作源码事实。
能力与路由
1. 接入路线判断
当用户只说“要接华为支付”或“要接鸿蒙支付服务”时,先帮助其确认:
- 基础支付、签约代扣,还是平台类合单。
- 标准 HarmonyOS App 还是 ASCF 元服务。
- Java SDK、自研 REST,还是其他服务端语言。
优先读取:
2. 示例代码检索
用户要代码时,不直接从零生成,先确认场景和端类型,再读取索引:
输出代码时继续遵守:
orderStr/contractStr必须由服务端生成。- 标准 App 和 ASCF 的接口形态不能混写。
- 一次优先解决一个链路节点,避免堆叠不相关代码。
3. 业务知识速查
用户问规则、配置、回调、上线或验签时,按主题跳到通用规则文档:
4. 客户端改代码前的最小确认
在 HarmonyOS 客户端做基础支付接入或字段修复前,至少确认:
- 预下单接口 URL。
- 请求字段名和含义,例如
mercOrderNo、tradeSummary、totalAmount、callbackUrl。 - 响应字段名,至少确认
orderStr在哪一层。 callbackUrl由服务端固定、客户端传入,还是页面可配置。- 金额单位是分的整数,还是元的十进制。
处理要求:
- 不得把页面字段名直接当作服务端契约。
- 用户只给报错文本时,先从报错里提取字段名再反推缺口。
- 字段改名后,同步检查状态字段、请求构造、类型定义和展示文案。
- 避免把
entry/build/、.hvigor/等缓存实现当作正式源码。
5. 服务端改代码前的最小确认
在 Java / Spring Boot 等服务端接入前,至少确认:
- 商户模型是直连商户、服务商,还是平台类商户。
- 当前业务场景是基础支付、签约代扣,还是平台类合单。
- 服务端语言与框架。
- 是否要求优先官方 SDK。
- 预下单字段契约与金额单位。
- 回调地址是固定配置还是由客户端传入。
处理要求:
- 未确认商户模型前,不决定
appId/mercNo或spAppId/spMercNo/subMercNo映射。 - 要求官方 SDK 时,先走 SDK 可用性闸门,再写实现。
- starter / 样例工程优先保证可编译、可替换、可配置。
- 新增依赖前先验证可解析,避免先写未解析
import。
6. 客户端兼容与服务端构建排查
遇到编译或构建问题时,先做轻量分流,不要一开始就怀疑支付逻辑:
- HarmonyOS 客户端:优先检查 compatible SDK、API 最低版本、
arkts-no-any-unknown、上下文获取方式、真实源码路径。 - Java 服务端:优先检查源码真实性、Maven / Gradle 可用性、依赖拉取、镜像仓和官方 SDK 可验证性。
典型问题分流:当用户描述现网错误码或业务排障场景时,按业务域检索 references/5-问题排查/ 下的典型问题集(四段式条目,含错误现象/常见原因/解决步骤/官方文档/现网来源)。先匹配错误码或现象到对应条目,再给出解决步骤,避免从零推导。
优先读取:
7. 质量评估与排障
用户准备联调、测试、上线,或已经出现报错时:
- 只检查当前实际使用的模块。
- 不以客户端回调当作最终交易结果。
- 验签失败、幂等缺失、沙盒标识未清理属于高优先级问题。
- 若服务端返回
resultDesc这类字段校验报错,优先核对字段契约,而不是先怀疑 Payment Kit 拉起逻辑。
现网典型问题集入口(v1.8.0 新增):
- 基础支付排障:支付常见问题(含 TP-PAY-001~014)
- 退款排障:退款典型问题(含 TP-REF-001~007)
- 签约代扣排障:签约代扣典型问题(含 TP-WTH-001~006)
- 账单查询排障:账单查询典型问题(含 TP-BILL-001~006)
- 子商户进件排障:子商户进件典型问题(含 TP-SUB-001~006)
- 证书准备排障:证书准备典型问题(含 TP-CERT-001~007)
- 签名验签排障:签名与验签常见问题(含 TP-SIGN-001~007)
- 回调通知排障:回调与幂等常见问题(含 TP-CB-001~009)
- 错误码速查(含典型错误码→原因→解决映射):错误码速查
硬性红线
- 私钥不得出现在客户端代码、日志、公共仓库或对话明文示例中。
- 不得跳过回调验签,不得在验签失败时更新订单状态。
- 不得把
paymentService或 Payment Kit 虚构成三方依赖安装包。 - 不得建议客户端 Mock
orderStr或contractStr。 - 不得把标准 App API 和 ASCF API 混写。
- 不得把客户端回调结果作为最终支付或签约成功依据。
- 不得在未确认服务端字段契约前,擅自将页面字段名直接映射为预下单请求字段。
- 不得在官方 SDK 不可验证时,伪造 SDK 直连实现、虚构类名、配置对象或方法签名。
- 不得在新增 Maven 依赖尚未验证可解析前,就先写入依赖耦合实现或提交带有未解析
import的源码。 - 不得把
README、target/、build/、metadata 中出现的类或配置直接当作当前源码事实。 - 不得把
MOCK验签、内存幂等、样例签名工具包装成“可直接上线的生产实现”。
输出建议模板
## 结论
[一句话说明当前是否可接入、可联调、已定位问题或存在阻塞]
## 执行清单
- 已完成:
- [item]
- 待完成:
- [item]
## 风险与阻塞
- [风险项]
## 下一步
1. [最小可执行动作]
2. [下一步验证动作]
顶层入口
- 参考索引:reference.md
- 示例索引:examples.md
04 同仓库更多 Skills
writing-for-agents
为 agent 撰写文档。当创建或编辑 skill、修改 AGENTS.md 或 CLAUDE.md 时使用。
wait-what
停。上一条消息没讲明白:换个说法再讲一遍。
to-questionnaire
把你无法独自回答的决策转化成一份问卷,交给别人填写。
teach
在当前工作区内,教会用户一项新 skill 或概念。
handoff
把当前对话压缩成一份交接(handoff)文档,供另一个代理接手。
grilling
就一个计划、决策或想法对用户进行无情的访谈。当用户想压力测试自己的思路,或使用任何 'grill' 触发短语时使用。