IAP 2.0 (for Existing Apps Only)

Applicable devices

Mobile phones, tablets, and Vision products

Applicable regions

Global

pay.getProvider(OBJECT)

Obtains the service provider.

pay.pay(OBJECT)

Completes payment.

pay.productPay(OBJECT)

Pays for a product maintained in AppGallery Connect.

pay.getProductDetails(OBJECT)

Obtains product details from Huawei PMS. Avoid obtaining product information from your own server. Otherwise, price information may be inconsistent between your app and the checkout page of IAP.

pay.getPurchaseInfo(OBJECT)

Queries information about non-consumable product orders of the current user.

pay.getOrderDetail(OBJECT)

Queries order details. All orders that call the pay API can be queried for review when orders are lost.

pay.getWalletStatus(OBJECT)

Checks whether Huawei Pay is supported.

pay.startWalletPay(OBJECT)

Starts online payment using Huawei Pay.

orderInfo

json

Yes

Order information. For details, please refer to orderInfo parameters.

success

function

No

Callback upon success.

fail

function

No

Callback upon failure.

complete

function

No

Callback upon completion.

productName

string(0,50)

Yes

Yes

Product name customized by a merchant. This name will be displayed to the user for confirmation. The value cannot contain the following special characters: # " & / ? $ ^ *:) \ < > , | % +

productDesc

string(0,100)

Yes

Yes

Product description customized by a merchant. The value cannot contain the following special characters: # " & / ? $ ^ *:) \ < > , | % +

applicationID

string(0,100)

Yes

Yes

App ID obtained from HUAWEI Developers.

requestId

string(0,32)

Yes

Yes

Order ID generated by the merchant.

The merchant order ID is generated by your app before payment and is used as the unique identifier of one payment request. The IAP server returns the value of requestId in the server callback. This parameter contains letters and digits, and is the unique identifier of an order.

amount

string

Yes

Yes

Product payment amount. This amount will be displayed to the user for confirmation.

merchantId

string

Yes

Yes

Merchant ID.

The value is the payment ID obtained from HUAWEI Developers.

serviceCatalog

string

Yes

No

Product type.

• X4: theme
• X5: AppGallery
• X6: game
• X7: SkyTone
• X8: cloud storage space
• X9: eBook
• X10: iLearning
• X11: music
• X12: video
• V0: Vmall physical product
• X31: call fee top-up
• X32: air ticket or hotel
• X33: movie ticket
• X34: group purchase
• X35: mobile phone pre-order
• X36: payment of utility bills
• X37: fund product
• X38: lottery
• X39: traffic top-up

Set this parameter to X6 for games and X5 for apps. An incorrect product type will affect risk control. Ensure that you pass a correct product type.

merchantName

string(0,50)

Yes

No

Merchant name.

The value is the company name obtained from HUAWEI Developers.

sdkChannel

int

Yes

Yes

Channel information. The options are as follows:

• 0: no channel (for self-owned apps)
• 1: AppGallery
• 2: preload
• 3: GameCenter

Set this parameter to 3 for games and 1 for apps.

url

string(0,255)

No

Yes

Payment result callback URL.

After Huawei server receives the value of this parameter, it checks settings of HUAWEI Developers for a callback URL defined for the app. If such a URL has been defined, the defined URL is used. Otherwise, the URL indicated by this parameter will be used as the callback URL after the payment.

Note: The URL must be valid with up to 255 characters. The URL cannot end with a backslash (\) and must exclude get parameters.

Examples:

Correct: https://domain.com/path

Incorrect: https://domain.com/path?key=value

currency

string

No

Yes

Currency used for payment. Example: USD, CNY, or MYR, which must comply with ISO 4217.

For details, please refer to ISO 4217 Currency Codes.

If this parameter is not set, the default value CNY is used.

country

string

No

Yes

Country/Region code. Example: US, CN, or MY, which must comply with ISO 3166.

For details, please refer to ISO 3166 Country Codes.

If this parameter is not set, the default value CN is used.

urlver

string

No

Yes

Payment result callback version.

You can leave this parameter empty, or set it to 2. If the value is not 2, the payment will fail.

extReserved

string(0,128)

No

No

Information stored on the merchant side. The value cannot contain the following special characters: # " & / ? $ ^ *:) \ < > , | % +

If this parameter has a value, the value will be returned by the callback API of Huawei IAP server.

sign

string

Yes

No

