Field

Data type

Required

Description

accountNo

String

Yes

The unique identifier that is assigned to every WorldFirst Account. It represents the account number for the selected account type in accountType. 

More information:

• Maximum length: 64 characters

currencyList

List<String>

Yes

A currency list containing 3-character ISO 4217 currency codes that represent the currencies used.

Currently supported currencies:

• USD,EUR,GBP,NZD,CAD,AUD,JPY,SGD,HKD,CNH,PLN,SEK,MXN

More information:

• If this field is not indicated, WorldFirst returns all available currencies.

accountType

String

Yes

The type of the account.

Valid values are:

• ALIPAY_WALLET
• RECEIVE_ACCOUNT
• VIRTUAL_ACCOUNT

accountStatus

String

Yes

The status of the account.

Valid values are:

• ACTIVE: indicates the account status is active.
• ABNORMAL: indicates the account status is abnormal.

bankAccountList

Array<Bank Account object>

Conditional

The bank account information of the account that is being queried.

This field is required when both of the following conditions are met: 

• inquiryStore API is being called
•  accountType is VIRTUAL_ACCOUNT

Field

Data type

Required

Description

region

String

Yes

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

More information:

• Maximum length: 2 characters

state

String

No

State/County/Province.

More information:

• Maximum length: 8 characters

city

String

No

City/District/Suburb/Town/Village.

More information:

• Maximum length: 32 characters

address1

String

No

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

More information:

• Maximum length: 128 characters

address2

String

No

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

More information:

• Maximum length: 128 characters

zipCode

String

No

ZIP or postal code.

More information:

• Maximum length: 32 characters

Field

Data type

Required

Description

address1

String

No

Information about the address.

More information:

• Maximum length: 256 characters

Field

Data type

Required

Description

currency

String

Yes

3-character ISO 4217 currency code that represents the currency used. For example, USD.

More information:

• Maximum length: 3 characters

value

Integer

Yes

An integer. The value is in the smallest currency unit. For example, if the value is 100, the amount is $1.00 when the currency is USD, or ￥100 when the currency is JPY.

Field

Data type

Required

Description

fileName

String

Yes

The original file name of the submitted attachment

Example: file.pdf

More information about this field:

• Maximum length: 64 characters

fileKey

String

Yes

The key value of the attachment file

More information about this field:

• Maximum length: 128 characters

Field

Data type

Required

Description

bankAccountNo

String

Yes

The bank account number.

Note:

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

Rule:

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

More information:

• Maximum length: 64 characters

holderName

UserName object

Yes

The name of the account holder.

Note:

• For transfers inbound to China, use Chinese names.
• For transfers to the US or EU, use English names.

holderAccountType

String

No

The type of the account holder.

Valid values are:

• INDIVIDUAL: indicates the account holder is an individual.
• COMPANY: indicates the account holder is a company.

For the full list, refer to HolderAccountType.

holderAddress

Address object

No

The address of the holder.

currencyList

List<String>

No

A currency list containing 3-character ISO 4217 currency codes that represent the currencies used by the WorldFirst VA (Virtual Account) Account.

Supported currencies are:

• USD,EUR,GBP,NZD,CAD,AUD,JPY,SGD,HKD,CNH,PLN,SEK,MXN

bankName

String

Conditional

Name of the bank.

Note:

• This field is required when currencyList is one of the following values: USD, EUR, GBP, NZD, CAD, AUD, JPY, SGD, HKD, CNH, PLN, SEK, MXN

More information:

• Maximum length: 128 characters

routingNumber

String

Conditional

The code that identifies a specific financial institution, which includes:

• ABA routing number
• BSB routing number
• SORT code

Note: 

• This field is required when currencyList is USD or CAD.

More information:

• Maximum length: 64 characters

bankAddress

Address object

Conditional

The address of the bank.

Note: 

• Address1 is required when currencyList is one of the following values: USD, EUR, GBP, NZD, CAD. AUD, JPY, SGD, HKD, CNH, PLN, SEK, MXN
• region is required when currencyList is one of the following values: EUR, AUD, HKD, NZD, SGD, PLN, SEK, CNH, MXN

bankBIC

String

Yes

The bank Identifier Code. An 8 to 11-character code that identifies banks worldwide.

Note: 

• This field is required when currencyList is one of the following values: USD, EUR, GBP, NZD, CAD, AUD, JPY, SGD, HKD, CNH, PLN, SEK, MXN

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

Conditonal

The international Bank Account Number (IBAN) of the Beneficiary account.

Note:

This field is required when both of the following conditions are met:

• bankAddress.region is EU. 
• currencyList is GBP or EUR

Rule:

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

More information:

• Maximum length: 34 characters

bankAccountBSB

String

Conditional

A six-digit sort code that identifies Australian banks and branches. BSB (Bank State Branch) is used for local transactions in Australia. 

Note: 

• This field is required when currencyList is AUD or NZD. 

More information: 

• Maximum length: 128 characters

accountCreationDate

String

Conditional

The time when an account is created. 

Note: 

• This field is required when currencyList is one of the following values: USD, EUR, GBP, NZD, CAD, AUD, JPY, SGD, HKD, CNH, PLN, SEK, MXN

More information: 

• Format: YYYY-MM-DD, for example: 2022-12-02

bankCode

String

Conditional

The bank code. 

Note:

• This field is required when currencyList is one of the following values: MXN, CNH, SGD, JPY, HKD, GBP 

More information:

• Maximum length: 128 characters

branchCode

String

Conditional

A 3-digit or 3-letter code for bank branches. 

Note: 

• This field is required when currencyList is one of the following values: MXN, CNH, SGD, JPY, HKD

More information: 

• Maximum length: 128 characters

bankAccountType

String

Conditional

The type of the bank account. 

Note:

• This field is required when currencyList is JPY or CAD, and it takes one of the following values:

• checking: indicates a checking account
• saving: indicates a saving account

More information: 

• Maximum length: 34 characters

collectionArea

String

Conditional

The area where the transfer is received. 

Note: 

• This field is required when currencyList is AUD or NZD and it takes one of the following values: 

• GLOBAL: transfer is received internationally
• LOCAL: transfer is received locally

More information: 

• Maximum length: 34 characters

wireRoutingNumber

String

Conditional

A 9-digit number used to identify the financial agency that is conducting the electronic transfer, both sending or receiving, local or international. It can also be used to receive transfers from e-commerce platforms that are not based in the United States. 

Note:

• This field is sometimes required when currencyList is USD, depending on the e-commerce platforms where the transfer is made. 

More information:

Maximum length: 64 characters

Field

Data type

Required

Description

holderAccountName

UserName object

Yes

Name of the account holder.

Note:

• 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}$"}.

