Property

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

Property

Data type

Required

Description

actionFormType

String

No

The action form type.

Enum: [ ORDER_CODE , REDIRECTION ]

orderCode

String 

No

The order code value. The order code is generated by merchants, which is a QR code with order information for customers to scan.

Max. length: 2048 characters.

redirectionUrl

String 

No

The URL of redirect.

Max. length: 4096 characters.

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: 64 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: 4096 characters.

Property

Data type

Required

Description

needSurcharge

Boolean

No

An indicator of a surcharge, which appears in the request from APS to Mobile Payment Partner. If the value is TRUE, the fields surchargeAmount and surchargeQuote  must be specified. The default value is FALSE.

isPaymentEvaluation

Boolean

No

An indicator of the payment evaluation. If the value is TRUE, the payment is only to evaluate whether the payment can be successful and no actual funds deduction occurs. The default value is FALSE.

isAuthorizationAndPay

Boolean

No

An indicator of whether to do authorization for the agreement payment (Auto Debit) during the payment. The default value is FALSE.

isAuthorizationPayment

Boolean

No

An indicator of whether the payment is an authorization payment.The default value is FALSE.

isDeferredPayment

Boolean

No

An indicator of whether the payment is a deferred payment, in which scenario the user uses the product or service in advance.

needCheckCompliance

Boolean

No

An indicator of whether the payment information must be validated to meet compliances before the payment is processed.

needOtpVerification

Boolean

No

An indicator of whether the payment needs to verify OTP (one time password).

isCrossborderSettlement

Boolean

No

An indicator of whether the payment requires cross-border settlement.

inStorePaymentScenario

Boolean

No

An indicator of PaymentCode/OrderCode/EntryCode .

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.

Property

Data type

Required

Description

loginIdType

String 

Yes

The types of Login ID:

• MOBILE_PHONE 
• EMAIL 
• OTHER

Max. length: 64 characters.

loginId

String 

No

An unique identifier for an user's ID login, which can be a mobile number or an email address. Users can use their login ID that without hidden bits to log in to the Wallet.

Max. length: 64 characters.

maskLoginId

String 

No

Mask Login ID that represents several bits of the phone number that are hidden to protect users' privacy.

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.

extendInfo

String 

No

The extensive information for wallets and merchants to add.

Max. length: 4096 characters.

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.

extendInfo

String 

No

The extensive information for wallets and merchants to add.

Max. length: 4096 characters.

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.

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.

Property

Data type

Required

Description

fullName

String 

No

Full Name.

Max. length: 128 characters.

firstName

String 

No

First Name.

Max. length: 32 characters.

middleName

String 

No

Middle Name.

Max. length: 32 characters.

lastName

String 

No

Last Name.

Max. length: 32 characters.

Property

Data type

Required

Description

referenceOrderId

String

Yes

The unique identification of the order on the merchant side. It is used for the display of user consumption records, and the subsequent payment operations such as customer complaints and disputes track.

Max. length: 64 characters.

orderDescription

String

Yes

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

Max. length: 256 characters.

orderAmount

Amount

Yes

The amount of an order, like how much to charge in the specified currency unit for an order.

orderCreateTime

String/Datetime

No

Order create time from merchant which follows the ISO 8601 standard.

Max. length: 32 characters.

merchant

Merchant

Yes

Merchant information.

goods

Array<Goods>

No

Goods information.

shipping

Shipping

No

Shipping information.

buyer

Buyer

No

Buyer information.

env

Env

No

The order environment information, such as the device information.

extendInfo

String 

No

Extended infomation data, this field includes information that are not common but needed for special use cases.

Max. length: 2048 characters.

Field

Data type

Required

Description

referenceMerchantId

String

Yes

Indicates the unique ID assigned by Mini Program Platform to identify a merchant.

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

merchantMCC

String

No

Indicates the merchant's MCC (merchant category code). The value follows the ISO 18245 standard format.

• Maximum length: 32 characters
• Minimum length: 1 character

merchantName

String

Yes

Indicates the name of the merchant.

Maximum length: 256 characters

merchantDisplayName

String

No

Indicates the display name of the merchant.

• Maximum length: 64 characters

merchantAddress

Address

No

Indicates the address of the merchant.

merchantRegisterDate

Datetime

No

Indicates the date and time when the merchant registered their business. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".

merchantStore

MerchantStore

No

Indicates the information of the merchant's store.

Field

Data type

Required

Description

region

String

Yes

Indicates the Alpha-2 code that refers to a region according to ISO 3166, for example, JP or US.

Maximum length: 2 characters

state

String

No

Indicates State, County, or Province.

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

city

String

No

Indicates City, District, Suburb, Town, or Village.

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

address1

String

No

Indicates address line 1 (including Street address, P.O. box, or Company name).

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

address2

String

No

Indicates address line 2 (including Apartment, Suite, Unit, or Building).

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