1. Sort all the relevant parameters in ascending order based on ASCII codes of the parameter names. If the first letters of some parameters are the same, the second letter is used. The rest may be deduced by analogy.
   CAUTION:

   The principles for signing relevant parameters are as follows:

   1. If a parameter in a request is marked as signed in this table and the parameter has a value other than null or "", the parameter value must be the same as that in ProductPayRequest in signing.
   2. The sign parameter is not signed.
2. Concatenate all the parameter names and values in key-value pairs using the & character to obtain a character string to be signed.
3. Sign the character string using the payment private key to obtain the value of sign. For details about how to obtain the payment private key, please refer to Using APIs of IAP 2.0.
4. You need to generate a payment signature string for your quick game.

expireTime

string

No

Yes

Timeout interval of an order in your quick app. This parameter is available only for payments by scanning a QR code.

Do not use this parameter.

partnerIDs

string

No

Yes

List of payment receiving account IDs, which is a JSON array.

Do not use this parameter.

validTime

int

No

No

Order validity period in your quick app.

This parameter indicates the maximum stay time of an order on the payment page, in seconds. If this validity period is exceeded, an error will occur if payment is to make, indicating that the order is invalid. After the user confirms the failure, the payment page will exit, and a result code will be returned to the app.

The value of this parameter cannot be shorter than 60s (default value). Otherwise, the default value will be used.

If this parameter is not passed, no validity period will be set on the IAP server.

Do not use this parameter.

publicKey

string

Yes

No

Public key, which is obtained when IAP is enabled on HUAWEI Developers. For details about how to obtain the public key, please refer to Using APIs of IAP 2.0.

result

string

Payment result.

code

number

Status code.

data

string

Message content.

applicationID

string

Yes

Yes

App ID, which is the unique identifier allocated by HUAWEI Developers to an app after the app is created.

productNo

string

Yes

Yes

PMS code of a purchased product, used to obtain product details (such as price) from PMS. Refer to getProductDetails for how product details are obtained. If a product cannot be found in PMS, the payment will fail and the value of PayResult:returnCode will be PRODUCT_NOT_EXIST (defined in PayStatusCodes).

requestId

string

Yes

Yes

Payment order ID on the merchant side, which uniquely identifies a payment request.

The payment order ID is generated by you and consists of letters and digits. It cannot contain Chinese characters and special characters including # " & / ? $ ^ * : ) \ < > , | .

The payment order ID must be unique in the request. When an order is canceled or the order payment fails, the generated payment order ID cannot be reused.

The IAP server returns the value of requestId without change in the API callback.

merchantId

string

Yes

Yes

Merchant ID, which is the payment ID allocated by HUAWEI Developers to you.

serviceCatalog

string

Yes

No

Product type.

Set this parameter to X6 for games and X5 for apps.

An incorrect product type will affect risk control. Ensure that you pass a correct product type.

merchantName

string

Yes

No

Merchant name. Set this parameter to the company name configured during developer registration.

sdkChannel

int

Yes

Yes

Channel information. Set this parameter to 3 for quick games.

The options are as follows:

• 0: no channel (for self-owned apps)
• 1: AppGallery
• 2: preload
• 3: GameCenter

url

string

No

Yes

Payment result callback URL.

After Huawei server receives the value of this parameter, it checks settings of HUAWEI Developers for a callback URL defined for the app. If such a URL has been defined, the defined URL is used. Otherwise, the URL indicated by this parameter will be used as the callback URL after the payment.

Example:

Correct: https://test.sdkapp.chuangyunet.com/Pay/path

Incorrect: https://test.sdk_app.chuangyunet.com/Pay/path?key=value

urlver

string(100)

No

Yes

Payment result callback version.

You can leave this parameter empty, or set it to 2. If the value is not 2, the payment will fail.

publicKey

string(50)

Yes

No

Public key, which is obtained when IAP is enabled on HUAWEI Developers. For details about how to obtain the public key, please refer to Using APIs of IAP 2.0.

extReserved

string(128)

No

No

Information stored on the merchant side. The value cannot contain the following special characters: # " & / ? $ ^ * : ) \ < > , | % +

If this parameter has a value, the value will be returned by the callback API of Huawei IAP server.

sign

string

Yes

No