holderAddress

Address object

No

The address of the holder.

holderAccountType

String

No

The type of the account holder.

Valid values are:

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

For the full list, refer to HolderAccountType.

bankRegion

String

Yes

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

• Maximum length: 2 characters

routingNumber

String

No

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

• ABA routing number
• BSB routing number
• SORT code

More information:

• Maximum length: 64 characters

bankBIC

String

No

Bank Identifier Code. An 8 to 11-character code that identifies banks worldwide.

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

bankName

String

No

Name of the bank.

Note:

• When transferFactor.transferFundType is not FX_CNY, the field length cannot exceed 35.

Rule:

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

More information:

• Maximum length: 128 characters

branchBankName

String

No

Name of the bank branch.

More information:

• Maximum length: 128 characters

bankAddress

Address object

No

The address of the bank.

bankAccountNo

String

No

Bank account number.

Note:

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

Rule:

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

More information:

• Maximum length: 64 characters

bankAccountIBAN

String

No

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

Note:

• 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

Field

Data type

Required

Description

bankCountryCode

String

Yes

2-character ISO-3166 country/region code that represents the country/region where the bank locates.

More information:

• Maximum length: 2 characters

bankAccountNo

String

No

Bank account number.

Note:

• This field is required when bankCountryCode is not EU.

Rule: 

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

More information:

• Maximum length: 64 characters

bankAccountIBAN

String

No

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

Note:

• This field is required when  bankCountryCode is EU. 

Rule:

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

More information:

• Maximum length: 34 characters

beneficiaryType

String

No (Conditional)

The beneficiary type. Specify this parameter if the value of the transferToDetail.transferToAmount.currency parameter is CNY .

Valid values are:

• THIRD_PARTY_COMPANY_BANK_ACCOUNT: indicates the beneficiary is a third-party company bank account.
• THIRD_PARTY_PERSONAL_BANK_ACCOUNT: indicates the beneficiary is a third-party personal bank account.

bankAccountLocalName

String

No (Conditional)

The bank account holder's name in local language. Specify this parameter if the value of the transferToDetail.transferToAmount.currency parameter is CNY .

More inforamtion about this field:

• Maximum length: 70 characters

bankLocalName

String

No (Conditional)

The bank name in local language. Specify this parameter if the value of the transferToDetail.transferToAmount.currency parameter is CNY .

More inforamtion about this field:

• Maximum length: 128 characters

routingNumber

String

No (Conditional)

The routing number of a specific financial institution, which includes ABA routing number, BSB routing number, and Sort code.

Specify this parameter if the value of the transferToDetail.transferToAmount.currency parameter is CNY  and set its value as the bank identifier code, for example, 910290003990.

More information:

• Maximum length: 64 characters

bankAccountName

String

No

The account holder's name.

More inforamtion about this field:

• Maximum length: 70 characters

bankName

String

No

Name of the bank.

More information:

• Maximum length: 128 characters

branchBankName

String

No

Name of the bank branch.

More information:

• Maximum length: 128 characters

bankAddress

Address object

No

The address of the bank.

bankBIC

String

No

Bank Identifier Code. An 8 to 11-character code that identifies banks worldwide.

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

beneficiaryAddress

String

No

The address of the beneficiary.

beneficiaryCountryCode

String

No

2-character ISO-3166 country/region code that represents the country/region where the beneficiary locates.

Field

Data type

Required

Description

beneficiaryToken

String

Yes

A ciphered text that contains information about the details of the beneficiary's bank account.

Note:

• The cipher is encoded in the Base64 algorithm. For more details about encoding, refer to the message encoding chapter.

bindBeneficiaryRequestId

String

Yes

The unique ID assigned by the initiator to identify a bind beneficiary request.

Note:

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

beneficiaryBankAccount

BeneficiaryBankAccount object

Yes

Details about the beneficiary's bank account.

countryCode

String

Yes

2-character ISO 3166 country/region code that represents the country/region where the beneficiary locates.

More information:

• Maximum length: 2 characters

currency

String

Yes

3-character ISO 4217 currency code that represents the currency used. Currently, the following currencies are supported:

• USD,EUR,GBP,NZD,CAD,AUD,JPY,SGD,HKD,CNH

beneficiaryType

String

Yes

Defines the type of the beneficiary's card.

Valid values are:

• THIRD_PARTY_COMPANY_BANK_ACCOUNT
• THIRD_PARTY_PERSONAL_BANK_ACCOUNT

For the full list, refer to BeneficiaryType.

beneficiaryNick

String

Yes

The nickname of the beneficiary. The nickname is defined by the Customer to identify the beneficiary easily.

status

String

Yes

Indicates whether the beneficiary is valid or not.

Possible values are:

• SUCCESS
• FAIL

For the full list, refer to status.

referenceBeneficiaryId

String

No

The unique ID defined by the Partner to identify a beneficiary. 

More information:

• Maximum length: 64 characters

Field

Data type

Required

Description

bankAccountName

String

No

The name of the beneficiary's bank account.

bankAccountNo

String

No

The number of the bank account.

Note:

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

Rule:

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

More information:

• Maximum length: 64 characters

bankName

String

No

Name of the bank.

Note:

• When transferFactor.transferFundType is not FX_CNY, the field length cannot exceed 35.

Rule:

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

More information:

• Maximum length: 128 characters

bankBIC

String

No

Bank Identifier Code. An 8 to 11-character code that identifies banks worldwide.

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.

Note:

• 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

routingNumber

String

No

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

• ABA routing number
• BSB routing number
• SORT code

More information:

• Maximum length: 64 characters

beneficiaryCountryCode

String

No

2-character ISO 3166 country/region code that represents the country/region where the beneficiary's bank is located at.

More information:

• Maximum length: 2 characters

beneficiaryPhone

String

No

Phone number of the beneficiary. 

bankBranchCode

String

No

Branch code of the beneficiary's bank. 

bankAccountLocalName

String

No

Bank account holder name in the local language. 

beneficiaryTIN

String

No

Beneficiary's Taxpayer Identification Number.

Rule:

• {"checkRules": "^([0-9]{11})|([0-9]{14})$"}.

More information: 

• Maximum length: 64 characters.

beneficiaryDepositType

String

No

Type of beneficiary's bank deposit.

Rule:

• {"checkRules": "^[A-Z]{2}$"}.

More information:

• Maximum length: 64 characters.

bankCountryCode

String

No

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

Rule:

• {"checkRules": "^[A-Z]{2}$"}.

More information:

• Maximum length: 2 characters.

bankLocalName

String

No

Bank name in local language. 

Rule:

