目录

IAP

The In-App Purchase (IAP) module provides full-link payment capabilities of digital products (virtual products) for HarmonyOS apps, including product query, purchase, delivery confirmation, subscription management, and refund.

This module can be integrated when your app needs to sell virtual products (such as game items and memberships) or provide subscription services for users. Before initiating a product query or purchase, you are advised to call iap.queryEnvironmentStatus to check whether the IAP service is supported in the region where the current user account is located. This helps prevent exceptions in subsequent processes.

You can use this module to implement the following features:

Model restriction: APIs of this module can be used only in the stage model.

Since: 4.0.0(10)

Modules to Import

import { iap } from '@kit.IAPKit';

ProductType

Product type.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Name Value Description
CONSUMABLE 0

Consumable.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
NONCONSUMABLE 1

Non-consumable.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
AUTORENEWABLE 2

Auto-renewable subscription.

This product type is not supported for wearables.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

Since: 4.1.0(11)
NONRENEWABLE 3

Non-renewable subscription.

This product type is not supported for wearables.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

Since: 5.0.2(14)

PurchaseQueryType

Type of purchase data to be queried.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Name Value Description
ALL 0 All purchase records, including consumables, non-consumables, auto-renewable subscriptions, and non-renewable subscriptions.
UNFINISHED 1 Consumables, non-consumables, auto-renewable subscriptions, and non-renewable subscriptions that have been purchased but not delivered.
CURRENT_ENTITLEMENT 2 Non-consumables that have been purchased and subscriptions that are currently active.

PeriodUnit

Billing cycle unit of a subscription.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Name Value Description
DAY 0 Day.
WEEK 1 Week.
MONTH 2 Month.
YEAR 3 Year.
MINUTE 4 Minute. (Reserved parameter, which is not supported currently.)

OfferPaymentMode

Payment method for a promotion.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Name Value Description
FREE_TRIAL 1

Free trial.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
PAY_AS_YOU_GO 2

Pay-as-you-go.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
PAY_UP_FRONT 3

Upfront payment.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
SINGLE_PROMOTION 5

Single-use promotion, applicable only to consumables, non-consumables, and non-renewable subscriptions.

Atomic service API: This API can be used in atomic services since API version 5.0.5(17).

Since: 5.0.5(17)

OfferType

Promotion type.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Name Value Description
INTRODUCTORY 0 Introductory offer.
PROMOTIONAL 1 Promotional offer.

IAPErrorCode

Enumeration of error codes.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Name Value Description
USER_CANCELED 1001860000

The user canceled the current operation.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
SYSTEM_ERROR 1001860001

Internal system error.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
APP_NOT_AUTHORIZED 1001860002

The app is not authorized to call the API.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
INVALID_PRODUCT 1001860003

Invalid product information.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
FREQUENT_CALLS 1001860004

The API is called too frequently.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
NETWORK_ERROR 1001860005

Network connection error.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
PRODUCT_TERRITORY_NOT_SUPPORTED 1001860007

The product's associated app is not available in the specified country/region.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
ACCOUNT_NOT_LOGGED_IN 1001860050

The user has not signed in to a HUAWEI ID.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
PRODUCT_OWNED 1001860051

The purchase failed because the user already owns the product.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
PURCHASE_NOT_PAID 1001860052

The delivery failed because the user does not own the product.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
PURCHASE_FINISHED 1001860053

The product has been delivered. No more delivery is needed.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
ACCOUNT_TERRITORY_NOT_SUPPORTED 1001860054

The country or region of the signed-in HUAWEI ID does not support IAP.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
USER_NOT_ALLOWED 1001860056

The user's transaction was declined.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
APP_NOT_DEBUG 1001860057

The app is not signed with a debug certificate.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

Since: 5.0.0(12)
ACCOUNT_NOT_TEST 1001860058

The HUAWEI ID is not a sandbox test account.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

Since: 5.0.0(12)
INVALID_PROMOTIONAL_OFFER 1001860059

Invalid promotional offer information.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

Since: 5.0.0(12)
INVALID_PURCHASE_SIGNATURE 1001860060

Invalid signature information.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

Since: 5.0.0(12)
PURCHASE_ALREADY_REFUNDED 1001860061

The product has been refunded or is being refunded.

Atomic service API: This API can be used in atomic services since API version 5.0.3(15).

Since: 5.0.3(15)
REFUND_NOT_ALLOWED 1001860062

Refund is not allowed.

Atomic service API: This API can be used in atomic services since API version 5.0.3(15).

Since: 5.0.3(15)
PURCHASE_NOT_FOUND 1001860064

The order cannot be found under the signed-in HUAWEI ID.

Atomic service API: This API can be used in atomic services since API version 6.1.0(23).

Since: 6.1.0(23)
OPERATION_NOT_SUPPORTED 1001860065

Invoice issuance is not supported.

Atomic service API: This API can be used in atomic services since API version 6.1.0(23).

Since: 6.1.0(23)

WindowScreenMode

UI window mode.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 5.0.0(12)

Name Value Description
DIALOG_BOX 1 Pop-up.
FULLSCREEN 2 Full-screen.

ProductStatus

Enumeration of product statuses.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 5.0.0(12)

Name Value Description
VALID 0 Valid.
CANCELED 1 Canceled, that is, deleted. Products in this status cannot be renewed or subscribed to.
OFFLINE 3 Offline. New subscriptions are not allowed, but existing users may continue to renew.

iap.queryEnvironmentStatus

queryEnvironmentStatus(context: common.Context): Promise<void>

Checks whether the signed-in account is located in a country or region where IAP is available. Currently, this API is available only in the Chinese mainland.

This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.Context Yes Context. UIAbilityContext is recommended.

Returns

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860000 The operation was canceled by the user.
1001860001 System internal error.
1001860002

The application is not authorized.

