Hmos Payment Kit Huawei Payment Integration

---
name: hmos-payment-kit-huawei-payment-integration
description: 本技能面向 HarmonyOS Payment Kit 华为 / 鸿蒙支付接入排障，覆盖基础支付、签约代扣、平台合单、回调验签、沙盒联调、SpringBoot 服务端与 ArkTS 客户端适配，包含官方 Java‑SDK、Maven 构建、配置校验、常见报错排查，命中指定关键词即启用，输出接入指引与问题修复方案。
version: 1.8.0
---

# 华为支付 / 鸿蒙支付服务接入指引

## 何时使用

本技能中，“华为支付”“鸿蒙支付服务”“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 / 华为支付 / 鸿蒙支付服务上下文。

## 使用顺序

1. 先确认业务路径：基础支付、签约代扣，还是平台类合单。
2. 再确认客户端类型与服务端形态：标准 App / ASCF、Java SDK / 自研 REST / 其他语言。
3. 先读资源层，再给结论或代码，避免把 `SKILL.md` 当成完整知识库。

常用入口：

- 场景与主题导航：[reference.md](references/reference.md)
- 示例入口：[examples.md](assets/examples.md)
- 场景选择：[场景选择说明](references/6-资源索引/场景选择说明.md)
- 服务端官方 SDK 最小事实：[官方 Java SDK 最小事实](references/4-通用规则/接入指南/官方JavaSDK最小事实.md)

## 全局高优先级规则

> 以下规则适用于本技能全部能力和全部对话轮次，优先级高于局部规则。

1. **关键问题必须得到用户明确回答后才能继续。** 对商户模型、业务场景、客户端类型、服务端语言等关键信息，严禁擅自猜测或补默认值。
2. **场景前置确认**：除简单知识问答外，优先确认当前属于基础支付、签约代扣还是平台类合单，再进入后续能力。
3. **分步确认协议**：需要帮用户分析、排障、改代码或执行操作时，必须遵循“先理解需求 -> 提议下一步 -> 征得同意 -> 收集信息 -> 执行前确认”。
4. **线上风险提示**：涉及生产环境、真实商户号、证书、公钥私钥、回调地址等内容时，必须先提示风险，再继续。
5. **资源优先原则**：优先从 `references/` 检索现有指南和示例代码；资源缺失时，才可结合官方文档和本技能规则补充最小示例。
6. **最小改动原则**：处理 `module.json5`、`oh-package.json5`、客户端页面代码或服务端配置时，只给必要修改，不擅自扩大变更范围。
7. **接口契约先行**：凡是客户端要直接调用商户服务端预下单或预签约接口，改代码前必须明确接口 URL、请求字段、响应字段、回调地址和金额单位；缺任一关键项时，先向用户确认，严禁按页面字段名臆测服务端字段名。
8. **ArkTS 编译约束前置**：在 HarmonyOS 客户端改代码前，先确认当前工程的兼容 SDK 和 ArkTS 语法约束；不要先写出高版本 API 或 TypeScript 宽泛类型，再等编译报错后回改。
9. **只改源码，不改构建产物**：`entry/build/`、`.hvigor/`、缓存产物中的 `.ts` 文件只可用于只读比对或推断历史实现，不能当作正式源码编辑目标；最终改动必须回到 `src/main/ets` 等源码目录。
10. **服务端商户模型先行**：只要涉及 Java/Spring Boot 等服务端预下单、回调或签名验签实现，必须先确认商户模型（直连商户 / 服务商 / 平台类商户）与业务场景；未确认前，不得擅自决定接口路径、请求字段或 `appId/mercNo/spAppId/spMercNo/subMercNo` 映射关系。
11. **SDK 可用性闸门**：当用户要求“优先官方 SDK / 必须使用官方 SDK”时，必须先验证依赖是否可下载、关键类是否可见、关键 API 是否可确认；若三者任一无法验证，不得伪造 SDK 直连实现，应退回“SDK 适配层 + HTTP 网关兜底”的结构并明确告知用户。
    - **用户已提供官方接入文档或官方样例工程时**：优先以文档/样例中的 Maven 坐标、`pom.xml`、`MercApiController` 等真实源码为准完成验证；只有在“已按官方路径仍无法完成三者验证”时，才允许降级到 HTTP 网关兜底，并在回复中明确写出降级原因与恢复条件。
    - **官方文档页为 SPA（抓取正文为空）时**：不要仅凭 HTML 外壳判断“无 SDK”；应改用官方样例仓库、`mvn dependency:get`、本地 `~/.m2` 产物、`javap` 反查类签名等方式完成验证。