• {"checkRules": "^[A-Za-z0-9/() .,-?:'+*§©°¿ĢģĪīĶķĹŚśŪūΆΌΎΏΪЬьюя€\!-\'\;-\@\[-\`\{-\~\ -\£\À-\Ö\Ø-\ÿ\Ā-\ć\Ċ-\ē\Ė-\ğ\Į-\ij\ĺ-\ľ\Ł-\ň\Ő-\ř\Ş-\ť\Ů-\ų\Ÿ-\ž\Ș-\ț\Έ-\Ί\Α-\ώ\А-\Ъ\Ю-\ъ]{0,70}$"}.

More information:

• Maximum length: 128 characters.

beneficiaryState

String

No

The English name of the state/county/province where the beneficiary is located. 

Rule:

• {"checkRules": "^[A-Za-z0-9/() .,-?:'+]{0,35}$"}.

More information:

• Maximum length: 64 characters.

beneficiaryCity

String

No

The English name of the city/district/suburb/town/village where the beneficiary is located. 

Rule: 

• {"checkRules": "^[A-Za-z0-9/() .,-?:'+]{0,35}$"}.

More information: 

• Maximum length: 64 characters.

beneficiaryAddress

String

No

The beneficiary's detailed address in English. 

localBeneficiaryAddress

String

No

The beneficiary's detailed address in local language.

Rule:

• {"checkRules": "^[A-Za-z0-9/() .,-?:'+*§©°¿ĢģĪīĶķĹŚśŪūΆΌΎΏΪЬьюя€\!-\'\;-\@\[-\`\{-\~\ -\£\À-\Ö\Ø-\ÿ\Ā-\ć\Ċ-\ē\Ė-\ğ\Į-\ij\ĺ-\ľ\Ł-\ň\Ő-\ř\Ş-\ť\Ů-\ų\Ÿ-\ž\Ș-\ț\Έ-\Ί\Α-\ώ\А-\Ъ\Ю-\ъ]{0,105}$"}.

More information:

• Maximum length: 128 characters.

beneficiaryPostalCode

String

No

The beneficiary's postal code. 

Rule:

• {"checkRules": "^[A-Z0-9-( )]{0,16}$"}.

More information:

• Maximum length: 64 characters.

Field

Data type

Required

Description

buyerEnName

String

Yes (conditional)

Indicates the buyer's English name in goods trade.

More information about this field:

• Maximum length: 100 characters
• Required if tradeType = GOODS.

tradeCountry

String

Yes (conditional)

Indicates the trader's country/region code in 2 letters (ISO-3166).

For the safety of customers' funds, we do not support trade orders from the following countries:

• BY: Byelorussia
• RU: Russia

More information about this field:

• Maximum length: 2 characters
• Required if tradeType = GOODS.

deliverCountry

String

Yes (conditional)

Indicates the recipient's country/region code in 2 letters (ISO-3166).

For the safety of customers' funds, we do not support trade orders from the following countries:

• BY: Byelorussia
• RU: Russia

More information about this field:

• Maximum length: 2 characters
• Required if tradeType = GOODS.

contractList

Array <AttachmentInfo Object>

Yes (conditional)

At least one of them in goods trade:

PI, CI, contract

More information about this field:

• Required if the value of sceneCode is CREATE_B2B_ORDERS.

Field

Data type

Required

Description

referenceBuyerId

String

No (Conditional)

Indicates the unique ID that is assigned by the Partner to identify a buyer.

More information about this field:

• Maximum length: 64
• Specify at least one of the values of referenceBuyerId, buyerName, and buyerEmail.

buyerName

UserName object

No (Conditional)

Indicates the buyer name.

More information about this field:

• Specify at least one of the values of referenceBuyerId, buyerName, and buyerEmail.

buyerEmail

String

No (Conditional)

Indicates the buyer's email address.

More information about this field:

• Maximum length: 128
• Specify at least one of the values of referenceBuyerId, buyerName, and buyerEmail.

buyerPhoneNo

String

Optional

Indicates the buyer's phone number.

More information about this field:

• Maximum length:  24

Field

Data type

Required

Description

fieldName

String

Yes

Name of the field.

fieldDescription

String

Yes

Description of the field.

required

String

Yes

Indicates whether the rules must be followed.

Possible values are:

• Y: The field is required. The specific restrictions must be applied.
• N: The field is not required. If the field has value, apply the specific restrictions.

restriction

Restriction object

No

Restrictions that need to be applied to the field.

Field

Data type

Required

Description

certificateNo

String

No

Certification number of the Customer's company.

More information:

• Maximum length: 128 characters

certificateType

String

No

Type of the certification.

Possible values are:

• ENTERPRISE_REGISTRATION: The certification is business license.

Field

Data type

Required

Description

customerId

Only for B2C

String

No (Conditional)

Indicates the unique ID that is assigned by Worldfirst to identify a user. Specify this parameter if the value of the sceneCode parameter is PAY_INTO_CHINA and the value of the quotaAccumulationMethod parameter is USER_ID.

More information:

• Maximum length: 64 characters

referenceCustomerId

Only for B2C

String

No (Conditional)

Indicates the unique ID that is assigned by the Partner to identify a user. Specify this parameter if the value of the sceneCode parameter is PAY_INTO_CHINA and the value of the quotaAccumulationMethod parameter is BENEFICIARY.

More information:

• Maximum length: 64 characters

customerCompanyName

String

No

Indicates the registration name of the customer's company.

More information:

• Maximum length: 256 characters

certificateList

Array<Certificate Object>

No

List of Information about the customer's certifications.

Field

Data type

Required

Description

dealId

String

Yes

The unique ID assigned by WorldFirst to identify a forward deal.

More information:

• Maximum length: 64 characters

dealRequestId

String

Yes

The unique ID assigned by the Partner to identify a deal request.

More information:

• Maximum length: 64 characters

sell

Amount object

Yes

The amount to sell.

buy

Amount object

Yes

The amount to buy.

unSettledBuy

Amount object

No

The amount of unsettled amount that the Partner buys.

Note:

• This field might be returned when the Partner cancels this forward deal.

unSettledSell

Amount object

No

The amount of unsettled sell amount that the Partner sells.

Note:

• This field might be returned when the Partner cancels this forward deal.

quote

Quote object

Yes

Information with regard to the quote, such as the currency pair used, the expiry time of the quote, etc.

forwardType

String

Yes

The type of the forward quote.

Possible values are:

• FIXED: Indicates a fixed date.
• WINDOWED: indicates a windowed date.
• FLEXIBLE: Indicates a flexible date.

For the full list, refer to forwardType.

windowStartTime

DateTime object

Yes(Conditional)

Indicates the start time of the window.

Note:

• This field is required when forwardType is WINDOWED.

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

expiredTime

DateTime object

Yes

