Field

Data Type

Required

Description

Example

benefitUseRequestId

String

Yes

Indicates the unique ID assigned by the ISV to identify a synchronization request of the used benefit.

• Maximum length: 64 characters
• Characters not allowed: special characters such as @ # ?

Note: This field is an idempotency field. For synchronization requests of the used benefit, which are initiated with the same benefitUsedSyncRequestId, our server must return the same result. For details about API idempotency, see the Idempotency chapter.

-

userId

String

Yes

Indicates the unique ID assigned by the super app to identify a user who collects the benefit..

• Maximum length: 32 characters
• Characters not allowed: special characters such as @ # ?

-

clientCode

String

Yes

Indicates codes to identify different super apps. Valid values are:

• TRUEMONEY: TrueMoney
• ALIPAY_HK: Alipay HK

• TNG: Touch 'n Go
• ALIPAY_CN: Alipay CN

• GCASH: Gcash
• DANA: Dana

• KAKAOPAY: KakaoPay
• BKASH: bKash

• CHOPE: Chope
• LAZADA: Lazada

-

benefitInstanceId

String

Yes

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

• Maximum length: 64 characters
• Characters not allowed: special characters such as @ # ?

-

benefitTemplateId

String

Yes

Indicates the unique ID assigned by the ISV to identify one type of benefit.

• Maximum length: 64 characters
• Characters not allowed: special characters such as @ # ?

-

benefitUseDate

String

Yes

Indicates the date and time when the user redeems the benefit.

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"

useScene

String

Yes

Indicates the scenarios to use the benefit. Valid values are:

• INSTORE: use the benefit in physical stores.
• MINI_PROGRAM: use the benefit in mini programs.

• OTHER: use the benefit in other scenarios except for physical stores and mini programs.

-

usedAmount

Amount

No

Indicates the used amount of the benefit.

• This field is required when the amount of the benefit is partially used.
• This field can be Null when the total amount of the benefit is used.

-

benefitCode

String

No

Indicates that the user can redeem the benefit with a code.

• Maximum length: 64 characters
• Characters not allowed: special characters such as @ # ?

• Can be empty

-

benefitUrl

String

No

Indicates that the user can redeem the benefit with an URL.

• Maximum length: 256 characters

-

extendInfo

String

No

Indicates the extended information about this API.

• Maximum length: 2048 characters
• Characters not allowed: special characters such as @ # ?

• Can be empty

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

Field

Data type

Required

Description

result

Result

Yes

Indicates the request result, such as status and error codes.

Result status

Description 

S

The used benefit is synchronized to our server successfully.

The corresponding result.resultCode is SUCCESS and the result.resultMessage is Success.

U

The synchronization status of the used benefit is unknown. 

The corresponding result.resultCode is UNKNOWN_EXCEPTION and result.resultMessage is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section.

F

The used benefit failed to synchronize to our server.

The corresponding result.resultCode and result.resultMessage are various based on different situations. For details, see the following Error codes section.