Submit trade order
POST: /amsin/api/v1/business/account/submitTradeOrder
This API is used to submit trade orders. The Partner calls submitAttachment API to submit the required attachments.
Structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:
Request body parameters
Field | Data type | Required | Description |
requestId | String | Yes | The unique ID assigned by the Partner to identify a trade order submission request. More information about this field:
|
sceneCode | String | Yes | The code that represents the business scenario. Valid values:
|
tradeOrders | Array <TradeOrder Object> | Yes | The list of trade orders. If the value of the sceneCode parameter is |
platform | String | No (Conditional) | The platform where the trade order occurs. Specify this parameter if he value of the sceneCode parameter is More information about this parameter:
|
transferId | String | No (Conditional) | Indicates the transfer or collection order number. Specify this parameter if the value of the sceneCode parameter is More information about this field:
|
quotaAccumulationMethod | String | No (Conditional) | The method that is used for the quota accumulation. Valid values are:
Specify this parameter if the value of the sceneCode parameter is |
referenceBatchNo | String | No (Conditional) | The batch number of trade orders. Specify this parameter if the value of the quotaAccumulationMethod parameter is More information about this field:
|
notifyUrl String | String | No | The asynchronous URL where the notification of trade order submission result is sent. More information about this field:
|
Response parameters
Field | Data type | Required | Description |
result | Result Object | Yes | Indicates the result of trade order submission. |
requestId | String | Yes | The unique ID assigned by the Partner to identify a trade order submission request. More information about this field:
|
acceptOrderId | String | Yes | Accepted order number More information about this field:
|
tradeOrderResult | Array <TradeOrderResult object> | Conditional | The trade order information, including the trade order number and the trade order status. This parameter is returned if the value of the sceneCode parameter is |
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 UNKNOWN, retry calling it. Retry strategy:
Please contact WorldFirst technical support if the issue remains. |
Result code
result.resultCode
resultCode | resultStatus | resultMessage | 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 the limit. | Update the number of order associations, change order reqeustId, 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 reqeustId, and retry it. |
TRADE_ORDER_AUTH_STATUS_ILLEGAL | F | The 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 reqeustId, and retry. Note: The amount of the submitted order can not be modified. |
ENTITY_REGISTRATION_REQUIRED | F | Entity registration is required for uploading customs declarations. | 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. |
Sample code
Sample 1: B2C senario where the value of quotaAccmulationMethod is USER_ID
Request
{
"requestId": "20230222191210001100300007*****",
"sceneCode": "PAY_INTO_CHINA",
"quotaAccumulateTarget": "USER_ID",
"platform": "AER",
"tradeOrder": [
{
"referenceOrderNo": "50957342066*****",
"orderTime": "2023-01-10T21:18:24Z",
"payTime": "2023-01-10T21:28:24Z",
"orderType": "PAYMENT",
"tradeBizType": "B2C",
"tradeType": "GOODS",
"tradeAmount": {
"value": 500,
"currency": "USD"
},
"transAmount": {
"value": 500,
"currency": "USD"
},
"merchant": {
"store": {
"storeShopUrl": "//www.aliexpress.com/store/56*****"
}
},
"buyer": {
"referenceBuyerId": "7175*****",
"buyerName": {
"fullName": "ekaterina tsip*****"
}
},
"seller": {
"customerId": "21201200791*****"
},
"goods": [
{
"goodsName": "*****",
"goodsCategory": "Jewelry & Access*****",
"goodsQuantity": "1"
}
],
"shipping": {
"wayBillInfo": [
{
"shippingOrderReferenceNo": "RM450941*****",
"shippingAddress": {
"address1": "Калининград г, Калининградская обл, Менделее*****",
"city": "Калининг*****",
"region": "RU"
}
}
]
}
}
]
}Response
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"requestId": "*****",
"tradeOrderResults": [
{
"referenceOrderNo": "*****",
"orderStatus": "ACCEPT",
"statusMessage": "Accepted, pending process."
}
]
}Sample 2: B2C senario where the value of quotaAccmulationMethod is RECEIVING_ACCOUNT
Request
{
"requestId": "20230222191210001100300007*****",
"sceneCode": "PAY_INTO_CHINA",
"quotaAccumulateTarget": "RECEIVING_ACCOUNT",
"platform": "AER",
"tradeOrder": [
{
"referenceOrderNo": "50957342066*****",
"orderTime": "2023-01-10T21:18:24Z",
"payTime": "2023-01-10T21:28:24Z",
"orderType": "PAYMENT",
"tradeBizType": "B2C",
"tradeType": "GOODS",
"tradeAmount": {
"value": 500,
"currency": "USD"
},
"transAmount": {
"value": 500,
"currency": "USD"
},
"merchant": {
"store": {
"storeShopUrl": "//www.aliexpress.com/store/56*****"
}
},
"buyer": {
"referenceBuyerId": "7175*****",
"buyerName": {
"fullName": "ekaterina tsip*****"
}
},
"seller": {
"referenceCustomerId": "7276*****"
},
"sellerAccount": {
"bankAccountNo": "*****"
}
"goods": [
{
"goodsName": "*****",
"goodsCategory": "Jewelry & Access*****",
"goodsQuantity": "1"
}
],
"shipping": {
"wayBillInfo": [
{
"shippingOrderReferenceNo": "RM450941*****",
"shippingAddress": {
"address1": "Калининград г, Калининградская обл, Менделее*****",
"city": "Калининг*****",
"region": "RU"
}
}
]
}
}
]
}Response
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"requestId": "*****",
"tradeOrderResults": [
{
"referenceOrderNo": "*****",
"orderStatus": "ACCEPT",
"statusMessage": "Accepted, pending process."
}
]
}Sample 3: B2B scenario
Request
{
"requestId": "16782687*****",
"sceneCode": "CREATE_ORDERS_AND_ASSOCIATE",
"transferId": "20230308191210001100300007*****",
"tradeOrders": [
{
"referenceOrderNo": "trade_order16782687*****",
"tradeBizType": "B2B",
"tradeType": "GOODS",
"orderTime": "2023-01-10T21:18:24Z",
"isUsedForExchange": "Y",
"purposeCode": "ACM",
"tradeAmount": {
"currency": "USD",
"value": "2999"
},
"transAmount": {
"currency": "USD",
"value": "2999"
},
"bizContractInfo": {
"buyerEnName": "阿联*****",
"contractList": [
{
"fileKey": "sd*****",
"fileName": "sa*****"
}
],
"deliverCountry": "JP",
"tradeCountry": "JP"
},
"goods": [
{
"goodsCnName": "微软*****",
"goodsName": "Microsoft Ergonomic Keyboard (LXM-0*****",
"goodsQuantity": "3",
"goodsUnit": "KG",
"storeUrl": "http://sd*****"
}
],
"shipping": {
"expectedShippingDate": "16594306*****",
"isDeclared": "N",
"isNewBuyer": "N",
"isShipped": "N",
"tradeTerms": "CFR",
"wayBillInfos": [
{
"logisticsCompany": {
"providerKey": "HYESL",
"providerValue": "阿联酋*****"
},
"shippingMethod": "RAILWAY",
"shippingOrderReferenceNo": "12*****",
"shippingProofAttachmentList": [
{
"fileKey": "sd*****",
"fileName": "sa*****"
}
]
}
]
},
"storeWebSites": {
"fileKey": "sd*****",
"fileName": "sa*****"
},
"otherAttachmentList": [
{
"fileKey": "remarkfilefi*****",
"fileName": "remarkfilefil*****"
}
],
"attachmentDesc": "123*****"
}
]
}Response
{
"acceptOrderId": "20230308191680008004600000*****",
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
}
}