Inquire about available quotaSignature required

2024-11-21 06:55

POST /amsin/api/v1/business/account/inquiryAvailableQuota

Call the inquiryAvailableQuota API to inquire about the available quota for foreign exchange (FX) settlement. The quota is used for FX settlement declaration from WorldFirst.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

quotaAccumulationMethod String REQUIRED

Indicates the method that is used for FX settlement quota accumulation.

Valid values are:

USER_ID: indicates that the quota is accumulated by the WorldFirst user ID.
RECEIVING_ACCOUNT: indicates that the quota is accumulated by the receiving account.
VIRTUAL_ACCOUNT: indicates that the quota is accumulated by the virtual account.
BENEFICIARY: indicates that the quota is accumulated by the beneficiary.

quotaAccumulationId String REQUIRED

Indicates an ID to identify the quota accumulation method. Rules:

If quotaAccumulationMethod = USER_ID, specify this parameter as the WorldFirst user ID.
If quotaAccumulationMethod = RECEIVING_ACCOUNT, specify this parameter as the receiving account.
If quotaAccumulationMethod = VIRTUAL_ACCOUNT , specify this parameter as the virtual account.
If quotaAccumulationMethod = BENEFICIARY , specify this parameter as the beneficiary ID.

currency String REQUIRED

Indicates the currency used for the FX settlement quota. The value of this parameter must be a 3-character alphabetic code that follows the ISO 4217 standard, for example, USD.

tradeType String CONDITIONAL

The type of the trade. Specify this parameter if quotaAccumulationMethod = BENEFICIARY.

Valid values are:

GOODS: indicates the goods trade.
SERVICE: indicates the service trade.

Response parameters

result Result REQUIRED

Indicates the result of the API call.

Show child parameters

quotaAccumulationMethod String REQUIRED

Indicates the method that is used for FX settlement quota accumulation.

Valid values are:

USER_ID: indicates that the quota is accumulated by the WorldFirst user ID.
RECEIVING_ACCOUNT: indicates that the quota is accumulated by the receiving account.
VIRTUAL_ACCOUNT: indicates that the quota is accumulated by the virtual account.
BENEFICIARY: indicates that the quota is accumulated by the beneficiary.

quotaAccumulationId String REQUIRED

Indicates an ID to identify the quota accumulation method. Rules:

If quotaAccumulationMethod = USER_ID, specify this parameter as the WorldFirst user ID.
If quotaAccumulationMethod = RECEIVING_ACCOUNT, specify this parameter as the receiving account.
If quotaAccumulationMethod = VIRTUAL_ACCOUNT , specify this parameter as the virtual account.
If quotaAccumulationMethod = BENEFICIARY , specify this parameter as the beneficiary ID.

availableQuota Amount REQUIRED

Indicates the available FX settlement quota for declaration.

Show child parameters

tradeType String CONDITIONAL

The type of the trade. Specify this parameter if quotaAccumulationMethod = BENEFICIARY.

Valid values are:

GOODS: indicates the goods trade.
SERVICE: indicates the service trade.

API Explorer

Request

URL

Case

When quotoAccumulationMethod is USER_ID

Request Body

Response

Case

When quotoAccumulationMethod is USER_ID

Response Body

Result processing logic

After the Partner calls the API, WorldFirst responds to the Partner by specifying the value of the result.resultStatus parameter in the response body. The following table lists valid values for the result.resultStatus parameter and their descriptions.

result.resultStatus	Description
`S`	The API call succeeds.
`F`	The API call failed. For more information about why the call failed and how to handle the result, see the value of the result.resultCode parameter.
`U`	The API call result is unknown. The Partner can try to call the API again by following the rules below: At most 7 queries are allowed. Intervals between queries: 5m, 10m, 20m, 40m, 80m, 160m, and 320m. If none of the queries is successful, contact the WorldFirst Technical Support Team.

Result/Error codes

Code	Value	Message	Further action
SUCCESS	S	Success
UNKNOWN_EXCEPTION	U	The API call is failed, which is caused by unknown reasons.	The service might be down, retry later. If the issue persists, contact the WorldFirst Technical Support Team.
PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.	Check and verify whether the request fields, including the header fields and body fields, are correct and valid. For details on the fields of each API, see the specific API Structure section.
CONTRACT_CHECK_FAIL	F	The contract check failed.	Check the contract status with WorldFirst before retrying.
ACCOUNT_NOT_EXIST	F	The account does not exist.	Check if the account is valid and retry.