Applicable versions: 5.0.0(12)+
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860050 The HUAWEI ID is not signed in.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        iap.queryEnvironmentStatus(this.getUIContext().getHostContext() as common.UIAbilityContext).then(() => {
            // The request succeeded.
            console.info('Succeeded in querying environment status.');
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to query environment status. Code is ${err.code}, message is ${err.message}`);
        });
    }

    build() {}
}

iap.queryEnvironmentStatus

queryEnvironmentStatus(context: common.Context, callback: AsyncCallback<void>): void

Checks whether the signed-in account is located in a country or region where IAP is available. Currently, this API is available only in the Chinese mainland.

This API returns the result asynchronously through a callback.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.Context Yes Context. UIAbilityContext is recommended.
callback AsyncCallback<void> Yes Callback function. If the signed-in HUAWEI ID is from a country or region supported by IAP, err is undefined; otherwise, an error object will be returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860000 The operation was canceled by the user.
1001860001 System internal error.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860050 The HUAWEI ID is not signed in.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        iap.queryEnvironmentStatus(this.getUIContext().getHostContext() as common.UIAbilityContext, (err: BusinessError) => {
            if (err) {
                // The request failed.
                console.error(`Failed to query environment status. Code is ${err.code}, message is ${err.message}`);
                return;
            }
            // The request succeeded.
            console.info('Succeeded in querying environment status.');
        });
    }

    build() {}
}

iap.queryProducts

queryProducts(context: common.UIAbilityContext, parameter: QueryProductsParameter): Promise<Array<Product>>

Obtains the product details configured in AppGallery Connect. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter QueryProductsParameter Yes QueryProductsParameter object, which contains the request information.

Returns

Type Description
Promise<Array<Product>> Promise object, which contains product details.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860001 System internal error.
1001860002 The application is not authorized.
1001860003 Invalid product information.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860007 The app to which the product belongs is not released in a specified location.
1001860050 The HUAWEI ID is not signed in.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.QueryProductsParameter = {
            // iap.ProductType.CONSUMABLE: consumable
            // iap.ProductType.NONCONSUMABLE: non-consumable
            // iap.ProductType.AUTORENEWABLE: auto-renewable subscription
            // iap.ProductType.NONRENEWABLE: non-renewable subscription
            productType: iap.ProductType.CONSUMABLE,
            // Use IDs of the products you configured in AppGallery Connect as the values of productIds.
            productIds: ['testConsumeProduct01', 'testConsumeProduct02']
        }
        iap.queryProducts(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter).then((data: Array<iap.Product>) => {
            // The request succeeded.
            console.info(`Succeeded in querying products. data length: ${data?.length}`);
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to query products. Code is ${err.code}, message is ${err.message}`);
        });
    }

    build() {}
}

iap.queryProducts

queryProducts(context: common.UIAbilityContext, parameter: QueryProductsParameter, callback: AsyncCallback<Array<Product>>): void

Obtains the product details configured in AppGallery Connect. This API returns the result asynchronously through a callback.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter QueryProductsParameter Yes QueryProductsParameter object, which contains the request information.
callback AsyncCallback<Array<Product>> Yes Callback function. If the query succeeds, err is undefined and data is the obtained Array<Product>; otherwise, an error object will be returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860001 System internal error.
1001860002 The application is not authorized.
1001860003 Invalid product information.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860007 The app to which the product belongs is not released in a specified location.
1001860050 The HUAWEI ID is not signed in.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.QueryProductsParameter = {
            // iap.ProductType.CONSUMABLE: consumable
            // iap.ProductType.NONCONSUMABLE: non-consumable
            // iap.ProductType.AUTORENEWABLE: auto-renewable subscription
            // iap.ProductType.NONRENEWABLE: non-renewable subscription
            productType: iap.ProductType.CONSUMABLE,
            // Use IDs of the products you configured in AppGallery Connect as the values of productIds.
            productIds: ['testConsumeProduct01', 'testConsumeProduct02']
        }
        iap.queryProducts(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter, (err: BusinessError, data: Array<iap.Product>) => {
            if (err) {
                // The request failed.
                console.error(`Failed to query products. Code is ${err.code}, message is ${err.message}`);
                return;
            }
            // The request succeeded.
            console.info(`Succeeded in querying products. data length: ${data?.length}`);
        });
    }

    build() {}
}

iap.queryProducts

queryProducts(context: common.UIAbilityContext, productIds: string[]): Promise<Array<Product>>

Queries the product details configured in AppGallery Connect. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 6.0.0(20).

System capability: SystemCapability.Payment.IAP

Since: 6.0.0(20)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
productIds string[] Yes

ID list of products to be queried. Each product ID must exist and be unique in your app.

The product IDs come from the product information you have configured in AppGallery Connect. For details, please refer to Configuring Products.

Note: A maximum of 200 product IDs can be queried at a time. If you need to query more items, it is recommended to split the requests into batches.

Returns

Type Description
Promise<Array<Product>> Promise object, which contains product details.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860001 System internal error.
1001860002 The application is not authorized.
1001860003 Invalid product information.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860007 The app to which the product belongs is not released in a specified location.
1001860050 The HUAWEI ID is not signed in.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        // Use IDs of the products you configured in AppGallery Connect as the values of productIds.
        const productIds: string[] = ['testConsumeProduct01', 'testConsumeProduct02'];
        iap.queryProducts(this.getUIContext().getHostContext() as common.UIAbilityContext, productIds).then((data: Array<iap.Product>) => {
            // The request succeeded.
            console.info(`Succeeded in querying products. data length: ${data?.length}`);
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to query products. Code is ${err.code}, message is ${err.message}`);
        })
    }

    build() {}
}

iap.purchase(deprecated)

purchase(context: common.UIAbilityContext, parameter: PurchaseParameter): Promise<PurchaseResult>

Creates a purchase order, which supports both consumables and non-consumables. After a user initiates a purchase for a product already configured in AppGallery Connect, this API brings up the checkout screen of IAP to show the product name, price, and payment methods.

This API uses a promise to return the result.

Deprecation notice: This API is deprecated since API version 4.1.0(11). You are advised to use createPurchase instead.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 1001860001.

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter PurchaseParameter Yes PurchaseParameter object, which contains the request information.

Returns

Type Description
Promise<PurchaseResult> Promise object, which contains the purchase result.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
1001860000 The operation was canceled by the user.
1001860001 System internal error.
1001860002 The application is not authorized.
1001860003 Invalid product information.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860007 The app to which the product belongs is not released in a specified location.
1001860051 Failed to purchase a product because the user already owns the product.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.
1001860056 The user is not allowed to make purchase.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.PurchaseParameter = {
            // iap.ProductType.CONSUMABLE: consumable
            // iap.ProductType.NONCONSUMABLE: non-consumable
            productType: iap.ProductType.CONSUMABLE,
            // Use the product ID set by you when configuring product information in AppGallery Connect as the value of productId.
            productId: 'testConsumeProduct01',
            developerPayload: 'test developer payload string.'
        }
        iap.purchase(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter).then((data: iap.PurchaseResult) => {
            // The request succeeded.
            console.info(`Succeeded in purchasing. data: ${data.inAppPurchaseData}`);
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to purchase. Code is ${err.code}, message is ${err.message}`);
        });
    }

    build() {}
}

