WorldFirst DocsWorldFirst DocsDOCS

Inquire about available quotaSignature required

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 object 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 object 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

CodeValueMessageFurther action
SUCCESSSSuccess
UNKNOWN_EXCEPTIONUThe 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_ILLEGALFIllegal 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_FAILFThe contract check failed.

Check the contract status with WorldFirst before retrying.

ACCOUNT_NOT_EXISTFThe account does not exist.

Check if the account is valid and retry.

@2024 WorldFirst