Field

Data type

Required

Description

holderName

UserName object

Yes

Name of the account holder.

accountNo

String

Yes

The unique identification of the account.

More information:

• Maximum length: 64 characters

bankName

String

No

Name of the bank.

More information:

• Maximum length: 2048 characters

bankBIC

String

No

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

More information:

• Maximum length: 11 characters

Field

Data type

Required

Description

address1

String

Yes

Street address of the Customer.

Note: For street addresses from China, use the following format:

Room number, Town/Village, Community, Street, District, City, Province, Country

For example, "401, Dabutou Village, Songyuanxia Community, Guanhu Street, Longhua District, Shanghai, China"

More information:

• Maximum length: 256 characters

Field

Data type

Required

Description

region

String

Yes

2-character ISO 3166 country/region code that represents the country/region. For example, US

More information:

• Maximum length: 2 characters

state

String

Yes

Merchant's state or province.

More information:

• Maximum length: 64 characters

city

String

Yes

Merchant's city, district, suburb, town, or village.

More information:

• Maximum length: 64 characters

address1

String

Yes

Merchant's street address, P.O. box address, or the company 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

String

Yes

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

More information:

• Maximum length: 16 characters

Field

Data type

Required

Description

merchantName

String

Yes

Name of the merchant.

More information:

• Maximum length: 256 characters

merchantAddress

Address object

Yes

Detailed address of the merchant.

Note:

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

Field

Data type

Required

Description

paymentMethodType

String

Yes

Type of the payment method.

Valid values are:

• BANK_ACCOUNT
• WALLET

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

paymentMethodMetaData

String

Yes

A JSON string that describes the payment details.

Note:

• For more details about this field, refer to:

• WalletAccountPaymentMethodDetail

• For examples of paymentMethodMetaData, refer to the samples provided with the transfer API.

More Information:

• Maximum length: 2048 characters

Field

Data type

Required

Description

quoteId

String

Yes

The unique ID assigned by the Partner for every quote.

More information:

• Maximum length: 64 characters

quoteCurrencyPair

String

Yes

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

Note:

• Format: base currency/quote currency. For example. RUB/USD

More information:

• Maximum length: 7 characters

quotePrice

String

Yes

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

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

Note:

• The number must be in decimal.

More information:

• Maximum length: 20 characters

quoteStartTime

Datetime object

No

The date and time since when quotePrice is effective.

Note:

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

quoteExpiryTime

Datetime object

No

The date and time when quotePrice expires.

Note:

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

baseCurrency

String

Yes

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

More information:

• Maximum length: 3 characters

quoteUnit

String

Yes

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

1 base currency = quotePrice * quoteUnit * quote currency.

More information:

• Maximum length: 64 characters

Field

Data type

Required

Description

currency

String

Yes

3-character ISO 4217 currency code that the Receiving Account uses. For example, USD

More information:

• Maximum length: 3 characters

walletAccountNo

String

Yes

The account number of the Receiving Account assigned by WorldFirst.

More information:

• Maximum length: 128 characters

Field

Data type

Required

Description

resultCode

String

Yes

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

More information:

• Maximum length: 16 characters

resultMessage

String

No

Result message that explains result codes in detail.

More information:

• Maximum length: 64 characters

resultStatus

String

Yes

Result status.

Valid values are:

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

For more details about each value, refer to the

ResultStatusType section.

Field

Data type

Required

Description

transferFundType

String

Yes

Specify the scenario that the transfer request belongs to.

Valid values are:

• GLOBAL_WORLDFIRST: Transfer to a WorldFirst Account.
• GLOBAL_WORLDFIRST_VA: Transfer to a WorldFirst Virtual Account.

delegationMode

String

Yes

Indicates whether a delegated agent engages in the transfer.

Valid values are:

• TRANSFER: Normal transfer with no delegation.
• DELEGATION_TRANSFER: Transfer by a delegated agent.
• DELEGATION_WITHDRAW: Withdrawal by a delegated agent.

