更新记录

1.0.0（2026-07-30）

支持 鸿蒙应用内购

平台兼容性

uni-app(5.08)

uni-app x(5.08)

tt-harmony-iap

基于 HarmonyOS IAP Kit 的应用内支付插件，为 uni-app 和 uni-app x 提供 HarmonyOS 平台的商品查询、购买、权益查询、主动补单和确认交付能力。

首发优惠

插件按累计付费用户数阶梯定价，普通授权和源码授权统一计入累计人数。已购买用户不受后续调价影响，实际成交价以插件市场页面显示为准。

接入准备

1. 在 AppGallery Connect 中开通应用内支付服务。
2. 创建商品，并配置商品类型、价格和描述。
3. 确认应用包名、签名和 AppGallery Connect 中的应用信息一致。
4. 配置华为沙箱测试账号，并使用真机联调。
5. 在 Harmony 工程中集成 IAP Kit。

Harmony 工程配置

当前示例项目提供了项目级配置文件：

• harmony-configs/entry/src/main/module.json5

其中包含 IAP 联网所需权限：

{
  "name": "ohos.permission.INTERNET"
}

快速开始

插件只支持 HarmonyOS，业务代码应使用条件编译。

// #ifdef APP-HARMONY
import * as harmonyIapSdk from '@/uni_modules/tt-harmony-iap'

let harmonyIap: harmonyIapSdk.TTHarmonyIap | null = null

onReady(() => {
    harmonyIap = harmonyIapSdk.getTTHarmonyIap()
})
// #endif

所有接口均使用 success、fail、complete 回调并返回 void：

API

getTTHarmonyIap

获取插件单例。

const harmonyIap = harmonyIapSdk.getTTHarmonyIap()

queryEnvironmentStatus

检查当前设备、华为账号及账号服务地区是否支持 IAP。检查成功时 supported 为 true；不支持或检查失败时进入 fail，不会返回 supported: false。

harmonyIap?.queryEnvironmentStatus({
    success: (result) => {
        console.log('IAP supported', result.supported)
    },
    fail: (error) => {
        console.log(error.errCode, error.errMsg)
    }
})

成功结果 TTHarmonyIapEnvironmentResult：

queryProducts

查询 AppGallery Connect 中配置的商品信息。同一次调用中的 productIds 不能为空、不能包含空字符串且不能重复。

harmonyIap?.queryProducts({
    type: 'consumable',
    productIds: ['coin_001', 'coin_002'],
    success: (products) => {
        console.log(products)
    },
    fail: (error) => {
        console.log(error.errMsg)
    }
})

商品 TTHarmonyIapProduct：

createPurchase

创建订单并拉起 HarmonyOS IAP 支付界面。

harmonyIap?.createPurchase({
    type: 'consumable',
    productId: 'coin_001',
    developerPayload: 'order_123',
    success: (purchase) => {
        // 将完整 purchase.purchaseData 上传到服务端验签和校验。
        console.log(purchase.purchaseOrderId)
    },
    fail: (error) => {
        console.log(error.errMsg)
    }
})

购买结果 TTHarmonyIapPurchase：

插件始终返回完整 purchaseData。某条 JWS 无法解析时，对应解析字段为 null 并写入 parseWarnings，不会阻断同批次的其他订单。

queryPurchases

查询当前有效权益。只支持非消耗型商品和自动续订商品。插件会自动读取全部分页。

harmonyIap?.queryPurchases({
    type: 'non_consumable',
    success: (purchases) => {
        console.log(purchases)
    },
    fail: (error) => {
        console.log(error.errMsg)
    }
})

该接口不是历史订单查询：非消耗型商品返回当前拥有的权益，自动续订商品返回当前有效的订阅。

queryUnfinishedPurchases

查询已购买但尚未完成交付的订单。支持四种商品类型，并自动跟随 continuationToken 读取全部分页。建议在登录成功、应用启动和回到前台时调用，用于主动补单。

harmonyIap?.queryUnfinishedPurchases({
    type: 'consumable',
    success: (purchases) => {
        console.log('unfinished purchases', purchases)
    },
    fail: (error) => {
        console.log(error.errMsg)
    }
})

