Data dictionary

2023-12-04 07:36

Model

Address

Field	Data type	Required	Description
region	String	No	2-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: 64 characters
city	String	No	City/District/Suburb/Town/Village. More information: Maximum length: 64 characters
address1	String	No	Address line 1(Street address/PO Box/Company name). More information: Maximum length: 256 characters
address2	String	No	Address line 2(Apartment/Suite/Unit/Building). More information: Maximum length: 256 characters
zipCode	String	No	ZIP or postal code. More information: Maximum length: 32 characters

Amount

Field

Data type

Required

Description

currency

String

Yes

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

More information:

Maximum length: 3 characters

value

Integer

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:

The Partner is suggested to choose Integer as the data type while creating a payment order. While in the response message, WorldFirst only returns this field as a String.
Maximum length: 16 characters

Buyer

Field	Data type	Required	Description
referenceBuyerId	String	Yes	The unique ID assigned by the Partner to identify the buyer on the Partner's marketplace.

FeeDetailSummary

Field	Data type	Required	Description
feeType	String	Yes	Type of the fee requested. If no fee is requested, the parameter remains empty.
paymentMethodType	String	Yes	Type of the payment method. Note: The value of this field is fixed as `WALLET_WF`.
feeAmount	Amount object	Yes	The amount of the fee.

Order

Field	Data type	Required	Description
referenceOrderId	String	Yes	The unique ID that is assigned by the Partner to identify the payment order. The Partner uses this field for various purposes such as displaying the Customers payment history, managing the Customer's disputes, and providing Customer support. More information: Maximum length: 64 characters
transactionTime	DateTime object	Yes	The time that the payment order takes place. Note: The value of this field is accurate to milliseconds and follows the ISO 8601 standard format and +08:00 timezone. For example, `2022-06-17T08:43:58.588Z`.
orderDescription	String	Yes	Description of the payment order. The Customer can view this information from the "Order Information" section on the Checkout page. More information: Maximum length: 256 characters
orderTotalAmount	Amount object	Yes	The total amount of the payment order. The Customer views this amount on the "Payment successful" page.
orderFeeAmount	Amount object	No	Amount of the fee for the payment order. The Customer views this amount on the "Payment successful" page.
shippingInfo	Shipping object	No	Shipping information.

OrderGroup

Field	Data type	Required	Description
orderGroupId	String	Yes	The unique ID that assigned by the Partner to identify the order group. Note: WorldFirst displays the value of this field on the Checkout page. More specifically, in the "Order Information" section. More information: Maximum length: 64 characters
orderGroupDescription	String	Yes	Description of the order group. For example, `CASHIER_PAYMENT`. WorldFirst displays the value of this field on the Checkout page. More information: Maximum length: 64 characters
orderBuyer	Buyer object	Yes	Information about the buyer. WorldFirst uses the value of this field for risk control purposes.
orders	Array<Order object>	Yes	Information about the order.

OrderResult

Field

Data type

Required

Description

status

String

Yes

Status of the order.

Valid values are:

SUCCESS: Payment order success
PROCESS_FAIL: Payment order failed to process.
BANK_REFUSE_PAYMENT: Bank refused to honor the payment order.

statusMsg

String

Yes(Conditional)

The status message of the payment order explains the reason for the unsuccessful payment.

Note:

This field is returned to the Partner when the payment order failed.

PaymentDetailSummary

Field	Data type	Required	Description
customerId	String	Yes(Conditional)	The unique ID that is assigned by WorldFirst to identify a Customer. Note: This field is not required in the inquirePayment API. This field is required for the notifyPayment API. More information: Maximum length: 32 characters
customerName	UserName object	Yes	Payer's name. Give `customerName.fullName` parameter the value of a company name for a corporate payer or a person's full name for an individual payer. Note: This parameter enables the whitelisted partners to call payers' names. If you need this capability and are not yet in the whitelist, contact your business point of contact (BD/SA) beforehand.
paymentAmount	Amount object	Yes	The amount of the payment that the Customer needs to pay.
paymentMethodType	String	Yes	Type of the payment method used. Note: The value of this field is fixed as `WALLET_WF`.
paymentMethodMetadata	String	No	Extended information about the WorldFirst website login that the Partner uses.
extendInfo	String	Yes(Conditional)	Extended information on the payment details. Note: WorldFirst only returns this field to the Partner when the fields are about payment fees.

PaymentMethod

Field

Data type

Required

Description

paymentMethodType

String

Yes

Defines the type of payment method.

Default value is WALLET_WF.

Possible values are:

WALLET_WF
MIXEDCARD

PayToDetail

Field	Data type	Required	Description
payToRequestId	String	Yes	The unique ID that is assigned by the Partner to identify each payment. Note: This field is an API idempotency field. For details about API idempotency, refer to the Idempotency chapter. More information: Maximum length: 64 characters
referenceOrderId	String	Yes	The unique ID that is assigned by the Partner to identify the payment order. The Partner uses this field for various purposes such as displaying the Customers payment history, managing the Customer's disputes, and providing Customer support. More information: Maximum length: 64 characters
payToAmount	Amount object	Yes	The amount of the payment that the Payee needs to pay.
payToMethod	PayToMethod object	Yes	The detailed information about the payment methods that the payee uses.
paymentNotifyUrl	String	Yes	The customized URL that is defined by the Partner to receive the payment result notification. More information: Maximum length: 1024 characters
paymentExpiryTime	DateTime	Optional	The time when an order expires. Note: When paymentExpiryTime and paymentTimeoutExpress are specified at the same time, paymentExpiryTime is used by default. More information: 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). This parameter is currently only available for the whitelisted partners. If you need to use it, contact your business point of contact (BD/SA) beforehand.
paymentTimeoutExpress	String	Optional	The timeframe in which the order must be completed. Exceeding this timeframe leads to payment rejection and order cancellation. Note: When paymentExpiryTime and paymentTimeoutExpress are specified at the same time, paymentExpiryTime is used by default. This parameter uses the following time units: m (minute), h (hour), and d (day). This parameter only supports integers. For example, 1.5 h must be converted into 90 m. More information: This parameter is currently only available for the whitelisted partners. If you need to use it, contact your business point of contact (BD/SA) beforehand.