The expired time of the deal. Also known as the latest time to complete the exchange.

Note:

• For createDeal, the value of this field is the same as quote.quoteExpiryTime in the response message of the createQuote API.
• The value of this field follows the ISO 8601 standard format. For example, 2019-01-01T01:01:01+08:00, or 2019-01-01T01:01:01Z(UTC timezone).

margin

Amount object

Yes

The amount of the margin used in this forward deal.

creditLine

Amount object

Yes

The amount of the credit line used in this forward deal.

creditLineBase

Amount object

Yes

The amount of the base currency that the forward deal uses.

settledTime

DateTime object

No

The finishing time of all the related settlements of the forward deal.

Note:

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

cancelTime

DateTime object

No

The cancel time of the forward deal. Also known as the latest time to complete the exchange.

Note:

• This field might be returned when the Partner cancels this forward deal.
• The value of this field follows the ISO 8601 standard format. For example, 2019-01-01T01:01:01+08:00, or 2019-01-01T01:01:01Z(UTC timezone).

cancelCost

Amount object

No

The amount that costs the deal initiator from the cancellation request.

Note:

• This field might be returned when the Partner cancels this forward deal.

cancelGain

Amount object

No

The amount that the deal initiator gains from the cancellation request.

Note:

• This field might be returned when the Partner cancels this forward deal.

Field

Data type

Required

Description

declarationOrderReferenceNo

Only for B2B

String

Yes

Customs number or customs declaration.

More information about this field:

• Maximum length: 100 characters

supervisionMethod

Only for B2B

String

Yes

Indicates the supervision mode.

Valid values are:

• 9810: Export overseas warehouse of cross-border e-commerce for business to business
• 9710: Direct export of cross-border e-commerce for business to business
• 0110: General trade

customsDeclarationAttachmentList

Only for B2B

Array <AttachmentInfo Object>

Yes

Indicates the attachments of customs declaration.

Field

Data type

Required

Description

clientIp

String

Yes

Client ip address

More information:

• Maximum length: 64 characters

sessionId

String

No

Session id

More information:

• Maximum length: 64 characters

deviceTokenId

String

No

The token for query full device data of appId sdk

More information:

• Maximum length: 128 characters

terminalType

String

Yes

Terminal type, possible values are:

• WEB 
• WAP 
• APP 
  

language

String

Yes

Language of user interface the user is using

More information:

• Maximum length: 8 characters

clientUmid

String

No

DeviceId generated by alibaba group umid sdk

More information:

• Maximum length: 128 characters

umidTokenId

String

No

The token associated with umid reported data

More information:

• Maximum length: 64 characters

userAgent

String

No

User agent

More information:

• Maximum length: 1024 characters

cookieId

String

No

User cookie id

More information:

• Maximum length: 64 characters

osType

String

Yes (Conditional)

Type of the operation system

Note:

• Required when terminalType = APP 

More information:

• Maximum length: 32 characters

osVersion

String

Yes (conditional)

Version of the operation system

Note:

• Required when terminalType = APP

More information:

• Maximum length: 32 characters

deviceModel

String

No

Device model

More information:

• Maximum length: 32 characters

deviceVersion

String

No

Device version

More information:

• Maximum length: 32 characters

appVersion

String

No

App version

More information:

• Maximum length: 32 characters

browserVersion

String

Yes (conditional)

Browser version 

Note:

• Required when terminalType = WEB or WAP 

More information:

• Maximum length: 32 characters

browserType

String

Yes (conditional)

Browser type

Note:

• Required when terminalType = WEB or WAP

More information:

• Maximum length: 32 characters

browserTimeZone

String

Yes (conditional)

Browser time zone, the difference between the time zone of the device location and Greenwich Mean Time (GMT) in minutes

Note:

• Required when terminalType = WEB or WAP

Value of this field (GMT+08:00 as an example):

• The number of minutes returned by getTimezoneOffset in the web browser is -480, and its negation 480 is the value of this field; or 
• GMT +8, 8*60 calculates the number of minutes as 480 
  

More information:

• Maximum length: 32 characters

operateEntrance

String

No

The operate entrance to identify requests from merchants and requests from third-party mini-programs. For example, for LZD scenarios, the value of this field is GCash-Mini for GCash and TNG-Mini for TNG. 

More information:

• Maximum length: 64 characters

isPastedCard

Boolean

No

Whether the user copy-and-pasted the card information for the payment input

Field

Data type

Required

Description

dealId

String

Yes

The unique ID assigned by WorldFirst to identify a forward deal.

More information:

• Maximum length: 64 characters

actualSellAmount

Amount object

No

The actual sell amount of the forward exchange.

Note:

• This field is not required for the Partner. This field might be included in the response message.

actualBuyAmount

Amount object

No

The actual buy amount of the forward exchange.

Note:

• This field is not required for the Partner. This field might be included in the response message.

serviceFeeAmount

Amount object

No

The service fee for the settlement.

Note:

• This field is not required for the Partner. This field might be included in the response message.

Field

Data type

Required

Description

exchangeMemo

String

No

An additional memo that is provided by the Customer. This field is used for displaying user records.

referenceOrderId

String

No

A unique ID assigned by the Partner to identify the transfer order for the Customer(Merchant).

More information:

• Maximum length: 64 characters

Field

Data type

Required

Description

payerName

String

No (Conditional)

The name of the payer.

Note:

• Data are desensitized.
• This field is conditionally optional when the value of StatementList.transactionType is:

• • COLLECTION
  • COLLECTION_REFUND
  • TRANSFER
  • TRANSFER_REFUND
  • WITHDRAWAL
  • WITHDRAWAL_REFUND
  • CONVERSION
  • CONVERSION_DEAL
  • CHARGE
  • CHARGE_REFUND

More information:

• Maximum length: 128 characters

payerAccountNo

String

No (Conditional)

The account number of the payer.

Note:

• Data are desensitized.
• This field is conditionally optional when the value of StatementList.transactionType is:

• • COLLECTION
  • COLLECTION_REFUND
  • TRANSFER
  • TRANSFER_REFUND
  • WITHDRAWAL
  • WITHDRAWAL_REFUND
  • CONVERSION
  • CONVERSION_DEAL
  • CHARGE
  • CHARGE_REFUND

More information:

• Maximum length: 64 characters

payerAccountType

String

No (Conditional)

The type of the payer's account.

Note:

• This field is conditionally optional when the value of StatementList.transactionType is:

• • COLLECTION
  • COLLECTION_REFUND
  • TRANSFER
  • TRANSFER_REFUND
  • WITHDRAWAL
  • WITHDRAWAL_REFUND
  • CONVERSION
  • CONVERSION_DEAL
  • CHARGE
  • CHARGE_REFUND

