Data dictionary

#Model

This section introduces the common data objects used across all interfaces.


#Address

No.

Field

Description

1

region

MANDATORY String (2)
The 2-letter country/region code. For more information, see ISO 3166 Country Codes standard.

2

state

OPTIONAL String (8)

The state, country, or province name.

3

city

OPTIONAL String (32)

The city, district, suburb, town, or village name.

4

address1

OPTIONAL String (256)

Address line 1, for example, the street address, PO box, and company name.

5

address2

OPTIONAL String (256)

Address line 2, for example, the apartment, suite, unit, and building information.

6

zipCode

OPTIONAL String (32)

ZIP or postal code


#Amount

No.

Field

Description

1

currency

MANDATORY String (3)
The 3-letter currency code that follows the ISO 4217 standard.

2

value

MANDATORY String (16)

The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a zero-decimal currency).


#AmountLimit

No.

Field

Description

1

maxAmount

MANDATORY Amount
The maximum amount.

2

minAmount

MANDATORY Amount

The minimum amount.

3

remainAmount

MANDATORY Amount

The remaining amount.


#AmountLimitInfo

No.

Field

Description

1

singleLimit

MANDATORY AmountLimit

The limit for a single transaction.

2

dayLimit

MANDATORY AmountLimit

The limit for the transaction amount in one day.

3

monthLimit

MANDATORY AmountLimit

The limit for the transaction amount in one month.


#Attachment

No.

Field

Description

1

attachment

MANDATORY String (32)

Attachment type. Possible values:

  • ASSOCIATION_ARTICLE: articles of association
  • ENTERPRISES_ANNUAL_INSPECTION_REPORT: annual inspection report of enterprise
  • ADDRESS_PROOF: proof of the address
  • OTHER_MATERIAL: other materials

2

file

MANDATORY String (1024)

File information

3

attachmentName

OPTIONAL String (128)

Attachment name


#BankInfo

No.

Field

Description

1

bankShortName

String (64)

Short name of bank

2

cardIssuedCode

String (64)

Card issue code

3

enabled

Boolean

Indicates whether the bank is enabled.


#BusinessContactEntity

No.

Field

Description

1

businessContactType

MANDATORY String (32)

Contact type of the business. Possible values:

  • DIRECTOR: executives and senior managers
  • SHAREHOLDER: shareholders
  • BOARD_MEMBER: board members
  • UBO: ultimate beneficial owners
  • LEGAL_REPRESENTATIVE: legal representatives
  • AUTHORIZED_SIGNATORY: authorized signatory
  • COMMON: general contacts

2

legalEntityType

MANDATORY String

Legal entity type. Possible values:

  • INDIVIDUAL: to represent an individual type
  • COMPANY: to represent a company type

3

shareHoldingRatio

OPTIONAL String

Ratio of the shareholding

4

individual

OPTIONAL Individual

Individual information

5

company

OPTIONAL Company 

Company information

6

fundsSources

OPTIONAL List<String>

Fund sources

7

fundsDestinations

OPTIONAL List<String> 

Fund destinations


#BusinessPartner

No.

Field

Description

1

businessName

OPTIONAL String (256)

Short name, abbreviation, or other names of the business partner

2

mcc

OPTIONAL String (32)

MCC (Merchant Category Code) of the business partner

3

brand

OPTIONAL String (128)

Business brand

4

logo

OPTIONAL String (128)

Business logo

5

webSites

OPTIONAL Array<Website

Websites of the business partner

6

operationAddress

OPTIONAL Address 

Address of the business partner

7

mainGoods

OPTIONAL List<String> 

Main products of the business partner

8

stores

OPTIONAL Array<Store

Information about the stores of the business partner

9

businessContactEntities

OPTIONAL Array<BusinessContactEntity>

Information about the business partner


#Buyer

No.

Field

Description

1

referenceBuyerId

OPTIONAL String (64)

The unique ID to identify the buyer

2

buyerName

OPTIONAL UserName

Name of the buyer

3

buyerPhoneNo

OPTIONAL String (24)

Mobile phone number of the buyer

4

buyerEmail

OPTIONAL String 

Email of the buyer


CardPaymentMethodDetail

No.

Field

Description

1

cardToken

OPTIONAL String

Card token information

2

accountNo

OPTIONAL String (64)

Account number

3

brand

OPTIONAL CardBrandType

Card brand

4

cardIssuer

OPTIONAL String (32)

Card issuer

5

countryIssue

OPTIONAL String (32)

Card issuing country

6

instUserName

OPTIONAL UserName (32)

Card holder name

7

expiryYear

OPTIONAL String (16)

Expiry year of the card

8

expiryMonth

OPTIONAL String (16)

Expiry month of the card. The value is in two digits.

9

billingAddress

OPTIONAL Address

Billing address

10

mask

OPTIONAL String (32)

The first 6 and last 4 digits of the bank card number.

11

