inquiryTransferQuota

2022-05-13 12:00

POST: /aps/api/business/trade/inquiryTransferQuota
Signature required

Note: This step only concerns transfers inbound to China. It is not necessary for non-CNY scenario transfers.

For transfers that are inbound to China, a Customer might be subject to a quota limit. It is the best practice for the Partner to ensure the transfer request does not exceed the available transfer quota.

The Partner can query the quota limit of a Customer in a certain currency with the inquiryTransferQuota interface. WorldFirst(Alipay) responds to the Partner with the available quota, the quota that is frozen(unavailable), and the total quota. The Partner needs to make sure the available transfer quota is enough for the amount of the transfer.

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

Field	Data type	Required	Description
transferFactor	TransferFactor object	Yes	Indicates different scenarios for the transfer, such as: remitting to China in CNY, or remitting to countries/regions other than China. Note: This field is required when you need to support more than one remittance scenarios (`transferFactor.transferFundType` has more than one value)
merchantId	String	Yes(Conditional)	The unique ID that is assigned by WorldFirst(Alipay) to identify the Customer. In this case, the beneficiary. Note: This field is required when `transferFundType` is `GLOBAL_CNH_CN` or `FX_CN`. This field is optional when `transferFundType` is `GLOBAL_GLOBAL_SERVICE`. This field can be the same as the `customerId` field which is obtained by calling the registerCustomer API. More information: Maximum length: 32 characters
referenceMerchantId	String	Yes(Conditional)	The unique ID assigned by the Partner to identify the Merchant(Customer). Note: This field is required when `transferFundType` is `GLOBAL_CNH_CN` or `FX_CN`. This field is optional when `transferFundType` is `GLOBAL_GLOBAL_SERVICE`. More information: Maximum length: 64 characters
currency	String	No	3-character ISO-4217 code of the currency that hits the transfer quota limit. Note: If `currency` is missing, WorldFirst(Alipay) returns the quotas in all the available currencies of the beneficiary. More information: Maximum length: 3 characters
bopCode	String	Yes	Balance of payment code. The default value of this field is `122030`(online trade). More information: Maximum length: 16 characters

Response parameters

Field	Data type	Required	Description
result	Result object	Yes	Indicates whether this API is called successfully.
transferFactor	TransferFactor object	Yes	Indicates different scenarios for the transfer, such as: remitting to China in CNY, or remitting to countries/regions other than China.
referenceMerchantId	String	Yes(Conditional)	The unique ID that is assigned by the partner to identify the customer. Note: WorldFirst(Alipay) returns this field when `transferFundType` is `GLOBAL_CNH_CN` or `FX_CN`. WorldFirst(Alipay) does not return this field when `transferFundType` is `GLOBAL_GLOBAL_SERVICE`. More information: Maximum length: 64 characters
merchantId	String	Yes(Conditional)	The unique ID that is assigned by WorldFirst(Alipay) to identify the customer. In this case, the Beneficiary. Note: WorldFirst(Alipay) returns this field when `transferFundType` is `GLOBAL_CNH_CN` or `FX_CN`. WorldFirst(Alipay) does not return this field when `transferFundType` is `GLOBAL_GLOBAL_SERVICE`.
transferQuotas	Array<TransferQuota object>	Yes(Conditional)	Detailed information on the beneficiary's transfer quota. Note: WorldFirst(Alipay) returns this field when `result.resultStatus` is `S`.

Result processing logic

After calling the API, a response is returned. The possible responses for result.resultStatus are:

Result status	Description
S	This indicates the API call succeeded.
F	This indicates the API call failed. For more information on why the call failed, see `result.resultCode`.
U	This indicates the API call result is unknown. The Partner can make another API call. Use the following query strategy: A Partner can make 7 queries at maximum. Intervals between queries: 5m, 10m, 20m, 40m, 80m, 160m, and 320m. If none of the queries is successful, contact WorldFirst(Alipay) Technical Support.

Result codes

`result.resultCode`

resultCode	resultStatus	resultMessage	Further action
SUCCESS	S	Success
PROCESS_FAIL	F	A general business failure occurred. Do not retry.	Human intervention is usually needed. It is recommended that you contact WorldFirst Technical Support to resolve the issue.
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.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.	Call the interface again to resolve the issue. If the issue persists, contact WorldFirst Technical Support.
INVALID_API	F	The called API is invalid or not active.	Check whether the correct API is being called.
INVALID_CLIENT	F	The client is invalid.	The Client ID does not exist or is invalid.
INVALID_SIGNATURE	F	The signature is invalid.	Make sure the request is properly signed with a valid signature. For more details, refer to the following chapter: The signature field in a request header. How to calculate a signature.
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.	Ensure the HTTP method is `POST`.
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 WorldFirst Technical Support.
UN_SUPPORT_BUSINESS	F	Unsupported business.	Invalid parameters are used e.g. currency is incorrect. Retry with the correct information.

Samples

Request

copy

{
  "bopCode": "228050",
  "currency": "USD",
  "merchantId": "2021******",
  "referenceMerchantId": "111******",
  "transferFactor": {
    "transferFundType": "GLOBAL_CNH_CN"
  }
}

Response

copy

{
  "merchantId": "2021******",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  },
  "transferFactor": {
    "transferFundType": "GLOBAL_CNH_CN"
  },
  "transferQuotas": [{
    "availableQuota": {
      "currency": "USD",
      "value": "5657"
    },
    "frozenQuota": {
      "currency": "USD",
      "value": "0"
    },
    "totalQuota": {
      "currency": "USD",
      "value": "5657"
    }
  }]
}