More information:

• Maximum length: 32 characters

Field

Data type

Required

Description

payer

User object

Yes(Conditional)

Information about the payer.

Note:

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

merchant

Merchant object

Yes(Conditional)

Information of the merchant.

Note:

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

transferFromRegion

String

Yes

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

More information:

• Maximum length: 2 characters

Field

Data type

Required

Description

transferFromAmount

Amount object

Yes

The amount of the transfer that the payer needs to pay in a specific currency.

Field

Data type

Required

Description

beneficiary

User object

Yes

Information with regard to the beneficiary.

transferToRegion

String

Yes

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

More information:

• Maximum length: 2 characters

transferRemark

String

No

Remarks for the transfer.

Note:

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

More information:

• Maximum length: 128 characters

bopCode

String

Yes

Code for the Balance of Payments.

Commonly used values are:

• 700001: Partner settlement. transferToRegion cannot be CN, KR, or TH.
• 700002: Commission service trade. transferToRegion cannot be CN, KR, or TH.

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

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

Field

Data type

Required

Description

transferToAmount

Amount object

Yes

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

transferToMethod

PaymentMethod object

Yes

The method that the beneficiary uses to receive the transfer.

transferQuote

Quote object

No

Information on the transfer quotes.

Note:

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

Field

Data type

Required

Description

referenceOrderId

String

Yes

The unique ID that is 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

transferFromAddition

TransferFromAddition object

Yes

Additional transfer information about the payer.

transferToAddition

TransferToAddition object

Yes

Additional transfer information about the beneficiary.

Field

Data type

Required

Description

merchantTransactionId

String

Yes

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

More information:

• Maximum length: 256 characters

referenceNumber

String

Yes

The unique ID assigned by the Partner to identify an order.

More information:

• Maximum length: 64 characters

acquirerId

String

No

Transaction ID assigned by the Partner.

Note: Use this parameter when the Partner is an acquiring financial institution (acquirer).

More information:

• Maximum length: 256 characters

marketplaceId

String

Yes

The ID of the Partner where the order originated from.

Note:

• Value can be the same as extBizPartnerId

More information:

• Maximum length: 64 characters

orderType

String

Yes

Type of the order.

Valid values are:

• Loan
• Refund

For more information about each value, refer to the

OrderType section.

More Information:

• Maximum length: 32 characters

paymentTime

DateTime object

Yes

Indicates the time of the payment.

Note:

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

tradeTime

DateTime object

Yes

Indicates the creation time of the order.

Note:

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

originalAmount

String

Yes

The original amount in cents.

Note:

• Calculate the original amount using the following formula:originalAmount = transactionAmount + distributedAmount
• Maximum length: 16 characters

originalCurrency

String

Yes

3-character ISO 4217 currency code that originalAmountuses.

More information:

• Maximum length: 3 characters

transactionAmount

String

Yes

The transaction amount in cents.

Note:

• Calculate the transaction amount using the following formula:transactionAmount = originalAmount-distributedAmount

More information:

• Maximum length: 16 characters

transactionCurrency

String

Yes

The 3-character ISO 4217 currency code that transactionAmountuses.

More information:

• Maximum length: 3 characters

distributedAmount

String

No

The amount of distributed payments made in cents.

Note: Use this parameter when the Customer needs to make payments for distribution.

• Calculate the distributed amount of the transaction using the following formula:distributedAmount = originalAmount - transactionAmount.

More information:

• Maximum length: 16 characters

distributedCurrency

String

No

The 3-character ISO 4217 currency code that distributedAmount uses.

Note: Use this parameter when the Customer needs to make payments for distribution.

More information:

• Maximum length: 3 characters

buyerId

String

Yes

Buyer ID assigned by the Partner.

More information:

• Maximum length: 32 characters

buyerCountry

String

Yes

The 2-character ISO 3166-1 alpha-2 code that defines the country or region where the buyer locates. For example, US