last4

OPTIONAL String (4)

Last 4 digits of the card number

12

paymentMethodDetailMetadata

OPTIONAL String (2048)

Set of key-value pairs. This can be used for storing additional information about the object in a structured format.


#CardPaymentOptionDetail

No.

Field

Description

1

paymentOptionDetailType

PaymentOptionDetailType

Payment method details. Possible values include:

  • INSTALLMENT
  • CARD

2

supportCardBrands

Array<SupportCardBrand>

Supported card brand and corresponding currency information

3

bankInfos

Array<BankInfo>

Bank information of the card

4

disableTimeInfo

DisableTimeInfo

Information about the channel maintenance time 

5

paymentOptionMetadata

String (2048)

Set of key-value pairs. This field can be used for storing additional information about the object in a structured format.


#Certificate

No.

Field

Description

1

certificateType

MANDATORY String (32)

Certificate type. Possible values:

  • ENTERPRISE_REGISTRATION: enterprise registration certificate, such as business license
  • PASSPORT: passport
  • ID_CARD: identity card
  • DRIVING_LICENSE: driving license
  • TAX_REGISTRATION_CERTIFICATE: tax registration certificate

2

certificateNo

MANDATORY String (64)

Certificate number

3

files

OPTIONAL Array<String>

List of documents attached to the certificate

4

holderName

OPTIONAL String (256)

Name of the holder of the certificate

5

effectiveDate

OPTIONAL Datetime

Effective date of the certificate

6

expireDate

OPTIONAL Datetime

Expiry date of the certificate

7

certificateAuthority

OPTIONAL String (64)

The certificate authority


#ChallengeActionForm

No.

Field

Description

1

challengeType

MANDATORY ChallengeType

Type of challenge

2

challengeRenderValue

MANDATORY String (64)

The actual render value

3

triggerSource

MANDATORY ChallengeTriggerSourceType
Describes that the challenge is required by Alipay or external party.

4

extendInfo

OPTIONAL String (2048)

Extended information


#ChinaExtraTransInfo

No.

Field

Description

1

businessType

MANDATORY String (16)

The business type. Supported values are

1: Hotel

2: Air Flight

3: Study Abroad

4: Trade

5: Other 

Multiple business types are delimited with '|'.

2

flightNumber

OPTIONAL String (1000)

The flightNumber. Multiple flight numbers are delimited with '|'. when businessType=2, you should pass the value.

3

departureTime

OPTIONAL String (1000)

The flight departure time. Format as yyyy-MM-dd HH:mm. Multiple flight departure times are delimited with '|'.when businessType=2, you should pass the value.

4

hotelName

OPTIONAL String (1000)

The hotel name. Multiple hotel names are delimited with '|'. when businessType=1, you should pass the value.

5

checkinTime

OPTIONAL String (1000)

The hotel check-in time. Format: yyyy-MM-dd. Timezone: UTC+8

Multiple hotel check-in times are delimited with '|'.when businessType=1, you should pass the value.

6

checkoutTime

OPTIONAL String (1000)
The hotel checkout time. Format: yyyy-MM-dd. Timezone: GMT +8.

Multiple hotel checkout times are delimited with '|'.when businessType=1, you should pass the value.

7

admissionNoticeUrl

OPTIONAL String (1000)

The school admission notice URL. Mulitple URLs are delimited with '|'.when businessType=3, you should pass the value.

8

goodsInfo

OPTIONAL String (2000)

Goods information that includes SKU names and corresponding quantities, in the format of SKU_name^quantity. If more than one goods exists, separate values with a vertical bar (|). Specify this field only when business_type is 4 (Sales of goods). When businessType=4, you should pass the value.

9

totalQuantity

OPTIONAL String (8)

Total quantities of all goods in one order. Specify this field only when business_type is 4 (Sales of goods). When businessType=4, you should pass the value.


#CodeDetail

No.

Field

Description

1codeValueType

MANDATORY CodeValueType

Code type

2codeValue

MANDATORY String (2048)

Code value

3displayType

MANDATORY DisplayType

Indicates the way to show the code.


#ContactPerson

No.

Field

Description

1contactPersonType

MANDATORY String (32)

Type of the contact person, such as customer service staff, shop assistant

2name

MANDATORY String (256)

Name of the contact person, which must be identical to the name of a provided identity document

3firstName

OPTIONAL String (32)

First name of the contact person

4

lastName

OPTIONAL String (32)

Last name of the contact person

5

gender

OPTIONAL Gender

Gender of the contact person

6

residentAddress

OPTIONAL Address

Resident address

7

birthDate

OPTIONAL Datetime

Date of birth

8

birthPlace

OPTIONAL Address

Place of birth

9

nationality

OPTIONAL String

Nationality, a 2-letter code that follows ISO 3166

10

contactWays

OPTIONAL Array<ContactWay>

Contact ways


#ContactWay

No.

Field

Description