12. **源码事实优先于文档**：服务端工程改造时，优先以 `src/main/java`、`src/main/resources` 等真实源码为准；`README.md`、`target/`、`build/`、metadata、历史产物只能作为线索，不能当作源码事实。

## 能力与路由

### 1. 接入路线判断

当用户只说“要接华为支付”或“要接鸿蒙支付服务”时，先帮助其确认：

- 基础支付、签约代扣，还是平台类合单。
- 标准 HarmonyOS App 还是 ASCF 元服务。
- Java SDK、自研 REST，还是其他服务端语言。

优先读取：

- [场景选择说明](references/6-资源索引/场景选择说明.md)
- [接入前置核查清单](references/4-通用规则/接入指南/接入前置核查清单.md)

### 2. 示例代码检索

用户要代码时，不直接从零生成，先确认场景和端类型，再读取索引：

- 基础支付：[接口索引](assets/1-基础支付/示例代码/接口索引.md)
- 签约代扣：[接口索引](assets/2-签约代扣/示例代码/接口索引.md)
- 平台类合单：[接口索引](assets/3-平台类合单/示例代码/接口索引.md)

输出代码时继续遵守：

- `orderStr` / `contractStr` 必须由服务端生成。
- 标准 App 和 ASCF 的接口形态不能混写。
- 一次优先解决一个链路节点，避免堆叠不相关代码。

### 3. 业务知识速查

用户问规则、配置、回调、上线或验签时，按主题跳到通用规则文档：

- [接入前置核查清单](references/4-通用规则/接入指南/接入前置核查清单.md)
- [签名与验签规则](references/4-通用规则/接入指南/签名与验签规则.md)
- [回调通知处理](references/4-通用规则/接入指南/回调通知处理.md)
- [沙盒联调与生产切换](references/4-通用规则/接入指南/沙盒联调与生产切换.md)
- [配置文件防误生成](references/4-通用规则/接入指南/配置文件防误生成.md)
- [接入质量检查清单](references/4-通用规则/接入指南/接入质量检查清单.md)
- [服务端构建与依赖排障](references/4-通用规则/接入指南/服务端构建与依赖排障.md)
- [官方 Java SDK 最小事实](references/4-通用规则/接入指南/官方JavaSDK最小事实.md)
- [官方文档映射](references/6-资源索引/官方文档映射.md)

### 4. 客户端改代码前的最小确认

在 HarmonyOS 客户端做基础支付接入或字段修复前，至少确认：

1. 预下单接口 URL。
2. 请求字段名和含义，例如 `mercOrderNo`、`tradeSummary`、`totalAmount`、`callbackUrl`。
3. 响应字段名，至少确认 `orderStr` 在哪一层。
4. `callbackUrl` 由服务端固定、客户端传入，还是页面可配置。
5. 金额单位是分的整数，还是元的十进制。

处理要求：

- 不得把页面字段名直接当作服务端契约。
- 用户只给报错文本时，先从报错里提取字段名再反推缺口。
- 字段改名后，同步检查状态字段、请求构造、类型定义和展示文案。
- 避免把 `entry/build/`、`.hvigor/` 等缓存实现当作正式源码。

### 5. 服务端改代码前的最小确认

在 Java / Spring Boot 等服务端接入前，至少确认：

1. 商户模型是直连商户、服务商，还是平台类商户。
2. 当前业务场景是基础支付、签约代扣，还是平台类合单。
3. 服务端语言与框架。
4. 是否要求优先官方 SDK。
5. 预下单字段契约与金额单位。
6. 回调地址是固定配置还是由客户端传入。

处理要求：

- 未确认商户模型前，不决定 `appId/mercNo` 或 `spAppId/spMercNo/subMercNo` 映射。
- 要求官方 SDK 时，先走 SDK 可用性闸门，再写实现。
- starter / 样例工程优先保证可编译、可替换、可配置。
- 新增依赖前先验证可解析，避免先写未解析 `import`。

### 6. 客户端兼容与服务端构建排查

遇到编译或构建问题时，先做轻量分流，不要一开始就怀疑支付逻辑：

- HarmonyOS 客户端：优先检查 compatible SDK、API 最低版本、`arkts-no-any-unknown`、上下文获取方式、真实源码路径。
- Java 服务端：优先检查源码真实性、Maven / Gradle 可用性、依赖拉取、镜像仓和官方 SDK 可验证性。

