目录

Data Model Description

orderStr

Describes the order payment information, which is the input parameter of the Huawei Pay SDK API.

Parameter Mandatory Type Description
app_id No String

App ID.

Note: In the service provider mode, when a merchant app or atomic service is switched to start the checkout screen, app_id needs to be changed to the app ID of the merchant and transferred through the subAppId field in the platform merchant/service provider pre-ordering API.
merc_no Yes String

Merchant number.

Note: Pass the direct merchant number or the merchant number of the platform merchant/service provider. This number must be the same as the merchant number used to obtain the prepayment ID.
prepay_id Yes String Prepayment ID. It is generated using the direct merchant pre-ordering or platform merchant/service provider pre-ordering API request, and is valid within 10 minutes.
timestamp Yes String Current timestamp, which is the number of milliseconds elapsed since 00:00:00 on January 1, 1970 (UTC+08:00). The value is a 13-digit number. Example value: 1666230721315.
noncestr Yes String

Random string. The value must contain 1 to 32 characters. If the value is out of the specified range, the request will fail. The random number generation algorithm is recommended.

A new value must be generated for each order.
sign Yes String Signature. The value is calculated using all fields except the sign field. For details, see Signing Rules.
auth_id Yes String Merchant certificate ID. A merchant can configure multiple certificates. Keep them secure. For details, see Preparing Certificates.
reserved No String Extended field, in JSON string format. For details, see reserved.

Describes the order payment redirection information, which is the input parameter for the SDK-based redirection to third-party payment API.

Parameter Mandatory Type Description
nextAction Yes String

Third-party payment method.

- L: linkUrl

- S: scheme
linkUrl No String Link URL of the third-party payment method (obtained based on the access requirements of the third-party payment platform). The default value is an empty string. The value is passed based on the payment method specified by nextAction.
scheme No String Scheme URL of the third-party payment method (obtained based on the access requirements of the third-party payment platform). The default value is an empty string. The value is passed based on the payment method specified by nextAction.
clientToken Yes String

Client token.

The value is obtained from the response of the API for starting the unified checkout screen (requestPayment or cashierPicker).

reserved

Describes the extended field information of orderStr.

Parameter Mandatory Type Description
sandbox_flag No Boolean

Sandbox flag. It is used to determine whether to use the sandbox environment for debugging. This parameter is mandatory when the sandbox environment is used for debugging.

- true: yes

- false: no (default value)
referer No String

Referer link. When the user is redirected to WeChat Pay, if a valid referer is passed, the referer is preferentially used.

Note: The validity of the passed referer link is verified as follows:

- The domain name cannot be empty and must use the HTTPS protocol.

