DOCS

Data dictionary (for v1)

Model

Amount

Property

Data type

Required

Description

currency

String 

Yes

The three-character ISO-4217 currency code.

Max. length: 3 characters.

value

String 

Yes

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 to charge $100, a zero-decimal currency).

Max. length: 16 characters.

ActionForm

Property

Data type

Required

Description

redirectionUrl

String 

No

The URL of redirect.

Max. length: 4096 characters.

Env

Property

Data type

Required

Description

terminalType

String

No

The terminal type of this request.

Enum: [ MINI_APP, APP, WEB, WAP, SYSTEM ]

osType

String

No

OS type.

Enum: [ IOS, ANDROID ]

userAgent

String 

No

User agent.

Max. length: 1024 characters.

deviceTokenId

String 

No

Token ID of the device.

Max. length: 128 characters.

clientIp

String 

No

IP address of the client device.

Max. length: 128 characters.

cookieId

String 

No

User cookie ID.

Max. length: 128 characters.

storeTerminalId

String 

No

The store terminal ID.

Max. length: 64 characters.

storeTerminal

RequestTime

String/Datetime

No

The store terminal request time.

Max. length: 32 characters.

extendInfo

String 

No

Extend info.

Max. length: 2048 characters.

User

Property

Data type

Required

Description

userId

String 

No

The hashed unique identifier allocated for user.

Max. length: 64 characters.

status

String 

No

User status, Enum: "ACTIVE", "FROZEN", "INACTIVE"

Max. length: 32 characters.

nickName

String 

No

Nick name.

Max. length: 256 characters.

userName

UserName

No

User name, fullName and (firstName,middleName,lastName) can not both empty.

userAddresses

Array<Address>

No

The user's address information.

avatar

String 

No

Avatar url.

Max. length: 256 characters.

gender

String 

No

F: female; M: Male.

Max. length: 32 characters.

birthDate

String/Datetime

No

Birth date which follows the ISO 8601 standard.

Max. length: 32 characters.

nationality

String 

No

Nationality,  alpha-2 code according to ISO3166. e.g. JP, US.

Max. length: 32 characters.

loginIdInfos

Array<LoginIdInfo>

No

A list of user login IDs.

contactInfos

Array<ContactInfo>

No

A list of contact information.

extendInfo

String

No

The extend information,wallet and merchant can put extend info here.

Max. length: 4096 characters.

LoginIdInfo

Property

Data type

Required

Description

loginIdType

String 

Yes

The types of Login ID:

  • MOBILE_PHONE 
  • EMAIL 
  • OTHER

Max. length: 64 characters.

hashLoginId

String 

No

Hash login ID that identifies an loginId  that is hashed by a hash algorithm. The external system can use it to compare its login ID that is hashed by the same hash algorithm to check whether the login ID is identical.

Max. length: 256 characters.

loginId

String 

No

The Login ID for this user

maskLoginId

String

Yes

The masked Login Id for

ContactInfo

Property

Data type

Required

Description

contactType

String 

Yes

The followings are contact types that are available to all users：

  • MOBILE_PHONE 
  • TELEPHONE 
  • EMAIL 

Tips: Developer can add new types, but should consider the compatibility.

Max. length: 32 characters.

contactNo

String 

Yes

The value that corresponds to the contact type that is configured in the contactType  field. For example, this field can be mobile phone numer, or e-mail address.

Max. length: 64 characters.

PaymentMethod

Property

Data type

Required

Description

paymentMethodType

String 

Yes

Payment method type, used to identifier a payment method.

Max. length: 32 characters.

paymentMethodId

String 

No

The uniqueId of a customer belong to a paymentMethod.

Max. length: 128 characters.

paymentMethodMetaData

String 

No

The payment method metadata.

Max. length: 2048 characters.

Result

Property

Data type

Required

Description

resultStatus

String

No

Result status. Valid values are:

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

resultCode

String

No

Result code.

Max. length: 64 characters.

resultMessage

String

No

Result message that describes the result code in details.

Max. length: 256 characters.

UserName

Property

Data type

Required

Description

fullName

String 

No

Full Name.

Max. length: 128 characters.

firstName

String 

No

First Name.

Max. length: 32 characters.

secondName

String 

No

SecondName

Max. length: 32 characters.

thirdName

String 

No

Third Name.

Max. length: 32 characters.

lastName

String 

No

Last Name.

Max. length: 32 characters.

Order

Property

Data type

Required

Description

orderDescription

String

Yes

Description of the order used to display user consumption records, etc.