iap.purchase(deprecated)

purchase(context: common.UIAbilityContext, parameter: PurchaseParameter, callback: AsyncCallback<PurchaseResult>): void

Creates a purchase order, which supports both consumables and non-consumables. After a user initiates a purchase for a product already configured in AppGallery Connect, this API brings up the checkout screen of IAP to show the product name, price, and payment methods.

This API returns the result asynchronously through a callback.

Deprecation notice: This API is deprecated since API version 4.1.0(11). You are advised to use createPurchase instead.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices, but does not respond on other device types.

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter PurchaseParameter Yes PurchaseParameter object, which contains the request information.
callback AsyncCallback<PurchaseResult> Yes Callback function. If the purchase is successful, err is undefined and data is the obtained PurchaseResult object; otherwise, an error object will be returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
1001860000 The operation was canceled by the user.
1001860001 System internal error.
1001860002 The application is not authorized.
1001860003 Invalid product information.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860007 The app to which the product belongs is not released in a specified location.
1001860051 Failed to purchase a product because the user already owns the product.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.
1001860056 The user is not allowed to make purchase.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.PurchaseParameter = {
            // iap.ProductType.CONSUMABLE: consumable
            // iap.ProductType.NONCONSUMABLE: non-consumable
            productType: iap.ProductType.CONSUMABLE,
            // Use the product ID set by you when configuring product information in AppGallery Connect as the value of productId.
            productId: 'testConsumeProduct01',
            developerPayload: 'test developer payload string.'
        }
        iap.purchase(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter, (err: BusinessError, data: iap.PurchaseResult) => {
            if (err) {
                // The request failed.
                console.error(`Failed to purchase. Code is ${err.code}, message is ${err.message}`);
                return;
            }
            // The request succeeded.
            console.info(`Succeeded in purchasing. data: ${data.inAppPurchaseData}`);
        });
    }

    build() {}
}

iap.createPurchase

createPurchase(context: common.UIAbilityContext, parameter: PurchaseParameter): Promise<CreatePurchaseResult>

Initiates a purchase. Consumables, non-consumables, auto-renewable subscriptions, and non-renewable subscriptions are supported. After a user initiates a purchase for a product already configured in AppGallery Connect, this API brings up the checkout screen of IAP to show information such as the product name and price.

This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter PurchaseParameter Yes PurchaseParameter object, which contains the request information.

Returns

Type Description
Promise<CreatePurchaseResult> Promise object, which contains the purchase result.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860000 The operation was canceled by the user.
1001860001 System internal error.
1001860002 The application is not authorized.
1001860003 Invalid product information.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860007 The app to which the product belongs is not released in a specified location.
1001860051 Failed to purchase a product because the user already owns the product.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.
1001860056 The user is not allowed to make purchase.
1001860059

Invalid promotional offer id.

Applicable versions: 5.0.0(12)+
1001860060

Invalid purchase signature.

Applicable versions: 5.0.0(12)+

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.PurchaseParameter = {
            // iap.ProductType.CONSUMABLE: consumable
            // iap.ProductType.NONCONSUMABLE: non-consumable
            // iap.ProductType.AUTORENEWABLE: auto-renewable subscription
            // iap.ProductType.NONRENEWABLE: non-renewable subscription
            productType: iap.ProductType.AUTORENEWABLE,
            // Use the product ID set by you when configuring product information in AppGallery Connect as the value of productId.
            productId: 'testProduct01',
            developerPayload: 'test developer payload string.'
        }
        iap.createPurchase(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter).then((data: iap.CreatePurchaseResult) => {
            // The request succeeded.
            console.info(`Succeeded in creating purchase. data: ${data.purchaseData}`);
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to create purchase. Code is ${err.code}, message is ${err.message}`);
        });
    }

    build() {}
}

iap.createPurchase

createPurchase(context: common.UIAbilityContext, parameter: PurchaseParameter, callback: AsyncCallback<CreatePurchaseResult>): void

Initiates a purchase. Consumables, non-consumables, auto-renewable subscriptions, and non-renewable subscriptions are supported. After a user initiates a purchase for a product already configured in AppGallery Connect, this API brings up the checkout screen of IAP to show information such as the product name and price.

This API returns the result asynchronously through a callback.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter PurchaseParameter Yes PurchaseParameter object, which contains the request information.
callback AsyncCallback<CreatePurchaseResult> Yes Callback function. If the purchase succeeds, err is undefined and data is the obtained CreatePurchaseResult; otherwise, an error object will be returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860000 The operation was canceled by the user.
1001860001 System internal error.
1001860002 The application is not authorized.
1001860003 Invalid product information.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860007 The app to which the product belongs is not released in a specified location.
1001860051 Failed to purchase a product because the user already owns the product.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.
1001860056 The user is not allowed to make purchase.
1001860059

Invalid promotional offer id.

Applicable versions: 5.0.0(12)+
1001860060

Invalid purchase signature.

Applicable versions: 5.0.0(12)+

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.PurchaseParameter = {
            // iap.ProductType.CONSUMABLE: consumable
            // iap.ProductType.NONCONSUMABLE: non-consumable
            // iap.ProductType.AUTORENEWABLE: auto-renewable subscription
            // iap.ProductType.NONRENEWABLE: non-renewable subscription
            productType: iap.ProductType.AUTORENEWABLE,
            // Use the product ID set by you when configuring product information in AppGallery Connect as the value of productId.
            productId: 'testProduct01',
            developerPayload: 'test developer payload string.'
        }
        iap.createPurchase(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter, (err: BusinessError, data: iap.CreatePurchaseResult) => {
            if (err) {
                // The request failed.
                console.error(`Failed to create purchase. Code is ${err.code}, message is ${err.message}`);
                return;
            }
            // The request succeeded.
            console.info(`Succeeded in creating purchase. data: ${data.purchaseData}`);
        });
    }

    build() {}
}

iap.consumePurchase(deprecated)

consumePurchase(context: common.UIAbilityContext, parameter: ConsumePurchaseParameter): Promise<ConsumeResult>

Consumes a successfully purchased consumable after it is successfully delivered. This API uses a promise to return the result.

Deprecation notice: This API is deprecated since API version 4.1.0(11). You are advised to use finishPurchase instead.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 1001860001.

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter ConsumePurchaseParameter Yes ConsumePurchaseParameter object, which contains the request information.

Returns

Type Description
Promise<ConsumeResult> Promise object, which contains the consumption result.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860007 The app to which the product belongs is not released in a specified location.
1001860050 The HUAWEI ID is not signed in.
1001860052 The purchase cannot be finished because the user has not paid for it.
1001860053 The purchase has been finished and cannot be finished again.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.ConsumePurchaseParameter = {
            purchaseToken: '***',
            developerChallenge: 'developerChallenge'
        }
        iap.consumePurchase(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter).then((data: iap.ConsumeResult) => {
            // The request succeeded.
            console.info(`Succeeded in consuming purchases. data: ${data.consumedPurchaseData}`);
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to consume purchase. Code is ${err.code}, message is ${err.message}`);
        });
    }

    build() {}
}

