Data dictionary

Property

Data Type

Required

Description

Example

resultStatus

String

Yes

Result status. Valid values are:

• S: The result status is successful.
• F: The result status failed.

• U: The result status is unknown.

"S"

resultCode

String

No

Result code

Maximum length: 64 characters

"PARAM_ILLEGAL"

resultMessage

String

No

Result message that describes the result code in detail.

Maximum length: 256 characters

Property

Data Type

Required

Description

Example

currency

String 

Yes

Indicates the three-character ISO-4217 currency code.

• Maximum length: 3 characters

"USD"

value

String

Yes

Indicates a string that encloses a positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 dollars to charge $100, a zero-decimal currency).

• Maximum length: 16 characters

"100"

Property

Data Type

Required

Description

Example

benefitInstanceId

String

Yes

Indicates the unique ID assigned by the ISV to identify a benefit instance.

• Maximum length: 64 characters

"abcd1234"

benefitTemplateId

String

Yes

Indicates the unique ID assigned by the ISV to identify a benefit template.

• Maximum length: 64 characters

"202110013121247125127141241"

amount

Amount

No

Indicates the benefit amount.

{

"currency": "USD",

"value": "10000"

}

status

String

Yes

Indicates the statuses of a benefit. Valid values are:

• ACTIVATED: The benefit is activated.
• REVERSED: The benefit is reversed.

• USED: The benefit is used.
• EXPIRED: The benefit is expired.

"ACTIVATED"

activateTime

String

Yes

Indicates the actual time when a benefit is activated.

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".

UTC+05:30: "2019-04-04T12:08:56+05:30"

UTC+0: "2019-04-04T12:08:56Z"

expireTime

String

Yes

Indicates the actual time when a benefit is expired.

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".

UTC+05:30: "2019-04-04T12:08:56+05:30"

UTC+0: "2019-04-04T12:08:56Z"

benefitCode

String

No

Indicates the code value of a benefit.

• Maximum length: 64 characters

benefitPin

String

No

Indicates the pin value of a benefit.

• Maximum length: 64 characters

benefitUrl

String

No

Indicates the URL of a benefit.

• Maximum length: 256 characters

extendInfo

String

No

Indicates the extended information.

• Maximum length: 2048 characters

"{\"k1\":\"v1\",\"k2\":\"v2\"}"

Property

Data Type

Required

Description

Example

type

String

Yes

Indicates the types of time. Valid values are:

• ABSOLUTE: the absolute time
• RELATIVE: the relative time

Maximum length: 64 characters.

"RELATIVE"

activeTime

String

No

Indicates the activation time after collecting a benefit.

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".

Note: This field is required when the value of type is ABSOLUTE.

UTC+05:30: "2019-04-04T12:08:56+05:30"

UTC+0: "2019-04-04T12:08:56Z"

expireTime

String

No

Indicates the expiration time after collecting a benefit.

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".

Note: This field is required when the value of type is ABSOLUTE.

UTC+05:30: "2019-04-04T12:08:56+05:30"

UTC+0: "2019-04-04T12:08:56Z"

activeSeconds

Integer

No

Indicates the number of seconds from the time a benefit is collected to the time the benefit is activated.

The format must be an Integer. For example, 2592000 indicates 30 days (30*24*60*60 seconds).

Note: This field is required when the value of type is RELATIVE.

2592000

expireSeconds

Integer

No

Indicates the number of seconds from the time a benefit is activated to the time the benefit is expired.

The format must be an Integer. For example, 2592000 indicates 30 days (30*24*60*60 seconds).

Note: This field is required when the value of type is RELATIVE.

2592000

Property

Data Type

Required

Description

Example

type

String

Yes

Indicates the types of benefit budget. Valid values are:

• NOLIMIT: unlimited budget
• AMOUNT: the amount type

• COUNT: the quantity type

For example, "COUNT".

"COUNT"

amount

Amount

No

Indicates the amount of benefit budget.

Note: This field is required when the value of type is AMOUNT.

count

Integer

No

Indicates the quantity of benefit budget. For example, "100".

Note: This field is required when the value of type is COUNT.

100

Property

Data Type

Required

Description

Example

merchantId

String

Yes

Indicates the unique ID assigned by the ISV to identify a merchant.

Maximum length: 64 characters

name

String

Yes

Indicates the merchant's name.

Maximum length: 128 characters

"Burger King"

logoImage

Image

Yes

Indicates the logo image of the merchant.

mcc

String

No

Indicates Merchant Category Code.

Maximum length: 32 characters

Property

Data Type

Required

Description

type

String

Yes

Indicates the types of images. Valid values are:

• BASE64: base64 string
• URL: image URL

content

String

Yes

Indicates the content of the image, including base64 string or image URL.

The requirements of base64 string:

• Maximum size: 100KB
• Image format: image/jpeg, image/jpg, image/png

The requirement of image URL:

• Use an image URL that can be directly used by the super app. We do not convert the image URL, but directly transmits it to the super app.

Property

Data Type

Required

Description

Example

type

String

Yes

Indicates the types of benefits. Valid values are:

• REDUCE_BY: Take {amount} off for purchase over {amount}.
• REDUCE_TO: Reduce to {amount}.

• CASH_BACK: Enjoy {amount} back for purchase over {amount}.
• GIFT: Get a gift with purchase over {amount}.

• DISCOUNT: Take {percentage} off the usual price.

thresholdAmount

Amount

No

Indicates the minimum amount required to enjoy a benefit. You can enjoy the benefit if your purchase reaches the threshold amount. For example, a voucher saves 10 yuan on every 200 yuan, thresholdAmount is 200 yuan.

Note: This field is required when the value of type is REDUCE_BY, CASH_BACK, or GIFT.

amount

Amount

No

Indicates the benefit amount.

Note: This field is required when the value of type is REDUCE_BY, REDUCE_TO, or CASH_BACK.

• REDUCE_BY or CASH_BACK: You can enjoy the benefit if your purchase reaches the threshold amount.
• REDUCE_TO: Reduce to {amount}.

ratio

String

No

Indicates the percentage of the discount.

• Value range: 0-1
• Accurate to two decimal places.

For example, 12 percent off means the discount ratio is "0.88".

Note: This field is required when the value of type is DISCOUNT.

"0.88"

giftDescription

String

No

Indicates the description of gifts. For example, "Get a gift".

• Maximum length: 256 characters

Note: This field is required when the value of type is GIFT.

"Get a gift"

Property

Data Type

Required

Description

Example

type

String

Yes

Indicates the frequencies to collect the benefit. Valid values are:

• DAY: indicates the number of times to collect the benefit per day
• WEEK: indicates the number of times to collect the benefit per week

• MONTH: indicates the number of times to collect the benefit per month
• YEAR: indicates the number of times to collect the benefit per year

• LIFE_TIME: indicates the number of times to collect the benefit in whole life

count

Integer

Yes

Indicates the specific number of times to collect the benefit with different collection frequencies (DAY, WEEK, MONTH, YEAR, or LIFE_TIME).

• Value range: unlimited