Max. length: 256 characters.

merchant

Merchant

No

Merchant information.

goods

Array<Good>

No

Goods information.

shipping

Shipping

No

Shipping information.

buyer

Buyer

Yes

Buyer information.

It is optional only for Agreement Pay scenario.

env

Env

No

The order environment information, such as the device information.

Transaction

Property

Data type

Required

Description

transactionType

String

Yes

Transaction type for each subsequent payment activity.

transactionId

String

Yes

The unique ID assigned by wallet to identify a transaction. When the transaction type is CAPTURE, the value of this field is identical to captureId. When the transaction type is VOID, the value of this field is identical to voidId.

transactionStatus

String

No

Transaction status type.

transactionAmount

Amount

Yes

Transaction amount. When the transaction type is CAPTURE, the value of this field is identical to captureAmount. When the transaction type is VOID, the value of this field is identical to voidAmount.

transactionTime

Date

No

Transaction time

isLastCapture

String

No

Only for capture transaction

Merchant

Property

Data type

Required

Description

referenceMerchantId

String 

No

Merchant ID.

Max. length: 32 characters.

merchantMCC

String 

Yes

Merchant MCC ( merchant category code).

Max. length: 32 characters.

merchantName

String 

No

Name of Merchant.

Max. length: 256 characters.

store

Store

No

Merchant store.

Address

Property

Data type

Required

Description

country

String

Yes

County, e.g. CHN

Max. length: 32 characters.

region

String 

Yes

Alpha-2 code according to ISO3166. e.g. JP, US.

Max. length: 2 characters.

state

String 

No

State/County/Province.

Max. length: 8 characters.

city

String 

No

City/District/Suburb/Town/Village.

Max. length: 32 characters.

address1

String 

No

Address line 1(Street address/PO Box/Company name).

Max. length: 256 characters.

address2

String 

No

Address line 2(Apartment/Suite/Unit/Building).

Max. length: 256 characters.

zipCode

String 

No

ZIP or postal code.

Max. length: 32 characters.

extendInfo

String 

No

Extend info.

Max. length: 2048 characters.

Store

Property

Data type

Required

Description

referenceStoreId

String 

No

The unique ID assigned by wallet to identify a store.

Max. length: 64 characters.

externalStoreId

String

No

The store belongs to a merchant, and the ID assigned by the corresponding merchant to the store is unique under the merchant.

Max. length: 64 characters.

Goods

Property

Data type

Required

Description

referenceGoodsId

String 

Yes

Unique ID of goods.

Max. length: 64 characters.

goodsName

String 

Yes

Name of goods.

Max. length: 256 characters.

goodsCategory

String 

No

Category of goods.

Max. length: 256 characters.

goodsUnitAmount

Amount

Yes

Order amount for display of user consumption records, payment results page.

goodsQuantity

String 

No

Quantity of goods.

Max. length: 32 characters.

goodsUrl

String 

No

Goods url.

Max. length: 512 characters.

extendInfo

String 

No

The extend information of goods.

Max. length: 2048 characters.

Shipping

Property

Data type

Required

Description

shippingId

String

Yes

Shipping id.

Max. length: 64 characters.

shippingName

UserName

Yes

Shipping name.

shippingAddress

Address

Yes

Shipping address.

shippingCarrier

String 

No

The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc.

Max. length: 128 characters.

shippingPhoneNo

String 

No

Recipient PhoneNo(including extension).

Max. length: 16 characters.

shippingFee

Amount

No

Shipping fee.

Buyer

Property

Data type

Required

Description

referenceBuyerId

String 

Yes

Unique Identification of buyer.

Max. length: 32 characters.

buyerName

UserName

No

Buyer name.

ContentTemplate

Property

Data type

Required

Description

templateParameters

Map<String,String>

Yes

A string-to-string mapping. The data structure is in JSON format: 

"templateParameters": {"key": "value"}  

, where: 

  • key : represents the variable that is defined in the template.
  • value : is used to replace the value of the  key parameter in the template.

RedirectActionForm

Property

Data type

Required

Description

method

String

No

The HTTP method. The value is POST  or GET .

parameters

String 

No

The parameters that are required for the HTTP method, which is in the key:value  pair format.

Max. length: 2048 characters.

redirectUrl

String 

Yes

The URL of redirect.

Max. length: 2048 characters.

Message

Property

Data Type

Required

Description

messageId

String

Yes

The unique ID is generated by Mini Program Platform to identify a notification.

  • Maximum length: 64 characters.
  • Characters not allowed: special characters such as @, #, ? and so on.

