Data dictionary

Model

AccountBalance

Field

Data type

Required

Description

accountNo

String

Yes

The unique ID assigned by WorldFirst to identify an account.

More information:

  • Maximum length: 32 characters

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.

currency

String

Yes

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

More information:

  • Maximum length: 3 characters

availableBalance

Amount object

Yes

Balance that is available.

frozenBalance

Amount object

Yes

Balance that is frozen.

totalBalance

Amount object

Yes

Balance in total.

AccountInfo

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

Address

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

Address for TransferPayer

Field

Data type

Required

Description

address1

String

No

Information about the address.

More information:

  • Maximum length: 256 characters

AlipayAccountPaymentMethodDetail

Field

Data type

Required

Description

beneficiaryType

String

Yes

The type of the beneficiary, which could be a corporate or an individual Alipay account that receives funds from the payout.

Valid values for beneficiaryType are:

  • THIRD_PARTY_ALIPAY_COMPANY_ACCOUNT:  Indicates that the beneficiary is a third-party company's Alipay account.
  • THIRD_PARTY_ALIPAY_PERSONAL_ACCOUNT: Indicates that the beneficiary is a third-party personal Alipay account. 

alipayAccountName

String

Yes

The name of the Alipay account.

More information about this field:

  • Maximum length: 256 characters

alipayAccountLogonId

String

Yes

The account ID that logs onto Alipay, which is an email address or phone number.

Note:

It should be either a legit email address with no more than 64 characters or an 11-character phone number.

Amount

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.

AttachmentInfo

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

BankAccount

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

BankAccount for inquiryAccount

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

BankAccountPaymentMethodDetail

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.

Beneficiary

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

BeneficiaryBankAccount

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.

BizContractInfo

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.

Buyer

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

CardTemplateField

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.

Certificate

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.

Customer

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.

Deal

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.

DeclarationInfo

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.

Env

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

ExchangeForwardInfo

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.

ExchangeQuoteAddition

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

FundMoveDetail

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

Goods

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.

InquiryRateCondition

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

LogisticsCompany

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

Merchant

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.

OperatorInfo

Field

Data type

Required

Description

operatorName

String

No

Name of the operator.

operatorEmail

String

No

Email of the operator. 

PaymentMethod (for Payout)

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_DETAILuse 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:

More Information:

  • Maximum length: 2048 characters

PaymentMethod (for Transfer)

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

Quote

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.

Quote for inquiryStatementList

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

QuoteAmount

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

QuoteForwardInfo

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.

ReferenceRate

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

Restriction

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

RestrictionOption

Field

Data type

Required

Description

optionName

String

Yes

The name of the option.

optionValue

String

Yes

The value of the option.

Result

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

Shipping

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

Statement

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. 

Store

Field

Data type

Required

Description

storeShopUrl

String

Yes

Indicates the store's URL.

More information about this field:

  • Maximum length: 64 characters

TradeOrder

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

TradeOrderResult Only for B2C

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.

TransferBeneficiary

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).

extendInfo

String

No

Extended information about the beneficiary.

More information:

  • Maximum length: 2048 characters

TransferFromAddition

Field

Data type

Required

Description

transferPayer

TransferPayer object

Yes

Information about the payer.

TransferFromDetail

Field

Data type

Required

Description

transferFromMethod

PaymentMethod object for Payout

PaymentMethod object for Transfer

No

The payment method that the Payer utilizes.

transferFromAmount

Amount object

Yes

The amount of the transfer that the payer needs to pay (before fee collection). If the value of this parameter is set as null, the value of the transferToDetail.transferToAmount parameter in the reponse is also set as null.

transferFromCurrency

String

No

The currency the payer users (3-character ISO 4217 currency code).

This field and the amount cannot be specified at the same time. 

transferLimitInfo

(For responses only)

TransferLimitInfo object

No (Conditional)

The limit information about the transfer amount. Specify this parameter if the value of the transferToDetail.transferToAmount.currency parameter is CNY.

actualTranferFromAmount

(For responses only)

Amount object

No

The actual amount for the transfer (after fee collection). This field is only included in responses. 

feeAmount

(For responses only)

Amount object

No

The fee amount paid by the payer. This field is only included in responses. 

transferQuote

Quote object

No

Quote information for the transfer. 

TransferOrderAddition

Field

Data type

Required

Description

referenceOrderId

String

No

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

Note:

  • This field is used for user consumption records display and further payment operations such as customer complaints and disputes track.

More information:

  • Maximum length: 64 characters

