Submit trade orderSignature required
Use this API to submit trade orders.
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
requestId String REQUIRED
The unique ID assigned by the Partner to identify a trade order submission request.
More information:
- This field is an API idempotency field.The Partner can use it to do the idempotent check.
- Maximum length: 64 characters
sceneCode String REQUIRED
The code that represents the business scenario. Valid values:
CREATE_B2B_ORDERS: the B2B trade orders are created and associated.PAY_INTO_CHINA: the foreign exchange scenario without the association of the trade order.
quotaAccumulationMethod String REQUIRED
The method that is used for the quota accumulation. Valid values are:
USER_ID: indicates the quota is accumulated by the WorldFirst user ID.RECEIVING_ACCOUNT: indicates the quota is accumulated by the receiving account.VIRTUAL_ACCOUNT: indicates the quota is accumulated by the virtual account.BENEFICIARY: indicates the quota is accumulated by the beneficiary.TRANSFER_ID: indicates the quota is accumulated by the transfer ID.COLLECTION_ID:indicates the quota is accumulated by the collection ID.
quotaAccumulationId String REQUIRED
The ID that is used for the quota accumulation. Specify this parameter with the following 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. - If quotaAccumulationMethod =
TRANSFER_NO, specify this parameter as the transfer ID. - If quotaAccumulationMethod =
COLLECTION_NO, specify this parameter as the batch number, which is specified in the collection ID.
tradeOrders Array <TradeOrder> REQUIRED
The list of trade orders. Specify this parameter with the following rules:
- If the value of the sceneCode parameter is
CREATE_B2B_ORDERS, the maximum size of this parameter is 10 elements. - If the value of the sceneCode parameter is
PAY_INTO_CHINA, the maximum size of this parameter is 100 elements.
notifyUrl String
The url to receive trade order submission results from WorldFirst via the notifyTradeOrder and notifyAssociationResult APIs.
More information:
- Maximum length: 256 characters
platform String B2C CONDITIONAL
The platform where the trade order occurs. Specify this parameter if the value of the sceneCode parameter is PAY_INTO_CHINA.
More information:
- Maximum length: 32 characters
extendInfo String B2B
Extended information.
More information:
- Maximum length: 2048 characters
Response parameters
result Result REQUIRED
Indicates the result of trade order submission.
requestId String B2C CONDITIONAL
The unique ID assigned by the Partner to identify a trade order submission request.
This parameter is returned if sceneCode is
PAY_INTO_CHINA.
More information:
- This field is an API idempotency field.The Partner can use it to do the idempotent check.
- Maximum length: 64 characters
acceptOrderId String B2B CONDITIONAL
The unique ID assigned by WorldFirst to identify a trade order submission request.
This parameter is returned if sceneCode is
CREATE_B2B_ORDERS.
More information:
- Maximum length: 128 characters
tradeOrderResult B2C Array <TradeOrderResult> CONDITIONAL
The trade order information, including the trade order number and the trade order status.
This parameter is returned if sceneCode is
PAY_INTO_CHINA.
Request
Response
Result processing logic
Once the Partner calls API, WorldFirst returns with its result. The range of result.resultStatus field is:
result.resultStatus Description S API is called with success. F API is called with failure. For reasons, refer to result.resultCode and result.resultMessage. U When API returns with Retry strategy: Please contact WorldFirst technical support if the issue remains.UNKNOWN, retry calling it.
result.resultCode
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | Success | |
| PROCESS_FAIL | F | A general business failure occurred. Do Not retry. | Contact WorldFirst technical support for human intervention. |
| PARAM_ILLEGAL | F | Illegal parameters exist. For example, a non-numeric input, or an invalid date. | Update the trade order, change requestId, and retry it. |
| INVALID_SIGNATURE | F | The signature is invalid. | Validate the signing request, change requestId, and retry it. |
| REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. | It's a idempotent request. Do Not retry. |
| UNKNOWN_EXCEPTION | U | The API call is failed, which is caused by unknown reasons. | Do not change requestId. Retry it. |
| FUND_ORDER_NOT_EXIST | F | The fund order does not exit. | Contact WorldFirst technical support. |
| ACCESS_DENIED | F | Access is denied for submitting trade orders. | Contact WorldFirst technical support. |
| ORDER_COUNT_EXCEED_LIMIT | F | The number of associated trade orders exceeds limit. | Update the number of order associations, change order requestId, and retry it. |
| WRONG_TRADE_TYPE | F | tradeType is not supported, or tradeType values are inconsistent across trade orders. | Contact WorldFirst technical support. |
| REQUEST_PARAM_AMOUNT_ERROR | F | Invalid amount parameter exists. | Update the trade order or its associated details, change the order requestId, and retry it. |
| TRADE_ORDER_AUTH_STATUS_ILLEGAL | F | Associated trade order already exists, and its verification has not passed. | Contact WorldFirst technical support. |
| RELATE_AMOUNT_ERROR | F | The intended association amount is incorrect. | Update the associated amount of trade order, change order requestId, and retry. Note: The amount of the submitted order can not be modified. |
| ENTITY_REGISTRATION_REQUIRED | F | Entity registration is required for uploading customs declaration. | Contact WorldFirst technical support. |
| INCONSISTENT_TRADE_TYPE | F | tradeType values are inconsistent for partial associations of the same collection order. | Contact WorldFirst technical support. |
| UN_SUPPORT_BUSINESS | F | Unsupported business. | Invalid parameter. Retry with the correct parameters. |
| CONTRACT_CHECK_FAIL | F | The contract check has failed. | Check the contract status then retry. |
| REGULATED_COUNTRY_NOT_SUPPORTED | F | The tradeCountry or deliverCountry of the trade order is not supported. We do not support the order temporarily for the safety of customers' funds. | For the full list of regulated countries, refer to the parameter introduction . Please contact WorldFirst Support Team for further details. |
| REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. | Ensure all the fields in the requests are the same and try again. |
| FUND_ORDER_RELATED_MANUALLY | F | Fund order has already been manually related to the trade order. | Check if the related fund order is correct. If so, do not relate it again. |
| USER_NOT_EXIST | F | The user does not exist. | Retry with the correct user information. |
| 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. |