More information:

• Maximum length: 2 characters

sellerId

String

Yes

Seller ID assigned by the Partner, which usually shares the same value with referenceCustomerId

More information:

• Maximum length: 32 characters

goodsCategory

String

No

Category of the goods.

Note:

• Specify this field if you have the goods information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates.

More information:

• Maximum length: 256 characters

goodsTitle

String

Yes

Title of the goods.

More information:

• Maximum length: 1024 characters

goodsQuantity

Integer

Yes

Quantity of the goods.

logisticsNo

String

No

The logistic number provided.

Note:

• Specify this field if you have the logistics information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates.

More information:

• Maximum length: 128 characters

logisticsMethod

String

No

The method used for logistics.

Note: Specify this field if you have the logistics information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates.

More information:

• Maximum length: 128 characters

serviceProvider

String

No

Logistic service provider's name.

Note:

• Specify this field if you have the logistics information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates.

More information:

• Maximum length: 128 characters

receiverAddress

String

No

Address of the goods' receiver.

Note:

• Specify this field if you have the goods or logistics information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates.

More information:

• Maximum length: 512 characters

receiverName

String

No

Name of the goods' receiver.

Note:

• Specify this field if you have the goods or logistics information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates.

More information:

• Maximum length: 1024 characters

senderAddress

String

No

Address of the goods' sender.

Note:

• Specify this field if you have the goods or logistics information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates.

More information:

• Maximum length: 512 characters

senderName

String

No

Name of the goods' sender.

Note:

• Specify this field if you have the goods or logistics information. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and would increase payment success rates.

More information:

• Maximum length: 1024 characters

storeUrl

String

Yes

URL of the Customer's store on Partner's platform. Used for subsequent risk assessment.

More information:

• Maximum length: 256 characters

Field

Data type

Required

Description

userName

UserName object

Yes(Conditional)

User's name.

Note:

• This field is required when the Customer needs information for risk management purposes.

birthday

String

Yes(Conditional)

User's birthday. For example,19920202

Note:

• This field is required when the Customer needs information for risk management purposes.

More information:

• Maximum length: 8 characters

userPhoneNo

String

Yes(Conditional)

User's phone number. For example, 8613766666666

Note:

• This field is required when the Customer needs information for risk management purposes.

More information:

• Maximum length: 32 characters

userAddress

Address object

Yes(Conditional)

User's address.

Note:

• This field is required when the Customer needs information for risk management purposes.

accountStatus

String

Yes

Status of the user's account.

Valid values are:

• ACTIVE
• INACTIVE

For more information about each value, refer to the

AccountStatus section.

Field

Data type

Required

Description

userName

UserName object

Yes

User's name.

Field

Data type

Required

Description

firstName

String

Yes

User's first name.

More information:

• Maximum length: 32 characters

lastName

String

Yes

User's last name.

More information:

• Maximum length: 32 characters

Field

Data type

Required

Description

fullName

String

Yes

User's full name.

More information:

• Maximum length: 64 characters

Field

Data type

Required

Description

walletAccountNo

String

Yes

Account number of the wallet.

More information:

• Maximum length: 128 characters

paymentMethodDetailType

String

Yes

Account type of the wallet. The default value is WorldFirst.

More information:

• Maximum length: 64 characters

customerName

UserName object

Yes

Name of the Customer.

More information:

• Maximum length: 64 characters

walletName

String

Yes

Name of the e-Wallet account brand. For example, worldFirst.

Key

Description

ACTIVE

The user is active.

INACTIVE

The user is inactive.

Key

Description

INDIVIDUAL

The account holder is an individual.

COMPANY

The account holder is a company.

Key

Description

Loan

Loan order.

Refund

Refund order.

Key

Description

S

Success

F

Failure

U

Unknown

Key

Description

BANK_ACCOUNT

Bank account

WALLET

E-wallet