iap.consumePurchase(deprecated)

consumePurchase(context: common.UIAbilityContext, parameter: ConsumePurchaseParameter, callback: AsyncCallback<ConsumeResult>): void

Consumes a successfully purchased consumable after it is successfully delivered. This API returns the result asynchronously through a callback.

Deprecation notice: This API is deprecated since API version 4.1.0(11). You are advised to use finishPurchase instead.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 1001860001.

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter ConsumePurchaseParameter Yes ConsumePurchaseParameter object, which contains the request information.
callback AsyncCallback<ConsumeResult> Yes Callback function. If the consumption is successful, err is undefined and data is the obtained ConsumeResult object; otherwise, an error object will be returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860007 The app to which the product belongs is not released in a specified location.
1001860050 The HUAWEI ID is not signed in.
1001860052 The purchase cannot be finished because the user has not paid for it.
1001860053 The purchase has been finished and cannot be finished again.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.ConsumePurchaseParameter = {
            purchaseToken: '***',
            developerChallenge: 'developerChallenge'
        }
        iap.consumePurchase(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter, (err: BusinessError, data: iap.ConsumeResult) => {
            if (err) {
                // The request failed.
                console.error(`Failed to consume purchase. Code is ${err.code}, message is ${err.message}`);
                return;
            }
            // The request succeeded.
            console.info(`Succeeded in consuming purchases. data: ${data.consumedPurchaseData}`);
        });
    }

    build() {}
}

iap.finishPurchase

finishPurchase(context: common.UIAbilityContext, parameter: FinishPurchaseParameter): Promise<void>

Acknowledges the delivery of a product to complete the purchase after the product is delivered. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter FinishPurchaseParameter Yes FinishPurchaseParameter object, which contains the request information.

Returns

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860050 The HUAWEI ID is not signed in.
1001860052 The purchase cannot be finished because the user has not paid for it.
1001860053 The purchase has been finished and cannot be finished again.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const finishPurchaseParam: iap.FinishPurchaseParameter = {
            // iap.ProductType.CONSUMABLE: consumable
            // iap.ProductType.NONCONSUMABLE: non-consumable
            // iap.ProductType.AUTORENEWABLE: auto-renewable subscription
            // iap.ProductType.NONRENEWABLE: non-renewable subscription
            productType: iap.ProductType.CONSUMABLE,
            purchaseToken: '***',
            purchaseOrderId: '***'
        };
        iap.finishPurchase(this.getUIContext().getHostContext() as common.UIAbilityContext, finishPurchaseParam).then(() => {
            // The request succeeded.
            console.info('Succeeded in finishing purchase.');
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to finish purchase. Code is ${err.code}, message is ${err.message}`);
        });
    }

    build() {}
}

iap.finishPurchase

finishPurchase(context: common.UIAbilityContext, parameter: FinishPurchaseParameter, callback: AsyncCallback<void>): void

Acknowledges the delivery of a product to complete the purchase after the product is delivered. This API returns the result asynchronously through a callback.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter FinishPurchaseParameter Yes FinishPurchaseParameter object, which contains the request information.
callback AsyncCallback<void> Yes Callback function. If the delivery acknowledgement is complete, err is undefined; otherwise, an error object will be returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860050 The HUAWEI ID is not signed in.
1001860052 The purchase cannot be finished because the user has not paid for it.
1001860053 The purchase has been finished and cannot be finished again.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const finishPurchaseParam: iap.FinishPurchaseParameter = {
            // iap.ProductType.CONSUMABLE: consumable
            // iap.ProductType.NONCONSUMABLE: non-consumable
            // iap.ProductType.AUTORENEWABLE: auto-renewable subscription
            // iap.ProductType.NONRENEWABLE: non-renewable subscription
            productType: iap.ProductType.CONSUMABLE,
            purchaseToken: '***',
            purchaseOrderId: '***'
        };
        iap.finishPurchase(this.getUIContext().getHostContext() as common.UIAbilityContext, finishPurchaseParam, (err: BusinessError) => {
            if (err) {
                // The request failed.
                console.error(`Failed to finish purchase. Code is ${err.code}, message is ${err.message}`);
                return;
            }
            // The request succeeded.
            console.info('Succeeded in finishing purchase.');
        });
    }

    build() {}
}

iap.queryOwnedPurchases(deprecated)

queryOwnedPurchases(context: common.UIAbilityContext, parameter: QueryPurchasesParameter): Promise<QueryPurchasesResult>

Queries data of the purchased products, including consumables and non-consumables. Only one type of products can be queried per API call.

This API uses a promise to return the result.

Deprecation notice: This API is deprecated since API version 4.1.0(11). You are advised to use queryPurchases instead.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 1001860001.

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter QueryPurchasesParameter Yes QueryPurchasesParameter object, which contains the request information.

Returns

Type Description
Promise<QueryPurchasesResult> Promise object, which contains the queried purchase data.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
1001860001 System internal error.
1001860002 The application is not authorized.
1001860003 Invalid product information.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860007 The app to which the product belongs is not released in a specified location.
1001860050 The HUAWEI ID is not signed in.
1001860053 The purchase has been finished and cannot be finished again.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.QueryPurchasesParameter = {
            productType: iap.ProductType.CONSUMABLE
        }
        iap.queryOwnedPurchases(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter).then((data: iap.QueryPurchasesResult) => {
            // The request succeeded.
            console.info(`Succeeded in querying owned purchases. data len: ${data.productList?.length}`);
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to query owned purchases. Code is ${err.code}, message is ${err.message}`);
        });
    }

    build() {}
}

iap.queryOwnedPurchases(deprecated)

queryOwnedPurchases(context: common.UIAbilityContext, parameter: QueryPurchasesParameter, callback: AsyncCallback<QueryPurchasesResult>): void

Queries data of the purchased products, including consumables and non-consumables. Only one type of products can be queried per API call.

This API returns the result asynchronously through a callback.