label

String

No

Indicates the label for the address, for example, home or work.

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

zipCode

String

No

Indicates the ZIP or postcode.

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

longitude

String

No

Indicates the longitude of the address.

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

Note: If latitude is provided, then longitude must be provided.

latitude

String

No

Indicates the latitude of the address.

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

Note: If longitude is provided, then latitude must be provided.

extendInfo

String

No

Indicates the extended information of the address.

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

Field

Data type

Required

Description

referenceStoreId

String

Yes

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

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

storeName

String

No

Indicates the name of the store.

• Maximum length: 256 characters

storeMCC

String

No

Indicates the store's MCC (merchant category code). The value follows the ISO 18245 standard format.

• Maximum length: 32 characters
• Minimum length: 1 character

storeDisplayName

String

No

Indicates the display name of the store.

• Maximum length: 64 characters

storeTerminalId

String

No

Indicates the unique identifier of the store's terminal.

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

storeOperatorId

String

No

Indicates the unique identifier of the store's terminal operator.

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

storeAddress

Address

No

Indicates the address of the store.

storePhoneNo

String

No

Indicates the contact number of the store.

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

Field

Data type

Required

Description

referenceGoodsId

String

Yes

Indicates a unique ID assigned by the merchant to identify goods in the order.

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

goodsName

String

Yes

Indicates the name of goods.

Maximum length: 256 characters

goodsCategory

String

No

Indicates the category of goods.

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

goodsBrand

String

No

Indicates the brand of goods.

• Maximum length: 32 characters

goodsUnitAmount

Amount

No

Indicates the unit amount of goods.

goodsPaymentAmount

Amount

Yes

Indicates the actual payment amount for the goods. If there is more than one item of the same goods, the actual amount paid for the goods is equal to the unit amount multiplied by the quantity.

goodsQuantity

Integer

Yes

Indicates the number of goods.

Value range: 1-unlimited

goodsSkuName

String

No

Indicates the SKU name of goods.

• Maximum length: 64 characters

goodsUrl

String

No

Indicates the URL of goods in the mini program.

Maximum length: 2048 characters

extendInfo

String

No

Indicates the extended information about goods.

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

Property

Data type

Required

Description

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.

Field

Data type

Required

Description

referenceBuyerId

String

Yes

Indicates the unique ID assigned by Mini Program Platform to identify a buyer.

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

buyerName

UserName

No

Indicates the name of the buyer.

buyerPhoneNo

String

No

Indicates the contact number of the buyer.

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

buyerEmail

String

No

Indicates the email address of the buyer.

Maximum length: 128 characters

Property

Data type

Required

Description

templateParameters

Map<String,String>

No

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

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

, where: 

• key : represents the placeholder that is designed in the selected message template.
• value : is used to replace the value of the  key parameter in the message template.

language

String

No

RFC 1766, such as zh-CN, en-US.

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.

Property

Data type

Required

Description

Example

promoId

String

Yes

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

Maximum length: 64 characters

-

promoType

String

Yes

Indicates the type of promotion.

Valid values are:

• INSTANT_DISCOUNT: An instant discount on items.
• COUPON: A coupon to be applied that offers a discount on items.

"COUPON"

promoName

String

No

Indicates the name of the promotion.

Maximum length: 256 characters

-

discountAmount

Amount

Yes

Indicates the amount that is reduced.

-

extendInfo

String

No

Indicates the extended information about the promotion.

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

Note: Specify the promoInvestorType parameter that indicates the investor who funds the marketing promotions. Valid values are:

• MERCHANT: The merchant funds the marketing promotions.
• PLATFORM: Mini Program Platform funds the marketing promotions.
• SUPER_APP: The super app funds the marketing promotions.

{\"promoInvestorType\":\"PLATFORM\"}

Field

Data type

Required

Description

refundId

String

Yes

Indicates the unique ID to identify a refund.

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

refundAmount

Amount

Yes

Indicates the refund amount.

refundStatus

String

Yes

Indicates the status of the refund.

Valid values are:

• PROCESSING: The refund is being processed.
• SUCCESS: The refund is successful.
• FAIL: The refund failed.

refundTime

Datetime

Yes

Indicates the time when the user initiates a refund request.

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

Key

Description

IOS

iOS.

ANDROID

Android.

Key

Description

BALANCE

Balance.

COUPON

Coupon.

CREDIT_CARD

Credit Card.

DEBIT_CARD

Debit Card.

Key

Description

MINI_APP

Mini program.

APP

Mobile Application.

WEB

Broswer Web.

WAP

Mobile Wap.

SYSTEM

System Call.

Key

Description

INSTANT_DISCOUNT

An instant discount on items.

COUPON

A coupon to be applied that offers a discount on items.

Key

Description

PROCESSING

The refund is being processed.

SUCCESS

The refund is successful.

FAIL

The refund failed.