1contactWayType

MANDATORY String (32)

Type of the way to contact. Possible values:

  • PHONE_NO
  • EMAIL
2contactWayInfo

MANDATORY String (256)

Detailed information about the way to contact

3contactWayDesc

OPTIONAL String (512)

Description of the way to contact, for example, the usage scenario of the contact way.


#CouponPaymentMethodDetail

No.

Field

Description

1

couponId

String (64)

Coupon ID

2

availableAmount

Amount

Available balance

3couponName

String (64)

Coupon name

4

couponDescription

String (128)

Coupon description

5

couponExpireTime

Datetime

Coupon expiration date

6

paymentMethodDetailMetadata

String (2048)

Set of key-value pairs. This field can be used for storing additional information about the object in a structured format.


#CreditPayPlan

No.

Field

Description

1

installmentNum

MANDATORY Number (8)

The number of installments within a month.

2

creditPayFeeType

MANDATORY CreditPayFeeType

The fee type of the credit payment plan.

3

feePercentage

OPTIONAL Number (3)

The value of this field is in the range 0-100, which is determined by the sellers' liability. For example:

  • 0 indicates the seller is not liable for any fee.
  • 100 indicates the seller pays 100% of the fee.


Note: This field is required when the value of creditPayFeeType is PERCENTAGE.


#Customer

No.

Field

Description

1


referenceCustomerId

OPTIONAL String

The unique ID assigned by the acquirer or merchant to identify a merchant

2


customerType

OPTIONAL CustomerType

Customer type. The value is BUSINESS_PARTNER.

3

businessPartner

OPTIONAL BusinessPartner

Business partner information

4

legalEntityType

OPTIONAL LegalEntityType

Type of the legal entity

5

individual

OPTIONAL Individual

Individual information

6

company

OPTIONAL Company

Company information

7

customerMetadata

OPTIONAL String (2048)

Extended information


#Company

No.

Field

Description

1

legalName

MANDATORY String (128)

Legal registration name of the company

2

attachments

OPTIONAL Array<Attachment>

Attachments of the company

3

contactWays

OPTIONAL Array<ContactWay>

Contact ways of the company

4

certificates

OPTIONAL Array<Certificate>

Certificates of the company

5

wealthSources

OPTIONAL List<String>

The sources of wealth of the company

6

taxNo

OPTIONAL String (64)

Tax number. In some countries, the tax number might be identical to the registration number

7

vatNo

OPTIONAL String (64)

Value-Added Tax (VAT) number

8

registrationType

OPTIONAL String

Registration type of the company

9

registrationNo

OPTIONAL String (64)

Registration number of the company

10

registrationAddress

OPTIONAL Address

Registration address of the company

11

registrationDate

OPTIONAL Date

Registration date of the company

12

companyType

OPTIONAL String (32)

Company type. Possible values:

  • COMPANY: company
  • SOLE_PROPRIETORSHIP_ENTERPRISE: sole proprietorship enterprise
  • PARTNERSHIP: partnership
  • INDIVIDUAL: individual

13

industryType

OPTIONAL String (64)

Industry of the company

14

stockCode

OPTIONAL String (32)

Stock code

15

stockMarket

OPTIONAL String (32)

Stock market

16

staffNumber

OPTIONAL Long

Staff number


#DisableTimeInfo

No.

Field

Description

1

maintenanceType

String (32)

Channel maintenance type. Possible values are:

  • DAILY
  • WEEKLY
  • MONTH
  • TEMPORARILY
2timeZone

String (32)

Channel maintenance time zone

3

startTime

String (64)

The channel maintenance start time. The value might be a fixed time, such as 2018-03-16 08:00, or 23:00 at the cycle time.

4

sustainMins

String (16)

Number of minutes of channel maintenance

5

dayOfMonth

String (16)

Day or month of channel maintenance, the value is in the range 1 - 31


#DiscountPaymentMethodDetail

No.

Field

Description

1

discountId

String (64)

Discount ID

2

availableAmount

Amount

Available balance

3

discountName

String (64)

Discount name

4

discountDescription

String (128)

Discount description

5

paymentMethodDetailMetadata

String (2048)

Set of key-value pairs. This field can be used for storing additional information about the object in a structured format.


#Env

No.

Field

Description

1

terminalType

OPTIONAL TerminalType

Terminal type. Possible values are:

  • WEB
  • WAP
  • APP

Note: This field is required when productCodeType is Cashier payment.

2

osType

OPTIONAL OsType
OS type. Possible values are:

  • IOS
  • ANDROID

Note: This field is required when productCodeType is cashier payment and terminalType is not WEB.

3

userAgent

OPTIONAL String (1024)

The user agent

4

deviceTokenId

OPTIONAL String (64)

Token identifier of the device

5

clientIp

OPTIONAL String (32)

IP of the client device

6

cookieId

OPTIONAL String (64)

The cookie ID of the buyer