Deprecation notice: This API is deprecated since API version 4.1.0(11). You are advised to use queryPurchases instead.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 1001860001.

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter QueryPurchasesParameter Yes QueryPurchasesParameter object, which contains the request information.
callback AsyncCallback<QueryPurchasesResult> Yes Callback function. If the query is successful, err is undefined and data is the obtained QueryPurchasesResult object; otherwise, an error object will be returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
1001860001 System internal error.
1001860002 The application is not authorized.
1001860003 Invalid product information.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860007 The app to which the product belongs is not released in a specified location.
1001860050 The HUAWEI ID is not signed in.
1001860053 The purchase has been finished and cannot be finished again.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.QueryPurchasesParameter = {
            productType: iap.ProductType.CONSUMABLE
        }
        iap.queryOwnedPurchases(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter, (err: BusinessError, data: iap.QueryPurchasesResult) => {
            if (err) {
                // The request failed.
                console.error(`Failed to query owned purchases. Code is ${err.code}, message is ${err.message}`);
                return;
            }
            // The request succeeded.
            console.info(`Succeeded in querying owned purchases. data len: ${data.productList?.length}`);
        });
    }

    build() {}
}

iap.queryPurchaseRecords(deprecated)

queryPurchaseRecords(context: common.UIAbilityContext, parameter: QueryPurchasesParameter): Promise<QueryPurchasesResult>

Obtains the purchase data of consumables that have been consumed. This API uses a promise to return the result.

Deprecation notice: This API is deprecated since API version 4.1.0(11). You are advised to use queryPurchases instead.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 1001860001.

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter QueryPurchasesParameter Yes QueryPurchasesParameter object, which contains the request information.

Returns

Type Description
Promise<QueryPurchasesResult> Promise object, which contains the purchase data of consumables that have been consumed.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860050 The HUAWEI ID is not signed in.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.QueryPurchasesParameter = {
            productType: iap.ProductType.CONSUMABLE
        }
        iap.queryPurchaseRecords(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter).then((data: iap.QueryPurchasesResult) => {
            // The request succeeded.
            console.info(`Succeeded in querying purchase records. data len: ${data.productList?.length}`);
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to query purchase records. Code is ${err.code}, message is ${err.message}`);
        });
    }

    build() {}
}

iap.queryPurchaseRecords(deprecated)

queryPurchaseRecords(context: common.UIAbilityContext, parameter: QueryPurchasesParameter, callback: AsyncCallback<QueryPurchasesResult>): void

Obtains the purchase data of consumables that have been consumed. This API returns the result asynchronously through a callback.

Deprecation notice: This API is deprecated since API version 4.1.0(11). You are advised to use queryPurchases instead.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 1001860001.

Since: 4.0.0(10)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter QueryPurchasesParameter Yes QueryPurchasesParameter object, which contains the request information.
callback AsyncCallback<QueryPurchasesResult> Yes Callback function. If the query is successful, err is undefined and data is the obtained QueryPurchasesResult object; otherwise, an error object will be returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860050 The HUAWEI ID is not signed in.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.QueryPurchasesParameter = {
            productType: iap.ProductType.CONSUMABLE
        }
        iap.queryPurchaseRecords(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter, (err: BusinessError, data: iap.QueryPurchasesResult) => {
            if (err) {
                // The request failed.
                console.error(`Failed to query purchase records. Code is ${err.code}, message is ${err.message}`);
                return;
            }
            // The request succeeded.
            console.info(`Succeeded in querying purchase records. data len: ${data.productList?.length}`);
        });
    }

    build() {}
}

iap.queryPurchases

queryPurchases(context: common.UIAbilityContext, parameter: QueryPurchasesParameter): Promise<QueryPurchaseResult>

Queries the order information of purchased products, including:

This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter QueryPurchasesParameter Yes QueryPurchasesParameter object, which contains the request information.

Returns

Type Description
Promise<QueryPurchaseResult> Promise object, which contains the order information of purchased products. In the sandbox environment, the order information of delivered non-consumables is not returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860050 The HUAWEI ID is not signed in.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.QueryPurchasesParameter = {
            productType: iap.ProductType.CONSUMABLE,
            queryType: iap.PurchaseQueryType.UNFINISHED
        }
        iap.queryPurchases(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter).then((data: iap.QueryPurchaseResult) => {
            // The request succeeded.
            console.info(`Succeeded in querying purchases. data len: ${data.purchaseDataList?.length}`);
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to query purchases. Code is ${err.code}, message is ${err.message}`);
        });
    }

    build() {}
}

iap.queryPurchases

queryPurchases(context: common.UIAbilityContext, parameter: QueryPurchasesParameter, callback: AsyncCallback<QueryPurchaseResult>): void

Queries the order information of purchased products, including:

This API returns the result asynchronously through a callback.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Parameters

Name Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
parameter QueryPurchasesParameter Yes QueryPurchasesParameter object, which contains the request information.
callback AsyncCallback<QueryPurchaseResult> Yes Callback function. If the query is successful, err is undefined and data is the obtained QueryPurchaseResult object; otherwise, an error object will be returned. In the sandbox environment, the order information of delivered non-consumables is not returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860050 The HUAWEI ID is not signed in.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const parameter: iap.QueryPurchasesParameter = {
            productType: iap.ProductType.CONSUMABLE,
            queryType: iap.PurchaseQueryType.UNFINISHED
        }
        iap.queryPurchases(this.getUIContext().getHostContext() as common.UIAbilityContext, parameter, (err: BusinessError, data: iap.QueryPurchaseResult) => {
            if (err) {
                // The request failed.
                console.error(`Failed to query purchases. Code is ${err.code}, message is ${err.message}`);
                return;
            }
            // The request succeeded.
            console.info(`Succeeded in querying purchases. data len: ${data.purchaseDataList?.length}`);
        });
    }

    build() {}
}

iap.showManagedSubscriptions

showManagedSubscriptions(context: common.Context, uiParameter: UIWindowParameter, groupId?: string): Promise<void>

Redirects to the subscription status screen or subscription details screen. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Device behavior differences: This API is supported on phones, tablets, 2-in-1 devices, and TVs. On other device types, it returns error code 801.

Since: 5.0.0(12)

Parameters

Name Type Mandatory Description
context common.Context Yes Context. UIAbilityContext is recommended.
uiParameter UIWindowParameter Yes UIWindowParameter object, which contains the window display mode.
groupId string No

Subscription group ID, which you have defined in AppGallery Connect. For details, please refer to Adding a Single Product > Auto-renewable Subscriptions.

NOTE