**典型问题分流**：当用户描述现网错误码或业务排障场景时，按业务域检索 `references/5-问题排查/` 下的典型问题集（四段式条目，含错误现象/常见原因/解决步骤/官方文档/现网来源）。先匹配错误码或现象到对应条目，再给出解决步骤，避免从零推导。

优先读取：

- [服务端构建与依赖排障](references/4-通用规则/接入指南/服务端构建与依赖排障.md)
- [支付常见问题](references/5-问题排查/支付常见问题.md)
- [错误码速查](references/5-问题排查/错误码速查.md)
- [签名与验签常见问题](references/5-问题排查/签名与验签常见问题.md)
- [回调与幂等常见问题](references/5-问题排查/回调与幂等常见问题.md)
- [退款典型问题](references/5-问题排查/退款典型问题.md)
- [账单查询典型问题](references/5-问题排查/账单查询典型问题.md)
- [子商户进件典型问题](references/5-问题排查/子商户进件典型问题.md)
- [证书准备典型问题](references/5-问题排查/证书准备典型问题.md)
- [签约代扣典型问题](references/5-问题排查/签约代扣典型问题.md)

### 7. 质量评估与排障

用户准备联调、测试、上线，或已经出现报错时：

- 只检查当前实际使用的模块。
- 不以客户端回调当作最终交易结果。
- 验签失败、幂等缺失、沙盒标识未清理属于高优先级问题。
- 若服务端返回 `resultDesc` 这类字段校验报错，优先核对字段契约，而不是先怀疑 Payment Kit 拉起逻辑。

**现网典型问题集入口**（v1.8.0 新增）：

- 基础支付排障：[支付常见问题](references/5-问题排查/支付常见问题.md)（含 TP-PAY-001~014）
- 退款排障：[退款典型问题](references/5-问题排查/退款典型问题.md)（含 TP-REF-001~007）
- 签约代扣排障：[签约代扣典型问题](references/5-问题排查/签约代扣典型问题.md)（含 TP-WTH-001~006）
- 账单查询排障：[账单查询典型问题](references/5-问题排查/账单查询典型问题.md)（含 TP-BILL-001~006）
- 子商户进件排障：[子商户进件典型问题](references/5-问题排查/子商户进件典型问题.md)（含 TP-SUB-001~006）
- 证书准备排障：[证书准备典型问题](references/5-问题排查/证书准备典型问题.md)（含 TP-CERT-001~007）
- 签名验签排障：[签名与验签常见问题](references/5-问题排查/签名与验签常见问题.md)（含 TP-SIGN-001~007）
- 回调通知排障：[回调与幂等常见问题](references/5-问题排查/回调与幂等常见问题.md)（含 TP-CB-001~009）
- 错误码速查（含典型错误码→原因→解决映射）：[错误码速查](references/5-问题排查/错误码速查.md)

## 硬性红线

- 私钥不得出现在客户端代码、日志、公共仓库或对话明文示例中。
- 不得跳过回调验签，不得在验签失败时更新订单状态。
- 不得把 `paymentService` 或 Payment Kit 虚构成三方依赖安装包。
- 不得建议客户端 Mock `orderStr` 或 `contractStr`。
- 不得把标准 App API 和 ASCF API 混写。
- 不得把客户端回调结果作为最终支付或签约成功依据。
- 不得在未确认服务端字段契约前，擅自将页面字段名直接映射为预下单请求字段。
- 不得在官方 SDK 不可验证时，伪造 SDK 直连实现、虚构类名、配置对象或方法签名。
- 不得在新增 Maven 依赖尚未验证可解析前，就先写入依赖耦合实现或提交带有未解析 `import` 的源码。
- 不得把 `README`、`target/`、`build/`、metadata 中出现的类或配置直接当作当前源码事实。
- 不得把 `MOCK` 验签、内存幂等、样例签名工具包装成“可直接上线的生产实现”。

## 输出建议模板

```markdown
## 结论
[一句话说明当前是否可接入、可联调、已定位问题或存在阻塞]

## 执行清单
- 已完成：
  - [item]
- 待完成：
  - [item]

## 风险与阻塞
- [风险项]

## 下一步
1. [最小可执行动作]
2. [下一步验证动作]
```

## 顶层入口

- 参考索引：[reference.md](references/reference.md)
- 示例索引：[examples.md](assets/examples.md)