SuperAPI AI Directory

harmonyos-iap-integration

Coding & development

View repository

Updated 10-15 21:07

About this skill

HarmonyOS IAP Kit In-App Purchases Integration Skill

Skill Objective

Provide developers with a directly executable HarmonyOS IAP Kit in-app purchases integration process to help quickly complete the closed loop from joint debugging to launch.

Covered capabilities:

  • Consumable product purchase: e.g., game coins, diamonds, stamina, etc.
  • Non-consumable product purchase: e.g., ad removal, extra levels, permanent unlock, etc.
  • Auto-renewable subscription product purchase: e.g., monthly VIP, annual membership, continuous monthly, continuous quarterly, continuous yearly, etc.
  • Non-renewing subscription product purchase: e.g., quarterly card, monthly card, yearly card, one-month membership, etc.

When to Use

Enable this skill when the user wants to perform any of the following tasks:

  • Design or implement Huawei HarmonyOS in-app purchases (HarmonyOS IAP Kit)
  • Need to implement paid features in a HarmonyOS app
  • Troubleshoot lost orders, duplicate delivery, order replenishment, abnormal subscription status
  • Create a sandbox joint debugging and production launch checklist

Interaction Strategy

When the user requests integration with IAP Kit:

  1. Fully understand the project situation: Identify key information related to IAP integration such as products
  2. First identify the required product types from the current project; if unable to identify, ask for the product types (multiple choice): Consumable/non-consumable/auto-renewable subscription/non-auto-renewable subscription
  3. First identify the required server-side language from the current project; if unable to identify the server-side language, ask for the server-side language:Java/Python/Node.js/PHP/Golang
  4. [Mandatory] Strictly follow the standard process, and must check item by item whether each step has been implemented: 7 steps of the standard digital product purchase process, 4 steps of the standard digital product order replenishment process, 5 notification types of the standard key event notification process
  5. Provide code as needed: Read the corresponding data structures and demo code from the references directory; the code can be reused, and TODOs need to be further implemented
  6. [Mandatory] Code specification check: Use strongly typed DTOs instead of weak types such as Map, JsonNode (to prevent field name spelling errors)
  7. [Mandatory] After implementation is complete, must use the standard process to check that each step has been implemented

Output requirements when generating code or solutions

  • The client side should preferably stay close to the structure and API naming of the official ArkTS demo (in the references directory)
  • The server side should preferably stay close to the official demo in the user-specified language (in the references directory)
  • [Important] The data structures used by the client and server should preferably be found fromreferences/client-arkts.mdSearch in

Prerequisites

  1. Enable and activate the in-app purchase service
  2. Configuremodule.json5Addclient_id
  3. Configure products in the product management system and put them on sale (status must be online)
  4. Configure manual signing (automatic signing cannot be used), guidance document:https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-signing#section297715173233

Standard Process (Must Be Strictly Followed)

Standard digital product purchase process (must fully implement all steps)

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

Standard digital product order replenishment process (must fully implement all steps)

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

Standard Process for Key Event Notification (All steps must be fully implemented)

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

Notification Request Body Example:{"jwsNotification":"xxx"}

Core Data Structure Description

  1. Consumable/non-consumable/non-renewing subscription products follow the order process, and the status data structure is PurchaseOrderPayload. For the specific structure, refer toreferences/client-arkts.md
  2. Auto-renewable subscription products follow the subscription process, and the status data structure is SubGroupStatusPayload. For the specific structure, refer toreferences/client-arkts.md

Best Practices

Recommendations for Server-Side Pre-order Processing

  1. Initialize the business order and persist it to the database. The business order is recommended to include fields such as app account, product ID, price, and currency
  2. Return the order number

Recommendations for Initiating Purchase and Bringing Up the Checkout Page (createPurchase)

Use the value returned in the pre-order for developerPayload

Recommendations for Reporting PurchaseData

  1. Directly pass the purchaseData JSON string returned by createPurchase/queryPurchases
  2. PurchaseData Data Structure Referencereferences/client-arkts.md PurchaseData structure in

Recommendations for Server-Side Signature Verification and Entitlement Granting

  1. Handle by distinguishing product types, verify the signature of the corresponding jws status data, and decode the corresponding status data
  2. Orders that have already been refunded do not need entitlements to be granted. The condition is that purchaseOrderRevocationReasonCode is not empty
  3. Orders for which entitlements have already been granted do not need to be processed, to prevent duplicate entitlement granting
  4. Query the business order based on developerPayload, and grant entitlements based on the user account and product ID in the order information

Standard Process for Digital Product Order Supplements

  1. When the app starts: Always query for unfinished purchases.
  2. When purchase returnsPRODUCT_OWNEDorSYSTEM_ERRORwhen: Indicates that there is an unfinished purchase

Recommendations for Handling Key Event Notifications

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

Recommendations for Determining Whether Entitlements Need to Be Granted

  1. Orders that have already been refunded do not need entitlements to be granted. The condition is that purchaseOrderRevocationReasonCode is not empty
  2. Orders for which entitlements have already been granted do not need to be processed, to prevent duplicate entitlement granting

Recommendations for Handling Entitlement Revocation

  1. Revoke the entitlement for the corresponding product in the business order, not all entitlements
  2. For example, if the product entitlement corresponds to 1 month of membership, then revoke one month of membership

Common Error Codes

Error Code Meaning Solution
1001860001 Internal system error If the purchase request returns this error code, it is recommended to use the queryPurchases API to confirm whether the user has purchased but not yet been granted entitlements for a product, and grant the entitlements promptly
1001860002 The app is not authorized to access the API 1. Check the app signature/identity information configuration. 2. Check whether the app's payment service switch is turned on.
1001860003 Invalid product information Please log in to the AppGallery Connect website, select "My apps > Operations > Product management > Product list", and check whether the corresponding product exists, whether the required information is complete, and whether the product information has been submitted for review and approved. If it has not been approved, you can use a sandbox account to test
1001860004 API access too frequent Please control the API call frequency. The current default API access interval is 5s. In the future, IAP Kit may lower or increase the rate limit as needed
1001860005 Network connection abnormal The app prompts the user to check the network
1001860007 The app to which the product belongs is not available in the specified country/region Please log in to the AppGallery Connect website, select "My apps > Distribution > Version information > Prepare for submission", and check the country/region configured for the product.
1001860050 Not logged in to a HUAWEI Account Guide the user to log in to a HUAWEI Account
1001860051 Product already owned Query incomplete purchases and complete shipment confirmation
1001860052 Shipment failed because the product is not owned You can use the queryPurchases API to confirm whether the user has purchased the product
1001860053 Shipment for this purchase has already been completed; no need to ship again You can use the queryPurchases API to query whether there is a shipment confirmation record for the product
1001860054 The service location of the user account is not in a country/region where IAP Kit supports settlement The user account service location is outside mainland China (excluding Hong Kong SAR, Macao SAR, and Taiwan, China). It is recommended that the app hide the relevant IAP feature entry.
1001860056 User transaction rejected It is recommended to try again later or change the payment method
1001860057 The current app is not a debug-signed app Build a debug-signed app
1001860058 The logged-in HUAWEI Account is not a configured test account You need to add a test account in "Users and access" in AppGallery Connect

Output template

Use the following structure for all replies:

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

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

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

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

Reference resources (do not reference documents other than official documents)