disPlayTitle

String

No

Use this field to display an overview of transaction details in the Alipay CN account that receives the payout.

env

Env object

No

The environment used for the transfer. 

transferFromAddition

TransferFromAddition object

No

Additional transfer information about the payer.

transferToAddition

TransferToAddition object

No

Additional transfer information about the beneficiary.

extendInfo

String

No

Extended information. 

More information:

  • Maximum length: 2048 characters

TransferLimitInfo (for Payout)

Field

Data type

Required

Description

currentTransferAmountLimitMin

Amount object

Yes

The minimum amount limit of the current payout.

currentTransferAmountLimitMax

Amount object

Yes

The maxmium limit of the payout amount.

TransferPayer

Field

Data type

Required

Description

referencePayerId

String

No

The unique ID assigned by the Partner to identify the payer.

More information:

  • Maximum length: 64 characters

payerName

UserName object

No

The name of the payer.

payerCountry

String

No

2-letter ISO 3166 code that represents the country where the payer locates at.

payerAddress

Address object

No

The address of the payer.

payerMobileNo

String

No

Mobile phone number of the payer 

More information:

  • Maximum length: 24 characters

payerEmail

Email

No

Email address of the payer

payerRegistrationTime

DateTime object

No

Registration time of the payer

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).

payerLastLoginTime

DateTime object

No

Last login time of the payer

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).

extendInfo

String

No

Extended information of the payer

TransferResult

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

resultMessage

String

No

Result message that explains result codes in detail.

More information:

  • Maximum length: 256 characters

resultStatus

String

Yes

Result status. Valid values are:

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

TransferToAddition

Field

Data type

Required

Description

transferToRequestId

String

No

The unique ID to identify the transfer request. 

More information:

  • Maximum length: 64 characters

transferBeneficiary

TransferBeneficiary object

Yes

Information with regard to the beneficiary.

TransferToDetail (for Transfer)

Field

Data type

Required

Description

transferToRequestId

String

Yes

The unique ID to identify the transfer request. 

transferToMethod

PaymentMethod object (for Transfer)

Yes

The method that the beneficiary uses to receive the transfer.

transferToAmount

Amount object

Yes

The amount of the transfer that the beneficiary collects in a specific currency (before fee collection).

Note:

  • For the createTransfer API, only transferToAmount.currency is required. transferToAmount.value is not required.

transferToCurrency

String

No

3-character ISO-4217 currency codes

representing the currency that the beneficiary collects. 

This field and transferToAmount cannot be specified at the same time. 

actualTransferToAmount

(For responses only)

Amount object

No

The amount of the transfer that the beneficiary collects (after fee collection). This field might be included in the response message.

feeAmount

Amount object

No

Service fee for the transfer. If specified in the request, the service fee will be collected as specified. 

transferQuote

Quote object

No

Indicates the foreign exchange quote information.

transferNotifyUrl

String (URL)

No

If the partner specifies this field, WorldFirst will send the transfer result notification to this URL. 

transferToId

(For responses only)

String

No

The unique identifier returned by AAC. 

This field might be included in the response message and can be used for inquiries. 

More information:

  • Maximum length: 64 characters

transferToResult

Result object

No

The transfer processing result by AAC, including information on the business status and error message. This field is returned for batched transfers only. 

transferToFinishTime

DateTime object

No

The finish time for the transfer. This field is only included in responses. 

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).

transferRemark

String

No

Information provided for bank settlements. 

More information:

  • Maximum length: 1024 characters

transferMemo

String

No

The memo that the transfer initiator leaves.

More information:

  • Maximum length: 256 characters

extendInfo

String

No

Additional information for the transfer. 

More information:

  • Maximum length: 2048 characters

transferToReturnAmount

(For responses only)

Amount object

No

For refunds, this field indicates the amount of the refund. This field is only used for notifications. 

transferToReturnTime

(For responses only)

DateTime object

No

For refunds, this field indicates the time of the refund. This field is only used for notifications. 

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).

purposeCode

String

Yes

Defines the purpose of the transfer.

Possible values are:

  • GDS: Goods bought or sold.

For the full list, refer to purposeCode.

TransferToDetail (for payout)

Field

Data type

Required

Description

transferToRequestId

String

Yes

The unique ID to identify the payout request. 

transferToMethod

PaymentMethod object (for Payout)

Yes

The method that the beneficiary uses to receive the payout.

transferToAmount

Amount object

Yes

The amount of the payout that the beneficiary collects (before fee collection).