PayToMethod

Field	Data type	Required	Description
paymentMethodType	String	Yes	Defines the type of payment method. Note: The value of this field is fixed as `BALANCE`.
paymentMethodDataType	String	Yes	Defines the data type of the payment method. Note: The value of this field is fixed as `PAYMENT_ACCOUNT_NO`.
customerId	String	Yes	The unique ID that is assigned by WorldFirst to identify a Customer. More information: Maximum length: 32 characters

PayToSummary

Field	Data type	Required	Description
orderResult	OrderResult object	Yes(Conditional)	Indicates the result of the payment order. Note: This field is required for the inquirePayment API. This field is not required for the createCashierPayment API.
payToAmount	Amount object	Yes	The amount of the payment that the Payee needs to pay.
payToRequestId	String	Yes	The unique ID that is assigned by the Partner to identify each payment. Note: This field is an API idempotency field for the createCashierPayment API. For details about API idempotency, refer to the Idempotency chapter. More information: Maximum length: 64 characters
payToId	String	Yes	The unique ID assigned by WorldFirst to define each payment. More information: Maximum length: 64 characters
payToCreateTime	DateTime object	Yes	The time that the payment order is created. Note: The value of this field follows the ISO 8601 standard format and +08:00 timezone. For example, `2018-09-03T00:00:00+08:00`.

RedirectActionForm

Field	Data type	Required	Description
actionFormType	String	Yes	Defines the type of the action form. Valid values are: `RedirectActionForm`: Indicates this action form is for redirection purposes.
method	String	Yes	The HTTP method that is used for the action form. More information: Maximum length: 64 characters
parameters	String	No	The value parameter that is used for the HTTP method. More information: Maximum length: 2048 characters
redirectUrl	String	Yes	Redirection URL that is used for the action form. More information: Maximum length: 1024 characters
extendInfo	String	No	Extended information about the action form. More information: Maximum length: 2048 characters

RefundOrder

Field

Data type

Required

Description

refundFeeAmount

Amount object

The amount of the refund fee.

referenceRefundId

String

The unique ID that is assigned by the Partner to identify a refund request.

More information:

Maximum length: 64 characters

RefundToDetail

Field	Data type	Required	Description
refundMethod	PaymentMethod object	Yes	The payment method utilized for the refund request.
refundAmount	Amount object	Yes	Amount that the payee refunds.
refundToAmount	Amount object	No	Amount that the payer receives.
extendInfo	String	No	Extended information about the refund. More information: Maximum length: 2048 characters

RefundDetail

Field	Data type	Required	Description
refundMethod	PaymentMethod object	Yes	The payment method utilized for the refund request.
refundAmount	Amount object	Yes	The amount that the payment executor pays.

Result

Field	Data type	Required	Description
resultCode	String	Yes	Result code. Possible values are listed in the Result codes table on this page. More information: Maximum length: 64 characters
resultStatus	String	Yes	Result status. Valid values are: `S`: Successful `F`: Failed `U`: Unknown
resultMessage	String	No	Result message that explains result codes in detail. More information: Maximum length: 256 characters

Shipping

Field	Data type	Required	Description
shippingName	UserName object	No	The name of the receiver of the goods being shipped.
shippingAddress	Address object	No	The address of the receiver of the goods being shipped.
shippingFee	Amount object	No	Shipping fees for the goods.
shippingCarrier	String	No	More information: Maximum length: 128 characters

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	No	The full name of the user. More information: Maximum length: 128 characters

RefundInfo

Field	Data type	Required	Description
refundId	String	Yes	The unique ID of the refund order. More information: Maximum length: 64 characters
refundRequestId	String	Yes	The unique ID of the refund request. More information: Maximum length: 64 characters
payToId	String	Yes	The unique ID assigned by WorldFirst to identify a payment. More information: Maximum length: 64 characters
refundReason	String	No	The reason for the refund. More information: Maximum length: 256 characters
refundAmount	Amount object	Yes	The amount to be refunded.
refundTime	DateTime	Yes	The time of refund. More information: 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).
refundStatus	String	Yes	The refund status. Valid values: `SUCCESS` indicates refund is successful.
refundOrderDetail	Array<RefundOrderDetail>object	Yes	The details of the refund order, such as the actual refunded amount, its fund type and payment method.

RefundOrderDetail

Field	Data type	Required	Description
refundActualAmount	Amount object	Yes	The actual refunded amount.
fundType	String	Conditional	The type of the refund. Note: The value of this parameter is fixed as `FEE`.
paymentMethodType	String	Yes	Type of the payment method used. Note: The value of this parameter is fixed as `WALLET_WF`.

Enumeration

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

PaymentMethodType

Key	Description
BALANCE	Wallet balances payment.
MIXEDCARD	Card payment.
WALLET_WF	WorldFirst wallet payment.