Possible values are:

• WORLDFIRST
• BANK_CARD
• VIRTUAL_ACCOUNT
• ALIPAY_CN
• MINI_ACCOUNT
• INST_ACCOUNT
• INNER_ACCOUNT

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

beneficiaryName

String

No (Conditional)

The name of the beneficiary, who is the account holder of the beneficiary account.

Note:

• Data are desensitized.
• This field is conditionally optional when the value of StatementList.transactionType is:

• • COLLECTION
  • COLLECTION_REFUND
  • TRANSFER
  • TRANSFER_REFUND
  • WITHDRAWAL
  • WITHDRAWAL_REFUND
  • CONVERSION
  • CONVERSION_DEAL
  • CHARGE
  • CHARGE_REFUND

More information:

• Maximum length: 128 characters

beneficiaryAccountNo

String

No (Conditional)

The beneficiary's account number.

Note:

• Data are desensitized.
• This field is conditionally optional when the value of StatementList.transactionType is:

• • COLLECTION
  • COLLECTION_REFUND
  • TRANSFER
  • TRANSFER_REFUND
  • WITHDRAWAL
  • WITHDRAWAL_REFUND
  • CONVERSION
  • CONVERSION_DEAL
  • CHARGE
  • CHARGE_REFUND

More information:

• Maximum length: 64 characters

beneficiaryAccountType

String

No (Conditional)

The type of the beneficiary's account.

Note:

• Data are desensitized.

• This field is conditionally optional when the value of StatementList.transactionType is:

• • COLLECTION
  • COLLECTION_REFUND
  • TRANSFER
  • TRANSFER_REFUND
  • WITHDRAWAL
  • WITHDRAWAL_REFUND
  • CONVERSION
  • CONVERSION_DEAL
  • CHARGE
  • CHARGE_REFUND

Possible values are:

• WORLDFIRST
• BANK_CARD
• VIRTUAL_ACCOUNT
• ALIPAY_CN
• MINI_ACCOUNT
• INST_ACCOUNT
• INNER_ACCOUNT
• WorldFirst

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

beneficiaryBankCountry

String

No (Conditional)

The country where the beneficiary's bank account locates at.

Note:

• This field is conditionally optional when the value of StatementList.transactionType is:

• • COLLECTION
  • COLLECTION_REFUND
  • TRANSFER
  • TRANSFER_REFUND
  • WITHDRAWAL
  • WITHDRAWAL_REFUND
  • CONVERSION
  • CONVERSION_DEAL
  • CHARGE
  • CHARGE_REFUND

More information:

• Maximum length: 64 characters

beneficiaryBankName

String

No (Conditional)

The name of the bank that the beneficiary's bank account belongs to.

Note:

• This field is conditionally optional when the value of StatementList.transactionType is:

• • COLLECTION
  • COLLECTION_REFUND
  • TRANSFER
  • TRANSFER_REFUND
  • WITHDRAWAL
  • WITHDRAWAL_REFUND
  • CONVERSION
  • CONVERSION_DEAL
  • CHARGE
  • CHARGE_REFUND

More information:

• Maximum length: 256 characters

beneficiaryStoreName

String

No (Conditional)

The name of the store that the beneficiary owns.

Note:

• This field is conditionally optional when StatementList.transactionType is COLLECTION.

More information:

• Maximum length: 512 characters

beneficiaryMarketplaceName

String

No (Conditional)

The name that the Partner registers at the Marketplace.

Note:

• This field is conditionally optional when StatementList.transactionType is COLLECTION.

More information:

• Maximum length: 512 characters

remarks

String

No

Additional remarks for the transaction.

More information:

• Maximum length: 512 characters

description

String

No

Descriptions for the transaction.

More information:

• Maximum length: 512 characters

receiveAccount

String

No

Receiving Account number or Virtual Account number.

Note:

• This field is conditionally optional when the value of StatementList.transactionType is: COLLECTION.

More information:

• Maximum length: 128 characters

payerUserId

String

No (Conditional)

The unique ID assigned by WorldFirst to identify a payer.

Note: 

• This field is conditionally optional when the value of statementList.transactionType is VENDOR_COLLECTION_PAYMENT.

More information:

• Maximum length: 16 characters

paymentExplanation

String

No (Conditional)

Explanatory information provided by the payer on a payment. 

Note: 

• This field is conditionally optional when the value of statementList.transactionType is VENDOR_COLLECTION_PAYMENT. 

More information:

• Maximum length: 30 characters

paymentSubject

String

No (Conditional)

Payer's username at the service provider's platform. 

Note:

• This field is conditionally optional when the value of statementList.transactionType is VENDOR_COLLECTION_PAYMENT. 

More information:

• Maximum length: 70 characters

paymentVoucherNo

String

No (Conditional)

Payment voucher, namely, a payment reference number issued by service provider and later filled out by payer.

Note:

• This field is conditionally optional when the value of statementList.transactionType is VENDOR_COLLECTION_PAYMENT. 

More information:

• Maximum length: 100 characters

Field

Data type

Required

Description

goodsName

String

Yes

Indicates the goods name.

More information about this field:

• Maximum length: 256 characters

goodsCategory

Only for B2C

String

No (Conditional)

Indicates the goods category. Specify this parameter if the value of the sceneCode parameter is PAY_INTO_CHINA.

More information about this field:

• Maximum length: 256 characters

goodsQuantity

String

Yes

Indicates the number of goods. 

goodsUnit

Only for B2B

String

No (Conditional)

Indicates the unit of measurement for goods. This parameter is required when sceneCode is CREATE_B2B_ORDERS.

goodsCnName

Only for B2B

String

No (Conditional)

Indicates the Chinese names of the goods. This parameter is required when sceneCode is CREATE_B2B_ORDERS.

storeUrl

Only for B2B

String

No (Conditional)

Indicates the store URL. This parameter is required when sceneCode is CREATE_B2B_ORDERS.

Field

Data type

Required

Description

sellCurrency

String

Yes

3 character ISO-4217 currency code of the currency that the Partner intends to convert from.

More information:

• Maximum length: 3 characters

buyCurrency

String

Yes

3 character ISO-4217 currency code of the currency that the Partner intends to convert to.

More information:

• Maximum length: 3 characters

Field

Data type

Required

Description

providerKey

String

Yes (conditional)

Logistics company code

Reference: ProviderKey

More information about this field:

• Required if isUsedForExchange = Y, isShipped = Y and isDeclared = N.
• Maximum length: 8 characters

providerValue

String

Yes (conditional)

Logistics company name

More information about this field:

• Required if isUsedForExchange = Y, isShipped = Y and isDeclared = N.
• Maximum length: 128 characters

