WorldFirst DocsWorldFirst DocsDOCS

Data dictionary

Model

Account

Field

Data type

Required

Description

holderName

UserName object

No

Name of the account holder.

accountNo

String

No

The account number.

More information:

  • Maximum length: 64 characters

bankName

String

No

Name of the bank.

More information:

  • Maximum length: 2048 characters

bankBIC

String

No

8-to-11-character SWIFT code that represents the bank identifier code.

Note:

  • Rule: {"checkRules": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$"}

More information:

  • Maximum length: 64 characters

multipleCurrencies

Array<String>

No

An array of multiple currencies that the account uses. For each element, use the 3-character ISO-4217 currency code that represents the currency used.

Address

Field

Data type

Required

Description

region

String

Yes

2-letter ISO3166 country/region code that represents the country/region of the address.

More information:

  • Maximum length: 2 characters

state

String

Yes

State/County/Province.

More information:

  • Maximum length: 64 characters

city

String

Yes

City/District/Suburb/Town/Village.

More information:

  • Maximum length: 64 characters

address1

String

Yes

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

More information:

  • Maximum length: 256 characters

address2

String

No

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

More information:

  • Maximum length: 256 characters

zipCode

String

No

ZIP or postal code.

More information:

  • Maximum length: 32 characters

Amount

Field

Data type

Required

Description

currency

String

Yes

3-character ISO-4217 currency code that represents the currency used.

More information:

  • Maximum length: 3 characters

value

String

Yes

0 or a positive integer. The value is in the smallest currency unit(for example, if the value is 100, the amount is $1.00 when currency is USD, or ￥100 when currency is JPY).

More information:

  • Maximum length: 16 characters

Attachment

Field

Data type

Required

Description

attachmentType

String

Yes

Type of the attachment file.

Valid values are:

  • BUSINESS_LICENSE: The attachment of the business license of the Customer. In this case, the merchant is an enterprise.
  • ID_CARD_FRONT_SIDE: The attachment of the front side of the Customer's ID card. In this case, the merchant is an individual.
  • ID_CARD_BACK_SIDE: The attachment of the back side of the Customer's ID card. In this case, the merchant is an individual.

For more details about each value, refer to the AttachmentType section.

More information:

  • Maximum length: 32 characters

file

String

Yes

URL of the attachment file.

More information:

  • Maximum length: 1024 characters

attachmentName

String

No

Name of the attachment file.

More information:

  • Maximum length: 128 characters

AuditDetail

Field

Data type

Required

Description

auditKey

String

Yes

The specific field that caused the submission to fail to pass the review. For example, ubo.individualLegalName.

  • For more details about possible values, refer to the References section in the inquiryRegisterCustomer chapter.
  • For each auditKey, there could be multiple auditReason fields.

auditReason

String

Yes

The reason that the submission failed to pass the review. For example, notMatch, which means the submitted information does not match the actual information.

Note:

  • For more details about possible values, refer to the References section in the inquiryRegisterCustomer chapter.

auditKeyType

String

Yes

The type of auditKey that failed to pass the review. For example:

  • Merchant
  • CONTACT_PERSON

index

String

No

WorldFirst(Alipay) uses this field to indicate which board member/legal representative/ubo failed to pass the review.

Note:

  • This field is not returned when the information is not available. For example, when the company type is UBO but related information is not provided.

certificateNo

String

Yes

The certificate number of the specific board member/legal representative/ubo that failed to pass the review.

memo

String

Yes

Detailed information about the reason that the submission failed to pass the review.

BankAccountPaymentMethodDetail

Field

Data type

Required

Description

bankAccountNo

String

No

Bank account number.

Notes:

  • This field is required when PaymentMethod.paymentMethodType is BANK_ACCOUNT.
  • This field is required when bankAddress.region is not EU.

Rule:

  • {"checkRules": "^[A-Z0-9]{0,34}$"}

More information:

  • Maximum length: 64 characters

holderAccountName

UserName object

Yes

Name of the account holder.

Notes:

  • This field is required when PaymentMethod.paymentMethodType is BANK_ACCOUNT.
  • For transfers inbound to China, use Chinese names.
  • For transfers to US or EU, use English names.

Rule:

  • {"checkRules": "^[A-Za-z0-9_,()\\s.,]{0,70}$"}.

holderAccountType

String

No

The type of the holder account.

Valid values are:

  • INDIVIDUAL: The holder is an individual.
  • COMPANY: The holder is a company.

For more details about each value, refer to the holderAccountType section.

holderAddress

Address object

No

Address of the holder.

bankName

String

No

Name of the bank.

Notes:

  • This field is required when PaymentMethod.paymentMethodType is BANK_ACCOUNT.
  • Maximum length is limited to 35 characters when transferFactor.transferFundType is not FX_CNY.

Rule:

  • {"checkRules": "^.{0,35}$"}

More information:

  • Maximum length: 128 characters

branchBankName

String

No

Name of the bank branch.

  • Maximum length: 128 characters

routingNumber

String

No

Code that is used to identify a specific financial institution, which includes:

  • ABA routing number
  • BSB routing number
  • SORT code

bankAddress

Address object

No

Address of the bank.

bankBIC

String

No

8-to-11-character SWIFT code that represents the bank identifier code.

Rule:

  • {"checkRules": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$"}

More information

  • Maximum length: 11 characters

bankAccountIBAN

String

No

International Bank Account Number(IBAN) of the Beneficiary Account.

Notes:

  • This field is required when bankAddress.region is EU. 

Rule:

  • {"checkRules": "^[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}$"}.

More information:

  • Maximum length: 34 characters

BoardMember

Field

Data type

Required

Description

legalName

String

Yes

The legal name of the board member.

More information:

  • Maximum length: 128 characters

certificates

Array<Certificate object>

Yes

Certificates of the board member, including information such as the certificate type and the certificate number of the board member.

attachments

Array<Attachment object>

Yes

Attachments of the certificates.

BusinessContactEntity

Field

Data type

Required

Description

businessContactType

String

Yes

Type of the business contact.

Valid values are:

  • DIRECTOR
  • SHAREHOLDER
  • BOARD_MEMBER
  • UBO
  • LEGAL_REPRESENTATIVE
  • AUTHORIZED_SIGNATORY
  • COMMON

For more details about valid values, refer to the BusinessContactType section.

legalRepresentative

LegalRepresentative object

Yes(Conditional)

Information about the legal representative.

Note:

  • This field is required when the board member is located in mainland China(when businessContactType is LEGAL_REPRESENTATIVE).

boardMember

BoardMember object

Yes(Conditional)

Information about the board member.

Note:

  • This field is required when the board member is located in mainland China(when businessContactType is BOARD_MEMBER).

ubo

Ubo object

Yes(Conditional)

Information about the Ultimate Beneficial Owner of the company.

Note:

  • This field is required when Customer.BusinessContactEntity.BusinessContactType is UBO, and shareHoldingRatio >= 0.25.

legalEntityType

String

Yes

Type of the legal entity.

Valid values are:

  • INDIVIDUAL: The legal entity is an individual.
  • COMPANY: The legal entity is a company.

For more details about each value, refer to the

legalEntityType section.

individual

Individual object

Yes(Conditional)

Information of the individual.

Note:

  • This field is required when the value of BusinessContactEntity.legalEntityType is INDIVIDUAL.

company

Company object

Yes(Conditional)

Information about the company.

Note:

  • This field is required when the value of BusinessContactEntity.legalEntityType is COMPANY.

shareHoldingRatio

String

Yes(Conditional)

The shareholder equity ratio. Use decimal for percentage. For example, 0.1 = 10%.

Note:

  • This field is conditionally required when BusinessContactEntity.ubo has value.

More information:

  • Maximum length: 32 characters

BusinessPartner

Field

Data type

Required

Description

businessName

String

Yes

The operating name of the business.

More information:

  • Maximum length: 256 characters

mcc

String

Yes

Merchant category code

More information:

  • Maximum length: 32 characters

websites

Array<Website object>

No

Websites of the business partner.

businessContactEntities

Array<BusinessContactEntity object>

Yes

Entities of the business contact.

Note:

  • This field is required for company registration (When customer.legalEntityType is COMPANY.)

CardDataCfgInfo

Field

Data type

Required

Description

cardColumnCode

String

Yes

English Description of a set of rules that needs to be applied to the Customer's card.

cardColumnName

String

Yes

Chinese Description of a set of rules that needs to be applied to the Customer's card.

required

String

Yes

Indicate whether the parameter is required or not.

Valid values are:

  • Y: The parameter is required, need to follow the value rule.
  • N: The parameter is not required, need to follow the value rule.

cardColumnValueRule

String

Yes

A set of rules that needs to be applied to the Customer's card.

Certificate

Field

Data type

Required

Description

certificateType

String

Yes

Type of the certification.

Valid values are:

  • ID_CARD: Identification card
  • PASSPORT: Passport
  • BUSINESS_LICENSE: Business license
  • MAINLAND_TRAVEL_PERMIT_HK_MC: Mainland Travel Permit for Hong Kong and Macao Residents
  • MAINLAND_TRAVEL_PERMIT_TAIWAN: Mainland Travel Permit for Taiwan Residents

For more details about each value, refer to the

certificateType section.

More information:

  • Maximum length: 32 characters

certificateNo

String

Yes

Certificate identifier number.

More information:

  • Maximum length: 64 characters

holderName

UserName object

Yes

Certificate holder name.

effectivePeriodType

String

Yes

Type of the certificate effective period.

Valid values are:

  • TIME_RANGE: The certificate is effective for a time range. You need to define the time range with effectiveDate and expireDate.
  • LONG_TERM: The certificate is effective for the long term.

For more details about each value, refer to the

effectivePeriodType section.

effectiveDate

DateTime object

Yes(Conditional)

The date that the certification is effective.

Note:

  • This field is required when:
    • customer.legalEntityType is COMPANY.
    • effectivePeriodType is TIME_RANGE.
  • The value of this field follows the ISO 8601 standard format and +08:00 timezone. For example, 2018-09-03T00:00:00+08:00.

expireDate

DateTime object

Yes(Conditional)

The date that the certification will expire.

Note:

  • This field is required when:
    • customer.legalEntityType is COMPANY.
    • effectivePeriodType is TIME_RANGE.
  • The value of this field follows the ISO 8601 standard format and +08:00 timezone. For example, 2018-09-03T00:00:00+08:00.

Company

Field

Data type

Required

Description

legalName

String

Yes

Legal name of the company.

More information:

  • Maximum length: 128 characters

enterpriseType

String

Yes

This field indicates if it is a listed company on the stock market or not.

Valid values are:

  • IPO: Listed company
  • UNIPO: Unlisted company

For more details about each value, refer to the

enterpriseType section.

stockCode

String

Yes(Conditional)

Ticker symbol of the company.

Note:

  • This field is required when enterpriseType is IPO.

More information:

  • Maximum length: 32 characters

stockMarket

String

Yes(Conditional)

2-character ISO 3166 country/region code that represents the country/region where the stock is located at.

Note:

  • This field is required when enterpriseType is IPO.

More information:

  • Maximum length: 32 characters

registrationAddress

Address object

Yes

Registration address of the company.

attachments

Array<Attachment object>

Yes

Attachments of the company certificates' photocopies.

contactWays

Array<ContactWays object>

Yes

Company's contact methods.

certificates

Array<Certificate object>

Yes

Certifications of the company.

companyType

String

No

Defines the type of the company.

Default value:

  • COMPANY

For more details about possible values, refer to the companyType section.

industryType

String

Yes

Defines the type of industry that the company belongs to. For example, "Real estate activities".

Note:

  • For more information about the possible values, refer to the References section.

More information:

  • Maximum length: 256 characters

businessName

String

No

The business name of the company.

businessAddress

Address object

No

The operation address of the company.

extendInfo

String

No

This field contains the following keys in JSON string format:

  • OPERATION_ADDRESS: Business address where the business operation is registered. Use the Address format.

More information:

  • Maximum length: 4096 characters

ContactWay

Field

Data type

Required

Description

contactWayType

String

Yes

Company's preferred contact method.

Valid values are:

  • PHONE: Phone
  • EMAIL: Email
  • FAX: Fax
  • WEBSITE: Website
  • CS_PHONE: Customer service phone number
  • CS_EMAIL: Customer service email address

For more details about each value, refer to the ContactWayType section.

contactWayInfo

String

Yes

Contact details. For example, the contact's phone number. For example: 86-88888888, test@abc.com.

More information:

  • Maximum length: 256 characters

contactWayDesc

String

Yes

Description of the contact method. For example: PHONE, EMAIL.

More information:

  • Maximum length: 512 characters

Customer

Field

Data type

Required

Description

customerId

String

No

The unique ID assigned by the WorldFirst(Alipay) to identify a Customer.

More information:

  • Maximum length: 32 characters

referenceCustomerId

String

Yes

The unique ID assigned by the Partner to identify a Customer.

More information:

  • Maximum length: 64 characters

customerType

String

Yes

Defines the type of Customer.

Valid values are:

  • BUSINESS_PARTNER: The Customer is a business partner.
  • USER: The Customer is a user.

For more details about each value, refer to the CustomerType section.

businessPartner

BusinessPartner object

Yes(Conditional)

Information about the business partner.

Note:

  • This field is required when the value of customerType is BUSINESS_PARTNER.

user

User object

Yes(Conditional)

Information about the user.

Note:

  • This field is required when the value of customerType is USER.

legalEntityType

String

Yes

Type of the legal entity.

Valid values are:

  • INDIVIDUAL: The customer is an individual.
  • COMPANY: The customer is a company.

For more details about each value, refer to the

LegalEntityType section.

individual

Individual object

Yes(Conditional)

Information of the individual.

Note:

  • This field is required when the value of legalEntityType is INDIVIDUAL.

company

Company object

Yes(Conditional)

Information about the company.

Note:

  • This field is required when the value of legalEntityType is COMPANY.

Goods

Field

Data type

Required

Description

goodsTitle

String

No

Title of the goods.

goodsName

String

Yes

Name of the goods.

More information:

  • Maximum length: 256 characters

goodsQuantity

Integer

Yes

Quantity of the goods.

More information:

  • Maximum length: 32 characters

Individual

Field

Data type

Required

Description

legalName

String

Yes

The legal name of the individual.

More information:

  • Maximum length: 128 characters

wealthSources

List<String>

No

Source of the wealth.

Possible values include:

  • Financial Investments
  • Property Investments
  • Inheritance or Gifting
  • Ownership of a Business
  • Lottery/Gambling
  • Life Insurance Policy
  • Other Investments
  • Others

gender

String

No

Gender of the individual.

Valid values are:

  • FEMALE
  •  MALE

For more details about each value, refer to the

Gender section.

attachments

Array<Attachment object>

Yes

Attachments of the certificates.

certificates

Array<Certificate object>

Yes

Certificates of the individual.

birthDate

DateTime object

Yes(Conditional)

Date of birth of the individual.

Note:

  • Use the format of YYYY-MM-DD for this field. For example, 2000-01-01.
  • This field is only required for the customer.individualfield.

nationality

String

Yes(Conditional)

2-character ISO 3166 country/region code that represents the country/region of the individual. For example: CN.

Note:

  • This field is only required for the customer.individualfield.

contactWays

Array<ContactWay object>

Yes(Conditional)

Contact methods of the individual.

Note:

  • This field is only required for the customer.individualfield.

contactAddress

Address object

Yes(Conditional)

Contact address of the individual.

Note:

  • This field is only required for the customer.individualfield.
  • In the case of registering as an individual, the value of this field is the same as the address on the ID card.

LegalRepresentative

Field

Data type

Required

Description

legalName

String

Yes

The legal name of the legal representative.

More information:

  • Maximum length: 128 characters

certificates

Array<Certificate object>

Yes

Certificates of the legal representative.

attachments

Array<Attachment object>

Yes

Attachments of the certificates.

Merchant

Field

Data type

Required

Description

merchantId

String

Yes

The unique ID assigned by the Partner to identify the merchant(Customer).

Note:

  • This field can be the same as the customerId field which is obtained by calling the registerCustomer API.

More information:

  • Maximum length: 32 characters

referenceMerchantId

String

Yes(Conditional)

The unique ID assigned by the Partner to identify the Merchant(Customer).

Note:

  • This field is only required for the tradeOrders.merchant field in the submitTradeOrder API.

More information:

  • Maximum length: 64 characters

merchantName

String

No

Name of the merchant.

More information:

  • Maximum length: 256 characters

merchantAddress

Address object

Yes

Detailed address of the merchant.

Note:

  • This is not the store address. For individual merchants, use the individual address. For companies, use the company address.

merchantMCC

String

Yes(Conditional)

Merchant category code.

Note:

  • This field is only required for the tradeOrders.merchant field in the submitTradeOrder API.

store

Store object

Yes(Conditional)

Information about the merchant store/website.

Note:

  • This field is only required for the tradeOrders.merchant field in the submitTradeOrder API.

PaymentMethod

Field

Data type

Required

Description

paymentMethodType

String

Yes

Type of the payment method.

Valid values are:

  • BANK_ACCOUNT: Bank account
  • WALLET: Alipay Wallet

For more details about each value, refer to the

paymentMethodType section.

paymentMethodMetaData

String

Yes

A JSON string that describes the payment details.

Note:

  • When the value of paymentMethodType is BANK_ACCOUNT:
    • paymentMethodMetaData is a string.

More Information:

  • Maximum length: 2048 characters

Product

Field

Data type

Required

Description

productType

String

Yes

Type of the product.

Valid values are:

  • ALIPAY_BUSINESS: Registered with Alipay+.
  • ALIPAY_CN: Registered with Alipay China.

For more details about each value, refer to the

productType section.

productStatus

String

Yes(Conditional)

Status of the product.

Valid values are:

  • ACTIVE: The product is active.
  • INACTIVE: The product is inactive.

For more details about each value, refer to the

productStatus section.

Note:

  • This field is optional for the registerCustomer interface.
  • This field is required for the inquiryRegisterCustomer and notifyRegisterCustomer interfaces.

reasonCode

String

No

Reason for registration failure.

Note:

  • This field is required when productStatus is INACTIVE.

Valid values are:

  • MISSING_OR_INCORRECT_INFO
  • PRODUCT_CONFLICT
  • REJECT_FOR_RISK

For more details about each value, refer to the ReasonCode section.

More information:

  • Maximum length: 64 characters

Quote

Field

Data type

Required

Description

baseCurrency

String

Yes

3-character ISO-4217 currency code that the first currency in the quoteCurrencyPair uses. For example, in currency pair USD/CNY, baseCurrency is USD.

More information:

  • Maximum length: 3 characters

quoteCurrencyPair

String

Yes

Two 3-character ISO 4217 currency codes that define the currency pair for the quote. Format: base currency/quote currency. For example. RUB/USD。

More information:

  • Maximum length: 7 characters

quoteId

String

Yes

The unique ID assigned by the Partner to identify a quote.

More information:

  • Maximum length: 64 characters

quotePrice

String

Yes

The price represents how much of the quote currency you need to get 1 quote unit of the base currency.

  • For example, if quotaPrice is 7, and the quoteUnit is 1, in currency pair USD/CNY, you need 7 CNY to buy 1 USD.

Note:

  • The number must be in decimal.

More information:

  • Maximum length: 20 characters

quoteUnit

String

Yes

Multiplier or divisor applied to quotePrice. Usually, the value is 1.

1 base currency = quotePrice * quoteUnit * quote currency.

More information:

  • Maximum length: 64 characters

quoteStartTime

Datetime object

No

The date and time when quotePrice is effective.

Note:

  • The value of this field follows the ISO 8601 standard format. For example, 2019-01-01T01:01:01+08:00.

quoteExpiryTime

Datetime object

No

The date and time when quotePrice expires.

Note:

  • The value of this field follows the ISO 8601 standard format. For example, 2019-01-01T01:01:01+08:00.

ReceivingAccount

Field

Data type

Required

Description

currency

String

Yes

3-character ISO-4217 currency code that represents the currency of the Receiving Account.

More information:

  • Maximum length: 3 characters

walletAccountNo

String

Yes

The Receiving Account number assigned by WorldFirst(Alipay).

More information:

  • Maximum length: 128 characters

RegisterDetail

Field

Data type

Required

Description

registerStatus

String

Yes

The status of the registration.

Valid values are:

  • SUCCESS: Success
  • FAILED: Failure
  • PROCESSING: Processing
  • ACCEPT: Accepted

For more details about each value, refer to the

registerStatus section.

registerMessage

String

Yes(Conditional)

Result message that describes registerStatus in detail.

Note:

  • This field is required when registerStatus is FAILED.

More information:

  • Maximum length: 64 characters

reasonCode

String

Yes(Conditional)

Reason for registration failure.

Note:

  • This field is required when registerStatus is FAILED.

Valid values are:

  • MISSING_OR_INCORRECT_INFO
  • PRODUCT_CONFLICT
  • REJECT_FOR_RISK

For more details about each value, refer to the ReasonCode section.

More information:

  • Maximum length: 256 characters

Result

Field

Data type

Required

Description

resultCode

String

Yes

Result code. Possible values are listed in the Result codes table on this page.

More information:

  • Maximum length: 16 characters

resultMessage

String

No

Result message that describes resultCode in detail.

More information:

  • Maximum length: 64 characters

resultStatus

String

Yes

Result status. Valid values are:

  • S: Successful
  • F: Failed
  • U: Unknown

For more details about each value, refer to the resultStatusType section.

Shipping

Field

Data type

Required

Description

transportType

String

Yes

The type of logistics for transportation.

Possible values are:

  • land carriage
  • air parcel

For more details about each value, refer to the TransportType section.

shippingCarrier

String

Yes

Name of the carrier, such as FedEx, UPS, USPS, etc.

More information:

  • Maximum length: 64 characters

shippingInvoiceNo

String

Yes

Shipping invoice number.

More information:

  • Maximum length: 64 characters

shippingAddress

Address object

Yes

The shipping address.

Store

Field

Data type

Required

Description

referenceStoreId

String

Yes

The ID assigned by the Partner to identify a store that is associated with the Customer(merchant).

More information:

  • Maximum length: 64 characters

storeAddress

Address object

No

The physical address where the store is located.

Note:

  • This field is required when bopCode is not 122030.

storeWebSites

Array<Website> object

No

Website URL for online stores.

Note:

  • This field is required when bopCode is 122030.

TradeOrder

Field

Data type

Required

Description

orderId

String

Yes

The unique ID assigned by the Partner to identify a trade order.

Note:

  • This field is an API idempotency field. For details about API idempotency, see the Idempotency chapter.

More information:

  • Maximum length: 64 characters

referenceOrderId

String

Yes

The unique ID that is assigned by the Partner to identify the transfer order and display it to the Customer(Merchant).

More information:

  • Maximum length: 64 characters

payTime

Datetime object

Yes

Time that the payment takes place.

Note:

  • The value of this field follows the ISO 8601 standard format. For example, 2019-01-01T01:01:01+08:00.

orderTime

Datetime object

Yes

Time that the trade order takes place.

Note:

  • The value of this field follows the ISO 8601 standard format. For example, 2019-01-01T01:01:01+08:00.

transAmount

Amount object

Yes

The actual payment/clearing/settlement amount.

orderAmount

Amount object

Yes

The transaction amount in the merchant system.

bopCode

String

Yes

Code for the Balance of Payments.

Commonly used values are:

  • 700001: Partner settlement. In this case, the transferToRegion field cannot be CN, KR, or TH.
  • 700002: Commission service trade. In this case, the transferToRegion field cannot be CN, KR, or TH.

If you do not know the appropriate value to use, contact Technical Support.

For more details about the value of the bopCode parameter, refer to the More information section in the submitTradeOrder API.

tradeBizType

String

Yes

Type of the merchant platform.

Valid values are:

  • B2B: Business to business
  • B2C: Business to consumer
  • C2C: Consumer to consumer (Currently not supported)

For more details about each value, refer to the

tradeBizType section.

merchant

Merchant object

Yes

Information of the merchant.

buyer

User object

No

Information of the buyer.

Note:

  • This field is required when transferFactor.transferFundType is FX_CNY or GLOBAL_CNH_CN.

seller

User object

No

Information of the seller.

Note:

  • This field is required when transferFactor.transferFundType is FX_CNY or GLOBAL_CNH_CN.

goods

Array<Goods object>

Yes

Information of the goods.

Note:

  • This field is required when transferFactor.transferFundType is FX_CNY and GLOBAL_CNH_CN.

shippings

Array <Shipping object>

No

Shipping information.

Note:

  • This field is required when bopCode is 122030.

TradeOrderResult

Field

Data type

Required

Description

orderId

String

Yes

The unique ID assigned by the Partner to identify a transaction.

More information:

  • Maximum length: 64 characters

orderStatus

String

Yes

Status of the trade order review.

Valid values are:

  • ACCEPT
  • AVAILABLE
  • REJECT
  • PARTIAL_DECLARED
  • DECLARED

For more details, refer to orderStatus

resultMessage

String

Yes

Result message that describes resultCode in detail.

More information:

  • Maximum length: 512 characters

partialDeclaredAmount

Amount object

Yes(Conditional)

The amount for value declaration.

Note:

  • This field is required when orderStatus is PARTIAL_DECLARED.

TransferOrderAddition

Field

Data type

Required

Description

referenceOrderId

String

No

The unique ID that is assigned by the Partner to identify the transfer order and display it to the Customer(Merchant).

Note:

  • This field is required when the Merchant tries to make transfers inbound to China with currency exchange.

More information:

  • Maximum length: 64 characters

transferFromAddition

TransferFromAddition object

Yes

Additional information about the entity that the transfer originates from.

transferToAddition

TransferToAddition object

Yes

Additional information about the beneficiary who receives the transfer.

TransferFactor

Field

Data type

Required

Description

transferFundType

String

Yes

Specify the scenario to which the transfer request belongs.

Valid values are:

  • FX_CNY
  • GLOBAL_CNH_CN
  • GLOBAL_WORLDFIRST
  • GLOBAL_GLOBAL_SERVICE

Note:

  • For FX_CNY and GLOBAL_CN_CN, the value of customer.user.userId is assigned by WorldFirst(Alipay).
  • For GLOBAL_GLOBAL_SERVICE, the value of customer.user.userId is assigned by the Partner, which shares the same value as referenceCustomerId.

For more details about each value, refer to the

TransferFundType section.

delegationMode

String

Yes(Conditional)

Indicates whether a delegated agent engages in the transfer.

Note:

  • This field is only required for the inquiryQuote, transfer, inquiryTransfer, and notifyTransfer interfaces.

Valid values are:

  • TRANSFER: Normal transfer with no delegation. This field is optional in this mode.
  • DELEGATION_TRANSFER: Transfer by a delegated agent. This field is required in this mode.
  • DELEGATION_WITHDRAW: Withdrawal by a delegated agent. This field is required in this mode.

For more details about each value, refer to the

DelegationModeType section.

More information:

  • Maximum length: 32 characters

TransferFromAddition

Field

Data type

Required

Description

payer

` object

Yes(Conditional)

Information about the entity that makes the payment.

Note:

transferFromAddition.payer and transferFromAddition.merchant cannot be both empty.

merchant

Merchant object

Yes(Conditional)

Information of the merchant.

Note:

transferFromAddition.payer and transferFromAddition.merchant cannot be both empty.

transferFromRegion

String

Yes

2-character ISO-3166 country/region code that represents the country or region of the payer.

More information:

  • Maximum length: 2 characters

delegationMerchant

Merchant object

No

Information of the delegated merchant.

TransferFromDetail

Field

Data type

Required

Description

transferFromAmount

Amount object

Yes

Amount paid during the transfer request, also known as the payment amount.

feeAmount

Amount object

No

The transfer fee that WorldFirst(Alipay) charges from the Partner.

TransferQuota

Field

Data type

Required

Description

totalQuota

Amount object

Yes

Amount of the quota in total, which is the sum of available quota and frozen quota.

availableQuota

Amount object

Yes

Available quota, which is the result of total quota excluding frozen quota.

frozenQuota

Amount object

Yes

Frozen quota, which is the amount that is being processed.

TransferToAddition

Field

Data type

Required

Description

beneficiary

User object

Yes

Information of the Beneficiary.

transferToRegion

String

Yes

Beneficiary's country or region as defined by the two-character ISO 3166 country/region code. For example, US

More information:

  • Maximum length: 2 characters

transferRemark

String

No

Remarks for the transfer.

Note:

  • Specify this field if you intend to make a remark upon the transfer.

More information:

  • Maximum length: 128 characters

bopCode

String

Yes

Code for the Balance of Payments.

Commonly used values are:

  • 700001: Partner settlement. In this case, the transferToRegion field cannot be CN, KR, or TH.
  • 700002: Commission service trade. In this case, the transferToRegion field cannot be CN, KR, or TH.

If you do not know the appropriate value to use, contact Technical Support.

For more details about the value of bopCode parameter, refer to the More information section in the transfer API.

TransferToDetail

Field

Data type

Required

Description

transferToAmount

Amount object

Yes

The amount of the transfer that the beneficiary collects in a specific currency.

transferToMethod

PaymentMethod object

Yes

The method that the beneficiary uses to receive the transfer.

transferQuote

Quote object

No

Information on the transfer quotes.

Note:

  • This field is required when the Partner calls the transfer API to make a transfer order with currency exchange.

reverseAmount

Amount object

No

The amount of money that the Partner received for the reversal request.

Ubo

Field

Data type

Required

Description

legalName

String

Yes

The legal name of the individual.

More information:

  • Maximum length: 128 characters

certificates

Array<Certificate object>

Yes

Certificates of the individual.

attachments

Array<Attachment object>

Yes

Attachments of the certificates.

birthDate

String

Yes

Date of birth of the individual.

Note:

  • Use the format of YYYY-MM-DD for this field. For example, 2000-01-01.

nationality

String

Yes

2-character ISO 3166 country/region code that represents the country/region of the individual. For example: CN.

wealthSources

List<String>

No

Source of the wealth.

Possible values include:

  • Financial Investments
  • Property Investments
  • Inheritance or Gifting
  • Ownership of a Business
  • Lottery/Gambling
  • Life Insurance Policy
  • Other Investments
  • Others

contactWays

Array<ContactWay object>

Yes(Conditional)

Contact methods of the individual.

Note:

  • This field is only required for the customer.indivdualfield.

contactAddress

Address object

Yes(Conditional)

Contact address of the individual.

Note:

  • This field is only required for the customer.indivdualfield.
  • In the case of registering as an individual, the value of this field is the same as the address on the ID card.

User

Field

Data type

Required

Description

userId

String

Yes

The unique identifier that is assigned to the user.

More information:

  • Maximum length: 64 characters

userName

UserName object

Yes

Name of the user.

certificate

Certificate object

No

Certificate information of the user.

birthDate

Datetime object

No

Date of birth.

Note:

  • Use the format of YYYY-MM-DD for this field. For example, 2000-01-01.

nationality

String

No

2-character ISO-3166 country code that represents the nationality of the user.

More information:

  • Maximum length: 2 characters

userEmail

String

No

User's email.

More information:

  • Maximum length: 67 characters

userPhoneNo

String

Yes

User's phone number.

More information:

  • Maximum length: 31 characters

userAddress

Address object

No

User's address.

User for submitTradeOrder

This object concerns the following fields in the submitTradeOrder API:

  • tradeOrders.seller
  • tradeOrders.buyer

Field

Data type

Required

Description

userName

UserName object

Yes

User's name.

userId

String

Yes

The unique identifier that is assigned to the user.

More information:

  • Maximum length: 64 characters

userPhoneNo

String

No

User's phone number.

More information:

  • Maximum length: 31 characters

User for transfer

This object concerns the following fields in the transfer API:

  • transferOrderAddition.transferFromAddition.payer
  • transferOrderAddition.transferFromAddition.beneficiary

Field

Data type

Required

Description

userName

UserName object

Yes

User's name.

UserName

Field

Data type

Required

Description

fullName

String

Yes

User's full name

More information:

  • Maximum length: 64 characters

Website

Field

Data type

Required

Description

name

String

Yes

Website Name

More information:

  • Maximum length: 256 characters

url

String

Yes

Website URL

More information:

  • Maximum length: 2048 characters

Enumeration

Enumeration values below are used across all APIs. An enumeration value is a predetermined set of values defined as a String.

AttachmentType

Key

Description

ASSOCIATION_ARTICLE

Articles of association

AGREEMENT

Agreement

ADDRESS_PROOF

Address proof

FINANCIAL_REPORT

Financial report

OTHER_MATERIAL

Other materials

ID_CARD_FRONT_SIDE

The front side of an ID card

ID_CARD_BACK_SIDE

The back side of an ID card

BUSINESS_LICENSE

Business license

PASSPORT_PERSONAL_INFORMATION_PAGE

Passport personal info page

BusinessContactType

Key

Description

DIRECTOR

Director

SHAREHOLDER

Shareholder

BOARD_MEMBER

Board member

UBO

Ultimate Beneficial Ownership

LEGAL_REPRESENTATIVE

Legal representative

AUTHORIZED_SIGNATORY

Authorized Signatory

COMMON

Common people

CertificateType

Key

Description

ID_CARD

Identification card

PASSPORT

Passport

BUSINESS_LICENSE

Business license

MAINLAND_TRAVEL_PERMIT_HK_MC

Mainland Travel Permit for Hong Kong and Macao Residents

MAINLAND_TRAVEL_PERMIT_TAIWAN

Mainland Travel Permit for Taiwan Residents

CompanyType

Key

Description

COMPANY

The company is a regular company.

SOLE_PROPRIETORSHIP_ENTERPRISE

The company is a sole proprietorship enterprise.

PARTNERSHIP

The company is a partnership company.

ContactPersonType

Key

Description

SHAREHOLDER

The contact is a shareholder.

LEGAL_REPRESENTATIVE

The contact is a legal representative.

BOARD_MEMBER

The contact is a board member.

ContactWayType

Key

Description

PHONE

Phone

EMAIL

Email

FAX

Fax

WEBSITE

Website

CS_PHONE

Customer service phone number

CS_EMAIL

Customer service email address

CustomerType

Key

Description

USER

User

BUSINESS_PARTNER

Business partner

DelegationModeType

Key

Description

TRANSFER

Normal transfer with no delegation.

DELEGATION_TRANSFER

Transfer by a delegated agent.

DELEGATION_WITHDRAW

Withdrawal by a delegated agent.

EffectivePeriodType

Key

Description

TIME_RANGE

This value means that the certificate is valid for a certain time range.

LONG_TERM

This value means that the certificate is valid for the long term.

EnterpriseType

Key

Description

IPO

Listed company

UNIPO

Unlisted company

Gender

Key

Description

MALE

Male

FEMALE

Female

HolderAccountType

Key

Description

INDIVIDUAL

Individual

COMPANY

Company

LegalEntityType

Key

Description

INDIVIDUAL

Individual

COMPANY

Company

OrderStatus

Key

Description

ACCEPT

The trade order is accepted and pending for validation.

AVAILABLE

This trade order has passed validation and can be used for declaration.

REJECT

This trade order fails to pass the validation.

PARTIAL_DECLARED

Only parts of this transaction are used for declaration. Certain amounts of the transaction are leftover.

DECLARED

Transaction can be used for declaration without any leftover amounts.

PaymentMethodType

Key

Description

BANK_ACCOUNT

The beneficiary account is a bank account(bank card).

WALLET

The beneficiary account is an Alipay wallet.

ALIPAY_CN

The beneficiary account is an Alipay China e-Wallet.

ProductType

Key

Description

ALIPAY_BUSINESS

Register into Alipay+.

ALIPAY_CN

Register into Alipay China.

ProductStatus

Key

Description

ACTIVE

Active

INACTIVE

Inactive

ResultStatusType

Key

Description

S

Success

F

Failure

U

Unknown

RegisterStatus

Key

Description

SUCCESS

Success

FAILED

Failure

PROCESSING

Processing

ACCEPT

Accepted

RegistrationType

Key

Description

CN_REGISTRATION

Mainland China registration

HK_REGISTRATION

China Hong Kong registration

JP_REGISTRATION

Japan registration

ReasonCode

Key

Description

MISSING_OR_INCORRECT_INFO

Information is missing or incorrect.

PRODUCT_CONFLICT

Wrong product is used.

REJECT_FOR_RISK

Rejected for risk control reasons.

EXPIRED_CERTIFICATE

The certificate is expired.

CUSTOMER_ALREADY_EXIST

The customer's phone number is already registered or used.

BIZ_LICENSE_CANCELED

The submitted business license is canceled.

USER_FORBIDEN

The user is forbidden.

BIZ_LICENSE_REVOKED

The submitted business license is revoked.

USER_KYC_NOT_QUALIFIED

Registration failed due to the user's KYC status. The user is either not KYC compliant, or the KYC status is not qualified.

BIZ_LICENSE_LEGAL_INFO_NO_MATCH

The submitted business license does not match with the provided legal information. Retry with the correct information.

GMM_AUDITING_RECTIFY

GMM manual auditing failed. Rectify the information and retry.

SUBMIT_FAIL

The submission failed.

ATTACHMENT_NOT_MATCH

The submitted attachment does not match the information on the certificate. Retry with the correct information.

TradeOrderStatus

Key

Description

ACCEPT

Accepted and pending for validation

AVAILABLE

The trade order can be declared

REJECT

Rejected for risk control or other reasons

PARTIAL_DECLARED

Part of the trade order amount is declared

DECLARED

All the trade order amount is declared

TransferFundType

Key

Description

FX_CNY

Remit to China with foreign exchange.

GLOBAL_CNH_CN

Remit to China in CNY.

GLOBAL_GLOBAL_SERVICE

Remit to countries/regions other than China according to the settlement service agreement with merchants.

GLOBAL_WORLDFIRST

Remit to WorldFirst(Alipay) Account.

TransportType

Key

Description

land carriage

The type of transportation is by land carriage.

air parcel

The type of transportation is by air parcel.

TransferPurpose

Key

Description

FAMILY_SUPPORT

The purpose of the transfer is for family support.

SALARY

The purpose of the transfer is for salary.

TradeBizType

Key

Description

B2B

Business to business

B2C

Business to consumer

C2C

Consumer to consumer

@2024 WorldFirst