Data dictionary

Field

Data type

Required

Description

currency

String 

Yes

The 3-character currency code that follows ISO-4217 standard.

Maximum length: 3 characters

value

Integer

Yes

Indicates the charged amount, which is in currency's smallest unit. That is, 100 cents to charge 1.00 dollar, or 100 dollar to charge 100 dollar, a zero-decimal currency.

Value range: 0-2147483647

Field

Data type

Required

Description

Example

fieldCode

String 

Yes

The personal information provided by the user in the following scenarios:

• The registration of membership card, where this information is specified in the registrationFields parameter in the notifyCardRegistration API
• The update of membership card detail, where this information is specified in the cardFields parameter in the updateCardDetail API

Valid values are:

• FIRST_NAME: Indicates the user's first name
• LAST_NAME: Indicates the user's last name
• USER_NAME: Indicates the user's username that is used for display
• USER_SALUTATION: Indicates the user's salutation
• GENDER: Indicates the user's gender
• BIRTH_DATE: Indicates the user's birth date
• MOBILE_PHONE: Indicates the user's phone number
• EMAIL: Indicates the user's email address
• PASSWORD: Indicates the user's login password that is encrypted with AES256

"USER_NAME"

fieldValue

String

Yes

The specific value of the card information specified in the above fieldCode parameter.

• Maximum length: 256 characters

Notes:

• When the value of fieldCode is FIRST_NAME, LAST_NAME, or USER_NAME, the maximum length of fieldValue is 20 characters.
• When the value of fieldCode is USER_SALUTATION, the valid values of its fieldValue are:

• MR.: Indicates the user's salutation is Mr.
• MS.: Indicates the user's salutation is Ms.
• MRS.: Indicates the user's salutation is Mrs.
• MISS: Indicates the user's salutation is Miss

• When the value of fieldCode is GENDER, the valid values of fieldValue are:

• F: Indicates the user's gender is female
• M: Indicates the user's gender is male

• When the value of fieldCode is BIRTH_DATE, fieldValue follows the YYYY-MM-DD format, for example, 2002-07-25.
• When the value of fieldCode is MOBILE_PHONE, fieldValue follows the [+][country code][area code without leading 0][local phone number] format, for example, +658812****.
• When the value of fieldCode is EMAIL, fieldValue needs to include an at sign (@), and allows the following characters:

• Uppercase letters from A to Z
• Lowercase letters from a to z
• Arabic numerals from 0 to 9
• Special characters, such as underline (_) and minus (-)

• When the value of fieldCode is PASSWORD, filedValue is a string that is calculated by encrypting the plaintext password with AES256. The plaintext password needs to have a minimum of eight characters, including at least one uppercase letter, one lowercase letter, one digit, and one special character.

{

"fieldCode": "GENDER",

"fieldValue": "M"

}

Field

Data type

Required

Description

Example

fieldCode

String 

Yes

Indicates the card details defined by the merchant when the user registers the membership card, which is specified in the cardFields parameter in the issueCard API or the inquireCardDetail API.

Valid values are:

• POINT: The reward points
• BALANCE: The membership card balance
• LEVEL: The membership level
• GROWTH: The membership growth value
• FIRST_NAME: The user's first name
• LAST_NAME: The user's last name
• USER_NAME: The user's username that is used for display
• USER_SALUTATION: The user's salutation
• GENDER: The user's gender
• BIRTH_DATE: The user's birth date
• MOBILE_PHONE: The user's phone number
• EMAIL: The user's email address
• PASSWORD: The user's login password that is encrypted with AES256

"POINT"

fieldValue

String

Yes

Indicates the specific value of the card information specified in the above fieldCode parameter.

• Maximum length: 256 characters

Note:

• When the value of fieldCode is POINT, fieldValue is an integer that indicates the number of points (Value range: 0-99,999).
• When the value of fieldCode is BALANCE, fieldValue is in JSON format containing an Amount object, which indicates the amount of the card balance.
• When the value of fieldCode is LEVEL, the maximum length of fieldValue is 10 characters.
• When the value of fieldCode is GROWTH, fieldValue may be an integer or percentage, or in JSON format containing an Amount object.

• When fieldValue is an integer, value range is 0 - unlimited.
• When fieldValue is a percentage, no percent sign is required, up to two decimal places (Value range: 0.00-100.00).