Note:

  • For the createPayout API, only transferToAmount.currency is required. transferToAmount.value is not required.
  • If the value of the transferFromDetail.transferToAmount parameter in the request is set as null, the value of this parameter is also set as null.

transferToCurrency

String

No

3-character ISO-4217 currency codes

representing the currency that the beneficiary collects. 

This field and transferToAmount cannot be specified at the same time. 

actualTransferToAmount

(For responses only)

Amount object

No

The amount of the payout that the beneficiary collects (after fee collection). This field might be included in the response message.

feeAmount

Amount object

No

Service fee for the payout. If specified in the request, the service fee will be collected as specified. 

transferQuote

Quote object

No

Indicates the foreign exchange quote information.

transferNotifyUrl

String (URL)

No

If the partner specifies this field, WorldFirst will send the payout result notification to this URL. 

transferToId

(For responses only)

String

No

The unique identifier returned by AAC. 

This field might be included in the response message and can be used for inquiries. 

More information:

  • Maximum length: 64 characters

transferToResult

Result object

No

The payout processing result by AAC, including information on the business status and error message. This field is returned for batched payouts only. 

transferToFinishTime

DateTime object

No

The finish time for the payout. This field is only included in responses. 

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).

transferRemark

String

No

Information provided for bank settlements. 

More information:

  • Maximum length: 1024 characters

transferMemo

String

No

The memo that the payout initiator leaves.

More information:

  • Maximum length: 256 characters

extendInfo

String

No

Additional information for the payout

More information:

  • Maximum length: 2048 characters

transferToReturnAmount

(For responses only)

Amount object

No

For refunds, this field indicates the amount of the refund. This field is only used for notifications. 

transferToReturnTime

(For responses only)

DateTime object

No

For refunds, this field indicates the time of the refund. This field is only used for notifications. 

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).

purposeCode

String

Yes

Defines the purpose of the payout.

Possible values are:

  • GDS: Goods bought or sold.

For the full list, refer to purposeCode.

 isFVT

String

No

Indicates whether a Full Value Transfer (FVT) is intended to ensure the beneficiary collects the full amount. 

Possible values are:

  • Y: using FVT
  • N: not using FVT

arrivalType

String

No

The preference of using the Full Value Transfer (FVT) in a payout. Valid values are:

  • NEED_FVT: indicates that the FVT is required in a payout.
  • PREFER_FVT: indicates that the FVY is not required but preferred in a payout.

Note: The capability of FVT can be implemented only for partners in the white list. If you need to implement this capability, contact your BD or SA in advance.

fvtPayment

(For responses only)

String

No

Indicates whether the payout uses the FVT capability. Valid values are:

  • trueindicates that the payout uses the FVT capability.
  • falseindicates that the payout does not use the FVT capability.

Note: This parameter is returned by Worldfirst only if you have the capability of FVT. The capability of FVT can be implemented only for partners in the white list. If you need to implement this capability, contact your BD or SA in advance.

UserName

Field

Data type

Required

Description

firstName

String

No

The first name of the user.

More information:

  • Maximum length: 32 characters

middleName

String

No

The middle name of the user.

More information:

  • Maximum length: 32 characters

lastName

String

No

The last name of the user.

More information:

  • Maximum length: 32 characters

fullName

String

Yes

The full name of the user.

More information:

  • Maximum length: 96 characters

UserName for TransferPayer

Field

Data type

Required

Description

fullName

String

No

The full name of the user.

More information:

  • Maximum length: 128 characters

WayBillInfo

Field

Data type

Required

Description

shippingOrderReferenceNo

String

No (Conditional)

Indicates the outbound logistics order number. 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.

shippingAddress

Only for B2C

Address Object

No (Conditional)

Indicates the shipping address. Specify this parameter if the value of sceneCode is PAY_INTO_CHINA.

shippingMethod

Only for B2B

String

No (Conditional)

Indicates the shipping method. 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 N 

Valid Values are:

  • RAILWAY
  • LAND_TRANSPORTATION
  • BY_SEA
  • AIR_CARGO
  • EXPRESS
  • SPECIAL_LINE_TRANSPORTATION
  • OTHER

shippingProofAttachmentList

Only for B2B

Array <AttachmentInfo Object>

No (Conditional)

Indicates the attachments of the shipping voucher.  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 N

logisticsCompany

Only for B2B

LogisticsCompany Object

No (Conditional)

Indicates the logistics company.  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 N

Invoice

Field

Data type

Required

Description

invoiceType

String

Yes