- Only the protocol and domain name are retained. (If https://xxx.com/search?xxx=123&yyy=456 is passed, only https://xx.com is retained.)

- The value must contain 1 to 2048 characters.

extraInfo

Describes the reserved field of the Huawei Pay SDK API.

Parameter Mandatory Type Description
selectPayType No String

List of payment methods to be displayed on the checkout screen. Multiple payment methods are separated by vertical bars (|). The payment methods are those provided in Product Enabling and Configuration.

Note: For example, if a merchant configures three payment methods (WeChat Pay wechat_pay, Alipay ali_pay, and Alipay sandbox ali_pay_sandbox), you can pass the following values:

1. wechat_pay|ali_pay (WeChat Pay and Ali Pay are displayed in the checkout screen.)

2. wechat_pay|**ali_pay_sandbox **(WeChat Pay and Ali Pay sandbox are displayed in the checkout screen.)

payload

Describes the payload field reserved in the Huawei Pay SDK API.

Parameter Mandatory Type Description
method No String

Alternative payment method.

AP: alternative Payment Type

contractStr

Describes the input parameters of the SDK signing API.

Parameter Mandatory Type Description
appId No String App ID.
preSignNo Yes String Pre-signing ID, which is generated using the direct merchant pre-signing or platform merchant/service provider pre-signing API request and is valid within 10 minutes.

PayMercAuth

Describes the PayMercAuth JSON type, which stores merchant authentication information and is used as the request header input parameter.

Parameter Mandatory Type Description
callerId Yes String

Merchant number.

Note: Pass the direct merchant number or the merchant number of the platform merchant/service provider. This number must be the same as the merchant number to which the merchant certificate ID (authId) belongs.
traceId Yes String Trace ID. This parameter corresponds to the request. Ensure that the value is unique for each request. You are advised to use the timestamp and random number. The value contains a maximum of 32 characters.
time Yes Long Current timestamp, in milliseconds. This parameter is used to prevent repeated requests.
authId Yes String Merchant certificate ID. A merchant can configure multiple certificates. Keep them secure. For details, see Preparing Certificates.
sessionKey No String SM4 key encrypted using SM2. This parameter is mandatory when sensitive parameters need to be transferred. For details, see Sensitive Information Processing. Otherwise, this parameter does not need to be transferred.
headerSign Yes String Signature value of the input parameters in the PayMercAuth object (all fields except headerSign). The value is generated by signing after sorting and concatenating based on the signing rules.
bodySign Yes String

Signature of the request body parameters. The value is generated by signing after sorting and concatenating based on the signing rules.

Note:

For a GET request, sign the request URI. For example, if the request URL is https://www.xxxxxx.com/api/v2/aggr/transactions/merc-orders/202xxx?mercNo=1015xxx, the signature content is /api/v2/aggr/transactions/merc-orders/202xxx?mercNo=1015xxx.

PayDevAuth

Defines the JSON data, which stores the developer authentication information and is used as the input parameter in the request header.

Parameter Mandatory Type Description
clientId Yes String OAuth 2.0 client ID of the app. On AppGallery Connect, click Development and services, find the project in the project list, choose Project settings > General information, and obtain the value of OAuth 2.0 client ID > Client ID in the App information area.
accessToken Yes String App-level token. For details about how to obtain the token, see Obtaining an App-Level Credential.
traceId Yes String Trace ID. This parameter corresponds to the request. Ensure that the value is unique for each request. You are advised to use the timestamp and random number. The value contains a maximum of 32 characters.
time Yes Long Current timestamp, in milliseconds. This parameter is used to prevent repeated requests.
developerEncKeyId No String

ID of the developer's public key certificate for encryption. For details about how to obtain the ID, see Uploading the Developer Public Key. This parameter is mandatory in the request scenario where sensitive parameters (described in the API fields) are involved. Otherwise, this parameter is not required.

The developer specifies that Huawei uses the corresponding developer's public key to encrypt the response fields and returns the encrypted response fields. The developer uses the corresponding private key to decrypt the response fields.
petalpayEncKeyId No String

ID of Huawei's public key certificate for encryption. For details about how to obtain the ID, see Uploading the Developer Public Key. This parameter is mandatory in the scenario where sensitive response parameters (described in the API fields) are involved. Otherwise, this parameter is not required.

The developer uses the corresponding Huawei's public key to encrypt the privacy fields in the API request, and Huawei uses the corresponding private key to decrypt the fields.
developerSignKeyId Yes String ID of the developer's public key certificate for signature verification. For details about how to obtain the ID, see Uploading the Developer Public Key. The developer uses the corresponding private key to sign the API request, and Huawei uses the corresponding public key to verify the signature.
petalpaySignKeyId Yes String ID of Huawei's public key certificate for signature verification. For details about how to obtain the ID, see Uploading the Developer Public Key. Huawei uses the corresponding private key to sign the API response packet, and the developer uses the corresponding public key to verify the signature.
bodySign Yes String Signature of the request body parameters. Request parameters are sorted and concatenated based on the signing rules and then signed using SM2.
headerSign Yes String Signature of the headerSign parameter in the request. The signature values of the input parameters in the PayDevAuth object (all fields except headerSign) are sorted and concatenated based on the signing rules and then signed using SM2.

PromotionItem

Defines the promotion information cache model.

Parameter Mandatory Type Description
promotionId No String ID of the promotion type.
promotionType No String

Promotion type.

- PROMOTION: promotion activity

- COUPON: coupon

- VOUCHER: voucher

- CONSVOUCHER: consumption voucher
promotionAmount No Long Promotion amount, in cents.
promotionStatus No String

Promotion status.

- PROMO_FAILED: The promotion fails.

- PROMO_UNKNOW: The promotion status is unknown.

- PROMO_SUCCESS: The promotion is successful.

BillDownloadParam

Defines the bill download address information.

Parameter Mandatory Type Description
headers Yes Map Download authentication information.
method Yes String Calling method.
downloadUrl Yes String File download URL.

Map

Defines the fields related to the bill download information request header.

Parameter Mandatory Type Description
Authorization Yes String Authentication request header.
x-amz-content-sha256 Yes String Signature calculation mode.
x-amz-client-request-id Yes String ID of the signature client request.
x-amz-date Yes String Signature date ID.
connection Yes String Connection ID, which indicates whether the request uses a persistent connection or a short connection.
Host Yes String Request host.
user-agent Yes String Agent ID, which identifies the user agent that initiates the request.
Content-Type Yes String Resource type.

PayerIn

Defines the user information of the API request.

Parameter Mandatory Type Description
userClientIp No String IP address of the client when an order is placed.
credentialType No String

Certificate type. The maximum length is 2.

01: ID card (default value)

02: Military ID card

03: Passport

04: Household register

05: Soldier ID card

06: Mainland Travel Permit for Hong Kong and Macao Residents

07: Mainland Travel Permit for Taiwan Residents

08: Temporary ID card

09: Residence permit for foreigners

10: Police officer ID card

15: Residence Permit for Hong Kong/Macao Residents

16: Residence Permit for Taiwan Residents

99: Others
credentialIdNo Yes String

Certificate number. It is used to verify payment transactions authenticated by the same name.

This is a privacy field and must be encrypted before being transferred. For details, see Sensitive Information Processing.

The value contains a maximum of 128 characters.
realName No String

User real name. It is used to verify payment transactions authenticated by the same name.

This is a privacy field and must be encrypted before being transferred. For details, see Sensitive Information Processing.

The value contains a maximum of 256 characters.
textType No String

Text type. The maximum length is 2.

01: Full text of the ID card number, name, and certificate type (default value)

02: Last six digits of the ID card number, and full text of the name and certificate type

PayerOut

Defines the user information.

Parameter Mandatory Type Description
openId No String Unique ID of a user under the merchant app ID.
spOpenId No String Unique ID of a user under the partner merchant app ID.
subOpenId No String Unique ID of a user under the sub-merchant app ID.
userClientIp No String IP address of the client when an order is placed.
userClientIpMatched No Boolean

Whether the IP address is the same when the order is created and completed.

- true: yes

- false: no

ContractInfo

Defines the contract information.

Parameter Mandatory Type Description
planId Yes String Contract template ID. The template ID is generated by Huawei Pay when the merchant submits a permission application for withholding to Huawei Pay.
mercContractCode Yes String Merchant contract code. The contract code is passed when you request contract signing. It is generated by the merchant and must be unique. The value contains a maximum of 64 characters.
callbackUrl Yes String Callback notification URL. It must be an HTTPS URL that can be directly accessed from the external network. For details, see Notification Callback API Description. The value contains a maximum of 512 characters.

GoodDetail

Defines the goods details.

Parameter Mandatory Type Description
quantity Yes Integer Goods quantity.
unitPrice Yes Integer Unit price of the goods, in cents. The value must be greater than 0. If a value outside of the range is passed, the request will be abnormal.
goodsName Yes String Name of the goods. The value contains a maximum of 128 characters. If a value outside of the range is passed, the request will be abnormal.
goodsId No String ID of the goods. The value contains a maximum of 32 characters. If a value outside of the range is passed, the request will be abnormal.

SubMercOrder

Defines the sub-order information.

Parameter Mandatory Type Description
mercNo Yes String

Sub-merchant ID for receiving payment of the sub-order.

Note:

1. The sub-merchant ID must be the one transferred in the primary order associated with the sub-order.

2. The merchant IDs of sub-orders must be different. Orders of the same sub-merchant can be combined into one sub-order and do not need to be split.
tradeSummary Yes String Trade summary. Recommended format: Merchant app name-Product description. The value contains a maximum of 128 characters.
totalAmount Yes Long Total order amount, in cents. The value must be an integer greater than 0.
currency No String

Transaction currency. The value contains a maximum of 3 characters.

The default value is CNY. Currently, only this currency is supported.
goodsDetail No List<GoodDetail> List of goods details.
allocationType No String

Allocation type.

- NO_ALLOCATION: no allocation (default value)

- DELAY_ORDER_ALLOCATION: delayed allocation

Note: To use this field, contact your merchant contact person to apply for the allocation capability.
payload No String Information reserved by the merchant, which will be returned as-is in the query response and callback notification. The value contains a maximum of 255 characters.

SubOrderResult

Defines the sub-order result information.

Parameter Mandatory Type Description
sysTransOrderNo Yes String Transaction order number in the Huawei Pay system.
mercOrderNo Yes String Merchant order number, which is generated by the merchant and must be unique. The value contains 1 to 46 characters.
orderStatus Yes String

Order status.

- TRX_SUCCESS: The transaction is successful.

- TRX_FAILED: The transaction failed.

- TRX_APPLY: The transaction is being processed.
payload No String Reserved information. If this parameter is passed in a merchant request, it will be returned as-is.
currency No String

Transaction currency. The value contains a maximum of 3 characters.

The default value is CNY. Currently, only this currency is supported.
totalAmount No Long Total transaction amount, in cents.
payerAmount No Long Actual payment amount, in cents.
promotionAmount No Long Promotion amount, in cents.
finishTime No String Time when the sub-order payment is completed, in UTC time format (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
paymentTools No String

Payment method.

- WECHAT_MICROPAY: WeChat Pay connected through Huawei Pay

- AGMT: payment using a debit or credit card based on an agreement

- ACCT: account balance

- HUAWEIPAY: Huawei Pay
promotionDetail No List<PromotionItem> Promotion information.

payInfo

Defines the input parameter payInfo of the third-party payment service API. The value is a JSON string. The following is an example:

// PayMethod.WECHAT_PAY: '{"appId":"***","partnerId":"***","prepayId":"***","packageValue":"***","nonceStr":"***","timeStamp":"***","sign":"***","extData":"***","token":"***"}'
// PayMethod.ALI_PAY: '{"orderInfo":"***", "token":"***"}'
// PayMethod.WECHAT_MINI_PROGRAM: '{"userName":"original ID", "path":"mini program start path", "miniProgramType":"mini program type, 0: official version; 1: development version; 2: trial version. Default value : 0", "extData":"***", "token":"***"}'

The parameters to be passed vary depending on the third-party payment method (PayMethod) used to start the checkout.

The following table lists the parameters required by Huawei Pay.

Parameter Mandatory Type Description
token Yes string Client token. This parameter is returned in the payment information response PayResult (hybrid payment scenario) or PickerResult (external payment scenario) when the unified checkout screen is displayed.

SelectPromotions

Defines the request information of the platform coupon information.

Parameter Mandatory Type Description
platCoupons No List<PlatCoupon> Platform coupon information. For details about how to obtain it, please refer to the API for querying platform coupons available to a user.
isPlatCouponRecommend No Boolean

Whether to recommend platform coupons to the user.

- true (default): platCoupons can be used to specify the recommended platform coupons. If platCoupons is not specified, the default logic of Huawei Pay is used.

- false: The platCoupons field does not take effect.

PlatCoupon

Defines the data model of the platform coupon information.

Parameter Mandatory Type Description
platCouponNo Yes String Platform coupon ID.
openid Yes String User ID.
sceneParam Yes String

Coupon factor, in JSON string format. For details, see sceneParams.

For example, if the order amount is limited for a platform coupon, the value is {"tradeOrderAmount": 200}.

RequestSceneInfo

Queries the platform coupon information of a user.

Parameter Mandatory Type Description
sceneId Yes String Scenario ID, which is a unique string generated by the merchant and is used to match the response result.
sceneParams Yes Map<String, Object> Extended parameter of the scenario, which is used to match the conditions for using platform coupons. For details about some parameters, see @ohos.deviceInfo (Device Information).

sceneParams

Defines the platform coupon scenario parameters.

Parameter Mandatory Type Description
tradeOrderAmount Yes Integer Order amount, in cents.
bundleType Yes String Bundle type. Example: APP (HarmonyOS app) or ATOMIC_SERVICE (atomic service)
bundleName No String Bundle name.
productModel No String Product model. Example: ALN-AL00
deviceType No String Device type. For details, see deviceTypes. Example: phone
osType Yes String

System type. The options are as follows:

- HMOS: HarmonyOS operating system

ServCouponInfo

Defines the coupon information.

Parameter Mandatory Type Description
couponCode Yes String Coupon code.
batchNo Yes String Coupon batch
couponType Yes String

Coupon batch type. The options are as follows:

- NORMAL: fixed-amount threshold coupon.
effectiveTime Yes Long Timestamp of the start time when the coupon can be used.
expireTime Yes Long Timestamp of the expiration time of the coupon claimed by a user.
amount No Integer Discount amount (coupon face value), in cents.
displayInfo No SimpleDisplayInfo Simple display information of the coupon.

SimpleDisplayInfo

Simple display information of the coupon.

Parameter Mandatory Type Description
couponDesc No String Coupon description.
logoUrl No String URL of the logo.

SceneMatchedCouponNos

Defines the coupon number information matched in each scenario.

Parameter Mandatory Type Description
sceneId No String Scenario ID.
couponNos No List<String> Coupon number list.

CouponSendRule

Defines the coupon distribution rules.

Parameter Mandatory Type Description
maxCoupons Yes Integer

Maximum number of coupons that can be distributed in batch. The maximum value is 1000000.

Special rule: The value range is 0 ≤ value ≤ 1000000.

Note: When a batch is created, if the value of couponCodeMode is MERCHANT_UPLOAD, this parameter must be set to 0.
maxCouponsPerUser Yes Integer

Maximum number of coupons that a user can claim. The maximum value is 100.

Note: When a batch is created, if the value of couponCodeMode is HWPAY_MODE or MERCHANT_API, the user quota must be less than or equal to the total batch quota.
maxCouponsByDay No Integer

Maximum number of coupons that can be distributed in a single day. The maximum value is 1000000.

Special rule: The value range is 1 ≤ value ≤ 1000000.

Note: When a batch is created, if the value of couponCodeMode is HWPAY_MODE or MERCHANT_API, the daily quota must be less than or equal to the total batch quota.
sendEntrance Yes String

Where merchant coupons are distributed.

PLATFORM_PUSH: platform traffic

MERC_SELF_CHANNEL: merchant-owned traffic
naturalPersonLimit No boolean

Number of times that a natural person can claim coupons for all accounts under the same certificate number.

- true: yes

- false: no (default value)

Note: This parameter is specified by the maxCouponsPerUser parameter and is not supported in the current version.
preventApiAbuse No boolean

Whether to enable suspicious account blocking.

- true: yes

- false: no (default value)

Note: If this parameter is set to true, the device information of the user must be reported in the coupon distribution information. For details, see the coupon distribution API.

CouponUseRuleMod

Defines the coupon use rules.

Parameter Mandatory Type Description
useMethod Yes List<String>

Use method.

- FASTAPP: app or atomic service
useAppId No List<String> This parameter is mandatory when the coupon is used in an online app or atomic service. The maximum length of a list is 8. Each element contains 1 to 32 characters.

SendCountInfo

Defines the information about the total number of coupons distributed in batch.

Parameter Mandatory Type Description
totalSendNum No Integer Number of coupons distributed in batch. This parameter is returned for the threshold discount, percentage discount, and exchange offer types.
totalSendAmount No Integer Budget amount distributed in batch. This parameter is returned for the threshold discount type.
todaySendNum No Integer Number of coupons distributed in batch on the current day. This parameter is returned for the threshold discount, percentage discount, and exchange offer types when the daily distribution limit is set.
todaySendAmount No Integer Budget amount distributed in batch on the current day. This parameter is returned for the threshold discount type when the daily distribution limit is set.

DeviceInfo

Defines the user device information.

Parameter Mandatory Type Description
deviceId No String Device ID. The value contains a maximum of 128 characters.
deviceIdType No String Device ID type, such as UDID and OAID. The value contains a maximum of 8 characters.
deviceModel No String Device model. The value contains a maximum of 32 characters.
riskToken No String riskToken obtained through the safetyDetect API. The value contains a maximum of 512 characters.
clientIp No String Ip address of the client during coupon claiming, which is used for risk control. The value contains a maximum of 64 characters.
clientVersion No String Version information about the client during coupon claiming, which is used for risk control. The value contains a maximum of 32 characters.
packageName No String Package name of the client app during coupon claiming, which is used for risk control. The value contains a maximum of 64 characters.

CouponNotice

Defines the additional information about a notification.

Parameter Mandatory Type Description
receiveTime Yes String Time when the coupon is distributed to a user. The value is in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ, where yyyy-MM-DD indicates the year, month, and day, T indicates the start of the time element, HH:mm:ss.SSS indicates the hour, minute, second, and millisecond, and Z indicates the time zone. For example, 2023-03-28T17:50:12.000+0800 indicates 17:50:12 on March 28, 2023 (Beijing time). Note: The time must be an accurate UTC time.
batchNo Yes String Batch number.
couponCodes No List<String> List of coupon codes in the batch. This parameter is used to specify the coupon codes externally when the batch is created or to return the coupon codes when the result is returned.

UploadFailReason

Defines the information about the code that fails to be uploaded.

Parameter Mandatory Type Description
couponCode Yes String Coupon code uploaded by the merchant through the API.
subCode No String Error code indicating that the coupon code fails to be uploaded.
subMessage No String Error message about the upload failure.

DiscountCoupon

Defines the rules for using discount coupons.

Parameter Mandatory Type Description
discountPercent Yes Integer Discount percentage. For example, 86 indicates an 86% discount.
transactionMinimum Yes Integer

Consumption threshold, in cents.

Special rule: The value range is 1 ≤ value ≤ 10000000.

CouponSendRuleMod

Defines the coupon distribution rule.

Parameter Mandatory Type Description
preventApiAbuse No boolean

Whether to enable suspicious account blocking (such as black and gray industry accounts).

- true: yes

- false: no (default value)

Note: If this parameter is left empty, the value is false by default. If this parameter is set to true, the device information of the user must be reported in the coupon distribution information. For details, please refer to the coupon distribution API.

CouponUseRule

Defines the coupon use rules.

Parameter Mandatory Type Description
availableTime No CouponAvailableTime Date-based use conditions of the coupon.
fixedNormalCoupon No FixedNormalCoupon

Use rules of the fixed-amount threshold coupon.

Note: This parameter is mandatory when couponType is NORMAL.
discountCoupon No DiscountCoupon

Use rules of the discount coupon.

Note: This parameter is mandatory when couponType is DISCOUNT.
exchangeCoupon No ExchangeCoupon

Use rules of the exchange coupon.

Note: This parameter is mandatory when the coupon type (couponType) is exchange coupon (EXCHANGE).
useMethod Yes List<String>

Use method.

- FASTAPP: app or atomic service
useAppId No List<String> This parameter is mandatory when the use method is app or atomic service. A maximum of eight IDs can be configured. Each app ID contains 1 to 32 characters.

CouponInfo

Defines the batch information and code of the coupon to be distributed.

Parameter Mandatory Type Description
couponCode Yes String Coupon code.
batchNo Yes String Coupon batch ID.
batchName Yes String Coupon batch name.
belongMerchant Yes String ID of the merchant to which a batch belongs.
comment No String Batch comment, which are used to customize information. The value contains a maximum of 64 characters. Each Chinese character, English letter, or digit counts as one character.
goodsName Yes String Applicable goods. The value contains a maximum of 15 characters. Each Chinese character, English letter, or digit counts as one character.
couponType Yes String

Batch type.

- NORMAL: threshold discount coupon

- DISCOUNT: discount coupon

- EXCHANGE: exchange coupon
couponState Yes String

Merchant coupon state.

- SENDED: available

- USED: used

- EXPIRED: expired

- DEACTIVATED: deactivated
displayInfo No CouponDisplayInfo Coupon display information.
couponUseRule Yes CouponUseRule Coupon use rules.
availableStartTime Yes String Start time when the coupon can be used. The value is in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ, where yyyy-MM-DD indicates the year, month, and day, T indicates the start of the time element, HH:mm:ss.SSS indicates the hour, minute, second, and millisecond, and Z indicates the time zone. For example, 2023-03-28T17:50:12.000+0800 indicates 17:50:12 on March 28, 2023 (Beijing time).
expireTime Yes String Expiration time of the coupon claimed by a user. The value is in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ, where yyyy-MM-DD indicates the year, month, and day, T indicates the start of the time element, HH:mm:ss.SSS indicates the hour, minute, second, and millisecond, and Z indicates the time zone. For example, 2023-03-28T17:50:12.000+0800 indicates 17:50:12 on March 28, 2023 (Beijing time).
receiveTime Yes String Time when a user claims the coupon.
distributeRequestNo Yes String Unique credential passed during coupon distribution.
useRequestNo No String Unique credential passed during use. (If the coupon has been used, this field is returned.)
useTime No String Time when a coupon is used. (If the coupon has been used, this field is returned.) The value is in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ, where yyyy-MM-DD indicates the year, month, and day, T indicates the start of the time element, HH:mm:ss.SSS indicates the hour, minute, second, and millisecond, and Z indicates the time zone. For example, 2023-03-28T17:50:12.000+0800 indicates 17:50:12 on March 28, 2023 (Beijing time).
lastRefundRequestNo No String Unique credential passed during the last refund. (If the coupon has been refunded, this field is returned.)
lastRefundTime No String Time when the coupon was last refunded. (If the coupon has been refunded, this field is returned.) The value is in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ. yyyy-MM-DD indicates the year, month, and day. T indicates the start of the time element. HH:mm:ss.SSS indicates the hour, minute, and second. Z indicates the corresponding time zone. For example, 2023-03-28T17:50:12.000+0800 indicates 17:50:12 on March 28, 2023 (Beijing time).
deactivateRequestNo No String Unique credential passed when the coupon is deactivated. (If a coupon has been deactivated, this field is returned.)
deactivateTime No String Time when the coupon is deactivated. (If a coupon has been deactivated, this field is returned.) The value is in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ, where yyyy-MM-DD indicates the year, month, and day, T indicates the start of the time element, HH:mm:ss.SSS indicates the hour, minute, second, and millisecond, and Z indicates the time zone. For example, 2023-03-28T17:50:12.000+0800 indicates 17:50:12 on March 28, 2023 (Beijing time).
deactivateReason No String Reason why the coupon is deactivated. (If a coupon has been deactivated, this field may be returned.)

CouponBatchDetailExtInfo

Defines the coupon batch query response.

Parameter Mandatory Type Description
batchStatus Yes String

Current status of the batch.

- DEACTIVATED: deactivated

- ACTIVATED: activated

- EXPIRED: expired
batchNo Yes String Coupon batch number.
couponCodeCount No CouponCodeCount Number of coupon codes in a batch.
sendCountInfo No SendCountInfo Total number of coupons distributed in batch.
batchName Yes String Batch name.
belongMerchant Yes String

ID of the merchant to which a batch belongs. Note:

- In the direct connection mode, the value is the direct merchant ID.

- In the service provider mode, the value is the special merchant ID.

- In the platform merchant mode, the value is the platform sub-merchant ID.
comment No String Batch description.
goodsName Yes String Applicable goods, which describes the goods to which a batch is applicable.
couponType Yes String

Coupon type.

- NORMAL: threshold discount coupon

- DISCOUNT: discount coupon

- EXCHANGE: exchange coupon
couponUseRule Yes CouponUseRule Coupon use rule.
couponSendRule Yes CouponSendRule Coupon distribution rule.
displayInfo Yes CouponDisplayInfo Coupon display information.
couponCodeMode Yes String

Coupon code specified by the merchant during coupon distribution. The merchant uploads custom codes. When distributing coupons, the system randomly selects the uploaded coupon codes.

- HWPAY_MODE: The coupon codes are automatically allocated, and the merchant does not need to save codes.

- MERCHANT_API: The coupon codes need to be specified when the coupon distribution API is called.

- MERCHANT_UPLOAD: The API for uploading pre-saved codes needs to be called to upload codes. When the coupon distribution API is called, no code needs to be specified.
notifyConfig No NotifyConfig Notification callback configuration.

CurrentDayTime

Defines the available time on the current day.

Parameter Mandatory Type Description
beginTime No Integer Start time of the available time on the current day, in seconds. The value 1 indicates 00:00:01 on the current day.
endTime No Integer End time of the available time on the current day, in seconds. The value 86399 indicates 23:59:59 on the current day.

IrregularyTime

Defines the irregular validity period.

Parameter Mandatory Type Description
beginTime No String

Begin time. The value is in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ, where yyyy-MM-DD indicates the year, month, and day, T indicates the start of the time element, HH:mm:ss.SSS indicates the hour, minute, second, and millisecond, and Z indicates the time zone. For example, 2023-03-28T17:50:12.000+0800 indicates 17:50:12 on March 28, 2023 (Beijing time).

Note: The time must be an accurate UTC time.
endTime No String

End time. The value is in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ, where yyyy-MM-DD indicates the year, month, and day, T indicates the start of the time element, HH:mm:ss.SSS indicates the hour, minute, second, and millisecond, and Z indicates the time zone. For example, 2023-03-28T17:50:12.000+0800 indicates 17:50:12 on March 28, 2023 (Beijing time).

Note: The time must be an accurate UTC time.

FailResult

Defines the result of coupon distribution failure.

Parameter Mandatory Type Description
subCode Yes String Result code of the failure.
subMessage No String Result description of the failure.
number No Integer Number of failures.
batchNo Yes String Batch number.
couponCodes No List<String> List of coupon codes in the batch. This parameter is used to specify the coupon codes externally when the batch is created or to return the coupon codes when the result is returned.

CouponDisplayInfo

Coupon display information.

Parameter Mandatory Type Description
merchantLogoUrl Yes String URL of the merchant logo. The value contains 1 to 256 characters.
merchantName Yes String Short name of the merchant. The value contains 1 to 16 characters.
backgroundColor No String Background color. The default value is #DF674F (red). A dark color is recommended. The value contains a maximum of 16 characters.
couponTitle No String Coupon title. If this parameter is not set, the value is the same as the coupon batch name. The value contains a maximum of 64 characters.
description No String Usage instructions, which are used to describe the detailed activity rules. The value contains a maximum of 5120 characters.
jumpUrl No String Redirection URL. The merchant app and atomic service URLs are supported, but the app URL and fastapp URL are not supported. If this parameter is left empty, redirection is not performed in the Huawei traffic scenario. The value contains a maximum of 1024 characters.
nextJumpUrl No String Redirection URL for HarmonyOS Next. The app linking for atomic service is supported, but the app URL is not supported. The URL and fastapp URL are supported. If this parameter is left empty, redirection is not performed in the Huawei traffic scenario. The value contains a maximum of 1024 characters.
diversionName No String Display name of the traffic diversion column. The value contains a maximum of 16 characters.

ExchangeCoupon

Use rules of the exchange coupon.

Parameter Mandatory Type Description
exchangePrice Yes Integer

Exchange price of a single product, in cents.

Special rule: The value range is 0 ≤ value ≤ 10000000.
transactionMinimum Yes Integer

Consumption threshold, in cents.

Special rule: The value range is 1 ≤ value ≤ 10000000.

NotifyConfig

Notification callback configuration.

Parameter Mandatory Type Description
notifyAppId No String

App ID for event notification. The value contains a maximum of 32 characters. This parameter is used to calculate the openid of the user who performs the operation (for example, the user who claims the coupon) during callback notification. This parameter is optional when the merchant distributes coupons in their private domain. If this parameter is not set when coupons are distributed in the Huawei traffic scenario, the merchant will not be notified of the coupon distribution result.

Note: This parameter is mandatory when coupons are distributed in the Huawei traffic scenario. After this parameter is set, you are advised not to change its value because the openid will change after the modification.
notifyUrl No String URL for event notification. The value contains a maximum of 256 characters. This parameter is used for notifying the merchant of the coupon distribution result when the merchant distributes coupons in the private domain. If this parameter is not set, no notification will be sent. The callback URL must start with https.

SendCouponInfo

Defines the batch information and code of the coupon to be distributed.

Parameter Mandatory Type Description
sendNum Yes Integer Number of coupons to be distributed in the next distribution of the batch. The default value is 1.
batchNo Yes String Batch number.
couponCodes No List<String> List of coupon codes in the batch. This parameter is used to specify the coupon codes externally when the batch is created or to return the coupon codes when the result is returned. The list contains a maximum of 10 elements, and each element contains 1 to 32 characters.

CouponCodeCount

Number of coupon codes in a batch.

Parameter Mandatory Type Description
totalCount Yes Integer Total number of codes uploaded in the batch.
availableCount Yes Integer Number of available codes in the batch.

FixedNormalCoupon

Use rules of the fixed-amount threshold coupon.

Parameter Mandatory Type Description
discountAmount Yes Integer Discount amount (coupon face value), in cents. Special rule: The value range is 1 ≤ value ≤ 10000000.
transactionMinimum Yes Integer

Consumption threshold, in cents.

Special rule: The value range is 1 ≤ value ≤ 10000000.

BatchCoupons

Describes the result of successful coupon distribution.

Parameter Mandatory Type Description
batchNo Yes String Batch number.
couponCodes No List<String> List of coupon codes in the batch. This parameter is used to specify the coupon codes externally when the batch is created or to return the coupon codes when the result is returned.

CouponAvailableTime

Date-based use conditions of the coupon.

Parameter Mandatory Type Description
beginTime Yes String

Batch start time. The value is a string of 28 characters in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ. yyyy-MM-DD indicates the year, month, and day. T indicates the start of the time element. HH:mm:ss.SSS indicates the hour, minute, and second. Z indicates the corresponding time zone. For example, 2023-03-28T17:50:12.000+0800 indicates 17:50:12 on March 28, 2023 (Beijing time).

Note:

- The time must be an accurate UTC time.

- The maximum validity period of a merchant coupon is one year.
endTime Yes String

Batch end time. The value is a string of 28 characters in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ. yyyy-MM-DD indicates the year, month, and day. T indicates the start of the time element. HH:mm:ss.SSS indicates the hour, minute, and second. Z indicates the corresponding time zone. For example, 2023-03-28T17:50:12.000+0800 indicates 17:50:12 on March 28, 2023 (Beijing time).

Note:

- The time must be an accurate UTC time.

- The maximum validity period of a merchant coupon is one year.

- This validity period also affects the validity period of the coupon received by the user. Since the coupon is displayed in the wallet with the date specified, it is recommended that the end time be set to 23:59:59 of the end date.
dayAfterReceive No Integer Validity period of a coupon within the date range. The coupon is valid within x days after it takes effect. The value ranges from 1 to 365. For example, if the coupon is valid within one day after it takes effect, set this parameter to 1. If the coupon is valid within two days after it takes effect, set this field to 2. Note that if a user claims a merchant coupon before the validity period starts, the validity period starts from the first day of the validity period. If a user claims a merchant coupon within the validity period, the validity period starts from the day when the user claims the coupon. Regardless of when a user claims a merchant coupon, the coupon will become unavailable after the activity validity period ends.
availableWeek No AvailableWeek Fixed validity period. You can set multiple validity periods in multiple weeks, for example, 10:00 to 18:00 every Tuesday.
irregularyTime No List<IrregularyTime> Irregular validity period.
waitDaysAfterReceive No Integer Number of days a user needs to wait after claiming a coupon for it to take effect within the date range. The value ranges from 0 to 365. For example, if the coupon takes effect on the day it is claimed, leave this parameter empty. If the coupon takes effect on the second day after it is claimed, set this parameter to 1. The rest can be deduced by analogy. If a user claims a merchant coupon before the validity period starts, the validity period starts from the first day of the validity period. If a user claims a merchant coupon within the validity period, the validity period starts from the day when the user claims the coupon. Regardless of when the user claims the merchant coupon, the merchant coupon is unavailable after the activity ends.

AvailableWeek

Defines the validity period in a fixed cycle.

Parameter Mandatory Type Description
weekDay No List<Integer> Days in a week when the coupon is available. The value 0 indicates Sunday. This parameter is mandatory when dayTime is specified.
dayTime No List<CurrentDayTime> Available time segments on the current day. A maximum of two time segments are allowed. For details, see the definition of the CurrentDayTime structure.

CouponDisplayInfoMod

Coupon display information.

Parameter Mandatory Type Description
backgroundColor No String Background color. The default value is #DF674F (red). A dark color is recommended. The value contains a maximum of 16 characters.
couponTitle No String Coupon title. If this parameter is not set, the value is the same as the coupon batch name. The value contains a maximum of 64 characters.
description No String Usage instructions, which are used to describe the detailed activity rules. The value contains a maximum of 5120 characters.
jumpUrl No String Redirection URL. The merchant app and atomic service URLs are supported, but the app URL and fastapp URL are not supported. If this parameter is left empty, redirection is not performed in the Huawei traffic scenario. The value contains a maximum of 1024 characters.
nextJumpUrl No String Redirection URL for HarmonyOS Next. The app linking for atomic service is supported, but the app URL is not supported. The URL and fastapp URL are supported. If this parameter is left empty, redirection is not performed in the Huawei traffic scenario. The value contains a maximum of 1024 characters.
diversionName No String Display name of the traffic diversion column. The value contains a maximum of 16 characters.