Harmonyos Iap Integration

HarmonyOS IAP Kit 应用内支付接入技能

技能目标

为开发者提供一套可直接执行的HarmonyOS IAP Kit应用内支付接入流程，帮助快速完成从联调到上线的闭环。

覆盖能力：

• 消耗型商品购买： 例如游戏币、钻石、体力等
• 非消耗型商品购买：例如去广告、额外关卡、永久解锁等
• 自动续期订阅商品购买：例如月度VIP、年度会员、连续包月、连续包季、连续包年等
• 非续期订阅商品购买：例如季卡、月卡、年卡、一个月会员等

何时使用

当用户要做以下任一任务时启用本skill：

• 设计或实现华为鸿蒙应用内支付（HarmonyOS IAP Kit）
• 需要在鸿蒙应用中实现付费功能
• 排查掉单、重复发货、补单、订阅状态异常
• 制定沙盒联调和生产上线清单

交互策略

当用户请求接入IAP Kit时：

1. 完整了解项目情况: 识别商品等IAP接入相关的关键信息
2. 先从当前项目识别需要的商品类型，无法识别时询问商品类型（多选）：消耗型/非消耗型/自动续期订阅/非自动续期订阅
3. 先从当前项目识别需要的服务端语言，无法识别服务端语言时询问服务端语言：Java/Python/Node.js/PHP/Golang
4. 【强制】严格按照标准流程执行，必须逐项检查每个环节是否已实现：数字商品购买标准流程7个环节、数字商品补单标准流程4个环节、关键事件通知标准流程5个通知类型
5. 按需提供代码：从references目录中读取对应的数据结构和demo代码，代码可以复用，TODO需要继续实现
6. 【强制】代码规范检查：使用强类型DTO而非Map、JsonNode等弱类型（防止字段名拼写错误）
7. 【强制】实现完成后，必须使用标准流程检查每个环节都已实现

生成代码或方案时的输出要求

• 客户端优先贴近官方ArkTS demo（references目录中）的结构和API命名
• 服务端优先贴近用户指定语言的官方demo（references目录中）
• 【重要】客户端和服务端使用的数据结构优先从references/client-arkts.md中查找

前置准备

1. 开启和激活应用内购买服务
2. 配置module.json5添加client_id
3. 在商品管理系统中配置商品并上架（状态必须为在线）
4. 配置手动签名（不能用自动签名），指导文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-signing#section297715173233

标准流程（必须严格遵守）

数字商品购买标准流程（必须完整实现所有环节）

环境检测（queryEnvironmentStatus） → 查询商品信息（queryProducts） → 服务器预下单 → 发起购买，拉起收银台（createPurchase） -> 上报PurchaseData → 服务器验签发放权益 → 端侧确认发货（finishPurchase）                                                                                                 

数字商品补单标准流程（必须完整实现所有环节）

查询已购但未确认发货的订单/订阅列表（queryPurchases） -> 上报PurchaseData → 服务器验签发放权益 → 端侧确认发货（finishPurchase）                                                                                                 

关键事件通知标准流程（必须完整实现所有环节）

IAP服务器发送订单/订阅关键事件通知 -> 根据不同的通知类型处理相关的业务逻辑 -> 根据业务处理结果返回响应                                                                                      

通知请求体样例：{"jwsNotification":"xxx"}

核心数据结构说明

1. 消耗型/非消耗型/非续期订阅商品走订单流程，状态数据结构为PurchaseOrderPayload，具体结构参考references/client-arkts.md
2. 自动续期订阅商品走订阅流程，状态数据结构为SubGroupStatusPayload，具体结构参考references/client-arkts.md

最佳实践

服务器预下单处理建议

1. 初始化业务订单并落库，业务订单建议包含应用账号、商品ID、价格、币种等字段
2. 返回订单号

发起购买，拉起收银台（createPurchase）处理建议

developerPayload使用预下单中返回的值

上报PurchaseData处理建议

1. 直接传递createPurchase/queryPurchases返回的purchaseData JSON字符串
2. purchaseData数据结构参考references/client-arkts.md 中的PurchaseData结构

服务器验签发放权益处理建议

1. 区分商品类型处理，对相应的jws状态数据进行验签并解码出对应的状态数据
2. 已经退款的订单不需要发放权益，条件为purchaseOrderRevocationReasonCode不为空
3. 已经发放过权益的订单不需要处理，防止重复发放权益
4. 根据developerPayload查询业务订单，根据订单信息中的用户账号和商品ID发放权益

数字商品补单标准流程

1. 应用启动时：始终查询未完成的购买。
2. 购买返回PRODUCT_OWNED或SYSTEM_ERROR时：表示存在未完成的购买

关键事件通知处理建议

1. DID_NEW_TRANSACTION通知处理建议：

区分商品类型查询最新状态信息 -> 验签并解码对应的jws数据 -> 判断是否需要发放权益 -> 根据developerPayload查询业务订单 -> 根据用户账号和商品ID发放权益 -> 区分商品类型调用IAP服务器确认发货接口

2. REVOKE通知处理建议：

区分商品类型查询最新状态信息 -> 验签并解码对应的jws数据 -> 判断是否需要回收权益 -> 根据developerPayload查询业务订单 -> 根据用户账号和商品ID回收业务订单对应的权益

判断是否需要发放权益的处理建议

1. 已经退款的订单不需要发放权益，条件为purchaseOrderRevocationReasonCode不为空
2. 已经发放过权益的订单不需要处理，防止重复发放权益

回收权益的处理建议

1. 回收业务订单中对应商品的权益，而非全部权益
2. 例如商品权益对应1个月会员，则回收一个月会员

常见错误码

输出模板

所有回复使用以下结构：

## 结论
[一句话说明当前是否可接入/可发布/已定位问题]

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

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

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

参考资源（不要参考官方文档以外的文档）

• 开发指南：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/iap-kit-guide
• API参考-端：https://developer.huawei.com/consumer/cn/doc/harmonyos-references/iap-arkts
• API参考-云：https://developer.huawei.com/consumer/cn/doc/harmonyos-references/iap-rest
• 官方demo-端：https://gitcode.com/HarmonyOS_Samples/iapkit-sample-clientdemo-arkts
• 官方demo-云：https://gitcode.com/HarmonyOS_Samples/iapkit-sample-serverdemo