Note: This field is an API idempotency field. For the notifications which are sent with the same requestId and reach an S status, the native app must return the same messageId.

See the Idempotency for details about API idempotency.

customerId

String

Yes

The unique ID is generated by the native app to identify a user.

Example: 218820000000000000023.

Maximum length: 32 characters.

messageChannel

MessageChannel

Yes

The channels to send a notification, including push, SMS, and Inbox.

templateCode

String

No

Indicates the template ID that is generated by Mini Program Platform to identify a template.

  • Maximum length: 64 characters.
  • Characters not allowed: special characters such as @, #, ? and so on.
  • Can be Null.

messageContent

String 

Yes

The specific content that a notification to send.

Maximum length: 4096 characters.

  • Push

{

 "en-US": {

   "title": "testTitle",

   "content": "testContent",

   "linkUrl": "testUrl"

 },

 "zh-CN": {

   "title": "testTitle",

   "content": "testContent",

   "linkUrl": "testUrl"

 }

}

  • SMS

{

 "en-US": {

   "content": "this is sms content"

 },

 "zh-CN": {

   "content": "this is sms content"

 }

}

  • Inbox

{

 "en-US": {

   "displayType": "inbox_item_content",

   "header": {

     "appIcon": "icon url",

     "appName": "icon name",

     "msgBizName": "test_biz",

     "target": {

       "path": "header link url"

     }

   },

   "body": {

     "title": "message title",

     "content": "message content",

     "target": {

       "path": "message path url"

     }

   },

   "footer": [

     {

       "linkName": "link name",

       "target": {

         "path": "header link url"

       }

     }

   ]

 },

 "zh-CN": {

   "displayType": "inbox_item_content",

   "header": {

     "appIcon": "icon url",

     "appName": "icon name",

     "msgBizName": "test_biz",

     "target": {

       "path": "header link url"

     }

   },

   "body": {

     "title": "message title",

     "content": "message content",

     "target": {

       "path": "message path url"

     }

   },

   "footer": [

     {

       "linkName": "link name",

       "target": {

         "path": "header link url"

       }

     }

   ]

 }

}

extendInfo

String 

No

The extended information.

  • Maximum length: 4096 characters.
  • Characters not allowed: special characters such as @, #, ? and so on.
  • Can be Null.

MessageSendResult

Property

Data Type

Required

Description

messageId

String 

Yes

The unique ID is generated by Mini Program Platform to identify a notification.

  • Maximum length: 64 characters.
  • Characters not allowed: special characters such as @, #, ? and so on.

Note: This field is an API idempotency field. For the notifications which are sent with the same requestId and reach an S status, the native app must return the same messageId.

See the Idempotency for details about API idempotency.

success

Boolean

Yes

Indicates whether the notification is successfully sent to the native app. Valid values are:

  • true: The notification is sent successfully.
  • false: The notification fails to send.

retry

Boolean

No

Indicates whether the native app allows you to retry when the notification fails to send. Valid values are: 

  • true: The native app server allows to retry under specific scenarios, for example, when there are system exceptions.
  • false: The native app server does not allow to retry. For example, when the delivery frequency of the notification is beyond the limits set by the native app, retry is not allowed.

Note: This field is required when the value of the success field is false.

UserInfo

Property

Data type

Required

Description

userId

String 

Yes

Result code

Max. length: 128 characters.

loginIdInfos

Array<LoginIdInfo>

Yes

Login id info list

userName

UserName

No

User official name in English

userNameArabic

UserName

No

User official name in Arabic

avatar

String

No

User head portrait

Max. length: 256 characters.

gender

String

No

F: Female; M: Male

Max. length: 32 characters.

birthDate

String/Datetime

No

Birthday which follows the ISO 8601 standard.

Max. length: 32 characters.

nationality

String

No

Nationality, alpha-2 code according to ISO3166. e.g. JP, CN.

Max. length: 2 characters.

contactInfos

Array<ContactInfo>

No

Contact info list

OsType

Key

Description

IOS

iOS.

ANDROID

Android.

PaymentMethodType

Key

Description

BALANCE

Balance.

COUPON

Coupon.

CREDIT_CARD

Credit Card.

DEBIT_CARD

Debit Card.

TerminalType

Key

Description

MINI_APP

Mini program.

APP

Mobile Application.

WEB

Broswer Web.

WAP

Mobile Wap.

SYSTEM

System Call.

MessageChannel

Key

Description

SMS

SMS

PUSH

PUSH

INBOX

INBOX