1. Sort all the relevant parameters in ascending order based on ASCII codes of the parameter names. If the first letters of some parameters are the same, the second letter is used. The rest may be deduced by analogy.
   CAUTION:

   The principles for signing relevant parameters are as follows:

   1. If a parameter in a request is marked as signed in this table and the parameter has a value other than null or "", the parameter value must be the same as that in ProductPayRequest in signing.
   2. The sign parameter is not signed.
2. Concatenate all the parameter names and values in key-value pairs using the & character to obtain a character string to be signed.
3. Sign the character string using the payment private key to obtain the value of sign. For details about how to obtain the payment private key, please refer to Using APIs of IAP 2.0.
4. You need to generate a payment signature string for your quick game.

success

function

No

No

Callback upon success.

fail

function

No

No

Callback upon failure.

complete

function

No

No

Callback upon completion.

returnCode

int

Result code.

errMsg

string

Result code description.

merchantId

string

Merchant ID, which is the payment ID allocated by HUAWEI Developers to you.

orderID

string

Payment order ID generated by the IAP server.

microsAmount

long

Product price in micro unit.

The value equals the real product price multiplied by 1,000,000. For example, if the actual price of a product is USD1.99, the product price in micro unit is 1,990,000 (1.99 x 1,000,000).

currency

string

Currency. The value must comply with the ISO 4217 standard, for example, USD, CNY, and MYR.

country

string

Country/Region code. The value must comply with the ISO 3166 standard, for example, US, CN, and MY.

time

string

Payment completion timestamp.

requestId

string

Payment order ID on the merchant side, which is consistent with the value of requestId in the request.

productNo

string

ID of the purchased product.

sign

string

Signature of the preceding data.

code

number

Status code.

data

string

Status code description.

applicationID

string

Yes

App ID obtained from HUAWEI Developers.

requestId

string

Yes

Request ID, which is generated by your app and used to uniquely identify a product query request.

merchantId

string

Yes

Merchant ID, which is the payment ID allocated by HUAWEI Developers to you.

productNos

string

Yes

ID list of products to be queried. Use vertical bars (|) to separate multiple product IDs. Up to 20 products can be queried at a time.

The product ID is the same as that you configure in the product information in AppGallery Connect. For details, please refer to Creating an In-App Product.

success

function

No

Callback upon success.

fail

function

No

Callback upon failure.

complete

function

No

Callback upon completion.

requestId

string

Product query request ID, which is the same as the value of requestId in the request.

Your app can use this parameter to identify the query request to which the callback result belongs.

productList

list<productdetail>

List of products that are queried successfully. The value is an array containing the ProductDetail object.

failList

productfailobject

List of products that fail to be queried. The value is an array containing the ProductFailObject object.

productNo

string

ID of a product that is queried successfully.

microsPrice

long

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 USD1.99, the product price in micro unit is 1,990,000 (1.99 x 1,000,000).

price

string

Displayed price of a product, including the currency unit and actual price of the product. The value is in the Currency unit Price format, for example, CNY 0.15.

currency

string

Currency used to pay for a product. The value must comply with the ISO 4217 standard, for example, USD, CNY, and MYR.

country

string

Country/Region code. The value must comply with the ISO 3166 standard, for example, US, CN, and MY.

productName

string

Product name, which is set during product information configuration.

productDesc

string

Product description, which is set during product information configuration.

productNo

string

ID of a product that fails to be queried.

code

int

Error code for the query failure. For details, please refer to Error Codes.

msg

string

Query failure description.

code

number

Status code.

data

string

Status code description.

merchantId

string

Yes

Yes

Merchant ID, which is the payment ID allocated by HUAWEI Developers to you.

appId

string

Yes

Yes

App ID, which is the unique identifier allocated by HUAWEI Developers to an app after the app is created.

priceType

string

Yes

Yes

Price type. The parameter has a fixed value of 3, which indicates non-consumables in the app.

productId

string

No

Yes

PMS code of the purchased product. If this parameter is not passed, the information about all non-consumables is queried.

ts

long

Yes

Yes

Timestamp, which is the number of milliseconds from 00:00:00 on January 1, 1970 to the current time.

publicKey

string

Yes

No

Public key, which is obtained when IAP is enabled on HUAWEI Developers. For details about how to obtain the public key, please refer to Using APIs of IAP 2.0.

pageNo

long

Yes

Yes

Number of the page for which record count is queried. By default, 100 records are queried for each page.

sign

string

Yes

No