7

storeTerminalId

OPTIONAL String (64)

Store terminal ID.

Note: This field is required for the user-presented mode payment and order code payment.

8

storeTerminalRequestTime

OPTIONAL Datetime

The time that the request is sent by the store terminal, which follows the ISO 8601 standard.

Note: This field must be accurate to milliseconds. Besides, this field is required for the user-presented mode payment and order code payment. If you don't have the terminal request time, use the gateway time for this field.

9

extendInfo

OPTIONAL String (2048)

Extended information


#ExternalPaymentMethodDetail

No.

Field

Description

1

accountDisplayName

OPTIONAL String (128)

The name displayed for the user to identify the bound external account. The value can be a phone number or email address.

2

assetToken

MANDATORY String (128)

The asset token saved in Alipay, which is linked to an external account for actual payment.

3

disableReason

OPTIONAL String (64)

The reason for disablement. For example:

  • PAYMENT_ACCOUNT_NOT_AVAILABLE
  • EXCEED_CHANNEL_LIMIT_RULE
  • SERVICE_DEGRADE
  • CHANNEL_NOT_SUPPORT_CURRENCY
  • CHANNEL_DISABLE
  • CHANNEL_NOT_IN_SERVICE_TIME
  • QUERY_IPP_INFO_FAILED
  • LIMIT_CENTER_ACCESS_FAIL

4

paymentMethodDetailMetadata

OPTIONAL String (2048)

Set of key-value pairs. This field can be used for storing additional information about the object in a structured format.


#Goods

No.

Field

Description

1

referenceGoodsId

MANDATORY String (64)

The unique ID to identify the goods

2

goodsName

MANDATORY String (256)

Goods name

3

goodsUnitAmount

OPTIONAL Amount

Price of goods

4

goodsQuantity

OPTIONAL String (32)

Quantity of goods


#Individual

No.

Field

Description

1

legalName

OPTIONAL String (128)

Legal name of the individual

2

contactWays

OPTIONAL Array<ContactWay>

Contact ways of the individual

3

attachments

OPTIONAL Array<Attachment>

Attachments of the individual

4

certificates

OPTIONAL Array<Certificate>

Certificates of the individual

5

wealthSources

OPTIONAL List<String>

The sources of wealth of the individual

6

taxNo

OPTIONAL String (64)

Tax number. In some countries, the tax number might be identical to the registration number

7

vatNo

OPTIONAL String (64)

Value-Added Tax (VAT) number

8

idType

OPTIONAL String (64)

Identity registration type of the individual. This field is not included in the business contact entity.

9

idNumber

OPTIONAL String (64)

Identity registration number of the individual. This field is not included in the business contact entity.

10

firstName

OPTIONAL String (64)

First name of the individual

11

lastName

OPTIONAL String (64)

Last name of the individual

12

gender

OPTIONAL Gender (32)

Gender of the individual

13

nationality

OPTIONAL String (2)

Nationality of the individual, a 2-letter country code that follows ISO 3166

14

birthDate

OPTIONAL Date

Date of birth

15

birthPlace

OPTIONAL Address

Place of birth

16

residentAddress

OPTIONAL Address

Resident address

17

department

OPTIONAL String (64)

The department the individual belongs to

18

position

OPTIONAL String (32)

The position held by the individual


#Merchant

No.

Field

Description

1

referenceMerchantId

MANDATORY String (32)

The ID to identify the merchant that directly provides services or goods to the customer. 

2

merchantMCC

OPTIONAL String (32)

The merchant category code, which is a four-digit number listed in ISO 18245. This field is required for Alipay+ MPP.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

3

merchantName

OPTIONAL String (256)

The merchant name

4

merchantDisplayName

OPTIONAL String (64)

The merchant name to be displayed

5

merchantAddress

OPTIONAL Address

The merchant address information

6

merchantRegisterDate

OPTIONAL Date

Merchant registration date, which follows the ISO 8601 standard.

7

store

OPTIONAL Store

Store information. This parameter is required for offline payment scenarios.


#Order

No.

Field

Description

1

orderAmount

MANDATORY Amount

The order amount of the merchant that directly provides services or goods to the customer. This field is used for user consumption records display or payment results page.

2

referenceOrderId

OPTIONAL String (64)

The unique ID to identify the order on the merchant side, which is assigned by the merchant that provides services or goods directly to the customer. This field is used for user consumption records display and further payment operations such as customer complaints and disputes track.

3

orderDescription

MANDATORY String (256)

Summary description of the order, which is used for user consumption records display or other further operations.

4

goods

OPTIONAL Array<Goods>

Goods information

5

shipping

OPTIONAL Shipping

Shipping information

6

buyer

OPTIONAL Buyer

Buyer information, which is used for risk control. It is highly recommended to be provided.

7

merchant

OPTIONAL Merchant

Information about the secondary merchant

8

env

OPTIONAL Env