- If groupId is passed, the subscription details screen will be displayed.

- If groupId is not passed, the subscription status screen will be displayed. If a user has only one subscription data record in an app, the screen for showing the details of this subscription will be displayed.

Returns

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 5.1.0(18)+
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860050 The HUAWEI ID is not signed in.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        const uiWindowParameter: iap.UIWindowParameter = {
            windowScreenMode: iap.WindowScreenMode.DIALOG_BOX
        }
        const groupId = '***';
        iap.showManagedSubscriptions(this.getUIContext().getHostContext() as common.UIAbilityContext, uiWindowParameter, groupId).then(() => {
            // The request succeeded.
            console.info('Succeeded in showing subscription page.');
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to show subscription page. Code is ${err.code}, message is ${err.message}`);
        });
    }

    build() {}
}

iap.isSandboxActivated

isSandboxActivated(context: common.Context): Promise<boolean>

Checks whether the sandbox environment is available. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 5.0.0(12)

Parameters

Name Type Mandatory Description
context common.Context Yes Context. UIAbilityContext is recommended.

Returns

Type Description
Promise<boolean> Promise object. If true is returned, the sandbox environment is available. If false is returned, the sandbox environment is unavailable. You can check the reason based on the returned error code.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 6.1.0(23)+
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860050 The HUAWEI ID is not signed in.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.
1001860057 The app provision type is not debug.
1001860058 The HUAWEI ID is not test account.

Example:

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
    test() {
        iap.isSandboxActivated(this.getUIContext().getHostContext() as common.UIAbilityContext).then((isActivated: boolean) => {
            // The request succeeded.
            console.info(`Succeeded in checking the sandbox status. is activate: ${isActivated}`);
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to check the sandbox status. Code is ${err.code}, message is ${err.message}`);
        });
    }

    build() {}
}

iap.createRefundRequest

createRefundRequest(context: common.Context, purchaseOrderId: string): Promise<void>

Refund API, which is called to start the refund process. This API applies only to non-game apps. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.Payment.IAP

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Parameters

Name Type Mandatory Description
context common.Context Yes Context. UIAbilityContext is recommended.
purchaseOrderId string Yes Order ID of a purchase. The value contains a maximum of 256 characters.

Returns

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
401 Parameter error.Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1001860000 The operation was canceled by the user.
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.
1001860061 The purchase has been refunded or in refund.
1001860062 Refund is not allowed.

Example:

import { iap } from '@kit.IAPKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct IapTest {
  /**
   * Show the refund screen.
   */
  createRefundRequest() {
    const context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
    // Call iap.createRefundRequest to process the refund. Pass context and purchaseOrderId in the call request.
    let purchaseOrderId = '';
    iap.createRefundRequest(context, purchaseOrderId).then(() => {
      // Refund successful.
      console.info('Succeeded in create refund request.');
      // ...
    }).catch((err: BusinessError) => {
      // Refund failed.
      console.error(`Failed to create refund request. Code is ${err.code}, message is ${err.message}`);
      // ...
    });
  }
  build() {
  }
}

iap.showManagedInvoices

showManagedInvoices(context: common.Context, purchaseOrderId: string): Promise<void>

Redirects to the invoice issuing page. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 6.1.0(23).

System capability: SystemCapability.Payment.IAP.Extension

Device behavior differences: This API is supported on phones, tablets, and 2-in-1 devices. On other device types, it returns error code 1001860065.

Since: 6.1.0(23)

Parameters

Name Type Mandatory Description
context common.Context Yes Context. UIAbilityContext is recommended.
purchaseOrderId string Yes Order ID of a purchase. The value contains a maximum of 256 characters.

Returns

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

Error Code Error Message
1001860001 System internal error.
1001860002 The application is not authorized.
1001860004 Too frequent API calls.
1001860005 Network connection error.
1001860054 The country or region of the signed-in HUAWEI ID does not support IAP.
1001860064 The purchase order is not found for the signed-in HUAWEI ID.
1001860065 The operation is not supported.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import { iap } from '@kit.IAPKit';

@Entry
@Component
struct IapTest {
    /**
     * Open the invoice issuing screen.
     */
    showManagedInvoices() {
        const context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
        // Call iap.showManagedInvoices to open the invoice issuing screen. Pass context and purchaseOrderId in the call request.
        let purchaseOrderId = '';
        iap.showManagedInvoices(context, purchaseOrderId).then(() => {
            // The request succeeded.
            console.info('Succeeded in showing invoice page.');
            // ...
        }).catch((err: BusinessError) => {
            // The request failed.
            console.error(`Failed to show invoice page. Code is ${err.code}, message is ${err.message}`);
            // ...
        });
    }
    build() {
    }
}

QueryProductsParameter

Request parameters of the queryProducts API.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Name Type Read-Only Optional Description
productType ProductType No No

Type of products to be queried.

- CONSUMABLE: consumable

- NONCONSUMABLE: non-consumable

- AUTORENEWABLE: auto-renewable subscription

- NONRENEWABLE: non-renewable subscription
productIds string[] No No

ID list of products to be queried. Each product ID must exist and be unique in your app.

The product IDs come from the product information you have configured in AppGallery Connect. For details, please refer to Configuring Products.

Note: A maximum of 200 product IDs can be queried at a time. If you need to query more items, it is recommended to split the requests into batches.

Product

Details of a product.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Name Type Read-Only Optional Description
id string No No

Product ID.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
type ProductType No No

Product type.

- CONSUMABLE: consumable

- NONCONSUMABLE: non-consumable

- AUTORENEWABLE: auto-renewable subscription

- NONRENEWABLE: non-renewable subscription

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
name string No No

Product name, which you set when adding a product. The name is displayed on the checkout screen of IAP.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
description string No No

Product description, which you set when adding a product.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
price(deprecated) string No No

Displayed price of a product, in the format of Currency+Price, for example, EUR 0.15. For some countries and regions, the value of this parameter is in the format of Currency symbol+Price, for example, ¥0.15 in the Chinese mainland. The price includes tax.

- For a consumable or non-consumable with a promotional price, this parameter indicates the promotional price. If the product has no promotional price, this parameter indicates its original price.

- For an auto-renewable subscription, this parameter indicates its original price.

Note: This parameter is deprecated since 4.1.0(11). You are advised to use localPrice instead.
localPrice string No Yes

Displayed price of a product, in the format of Currency+Price, for example, EUR 0.15. For some countries and regions, the value of this parameter is in the format of Currency symbol+Price, for example, ¥0.15 in the Chinese mainland. The price includes tax.