The invoice type. Valid values are:

  • BILL: indicates the invoice is a bill.
  • ORDER: indicates the invoice is an order.

More information about this field:

  • Maximum length: 8 characters

bill

Bill

Conditional

The bill information, such as the bill type, the bill number, and the bill amount. Specify this parameter if the value of the invoiceType parameter is BILL.

Bill

Field

Data type

Required

Description

billType

String

Yes

The bill type. Valid values are:

  • VATMASTER_PAY_VAT
  • AMAZON_TRANSPARENCY_FEE
  • EPR_FEE
  • ADS_FEE
  • LOGISTICS_FEE
  • TRADEMARK_FEE
  • VAT
  • REQUEST_TO_PAY

billNumber

String

Yes

The bill number.

More information about this field:

  • Maximum length: 128 characters

billAmount

Amount

Yes

The bill amount.

remark

String

No

The bill remark.

More information about this field:

  • Maximum length: 512 characters

billCreationTime

Datetime

No

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

billDueTime

Datetime

No

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

billSender

User

No

The bill sender information.

billReceiver

User

No

The bill receiver information.

billItems

String

No

The details of the bill items.

More information about this field:

  • Maximum length: 512 characters

billTerm

String

No

The bill term. Valid values are:

  • DAILY: indicates the bill is generated in a daily term.
  • WEEKLY: indicates the bill is generated in a weekly term.
  • ANNUAL: indicates the bill is generated in an annual term.
  • FLEXIBLE: indicates the bill is generated in a flexible term.

More information about this field:

  • Maximum length: 16 characters
  • If this parameter is not specified, the value of this parameter is by default set to FLEXIBLE.

billField

String

No

Any other information about the bill.

More information about this field:

  • Maximum length: 64 characters

User

Field

Data type

Required

Description

userId

String

No

The user ID that is assigned by WorldFirst.

More information about this field:

  • Maximum length: 32 characters

userName

UserName

No

The username of the WorldFirst account.

More information about this field:

  • Maximum length: 128 characters
logonId

String

No

The login account of the user. 

More information about this field: 

  • Maximum length: 128 characters

userNickname

UserName

No

The nickname of user's subaccount.

userAddress

Address

No

The address of the user.

More information about this field:

  • Maximum length: 512 characters

userEmail

String

No

The email of the user.

More information about this field:

  • Maximum length: 67 characters

userMobile

String

No

The mobile phone of the user.

More information about this field:

  • Maximum length: 32 characters

PayToDetail

Field

Data type

Required

Description

payToAmount

Amount

Yes

The payment amount.

beneficiaryInfo

PaymentMethod

Yes

The beneficiary information, such as the payment method type and the receiving account ID.

feeAmount

Amount

No

The fee amount.

remark

String

No

The remark for the payment.

More information about this field:

  • Maximum length: 70 characters

paymentNotifyUrl

String

No

The URL that is used to receive the notification about the payment result.

More information about this field:

  • Maximum length: 128 characters

expireTime

Datetime

No

The time after which the payment order is expired. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

ActionForm

Field

Data type

Required

Description

actionFormType

String

Yes

The action form. The value of this parameter is fixed as RedirectActionForm.

method

String

Yes

The HTTP method.

More information about this field:

  • Maximum length: 16 characters

redirectUrl

String

Yes

The URL that the user is directed to after the payment.

More information about this field:

  • Maximum length: 128 characters

StoreInfo

Field

Data type

Required

Description

storeName

String

No

The name of the store.

marketplaceName

String

No

The name of the marketplace.

authorizedStatus

String

No

The authorization status of the store. 

The value is one of the following: 

  • AUTHORIZED: Authorized
  • NEVER_AUTHORIZED: Not authorized

accountInformation

List<AccountInfo>

No

The account details of the associated store.

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

Supporting document of address

FINANCIAL_REPORT

Financial report

OTHER_MATERIAL

Other materials

ID_CARD_FRONT_SIDE

The front side of the identity card

ID_CARD_BACK_SIDE

The back side of the identity card

BUSINESS_LICENSE

Business license

PASSPORT_PERSONAL_INFORMATION_PAGE

Personal information page of passport

BeneficiaryType

Key

Description

THIRD_PARTY_COMPANY_BANK_ACCOUNT

The beneficiary's bank account is a company third party bank account.

THIRD_PARTY_PERSONAL_BANK_ACCOUNT

The beneficiary's bank account is a personal third party bank account.

BeneficiaryAccountType

Key

Description

WORLDFIRST