queryPurchaseHistory

使用官方 ALL 查询指定商品类型的历史购买记录，并自动读取全部分页。历史记录用于订单展示和诊断，不能替代 queryUnfinishedPurchases 补单。

harmonyIap?.queryPurchaseHistory({
    type: 'consumable',
    success: (purchases) => {
        console.log(purchases)
    }
})

finishPurchase

服务端完成验签、订单校验和业务交付后，确认该笔购买已处理。不要在客户端购买回调中直接调用。

function finishVerifiedPurchase(purchase: harmonyIapSdk.TTHarmonyIapPurchase): void {
    if (purchase.purchaseToken == null || purchase.purchaseOrderId == null) {
        return
    }
    harmonyIap?.finishPurchase({
        type: purchase.type,
        purchaseToken: purchase.purchaseToken,
        purchaseOrderId: purchase.purchaseOrderId,
        success: () => {
            console.log('finish success')
        },
        fail: (error) => {
            console.log(error.errMsg)
        }
    })
}

needFinish 为 true 时必须确认交付；为 false 时确认交付是可选操作。无论取值如何，都应先完成服务端验签和业务侧幂等交付。

管理与辅助接口

以下接口对外仍使用回调。由于 Harmony IAP Kit 只为这些能力提供 Promise 版本，插件仅在各自内部进行适配。

harmonyIap?.showManagedSubscriptions({
    windowScreenMode: 'fullscreen',
    fail: (error) => {
        console.log(error.errCode, error.errMsg)
    }
})

这些接口受 HarmonyOS 版本和设备能力限制。不支持时会通过 fail 透传官方 801 等错误码，其中发票管理要求 SystemCapability.Payment.IAP.Extension。

自动续订状态

自动续订购买结果可能包含 subscriptionStatus：

续费计划 renewalInfo：

这些字段只是客户端解码结果。订阅是否有效、是否续费以及最终权益期限必须以服务端验签和业务记录为准。

错误处理

失败回调收到 TTHarmonyIapFail：

插件错误码：

其他错误码由 Harmony IAP Kit 返回，例如账号未登录、服务地区不支持、用户取消支付或商品配置错误。业务侧应保留原始 errCode，不要只根据错误文案判断。

安全、交付与补单

推荐业务流程：

1. 调用 queryEnvironmentStatus 检查支付环境。
2. 调用 queryProducts 获取商品和本地化价格。
3. 调用 createPurchase 拉起支付。
4. 将完整 purchaseData 和当前业务用户标识上传到服务端。
5. 服务端验证 JWS 签名，并校验应用、商品、金额、币种、用户和订单状态。
6. 服务端以 purchaseOrderId 做幂等交付，避免重复发货或重复开通权益。
7. 业务交付成功后，再调用 finishPurchase。
8. 在应用启动、登录成功和回到前台时调用 queryUnfinishedPurchases 主动补单，并重复服务端校验和幂等交付流程。

插件只解码 orderPayload 和 subscriptionStatus，不校验 JWS 签名。这些客户端解析结果不能替代服务端验签。验签失败、商品不匹配、订单已处理或用户关系不正确时，不应交付，也不应调用 finishPurchase。

常见问题

为什么购买成功后不能立即 finishPurchase？

购买成功只表示客户端拿到了购买结果，不代表订单已通过服务端验签或业务交付已完成。过早确认会导致订单无法再通过未完成订单查询补回。

queryUnfinishedPurchases 是历史订单查询吗？

不是。它只查询已购买但尚未交付的订单，并自动拉取全部分页。

查询商品或购买失败时先检查什么？

• AppGallery Connect 是否已开通 IAP，商品是否生效
• 商品 ID 和商品类型是否与平台配置一致
• 应用包名和签名是否匹配
• 真机是否登录可用的华为账号或沙箱账号
• 当前账号服务地区是否支持 IAP
• 是否已调用 queryEnvironmentStatus

参考资料

• HarmonyOS IAP Kit 接入指南
• HarmonyOS IAP 返回结果验签
• 华为应用内支付服务