• When the value of fieldCode is FIRST_NAME, LAST_NAME, or USER_NAME, the maximum length of fieldValue is 20 characters.
• When the value of fieldCode is USER_SALUTATION, the valid values of its fieldValue are:

• MR.: Indicates the user's salutation is Mr.
• MS.: Indicates the user's salutation is Ms.
• MRS.: Indicates the user's salutation is Mrs.
• MISS: Indicates the user's salutation is Miss

• When the value of fieldCode is GENDER, the valid values of fieldValue are:

• F: Indicates the user's gender is female
• M: Indicates the user's gender is male

• When the value of fieldCode is BIRTH_DATE, fieldValue follows the YYYY-MM-DD format, for example, 2002-07-25.
• When the value of fieldCode is MOBILE_PHONE, fieldValue follows the [+][country code][area code without leading 0][local phone number] format, for example, +658812****.
• When the value of fieldCode is EMAIL, fieldValue needs to include an at sign (@), and allows the following characters:

• Uppercase letters from A to Z
• Lowercase letters from a to z
• Arabic numerals from 0 to 9
• Special characters, such as underline (_) and minus (-)

• When the value of fieldCode is PASSWORD, filedValue is a string that is calculated by encrypting the plaintext password with AES256. The plaintext password needs to have a minimum of eight characters, including at least one uppercase letter, one lowercase letter, one digit, and one special character.

{

"fieldCode": "BALANCE",

"fieldValue": {

"value": 100,

"currency": "SGD"

}

}

Field

Data type

Required

Description

assetType

String

Yes

Indicates the type of the membership assets.

Valid values are:

• POINT: The reward points
• BALANCE: The membership card balance
• BENEFIT: The member benefits

assetValue

String

Yes

Indicates the value of the membership assets.

Note:

• pointMaxAmount: Indicates the maximum amount of money you can redeem with the reward points, which is in JSON format containing an Amount object.
• pointUnitAmount: Indicates the unit amount of money you can redeem with the reward points, which is in JSON format containing an Amount object.

See Sample response in the inquireMemberAssets API for sample implementation.

Field

Data type

Required

Description

benefitInstanceId

String

Yes

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

Maximum length: 64 characters

status

String

Yes

Indicates the status of a benefit.

Valid values are:

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

amount

Amount

No

Indicates the benefit amount.

createdTime

String

Yes

Indicates the actual time when a benefit is created.

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

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".

benefitTitle

MultiLanguageText

Yes

Indicates the title of the benefit.

useRules

MultiLanguageText

Yes

Indicates the usage rules of the benefit.

useScenarios

MultiLanguageText

Yes

Indicates the usage scenarios of the benefit.

iconUrl

String

Yes

Indicates the icon URL of the benefit.

Maximum length: 256 characters

benefitUrl

String

No

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

Maximum length: 256 characters

extendInfo

String

No

Indicates the extended information of the benefit.

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

Field

Data type

Required

Description

Example

languageValues

Map<String,String>

Yes

Indicates the key-value pairs of the multi-language content. The key is the language code, such as en-US, while the value is the actual text, such as KFC.

• Key:

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

• Value:

• Maximum length: 256 characters

{

"en-US": "KFC",

"zh-CN": "肯德基"

}

defaultLanguage

String

No

Indicates the language code of the default language, such as en-US.

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

Note: When a defaultLanguage value is provided, languageValues must contain data of the default language.

"en-US"

Field

Data type

Required

Description

resultStatus

String

No

Result status. Valid values are:

• S : Successful
• F : Failed
• U : Unknown
• A : Accepted, not yet succeeded, but can proceed with some actions.

resultCode

String

No

Result code

Maximum length: 64 characters.

resultMessage

String

No

Result message that describes the result code in detail.

Maximum length: 256 characters.

Field

Data type

Required

Description

identityType

String

Yes

The type of the user's identity. Valid values are:

• EMAIL: indicates the user's identify type is email.
• MOBILE_PHONE: indicates the user's identify type is mobile phone.

identityNo

String

Yes

The identity number.

If the value of identityType is EMAIL, set the value of this parameter to the user's email address; otherwise, set it to the user's mobile phone number, which includes its country code with a plus sign prefix.