Information about the environment where the order is placed, such as the device information. This field is required for entry code payments.

9

extendInfo

OPTIONAL String (2048)
Extended information data. This field includes information for special use cases. For example, for orders to Alipay CN, additional information is required as captured in the object ChinaExtraTransInfo


#OrderCodeForm

No.

Field

Description

1

paymentMethodType

OPTIONAL String (64)

Payment method type. The value can be the wallet type listed in WalletPaymentMethodType

2

expireTime

OPTIONAL Datetime

Expiry time of the order code information

3

codeDetails

MANDATORY List<CodeDetail>

Details about the code

4

extendInfo

OPTIONAL String (2048)

Extended information


#PaymentFactor

No.

Field

Description

1

isPaymentEvaluation

OPTIONAL Boolean

Indicates whether it's a payment evaluation. The default value is F. 

2

inStorePaymentScenario

OPTIONAL inStorePaymentScenario

Indicates the scenario of the in-store payment, including paymentCode, OrderCode, and some other related fields


#PaymentMethod

No.

Field

Description

1

paymentMethodType

MANDATORY String (32)

Payment method type:

  • For agreement payments and cashier payments, the value is one of the wallet type listed in WalletPaymentMethodType
  • For in-store payments, the value is CONNECT_WALLET.

2

paymentMethodId

OPTIONAL String (128)

The unique ID of the payment method that belongs to a buyer.

3

paymentMethodMetaData

OPTIONAL String (2048)

Other information about payment methods, which are key-value pairs in JSON format

4

customerId

OPTIONAL String (32)

The unique ID to identify a buyer

5

extendInfo

OPTIONAL String (2048)

Extended information


#PaymentMethodDetail

No.

Field

Description

1

paymentMethodDetailType

MANDATORY paymentMethodDetailType

Type of the asset.

2

card

OPTIONAL CardPaymentMethodDetail

Card details

3

externalAccount

OPTIONAL ExternalPaymentMethodDetail

External wallet details

4

discount

OPTIONAL DiscountPaymentMethodDetail

Discount payment method details

5

coupon

OPTIONAL CouponPaymentMethodDetail

Coupon payment method details

6

extendInfo

OPTIONAL String (2048)

Extended information


#PaymentMethodInfo

No.

Field

Description

1

paymentMethodType

MANDATORY String (64)

Payment method type. For a payment method in the wallet category, the value is listed in WalletPaymentMethodType

2

paymentMethodDetail

MANDATORY String (2048)

For details about the payment method, see paymentMethodDetail.

3

enabled

MANDATORY Boolean

Indicates whether the payment method is enabled.

4

preferred

MANDATORY Boolean

Indicates whether the payment method is preferred.

5

extendInfo

OPTIONAL String (2048)

Extended information


#PaymentOption

No.

Field

Description

1

paymentMethodType

MANDATORY String (64)

Payment method type. For the supported list of WALLET category, see WalletPaymentMethodType

2

paymentMethodCategory

MANDATORY PaymentMethodCategoryType

Payment method category. Possible values are:

  • WALLET
  • CARD

3

enabled

MANDATORY Boolean

Indicates whether the payment method is available.

4

preferred

OPTIONAL Boolean

Indicates whether the payment method is preferred.

5

disableReason

OPTIONAL String (64)

The reason why the payment method is disabled. Possible values are:

  • PAYMENT_ACCOUNT_NOT_AVAILABLE
  • EXCEED_CHANNEL_LIMIT_RULE
  • SERVICE_DEGRADE
  • CHANNEL_NOT_SUPPORT_CURRENCY
  • CHANNEL_DISABLE
  • CHANNEL_NOT_IN_SERVICE_TIME
  • QUERY_IPP_INFO_FAILED
  • LIMIT_CENTER_ACCESS_FAIL

6

amountLimitInfoMap

OPTIONAL Map<String, AmountLimitInfo>

The transaction amount limit for different currency settings.

7

supportedCurrencies

OPTIONAL List<String>

Supported currencies for the payment method type specified by paymentMethodType

8

paymentOptionDetail

String (2048)

Details about the payment option. If the value of paymentMethodCategory is CARD, the value of this field follows CardPaymentOptionDetail.

9

extendInfo

OPTIONAL String (2048)

Extend information


#PaymentVerificationData

No.

Field

Description

1verifyRequestId

MANDATORY String (64)

This is the requestId generated by payment site during the initAuthentication call that this request is associated with. 

2authenticationCode

MANDATORY String (64)

Verification code


#PspCustomerInfo

No.

Field

Description

1

pspName

OPTIONAL String (64)

The name of the payment method proivder (Alipay+ MPP)

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

2

pspCustomerId

OPTIONAL String (64)

The customer ID of Alipay+ MPP

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

3

displayCustomerId

OPTIONAL String (64)

The customer ID used for display. For example, loginId


#Quote

No.

Field

Description

1

quoteId