- For a consumable, non-consumable, or non-renewable subscription with a promotional price, this parameter indicates the promotional price. If the product has no promotional price, this parameter indicates its original price. (The promotional-price capability has been updated to temporary price adjustments. In temporary price-adjustment scenarios, this field represents the product's original price.)

- For an auto-renewable subscription, this parameter indicates its original price.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Since: 4.1.0(11)
microPrice number No No

Product price in micro unit, which equals the actual product price multiplied by 1,000,000. For example, if the actual price of a product is US$1.99, the product price in micro unit is 1,990,000 (1.99*1000000).

- For a consumable, non-consumable, or non-renewable subscription with a promotional price, this parameter indicates the promotional price in micro unit. If the product has no promotional price, this parameter indicates its original price in micro unit. (The promotional-price capability has been updated to temporary price adjustments. In temporary price-adjustment scenarios, this field represents the product's original price.)

- For an auto-renewable subscription, this parameter indicates its original price in micro unit.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
originalLocalPrice string No No

Original price of a product, in the format of Currency+Price, for example, EUR 0.15. For some countries and regions, the value of this parameter is in the format of Currency symbol+Price, for example, ¥0.15 in the Chinese mainland. The price includes tax.

- For a consumable, non-consumable, or non-renewable subscription, this parameter indicates the original price regardless of whether a promotional price is set.

- For an auto-renewable subscription, this parameter will not be returned.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
originalMicroPrice number No No

Original price in micro unit of a product. It equals the original product price multiplied by 1,000,000. For example, if the original price of a product is US$1.99, the product price in micro unit is 1,990,000 (1.99*1000000).

- For a consumable, non-consumable, or non-renewable subscription, this parameter indicates the original price in micro unit regardless of whether a promotional price is set.

- For an auto-renewable subscription, this parameter will not be returned.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
currency string No No

Currency used to pay for a product, for example, CNY.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).
status ProductStatus No Yes

Product status.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Since: 5.0.0(12)
subscriptionInfo SubscriptionInfo No Yes

Information about an auto-renewable subscription. This parameter is optional.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Since: 4.1.0(11)
promotionalOffers PromotionalOffer[] No Yes

List of promotional offers for specific user groups.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Since: 5.0.0(12)
jsonRepresentation string No Yes

Original JSON character string of product details.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Since: 4.1.0(11)

PromotionalOffer

Promotional offer information that you can define for a subscription.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 5.0.0(12)

Name Type Read-Only Optional Description
offerId string No No Promotional offer ID.
paymentMode OfferPaymentMode No No Payment method for a promotion.
periodUnit PeriodUnit No Yes Unit of the subscription billing cycle.
periodCount number No Yes Number of billing cycles for a subscription.
localPrice string No No Discounted price of a product, in the format of Currency+Price, for example, EUR 0.15. For some countries and regions, the value of this parameter is in the format of Currency symbol+Price, for example, ¥0.15 in the Chinese mainland.
microPrice number No No Discounted price in micro unit, which equals the actual product price multiplied by 1,000,000. For example, if the actual price of a product is US$1.99, the product price in micro unit is 1,990,000 (1.99*1000000).

SubscriptionInfo

Subscription information.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Name Type Read-Only Optional Description
periodUnit PeriodUnit No No Unit of the subscription billing cycle.
periodCount number No No Number of billing cycles for a subscription.
groupId string No No Subscription group ID.
groupLevel number No No Product subscription level.
hasEligibilityForIntroOffer boolean No Yes

Indicates whether a user has enjoyed an introductory offer. Options:

- true: yes.

- false: no.

- Other values: No relevant information is obtained.
introductoryOffer SubscriptionOffer No Yes Promotion information.

SubscriptionOffer

Promotion information.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Name Type Read-Only Optional Description
paymentMode OfferPaymentMode No No Payment method for a promotion.
periodUnit PeriodUnit No No Unit of the subscription billing cycle.
periodCount number No No Period count of a promotion.
localPrice string No No Promotional price of a product, in the format of Currency+Price, for example, EUR 0.15. For some countries and regions, the value of this parameter is in the format of Currency symbol+Price, for example, ¥0.15 in the Chinese mainland.
microPrice number No No Promotional price in micro unit. Promotional price in micro unit, which equals the product price multiplied by 1,000,000.
offerType OfferType No No Promotion type.

PurchaseParameter

Request parameters of the purchase and createPurchase APIs.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Name Type Read-Only Optional Description
productId string No No

ID of the product to purchase. Each product ID must be unique in an app. The product IDs come from the product information you have configured in AppGallery Connect. For details, please refer to Configuring Products.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
productType ProductType No No

Type of products to be queried.

- CONSUMABLE: consumable

- NONCONSUMABLE: non-consumable

- AUTORENEWABLE: auto-renewable subscription

- NONRENEWABLE: non-renewable subscription

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
developerPayload string No Yes

Information provided by the merchant.

If this parameter contains a value, it will be returned to the application unchanged in the payment-success callback result.

Note: The value length range is [0, 256]. If the length limit is exceeded, the truncated data will be returned after the payment is successfully completed. You are advised to verify the field length before sending a request to avoid unexpected truncation.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
reservedInfo string No Yes

Additional product information in JSON string format passed in key-value pairs.

Example: let reservedInfo = "{\"key1\":\"value1\",\"key2\":\"value2\"}";

Note: This parameter is reserved for you to pass additional information. You can choose to set it or not.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).
promotionalOfferId string No Yes

Promotional offer ID. This ID is the same as the promotional offer ID set by you when configuring a promotional offer for a product. This parameter must be passed when jwsRepresentation (see Generating a Signed Purchase Parameter for a Promotion) is passed for using a promotional offer. Otherwise, an error will be reported.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

Since: 5.0.0(12)
applicationUserName string No Yes

Obfuscated string that uniquely identifies a user's account. This parameter can be provided when promotionalOfferId is included. When jwsRepresentation (see Generating a Signed Purchase Parameter for a Promotion) is passed for using a promotional offer, this parameter is required if applicationUserName is present in jwsRepresentation; otherwise, an error will occur.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

Since: 5.0.0(12)
jwsRepresentation string No Yes

JWS signature data that contains purchase parameters, such as promotional offer information. For details, please refer to Generating a Signed Purchase Parameter for a Promotion.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

Since: 5.0.0(12)
quantity number No Yes

Quantity of the purchased consumables or non-renewable subscriptions. The value must comply with the following restrictions:

- The quantity parameter applies to one product type only. It does not support a mix of different product types.

- The maximum quantity is 10.