1. Sort all the relevant parameters in ascending order based on ASCII codes of the parameter names. If the first letters of some parameters are the same, the second letter is used. The rest may be deduced by analogy.
   CAUTION:

   The principles for signing relevant parameters are as follows:

   1. If a parameter in a request is marked as signed in this table and the parameter has a value other than null or "", the parameter value must be the same as that in ProductPayRequest in signing.
   2. The sign parameter is not signed.
2. Concatenate all the parameter names and values in key-value pairs using the & character to obtain a character string to be signed.
3. Sign the character string using the payment private key to obtain the value of sign. For details about how to obtain the payment private key, please refer to Using APIs of IAP 2.0.

success

function

No

No

Callback upon success.

fail

function

No

No

Callback upon failure.

complete

function

No

No

Callback upon completion.

rtnCode

string

Result code.

pageCount

long

Number of pages.

purchaseInfoList

list<purchaseinfo>

List of the queried non-consumable orders.

sign

string

Signature string.

requestId

string

Order ID on the merchant side.

merchantId

string

Merchant ID of the order.

appId

string

App ID.

productId

string

ID of a non-consumable.

tradeTime

string

Payment completion time, in yyyy-MM-dd HH:mm:ss format.

code

number

Status code.

data

string

Status code description.

merchantId

string

Yes

Yes

Merchant ID, which is the payment ID allocated by HUAWEI Developers to you.

requestId

string

Yes

Yes

ID of the payment order to be queried. The payment order ID is generated by your app during payment to uniquely identify a payment request. After being generated, payment order IDs are maintained by your app.

keyType

string

Yes

Yes

The fixed value is 1, which indicates the merchant key.

time

string

Yes

Yes

Timestamp of the current time, which is the number of milliseconds from 00:00:00 on January 1, 1970 to the current time.

publicKey

string

Yes

No

Public key, which is obtained when IAP is enabled on HUAWEI Developers. For details about how to obtain the public key, please refer to Using APIs of IAP 2.0.

sign

string

Yes

No

1. Sort all the relevant parameters in ascending order based on ASCII codes of the parameter names. If the first letters of some parameters are the same, the second letter is used. The rest may be deduced by analogy.
   CAUTION:

   The principles for signing relevant parameters are as follows:

   1. If a parameter in a request is marked as signed in this table and the parameter has a value other than null or "", the parameter value must be the same as that in payreq in signing.
   2. The sign parameter is not signed.
2. Concatenate all the parameter names and values in key-value pairs using the & character to obtain a character string to be signed.
3. Sign the character string using the payment private key to obtain the value of sign. For details about how to obtain the payment private key, please refer to Using APIs of IAP 2.0.

success

function

No

No

Callback upon success.

fail

function

No

No

Callback upon failure.

complete

function

No

No

Callback upon completion.

returnCode

int

Yes

Yes

Result code. For details, please refer to Error Codes.

returnDesc

string

Yes

Yes

Result code description.

requestId

string

No

Yes

Payment order ID generated by the app, which is consistent with the value of requestId in the request.

orderID

string

No

Yes

Payment order ID generated by the IAP server.

orderTime

string

No

Yes

Order placement time, in yyyy-MM-dd HH:mm:ss format.

tradeTime

string

No

Yes

Payment time, in yyyy-MM-dd HH:mm:ss format.

status

string

No

Yes

Payment status of an order.

• 0: Order payment failed.
• 1: Order payment completed.
• 2: The order is not processed. Possibly, the order is to be paid or a payment response is awaited. Query the order payment status again within one day. If the order is still not processed one day later, the order is processed as payment failure.
• 3: The order is being processed. Query the order payment status again within one day. If the order is still being processed one day later, the order is processed as payment failure.

sign

string

No

No

Signature string of the query response.

code

number

Status code.

data

string

Status code description.

event

string

"ONLINEPAY"

No

If this parameter is not set, the value ONLINEPAY is used.

success

function

-

Yes

Callback function used when the API is successfully called (that is, Huawei Pay is supported).

fail

function

-

Yes

Callback function used when the API fails to be called.

data

string

Error description.

code

int

Error code.

orderInfo

string

-

Yes

UnionPay order ID, which is obtained by the merchant server from the UnionPay server.

success

function

-

Yes

Callback function when the payment is successful.

fail

function

-

Yes

Callback function when the payment fails.

data

string

Payment success result description.

data

string

Error description.

code

int

Error code.

1060

2019-12-10

Added the getProductDetails, productPay, getPurchaseInfo, and getOrderDetail payment APIs for PMS.