The beneficiary is using a WorldFirst wallet.

ALIPAY_CN

The beneficiary is using is an Alipay China wallet.

BANK_CARD

The beneficiary is using is a bank card.

EXTERNAL

The beneficiary is using an account that belongs to external payment services.

INST_ACCOUNT

The beneficiary is using an account that belongs to a financial institution.

INNER_ACCOUNT

The beneficiary is using an internal account.

MINI_ACCOUNT

The beneficiary is using a mini account.

VIRTUAL_ACCOUNT

The beneficiary is using a Virtual Account(VA).

BusinessSceneCode

Key

Description

PAYOUT

The transfer is a payout request.

UNFUNDED_DEAL

The transfer is an unfunded deal.

ExchangeMode

Key

Description

REALTIME

The exchange mode is set to an exchange rate at the real-time.

APPOINTED

The exchange mode is set to an exchange rate at the appointed time.

ExchangeTradeType

Key

Description

SPOT

Spot rate. The foreign exchange trade uses the price when the immediate moment the exchange is initiated. Also known as the price on the spot

FORWARD

Forward rate. The foreign exchange trade uses the price of a predetermined date rather than taking place at the immediate moment the exchange is initiated.

ForwardType

Key

Description

FIXED

Indicates a fixed date.

WINDOWED

indicates a windowed date.

FLEXIBLE

Indicates a flexible date.

HolderAccountType

Key

Description

INDIVIDUAL

The account holder is an individual.

COMPANY

The account holder is a company

PayerAccountType

Key

Description

WORLDFIRST

The payer is using a WorldFirst account.

ALIPAY_CN

The payer is using an Alipay China wallet.

BANK_CARD

The payer is using a bank card.

EXTERNAL

The payer is using an account that belongs to external payment services.

INST_ACCOUNT

The payer is using an account that belongs to a financial institution.

INNER_ACCOUNT

The payer is using an internal account.

MINI_ACCOUNT

The payer is using a mini account.

VIRTUAL_ACCOUNT

The payer is using a Virtual Account(VA).

PaymentMethodType

Key

Description

BALANCE

Use account balance as the payment method.

BENEFICIARY_TOKEN

Use a beneficiary token as the payment method.

BANK_ACCOUNT_DETAIL

Use a bank account as the payment method.

WORLDFIRST_RECEIVE_ACCOUNT

Use a WorldFirst Receiving Account as the payment method.

PurposeCode

Key

Description

COM

The purpose of the transfer is for paying commissions.

TXS

The purpose of the transfer is for paying taxes.

ALW

The purpose of the transfer is for paying allowances.

ACM

The purpose of the transfer is for paying agency commissions.

GDS

Goods bought or sold.

Status

Key

Description

SUCCESS

Success

FAIL

Failure

TransactionType

Key

Description

COLLECTION

Incoming transfer for collecting money.

COLLECTION_REFUND

Refund for incoming transfer.

TRANSFER

Transfer.

TRANSFER_REFUND

Refund for a transfer.

WITHDRAWAL

Entrusted withdrawing.

WITHDRAWAL_REFUND

Refund for entrusted withdrawing.

CONVERSION

Currency conversion.

CONVERSION_DEAL

Currency conversion with a locked-in exchange rate.

CHARGE

Fees that are charged (outbound).

CHARGE_REFUND

Refund for fees that are charged.

ADJUSTMENT

Accounting adjustment.

DEDUCTION

Financial repayment.

DEDUCTION_REFUND

Refund for finanaical repayment. 

FUND_COLLECTION

Collect funds from the sub-accounts into the main account.

FUND_COLLECTION_REFUND

Refund of the collected funds.

REFUND

Refund for a payment.

FX_ADJUSTMENT

Foreign exchange accounting adjustment.

FX_FEE

Foreign exchange fees.

PAYMENT

Payment transaction.

VENDOR_COLLECTION_PAYMENT

Payment to service providers.

CASH_BACK

Cash back.

BALANCE_TO_BALANCE

Transfer between WorldFirst e-commerce balance and the samename funds.

DEPOSIT_PURCHASE

Purchase external term deposit by using WorldFirst balance.

DEPOSIT_REDEEM

Redeem external term deposit. 

FUND_PURCHASE

Purchase money funds.

FUND_REDEEM

Redeem money funds.

DISTRIBUTE

Distribute the commissions.

CREDIT_COLLECTION

Aggregate credit loans.

SETTLEMENT_COLLECTION

Transaction settlement. 

TOPUP

Topup the WorldFirst balance.