Field

Data type

Required

Description

Store

Store Object

Yes

Indicates the store information.

merchantId

String

No

Indicates the unique ID that is assigned by the Worldfirst to identify a merchant.

Field

Data type

Required

Description

operatorName

String

No

Name of the operator.

operatorEmail

String

No

Email of the operator. 

Field

Data type

Required

Description

paymentMethodType

String

Yes

Type of the payment method.

Valid values are:

• BENEFICIARY_TOKEN: use a beneficiary token as the payment method (an encrypted string containing information about the beneficiary's bank account)
• BANK_ACCOUNT_DETAIL: use a bank account as the payment method
• ALIPAY_CN_DETAIL: use an Alipay account as the payment method.
• REFERENCE_ALIPAY_CN: use a binding AlipayWallet as the payment method.

paymentMethodId

String

Yes(Conditional)

The unique ID of the payment method utilized.

This field is required when:

• paymentMethodType is BENEFICIARY_TOKEN. Then this field takes on the value of beneficiaryToken after calling the bindBeneficiary interface.
• paymentMethodType is REFERENCE_ALIPAY_CN. Then this field takes on the value of referecenCustomerId.

More information about this field:

• Maximum length: 128 characters

paymentMethodMetaData

PaymentMethodDetail Object

Yes(Conditional)

A JSON object that describes the payment details.

This field is required when:

• paymentMethodType is BANK_ACCOUNT_DETAIL. In this case, set this field value to be BankAccountPaymentMethodDetail object.
• paymentMethodType is ALIPAY_CN_DETAIL. In this case, set this field value to be AlipayAccountPaymentMethodDetail object.

More Information:

• Maximum length: 2048 characters

Field

Data type

Required

Description

paymentMethodType

String

Yes

Type of the payment method.

Valid values are:

• BALANCE: use account balance as the payment method. 
• WORLDFIRST_RECEIVE_ACCOUNT: use a WorldFirst Receiving Account as the payment method.

paymentMethodId

String

Yes(Conditional)

The unique ID of the payment method utilized.

Note:

• This field is required when paymentMethodType is WORLDFIRST_RECEIVE_ACCOUNT. The value of this field is the Receiving Account number which is accessible from the Partner's portal.

More information about this field:

• Maximum length: 128 characters

customerId

String

Yes(Conditional)

The unique ID assigned by WorldFirst to identify a Customer.

Note:

• This field is required when paymentMethodType is BALANCE.

• Specify this field to increase transfer success rate by increasing the accuracy of anti-money laundering and fraud detection.

More information about this field:

• Maximum length: 64 characters

Field

Data type

Required

Description

quoteId

String

No

The unique ID assigned by WorldFirst for every quote as the identifier.

More information:

• Maximum length: 64 characters

quoteCurrencyPair

String

Yes

Two 3-character ISO 4217 currency codes identifying the currency pair for the quote.

More information:

• Maximum length: 16 characters

quotePrice

Decimal

Yes

The quote price.

More information:

• Maximum length: 20 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, or 2019-01-01T01:01:01Z(UTC timezone).

quoteExpiryTime

DateTime object

No

The time that the quote expires.

Note:

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

guaranteed

Boolean

No

Indicates whether the exchange rate of the quote is guaranteed.

Valid values are:

• true: Quote is guaranteed.
• false: Quote is not guaranteed.

Field

Data type

Required

Description

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.

More information:

• Maximum length: 20 characters

transferFromCurrency

String

Yes

3-character ISO-4217 currency code that represents the base currency of the transfer. For example, USD.

More information:

• Maximum length: 3 characters

transferToCurrency

String

Yes

3-character ISO-4217 currency code that represents the exchange currency of the transfer. For example, USD.

More information:

• Maximum length: 3 characters

Field

Data type

Required

Description

currency

String

Yes

3-character ISO 4217 currency code that represents the currency used. For example, USD.

More information:

• Maximum length: 3 characters

value

Integer

Yes(Conditional)

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 the currency is USD, or ￥100 when the currency is JPY.

Note:

• This field is optional in the request messages of the createQuote API.
• This field is conditional in the request messages of the createExchange API.
• This field is required in the response messages for the createQuote, createExchange, inquiryExchange API.

More information:

• Maximum length: 16 characters

Field

Data type

Required

Description

settlementTimeType

String

No (Conditional)

The type of the exchange settlement time.

Specify this parameter if the value of the exchangeTradeType parameter is FORWARD.

Valid values are:

• FIXED: indicates a fixed date.
• WINDOWED: indicates a windowed date.
• FLEXIBLE: indicates a flexible date.

windowStartTime

Datetime object

Yes(Conditional)

Indicates the start time of the window.

Note:

• This field is required when forwardType is WINDOWED.
• The value of this field follows the ISO 8601 standard format. For example, 2019-01-01T01:01:01+08:00, or 2019-01-01T01:01:01Z(UTC timezone).

expiredTime

Datetime object

Yes

The expired time of the deal. Also known as the latest time to complete the exchange.

Note:

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

marginCurrency

String

No (Conditional)

3-character ISO 4217 currency code that represents the currency of:

• The margin fee.
• The cancel cost.

For example, USD.

Specify this parameter if the value of the exchangeTradeType parameter is FORWARD.

More information:

• Maximum length: 3 characters

quoteMarginAmount

Amount object

No

The amount of the margin with regard to a quote.

Note:

• This field is not required for the Partner. WorldFirst responds this field to the Partner.

quoteCreditLineAmount

Amount object

No

The amount of the credit line with regard to a quote.

Note:

• This field is not required for the Partner. WorldFirst responds this field to the Partner.

quoteCreditLineBaseAmount

Amount object

No

The base amount information of the credit line with regard to a quote.

Note:

• This field is not required for the Partner. WorldFirst responds this field to the Partner.

Field

Data type

Required

Description

sellCurrency

String

Yes

3 character ISO-4217 currency code of the currency that the Partner intends to convert from.

More information:

• Maximum length: 3 characters

buyCurrency

String

Yes

3 character ISO-4217 currency code of the currency that the Partner intends to convert to.

More information:

• Maximum length: 3 characters

rate

Decimal

Yes

The price represents how much of buyCurrency you get from selling 1 unit of the sellCurrency.

• For example, if rate is 6.7, the buyCurrencyis CNY, and the sellCurrency is USD, you get 6.7 CNY for selling 1 USD.

More information:

• Maximum length: 20 characters

Field

Data type

Required

Description

restrictionType

String

Yes

Defines the type of restriction.

Possible values are:

• PATTERN_RESTRICTION: The type of restriction is a regular expression (regEx).
• OPTIONS_RESTRICTION: The type of restriction is a list.

restrictionRegex

String

No

Specific rules that describe the restriction.

Note:

• This field is required when restrictionType is PATTERN_RESTRICTION

restrictionMsg

String

No

Additional messages that describe the restriction.

restrictionOptions

List <RestrictionOption object>

No

A list that defines the specific options of the restriction.

• This field is required when restrictionType is OPTIONS_RESTRICTION

Field

Data type

Required

Description

optionName

String

Yes

The name of the option.

optionValue

String

Yes

The value of the option.

Field

Data type

Required

Description

resultCode

String

Yes

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

• Maximum length: 64 characters

resultMessage

String

No

The result message that explains result codes in detail.

• Maximum length: 256 characters

resultStatus

String

Yes

The result status. Valid values are:

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

Field

Data type

Required

Description

isShipped

Only for B2B

String

No (Conditional)

Indicates the shipping status. Specify this parameter if the following requirements are met:

• the value of sceneCode is CREATE_B2B_ORDERS
• the value of tradeOrder.isUsedForExchange is Y

Valid values are:

• Y: Shipped
• N: Not shipped

isDeclared

Only for B2B

String

No (Conditional)

Indicates if there is a customs declaration. Specify this parameter if the following requirements are met:

• the value of sceneCode is CREATE_B2B_ORDERS
• the value of tradeOrder.isUsedForExchange is Y
• the value of shipping.isShipped is Y

Valid values are:

• Y: There is a customs declaration.
• N: There is Not customs declaration.

isNewBuyer

Only for B2B

String

No (Conditional)

Indicates new buyer or repeat buyer. Specify this parameter if the following requirements are met:

• the value of sceneCode is CREATE_B2B_ORDERS
• the value of tradeOrder.isUsedForExchange is Y
• the value of shipping.isShipped is N

Valid values are:

• Y: New buyer
• N: Repeat buyer

wayBillInfos

Array <WayBillInfo Object>

No (Conditional)

Indicates the invoice details. Specify this parameter if either of the following requirements is met:

• the value of sceneCode is CREATE_B2B_ORDERS, the value of tradeOrder.isUsedForExchange is Y, the value of shipping.isShipped is Y, and the value of shipping.isDeclared is N .
• the value of sceneCode is PAY_INTO_CHINA.

declarationInfos

Only for B2B

Array <DeclarationInfo Object>

No (Conditional)

Indicates the customs declaration details. Specify this parameter if the following requirements are met:

• the value of sceneCode is CREATE_B2B_ORDERS
• the value of tradeOrder.isUsedForExchange is Y
• the value of shipping.isShipped is  Y
• the value of shipping.isDeclared is  Y

expectedShippingDate

Only for B2B

String

No (Conditional)

Indicates the expected shipping date. Specify this parameter if the following requirements are met:

• the value of sceneCode is CREATE_B2B_ORDERS
• the value of tradeOrder.isUsedForExchange is  Y
• the value of shipping.isShipped is  N

Format: 13-digit time stamp

Example: 1659430628390

inquiryChatRecordAttachmentList

Only for B2B

Array <AttachmentInfo Object>

No (Conditional)

Inquire about the communication record of the trade order. Specify this parameter if the following requirements are met:

• the value of sceneCode is CREATE_B2B_ORDERS
• the value of tradeOrder.isUsedForExchange is  Y
• the value of shipping.isShipped is  N
• the value of shipping.isNewBuyer is Y

logisticsChatRecordAttachmentList

Only for B2B

Array <AttachmentInfo Object>

No (Conditional)

Indicates the communication logs/record of logistics. Specify this parameter if the following requirements are met:

• the value of sceneCode is CREATE_B2B_ORDERS
• the value of tradeOrder.isUsedForExchange is  Y
• the value of shipping.isShipped is  N
• the value of shipping.isNewBuyer is Y

tradeTerms

Only for B2B

String

No (Conditional)

Indicates the trading mode.  Specify this parameter if the value of sceneCode is CREATE_B2B_ORDERS .

Value reference: TradeTerms

Field

Data type

Required

Description

transactionTime

DateTime object

Yes

The time that the payment order is created by the Partner.

Note:

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

balanceTypes

Array<String>

Conditional

This field represents the various balance types. Valid values for this field vary from different clients as follows:

• For the only CN HK EC (E-commerce) clients from the point of risk control, valid values are:

• NORMAL_BALANCE: manages the balance of funds that come from the e-commerce platform.
• SAME_NAME_TOP_UP_BALANCE: manages the balance of funds that top-up by CN HK EC clients themselves.

• For other clients, this field value is NORMAL_BALANCE, which manages normal balance of funds.

transactionType

String

Yes

Indicates the type of transaction that this API requests.

Possible values include:

• TRANSFER
• WITHDRAWAL
• CONVERSION
• CHARGE
• COLLECTION

For the full list, refer to the transactionType.

transactionAmount

Amount object

Yes

Defines the amount of the transaction.

Note:

• The value of this field can be either positive or negative.

• • For inflow funds, the value of this field is positive.
  • For outflow funds, the value of this field is negative.

feeAmount

Amount object

No (Conditional)

The amount of the fee.

Note:

• This field is conditionally optional when the value of transactionType is:

• • TRANSFER
  • TRANSFER_REFUND
  • WITHDRAWAL
  • WITHDRAWAL_REFUND
  • CONVERSION
  • CONVERSION_DEAL
  • CHARGE
  • CHARGE_REFUND

originalTransactionAmount

Amount object

Yes

Defines the transaction amount originally submitted.

netAmount

Amount object

No (Conditional)

The net amount received after deducting the fees handled by WorldFirst during transaction.

Formula:

Net amount=total amount-fees.

Note: 

This field is required when transactionType is:

• TRANSFER
• CHARGE
• PAYMENT
• CASH_BACK

receiveAmount

Amount object

No (Conditional)

The final amount received after currency conversion. 

Formula:

Received amount=net amount*exchange rate applied during transaction.

Note: 

This field is required when transactionType is:

• TRANSFER
• CHARGE
• PAYMENT
• CASH_BACK

accountBalance

Amount object

Yes

Indicates the account balance in real-time after the transaction.

transactionId

String

No (Conditional)

The unique ID assigned by WorldFirst to identify a transaction.

Note:

• This field is required when the value of StatementList. transactionType is:

• • COLLECTION
  • COLLECTION_REFUND
  • TRANSFER
  • TRANSFER_REFUND
  • WITHDRAWAL
  • WITHDRAWAL_REFUND
  • CONVERSION
  • CONVERSION_DEAL
  • CHARGE
  • CHARGE_REFUND

More information:

• Maximum length: 64 characters

extTransactionId

String

No

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

More information:

• Maximum length: 256 characters

transactionStatus

String

Yes

The status for transactions.

Possible values are:

• INIT: The order has been initiated.
• PROCESSING: The order is being processed.
• PENDING: The order is pending.
• SUCCESS: The order has been processed successfully.
• FAIL: The order processing failed.

foreignExchangeQuote

Quote object

No (Conditional)

Information about quotes for transfer.

Note:

• This field is optional when the value of transactionType is:

• • TRANSFER
  • WITHDRAWAL
  • CONVERSION
  • CONVERSION_DEAL
  • CHARGE

refundForeignExchangeQuote

Quote object

No (Conditional)

Information about quotes for transfer refunds.

Note:

• This field is optional when the value of transactionType is:

• • TRANSFER_REFUND
  • WITHDRAWAL_REFUND
  • CHARGE_REFUND

fundMoveDetail

FundMoveDetail object

Yes

Defines the details about the fund move.

operatorInfo

OperatorInfo object

No(Conditional)

For payment, withdraw and convert orders submitted on the WF portal, WorldFirst returns this field in the corresponding statement. 

Field

Data type

Required

Description

storeShopUrl

String

Yes

Indicates the store's URL.

More information about this field:

• Maximum length: 64 characters

Field

Data type

Required

Description

referenceOrderNo

String

Yes

Indicates the trade order number.

More information about this field:

• Maximum length: 64 characters
• When sceneCode is CREATE_B2B_ORDERS, follow the rules below: 

• Keep the length to more than 3, but less than or equal to 64 characters.
• Avoid four consecutive repeated characters, for example, 1111, AAAA.

orderTime

Only for B2C

DateTime Object

No (Conditional)

Indicates the trading time. Specify this parameter if the value of the sceneCode parameter is PAY_INTO_CHINA.

paymentTime

DateTime Object

Yes

Indicates the payment time.

transAmount

Amount Object

Yes

Indicates the transfer amount.

The definition of this parameter varies based on the value of the sceneCode parameter:

• When sceneCode is CREATE_B2B_ORDERS, this parameter indicates the amount to be associated with the fund order.
• When sceneCode is  PAY_INTO_CHINA, this parameter indicates the amount paid by the buyer.

tradeAmount

Amount Object

Yes

Indicates the trade amount.

The definition of this parameter varies based on the value of the sceneCode parameter:

• When sceneCode is CREATE_B2B_ORDERS, this parameter indicates the total amount of this batch order.
• When sceneCode is  PAY_INTO_CHINA, this parameter indicates the amount received by the seller.

tradeType

String

Yes

Indicates the type of trade.

Values:

• GOODS: goods trade
• SERVICE: service trade

orderType

Only for B2C

String

No (Conditional)

Indicates the order type. Specify this parameter if the value of the sceneCode parameter is PAY_INTO_CHINA.

Valid values are:

• LOAN: indicates the trade is a payment.
• REFUND: indicates the trade is a refund.

merchant

Only for B2C

Merchant Object

No (Conditional)

Indicates the merchant information. Specify this parameter if the value of the sceneCode parameter is PAY_INTO_CHINA.

seller

Only for B2C

Customer Object

No (Conditional)

Indicates the seller information. Specify this parameter if the value of the sceneCode parameter is PAY_INTO_CHINA .

buyer

Only for B2C

Buyer Object

No (Conditional)

Indicates the buyer information. Specify this parameter if the value of the sceneCode parameter is PAY_INTO_CHINA .

goods

Array <Goods Object>

No (Conditional)

Indicates the goods details. Specify this parameter if the value of the tradeType parameter is GOODS.

shipping

Shipping Object

No (Conditional)

Indicates the shipping details. Specify this parameter if the value of the tradeType parameter is GOODS.

isUsedForExchange

Only for B2B

String

No (Conditional)

Indicates whether the order is used for foreign exchange. Specify this parameter if the value of the sceneCode parameter is CREATE_B2B_ORDERS.

Valid values:

• Y: for exchange
• N: not for exchange

bizContractInfo

Only for B2B

BizContractInfo Object

No (Conditional)

Indicates the contract details. Specify this parameter if the value of the sceneCode parameter is CREATE_B2B_ORDERS.

otherAttachmentList

Array <AttachmentInfo Object>

No

Indicates the additional attachments.

attachmentDesc

String

No

Indicates the additional comments on the attachment.

More information: 

• Maximum length: 200 characters.

market

String

No

The service market or region. Valid values are:

• CHN: indicates China.
• USA: indicates the USA.

revenueShare

String

No

The revenue share.

logisticsMode

Only for B2B

String

No (Conditional)

The logistics mode.

Valid values are:

• DROPSHIPPING: indicates dropshipping.
• REGULAR_MODE: indicates all standard logistics models excluding dropshipping.

Note: 

• This parameter is required when tradeType is GOODS. 

Field

Data type

Required

Description

referenceOrderNo

String

Yes

Indicates the trade order number.

More information about this field:

• Maximum length: 64 characters

orderStatus

String

Yes

Indicates the trade order status. Valid values are:

• REJECT: indicates the trade order is rejected for foreign exchange settlement.
• AVAILABLE: indicates the trade order is available for foreign exchange settlement.
• ACCEPTED: indicates the trade order is accepted for foreign exchange settlement.
• PARTIAL_DECLARED: indicates the trade order is partially declared for foreign exchange settlement.
• DECLARED: indicates the trade order is declared for foreign exchange settlement.

statusMessage

String

Yes

Indicates the trade order status details.

transAmount

Amount Object

No

Indicates the transaction amount.

tradeAmount

Amount Object

No

Indicates the trade amount.

remainAmount

Amount Object

No

Indicates the remaining amount available for foreign exchange settlement.

errorCode

String

No

Indicates the error code.

errorMessage

String

No

Indicates the error message.

Field

Data type

Required

Description

referenceBeneficiaryId

String

No

The unique ID assigned by the partner to identify the beneficiary.

More information:

• Maximum length: 64 characters

beneficiaryName

UserName Object

No

The name of the beneficiary.

beneficiaryCountry

String

No

3-letter ISO 3166-1 code that represents the country where the beneficiary locates at.

More information:

• Maximum length: 3 characters

beneficiaryAddress

Address Object

No

The address of the beneficiary.

beneficiaryMobileNo

String

No

The contact phone number of the beneficiary.

More information:

• Maximum length: 24 characters

beneficiaryEmail

Email

No

The email address of the beneficiary.

Note:

• The value of this field should be a valid email address.

beneficiaryRegistrationTime

DateTime object

No

The registration time of the beneficiary.

Note:

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

beneficiaryLastLoginTime

DateTime object

No

The last login time of the beneficiary.

Note:

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