OPTIONAL String (64)

The unique ID to identify an exchange rate.

2

quoteCurrencyPair

MANDATORY String (16)

Pair of currency exchange rate

3

quotePrice

MANDATORY Decimal (20)

The exchange rate used when a currency conversion occurs.

4

quoteStartTime

OPTIONAL Datetime

Effective time of the exchange rate, which follows the ISO 8601 standard

5

quoteExpiryTime

OPTIONAL Datetime

Expiration time of the exchange rate, which follows the ISO 8601 standard

6

guaranteed

OPTIONAL Boolean

Guaranteed exchange rate available for payment


#RedirectActionForm

No.

Field

Description

1

method

MANDATORY MethodType

Indicates the method type.

2

parameters

OPTIONAL String (2048)

Parameters required for the HTTP method in the key-value pair

3

redirectUrl

MANDATORY Url (1024)

The URL where the user is redirected to


#ReportDetail

No.

Field

Description

1

reportStatus

MANDATORY ReportStatus

Report status

2

reportMessage

MANDATORY String (1024)

Reported message

3

reasonCode

OPTIONAL ReasonCode (64)

Indicates the reason why a report is failed

4

referenceCustomerId

MANDATORY String (64)

The unique ID assigned by the acquirer or merchant to identify a merchant

5

storeReportDetails

OPTIONAL List<StoreReportDetail>

Details about the store report result


#Result

No.

Field

Description

1

resultCode

MANDATORY String (16)

Result code

2

resultStatus

MANDATORY ResultStatusType

Result status. Possible values are: 

  • S
  • F
  • U

3

resultMessage

OPTIONAL String (64)

Result message


#SettlementStrategy

No.

Field

Description

1

settlementCurrency

OPTIONAL String (3)

The ISO currency code of the currency that the merchant wants to be settled against. When paymentMethod is AlipayCN, this field must be specified.


#Shipping

No.

Field

Description

1

shippingName

OPTIONAL UserName

The recipant name

2

shippingAddress

OPTIONAL Address

Shipping address

3

shippingCarrier

OPTIONAL String (128)

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

4

shippingPhoneNo

OPTIONAL String (16)

The phone number of a recipient (including extension).


#Store

No.

Field

Description

1

referenceStoreId

MANDATORY String (64)

The unique store ID assigned by the merchant that owns the store

2

storeName

MANDATORY String (512)

Name of the store

3

storeMCC

MANDATORY String (32)

Store business category code

4

storeDisplayName

OPTIONAL String (64)

Display name of the store

5

storeAddress

OPTIONAL Address

Address of the store


#Store (This field is only used for the Report Customer interface)

No.

Field

Description

1

referenceStoreId

MANDATORY String (64)

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

2

storeName

MANDATORY String (256)

Name of the store

3

storeMCC

OPTIONAL String (32)

MCC code of the store

4

storeAddress

OPTIONAL Address

Store address

5

storeContactWays

OPTIONAL Array<ContactWay>

Contact ways of the store

6

storeWebSites

OPTIONAL Array<Website>

Store website

7

storeContactPersons

OPTIONAL Array<ContactPerson>

Store contact person

8

storeAttachments

OPTIONAL Array<Attachment>

Attachment of the store

9

storeType

OPTIONAL StoreType

Store type


#StoreReportDetail

No.

Field

Description

1

reportStatus

MANDATORY ReportStatus

Report status

2

reportMessage

MANDATORY String (1024)

Reported message

3

reasonCode

OPTIONAL ReasonCode (64)

Indicates the reason why a report is failed

4

referenceStoreId

OPTIONAL String (64)

The unique ID assigned by merchant to identify a store


#SupportCardBrand

No.

Field

Description

1

cardBrandType

MANDATORY CardBrandType

Card brand. Possible values are:

  • VISA
  • MASTERCARD
  • MAESTRO
  • AMEX
  • JCB
  • DINERS
  • DISCOVER
  • CUP
  • MIR
  • ELO
  • HPERCARD
  • TROY

2

supportedCurrencies

MANDATORY Array<String>

Supported currencies of the payment method type specified by paymentMethodType


#Transaction

No.

Field

Description

1

transactionResult

MANDATORY Result

The transaction result, which contains information related to the business result and error information.

2

transactionId

OPTIONAL String (64)

The unique ID assigned by Alipay to identify a transaction. When the transaction type is CAPTURE, the value of this field is identical to captureId. When the transaction type is REFUND, the value of this field is identical to refundId.

3

transactionType

MANDATORY TransactionType
Transaction type for each subsequent payment activity. Possible values are:

  • REFUND
  • CAPTURE

4

transactionStatus

MANDATORY TransactionStatusType

Transaction status type. Possible values are:

  • SUCCESS
  • FAIL
  • PROCESSING
  • CANCELLED

5

transactionAmount

MANDATORY Amount

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

6

transactionRequestId

MANDATORY String (64)