Note: If the quantity parameter is used to support bulk purchases of products, your app needs to verify that the ordered quantity matches the final delivered quantity to prevent under-deliveries or over-deliveries.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

Since: 5.0.3(15)

PurchaseResult(deprecated)

Result returned by the purchase API.

Deprecation notice: This API is deprecated since API version 4.1.0(11).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Name Type Read-Only Optional Description
inAppPurchaseData string No No JSON string of order data. For the specific parameters contained in the string, please refer to InAppPurchaseData.
signature string No No Signature string generated after the paymentData string is signed using the IAP private key.
signatureAlgorithm string No No Signature algorithm. The value is fixed at SHA256WithRSA/PSS.

CreatePurchaseResult

Result returned by the createPurchase API.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Name Type Read-Only Optional Description
purchaseData string No No Purchase result in JSON string format. For details, see PurchaseData.

ConsumePurchaseParameter(deprecated)

Request parameters of the consumePurchase API.

Deprecation notice: This API is deprecated since API version 4.1.0(11).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Name Type Read-Only Optional Description
purchaseToken string No No

Purchase token, which is generated by the IAP server when the payment for a product is complete.

Note: The purchase token is obtained from InAppPurchaseData. When the payment is successful or the queryOwnedPurchases API is called, InAppPurchaseData in JSON string format will be returned.
developerChallenge string No Yes

Custom challenge, which uniquely identifies a consumption request. After the consumption is successful, the challenge is recorded in the purchase data and returned.

Note: The value length range is [0, 64].

ConsumeResult(deprecated)

Result returned by the consumePurchase API.

Deprecation notice: This API is deprecated since API version 4.1.0(11).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Name Type Read-Only Optional Description
consumedPurchaseData string No No JSON string that contains consumption result data. For the specific parameters contained in the string, please refer to InAppPurchaseData.
signature string No No

Signature string generated after the consumption data (consumedPurchaseData) is signed using the IAP private key. The signature algorithm is specified by the signatureAlgorithm field.

After receiving the signature string, the app needs to perform signature verification on the JSON string of consumedPurchaseData. For details, please refer to Verifying the Signature in the Returned Result.
signatureAlgorithm string No No Signature algorithm. The value is fixed at SHA256WithRSA/PSS.

FinishPurchaseParameter

Request parameters of the finishPurchase API.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Name Type Read-Only Optional Description
productType ProductType No No

Product type.

- CONSUMABLE: consumable

- NONCONSUMABLE: non-consumable

- AUTORENEWABLE: auto-renewable subscription

- NONRENEWABLE: non-renewable subscription
purchaseToken string No No

Purchase token returned in the purchase order.

For a one-time purchase, the token has a one-to-one mapping with the specific purchase order. For a subscription purchase, the token has a one-to-one mapping with the subscription ID.

Note: purchaseToken is obtained from PurchaseOrderPayload. Both the createPurchase and queryPurchases APIs return PurchaseOrderPayload.
purchaseOrderId string No No

Order ID returned after a purchase. The value contains a maximum of 256 characters.

Note: purchaseOrderId is obtained from PurchaseOrderPayload. Both the createPurchase and queryPurchases APIs return PurchaseOrderPayload.

QueryPurchasesParameter

Request parameters of the queryOwnedPurchases, queryPurchaseRecords, and queryPurchases APIs.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Name Type Read-Only Optional Description
productType ProductType No No

Type of products to be queried.

- CONSUMABLE: consumable

- NONCONSUMABLE: non-consumable

- AUTORENEWABLE: auto-renewable subscription

- NONRENEWABLE: non-renewable subscription
continuationToken string No Yes

Pagination cursor used to locate data for paginated queries.

This parameter is optional for the first query. If a user owns a large number of products and a continuationToken is returned in the response, the app must call this API again and pass the received continuationToken. If not all products have been retrieved, additional calls must continue to be made until no continuationToken is returned, indicating that all products have been fetched.
queryType PurchaseQueryType No Yes

Query type. The options are as follows (default value: UNFINISHED):

- ALL: all purchase records, including consumables, non-consumables, auto-renewable subscriptions, and non-renewable subscriptions.

- UNFINISHED: consumables, non-consumables, auto-renewable subscriptions, and non-renewable subscriptions that have been purchased but not delivered.

- CURRENT_ENTITLEMENT: non-consumables that have been purchased and subscriptions that are currently active.

Note: This parameter is not relevant for queryOwnedPurchases or queryPurchaseRecords.

Since: 4.1.0(11)

QueryPurchasesResult(deprecated)

Result returned by the queryOwnedPurchases or queryPurchaseRecords API.

Deprecation notice: This API is deprecated since API version 4.1.0(11).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Payment.IAP

Since: 4.0.0(10)

Name Type Read-Only Optional Description
productList string[] No No Product ID array.
inAppPurchaseDataList string[] No No This parameter records InAppPurchaseData as an array of JSON strings, used in conjunction with inAppSignatureList for signature verification. For the specific parameters contained in each JSON string, please refer to InAppPurchaseData.
inAppSignatureList string[] No No

Signature string of each JSON string in inAppPurchaseDataList. The IAP private key is used for signing through the signature algorithm specified by the signatureAlgorithm field.

The app needs to verify each JSON string in inAppPurchaseDataList. For details about the verification method, please refer to Verifying the Signature in the Returned Result.
continuationToken string No Yes

Pagination cursor used to locate data for paginated queries.

If a user owns a large number of products and a continuationToken is returned in the response, the app must call this API again and pass the received continuationToken. If not all products have been retrieved, additional calls must continue to be made until no continuationToken is returned, indicating that all products have been fetched.
signatureAlgorithm string No No Signature algorithm. The value is fixed at SHA256WithRSA/PSS.

QueryPurchaseResult

Result returned by the queryPurchases API.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 4.1.0(11)

Name Type Read-Only Optional Description
purchaseDataList string[] No No Array of PurchaseData strings.
continuationToken string No Yes

Pagination cursor used to locate data for paginated queries.

If a user owns a large number of products and a continuationToken is returned in the response, the app must call this API again and pass the received continuationToken. If not all products have been retrieved, additional calls must continue to be made until no continuationToken is returned, indicating that all products have been fetched.

UIWindowParameter

UI window parameters of the iap.showManagedSubscriptions API.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.Payment.IAP

Since: 5.0.0(12)

Name Type Read-Only Optional Description
windowScreenMode WindowScreenMode No No

UI window mode.

- DIALOG_BOX: pop-up.

- FULLSCREEN: full-screen.