The unique ID assigned by the merchant to identify the transaction request. When the transaction type is CAPTURE, the value of this field is identical to captureRequestId. When the transaction type is REFUND, the value of this field is identical to refundRequestId.

7

transactionTime

OPTIONAL Datetime

Transaction time


#UserName

No.

Field

Description

1

firstName

MANDATORY String (32)

First name

2

middleName

OPTIONAL String (32)

Middle name

3

lastName

MANDATORY String (32)

Last name

4

fullName

OPTIONAL String (128)

Full name


#Website

No.

Field

Description

1

name

OPTIONAL String (256)

Website name

2

url

MANDATORY String (2048)

Website URL

3

desc

OPTIONAL String (512)

Website description


#Enum

This section introduces the common enumerations used across all interfaces.


#AuthenticationType

No.KeyDescription
1OTP

One-time password


#AuthenticationChannelType

No.KeyDescription
1

EMAIL

Email

2

SMS

Message


#CardBrandType

No.KeyDescription
1VISAVisa credit card
2MASTERCARDMaster credit card
3MAESTROMaster debit card
4AMEXAmerican Express credit card
5JCBJapan Credit Bureau card
6DINERSDiners card
7DISCOVERDiscover card
8CUPChina Union Pay card
9MIRRussia MIR card
10ELOBrazil ELO card
11HIPERCARDBrazil Hipercard
12TROYTurkey's Payment Method brand


#ChallengeTriggerSourceType

No.KeyDescription
1AMSDescribes the challenge that is required by Alipay.
2CHANNELDescribes the challenge that is required by the external party.


#ChallengeType

No.KeyDescription
1SMS_OTPSMS OTP verification
2

PLAINTEXT_CARD_NO

Plain text card number challenge

3

CARD_EXPIRE_DATE

Card expiry date challenge


#CodeValueType

No.KeyDescription
1

BARCODE

Indicates a bar code.
2

QRCODE

Indicates a QR code.


#CreditPayFeeType

No.KeyDescription
1

PERCENTAGE

The fee is described in percentage with 1 - 3 digits. For example, 5 means 5%, 100 means 100%.


#CustomerType

No.KeyDescription
1

USER

This field is for future use
2

BUSINESS_PARTNER

Indicates the customer type is business partner.


#DisplayType

No.KeyDescription
1

TEXT

Indicates to be directly shown on UI as text or label.

2

MIDDLEIMAGE

Indicates to be shown as a middle size image.

3

SMALLIMAGE

Indicates to be shown as a small size image.

4

BIGIMAGE

Indicates to be shown as a big size image.


#FeeType

No.KeyDescription
1SERVICE_FEE

Service fee


#Gender

No.KeyDescription
1MALE

Male

2

FEMALE

Female


#GrantType

No.KeyDescription
1AUTHORIZATION_CODEAuthorization Code, which is used by confidential and public clients to exchange an authorization code for an access token.
After the user returns to the client via the redirect URL, the application will get the authorization code from the URL and use it to request an access token.
2REFRESH_TOKENRefresh Token, which is used by authClient to exchange a refresh token for an access token when the access token has expired.
This allows clients to continue to have a valid access token without further interaction with the user.


#LegalEntityType

No.KeyDescription
1INDIVIDUAL

The legal entity is of an individual type

2COMPANY

The legal entity is of a company type


#inStorePaymentScenario

No.KeyDescription
1PaymentCodeIndicates that the user can use paymentCode to pay.
2OrderCodeIndicates that the user can use orderCode to pay.

3

EntryCode

Indicates that the user can use entryCode to pay.


#MethodType

No.KeyDescription
1POSTIndicates that the request that is sent to the redirection address needs to be a POST request.
2GETIndicates that the request that is sent to the redirection address needs to be a GET request.
3SCANIndicates that the request that is sent to the redirection address needs to be a SCAN request.


#OsType

No.KeyDescription
1IOSiOS
2ANDROIDAndroid


#PaymentMethodCategoryType

No.KeyDescription
1

WALLET

Indicates that the payment method is a wallet payment.

2

CARD

Indicates that the payment method is a card payment, including a credit card payment.


#PaymentMethodDetailType

No.KeyDescription
1

card

Asset type is a card.

2

externalAccount

Asset type is external account.

3

coupon

Asset type is coupon.

4

discount

Asset type is discount.


#PaymentNotifyType

No.KeyDescription
1PAYMENT_RESULTNotice of payment results
2OFFLINET_PAYMENT_CODEOffline payment result code notification


#PaymentOptionDetailType

No.

Field

Description

1CARD

MANDATORY String (64)

The payment type is CARD.

#

#ProductCodeType

No.KeyDescription
1AGREEMENT_PAYMENTMulti-use agreement for auto debit product.
The agreement stays valid until it is explicitly canceled.
2IN_STORE_PAYMENTOffline in-store payment
3CASHIER_PAYMENTCashier Payment


#PSPName

No.KeyDescription
1

AlipayCN

The Alipay+ MPP name of Alipay CN wallet.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

2AlipayHK

The Alipay+ MPP name of Alipay HK wallet.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

3

TrueMoney

The Alipay+ MPP name of TrueMoney wallet.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

4

Dana

The Alipay+ MPP name of Dana wallet.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

5

bKash

The Alipay+ MPP name of bKash wallet.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

6

TouchNGo

The Alipay+ MPP name of Touch 'n Go wallet.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

7

Easypaisa

The Alipay+ MPP name of Easypaisa wallet.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

8

KaKaoPay

The Alipay+ MPP name of KaKaoPay wallet.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

9

Gcash

The Alipay+ MPP name of Gcash wallet.

Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.


#ReasonCode

No.KeyDescription
1

MCC_INVALID

Invalid MCC

2MISSING_OR_INCORRECT_INFO

Information missing or incorrect information

3

REJECT_FOR_RISK

Rejected due to risk

4

INFO_UPDATE_FORBIDDEN

Information update is forbidden

5

STORE_REPORT_FAILED

The report process of the store is failed. For more information, see storeReportDetails


#ReportStatus

No.KeyDescription
1SUCCESS


Indicates that the report status is successful.

2FAILED

Indicates that the report status is failed.

3PROCESSING


Indicates that the report status is processing.


#ResultStatusType

No.KeyDescription
1S


Indicates that the result status is successful.

2F

Indicates that the result status is failed.

3U

Indicates that the result status is unknown.


#ScopeType

No.KeyDescription
1BASE_USER_INFOIndicates that the unique user ID can be obtained.
2USER_INFOIndicates that the complete user information, such as name or avatar, can be obtained.
3AGREEMENT_PAYIndicates a withholding authorization. The AuthClient can use the token to withhold user's assets.


#StoreType

No.KeyDescription
1IN_STOREIndicates a physical store
2ONLINEIndicates an online store


#TerminalType

No.KeyDescription
1APPMobile terminal
2WEBWeb, such as the desktop version of the merchant website
3WAPThe WAP version of the website on a mobile device like iPad, tablet, and so on


#TokenStatusType

No.KeyDescription
1VALID

The token status is valid.

2INVALID


The token status is invalid.


#TransactionStatusType

No.KeyDescription
1SUCCESSTransction is successful.
2FAILTransaction is failed.
3PROCESSINGTransaction is being processed.
4CANCELLEDTransaction is canceled.


#TransactionType

No.KeyDescription
1PAYMENTIndicates a payment process.
2REFUNDIndicates a refund process.
3CANCELIndicates a cancellation process.

4

AUTHORIZATION

Indicates an authorization process.

5

CAPTURE

Indicates a capture process.

6

VOID

Indicates a void for authorization.


#UserIdentityType

No.KeyDescription
1

WALLET_TOKEN

Wallet access token


#WalletPaymentMethodType

No.KeyDescription
1TRUEMONEY

TrueMoney wallet.

Notes:

  • The minimum payment amount allowed for this wallet is 1 THB.
  • The minimum refund amount allowed for this wallet is 1 THB.
2ALIPAY_HK

Alipay HK wallet.

Notes:

  • For the auto debit payment, the minimum payment amount allowed for this wallet is 0.01 HKD.
  • For the auto debit payment, the minimum refund amount allowed for this wallet is 0.01 HKD.
  • For the cashier payment, the minimum payment amount allowed for this wallet is 0.1 HKD.
  • For the cashier payment, the minimum refund amount allowed for this wallet is 0.1 HKD.
3TNG

Touch 'n Go wallet

Notes:

  • The minimum payment amount allowed for this wallet is 1 MYR.
  • The minimum refund amount allowed for this wallet is 1 MYR.
4ALIPAY_CN

Alipay CN wallet

5GCASH

Gcash wallet

Notes:

  • The minimum payment amount allowed for this wallet is 1 PHP.
  • The minimum refund amount allowed for this wallet is 1 PHP.
6DANA

Dana wallet

Notes:

  • The minimum payment amount allowed for this wallet is 300 IDR.
  • The minimum refund amount allowed for this wallet is 300 IDR.

7

BKASH

bKash wallet

Notes:

  • The minimum payment amount allowed for this wallet is 0.01 BDT.
  • The minimum refund amount allowed for this wallet is 0.01 BDT.

8

EASYPAISA

EasyPaisa wallet

Notes:

  • The minimum payment amount allowed for this wallet is 100 PKR.
  • The minimum refund amount allowed for this wallet is 100 PKR.

9

KAKAOPAY

KakaoPay wallet

Notes:

  • The minimum payment amount allowed for this wallet is 50 KRW.
  • The minimum refund amount allowed for this wallet is 50 KRW.

10

CONNECT_WALLET

Alipay+ Mobile Payment Partner